AI にはコメントを多めに書かせ、「意図」と修正の経緯をコードの隣に残す
コードだけで自己説明させるのには限界があるので、なぜそうしたか（意図）と「2026-05-12 クラッシュ修正: ○○が原因」のような経緯をコメントとして残させる。
人間向けには冗長に見えるコメントも、次にそのファイルを読むエージェントにとっては、git の履歴をたどらずに手に入る文脈になる。コンテキストとコードを近くに置くのが狙い。
やり方
- AGENTS.md / CLAUDE.md に「変更には意図をコメントで残す。バグ修正は日付と原因を1行で添える」と書く
- 回避策・一見不自然な実装・外部仕様に合わせた箇所は、必ず理由を書かせる
- レビューでは、コメントが現在のコードと食い違っていないかを見る
注意点
- 古いコメントは誤った文脈になる。大きな変更時はコメントも更新させる
- チームのコメント規約と衝突する場合は、対象をエージェントが触る箇所や複雑な箇所に絞る