契約と仕様書

実装者が暗黙の仕様判断をせずに済む契約と実装境界を決める。レベル1は会話に短い契約を示し、レベル2は.tmp/plan/YYYYMMDD_{topic}_spec.mdに仕様書を書く。

書く前に確認すること

会話、関連する.tmp/research/、既存コード、既存テストから現在の挙動と契約を確認する。変更対象と同種の既存実装を読み、接続点と既存の公開挙動を特定する。

続けて次の3つを行い、結果を契約や仕様書に書く。

1. ユーザーの目的と、解こうとしている問題を、自分の言葉で1〜2文に言い直す。依頼の文面を写すのではなく、なぜそれが必要かまで書く。
2. ユーザーが言っていない前提を列挙する。別の環境、別のプロジェクト、一般的な構成から持ち込んだ前提は、どこから来たかを添える。確かめられる前提は確かめ、確かめられないものは[未確定]にする。
3. 関連する未マージのPR、Issue、直近の議論を確認する。gh pr list --searchやgh issue list --searchで探し、会話で共有されたPR、Issue、Slackのスレッドは中身を読む。進行中の変更や既にある判断と食い違う計画を書かない。gitやGitHubを使っていない、Slackを読む手段がないなどで探せない場合は、その理由を前提として書く。

受け入れ条件の印とテストケースの候補

受け入れ条件は「テストが通る」ではなく、利用者または対象システムが観測できる完了状態として書き、末尾に確かめ方を付ける。

• [test]: ユーザーが示したテストケースを自動テストにする。ユーザーがケースを示したか、テストを書くよう明示した条件だけに付け、自分の判断では付けない
• [check]: 既存のmake check、型検査、既存テスト、ブラウザ操作、実行結果で確かめる
• [human]: ユーザーが画面や出力を見て確かめる。見るための材料（スクリーンショット、見る手順、URL、起動コマンド）をevidence.mdに用意する（~/.claude/references/evidence.md）

自動テストにする価値がありそうな条件があれば、テストを書かずにテストケースの候補を一覧で示す。1行に「入力 → 期待する結果」と対応する受け入れ条件を書き、テストしないこと（理由付き）も添える。ユーザーが選んだケースだけを[test]にし、選ばれなかった条件は[check]か[human]のままにする。レベルE、0では候補を示さない。テストの本数は[test]の条件の数を超えない（1条件1本まで）。

レベル1: 短い契約

目的（自分の言葉で言い直したもの）、置いた前提（関連する未マージのPR、Issue、議論があれば、その関係も）、受け入れ条件（印付き）、やらないこと、変更してよい範囲の5項目を会話に示す。前提がなければ「なし」と書く。[test]の条件には、ユーザーが示した「入力 → 期待値」を1行で添える。承認は待たずに進め、ユーザーが違うと言えば止めて直す。

レベル2: 仕様書

共通項目:

• 目的とOutcome（ユーザーの目的と問題を自分の言葉で言い直したもの）
• 前提（ユーザーが述べていないもの。出どころと、確かめたかどうか）
• 関連する未マージのPR、Issue、議論と、この計画との関係（なければ「なし」と、探した方法）
• スコープと非目標
• 受け入れ条件（印付き）とテストケースの候補
• 変更対象と既存モジュールとの接続点
• 入力、出力、失敗、不変条件、副作用のうち該当する契約
• 検証方法
• 未確定事項。[未確定]として列挙し、実装で勝手に吸収しない

判断に関係する場合だけ書く項目: APIと公開型、データモデルと移行、UI・UX、非機能要件、依存ライブラリと外部サービス、純粋ロジックと副作用の境界、テスト戦略。

長期的な設計記録が必要なアーキテクチャ判断は、ADR作成を提案する。承認前にADRは作らない。

仕様書はユーザーの承認を待つ。

リファクタリングの場合

既存の外部挙動を契約として固定し、その内側だけを整理する計画を.tmp/plan/YYYYMMDD_{topic}_refactor-plan.mdに書く。形式はreferences/refactor-plan-template.mdに従う。実装の手順はplaybookのplaybooks/refactoring.mdに従う。

• 定義、参照、型、呼び出し境界はLSPを優先し、rgと関連テストで補う。
• 既存テスト、公開API、型、文書化された挙動、不変条件から、変更で影響しうる入力、出力、失敗、副作用を書き出す。
• 仕様変更が必要なら、リファクタリングに混ぜず別の計画にする。既存の契約を守ることと、根拠のない互換shimを足すことは区別する。
• テストがない場合は、契約を観測できる代替の検証を書く。
• 範囲外の命名変更、依存追加、UI変更、テスト基盤の刷新、fallback追加は混ぜない。

[test]がある場合の進め方

1. ユーザーが示したケースどおりに、実装より先にテストを書く。
2. テストが期待どおりの理由（未実装、または不具合）で失敗することを確かめる。環境の不備、構文エラー、無関係な既存の失敗は、失敗の証拠にならない。最初から通るテストは条件を検証していない可能性があるので、ユーザーに伝える。
3. テストと受け入れ条件の対応を確かめてもらう。レベル1はreviewerサブエージェントに確かめさせて指摘を直し、レベル2はユーザーに確認してもらう。
4. 実装する。確認が済んだテストは変更しない。テストや仕様に誤りがあると判断したら、実装を止めて理由を報告する。テストを通すための特別扱いやassertの弱体化をしない。仕様を変えた場合は、テストを直してユーザーの承認を得る。

承認

ユーザーが提示した明確な小規模変更を契約に言い直しただけなら、同じ内容の再承認を求めない。こちらから新しい仕様、設計、UX、移行、互換性、変更範囲を提案した場合は、ユーザーの注釈をすべて反映してから承認済みとして実装に進む。