spec-dev: 工程ゲート付き開発フロー

目的: 「情報不足・仕様の問題が後工程で発覚して手戻りする」ことを、 各工程の完了条件 (ゲート) とトレース ID で防ぐ。

成果物の置き場所と命名

TODO.md                                  # やることリスト (repo 直下)
docs/<feature>/requirements.md           # R-01, R-02, ... (現在の正)
docs/<feature>/spec.md                   # S-01 (実現する R を明記)
docs/<feature>/design.md                 # D-01 (実現する S を明記) + ADR
docs/<feature>/coding.md                 # D↔コード表 + S↔T 表 (実装フェーズで作る)
notes/YYYYMMDD-<topic>.md                # 調査メモ (作業記録)
notes/fix-sessions/YYYYMMDD-<topic>.md   # fix-loop の作業台帳
notes/reviews/YYYYMMDD-<topic>.md        # コードレビュー結果の全文 (冒頭に対象コミット)
notes/review-log.md                      # cq-review の指摘台帳

ID は repo 全体で一意 — feature ごとに R-01 から始めない。テストコメントや コミットメッセージに書かれた ID は feature の文脈を持たないので、番号が唯一の 鍵になる。2 つ目以降の feature は既存の続き番号から始める。次に使える番号は trace-matrix.py の next: 行が出す (退役済みの番号も消費済みとして数える)。

使い分け: docs/ は「現在の正」(要件・仕様・設計) を置く。内容の改訂は 取り消し線と理由で痕跡を残し、ID ごとの撤回・移管は退役台帳へ (下記)。 notes/ は「時系列の作業記録」で、上書きせず追記していく。 TODO.md は「生きたやることリスト」で、完了したら消し込む (履歴は git と notes/ に残る)。

notes/ を独立した private repo にする場合

公開 repo の中に notes/ を私的な別 repo として置く構成 (親の .gitignore で無視) も想定内。その場合の注意:

• TODO.md も notes/ 側に置く。TODO → notes/reviews 等のリンクが private 内で 閉じ、公開読者に辿れないリンクが生まれない。公開側の文書に notes/ の内容が 必要なら、リンクせず要約して書く (rules/40-references.md の REF-2 と同じ理屈)
• notes/ にプログラムを置かない (CLAUDE.md のディレクトリ規約にも明記)。 .gitignore は言語ツールに効かず、go build ./... や import 探索はツリーを 歩く。そのため、コミットされないファイルが親のビルドや依存ファイルを汚す (実測: notes/ の捨て .go が原因で親の go.mod に推移的依存 7 行が入った)。 捨てスクリプトは調査メモの中にコードブロックとして記録し、実行形が要る間は セッションの scratchpad に置く。どうしても notes/ に実行形で残すなら、 ディレクトリ単位で除外される手段を使う (Go なら notes/ に入れ子の go.mod)
• 親 repo での git add -A は notes/ への gitlink を黙って stage する (実測: 1 日 3 回)。コミットゲート導入済みなら pre-commit が止める (意図的な 埋め込み repo は gate.conf の embedded_repos= に宣言)。剥がすのは git rm -f --cached notes
• notes/ から親のコミット件名への参照は別 repo 参照になる。notes/ は腐りを 許容する記録なので構わないが、その前提は意識しておく (REF-1 の対象外の続き)

撤回・移管 — 退役台帳

R/S/D を撤回したり、実装をサブパッケージ等へ移して文書の対象から外すときは、 本文を削除し (履歴は git が持つ)、文書の末尾に 1 行だけ残す:

## 退役 (番号は再利用しない)
- R-05: 2026-08-13 撤回 — ブラウザ操作をスコープ外にした (ADR-07)
- D-03: 2026-08-13 移管 — ext/fetch サブパッケージへ

• 台帳はその ID を定義していた文書の末尾の節であって、独立した .md を 作らない (R なら requirements.md、S なら spec.md、D なら design.md の末尾。 1 文書に台帳節は 1 つ)。読み手が R-05 を探す場所は requirements.md であり、 退役ファイルという新しい置き場を増やさない
• 判断の理由本体は ADR に書き、台帳は 1 行 + ポインタに留める
• 取り消し線を退役に使わない。取り消し線は「内容を改訂して痕跡を残す」ための 表現で、ID ごと退役させるときは台帳が痕跡になる (取り消し線見出しは trace-matrix から定義が消え、参照が全部「未定義」になる — 実事故)
• trace-matrix.py は台帳を読む: 退役 ID への言及は未定義参照にならず、カバレッジ 要求からも外れる。生きた見出しが退役 ID を「実現する」と主張していたら指摘 (退役の波及漏れ検出)。番号を再利用すると「台帳に載っているのに定義がある」と 指摘される
• feature 丸ごと移管したときは、文書冒頭に移管注記を書いてその feature の trace-matrix を回すのをやめる (文書ごと新しい置き場へ移すのが最善) レビュー指摘のうち今直さないものは TODO.md へ 1 行 (要点 + 場所 + あれば S-ID + 出典レビューへのリンク) で入れる。リンクは TODO → notes/ の片方向のみ (TODO は消し込むので、逆向きに張ると古くなる)。 PR ベースの開発では、レビュー結果は原則 PR コメントに残す (repo 内には置かない)。 notes/reviews/ は PR を使わないローカルレビューの全文を残したい場合に使う。

TODO を拾って修正するときの規模判定

すべての TODO に本フローをフル適用しない。ドキュメントを書くのは「判断があった所」だけ (全部に requirements から書き始めるとゲートが形骸化する):

テンプレートはこの Skill の templates/ にある。コミットやテストコメントにも ID を書く (例: // T-03: S-02 boundary case)。この ID が後の影響範囲調査 (/rework) の索引になる。

ゲートの機械チェック: trace-matrix.py

trace-matrix.py はこの SKILL.md と同じディレクトリにある。$SKILL はこの Skill の ディレクトリ (ホーム導入なら ~/.claude/skills/spec-dev、プロジェクト導入なら <repo>/.claude/skills/spec-dev)。

python3 $SKILL/trace-matrix.py [--code src/ --code test/] [--matrix] docs/<feature>/

R/S/D/T の定義と参照を走査し、「spec にカバーされていない R」「design にカバーされていない S」 「テストが参照していない S」「未定義 ID の参照 (typo)」「二重定義」を検出する。 ただし「カバーされている」は ID の言及の検査であって実現の主張の検査ではない — design 文書のどこかに「S-17 はこれから書く」と 1 行あるだけでもカバー扱いになる (実測)。D が本当にその S を実現しているかは、機械では見ておらず G2 の目視レビューが 担う。この検査を強い保証と読み違えないこと。 問題があると exit 1。ゲート G1 / G2 / G4 の対応表確認は目視でなくこれを実行する (テストファイルは --code のパス中の名前に test を含むもの。T-ID はテスト内の コメントが定義扱い)。--matrix で全 ID の対応表 (Markdown) も出せる。

ゲートの手作業だった 2 項目も検査する (その場で書く awk は、間違うと「全部だめ」か 「全部よし」に倒れる — 3 件の欠落を 10 件と報告した実事故が動機):

• 必須小見出し: 各 ID の節に決めた見出しがあるか。既定はテンプレートの 項目名 (S = 受入条件 + 境界条件・エラー時、R = 入出力例 + 境界条件)。 - 受入条件 (…): / **受入条件** / #### 受入条件 のどの表記でも拾う
• 曖昧語: G1 のリスト (適切に / 必要に応じて / など / 高速に / 柔軟に / 原則として) を requirements と spec の ID 節の中だけ走査する (用語定義の節は曖昧語を定義する場所なので対象外)

コミットゲート導入済みのプロジェクトでは、tools/gate.conf に trace_args="--code lib --code test docs/" を設定する。すると docs/ やコードを触る コミットごとに全 feature の matrix が自動走査され、壊したコミットはその場で 止まる (tools/check-trace.py)。有効化は matrix が緑の状態で行うこと。

このゲートが測るのは commit 内容ではなくその瞬間の worktree (check-metrics と 同じ)。テストを unstage したまま文書だけ commit しても通ってしまうが、それは 「単独で checkout すると赤い」履歴を作るのでやらない。コミットの単位は 「文書 + テスト側の ID 帳簿」 — S の受入条件と T は 1 つの宣言の両面なので 一緒に動かす。テストはこの時点で落ちてよい (G4 の「実装前に落ちる」の証拠が 履歴に残る)。メッセージに「tests fail by design; implementation follows」と 明記し、実装は次のコミット。

例外と上書きは docs/<feature>/trace-gate.txt に理由付きで宣言する (cq-baseline.txt と同じ契約 — 行を書くことが査読。理由を書けないなら文書側を直す):

require: S = 受入条件, 境界条件・エラー時   # この feature の必須見出し (空 = 無効化)
words: など, 適切に                          # 曖昧語リストの差し替え
word: S-03 など                              # この節のこの語は残す (理由を上に)
heading: R-03 入出力例                       # この節はこの見出しを持たない (同上)
pending: R-16                                # 着手中 — カバレッジ穴を今は受け入れる (同上)

pending: はフェーズを段階のままコミットするための宣言で、その ID の カバレッジ穴 (spec/design/テスト未カバー) だけを抑える。typo 参照・二重定義・ 退役違反・見出し・曖昧語は抑えない。集計に pending: R-16, S-17 (test) の形で 残っている穴の種類ごと表示されるので、着手中は宣言されて見える — 黙って 壊れている状態は存在しない。穴が塞がる (または ID ごと消える) と宣言自体は 陳腐化として報告されるので、消し忘れて居座ることもできない。

pending は matrix を通すための呪文ではない。実際に着手中の ID だけに書く (理由を上に書けないなら、それは着手中ではない)。ゲートとの対応: G1 通過時に pending へ R が残っていない / G2 通過時に S の (design) が残っていない / G4 通過時に pending: 行が空。

フェーズと出口ゲート

各ゲートの通過はユーザーの承認を得てから次へ進む。ゲートで落ちた項目は 「未確定事項」として requirements.md に残し、勝手に仮定で埋めない (仮定するなら「仮定:」と明記して承認を得る)。

ゲート項目の判定には確認した根拠を 1 つ添える (実行したコマンド・見た file:line・grep 結果)。添えられない項目は「通過」でも「該当なし」でもなく 「未確認」。根拠の無い「該当なし」は見ていない印で、チェックリストを 機械的に埋め始めたらそれは中身が無い合図。

フェーズ 0: 調査・要件整理 → requirements.md

最初に全 feature の matrix を回して現状を把握する: python3 $SKILL/trace-matrix.py [--code src --code test] docs/。 既に壊れていたら、それは前回以降の修正 (テストの削除・改名など) が壊したもので、 これから作る feature とは別物。先に直すか退役台帳へ移すかをユーザーと決めて から始める (作業の途中で「突然壊れている」と報告されるのが最悪の形)。

次に AI がユーザーに要件インタビューをする:

1. このタスクが解決する問題は何か。誰が使うか
2. 入力と出力の具体例 (正常系 1 つ、異常系 1 つ以上)
3. 境界条件 (0/空/最大/同時/失敗時)
4. 非機能要件 (性能、メモリ、互換性、対応環境)
5. 制約 (既存コードとの整合、変更してはいけない部分)
6. やらないこと (スコープ外の明示)
7. この変更が奪う既存の既定動作・振る舞いと、その代わりに用意するもの (例: シグナルを捕まえれば既定の即時終了が消える。エラー時の既定挙動、 OS/言語/フレームワークのデフォルトも対象)。奪うものが無ければ「無い」と書く — 奪うことは目的の副作用として起きるので、問われない限り話題に上らない

既存の notes/ を先に grep し、既知情報を質問しない。調査した内容は notes/ に保存する。

ゲート G0: 全 R に受入可能な形の記述がある / 未確定事項リストは空または承認済み / 「やらないこと」が 1 つ以上書かれている

フェーズ 1: 仕様 → spec.md

各 S 項目は「どの R を実現するか」と「受入条件 (検証可能な形)」を持つ。

ゲート G1:

• 全 R がいずれかの S でカバーされている (対応表で確認)。pending に R が残っていない
• 曖昧語が残っていないか: 「適切に」「必要に応じて」「など」「高速に」「柔軟に」 「原則として」を grep し、残す場合は定義を付ける
• 受入条件が手段になっていないか: 「同じ X を使う」「〜方式で」「〜を共有する」の ように実現方法が書かれていたら design へ移し、その手段で達成したい観測可能な結果 (入力→出力/状態) に書き直す。リトマス試験: 「実装を丸ごと取り替えても、この文の 真偽を判定できるか」— できなければ手段が混じっている
• 受入条件が片側だけになっていないか: 「N 秒以上」「M 以下」のように一方向しか 縛らない条件は、縛っていない側へ動く変更で真偽が変わらない。縛っていない側に 起こりうる変更を 1 つ挙げ、その変更でこの条件が偽になるか言う。ならないなら、 その条件は「今の実装がたまたま満たしていること」を書いているだけで、仕様として 決めていない。両側を書くか、片側でよい理由 (もう一方はいくら動いても誰も困らない) を添える。リトマス試験: 「この条件を全部満たしたまま、明らかに違うものを作れるか」 — 作れるなら片側が空いている
• 全 S に境界条件・エラー時の挙動が書かれている
• 受入条件は機械またはテストで判定可能な形か

片側の条件は後から効いてくる。「要求の間隔が 60 秒以上」は、間隔を 10 分に しても真であり、待ちを 1.0〜1.3 倍に散らす変更を入れたときも真のままだった — つまりその変更が入ったかどうかを、その仕様は何も言えない。受入条件が変わらない ことは「影響が無い」の証明ではなく、「検査していない」の印でありうる。この形を 見つけたら、既存の条件を書き換えるのではなく新しい S を立てる (古い条件は 古い条件で正しいので、消すと別のものが検査されなくなる)。

フェーズ 2: 設計 → design.md

モジュール分割、インタフェース (シグネチャレベル)、データフロー、エラー伝播を書く。 重要な判断は ADR ブロック (背景/選択肢/決定/理由) で残す。

ゲート G2 (設計レビュー):

• 全 S がいずれかの D でカバーされている。pending の S に (design) が残っていない
• 各モジュールの責務が 1 文で言えるか (言えない = 凝集度不足)
• モジュール間の依存が一方向か。循環依存がないか
• インタフェースは呼び出し例が書けるレベルに具体化されているか
• エラーの発生源と処理場所が決まっているか
• 「この設計でテストを書けるか」を T の視点で確認 (テスト容易性)
• 結合度: ある S の変更が複数 D に波及しないか (するなら分割を再考)

フェーズ 3: 実装

• D 単位で実装し、コミットメッセージに D-ID を含める (英語)。逆に文書から コミットを指すときはハッシュでなく件名か D-ID で (coding-rules の rules/40-references.md。履歴書き換えでハッシュは全滅する)
• 実装前に coding-rules Skill のルール (rules/*.md) を読み込み、書きながら適用する
• coding.md を作り、D↔コード表を書く (templates/coding.md)。実装コードのコメントには D-ID を書かない — コメントの説明は修正と一緒に直るが、番号は直らず残り、 古い番号は間違った出自を主張するので無いより悪い。D とファイルの対応は coding.md 側に集約する
• 実装して設計と変わった点は coding.md の「設計から変えた点」に理由ごと記録する (design.md 本体も取り消し線 + 理由で更新する)
• AI 実装の場合: 複数回試行になりそうなら fix-loop Skill のプロトコルで進める
• 実装完了時に cq-review Skill でレビューし、指摘を解消してから人間レビューへ
• 人間レビュー依頼時は self-review Skill のレビューパックを付ける

ゲート G3:

• ビルドが通る / cq-review の高深刻度指摘ゼロ / 全 D に対応する実装がある
• coding.md の D↔コード表が全 D を持つ
• 実装前に読んだ coding-rules の rules/*.md をファイル名で列挙できる (列挙できない = 読んでいない。本文の指示だけではゲートを通す作業の中で 存在しないのと同じだった、という実例から)

フェーズ 4: テスト組み込み

spec.md の受入条件 1 つにつき最低 1 つのテスト (T-ID) を作る。 テストには対応する S-ID をコメントで書く。設計判断そのもの (S に現れない内部の 取り決め) を固定するテストは、S の代わりに D-ID を参照してよい。

テストの層 (UT/FT 相当) は ID では分けず、次の 2 つで担保する:

• 機構の選び方: その条件を観測できる最小の機構で書く (純粋関数 > クラス単体 > 結合/UI)。ただし受入条件が複数の D にまたがる (モジュール間の 配線・ライフサイクル・UI 操作を含む) 場合、境界をスタブしたテストはその条件を 検証していない — 実経路を通すテストを最低 1 本書く (FT 相当)
• 単体の十分性: coding.md の D↔コード表の「壊れたら落ちるテスト」列を埋める。 D ごとに「この D を壊したらどの T が落ちるか」を書けるかが UT 相当の十分性。 書けない行はテストを足すか、「検証していないこと」に理由ごと載せる

coding.md に S↔T 表 (どの受入条件をどのテストが確かめるか) と 「検証していないこと」(自動テストで届かず、実機や手動でしか確認できない範囲。 対応する R/S を添える) を書く。

ゲート G4:

• 全 S の受入条件に T が対応している (「仕様にあってテストにない ID」がゼロ)。 matrix の pending: 行が空になっている
• 各 S に対応する T のうち最低 1 本は実経路を通しているか (S が複数の D に またがる場合、スタブ済みの単体テストだけでは通過にしない)
• D↔コード表の全行に「壊れたら落ちるテスト」があるか (無い行は 「検証していないこと」に理由付きで載っている)
• coding.md の S↔T 表と「検証していないこと」が書かれている
• 境界条件・異常系のテストが正常系と同数程度あるか
• テストは実装前は失敗し、実装後は通ることを確認したか (可能な場合)
• 失敗の理由が想定どおりかを失敗メッセージで確かめたか — 実装の不在ではなく テスト側の不備 (ディレクトリ未作成・定義未読込など、対象に到達する前の失敗) で 落ちていたなら、実装後に通っても何も担保していない
• lit ベースなら結果の確認は triage Skill を使う

途中で問題が見つかったら

上流 (要件・仕様・設計) の誤り・不足が見つかった場合は、その場で直さず /rework (rework Skill) に切り替える。トレース ID による影響範囲分析から始める。

上流文書の ID を直したら、その 1 段上の ID を読み直す (S を直したら実現元の R、 D を直したら S)。矛盾がないことを確認してから先へ進む。trace-matrix は ID の 有無しか見ないので、意味のズレはこの習慣でしか捕まらない。