documentation

ドキュメントスキル

目標

ドキュメントをプロジェクトの状態と同期させます。古くなったドキュメントはプロジェクトの不具合として扱います。ただし、ユーザー、運用担当者、コントリビューター、アーキテクチャ、将来のエージェントに影響しない内部のみの変更については、ドキュメントをむやみに変更しないでください。

デフォルトのワークフロー

1. ドキュメントを編集する前に、また、ドキュメントが実装に影響する可能性がある場合はコードを変更する前に、関連する既存ドキュメントを確認します。
2. タスクがインターフェース、構造、またはプロジェクトの知識を変更するかどうかを特定します。
3. コードまたはプロジェクトを変更します。
4. 変更したファイルを読み直すか、git diffを実行して、実際の変更を確認します。直前に行ったことの記憶に頼らないでください。
5. 手順4で確認した内容に基づき、影響を受けるドキュメントのみを更新します。
6. コード、README、ドキュメント、変更履歴、エージェント向けガイダンスの間に矛盾がないか確認します。
7. 最終回答で、ドキュメントに関する作業を要約します。

ドキュメントを更新するかどうかの判断

ドキュメントへの影響があるか、必ず確認してください。以下のいずれかの答えが「はい」の場合にのみ、ドキュメントを更新します。

• インターフェース： 公開動作、API、ルート、CLI コマンド、設定、環境変数、スキーマ、ファイル形式、インストール、使用方法に変更がありましたか？
• 構造： アーキテクチャ、モジュールの責務、依存関係の境界、デプロイ、運用、コントリビューターのワークフローに変更がありましたか？
• 知識： 重要な決定がなされたか、長期にわたるトレードオフを受け入れたか、制約が判明したか、技術的負債が明らかになりましたか？

純粋な内部リファクタリング、テスト、書式設定、目に見える動作の変更を伴わない小規模な実装修正、機械的な整理については、通常ドキュメントを更新しません。ただし、既存ドキュメントの内容が誤解を招くようになる場合は除きます。

編集前に根拠を確認する

ドキュメントの内容は、検証可能なプロジェクト上の根拠に厳密に基づいてください。エージェントが直前に行ったことについての認識を要約したり、言い換えたりせず、実際のファイルの現在の内容や差分を確認してください。

• git diffまたは変更したファイルそのもの — 変更内容の一次記録
• README、既存のドキュメント、AGENTS.md、CLAUDE.md、パッケージ単位の README
• パッケージのスクリプト、Makefile、タスクファイル、CI 設定、Docker ファイル、デプロイマニフェスト
• ソースのエクスポート、ルート定義、CLI パーサー、設定スキーマ、環境変数の検証、データベースのマイグレーション
• テスト、フィクスチャ、サンプル、設定例、リリースメタデータ
• ユーザーからの明示的な指示

コマンド、サポート状況、API、パフォーマンスに関する主張、互換性の保証、デプロイ手順を作り上げないでください。検証できない事項は、未解決の質問として記載するか、省略してください。

本番環境向けのガードレール

• ドキュメントの変更は、プロジェクトの変更に見合う範囲にとどめてください。
• 大規模な書き換え、再構成、スタイルのみの変更ではなく、必要最小限の編集を優先してください。
• プロジェクトの変更によって不要になったことが確認できない限り、警告、制約、コンプライアンスに関する注意事項、セキュリティガイダンス、運用手順書を維持してください。
• シークレット、非公開の認証情報、内部トークン、機密性の高い顧客データをドキュメントに記載しないでください。
• 生成された情報源や正式な情報源を重複して記載しないでください。OpenAPI 仕様、スキーマ、パッケージメタデータ、生成されたリファレンスドキュメントなどが正式な情報源である場合は、そちらにリンクしてください。
• 空のファイル、プレースホルダーのセクション、空の表、根拠のないロードマップ項目を作成しないでください。
• ユーザーから依頼された場合、または既存の構成に明らかな問題がある場合を除き、確立されたドキュメントの名前を変更したり、移動したりしないでください。

よくある合理化

古いドキュメントも、ドキュメントの不要な変更もバグです。以下の言い訳はいずれかにつながります。「実際の対応」欄がルールです。

言い訳	実際の対応
「ドキュメントは後でいい。追加の変更チケットを起票しよう。」	「後で」はたいてい「やらない」という意味です。コマンド、環境変数、必須手順、または公開される動作を変更した場合は、同じ変更にドキュメントも含めます。
「コード、スキーマ、エラーメッセージを見れば分かる。」	運用担当者やコントリビューターが読むのはドキュメントであり、バリデーターではありません。セットアップや公開される動作を変更した場合は、ドキュメントに記載します。
「レビューや CI でドキュメントの漏れに気づくはず。」	それでは、その時まで手戻りが発生し、main が古いままになります。変更を完成させてからリリースします。
「小さな変更だし、もう遅いし、リードもコードだけ出せばいいと言っている。」	規模、タイミング、「出してしまおう」という判断によって重大度が下がることはありません。必須手順が欠けていれば、引き続き重大な問題です。
「せっかくなので、整理したり分かりやすく書き直したりしよう。」	範囲外の変更は実際の変更を見えにくくし、リグレッションのリスクを高めます。編集は必要最小限にし、整理は別途対応します。
「表現が古いので、ついでに更新しておこう。」	「間違っていない」なら編集は不要です。現在の変更によって誤解を招くようになったドキュメントだけを修正します。
「CHANGELOG や ADR に記録したほうが、より丁寧だ。」	ユーザーに見える影響がなく、長期的に残すべき意思決定もない内部限定の変更には、どちらも必要ありません。丁寧に記録するとは、変更した内容を記載することであり、すべてを記載することではありません。

注意すべき兆候

ドキュメントの記載が不足しそうになっていることに気づいたら、いったん止まって再確認してください。

• コマンド、環境変数、セットアップ手順、または公開される動作を変更したのに、「ドキュメントは後で／追加のチケットで」と考える
• インターフェースやセットアップの変更に対して、「コードを見れば分かる」と考える
• ドキュメントが必要な変更を、ドキュメントが古いままマージする

ユーザーに見える変更、構造上の変更、または長期的に残すべき変更がないのに、ドキュメントを過剰に記載しそうになっている場合も同様です。

• 「せっかくなので、関係のないドキュメントも整理、書き直し、または改善しよう」と考える
• 長期的に残すべき意思決定がない内部限定の変更について、CHANGELOG や ADR に記載する
• 古いだけで、間違っても誤解を招くわけでもない表現を編集する

迷った場合は、現在の変更に照らしてドキュメントを正確に保つための最小限の編集を行ってください。必要以上でも、必要未満でもない編集にします。

更新マップ

該当する行をすべて適用しつつ、変更内容に応じた最小限の編集にとどめてください。

変更	更新内容
新しい公開機能	README または使い方ドキュメント。コマンド、API、設定、またはスキーマに関する場合はリファレンスドキュメントも更新します
公開 API、ルート、CLI、設定、環境変数、またはファイル形式の変更	リファレンスドキュメント。一般的な使い方が変わる場合は README も更新します
破壊的変更または非推奨化	README の移行に関する注記。存在する場合は CHANGELOG。リファレンスドキュメント
セットアップ、インストール、または開発ワークフローの変更	README。入門または開発ドキュメント。存在する場合は AGENTS.md
デプロイ、運用、またはインシデント対応の変更	運用ドキュメントまたはプレイブック。ユーザーに入口を案内する必要がある場合に限り README も更新します
アーキテクチャまたは依存関係の境界の変更	アーキテクチャドキュメント。意思決定が長期的に有効で、重要なトレードオフがある場合に限り ADR も作成します
重要な制約または今後の対応事項	ロードマップ、docs/known-issues.md、意思決定に関するドキュメント、または既存の計画ドキュメントのうち、最も適切なもの
リリース準備	CHANGELOG またはリリースノート。現在の状況や使い方が変わった場合に限り README も更新します
ドキュメント構成の変更（再編成、名称変更、分割、統合）	内部リンクをすべて更新します。移動したファイルを README の Documentation セクションに記載している場合は、そのセクションも更新します。ユーザーから依頼された場合、または現在の場所に明確な問題がある場合を除き、定着したファイルは移動しません

詳細な構成や例については、references/document-map.md を参照してください。

アーキテクチャ、リファレンス、またはプレイブックのドキュメントを作成する場合は、references/templates.md の記入式テンプレートを使用してください。

ブートストラップのルール

ドキュメントがない、またはほとんど記載がない場合は、プロジェクトの規模に応じて、役立つ最小限のドキュメントを作成します。

• 小さなスクリプト：README.md。既存のエージェントガイドがある場合に限り更新します。
• 小規模なライブラリまたは CLI：README.md、必要に応じて CHANGELOG.md、および README が長くなりすぎる場合に限り、目的を絞ったドキュメントファイルを 1 つ作成します。
• アプリ、サービス、インフラストラクチャプロジェクト、またはモノレポ：README.md と、現時点で実際の情報を記載できるドキュメントのみを作成します。

空のプレースホルダードキュメントは作成しないでください。空欄の多い大規模なテンプレートより、短く正確な README を優先してください。

ブートストラップテンプレートについては、references/bootstrap.md を参照してください。

意思決定記録

ADR は、長期にわたって有効で、変更が難しく、モジュール間または運用上の境界に関わり、重要な依存関係を導入し、または将来のエージェントが理解すべきトレードオフを記録する決定に限り作成します。

通常の実装上の選択、局所的な整理、小さなバグ修正、またはコードから明らかな選択については、ADR を作成しないでください。

ADR テンプレートについては、references/adr.md を参照してください。

既存プロジェクトのルール

• 一貫性がある場合は、プロジェクトの現在のドキュメントスタイルとファイル構成を維持してください。
• 新しいファイルを追加するより、既存のドキュメントを更新することを優先してください。
• ドキュメントが大量にある場合は、矛盾のために広範な整理が必要な場合を除き、変更に関連するドキュメントのみを確認して更新してください。
• プロジェクトに AGENTS.md、CLAUDE.md、.github/copilot-instructions.md、またはパッケージレベルのエージェント向けガイダンスがすでにある場合は、そのルールを管理する既存ファイルを更新してください。
• 新しい AGENTS.md を作成するのは、ドキュメントのブートストラップ時、またはユーザーがエージェント向けガイダンスを求めた場合に限ります。
• モノレポでは、ワークスペースレベルのドキュメントをルートに、パッケージ固有の使用方法や API のドキュメントをパッケージ内に配置してください。

最新性の確認

作業を終える前に、次の深刻度の順にドキュメントの問題を修正してください。

1. 重大 — 削除済みの動作、コマンド、ファイル、設定キー、ルート、またはセットアップ手順を記載している。新たに必須となった手順、環境変数、移行、または運用手順が記載されていない
2. 高 — ソースコード、例、テスト、またはパッケージメタデータと矛盾している
3. 低 — 検証できない主張がある。現在は誤り、または古くなった TODO が含まれている

最終回答

最後に、簡潔なドキュメントの概要を記載します。

Documentation updated:
- README.md: updated usage for the new import command
- docs/reference.md: added API parameters

ドキュメントを変更していない場合は、次のように記載します。

Documentation checked; no updates were needed because behavior, APIs, setup, and architecture did not change.