Fw Trap

---
name: fw-trap
description: flightwake 罠の登録 — 自明でない罠を TRAPS レジストリに書く。Use immediately when a surprising root cause is found (weird error, vendor quirk, encoding trap), or when the user says この罠を記録して/trap.
---

# fw-trap — 罠の登録

目的:同じ罠は 1 プロジェクトにつき 1 回だけ踏む(将来のセッションや他の agent も含めて)。

## TRAPS に載せる条件

- 症状と根本原因が**遠い**(例:jsonb が文字列スカラーとして保存される → 根本原因は driver の「文字列パラメータ + ::jsonb」のエンコード方式)
- ベンダーの文書化されていない挙動(例:ある操作経路では webhook が発火しない)
- 環境差の罠(ローカルでは通り、prod で爆発する)
- **載せないもの**:普通のバグ、エラーメッセージを読めば分かること

## 根本原因の確度(confidence)

レジストリの最も高くつく失敗は記録漏れではなく、**誤診を確定事項として書くこと**である——
読む側は「統制実験で確定したもの」と「その時点で最もありそうな説明」を区別できず、
誤った根本原因に従うのはレジストリが無いよりも遠回りになる。だから根本原因には確度を付ける:

| confidence | 意味 | 求められる根拠 |
|---|---|---|
| `confirmed` | 統制実験:原因を切り替える → 症状が現れる/消える、最低 2 回。**非因果的**な事実(ある機能の有無、一覧の内容、バージョン挙動)については「網羅的な直接確認 + 指し示せる一次情報(ソース行番号/公式ドキュメント/管理画面での逐一確認)」で代替する | 根拠欄がその実験またはその情報源を指し示せること |
| `probable` | 複数回の観察で一貫、ただし対照群なし | 観察回数と期間を書く |
| `suspected` | 単発の観察、または「その時点で最も可能性の高い説明」 | **まだ排除できていないもの**を明記する |

3 つのルール:

1. **症状欄は常に事実**(エラーは原文のまま貼る)。confidence が評価するのは「根本原因」欄のみ
2. `confirmed` 未満の項目は、対処を必ず「**回避**」として書く——「対処」とは書かない。**行動規範にもしない**
3. **非対称な基準**——この罠を「**これは壊れる**」の論拠に使うなら `probable` で足りる(外しても余分に守るだけ);
   「**これは安全だ**」の論拠にするなら `confirmed` が必須(外すと prod とユーザーに直撃する)

確度の引き上げ(suspected → confirmed)は**同じ項目をその場で書き換える**ことであり、supersede ではない。
supersede は「根本原因そのものが変わった」場合のために取っておく。

## 手順

1. `.flightwake/TRAPS.md` の冒頭で示されている項目形式(OKF 式 frontmatter:name/type/status/confidence/tags/discovered)に従い、
   `.flightwake/TRAPS.md` の**一番上**に書く
   任意の `paths` / `commands`——落とし穴が特定のファイルやコマンドに結びつくときだけ書く。Claude Code mod の検知線が、誰かが触れた
   瞬間にこの項目を示せるようになる:`paths: ["src/db/**", "*.sql"]`(repo 相対の glob。`/` を含まないパターンは任意の深さの同名ファイルに
   一致)、`commands: ["npm run migrate", "psql"]`(コマンドの前方一致、単語単位)。正規表現は使えない。迷ったら、あるいは場所ではなく
   考え方の落とし穴なら、空のままでよい——書かなくても項目は同じように働く
2. 4 つの欄をすべて埋める:症状(元のエラーメッセージを貼る)、根本原因を一文で、対処/回避、根拠リンク(commit/record)
3. 関連する罠は `[[名前]]` でリンクする
4. **症状はその場で書く**——細部は半日で曖昧になる。**根本原因は確定するまで断定しない**——
   未確定なら `confidence: suspected` を付け、まだ排除できていないものを書く。考えがまとまるまで
   書かずに置くのも、推測を結論として書くのも避ける。確定したら戻って引き上げる
5. 新しい罠が既存項目を**置き換える/包含する**場合:古い項目の frontmatter の `status` を `superseded` にし、本文で [[新しい項目]] を指す——行は決して削除しない。
   こうすれば「古い md vs 新しい md」が矛盾しても常に方向が定まる
6. 罠の**スコープ**を判断する:この repo 固有でない——どのプロジェクトでも踏む(プラットフォーム/言語/ツール層、例えば Node の stdin 挙動、shell の展開)——場合も、
   TRAPS には登録する(repo のレジストリは自己完結していなければならない:次の人や agent はあなたの個人メモリを見られない)。
   **同時にユーザーレベルのメモリにも 1 部保存する**(Claude memory など)。そうすれば他の repo で踏み直さずに済む。
   スコープごとに 1 部ずつ持つのは分担であって重複ではない:汎用の罠を 1 つの repo にしか記録しなければ、次の repo でまた刺さる