既存の Claude Code 環境に「学び台帳・Decision Record・母数照合・HANDOFF」を後付けする手順

元となる考え方: AI廃人部 第3回オフ会（2026-09-16）で共有された司令塔型 AI-OS プロトコルを、既存環境へ差分導入する形に組み替えたもの。

対象

既にCLAUDE.mdとsession終了手順を持つ環境。既存の司令塔・実行役分離やsession管理を置き換えず、不足する4要素だけを追加する。

1. HANDOFFを標準化する

<repo>/protocols/HANDOFF.mdを作り、見出しをTASK_ID / OBJECTIVE / BACKGROUND / CONTEXT / SOURCE_OF_TRUTH / INPUT / CONSTRAINTS / HUMAN_GATE / DONE_CRITERIA / OUTPUT / REPORT_TOに固定する。返却形式もTASK_ID / STATUS(DONE|PARTIAL|BLOCKED|FAILED) / RESULT / ARTIFACTS / VERIFICATION / DECISIONS / ISSUES / LEARNING / NEXTに固定する。

実行役には、目的から逸脱しない、正本を変えない、不可逆操作は承認境界を越えない、想定外を隠さない、完了条件を自分で検証する、と明記する。詰まった時は推測せず、CONTEXT → 正本 → Decision → 手順書 → memoryの順に調べる。結果を大きく左右する時だけ司令塔へ戻す。

Codexへはシェル展開を避けてnode <repo>/tools/codex-do.mjs --prompt-file <handoff.md> --cwd <target>で渡す。Codexはmemoryを継承しないため、今回の判断に必要な要点だけをCONTEXTへ貼る。

2. Decision Recordを置く

<repo>/protocols/DECISION-TEMPLATE.mdと<repo>/decisions/README.mdを作る。テンプレの見出しはdecision_id / date / status(ACTIVE|SUPERSEDED) / project / QUESTION / CONTEXT / OPTIONS / DECISION / WHY / TRADE-OFF / ASSUMPTIONS / REVERSIBILITY(REVERSIBLE|PARTIALLY_REVERSIBLE|IRREVERSIBLE) / REVISIT_TRIGGER / RELATEDに固定する。

方式選定、外部サービス採用、「やらない」という判断だけを残す。単なる実装手順は対象外。前提が維持されていれば同じ議論を繰り返さない。変わったら旧記録を上書きせず、新しいDEC-XXXXを作ってsupersedes:で結ぶ。READMEにはID、日付、status、一行要約の表を置く。

3. 学びの発生回数を既存memoryで数える

別台帳を増やさず、<memory-dir>/*.mdのfrontmatterを正本にする。

metadata:
  type: feedback
  count: 1
  status: ACTIVE
  critical: false
  promoted_to:
  promoted_at:

省略時はcount: 1、status: ACTIVE。同義の学びが再発したら新規memoryを作らずcountを増やす。3回でPROMOTE。データ消失、バックアップ不全、セキュリティ、権限事故、誤送信、不可逆操作、金銭損失はcritical: trueとして1回目からPROMOTEする。

<repo>/tools/learning-ledger.mjsはNode標準モジュールだけで実装し、--memory-dir <dir>、--list、--bump <file> [--critical]、--queue-out <path>、--dryを備える。bumpは本文を変更しない。壊れたfrontmatterはstderrへ出し、末尾に走査 N = 対象 a + 対象外 b + 解析不能 cを必ず出す。

昇格先はmemory → ルール文書 → Procedure/Checklist/Template → Skill/Agent → Hook/Validator/Test → Script/Automation → permission制約の順に強くなる。「覚えて守る」より「守らないと通らない」を選ぶ。DESIGN → IMPLEMENT → TEST → REVIEW → ACTIVATEまで終えてからPROMOTEDにし、昇格先と日付を書く。

session終了手順には同義memoryの検索、bump、queue更新、PROMOTE件数の引き継ぎを追加する。session開始手順にはqueueを読み、仕組み化: <name>を目的候補へ足す処理を追加する。

4. 母数照合を完了条件にする

バッチ、移行、一括処理ではTOTAL INPUT = SUCCESS + FAILED + EXCLUDED + UNRECOGNIZEDを成立させる。「エラー0件」は全件成功を意味しない。処理対象として認識されず、失敗にも記録されなかった入力を疑う。完了報告には母数: N = 成功 a + 失敗 b + 除外 c + 未認識 dを載せ、成功分から1件を抜き取って中身を確認する。

5. HANDOFFの完了条件を軽く検査する

codex-do.mjsが--prompt-fileを読んだ直後に、DONE_CRITERIA、完了条件、成功条件のいずれも無ければstderrへ警告する。既存利用を壊さないためブロックや終了コード変更はしない。

if (!/(?:DONE_CRITERIA|完了条件|成功条件)/.test(instruction)) {
  console.error('[codex-do] 警告: 指示ファイルに完了条件がありません');
}

6. fixtureで検証する

実memoryは書き換えない。一時ディレクトリへfixtureを作り、Node標準test runnerで、count 2→3、critical、PROMOTED除外、壊れたfrontmatterと母数式、--dry、完了条件なし警告を試験する。

node --test <repo>/tools/learning-ledger.test.mjs
node --test <repo>/tools/codex-do.test.mjs

scratchTokens見積り: 18,000。4プロトコルの設計、CLI仕様、fixture試験をゼロから組み立てる想定。 withMdTokens見積り: 5,000。本書の固定見出し、判定式、試験項目を転用し、環境固有箇所だけ確認する想定。