# SPEC 作成方法論: 要求書 / 判断軌跡

> `/beacon-spec` Skill の companion ドキュメント。MS 単位の SPEC を「要求書 / 判断軌跡」として書くための作法・対話パターン・チェックリストを集約する。

## 設計原則

### 0. SPEC = 要求書 / 判断軌跡 (詳細仕様書ではない)

CORE doc `doc-classification` を参照。要点:

- **書くこと**: 背景 / 解決すべき問題 / 設計方針 (判断軌跡) / スコープ / 受入条件 / 実装順序
- **書かないこと**: 詳細実装手順 (関数名・行数レベル) / API リファレンス / 長大なコード断片 / TODO リスト

判断の **理由** が残っていることが SPEC の価値。コードを読めば分かる情報は SPEC には書かない。

### 1. 対話駆動 (Socratic)

フォーム入力ではなく、ユーザーと対話しながらセクションを順に埋める。`/beacon-vision` の Existing モードや `/beacon-review-uc` と同じ作法。

理由:
- MS のオーナーはユーザー、AI は構造化と提案を担う
- ユーザーが「なぜこれをやるのか」を言語化する過程で、要求の解像度が上がる
- 一方的に AI が書くと、判断の根拠がユーザーの認識と乖離する

### 2. 起点材料の活用

SPEC を書き始める前に、必ず以下を読む:

| 材料 | コマンド / 場所 |
|---|---|
| プロジェクトビジョン | `beacon doc show project-vision` |
| 対象 MS の概要 | `beacon status --json --ms <ms-id>` |
| 関連 CORE doc | `beacon doc list --scope core --json` |
| 直近コミット | `git log --oneline -20` |
| 既存タスクの motivation/ac | `beacon task list --json --ms <ms-id>` |

これらから「なぜこの MS が必要か」の AI 仮説を立てて、ユーザーに提示する。

### 3. 推測は明示、ユーザーは精緻化

AI が起点材料から推測した内容は **「推測:」と明示** して提示し、ユーザーが訂正できる形にする。
ユーザーは認識訂正・優先度判断・スコープ調整を担う。

---

## SPEC の構造 (6 セクション)

### 1. 背景 / なぜこのMSが必要か

- このMSが作られた経緯 (どんな課題・発見・依頼から生まれたか)
- 現状の何が問題か (現状認識)
- このMSをやらないとどんな悪影響があるか (放置リスク)

**ヒント**: メタレビューや retrospection から派生したMSなら、その出典を明記する。

### 2. 解決すべき問題

- 1〜5 個の箇条書きで、対処したい事象を明確にする
- 既存タスク (entry-id) と紐づけられるとなお良い

### 3. 設計方針 (判断軌跡)

- 「こうする」と決めた指針と、**なぜそう決めたか**の理由
- 採用しなかった代替案があれば、却下理由を簡潔に
- 後から「あの判断はなぜ」を辿れることが本質

**ヒント**: 章立ては自由だが、各方針には必ず **理由 (Why)** を 1〜2 文添える。

### 4. スコープ

- **やる**: このMSで対処すること
- **やらない**: 混同されがちだが対象外のこと (別MS or 後回し)

「やらない」を明示することで、スコープクリープを防ぐ。

### 5. 受入条件 (Acceptance Criteria)

- どうなれば「完了」と言えるか、具体的な状態を箇条書きで
- 計測可能 or 観察可能な形が望ましい

### 6. 実装順序のヒント (任意)

- 依存関係 / 着手順の助言
- 「これを最初にやらないと他が決まらない」といったブロッカー

---

## 対話の進め方

### Phase 1: 起点提示 (AI 主導)

最初に AI が起点材料を読み、MS の概要と仮説を提示する:

```
ms-XX "[title]" の SPEC を作成します。

このMSの現状認識:
- (project-vision からの抜粋 or 関連 CORE doc 要約)
- (既存タスクから推測した、対処したい課題)

最初に確認したいのは「**背景・なぜこのMSが必要か**」です。
これがどんな課題・発見から生まれたMSか、教えてもらえますか？
推測:「[起点材料から推測した経緯]」 — 合っていますか？
```

### Phase 2: セクションを順に埋める

1問1答で、6セクションを順に対話する。**一度に複数質問しない**。

セクションごとの聞き方の例:

| セクション | 聞き方の例 |
|---|---|
| 背景 | 「このMSはどんなきっかけで生まれましたか？放置するとどう困りますか？」 |
| 問題 | 「対処したい具体的な事象を 1〜5 個に絞ると、どれですか？」 |
| 設計方針 | 「やり方として、どんな指針で進めますか？特に "こうはしない" と決めたことがあれば」 |
| スコープ | 「やる範囲を狭めるとしたら、どこを切りますか？混同されがちで対象外、というものは？」 |
| 受入条件 | 「どうなれば "完了" と言えますか？具体的な状態 / 観察できる事実で」 |
| 実装順序 | 「実装する順番に好みはありますか？最初にやらないと他が決まらない、というものは？」 |

### Phase 3: 確認フェーズ

6セクションが埋まったら、構造化された SPEC を **テキストとして** ユーザーに提示し、修正があれば受ける。
(`/beacon-vision` Step 4 と同じパターン)

### Phase 4: 書き込み + タスク一括起票

確認後、`beacon doc add --scope spec --ms <ms>` で記録。続けてタスク 3〜10 個に分割し、`beacon task add` で一括起票する (Step 詳細は Skill 本体参照)。

---

## タスク分割の基準

SPEC から task を起こすとき:

### 粒度
- 1 task = **1〜数日で消化できる単位**
- 1 task = **1 つの観察可能な成果** (コミット 1〜数本、PR 1 本程度)
- 細かすぎる (1 時間で終わる) もNG: 起票コストが上回る
- 粗すぎる (1〜2 週間かかる) もNG: 進捗が見えなくなる

### 各タスクに付与する情報

```bash
beacon task add "短い description" -m <ms-id> \
  --priority [highest|high|middle|low|lowest] \
  --motivation "なぜこの task が必要か (SPEC の問題項目と紐づける)" \
  --acceptance-criteria "完了の判定基準 (観察可能な事実 or 状態)"
```

### 優先度の付与基準

| 優先度 | 基準 |
|---|---|
| `highest` | これが止まると他が進まないブロッカー |
| `high` | SPEC の中核要件、欠けると受入条件を満たさない |
| `middle` | やるべきだが、後回し可能 |
| `low` | あると良いが、なくても本質を損なわない |

### タスクの並び順

SPEC の「実装順序のヒント」に従う。前提タスクが先、依存タスクが後。

---

## 良い SPEC / 悪い SPEC の例

### 良い例

```markdown
## 設計方針 (判断軌跡)

### 1. SPEC 無し MS は warning で促す (hard block しない)

- 理由: hard block すると緊急実装や試験運用が止まる。
- Beacon は監査の道具であって、強制力で動かす道具ではない。
- warning が出続けることで意識を促し、ユーザーが自発的に SPEC を整備するインセンティブを残す。

### 2. /beacon-spec は対話駆動の Skill にする

- フォーム入力ではなく Socratic 対話で 5〜6 セクションを埋める
- /beacon-vision の Existing モードと同じパターン
- 理由: MS のオーナーはユーザー、AI は構造化を担う分業を維持するため
```

判断の **理由** が残っているので、後から読んでも価値がある。

### 悪い例

```markdown
## 実装

1. `commands.py` の `cmd_milestone_add` に以下を追加:
   ```python
   def fire_spec_trigger(ms_id):
       trigger_path = ...
       with open(trigger_path, "w") as f:
           json.dump({"ms_id": ms_id}, f)
   ```
2. `bin/beacon` の `cmd_milestone_add` で `fire_spec_trigger($ms_id)` を呼ぶ
```

これは詳細仕様書。コードを読めば分かる情報を二重管理しているだけ。判断の理由が欠落しているため、SPEC の価値がない。

---

## チェックリスト (書き上げ後の自己レビュー)

- [ ] 6 セクションすべてが埋まっているか
- [ ] 各設計方針に **理由 (Why)** が 1〜2 文添えられているか
- [ ] スコープに「やらない」が含まれているか
- [ ] 受入条件が観察可能 / 計測可能な形か
- [ ] 詳細実装 (関数名・行数レベル) が混入していないか
- [ ] 既存 CORE doc / 関連 MS への参照があるか
- [ ] task 一括起票につながる粒度になっているか (タスク分割可能か)

---

## 関連

- CORE doc:
  - `doc-classification` Beacon ドキュメント分類 (本 methodology の上位定義)
  - `1IEownAgdmnOeQR1qLSq` Beacon の本質 (SPEC = 作業記憶)
  - `memory-vs-agent-layer` メモリ層とエージェント層の分離
- 関連 Skill:
  - `/beacon-vision` Socratic 対話のパターン (Existing モード)
  - `/beacon-review-uc` ペルソナ駆動レビューの対話パターン
  - `/beacon-task` task 操作の CLI ラッパー
