繰り返す間違いを仕組みで防ぐ

ユーザーが同じ間違いを何度も直している。次のエージェントがその間違いをできないように、対象を変える。

次の作業者は、開いたファイルしか見ず、近くの例を真似し、コンパイルが通る最短の道を選ぶエージェントだと考える。1つのファイルから見て正しそうな変更が、リポジトリ全体でも正しくなる形を目指す。

対象

• リポジトリ: 作業ディレクトリのリポジトリ。既定はこちら。
• グローバルのハーネス: ~/.claude/（CLAUDE.md、hooks/、skills/、agents/、settings.json）。ユーザーが指定した場合か、間違いが特定のリポジトリによらない場合。

1. 間違いの種類を洗い出す

次を読み、間違いを種類ごとにまとめる。同じ種類が2回起きたら1つの種類として数える。

• 最近のコミット、revert、PRのレビューコメント（git log、gh pr view --comments）
• エージェント向けの指示ファイル（AGENTS.md、CLAUDE.md）と、回避策を説明しているコメント
• ~/.claude/harness-log.jsonl。リポジトリが対象ならcwdで絞る。すべてのkindを数える。hookやStop hookが記録したもの（block-*、enforce-package-manager、protect-locked-tests、check-failed、check-failed-gave-up、evidence-missing、evidence-missing-gave-up、broken-link、cwd-moved-linkなど）、correction、manual、triage-override、untriaged-changeは間違いの証拠として扱う。triage、done、evidence-check-disabledは作業の記録で、間違いそのものではない。correctionはtaskでdoneと結びつけ、どのレベルの作業で指摘が多いかを見る（~/.claude/bin/harness-reportで集計できる）。知らないkindがあれば、記録しているhookやスキルを読んで意味を確かめる
• このワークスペースの会話履歴（~/.claude/projects/<slug>/*.jsonl。<slug>は作業ディレクトリのパスの英数字以外を-にしたもの）。ユーザーが訂正した箇所を探す。他のプロジェクトの履歴は読まない

2. 種類ごとに、効く範囲で最も上の層を選ぶ

1. 設計でなくす。 状態ごとに持ち主を1つにし、作業ごとに正しい方法を1つにする。内部を隠して、間違ったimportが失敗するようにする。手で同期しているリストを1つの正本に置き換える。エージェントが真似しそうな古い方法や死んだコードを消す。
2. 型で、間違った状態を書けなくする。 それでも間違ったコードがコンパイルを通るなら、lintかCIのチェックを足し、エラーメッセージで代わりに使うファイル、型、関数を名指しする。その書き方がすでに多いなら、変更で増えたときだけ失敗させる。
3. 振る舞いをテストする。 呼んでいる関数がすべて何も返さなくても通るテストは、直すか消す候補として計画に挙げる。既存のテストの修正や削除は、承認されたものだけ行う。新しいテストのケースは、過去の実際の間違いの入力と、正しいと分かっている出力から作る。それ以外のケースは計画でユーザーに示し、承認を得る。
4. 文書やエージェント向けのルールは最後。 判断が要るものに限る。エージェントが読み飛ばしても何も失敗しないから。

グローバルのハーネスでは、層を次のように読み替える。

1. 正しい方法を道具として用意する（スクリプト、スキル、makeのtarget）。例: rm -rfを繰り返すなら、片付け専用のスクリプトを用意して案内する
2. hookで止め、メッセージで正しい方法を名指しする
3. hookやスクリプトの動作を、過去の実際の入力で確かめる
4. CLAUDE.mdやスキルの文章

3. 計画を書いて承認を得る

.tmp/plan/YYYYMMDD_correct_{target}.mdに、種類ごとに次を書く。

• 証拠（2件以上。コミット、PR、ログの行、会話履歴の位置）
• 選んだ層と、それより上の層が使えない理由
• 追加するチェックと、そのエラーメッセージ
• 証明に使う過去の実際の間違いと、その状態の再現方法
• 直す・消す既存のテスト（あれば）
• 例外の扱い

承認を待つ。ユーザーの注釈はすべて反映してから実装する。

4. 直して証明する

承認された種類を、頻度の高いものから1つずつ直す。

• 新しいチェックが、過去の実際の間違いで失敗し、今のコードで通ることを示す。過去の状態は、git show <commit>:<path>でscratchpadに書き出すか、scratchpadへの複製で再現する。作業ツリーのチェックアウトは変えない。
• ローカルとCIで同じコマンドを実行する（make checkがあればそれに組み込む）。
• 例外は、該当する行に、理由、期限、承認した人間を書く。
• ブランチ作成とコミットは、CLAUDE.mdのGitの規則に従う。承認されていれば、1つの種類につき1コミットにする。

5. ルールの対応表を保つ

各ルールと、それを強制する仕組みの対応表を置く。リポジトリではAGENTS.md（なければCLAUDE.md）、グローバルのハーネスでは~/.claude/rules/enforcement.mdを既定とし、計画で示す。

ユーザーに訂正されて/correctが呼ばれたら、その間違いを直し、ルールを足す。ルールがすでにあって何も強制していなかったら、それは再発なので、同じ変更の中で上の層に上げる。間違いが起こりえなくなったルールは表から消す。

報告

種類ごとに、証拠、選んだ層、それより上の層が使えなかった理由、証明の結果を書く。承認待ちの計画があれば、そのパスを示す。