はじめに / 対象と前提

想定読者: Claude Code などの AI コーディングエージェントに、単発タスクではなく 数週間〜数ヶ月にわたる継続的な開発 を任せている人
前提環境: Claude Code v2.x 系、Git 管理下のリポジトリで CLAUDE.md によるプロジェクト指示を使っている構成
特定プロダクトの話ではなく、複数セッションにまたがる自律実装で汎用的に使える「意思決定の永続化」パターンの実装メモ

TL;DR

自律エージェントは セッションが切れるたびに文脈を失う。放置すると「前回却下した案」を再提案してきたり、同じ設計を巡って何度も同じ議論を繰り返す
対策は ADR(Architecture Decision Record)を Markdown で連番管理し、矛盾したときにどれを信じるかの優先順位を明文化するだけ。特別なツールは不要
ただし「更新忘れ」「矛盾の放置」「ログ肥大化」の3つでハマったので回避策込みで書く

手順 / 動かし方

1. 決定ログのテンプレを固定する

## ADR-0042: リトライは指数バックオフ+ジッターに統一

- 背景: 単純な固定間隔リトライで 429 が連発していた
- 決定: base=1s, factor=2, jitter=0.3 で統一。呼び出し側で個別実装しない
- 影響範囲: api_client.py の全 API 呼び出し
- 状態: 有効(supersedes: なし)

連番を振ることで、後から Claude 自身が「ADR-0038 の話」のように参照できるようになる。連番はファイル内で単純にインクリメントするだけで、特別な仕組みは要らない。

2. 矛盾したときの優先順位を明文化する

複数のドキュメントが矛盾する記述を持つのは避けられないので、Claude が迷わないよう優先順位を CLAUDE.md に一言書いておく。

優先順位: 現在地(直近の状況を書いたファイル) > 方針 > 過去の決定ログ

新しいセッションの冒頭で「まず現在地ファイルから読め」と指示しておくと、エージェントは自分で経緯を遡ってから作業に入るようになる。

3. 決定が上書きされたら明示的に無効化する

## ADR-0051: ADR-0042 のリトライ設定を修正(supersedes: ADR-0042)

- 背景: ジッターを入れても特定経路だと 429 が収まらなかった
- 決定: factor=3 に変更。ADR-0042 は本エントリで無効

古い決定を消さずに supersedes で参照させることで、履歴を残しつつ「今どれが有効か」を一意にできる。

4. セッション終了時の棚卸しをテンプレ化する

CLAUDE.md の末尾に次のような一文を入れておくと、記録漏れがかなり減る。

作業の最後に、今回した意思決定を1つでも思い出せるなら
決定ログに追記してからセッションを終えること。

これを「気が向いたら書く」から「終了条件の一部」に格上げしたのがポイントだった。

ハマりどころ

1. 更新忘れ
決定した瞬間に記録しないと、次のセッションでは何も残らない。「重要な意思決定をしたら記録する」と指示するだけでは弱く、結局は毎回の作業の最後に「今回何を決めたか棚卸しする」ステップをテンプレ化して埋め込む必要があった。

2. 矛盾の放置
supersedes を書かずに矛盾する決定を追記すると、エージェントがどちらを採用すべきか迷い、たまに古い方を採用してしまう。無効化した決定には必ず supersedes を書くルールを徹底する。

3. ログの肥大化
決定ログが数十件を超えると、セッション開始時に全文を読ませるのはコンテキストの無駄になる。現在地を書いた短いファイルと、決定の全履歴を書いた長いファイルを分離し、エージェントには基本は短い方だけを読ませ、必要なときだけ長い方を遡らせる構成にしたら解消した。

背景・補足

ADR 自体はソフトウェア設計の意思決定を記録する手法として以前からあるが、人間向けに書かれることが多い。自律エージェント運用では エージェント自身が読者になる ため、①連番で参照しやすくする、②優先順位を明文化する、③現在地と履歴を分離する、の3点が特に効いた。人間向け ADR との一番の違いは、読み手が「後で読み返す人間」ではなく「次のセッションで即座に判断を下すエージェント自身」だという点で、曖昧な表現より機械的に解釈できる断定的な書き方の方が事故が少ない。

まとめ

自律エージェントの継続運用では「今何が有効か」を毎回自力で判断させないことが重要
ADR 風の連番ログ + supersedes + 優先順位の明文化、という地味な仕組みで再質問・矛盾のかなりの部分は防げる
ログが増えたら「現在地」と「履歴」を分離するのが有効。1ファイルに全部書き続けると必ずコンテキストを圧迫する
記録漏れ対策は「気が向いたら書く」ではなく「セッション終了条件に組み込む」のが効いた