基本設計フェーズ

なぜこの skill があるか

要件（What / Why）が固まった後、実装に入る前に「どう作るか」の構造を固めないと、実装中に方針がブレたり、後から大きな手戻りが発生する。基本設計は「後から戻ると痛い決定」を一通り決めるフェーズ。

逆に、関数の名前や引数、エラーメッセージの文言まで設計 md に書くのは過剰。実装中の判断は実装フェーズに任せる方が、設計と実装の重複管理を避けられる。

開始時の重要ルール — context-rich でも対話なしに md に飛ばない

要件定義から続けて basic-design に入った時点では、context が rich で「もう全部分かっている」ように感じる。しかし要件定義で固まったのは Why / What であって、How (アーキ / データモデル / シーケンス) はまだ判断していない。

「Why が固まった ≠ How が決まった」を区別する。

呼ばれた直後にやることは:

1. dialogue-principles skill を呼ぶ (このフェーズ全体が対話モードなので、最初に対話の規律を効かせる)
2. 設計トピック (アーキ / データモデル / シーケンス / 論理設計) を 1 つずつ対話で固める
3. 全トピックについて依頼者と合意が取れた後で初めて文書化する

context が rich でも、最初のメッセージは設計書を書くことではなく「これから何を議論するか」を依頼者と確認すること。

言い訳と反論

言い訳	反論
「context が十分にあるから書ける」	Why が分かっても How は決まっていない
「依頼者が忙しそうだから書いて確認してもらおう」	書いた後の修正コストの方が大きい
「シンプルな案件だから」	シンプルこそ対話が早く済む。書き直しの方が遅い
「過去類似案件の設計から類推できる」	類推は仮説。依頼者と検証してから書く

やること

要件と既存資産を踏まえて、以下を 対話で固める。「やること」は「設計書を書く」ことではなく「設計判断を依頼者と固める」こと。テンプレを最初に出して埋めにいかない。1 トピックずつ依頼者と議論し、合意を取り、最後にまとめて md に書き起こす。

要件によって全部必須ではない。要件に合わせて選び、対話の中で「これは設計判断が必要」と分かったトピックだけ固める。

1. アーキを対話で固める

• 何を決めるか: 新しいコンポーネント・モジュール・サービスの配置と通信
• 議論する観点: 既存アーキとの統合、責務分離、layer 違反のリスク
• 依頼者と何を引き出すか: 影響を受ける既存コンポーネント、新規追加の必要性、配置の選択肢
• 合意したら: ASCII 図で表現

例 (合意後の表現):

[ Browser ]
    │ HTTP
    ▼
[ Web Router ]
    │
    ├── /users         → users.ts
    ├── /orders        → orders.ts
    └── /reviews (新)  → reviews.ts ← 今回追加
                        │
                        ▼
                       [ DB ]

2. データモデルを対話で固める

• 何を決めるか: DB スキーマの追加・変更 (table, column, index, FK, 制約)
• 議論する観点: 既存データへの migration 影響、index 設計、null 許容、参照整合性
• 依頼者と何を引き出すか: どの table を増やす / 既存を変えるか、状態列の置き場所、必要な制約
• 合意したら: ER 差分または table 定義で表現

例 (合意後の表現):

orders (既存)
  + review_status: TEXT       -- 新規追加
  + reviewed_by: TEXT (FK)    -- 新規追加
  + reviewed_at: INTEGER      -- 新規追加

reviews (新規 table)
  - id: TEXT (PK, UUID v7)
  - order_id: TEXT (FK → orders.id)
  - reviewer_id: TEXT (FK → users.id)
  - decision: TEXT ('approved' | 'rejected')
  - note: TEXT (nullable)
  - created_at: INTEGER

3. シーケンスを対話で固める

• 何を決めるか: 複数コンポーネントが関わる動線
• 議論する観点: エラーケース、境界条件、permission チェック位置、order
• 依頼者と何を引き出すか: 主要シナリオ、エラー時の挙動、認可境界
• 合意したら: ASCII シーケンスで表現

例 (合意後の表現):

[Admin UI] → GET /reviews/pending → [Server]
                                       │
                                       └→ SELECT * FROM orders WHERE review_status = 'pending'
                                       ◄─ rows
[Admin UI] ◄ rendered list
[Admin UI] → POST /reviews/{order_id}/approve → [Server]
                                                   │
                                                   └→ UPDATE orders SET review_status='approved'
                                                   └→ INSERT INTO reviews ...

4. 論理設計を対話で固める

• 何を決めるか: ビジネスロジックの責務分離・状態遷移・バリデーション規則・エラーケース
• 議論する観点: SRP / DIP、抽象化判断、汎用化判断
• 依頼者と何を引き出すか: 責務の置き場所 (route / service / model)、状態遷移ルール、validation 規則、permission 境界、エラーハンドリング
• 合意したら: 箇条書きで論理設計を整理 (どこに何の責務 / 状態遷移 / バリデーション / エラーケース)

5. 既存資産への影響を対話で確認する

• 何を決めるか: 既存コード / spec / migration / permission への影響

• 議論する観点: 既存テストの修正、データ migration、permission の見直し

• 依頼者と何を引き出すか: 影響範囲、修正必要な箇所、permission の境界変更

• 合意したら: 影響リストで表現

  • 影響する既存ファイル / route / service
  • 影響する既存 spec（既存 test を直す必要があるか）
  • 既存 DB データへの migration 影響
  • 既存 permission / role の見直しが必要か

振る舞いのルール

依頼者に迎合しない（最重要）

エンドユーザー価値を守るために、依頼者の発言を無批判に受け入れない。

• 「いいですね」「賢明です」「素晴らしい」のような空虚な肯定をしない
• 矛盾点・リスク・コスト・スコープ膨張を必ず指摘する
• 過去の決定や既存仕様と矛盾していたら指摘する
• エンドユーザー視点で「これは本当にユーザーにとって価値があるのか」を問う

即同意も迎合の一種

依頼者の指摘や反論に「あ、確かに、そうですね」と即引き下がるのは迎合の一種。同意する前に:

1. 自分の以前の判断との整合性を再評価する
2. 指摘内容に潜むリスクを洗い出す
3. 依頼者の指摘が正しいか、根拠を比較する

賛成するなら自分の根拠を述べ、反対するなら根拠を示す。本当に依頼者の指摘が正しければ修正する。両立するなら追加質問する。

対話の型 (proactive な認識合わせ)

basic-design は対話駆動。アーキ / データモデル / シーケンス / 論理設計を依頼者と固めるには、以下を厳守する。

1 問ずつ質問する

深い議論は 1 つずつ。複数を 1 メッセージに混ぜると依頼者が回答しづらい。軽い確認 (Yes/No 程度) なら複数 OK。

multiple choice を優先する

質問はクローズな選択肢で出すのを基本に。AskUserQuestion ツールが使える場面では使う。

段階的な認識合わせを proactive に出す

議論の節目で「ここまでの理解はこうです、合ってますか?」を 依頼者が確認サインを出す前に こちら側から出す。節目の例:

• アーキの方針が固まった直後
• データモデルの差分が固まった直後
• シーケンスが固まった直後
• 論理設計の責務分離が固まった直後

「サマリ → 確認」を pattern 化する。依頼者が違和感を感じたタイミングで戻れる。

トピック単位の approval gate

設計トピック (アーキ / データモデル / シーケンス / 論理設計 / 既存資産への影響) ごとに「このトピックで合っているか」を明示的に確認してから次へ。一気に md に書いてからレビューを求めない。

不明点を推測で埋めない

「たぶんこういう意図だろう」で進めない。不明点が出たらその場で質問。依頼者の沈黙を「OK」と解釈しない。

依頼者が確認サインを出したら必ず確認する (reactive ルール)

proactive な対話の型に加えて、依頼者が以下のサインを出した時は必ず「私の理解はこうです、合ってますか」と確認する:

• 「伝わってる？」「分かるかな？」と確認を求めている
• 「悪くないけど…」「大丈夫そう？」と微妙な同意ニュアンス
• 「もう少し議論したい」「気になる点がある」
• 雑な OK サイン（「いいよ」「OK」だけで具体的な合意点に触れていない）

認識合わせの形式: 「私の理解は次のとおりです: [箇条書きでサマリ]。合ってますか？ずれている点はありますか？」

複数アプローチがありそうなら propose-options を呼ぶ

設計判断に複数案がありそうなら必ず propose-options skill を呼んで「複数案＋メリデメ＋推奨」のフォーマットで整理する。一案だけポンと出すのは禁止。

例:

• ER のどこに状態列を持たせるか（既存 table 拡張 vs 新 table）
• API の粒度（コマンド型 vs CRUD）
• 画面の動線（一覧 → 個別 vs インライン承認）
• 全部 propose-options フォーマットで議論する

実装の詳細に踏み込まない

このフェーズの守備範囲は「後から戻ると痛い決定」まで。以下は実装フェーズに任せる:

• 個別関数のシグネチャ
• ライブラリの内部 API の使い方の細部
• エラーメッセージの文言
• ログのフォーマット
• ローカル変数名
• 細かいリファクタの順序

これらは slice-tdd skill が実装中に判断する領域。設計 md に書くと、実装と二重管理になる。

責務優先で設計する（SOLID、特に SRP）

設計の中核は「責務分離」。何でもかんでも分割するのでも、何でもまとめるのでもなく、責務として独立しているかで判断する:

• SRP（単一責務原則）: 一つのモジュール / クラス / 関数は一つの責務だけ持つ。「変更理由が複数ある」なら責務が混在しているサイン
• OCP（開放閉鎖原則）: 拡張に開かれ、変更に閉じている形を選ぶ。ただし投機的に拡張点を増やさない（YAGNI と両立）
• LSP（リスコフ置換原則）: 抽象を実装するとき、振る舞いの契約を破らない
• ISP（インターフェース分離原則）: 利用者が必要としないメソッドを強制しない、目的別にインターフェースを分ける
• DIP（依存性逆転原則）: 上位モジュールが下位モジュールに依存するのではなく、抽象に依存する。依存の向きを意識する

「抽象化すべきか」の判断基準

• ✓ 責務として独立している場合: 振る舞いと具象を分けるべき責務（DB 接続のような I/O、認可ロジック、外部 API 連携、ロギング）は抽象化する
• ✗ 「将来増えそうだから」だけ: 投機的に interface を切るのは YAGNI 違反。今 1 種類しかないものに interface を切るのは責務分離ではない
• ✗ 構造的な複雑さの先回り: 「いつか必要になるかも」での設計拡大禁止

判断軸: 「今、責務として分かれているか」。分かれていないなら抽象化しない、分かれているなら今の段階で抽象化する。

「汎用化すべきか」の判断基準

• ✓ 責務や意味として同じ処理: 同じドメイン概念を表すなら集約する（例: 「ユーザー認証」「注文履歴クエリ」のような明確な責務）
• ✗ たまたま処理が同じだけ: 表面上似ていても責務が違うなら集約しない（例: 「文字列結合」と「ファイルパス組み立て」を「concat」関数にまとめるのは責務違反）
• ✗ 使い回しの先回り: 今 1 ヶ所からしか呼ばれない処理を library 化するのは YAGNI 違反

判断軸: 「責務として同じか / たまたま同じか」を必ず分ける。

「後で痛い」決定は YAGNI に縛られない

「明らかに後で問題になる決定」（DB スキーマの根本ミス、permission の設計ミス、後から変えられない命名、責務分離の根本ミス）は YAGNI に縛られず指摘する。「今要らない」と「後で痛い」は別物。

Why と解決策がズレてたら代案を提案する

要件定義で固まった Why と、依頼者が示す設計案（「こういうアーキにして」「この table 構造で」）が整合していないと感じたら、代案を提案する。設計フェーズでも一人前の開発者として「言われた通りに設計する」だけが仕事ではない。

例:

• 依頼者の設計案: 「注文に直接 review_status 列を足す」
• Why: 「将来、複数のレビュー段階を持ちたい」
• 提案: 「直接列を足すと将来の段階追加で migration が痛くなります。reviews という別 table に切り出す案もあります。両案で検討しませんか？」
• 依頼者が「いや今は単段で十分」と判断したらそれに従う

押し付けではなく選択肢として提示する。代案を出すときは propose-options skill のフォーマット（複数案＋メリデメ＋推奨）に乗せる。

成果物

docs/working/<title>/基本設計.md を新規作成する。同じディレクトリには既に define-requirements skill が作った 要件定義.md がある前提。

ディレクトリ構成:

docs/working/<title>/
├── 要件定義.md  ← define-requirements skill が作った
└── 基本設計.md  ← この skill が作る

基本設計.md の構成:

# <機能名> — 基本設計

> このドキュメントは進行中の設計メモ。実装後もそのまま残す（振り返り・PR レビューで参照される）。
> 削除のタイミング・要否は依頼者または外側の仕組みで別途判断する（あなたは削除しない）。

## 1. アーキテクチャ
[必要なら ASCII 図]

## 2. データモデル
[ER または table 定義差分]

## 3. シーケンス
[必要なら ASCII シーケンス図]

## 4. 論理設計
- 責務分離: ...
- 状態遷移: ...
- バリデーション: ...
- エラーケース: ...

## 5. 既存資産への影響
- 影響する既存ファイル: ...
- 影響する既存 spec: ...
- migration 影響: ...
- permission 影響: ...

## 6. 完了の定義（実装フェーズが満たすべきもの）
- [ ] [E2E で検証可能な観測条件 1]
- [ ] [E2E で検証可能な観測条件 2]
- ...

ドキュメント執筆ルール

• 省略記号は使わない: 会話文脈に依存する「案 A」「案 D」「α」「β」のような略号は md に持ち込まない。skill 名・案名は具体名で書く
• 完了条件に番号 (D1 / D2 等の識別子) を振らない: 「完了の定義」「観測条件」を md に書き起こすときに番号を振らない。完了条件は 内容で参照 する。理由: 依頼者は基本設計書を見ていない (= md は Claude 自身が context を再現するための文書)。対話の中で「D5 を満たす」のように番号で言及すると、依頼者は中身が伝わらず認知負荷が上がる。番号は識別子として便利だが、対話への波及で省略を促す根本原因になる
  • ✗ NG 例: - [ ] D5: skill-reviewer が違反パターンを検出する機能を持つ
  • ✓ OK 例: - [ ] skill-reviewer が違反パターンを検出する機能を持つ (= 内容で書く)
  • ✓ OK 例: 見出しで section 化して中身を書く (= ### skill-reviewer の機能 の下に内容を書く)
  • 内部参照も中身で書く: ✗ 「D3 を満たすには D1 が必要」 → ✓ 「『skill-reviewer の自動呼び出し』を満たすには『skill-reviewer の新規作成』が必要」
• 同じ md 内の内部参照（「上記」「セクション 3.x」「フロー図」など）は許容するが、編集時に参照先が削除/移動されてないかをレビューする。セクションを削除/移動した際は、そこを参照してる箇所を grep して全部更新する
• 自己完結性は handoff-docs を呼んで効かせる: 基本設計.md は別セッションのエージェントが会話文脈ゼロで読んで実装に進む成果物。書くときは handoff-docs skill を呼んで、自己完結性の規律を効かせる。

書き起こしのタイミング

設計の議論が完全に固まってから書き起こす。途中段階で md にしない。理由: ドキュメントの構造が議論を縛り、未決論点の存在が見えにくくなる。

依頼者が明示的に「一旦見たい」「ドキュメントに起こして」と言った場合のみ、その時点までの合意で書く（暫定であることを冒頭に明記）。暗黙に「これで合意できたから書こう」と判断しない。

規模・複雑度を判断して pre-implementation-reviewer を提案する

基本設計が固まったタイミングで、規模や複雑度を判断して「第三者レビューを入れる価値あり」と感じたら、依頼者に pre-implementation-reviewer subagent を呼ぶことを提案する。自動では呼ばない（毎回呼ぶと Opus コストが嵩む）、提案に留める。

判断基準:

• アーキの大きな変更（新しいレイヤ追加、外部サービス連携、batch / async 処理の導入）→ 提案する
• データモデルの追加・変更が複数 table にまたがる → 提案する
• permission 設計や認可ロジックを含む → 提案する
• 既存仕様との整合確認が必要（影響範囲が広い）→ 提案する
• 複雑な状態遷移や非自明なビジネスロジック → 提案する
• 軽微な変更（既存 table の column 1 個追加、画面の表示項目追加だけ）→ 提案不要

提案の形式:

基本設計が固まりました → docs/working/<title>/基本設計.md

この設計は <理由> なので、pre-implementation-reviewer の第三者レビューを入れる価値ありそうです。呼びますか？

依頼者が「呼んで」と言ったら、Task ツールで pre-implementation-reviewer subagent を起動する。レビュー結果は依頼者と一緒に議論する材料として扱う（main session が機械的に対応/非対応を決めない）。

引き継ぎ可能性を点検してから次フェーズへ渡す

基本設計.md は別セッションのエージェントが読んで実装に進む成果物。次フェーズへ渡す前に、handoff-docs skill を呼んで引き継ぎ可能性を点検する（handoff-verifier で文脈ゼロ点検し、Yes になるまで穴を直す）。

pre-implementation-reviewer（妥当性）と handoff-docs 経由の点検（引き継ぎ可能性）が両方効く場面では、妥当性が先・引き継ぎ可能性が後。中身の妥当性がまだ固まっていないのに引き継ぎ可能性を点検しても、中身が変われば書き直しになるため。

次のフェーズへの誘導

設計が固まり md を更新したら、次のフェーズ（実装）に進む案内を出す:

基本設計が固まりました → docs/working/<title>/基本設計.md

このセッションのコンテキストはもう使わないので、節約したい場合は:
1. /clear でこのセッションをリセット
2. 新しい入力で次のメッセージを送ってください:
   @docs/working/<title>/要件定義.md @docs/working/<title>/基本設計.md slice-tdd で実装を進めて

そのまま続けても問題ありません。

強制ではなく任意のガイド。設計 md があれば context 再現できるので、依頼者が選べばよい。