repo-doc-maintainer

リポジトリドキュメントの保守担当

概要

最新のローカル変更を確認し、リポジトリの構成に関わる安定した知識が追加されたかを判断します。その知識が次のコントリビューターの安全な作業に役立つ場合に限り、プロジェクトレベルのドキュメント（AGENTS.md、CLAUDE.md、または同等のファイル）を更新します。

ドキュメントは簡潔で、重要な情報に絞ってください。どのファイルも変更履歴、機能の詳しい説明、実装の羅列にしないでください。

ワークフロー

1. 最新の変更一式を確認します。
2. 変更内容をプロジェクトのドキュメントにある既存の指針と照らし合わせます。
3. 今後のコントリビューターに必要な新しい高レベルの知識が追加されたかを判断します。
4. 適切なドキュメントだけを、適切な抽象度で更新します。
5. 変更内容を要約するか、ドキュメントの更新が不要であることを明示します。

変更一式を確認する

まずローカルの差分を確認します。質問に答えるために必要な最小限の範囲を優先してください。

• git status --short
• git diff --stat
• git diff -- <path>
• git log -1 --stat

ユーザーがマージ済みの変更やコミット済みの作業について尋ねた場合は、該当するコミットまたはコミット範囲を確認してください。

ドキュメントを編集する前に、影響を受けたコードを読みます。ファイル名だけから新しいルールを推測しないでください。

ドキュメントを変更するか判断する

次のような、長期的に再利用できる指針がある場合に限り、ドキュメントを更新します。

• 新しいアーキテクチャパターンまたはレイヤー分けのルール
• 新しい依存関係またはリポジトリ全体に関わる技術選定
• 新たに必要となった検証手順またはワークフロー手順
• 新しい DI、ルーティング、状態管理、API、永続化、テストの規約
• 微妙で繰り返し発生しやすく、回帰を招きそうな新たな注意点
• 重要な動作の新たな信頼できる情報源

次のような内容はドキュメントに追加しないでください。

• 一度限りの機能の詳細
• リポジトリに現在も適用される制約でない、一時的な回避策
• ファイルごとの要約
• 命名に関する些細な情報
• コードを見れば明らかな低レベルの実装上の仕組み
• 既存のドキュメントで十分に説明されている変更

次の基準で判断してください。これを知らなければ、十分な能力のある次のコントリビューターが間違いを犯しそうで、その指針が単一の機能を超えて役立つなら、ドキュメントに記載します。

適切なファイルを選ぶ

次のような指針は、リポジトリの概要を最短で確認したときに目に入るよう、AGENTS.md（または CLAUDE.md）を更新します。

• 安定したアーキテクチャ上の制約
• リポジトリ全体に適用されるルール
• 必須の検証コマンド
• 「重要事項」の簡潔なリマインダー

AGENTS.md も CLAUDE.md も存在せず、ドキュメントの更新が妥当な場合は、上記の基準を満たす指針だけを記載した AGENTS.md をリポジトリのルートに作成します。根拠の弱い候補を記載するために作成してはいけません。

追加内容は簡潔にしてください。1つの箇条書きか短い文を優先します。

次のように、より詳しい説明が必要な指針は、オンボーディング資料または開発者向けドキュメントを更新します。

• 判断基準
• 例
• 注意点
• ワークフローの詳細
• 新しいコントリビューターがルールを正しく適用するための根拠

同じルールを両方のファイルに記載する必要がある場合は、AGENTS.md にはできるだけ短いリマインダーを記載し、オンボーディング資料には詳しい説明を記載します。

編集ルール

• ドキュメントは高レベルかつ DRY に保ちます。
• 既存の文体と構成を保ちます。
• ランダムなメモを末尾に追加するのではなく、最も関連性の高い既存のセクションに新しい指針を組み込みます。
• すでに関連する概念がある場合は、新たな項目を追加する前に、既存の箇条書きを編集または簡潔化することを優先します。
• 同じファイル内の複数のセクションで同じルールを繰り返さないでください。
• 推測に基づくパターンは記載しないでください。ルールはすでにコードまたはワークフローに存在している必要があります。

出力の要件

確認後、次のいずれかを報告します。

• ドキュメントの更新が不要であることと、その簡潔な理由
• AGENTS.md / CLAUDE.md を更新したこと
• オンボーディング資料を更新したこと
• 両方を更新したこと

ドキュメントを更新した場合は、リポジトリの構成に関わるどの指針を追加したかを説明します。ファイルごとの差分を列挙するだけにしないでください。

ドキュメント更新の基準

最近の変更をプロジェクトレベルのドキュメントに記載する必要があるか判断する際は、この評価基準を使用します。

適切な候補

• リポジトリ全体に適用される新しい API またはデータアクセスのパターン
• 複数の機能に影響する新しい状態管理ルール
• 新しい依存性注入の登録要件
• 新しいルーティングまたはブートストラップの制約
• 新しい永続化、ローカライズ、またはテストの規約
• 新しい検証コマンド、CI の要件、またはテストの規約
• 実際の作業を通じて見つかった、新たな微妙なリグレッションの落とし穴

適切でない候補

• 単一画面の実装の詳細
• プライベートヘルパーの切り出し
• 動作の変更を伴わない名前の変更やコードの移動
• 一時的な実験
• 特定の機能に関する文言やアセットの変更
• リポジトリ全体の規約を示さない、テストだけに関する詳細

確認する質問

1. これは1か月後も重要ですか？
2. これは複数のファイル、機能、または将来のタスクに影響しますか？
3. このガイダンスを読まないコントリビューターは、実際に間違いを犯す可能性がありますか？
4. このルールは、すでにいずれかのドキュメントに明確に記載されていますか？
5. 実装方法を説明せずに、概要レベルで述べることができますか？

最初の3つの答えがほぼ「はい」なら、記録してください。最後の2つの答えが「いいえ」なら、慎重かつ簡潔に記録してください。