ドキュメントの同期
ドキュメントは静かにずれていきます。READMEに記載されたファイル名が移動しても、何も失敗しません。このスキルは、スタックされたPRの各ステージ後や機能完了後、PRを開く前に実行してください。
このスキルにはコミットが含まれます。 許可なくコミットする場合があり、常に現在のブランチにコミットし、決してmainにはコミットしません。
スキップすべき場合
- ドキュメントが参照するものに変更がない場合（純粋な内部ロジックの変更）。その場合でも、PRの「Testing」セクションに「ドキュメントをチェックしました。ずれはありません」と記載し、レビュアーに実行されたことを知らせてください。
- ユーザーが明示的にまだドキュメントのコミットを望まない場合。
インベントリ: docs/DOCS.md
スコープ内のドキュメント一覧はAGENTS.mdではなくdocs/DOCS.mdにあります。これにより、常にオンになっているコンテキストが同期のたびに肥大化するのを防ぎます。
# ドキュメントインベントリ
| パス | 所有する内容 | 自動生成元 |
|---|---|---|
| README.md | 製品概要、セットアップ、環境変数、レイアウト | |
| AGENTS.md | エージェントルール + プロジェクトゲート | |
| packages/api/README.md | エンドポイント、スクリプト、環境変数 | |
| docs/api/openapi.json | APIリファレンス | `pnpm generate:openapi` |
## 凍結（同期による編集は決して行わない）
- docs/plans/
## ずれチェック
<!-- 実際に発生したミスごとに1つのgrepと、その理由を説明するコメント -->
初回実行時: インベントリを作成します。ルートおよび各パッケージのREADME.md / AGENTS.md / CLAUDE.md、コントリビューター向けドキュメント、APIドキュメント（OpenAPIの説明、llms.txt）、スキルとルールのディレクトリ、環境変数の参照（.env.example、設定スキーマ）をスキャンします。それぞれが何を所有するかを書き留めます。
毎回の実行時: インベントリに記載されていないドキュメントが見つかった場合は、同じコミットで追加します。
手順
- 監査. ブランチをベースと比較します（
git diff <base>...HEAD --stat）。変更されたもので、ドキュメントが言及する可能性があるものをリストアップします: パス、パッケージ名、ルート、コマンドとスクリプト、環境変数、エクスポートされたAPI、動作、規約。 - 検証. インベントリ内の各ドキュメントについて、すべての具体的な主張をコードと照合します: 名前付きファイルがそのパスに存在するか、各コマンドがマニフェストに存在するか、各環境変数が実際に読み取られているか、各ルートとエクスポートが説明どおりに存在するか。コードを読みます。プローズを信頼してはいけません。自分が以前書いたプローズも含めて信頼してはいけません。
- 編集. ずれを修正します。コードが何をするかを説明し、ドキュメントを読みやすくするために動作をでっち上げてはいけません。コードとドキュメントが一致せず、どちらが間違っているか判断できない場合は、推測せずにフラグを立てます。
- 再生成. インベントリにリストされている各ジェネレーターコマンドを実行します。生成されたドキュメントは決して手動で編集してはいけません。
- ずれチェックを実行
docs/DOCS.mdにリストされているずれチェックを実行します。同期中に、再発しそうなミス（古いパス、リネームされたコマンド）が見つかった場合は、そのミスに対するgrepをコメント付きで追加します。 - コミット. ファイルをパスごとにステージします。
git add -Aは使わないでください。1つのアトミックなコミットを作成し、メッセージはdocs(<スコープ>): <変更内容>と同期とし、現在のブランチにコミットします。 - プッシュ ブランチがすでにリモートを追跡している場合（最初に
git pull --rebaseを実行）。決してmainにはプッシュしません。
ルール
- 凍結された履歴:
docs/plans/内の設計、計画、引き継ぎ文書は、当時決定されたことのスナップショットです。これらはgrepにヒットすることがありますが、それは想定内であり、ずれではありません。同期中にこれらを編集してはいけません。 - スパイクとプロトタイプは削除 その方向性が出荷されるか破棄された時点で削除され、参考として残されることはありません。スパイクの結論は、プロダクションがより良い知識を得た後では、リポジトリ内で最も信頼性の低いテキストです。まだ価値のあるものはすべて、出荷されたコードのドキュメントに移動します。
- サイズ予算: ドキュメントの行数はPRの予算にカウントされます。同期によってステージが500行を超えた場合は、スタックの上にドキュメントのみのステージとしてランディングします（
stacked-prsを参照）。 - ポインタファイルは小さく保つ:
AGENTS.mdを指すだけのCLAUDE.mdやGEMINI.mdは、そのままにしておきます。コンテンツをコピーしてはいけません。