xp-harness: Skill for Claude Code

基本設計フェーズ

なぜこの 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