結論：Claude Code は「コードを唯一の根拠（source of truth）」にしてドキュメントを書かせると、README・セットアップ手順・API 仕様書・docstring・アーキテクチャ説明までを一気に下書きでき、しかもコードとの乖離を最小化できます。鍵は「想像で書かせない」こと——@ でファイルやディレクトリを参照させ、git 履歴やテストを根拠に引かせる運用です。
- 要点1：README・手順・API 仕様・docstring は、Claude Code に「このコードを読んで、その実挙動だけを根拠に書け」と指示すると精度が上がる。
- 要点2：
@src/api/routes.tsのようにファイル/ディレクトリを@で渡すのが基本。説明文で場所を伝えるより速く正確（公式 common-workflows に明記）。 - 要点3：AI が書いたドキュメントは「事実（コードの実挙動）と乖離しうる」前提で、API 仕様と手順は必ず実際に動かして人が検証する。
対象読者：テクニカルライター／OSS メンテナ／API を提供する開発者／ドキュメント整備が後回しになっているチーム。今日やること：手元のリポジトリで @README.md と主要ソースを Claude Code に読ませ、「実挙動を根拠に README を更新して」と1回投げてみる。
正直、ドキュメントって「書くのが面倒」より「書いた後にコードが変わって嘘になる」のが一番つらいんですよね。READMEのセットアップ手順がいつの間にか動かなくなっていたり、API仕様書のパラメータが実装とズレていたり。私自身、受託開発でもそうですし、100社以上の現場でClaude Codeの導入支援をしていても「ドキュメントが信用できない」という相談は本当に多いです。
この記事では、テクニカルライターや開発者がClaude Codeを使って、①コードからREADME・セットアップ手順を生成する ②API仕様書（エンドポイント・パラメータ・例）を作る ③コードコメント・docstringを整える ④アーキテクチャ説明・図解の下書きを作る ⑤既存ドキュメントの更新・多言語化・用語統一をする、この5つの実践ワークフローを、指示例（プロンプト）とコード例付きで解説します。最後に「コードと乖離しないドキュメント」を保つコツ——コードを根拠にさせる運用——もまとめます。2026年6月時点の公式ドキュメント（Best practices / Common workflows）で確認できる機能だけを使います。
なぜ「コードを根拠にさせる」とドキュメントが効率化するのか
Claude Codeは単なるチャットボットではなく、ファイルを読み、コマンドを実行し、コードベースを自律的に探索する「エージェント型のコーディング環境」です。ここがドキュメント生成にとって決定的に重要です。普通のチャットLLMに「READMEを書いて」と頼むと、AIは学習知識から”それっぽい”汎用READMEを書いてしまう。でもClaude Codeは、実際にあなたのpackage.jsonやsrc/を読んでから書けるので、「このプロジェクトに実在する」内容を書けるわけです。
公式のBest practicesでも、曖昧な指示より「ソースを指し示す（Point to sources）」指示が推奨されています。たとえば「なぜこのAPIはこんな変な形なのか？」と聞くより、look through ExecutionFactory's git history and summarize how its api came to be（git履歴を辿って、このAPIがどう今の形になったか要約して）のように、根拠の在処を指定する。ドキュメント生成でもこの発想がそのまま効きます。「想像で書かせない、コードとgit履歴を根拠にさせる」——これが全ワークフロー共通の土台です。
まず覚える基本動作：@でファイル・ディレクトリを渡す
Claude Codeでドキュメントを書かせる前に、必ず覚えるべきが @ 参照です。説明文で「authのコードはsrc/authにあって…」と書く代わりに、@ でファイルやディレクトリを直接渡します。公式common-workflowsの「Reference files and directories」に明記された挙動です。
# 単一ファイルを参照（ファイルの全内容が会話に含まれる）
Explain the logic in @src/utils/auth.js
# ディレクトリを参照（ファイル一覧が渡される。中身ではなく構造）
What's the structure of @src/components?
# 複数ファイルもまとめて渡せる
@src/api/routes.ts and @src/api/handlers.ts のエンドポイント一覧を作って
ポイントは、単一ファイルは「中身」、ディレクトリは「一覧」が渡るという違い。だからREADMEを書かせるなら「全体構造はディレクトリ参照で把握させ、核となる実装は個別ファイルで読ませる」と精度とトークン効率のバランスが良くなります。なお @ 参照をすると、そのファイルのあるディレクトリと親ディレクトリの CLAUDE.md も自動的にコンテキストに入る、という地味だけど重要な仕様もあります（後述の用語統一で効きます）。
① コードからREADME・セットアップ手順を生成する
一番需要が高いのがこれです。新しく公開するリポジトリ、あるいは「READMEが3年前のまま」のプロジェクト。Claude Codeに実コードを根拠に書かせます。
ゼロから作る場合：まず /init を試す
プロジェクトの土台になるコンテキストファイルを作る公式コマンドが /init です。これはCLAUDE.md（Claudeが毎回読むプロジェクトメモリ）の生成用ですが、副産物として「ビルドシステム・テストフレームワーク・コード規約」を自動検出してくれるので、READMEの下書き材料として極めて有用です。
# プロジェクトルートで Claude Code を起動して
/init
# 検出された情報をもとにREADMEへ展開する
CLAUDE.md と package.json、src/ を根拠に、READMEのセットアップ手順を書いて。
推測は禁止。package.json の scripts に実在するコマンドだけを使うこと。
「scriptsに実在するコマンドだけ」という制約が肝です。これを付けないと、AIが一般的なnpm startなどを勝手に書きがち。実在を縛ることでコードと乖離しないREADMEになります。
既存READMEを更新する場合
@README.md と @package.json、@docker-compose.yml を読んで。
READMEの「セットアップ」「環境変数」「起動方法」セクションを、
現在のコードの実挙動に合わせて更新して。
- 環境変数は .env.example に実在するキーだけ列挙する
- 起動コマンドは package.json scripts と Dockerfile の実体に合わせる
- 変更した箇所は理由を箇条書きで報告して
このとき「変更した箇所と理由を報告して」と添えると、差分レビューが一気にラクになります。公式Best practicesでも「成功を主張させるな、証拠（evidence）を見せさせろ」と強調されている通り、「どこを何を根拠に直したか」を出させるのが検証の近道です。
失敗パターン（README編）
- ❌
READMEを今風にして→ ⭕@README.md を読んで、実コードと矛盾している箇所だけ直して。スタイルは変えない（「今風に」は主観的で、AIが構成ごと作り替えて既存の正しい記述まで壊す） - ❌ コードを読ませずに「セットアップ手順を書いて」 → ⭕ 必ず
@package.json等を@で渡す（読ませないと汎用テンプレが出る） - ❌ 生成手順をそのまま信用してコミット → ⭕ 別のクリーンな環境（コンテナ等）で手順通りに実際に動かして確認する。READMEのセットアップ手順は「自分の環境では動くが新規環境で動かない」が頻出
② API仕様書（エンドポイント・パラメータ・例）を作る
API仕様書はドキュメントの中でも特に「乖離が致命的」になる領域です。パラメータ名が1文字違うだけで連携先が落ちる。だからこそ、ルーティング定義やハンドラ実装を根拠にClaude Codeに棚卸しさせる価値が大きい。
エンドポイント一覧を実装から棚卸しする
@src/api/routes.ts と @src/api/handlers/ を読んで。
実装されている全エンドポイントを表にして。列は次の通り:
| メソッド | パス | 概要 | 必須パラメータ | 認証要否 |
ルーティング定義に実在するものだけ載せること。
コメントや想像で存在しないエンドポイントを足さないこと。
ここでも「実在するものだけ」「想像で足すな」を必ず書きます。次に、各エンドポイントのリクエスト/レスポンス例を、型定義やバリデーションスキーマから引かせます。
@src/schemas/user.ts のバリデーションスキーマ（zod）を根拠に、
POST /v1/users のリクエスト例とレスポンス例（成功・バリデーションエラー）を
JSON で書いて。スキーマに無いフィールドは例に含めないこと。
zodやJSON Schema、OpenAPIの型定義がリポジトリにあるなら、それを根拠にさせるのが最も乖離しにくい方法です。型がコードと一致している前提なら、型から起こした例はコードと一致します。
OpenAPI（Swagger）の下書きにも使える
既存のルーティングとスキーマから、OpenAPI 3.x のYAMLスケルトンを下書きさせることもできます。
@src/api/routes.ts と @src/schemas/ を根拠に、OpenAPI 3.1 の paths と
components/schemas のスケルトンを YAML で書いて。
- 実装に存在するパス・メソッド・パラメータだけ記述
- 値が不明な description は TODO: と明記して、埋めた風にしない
「不明な箇所はTODO:と明記して埋めた風にしない」が重要です。AIは空欄を嫌って”それらしい説明”で埋めてしまう癖があるので、明示的に「埋めるな」と縛る。生成したOpenAPIは必ずバリデータ（swagger-cli validate や redocly lint 等）にかけ、実際のAPIにリクエストを投げて応答と一致するかを人が確認します。これは省略不可です。
失敗パターン（API仕様編）
- ❌ コメントを根拠にさせる → ⭕ ルーティング定義と型/スキーマを根拠にさせる（コメントは古いことが多く、コメント由来の仕様書は二重に古くなる）
- ❌ レスポンス例をAIに創作させる → ⭕ 実際にAPIを叩いたレスポンスを貼って「これを整形して」と頼む（創作JSONはフィールドの過不足が起きる）
- ❌ 生成物を未検証で公開 → ⭕ バリデータ通過＋実リクエストでの突合を必須にする
③ コードコメント・docstringを整える
公式common-workflowsには「Handle documentation」という専用レシピがあり、まさにdocstring/JSDoc整備の手順が示されています。流れは「未記載箇所を探す→生成→文脈と例を足して改善→プロジェクト標準に沿うか確認」の4ステップです。
# 1. ドキュメントが無い関数を洗い出す
auth モジュールで JSDoc コメントが無い関数を探して
# 2. docstring/JSDoc を生成する
@src/auth.js の未記載の関数に JSDoc を付けて。
引数・返り値・throw する例外は、実装の挙動に厳密に合わせること
# 3. 文脈と例を足して改善する
生成した JSDoc に、使用例（@example）と、なぜこの関数が必要かの一文を足して
# 4. プロジェクト標準に沿うか確認する
このドキュメントが我々のプロジェクト標準（@CONTRIBUTING.md の規約）に
沿っているか確認して。ズレている箇所を直して
docstring生成で一番の注意は「@param の型や @throws を実装と一致させる」こと。AIは引数名から型を推測して書くので、実装で実際にどう使われているかを根拠にさせないと、型が微妙にズレます。「実装の挙動に厳密に合わせて」と明示し、生成後はリンタ（TypeScriptならtsc、PythonならdocstringチェッカーやmypyとIDEのホバー）で齟齬がないか確認しましょう。
④ アーキテクチャ説明・図解の下書きを作る
新人オンボーディング資料や設計ドキュメントの「全体像」パートは、Claude Codeが得意な領域です。公式Best practicesでも「新しいコードベースに入るときは、シニアエンジニアに聞くような質問をClaudeに投げよ」と推奨されています（How does logging work? / How do I make a new API endpoint? など）。その回答をそのままアーキテクチャ説明の下書きにできます。
@src/ 全体を読んで、このシステムの主要コンポーネントと
データの流れを説明するアーキテクチャ概要を書いて。
- レイヤー（プレゼンテーション/ドメイン/インフラ）ごとに整理
- 外部依存（DB・キュー・外部API）を明記
- 推測した箇所には「※要確認」と付けること
図解はMermaidで下書きさせる
図解そのものの完成品を期待するより、Mermaid記法のテキストを下書きさせるのが実用的です。テキストなのでレビュー・修正が容易で、コードと一緒にgit管理できます。
上のアーキテクチャ概要をもとに、コンポーネント間の依存関係を
Mermaid の flowchart で書いて。実コードに無い依存は書かないこと。
flowchart LR
Client --> API[API Layer]
API --> Service[Domain Service]
Service --> Repo[Repository]
Repo --> DB[(PostgreSQL)]
Service --> Queue[(Message Queue)]
ただし図解は特に「それっぽい嘘」が混ざりやすいので、「実コードに無い依存は書くな」と縛り、生成後は実装と矛盾がないか必ず目視します。大規模コードベースの読み解き自体は、別記事「Claude Codeで大規模コードベースを理解する｜新人即戦力化【2026】」で詳しく扱っているので、オンボーディング資料を作るならあわせて読んでください。
⑤ 既存ドキュメントの更新・多言語化・用語統一
多言語化（日↔英）
OSSや海外向けプロダクトでは英語READMEが必要になります。翻訳は得意分野ですが、コツは「コードブロック・コマンド・固有名詞・APIパラメータ名は翻訳せず原文維持」と明示することです。
@README.md を英語版（README.en.md）に翻訳して。
- コードブロック、コマンド、環境変数名、API パラメータ名は翻訳しない
- 見出し構造とリンクのアンカーは維持する
- 技術用語は業界標準の英語表現を使う
用語統一はCLAUDE.mdとimportが効く
チームでドキュメントを書くと「ユーザー／利用者／ユーザ」のような表記ゆれが必ず起きます。Claude Codeなら、用語集をCLAUDE.mdに置く（または@pathでimportする）ことで、毎回の生成・更新で自動的に統一できます。CLAUDE.mdは @path/to/import 構文で別ファイルを取り込めるのが公式仕様です。
# CLAUDE.md（抜粋）
ドキュメントの用語は @docs/glossary.md の表記に統一すること。
# docs/glossary.md
- 「ユーザ」「利用者」→「ユーザー」に統一
- 「ログイン」表記で統一（「サインイン」は使わない）
- 製品名は「Claude Code」（「ClaudeCode」「claude-code」は本文では使わない）
前述の通り @ でファイルを参照すると、そのディレクトリ・親ディレクトリのCLAUDE.mdが自動でコンテキストに入ります。つまりdocs/配下に用語ルールを置いておけば、docs内のファイルを編集させるたびに用語集が効く、という運用が組めます。CLAUDE.md設計そのもののコツは別記事「【2026】CLAUDE.md設計・運用ガイド｜効くプロジェクトメモリ」にまとめています（こちらは”AIへの指示書”側、本記事は”人間向けドキュメント生成”側で役割が違います）。
コードと乖離しないドキュメントを保つ運用のコツ
ここが本記事で一番伝えたい部分です。ドキュメント生成を一発の作業で終わらせず、「ズレ続けない仕組み」にするには次の3つが効きます。
コツ1：常に「コードを唯一の根拠」にさせる
全プロンプトで @ 参照を使い、「コメントや想像ではなく実装の挙動を根拠に」「実在するものだけ」「不明はTODO明記、埋めるな」を口癖のように添える。これだけで乖離は劇的に減ります。
コツ2：ドキュメント更新を「検証可能なタスク」にする
公式Best practicesの中心思想は「Claudeに検証手段（テスト・ビルド・スクリプト）を与えよ」です。ドキュメントにも応用できます。たとえばREADMEのコマンドが実在するかをスクリプトで照合させる。
README に書かれているコマンドを抽出して、
package.json scripts に実在するか照合するスクリプトを書いて。
実在しないコマンドがあれば一覧で報告して
API仕様なら「OpenAPIのパスと実ルーティングを突合するチェック」を書かせ、CIに入れる。こうすると「ドキュメントがコードとズレたらCIで気づく」状態になります。
コツ3：CIに非対話モード（claude -p）で組み込む
公式の非対話モード claude -p "プロンプト" を使えば、PR時にドキュメント鮮度チェックを自動化できます。
# 例：変更されたAPIに対してドキュメント差分を指摘させる（CIステップ）
git diff origin/main...HEAD -- 'src/api/**' | \
claude -p "この差分で API の挙動が変わった箇所を挙げ、
docs/api.md の該当箇所が更新必要かを判定して。要更新なら箇所を列挙"
非対話モードはCIやpre-commitフックに組み込むためのもので、出力を--output-format jsonで機械処理もできます。詳しい使い方は公式のNon-interactive modeを参照してください。Claude Code全体の実践テクニックは「Claude Code 実践テクニック完全ガイド｜12スキル学習順【2026】」、API開発自体の効率化は「【2026】Claude CodeでバックエンドAPI開発を効率化する実践ガイド」にまとめています。
正確性についての注意（必読）
最後に、これは技術記事として強く言っておきたいのですが——Claude Codeが生成したドキュメントは、事実（コードの実挙動）と乖離しうる前提で人が検証してください。特にAPI仕様と手順は、生成しただけで完了にせず、実際に動かして確認する。READMEのセットアップ手順はクリーンな環境で、API仕様は実リクエストで、docstringはリンタとIDEのホバーで突合する。AIは「空欄を嫌ってそれらしく埋める」「コメントを実装と思い込む」という癖があるので、根拠を縛り、生成物を検証する——この2点が、ドキュメント効率化を「速いけど嘘が増える」ではなく「速くて正確」にする分かれ目です。
なお本記事で挙げた @ 参照・CLAUDE.md の @import・/init・claude -p などの機能は、2026年6月時点の公式ドキュメント（Best practices / Common workflows）で確認したものです。Claude Codeはアップデートが速いので、実運用前に最新の公式ドキュメントで挙動を再確認することをおすすめします。
まとめと次のアクション
Claude Codeでドキュメントを効率化する核心は、ツールの使い方そのものより「コードを唯一の根拠にさせ、生成物を必ず検証する」運用設計にあります。今日から試せる3アクションはこちらです。
- 1分で試す：手元のリポジトリでClaude Codeを起動し、
@README.md と @package.json を読んで、実コードと矛盾するセットアップ手順を直してと1回投げる。 - 今週やる：API仕様書（または主要docstring）を、ルーティング定義と型/スキーマを根拠に棚卸しさせ、実リクエスト・リンタで検証する。
- 仕組みにする：
claude -pをCIに1ステップ足し、API変更PRで「ドキュメント要更新箇所」を自動指摘させる。用語集はCLAUDE.mdに@importで組み込む。
「ドキュメントがコードと乖離する」問題は、運用で構造的に解けます。まずは小さく1リポジトリから始めてみてください。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援に携わる。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆。Claude Codeの実装事例・導入支援を専門に発信しています。
参考・出典
- Best practices for Claude Code — Claude Code Docs（公式）
- Common workflows（Handle documentation / Reference files and directories）— Claude Code Docs（公式）
- Manage Claude’s memory（CLAUDE.md）— Claude Code Docs（公式）
- Headless / Non-interactive mode（claude -p）— Claude Code Docs（公式）
- Slash commands（/init 等）— Claude Code Docs（公式）
