Spec

---
name: spec
description: "実装前に、受け入れ条件と確かめ方を決めた契約を作る。作業の重さがレベル1（短い契約）か2（仕様書）のとき、公開挙動を変えないリファクタリングの計画、受け入れテストを先に書くときに使う。'/spec'、'仕様書を書いて'、'仕様をまとめて'、'リファクタリングしたい'、'責務を分けたい'で使う。"
---

# 契約と仕様書

実装者が暗黙の仕様判断をせずに済む契約と実装境界を決める。レベル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、移行、互換性、変更範囲を提案した場合は、ユーザーの注釈をすべて反映してから承認済みとして実装に進む。