doc-cleanup

ドキュメントの整理

Markdown から文脈の陳腐化を取り除きます。ただし、重要なルールや有用な経緯は消さないでください。ドキュメントに書かれた主張はすべて仮説として扱い、リポジトリを証拠として確認します。

作業は2段階で進めます。まず診断して、編集せずに報告します。その後、ユーザーが提案された整理を承認した場合にのみ実行します。編集の承認は、コミットの承認を意味しません。

1. 対象範囲全体を棚卸しする

生成物、依存関係、VCS、ユーザーが除外したパスを除き、対象となる *.md ファイルをすべて列挙します。各ファイルの行数と役割を記録します。

• entry：AGENTS.md、CLAUDE.md、または同等のファイル
• required：エントリードキュメントから読むよう指示されているファイル
• reference：必要に応じて参照するファイル
• historical：現在の指針ではなく、参照用に保持されているファイル

各エントリードキュメントの参照先をたどります。読み取り頻度に応じて調査結果の重要度を調整します。必読ドキュメントの陳腐化は、アーカイブの陳腐化より大きな影響があります。

すべての対象 Markdown ファイルに役割が割り当てられ、エントリードキュメントに記載されたすべての参照先が、有効、無効、または外部として確認できた時点で、棚卸しは完了です。

2. 編集せずに診断する

すべての対象ドキュメントを、次の陳腐化パターンに該当するか確認できる程度に読み込みます。

1. 完了済み作業の記録 — 完了したチェックリスト、フェーズの記録、実装の経緯、振り返り、検証の記録が、現行の指針として示されているもの。
2. 実行済み計画 — リリース済みの計画が、まだ実行前の意図として書かれているもの。置き換えられた分析や却下された案も含みます。
3. 内部矛盾 — 相反する値、古い表の下にある訂正、以前の指針を覆す日付入りの追記。
4. 古い主張 — 名前が変更されたシンボル、変更済みの定数、誤った行番号、マージ済みなのに未マージとして記述されている作業への言及。
5. 参照切れのパス — 存在しないファイル、古いマシン上のパス、移転済みのリポジトリ、削除済みのツール。
6. 権威のずれ — 真実の情報源とされているものが、実装済みの動作や後の権威ある決定と一致しなくなっているもの。

疑わしい箇所ごとに、次の情報を記録します。

• ファイルと行の正確な位置
• 問題となる主張または内容
• ファイルの確認、検索、設定、テスト、または Git 履歴から得られたリポジトリ上の証拠
• 確信度と、未解決の曖昧さ
• 安全に行える最小限の対応：維持、訂正、簡潔化、アーカイブ化、または注意書きの追加

コードは実装済みの動作を示しますが、必ずしも意図された動作を示すとは限りません。ドキュメントが意図された契約を定めている可能性がある場合、リポジトリ上の証拠によってどちらの権威が優先されるか確認できない限り、不一致は未解決の権威のずれとして報告します。

維持すべき重要な内容として、絶対的なルール、現在有効な決定、繰り返し発生する落とし穴、実行手順、ドメイン用語を明示します。落とし穴の発見経緯が過去のものであっても、その落とし穴が今も有効なら残します。

棚卸ししたすべてのファイルについて、証拠に裏付けられた指摘が少なくとも1件あるか、問題なしと明示され、事実に関するすべての指摘がリポジトリ上の証拠と照合された時点で、診断は完了です。

3. 報告して停止する

調査結果を、読み取り頻度 × 誤解を招くリスク の高い順に提示します。それぞれについて、主張、証拠、影響、提案する対応を示します。続いてファイルごとの整理計画を提示し、未解決の決定事項を分けて列挙してから、維持する重要な内容を明記します。

承認を求めて停止します。診断段階では、作業ツリーを変更してはなりません。

追加調査をしなくても、ユーザーが提案されたすべてのファイル変更を承認、却下、または修正できる状態になった時点で、報告は完了です。

4. 承認済みの計画を実行する

記述する直前に、事実に関する各主張を再確認してください。承認された変更のみを、ファイルごとの以下の手順に従って適用します。

• 容易に見つけられる状態を保つ必要がある履歴をアーカイブします。 docs/archive/ に、衝突しにくいソースと日付を含む名前で、原文のコピーまたは範囲が明確な抜粋を保存します。クリーンアップ報告書またはサイドカーマニフェストに、ソースパスと Git blob またはコンテンツハッシュを記録し、原文には手を加えません。ファイル全体のアーカイブは編集前に取得したソースと照合し、抜粋は記録されたソース範囲と照合して検証します。容易に見つけられる状態にする必要がなければ、Git 履歴だけで十分です。
• 現在の事実に基づいて、現行のガイダンスを書き直します。 アーカイブを作成した場合は、短い参照先を追加します。引き継いだ事実上の主張を未確認のまま残すのではなく、残す主張はすべて最新の証拠に基づいて記述します。
• 正式な情報源を示します。 変わりやすい値を重複して記載するのではなく、そのスキーマ、設定、またはソースファイルの管理元を明記します。
• 完了した作業を簡潔にまとめます。 完了済みのチェックリストは短い結果説明に置き換え、未完了の項目は元の文言のまま残します。
• 注意点を残します。 繰り返し発生する落とし穴は、履歴の説明を移す前に、短く命令形のガイダンスにします。
• 未解決の不整合を明示します。 不一致と、現在有効な正式情報源を示します。管理元が不明な契約を、黙って書き換えないでください。
• 入口となるドキュメントを修正します。 無効な読み進め先と古くなった機能の説明を修正し、必読項目を最小限に保ちます。

すべての承認済みの指摘に対応する差分があるか、変更不要とする理由が記録され、書き換えで触れた事実上の主張すべてに最新の証拠があれば、実行完了です。

5. 検証して引き継ぐ

以下を検証してください。

• 変更した各ファイル内のすべての相対リンクが解決できる
• ファイル全体のアーカイブが編集前に取得したソースとバイト単位で一致し、抜粋が記録されたソース範囲と一致する
• 診断時に特定した重要な内容が、現行のガイダンスに残っている
• 差分に承認済みの Markdown 変更だけが含まれている
• 変更したドキュメント間に新たな矛盾が生じていない

変更したファイル、アーカイブの対応関係、修正した矛盾、未解決の管理元に関する判断、実施した検証を報告します。具体的なメッセージを指定したドキュメントのみのコミットを提案し、ユーザーの承認があった場合に限り作成します。

承認済みの指摘すべてに対応し、すべてのチェックに合格し、ユーザーが確認できる差分と残っている判断事項が提示されれば、クリーンアップ完了です。