Claude Codeを用いて仕様書の自動更新の仕組みを構築した話

はじめに

こんにちは！クラシルリワードでバックエンド開発をしているkorosukeです。

今回は、Claude Codeを活用してアフィリエイト仕様書の自動更新システムを構築し、運用チームの問い合わせ対応時間を25%削減した事例をご紹介します。

カスタムコマンドでgit履歴から変更を検出し、Notion MCPで仕様書を自動更新する仕組みにより、手動作業を大幅に削減することができました。

背景：複雑化するアフィリエイト仕様と問い合わせの増加

クラシルリワードでは、多数のASP（アフィリエイトサービスプロバイダー）と連携し、複雑な成果通知システムを運用しています。
仕様が複雑で把握が困難な上、仕様書がない・古い状態のものもあり、毎回コード調査が必要となり問い合わせ対応時間が膨らんでいました。

抱えていた課題

1. 仕様が複雑化していて、そもそも仕様理解が難しい：多数のASPとの連携により、パラメータやエラーハンドリングのパターンが増加し、全体像の把握が困難
2. 組織変更が多く、自分自身も配属後3ヶ月程度で把握しきれていない部分がある：前任者からの引き継ぎはあったものの、すべての仕様を短期間で習得するのは困難
3. 前任者への相談で答えに辿り着くこともあるが、新たなパターンの問い合わせが随時でてくる：既知の問題は解決できるが、新しいケースではコード調査が必要になることが多い
4. コードの調査までいくと調査工数が膨らむ：仕様書がないものや古いものがあるため、毎回ソースコードから仕様を読み解く必要があり、対応時間が大幅に増加

解決策：Claude Codeによる仕様書の自動更新システム

概要

Claude Codeのスラッシュコマンド機能とNotion MCPを組み合わせて、以下のワークフローを構築しました：

# 使用するコマンド
/update-affiliate-docs 7    # 過去7日の変更を検知して仕様書更新

実装のポイント

1. 監視対象ファイルの特定

効率的に監視するために、FILE_PATTERNSにマッチした担当領域のコードのみチェックする形にしています。

// 監視パターンの定義（実際のパスは伏せています）
const FILE_PATTERNS = [
  "app/models/*target*.rb",
  "app/services/target_system/**/*.rb",
  "app/controllers/target/**/*.rb",
  "external_system/**/*.rb"
];

2. 変更検出とドキュメント生成ロジック

コード変更を検出して、自動的に非エンジニア向けの説明を生成する仕組みを構築しました。

3. Notion MCP連携

Claude CodeからNotionページを直接更新するため、Notion MCPを設定しました。

Notionの公式ホスト型MCPサーバーを使用することで、API トークンの設定なしで簡単にセットアップできます：

# Notion MCPをリモートで登録
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 接続確認とブラウザ認証
/mcp notion
# ↑ 実行後、ブラウザでNotionとの連携とアクセス許可を行います

これだけで、Claude CodeからNotionページの読み取り・更新が可能になります。

詳しくは公式ドキュメントをご参照ください：
🔗 Notion MCP 公式ガイド

カスタムコマンドの設定

カスタムコマンドを使って、定型作業を簡単に実行できるよう設定しました：

// settings.json (Claude Code設定ファイル)
{
  "claude.customCommands": {
    "update-affiliate-docs": {
      "description": "仕様書を最新のコード変更に基づいて自動更新",
      "prompt": "以下の手順で仕様書を更新してください:\n1. 過去${days:1}日間の変更をgit logで確認\n2. 変更されたファイルの内容を分析\n3. 非エンジニアにも分かりやすい内容で更新\n4. 用語集に基づいた一貫性のある記述\n5. 変更履歴を追記\n6. Notion MCPを使用してページ同期",
      "parameters": {
        "days": {
          "type": "number", 
          "default": 1,
          "description": "何日前からの変更を確認するか"
        },
        "notion_page_id": {
          "type": "string",
          "default": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "description": "更新対象のNotionページID"
        },
        "reference_pages": {
          "type": "array",
          "default": [
            "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
            "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
          ],
          "description": "参照する用語集や既存仕様書のNotionページID"
        },
        "use_terminology": {
          "type": "boolean",
          "default": true,
          "description": "用語集の定義を使用して一貫性のある記述にする"
        }
      }
    }
  }
}

# MCP接続確認
/mcp notion

# 特定ページへの同期
/update-affiliate-docs 7 --notion-page-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# デフォルトページへの自動同期
/update-affiliate-docs 7  # 設定済みのデフォルトページIDを使用

数分で変更検知からNotionへの同期まで終わります。
また、修正量が多い時は、確認を取ってくれます。

実行ログのサンプル

内容: 実行ログサンプル

自動更新の流れ

1. 変更検知: /update-affiliate-docs 7で過去7日の変更を分析
2. 仕様書更新: 新しいパラメータ値とその処理内容を自動で追記
3. Notion同期: 営業・企画チームが即座に最新情報を参照可能

この例では、従来なら手動で30分かかっていた仕様書更新が、3分で自動完了しました。

効果測定：問い合わせ対応時間25%削減

Before/After比較

対応前後のチームの作業工数比率

週毎の工数比率

削減要因の分析

1. 開発者側の効果（既に実現済み）

仕様書の確認で即回答できる問い合わせが増えたため、問い合わせ対応の工数が削減できました。

2. 非エンジニア側の効果（今後期待）

以下のような効果を期待：

• セルフサービス化による問い合わせ数削減
• より精度の高い初期対応

弊社内では、現在notionAIの活用も活発になってきており、効率的にAIに食わせるためのページ構成の整理等も行なっているところなので、このあたりもスムーズに進められそうだなと思っています。

工夫した点

Claude Codeの活用テクニック

1. パラメータ付きコマンド

細かいところですが、毎日対応しなくても大丈夫なように、何日分のチェックをかけるかを引数で渡せる形にしました。

{
  "parameters": {
    "days": {
      "type": "number",
      "description": "過去何日分の変更をチェックするか",
      "default": 1
    }
  }
}

2. プロンプトエンジニアリング

notionに用語集があったので、そちらを参照して、社内で利用している用語で統一した記述になるように、対応しました。
また、初回の作成時は、これまでの問い合わせの内容と回答を食わせて、細かいチューニングを行いました。

以下の手順で仕様書を更新してください：

1. 過去${days:1}日間の変更をgit logで確認
2. 変更されたファイルの内容を分析
3. 非エンジニアにも分かりやすい内容で更新
4. 用語集に基づいた一貫性のある記述
5. 変更履歴を追記
6. Notion MCPを使用してページ同期

まとめ

Claude Codeを活用した仕様書自動更新システムにより：

✅ 問い合わせ対応時間を25%削減
✅ 情報の一元化でナレッジの属人化を解消
✅ 非エンジニアのセルフサービス基盤を構築

特に印象的だったのは、Claude Codeのカスタムコマンド機能の使いやすさです。複雑な処理をシンプルなスラッシュコマンドで実行でき、まだまだいろいろなことができそうだなと感じました。