【事例】サポートナレッジをGitで管理しClaude Codeで更新するまで
目次 クリックで開く
カスタマーサポートの現場において、情報の鮮度を保つことは最大の課題です。新機能のリリースや仕様変更のたびに、Notionやesa、Zendesk内の記事を手作業で修正する運用は、サービスが成長するほど限界を迎えます。そこで今、エンジニアリングのベストプラクティスをドキュメント管理に持ち込む「Document as Code（コードとしてのドキュメント）」と、最新のAIエージェント「Claude Code」を組み合わせた運用が注目されています。
本記事では、サポートナレッジをGitレポジトリで管理し、Claude Codeを用いて半自動で更新・メンテナンスする仕組みの構築方法を、実務レベルで具体的に解説します。
なぜサポートナレッジをGitで管理するのか？
多くの企業がWikiツールや専用のSaaSを利用する中で、あえてGit（GitHubやGitLabなど）でナレッジを管理する理由は、AIとの親和性にあります。
Wikiツールの限界と「Document as Code」の親和性
一般的なWikiツールは、人間がUI上で編集するには適していますが、以下の点で課題が生じます。
- 変更履歴の追跡性: 「誰が」「いつ」「どの箇所の文言を」変えたのかの厳密な差分（diff）が見にくい。
- 一括変換の難しさ: サービス名や用語が変更になった際、100記事を一度に置換するような操作が困難。
- AIエージェントのアクセス: API経由での取得が必要になり、AIがファイルシステムとして直接読み書きするのに不向き。
これに対し、Markdown形式でGit管理（Document as Code）を行うことで、ドキュメントは「構造化されたテキストデータ」となり、プログラムやAIによる高速な処理が可能になります。
Claude Codeによる爆速更新が可能になる理由
Anthropicが提供を開始した「Claude Code」は、端末のローカル環境やレポジトリを直接理解するCLIツールです。従来のWeb型AIと異なり、ファイル構造を自ら探索し、複数のファイルを横断して修正案を提示・適用できます。これにより、「仕様書のMarkdownを読み取り、関連するFAQページをすべて最新化する」といった高度なタスクがコマンド一つで完結します。
社内のインフラ管理についても同様の考え方が適用できます。例えば、SaaSコストとオンプレ負債を断つ。バックオフィス＆インフラの「標的」と現実的剥がし方で述べられているような複雑なシステム構成図や運用手順も、コードに近い形式で管理することで、AIによる改善提案を受けやすくなります。
ナレッジベースをGit×Markdownで構築する設計
Claude Codeの性能を最大限に引き出すためには、AIが読みやすい「整理されたレポジトリ構成」が不可欠です。
推奨されるディレクトリ構成とファイル命名規則
サポートナレッジの場合、以下のような構成が実務的です。
knowledge-base/ ├── .claude/settings.json # permissions.deny で読み取り拒否するファイルを指定 ├── docs/ │ ├── internal/ # 社内向け運用手順 │ └── public/ # 公開用FAQ（最終的にZendesk等へ同期） ├── templates/ # 記事作成用のテンプレート └── metadata/ # カテゴリー定義や用語集（JSON/YAML）
ファイル名は how-to-reset-password.md のように、中身が推測できるケバブケースを推奨します。AIはファイル名からも文脈を読み取るためです。
メタデータ（Front Matter）の活用による管理の高度化
Markdownファイルの冒頭に、YAML形式でメタデータを記述します。
title: パスワードのリセット方法 last_updated: 2026-04-15 status: published target_audience: user
このメタデータがあることで、Claude Codeに対して「statusがpublishedのファイルの中から、特定の内容を修正して」といった条件付きの命令が出しやすくなります。
Claude Codeの導入と初期設定
Claude Codeを利用するには、Node.js環境とAnthropicのAPIキーが必要です。なお、仕様や料金については、必ずAnthropic公式ドキュメントを確認してください。
インストールと認証の手順
ターミナルで以下のコマンドを実行し、インストールを行います。
npm install -g @anthropic-ai/claude-code
初回起動時に claude コマンドを叩くと、ブラウザ経由での認証を求められます。API使用料は、通常のClaude API（Claude Sonnet 4.6等）の利用枠に基づいて従量課金されます。
セキュリティを担保する「permissions.deny」の設定
AIに機密情報を読み取らせないよう、レポジトリの .claude/settings.json に permissions.deny 配列を設定します。"Read(./.env)" や "Read(./.env.*)"、個人情報を含むログ・一時フォルダを "Read(./logs/**)" のように Read(...) ルールで列挙すると、該当ファイルの読み取りを確実に拒否できます。なお node_modules などコスト目的の除外は .gitignore に記載すれば既定で読み取り対象から外れます。かつて流布した .claudeignore は公式機能ではなく、読み取りを確実に止められない点に注意してください。
【実践】Claude Codeでナレッジを更新する具体的フロー
それでは、実際にナレッジを更新する手順を解説します。
ステップ1：現状分析と差分の抽出
まず、元となる情報をレポジトリ内に配置します。例えば「新機能：2段階認証の導入」という仕様書（spec.md）を置いた状態で、Claude Codeを起動します。
ステップ2：Claude Codeへの自然言語による更新指示
Claude Codeのインタラクティブ・シェルで以下のように指示を出します。
「docs/public/ 内にあるログイン関連のFAQを確認して。新機能の2段階認証（spec.md参照）の影響を受ける箇所をすべて特定し、Markdownファイルを最新の仕様に合わせて修正して。変更内容は日本のユーザー向けに丁寧なですます調で記述すること。」
Claude Codeは自律的にファイルをスキャンし、影響箇所をリストアップした後、エディタを開くことなく直接ファイルを書き換えます。
ステップ3：レビューとプルリクエストの作成
AIによる修正が終わったら、人間が git diff で内容を確認します。問題なければ、そのままブランチを作成しプルリクエストを出します。
git checkout -b feature/update-2fa-docs git add . git commit -m "Claude Code: 2段階認証導入に伴うFAQの更新" git push origin feature/update-2fa-docs
このようなワークフローは、非エンジニア部門でもGitHubのデスクトップアプリ等を使えば運用可能です。業務全体の自動化については、Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドで紹介されているような、ノーコードツールとの連携も検討の余地があります。
既存のナレッジ管理手法との比較
従来のSaaS管理と、今回紹介するGit×Claude Codeの手法を比較表にまとめました。
| 比較項目 | Notion / Zendesk等 | Git + Claude Code |
|---|---|---|
| 主な利用者 | CS、バックオフィス | エンジニア、テックリード |
| AIによる編集 | 1記事ごとのアシスト | レポジトリ単位での自律更新 |
| 履歴管理 | 簡易的なバージョン履歴 | Gitによる厳密な差分管理 |
| 情報の整合性 | 人間が目視で確認 | AIによる一括検知と修正 |
| 導入難易度 | 低（ブラウザのみ） | 中（CLI、Git知識が必要） |
大規模な組織では、これらを完全に切り替えるのではなく、Gitでマスターデータ（Single Source of Truth）を管理し、そこからGitHub Actions等でZendesk等へAPI経由で同期する構成が最も効率的です。
ナレッジコンテンツ種別 × Git管理の適合性 × Claude Code活用パターン × 維持コスト 早見表
前のセクションでClaude Codeによるナレッジ更新の具体的フローを説明しましたが、すべてのサポートナレッジがGit×Markdownに適しているわけではありません。テキスト中心の手順書はGit管理と相性が良い一方で、動画・スクリーンショット・フローチャートが多いビジュアルナレッジはGitだと扱いにくくなります。以下の表はコンテンツ種別ごとのGit管理適合性とClaude Code活用範囲をまとめたものです。
| ナレッジコンテンツ種別 | Git管理の適合性 | Claude Code活用パターン | 維持コストと更新頻度目安 | Git×Claude Code以外の推奨ツール |
|---|---|---|---|---|
| テキスト手順書・FAQ （ステップバイステップ・質問回答） |
◎ 最適（テキストのdiffが明確に出てコードレビューの要領で変更確認できる。バージョン管理・検索・差分追跡のすべてがGitで完結する） | 「製品Xのバージョンが2.0から3.0になったので、セクション2の手順を最新仕様に更新して」という指示でClaude Codeが差分ベースの更新を生成する。新しいFAQの初稿生成・既存FAQの表現改善も有効 | 維持コスト：低。製品・サービスの仕様変更のたびに更新（月次〜四半期）。一度Markdownテンプレートを整備すれば追加・修正の工数は最小 | Gitでの管理を前提として、閲覧用インターフェースとしてDocusaurus・GitBook・MkDocsを組み合わせると検索性・可読性が向上する |
| スクリーンショット付き操作ガイド （UI操作の画面キャプチャ入り） |
△ 部分的に適合（テキスト部分はGit管理に適するが、画像ファイルはGitのdiff表示が機能せず変更管理が難しい。Git LFSを使えば管理は可能だがリポジトリが肥大化する） | テキスト部分（手順の説明・注意事項）はClaude Codeで更新可能。画像の差し替えは手動作業が必要。「画像は古くなっているかもしれない」という注釈をClaude Codeに追加させる設計が現実的 | 維持コスト：中（UI変更のたびにスクリーンショットの撮り直しが必要。テキストはClaude Codeで更新できるが画像は手作業）。UIが頻繁に変わるSaaSのガイドは半年で陳腐化するリスクが高い | Scribe・Loom・Tango等の画面操作記録ツールと組み合わせて、UI変更時に自動でスクリーンショットを更新する設計が維持コストを下げる。Notionの埋め込み機能も有効 |
| フローチャート・構成図 （プロセスフロー・システム構成・ER図） |
○ 適合（Mermaid記法またはPlantUMLをMarkdownに埋め込む設計にすればGitで差分管理できる。画像ファイルとしてのフローチャートはGit管理が難しいがテキスト形式の図は管理可能） | 「Mermaid記法のフローチャートにこの新しいステップを追加して」という指示でClaude Codeが図のコードを更新できる。既存のフロー図のMermaid化（画像→テキスト変換）の初稿生成も有効 | 維持コスト：中（プロセス変更のたびにMermaidコードを更新する必要があるが、テキスト形式のため差分確認が容易）。Mermaid記法に慣れるまでの学習コストが初期にかかる | Mermaidが使えるZenn・GitBook・Docusaurusと組み合わせると図付きドキュメントの閲覧体験が向上する。複雑な構成図はLucidchartまたはdraw.ioで管理してGitにSVGとしてエクスポートする |
| 動画・スクリーンキャスト （操作デモ・チュートリアル動画） |
× 不適合（バイナリファイルのため差分管理ができない。GitリポジトリにMP4を置くとリポジトリが巨大化する。変更の都度再作成が必要で「更新が大変な資料」になりがち） | 動画本体はGit×Claude Codeの管理範囲外。動画の「台本・字幕テキスト・説明文」はMarkdownで管理してClaude Codeで更新する。動画へのリンクとバージョン情報をMarkdownファイルで管理する設計が現実的 | 維持コスト：高（動画は撮り直しが必要なため更新コストが最も高い。頻繁に変わる機能の動画ガイドは維持が困難で廃止・テキストへの置き換えを推奨する場合もある） | LoomまたはYouTube（限定公開）でホスティングして、Markdownに埋め込みリンクを記載する設計が最も管理しやすい。動画の目次（タイムスタンプ付き）をMarkdownで管理してClaude Codeで更新する |
この表で最もGit×Claude Codeの恩恵を受けやすいのが「テキスト手順書・FAQのメンテナンス」です。製品アップデートのたびに手動でドキュメントを更新していた工数を、Claude Codeが「変更点はここ。この部分を更新して」という指示一つで自動化できます。逆に動画・スクリーンショット主体のガイドはGit管理に向かないため、そのコンテンツはNotionやLoom等の別ツールで管理する役割分担を設計段階で決めておくことが、長期的な維持コストを下げる重要な判断です。
運用上の注意点とよくあるトラブル
ハルシネーション（誤情報）への対処
Claude Codeは非常に優秀ですが、存在しないUIの操作手順を「もっともらしく」生成することがあります。これを防ぐためには、指示を出す際に「不明な点は推測せず、質問すること」という制約を明示するか、社内の用語集を常に参照させる設定が必要です。
Git操作に不慣れなメンバーへのフォロー
カスタマーサポートのメンバー全員にGitを強いるのは現実的ではありません。AIが作成したプルリクエストをエンジニアやリーダーが確認し、マージされたら自動的にWebツールへ反映される「一方通行の同期システム」を構築することで、現場の負荷を抑えつつ品質を高めることができます。
特に経理や人事など、他部署とのデータ連携を伴う場合は、楽楽精算×freee会計の「CSV手作業」を滅ぼす。経理の完全自動化とアーキテクチャで解説しているような、ツール間のデータ責務の明確化が成功の鍵となります。
よくある質問（サポートナレッジ Git管理 Claude Code 更新 設計）
Q. サポートナレッジをGitで管理するメリットと基本的な運用設計は？
Gitで管理するメリットは①変更履歴の完全な追跡：誰がいつどのナレッジを変更したかがgit logで確認できる②Pull Requestによるレビュー：ナレッジの更新をチームでレビューしてから反映する品質管理が可能③ブランチによるドラフト管理：「まだ確認中の手順書」をブランチで管理し、確認完了後にmainにマージ④自動デプロイ：GitHub Actionsでmainへのマージをトリガーにナレッジをドキュメントサイト（Docusaurus・Mintlify等）に自動デプロイ、の4点です。運用設計の基本は「docs/」ディレクトリ内にMarkdownでナレッジを管理→PRレビュー→mainマージで公開というシンプルなフローです。
Q. Claude CodeでサポートナレッジのMarkdownを更新するには？
活用方法は①ナレッジの定期更新：「docs/payment-faq.mdをこのユーザーの問い合わせ回答に基づいて更新して」とClaude Codeに指示②ナレッジの検索と補完：「認証エラーについてdocsフォルダを検索して、不足している手順を追加して」③多言語対応：日本語で書いたナレッジを「このファイルを英語に翻訳してen/ディレクトリに保存して」④バグレポートからナレッジへ：「このGitHub Issueの内容を元にナレッジベースに手順を追加して」の4パターンが典型的な活用例です。CLAUDE.mdにナレッジ更新のルール（フォーマット・ディレクトリ構成・禁止事項）を記載することで一貫した品質が保てます。
Q. Gitとナレッジツール（Notion・Confluence）はどう使い分けますか？
使い分けの考え方は①Git（Markdown）が向いているケース：エンジニアが主に使うAPIリファレンス・コマンドリファレンス・障害対応Runbook。コードとナレッジが密接に関係し、コードレビューと同じPRフローで管理したい場合②Notion・Confluenceが向いているケース：カスタマーサポートチームが日常的に参照・更新するFAQ（非エンジニアが使いやすいUI）・プロダクトのロードマップ・会議メモ③両者の組み合わせ：GitHubリポジトリのdocsにRawナレッジを置き、Docusaurusで見やすいサイトとして公開する設計が一般的④Claude Codeの活用：Gitベースのナレッジ更新にはClaude Codeが有効、Notion/ConfluenceはAPIを介してAIが参照する設計、の4点です。
まとめ：AI時代のナレッジマネジメントへ
サポートナレッジを「ドキュメント」ではなく「コード」として扱うことで、AIのポテンシャルを最大限に活用できるようになります。Claude Codeという強力なエージェントを仲間に加えることで、情報のメンテナンスに追われる日々から解放され、よりクリエイティブな顧客体験の設計に時間を割くことが可能になるでしょう。
まずは、一部の技術的なFAQからMarkdown化とGit管理を試し、Claude Codeによる更新のスピード感を体感してみてください。
Git×Markdownでナレッジを管理し、Claude Codeに更新を委ねる運用を実務に乗せるには、どのファイルをAIに読ませてどこをdenyで遮断するかという権限設計と、変更の承認フロー・操作ログの整備が安定稼働の前提になります。ナレッジ管理へのClaude Code導入に向けた設計や実装方針のご相談は、Claude Code 導入支援でも承っています。
生成AIの法人導入・セキュリティ設計のご相談
ChatGPTやClaudeなど生成AIのプラン選定・セキュアな全社導入・権限／ログ設計を、貴社の体制に合わせて整理します。すでに導入済みの環境について『この設計で問題ないか』を確認したい、という導入前後のセカンドオピニオンにも対応しています。
AI・業務自動化
ChatGPT・Claude APIを活用したAIエージェント開発、n8n・Difyによるワークフロー自動化で繰り返し業務を削減します。まずはどの業務をAI化できるか診断します。