ループエンジニアリング実践ガイド

# LOOP.md — [ループ名]

## 1. 目的（一文で）
[このループが解決する、週1回以上くり返し発生する作業]

## 2. トリガー
[定時 / イベント / 前周の未達] — 頻度: [  ]

## 3. スコープ
- 触ってよいパス: [  ]
- 絶対に触らないパス: [ migrations/ , infra/ , .github/workflows/ など ]
- 作ってよい成果物: [ PR まで / コミットまで / 報告のみ ]

## 4. 検証（機械的に合否が返るもの）
- コマンド: [ npm test / pytest / build ]
- 合格条件: [ 終了コード 0 かつ 既存テストが1件も落ちない ]
- 検証役: [ 編集権限を持たない別エージェント ]

## 5. 停止条件（3つ全部書く）
- 達成: [ 上記の合格条件を満たした ]
- 試行上限: [ 3回 ]
- 予算上限: [ 1日 $X / 1周 $Y ]

## 6. 自律レベル
- 現在: [ L1 報告のみ ]
- 次に上げる条件: [ 2週間の誤検知率が X% 以下 ]
- 上げる判断をする人: [  ]

## 7. 人間のゲート
- 承認が必要な操作: [ マージ / push / 依存追加 ]
- 週次で読む担当: [  ]

各周回の最後に、必ず STATE.md を以下の書式で「上書き」してください。
追記はしないでください（肥大化を防ぐため、常に最新状態だけを保つ）。

# STATE
- 最終更新: [YYYY-MM-DD HH:MM]
- 周回数: [n]
- ステータス: [ IN_PROGRESS / BLOCKED / DONE ]

## 完了したこと（最大5件・古いものから捨てる）
- [  ]

## 次の1手（1件だけ）
- [  ]

## ブロッカー
- [ 無ければ「なし」 ]

## 触ってはいけないと判断した箇所
- [ path:行 — 理由 ]

制約:
- 「頑張ります」「確認中です」のような進捗のない記述は書かないこと
- 前周と状況が変わっていない場合は「変化なし」とだけ書き、他を書き換えないこと
- 推測を STATE に書かないこと。確認した事実だけを書くこと

あなたはこの変更を書いていない検証役です。コードは編集できません。

判定の材料にしてよいもの：
- 実際に実行したコマンドとその出力
- 差分そのもの

判定の材料にしてはいけないもの：
- 実装者の説明・意図・コミットメッセージ
- 「おそらく動く」「一般的にはこうする」という一般論

必ず次の順で実施してください：
1. [テストコマンド] を実行し、出力をそのまま貼る
2. 差分が [許可されたパス] の外に出ていないか確認する
3. テストが「追加・変更」されている場合、それが仕様の変更なのか
   合格させるための細工なのかを判定する

判定：
- PASS の条件は「1 が終了コード 0」かつ「2 が範囲内」かつ「3 が細工でない」
- 上記のいずれかが確認できない場合は、迷わず FAIL にすること
- 判断がつかない場合も FAIL（UNKNOWN は PASS ではない）

出力は VERDICT / EVIDENCE / BLOCKERS の3項目のみ。

直近7日間の [ループ名] の稼働結果を棚卸ししてください。

集計してほしいもの：
1. 起動回数 / 何かを出力した回数 / 人間が承認した回数
2. 出力のうち、実際にマージされたものの割合
3. 誤検知（人間が却下した）の件数と、その内容の傾向
4. 1周あたりの平均トークン消費と、7日間の合計コスト

そのうえで、次の3つを判定してください：
- このループは自律レベルを上げてよいか（根拠は誤検知率の数字で）
- 下げる、または止めるべきか（同上）
- 検証役が見逃していた種類の問題はあったか

最後に、次の質問に答えてください：
「このループが7日間ずっと間違い続けていたとしたら、
 どの時点で誰が気づけたか。気づけないなら、何を足すべきか」

数字が取れない項目は「計測していない」と書いてください。推定値で埋めないでください。

今週 [ループ名] がマージした変更を対象に、私の理解度を点検してください。

1. 変更されたファイルを、影響の大きい順に5件挙げてください
2. 各ファイルについて、私に対して次の質問をしてください（回答は私がします）
   - この変更が無かった場合、何が壊れますか
   - この実装を選んだ理由は何ですか。他の選択肢は何でしたか
   - この変更が原因で将来壊れるとしたら、どこが壊れますか

3. 私の回答が曖昧だった箇所を記録し、
   「理解できていない領域」として一覧にしてください

制約：
- 私が答えられなかったことを責めないでください。事実として記録してください
- 私の回答が間違っている場合は、遠慮なく指摘してください
- 私が「大丈夫」と言っても、根拠が示されない限り理解済みに分類しないでください

最後に、この一覧のうち「来週までに自分で読むべき1ファイル」を選んでください。

まだコードは変更しないでください。調査だけをお願いします。

[対象ディレクトリ / ファイル] を読んで、次を整理してください。
1. 現在の処理フロー（呼び出し順に箇条書き）
2. 状態・設定がどこで管理されているか
3. 外部依存（API・DB・環境変数）の一覧
4. 読んでいて「なぜこうなっているか分からない」と感じた箇所

推測で埋めた部分には必ず「推測」と明記してください。
根拠にしたファイルは path:行番号 の形式で示してください。

[作りたいものを1〜2行で] を作りたいです。
実装の前に、あなたから私に詳細をインタビューしてください。

- 技術的な実装方針、UI/UX、エッジケース、懸念、トレードオフについて聞いてください
- 答えが自明な質問はしないでください。私が見落としていそうな難所を掘ってください
- 一度に聞くのは3問までにしてください

論点が出尽くしたと判断したら、合意した内容を SPEC.md に書き出してください。
SPEC.md には「対象ファイル」「やらないこと（スコープ外）」
「完成を判定する検証手順」を必ず含めてください。

[実現したいこと] を実装する計画を立ててください。
計画のレビューが終わるまで、コードは編集しないでください。

出力してほしい項目：
1. 現状の処理フローの理解（間違っていたら私が指摘します）
2. 想定している根本的な変更点と、その理由
3. 変更が必要なファイルの一覧（新規/修正/削除の別）
4. 実装手順（レビュー可能な単位に分割）
5. リスクとエッジケース
6. 追加するテストと、その合否条件

不確実な前提があれば、勝手に決めずに質問として挙げてください。

[クラス名 / 関数名] が現在の形になった経緯を知りたいです。

git log と git blame を使って、このコードの変更履歴を追い、
「いつ・何のために・どんな制約から」現在の設計になったのかを要約してください。

- 各主張には該当コミットのハッシュを添えてください
- 履歴から読み取れないことは「履歴からは不明」と書いてください
  （そこを推測で埋めないでください）

[関数名 / 機能] を実装してください。

期待する振る舞い（テストケース）：
- 入力 [A] → 出力 [A']
- 入力 [B] → 出力 [B']
- 入力 [異常系 C] → [例外 / エラー内容]

実装したら `[テストコマンド]` を実行し、
落ちたテストがあれば通るまで修正してください。

完了報告には、実行したコマンドとその出力を必ず貼ってください。
「通ったはずです」ではなく、実際の出力で示してください。

[新しく作りたいもの] を実装してください。

まず [見本になる既存ファイルのパス] を読んで、
このコードベースでの書き方（命名、ディレクトリ構成、エラー処理、テストの置き場所）を把握してください。

制約：
- 上記の見本と同じ構造・同じ命名規則で書いてください
- 既に使われているライブラリ以外は追加しないでください
- 既存の [共通処理 / ユーティリティ] があれば再実装せず再利用してください

実装前に「見本から読み取った規則」を3行で要約してください。
そこがずれていたら私が止めます。

テストファーストで進めてください。順番を守ってください。

1. [仕様] を検証するテストを書く（実装はまだしない）
2. テストを実行し、期待どおり「落ちる」ことを確認する
   → この時点で失敗ログを私に見せてください
3. テストを通す最小限の実装をする
   → このときテストコードは書き換えないでください
4. 全テストを実行し、緑になったログを見せる

途中でテストの期待値を変えたくなった場合は、
勝手に変えず「仕様の解釈がずれている可能性がある」と報告してください。

[目標のデザイン画像を添付]

この画像のとおりに [対象ページ / コンポーネント] を実装してください。

実装後、実際の画面のスクリーンショットを撮り、目標画像と比較して
「一致していない点」を箇条書きで列挙してください（余白・字間・色・角丸など）。
列挙した差分を修正し、再度スクリーンショットを撮って比較してください。

差分が実装上の制約で埋められない場合は、
黙って妥協せず「埋められない理由」を書いてください。

バグの調査をお願いします。まだ修正はしないでください。

- 期待する挙動：[  ]
- 実際の挙動：[  ]
- エラー / スタックトレース：
```
[貼り付け]
```
- 関係しそうな箇所：[ファイルパス]
- すでに試したこと：[  ]

出してほしいもの：
1. 根本原因の仮説（複数あれば確からしい順に、それぞれ根拠つきで）
2. その仮説を確かめる方法（実行するコマンド or 見るべき箇所）
3. 同じ原因が影響していそうな他の箇所
4. 修正方針（対症療法ではなく原因側を直す案）

エラーの握り潰し（try-catch で黙らせる、条件を追加して回避する）は
解決策として提案しないでください。

[バグの症状] という不具合が報告されています。
[怪しい箇所] のあたりを確認してください。

手順：
1. この不具合を再現する失敗テストを書く
2. テストが落ちることを確認する（ログを見せる）
3. 原因を修正する
4. テストが通ることと、既存テストが壊れていないことを確認する（ログを見せる）

修正の diff と、なぜその修正で直るのかの説明を最後にまとめてください。

Wait.

いまの回答を、書いた本人ではなく第三者のレビュアーとして読み直してください。

- 事実として間違っている記述はありませんか
- 前半と後半で矛盾している主張はありませんか
- 検証せずに「たぶんこうだろう」で書いた箇所はどこですか

問題が無いなら「問題なし」と一言で答えてください。
無理に修正点を作り出さないでください。

あなたはこの変更を書いていない、外部のレビュアーです。
実装の意図は聞かされていない前提で、差分だけを見て評価してください。

対象：[ファイルパス / git diff の範囲]

見てほしい観点：
- 正しさに関わる欠陥（境界値、null / 空配列、例外経路、競合状態）
- 既存の実装パターンからの逸脱
- テストが無い分岐

出力形式：
| 深刻度 | 場所(path:行) | 何が問題か | 起きる不具合 |

制約：
- 好みの問題（命名の趣味、書式）は挙げないでください
- 「念のため」の防御的コード追加は提案しないでください
- 指摘が無い観点は「問題なし」と書いてください。数を埋めないでください

[対象の差分 / ファイル] を、次の観点「だけ」に絞ってレビューしてください。
他の観点には触れないでください。

観点：[認証・認可の抜け / 入力バリデーション / N+1 と計算量 / 例外時のリソース解放 / 並行処理の競合]

各指摘には必ず以下を付けてください：
- 該当行（path:行番号）
- 深刻度（Critical / High / Medium / Low）
- その問題が発火する具体的な入力または状況
- 修正案（diff 形式）

「発火する具体的な状況」を書けない指摘は、確信が持てていないということなので
提出せず削ってください。

[SPEC.md / PLAN.md] を正として、実際の差分と突き合わせてください。

確認項目：
1. 計画に書かれた要件のうち、実装されていないものはどれか
2. 挙げられていたエッジケースのうち、テストが無いものはどれか
3. 計画に無いのに変更されているファイル・振る舞いはあるか
4. 計画時の前提が、実装中に崩れた形跡はあるか

出力は「未達」「過剰」「前提の崩れ」の3見出しに分けてください。
スタイルや設計の好みについての指摘は不要です。

【1ターン目：検証質問の生成】
いまの回答に含まれる「事実として真偽が判定できる主張」を、すべて箇条書きで抜き出してください。
そのうえで、各主張を検証するための独立した質問を作ってください。
質問は、元の回答を読んでいない人でも単体で答えられる形にしてください。
この時点では回答しないでください。

【2ターン目：新しいセッションで実行】
以下の質問に、それぞれ独立して答えてください。
質問どうしの整合性は気にせず、1問ずつ根拠を示して答えてください。
根拠が確認できないものは「確認できず」と答えてください。

[1ターン目で出た質問を貼る]

【3ターン目：元のセッションに戻して実行】
以下が独立検証の結果です。
元の回答と矛盾する点だけを抽出し、その箇所を修正した最終版を出してください。
矛盾が無かった箇所は書き換えないでください。

[2ターン目の回答を貼る]

[判断したいこと] について評価してください。

私はまだ結論を出していません。私の意向を推測して寄せないでください。

必ず次の順で書いてください：
1. この案を採るべき理由（最も強い根拠を3つ）
2. この案を採るべきでない理由（最も強い根拠を3つ）
3. 判断が変わる分岐点になる事実は何か
4. その事実を確かめる方法
5. 現時点での推奨と、その確信度（％）と、確信度がその値である理由

私が後から反論した場合も、
新しい根拠が無い限り結論を変えないでください。

【ステップ1：対象の一覧化】
[移行内容：例 "React クラスコンポーネントを関数コンポーネントへ"] の対象になるファイルを
すべて洗い出し、files.txt に1行1パスで書き出してください。
判断に迷ったファイルは別リストに分けてください。

【ステップ2：試走】
files.txt の先頭3件だけを移行してください。
移行後、各ファイルについて「変換した内容」と「判断に迷った点」を報告してください。
（ここで私が指示を修正します）

【ステップ3：一括】
残りのファイルを1件ずつ独立して移行してください。
各ファイルについて、テストを実行し OK / FAIL のみを返してください。
FAIL のものは修正せず、理由を1行添えて一覧の最後にまとめてください。

[対象コード] をリファクタしたいです。外部から見た振る舞いは一切変えません。

順番を守ってください：
1. 現在の振る舞いを固定するテスト（characterization test）を書く
   - 現状が仕様として正しいかは問わない。「今こうなっている」を記録する
   - 異常系・境界値も含める
2. テストが全て通ることを確認する（この時点ではコードを変えない）
3. リファクタを実施する
4. 手順1のテストを一切書き換えずに再実行し、全て通ることを示す

リファクタ中に「現状の挙動がバグに見える」箇所を見つけた場合、
直さずに別途リストとして報告してください。

[CLAUDE.md / AGENTS.md] を剪定してください。

各行について、次を判定してください：
- コードを読めば分かることか（→ 削除候補）
- 一般的な言語慣習として既に知っていることか（→ 削除候補）
- この行を消したら実際に間違いが起きるか（→ 残す）
- 頻繁に変わる情報か（→ 削除候補。参照先リンクに置き換える）

出力：
1. 削除候補の一覧と、それぞれの削除理由
2. 剪定後の全文
3. 「規約ではなく自動実行すべき」もの（lint / フォーマッタ / フックに落とせるもの）の一覧

判断に迷う行は削らず、迷った理由を添えて残してください。

以下は、私が使っているプロンプトです。

```
[現在のプロンプト]
```

期待した結果：[  ]
実際に返ってきた結果：[  ]

このプロンプトを読んで、次を教えてください：
1. 期待した動きを妨げている指示はどれか（該当箇所を引用して）
2. 曖昧で複数の解釈ができる表現はどれか
3. 削っても結果が変わらない冗長な指示はどれか
4. 上記を反映した改訂版

改訂版は、元より短くしてください。
指示を足して解決するのではなく、誤解の元を取り除く方向で直してください。

## 出力ルール
- 通常の回答：3〜6文、または箇条書き5個以内
- はい/いいえで答えられる質問：2文以内
- 複数手順を伴う作業の報告：概要1段落のあと、以下のラベルつき箇条書き5個以内
  - 変更点 / 対象箇所 / リスク / 次の一手 / 未解決の論点
- コードは差分または該当関数のみを示す。ファイル全文は貼らない

## 長時間の作業中
- ツールを数回実行するごとに、状況が変わったときだけ1〜2文で進捗を報告する
- 最初のツール実行の前に、目的と制約を1文ずつ書く
- 進捗報告には必ず具体的な結果を書く（「確認中です」だけの報告はしない）

回答する際、次を守ってください。

- 判断に必要な情報が足りない場合は、推測で埋めずに「情報が足りない」と言ってください。
  そのうえで、何があれば判断できるかを書いてください
- 確認せずに書いた箇所には「未確認」と明記してください
- 実際に読んだファイル・実行したコマンドの結果に基づく記述と、
  一般論に基づく記述を分けて書いてください

「分かりません」は許容される回答です。
無理に答えを出すより、そちらを優先してください。

回答の前に、以下を実施してください。

【1. 下書き】
まず通常どおり回答を作ってください（まだ出力しません）。

【2. 検証の実行】
下書きに含まれる事実主張を箇条書きで抜き出し、それぞれについて
「どうやって確かめたか」を書いてください。
- 実際に検索・ファイル参照・コマンド実行で確認した → 参照元を示す
- 確認していない → 「未確認」と書く（ここを推測で埋めないでください）

【3. 4項目の点検】
- 事実関係：上記で未確認のまま残った主張はどれか
- 論理の一貫性：前提と結論が飛んでいる箇所はどこか
- 網羅性：問いに対して答えていない論点は何か
- 偏り：私の意向に寄せた（反論を避けた）箇所はどこか

【4. 出力】
点検で見つかった問題を修正した最終版を出してください。
文末に次を必ず付けてください：
- 確信度（％）とその根拠
- 未確認のまま残した事項の一覧
- 推測で書いた箇所の一覧

確信度が 80% を下回る場合は、断定を避けた表現に書き換えたうえで、
何を確認すれば確信度が上がるかを書いてください。