basic-design

basic-design: 基本設計書の作成・改訂

feature-spec と対をなす 基本設計書 1 本 を作る単機能スキル。成果物は docs/dev/<対象>/basic-design.md。仕様が「何を満たすか（REQ-#）」を定義するのに対し、 基本設計は 「どう実現するか」 を定義し、各機能を REQ-# へ紐づけて 要求に紐づかない機能 = スコープ外混入 を機械検出可能にする。

このスキルがやらないこと

• 実装しない。コードの作成・修正は範囲外。
• 仕様を書かない・改訂しない。要求の追加・変更が必要になったら /feature-spec <対象> の改訂モードへ回す（設計側で要求を勝手に足さない。それがスコープドリフトの発生源）。
• 詳細設計に踏み込みすぎない。クラス単位の内部実装・アルゴリズムの逐次手順は実装工程の 領分。基本設計は 境界（モジュール・インターフェース・データの流れ） までを確定させる。
• テスト成果物を作らない・直さない。docs/test/<対象>/ は testing スキル群の担当。

このスキルが従う原則

1. 単体動作（graceful degradation）

• 成果物の既定パスは docs/dev/<対象>/basic-design.md。
• プロジェクト側（CLAUDE.md / AGENTS.md 等）に成果物の配置規約があればそちらを優先する。
• 主入力: docs/dev/<対象>/spec.md（REQ-# を参照して機能一覧を導出する）。
• 任意入力（あれば整合を取るが、無くても成立する）:
  • docs/test/<対象>/test-analysis.md（テスト条件 TC-#。観測点・境界の洗い出しに使う）
  • docs/test/<対象>/test-case.md（テストケース CASE-#。設計が想定する入出力と突合する）
  • docs/dev/definition-of-done.md（完成の定義）
  • 任意のレビュードキュメント・ユーザーの直接指示
• spec.md が無くても作れる。ユーザーの直接指示・任意のレビュードキュメントを入力に 設計書を書いてよい。ただしその場合、機能一覧の「対応要求」列が - になり、 セルフ機械検査が「要求に紐づかない機能」として検出する。 先に /feature-spec <対象> を実行して仕様を確定させることを推奨する 旨を利用者へ伝え、 それでも進めるなら検査 NG が出ることを了解のうえで進める。

2. 調査優先 + 決定のみ質問

• 事実はリポジトリ調査で埋める。既存のモジュール構成・レイヤ分け・命名規約・ 依存の向き・公開契約は、利用者に訊く前に自分で調べる。既存構成に馴染む設計を出す。
• 利用者にしか決められない判断だけ を AskUserQuestion（推奨案を先頭）で確認する。 本スキルでは 設計方式の選択・既存構成を変えるか否か・分割の粒度・改訂提案の採否 が これに当たる。トレードオフのある選択は選択肢と代償を添えて訊く。
• 流れは 調査 → ドラフト提示 → 承認 → 規約パスへ書き込み。承認前に確定ファイルを書かない。

3. 記述品質

• 曖昧語（「適宜」「など」「柔軟に」「必要に応じて」）を設計文から排する。
• 略号・コードネームを定義なしで使わない。初出で正式名称・意味を併記する。
• インターフェースは 呼び出し側が実装なしで使える粒度 で書く（名前・入力・出力・ エラー時の振る舞い）。「よしなに返す」で終わらせない。

4. Progressive disclosure

• 本文は簡潔に保ち、雛形は references/ に置く。
• テンプレ: references/template.md（basic-design.md の雛形）。

機能一覧の REQ-# 契約（下流が依存する形式）

• 機能一覧は | 機能 | 対応要求 | 概要 | のテーブル で書く。
• 対応要求列に REQ-# を必ず書く。1 機能が複数要求にまたがるなら REQ-01/03 と併記する。
• 実在しない REQ-# を書かない（spec.md に無い ID は機械検査で検出される）。
• 要求に紐づかない機能を足さない。設計中に「これも要るのでは」と気づいたら、 勝手に足さず /feature-spec の改訂モードで要求として立てる ことを提案する。
• test-case.md があるときは CASE-# との対応が取れるかを確認する（機械検査も突合する）。

手順

引数は <対象名>。省略されたら docs/dev/ 配下の既存ディレクトリを一覧して選択を求める。

docs/dev/<対象>/basic-design.md の存在で 作成モード（無い）と 改訂モード（ある）に 分岐する。

作成モード

手順 1: 入力の確認

• docs/dev/<対象>/spec.md を読む。無ければ原則 1 に従い、/feature-spec の先行実行を 推奨したうえで、進めるかを利用者に確認する。
• 任意入力（test-analysis.md / test-case.md / definition-of-done.md）の有無を確認し、 あるものだけを読む。何を読んで何が無かったかを利用者へ 1 行で報告する。

手順 2: 既存構成の調査

リポジトリを調査して、設計の前提になる事実を集める:

• 既存のモジュール構成・レイヤ分け・ディレクトリ規約
• 依存の向き（どの層がどの層を呼んでよいか）と、既存の公開契約
• 新機能が差し込まれる接続点（拡張ポイント・既存のインターフェース）
• 既存の設定・データ書式（新しい書式を足すべきか、既存に乗るべきか）

手順 3: 機能一覧の導出

spec.md の REQ-# を 1 件ずつ辿り、実現に必要な機能へ分解してテーブルにする。

• 1 要求が複数機能に割れることも、複数要求が 1 機能に集約されることもある。 どちらでもよいが、対応要求列が空の行を作らない。
• 全 REQ-# が少なくとも 1 つの機能から参照されているかを確認する（要求の取りこぼし検出）。

手順 4: 設計の作成

references/template.md の構成でドラフトを作り、承認後に docs/dev/<対象>/basic-design.md へ書き込む。必須セクションは 機能一覧 / モジュール構成 / インターフェース / データフロー の 4 つ。

• モジュール構成: 新設・変更するモジュールと責務、依存の向き。既存構成との関係を明示する。
• インターフェース: 公開する関数・API・CLI 引数・ファイル書式・イベントの契約 （名前 / 入力 / 出力 / エラー時の振る舞い）。
• データフロー: 入力がどこから来てどう変換され、どこへ出るか。状態を持つなら どこが持つか。異常系の流れも書く。

手順 5: セルフ機械検査

後述の「セルフ機械検査」を実行し、NG があればその場で直してから完了宣言する。

改訂モード

既存の docs/dev/<対象>/basic-design.md を検出したら改訂モードに入る。

手順 1: 未反映の改善提案を収集

以下の入力源を横断して、まだ設計へ反映されていない 指摘・提案を集める。 入力源は疎結合で、どれか 1 つでもあれば成立する:

• docs/test/<対象>/ 配下のテスト成果物の「改善提案」セクション （test-design.md / test-analysis.md 等。設計の観測可能性・テスト容易性の指摘が集まる）
• docs/test/<対象>/test-review-*.md の「未解消の指摘」
• spec.md の改訂で増えた REQ-#（機能一覧に未反映のものが無いか突合する）
• ユーザーの直接指示・任意のレビュードキュメント

手順 2: 取捨選択

収集した提案を一覧で提示し、AskUserQuestion（推奨案を先頭）で採否を確認する。 各提案には「反映すると設計のどこが変わるか」（機能追加 / インターフェース変更 / モジュール移動）を添える。インターフェースの破壊的変更 はその旨を明示する。

手順 3: 反映

採用された提案だけを basic-design.md へ反映する。

• 機能を足すときは 必ず対応する REQ-# を確認する。対応要求が無い機能は反映せず、 /feature-spec <対象> の改訂モードで要求を立てることを提案する。
• spec.md から要求が消えている場合、それを参照する機能行は孤児になる。 機能ごと落とすか、要求を復活させるかを利用者に確認する。
• テスト成果物側の改善提案の 削除はしない（testing スキルの責務）。

手順 4: セルフ機械検査

作成モードと同じ（下記）。

セルフ機械検査

終了前に、test-review の決定論スクリプトを design-doc モードで自分に対して実行する。

<review-check.sh のパス> design-doc docs/dev/<対象> [docs/test/<対象>]

• 第 2 引数は開発ドキュメントのディレクトリ（docs/dev/<対象>）。
• 第 3 引数のテストドキュメントディレクトリは省略可（省略時は docs/dev/<対象> から docs/test/<対象> を自動導出する）。
• 検査内容: 必須セクションの存在 / 機能一覧の各項の REQ-# 参照必須と実在 / test-case.md があれば CASE-# との対応突合。

スクリプトの探索

次の順で探し、最初に見つかったものを使う:

1. 作業リポジトリ内の skills/testing/test-review/scripts/review-check.sh
2. install 済み testing-skills プラグインの同一パス （~/.claude/plugins/ 配下等。プラグインの配置は環境で変わるため実在確認をしてから使う）

どちらにも無ければ検査をスキップし、その旨を利用者へ明示する（例: 「review-check.sh が見つからないためセルフ機械検査をスキップした。testing-skills を install するか、/test-review <対象> design-doc で別途ゲートを通してほしい」）。 スクリプトの不在を理由に設計作成を失敗させない（原則 1: graceful degradation）。

NG が出たとき

NG は形式契約の違反であり事実なので、利用者判定を待たずにその場で直す。 ただし「対応要求が - の機能がある」NG は、要求側を足さないと直せない。この場合は 自分で要求を捏造せず、/feature-spec <対象> の実行を提案 して NG が残る旨を明示する。 SKIP（test-case.md が無い等）は問題ではない。

終了条件

以下を全て満たしたら 「<対象> の基本設計は完了」と明言 して閉じる。満たしていない項目が あれば、何が残っているかを列挙して先へ進めない。

1. 入力の有無を確認・報告済み（spec.md の有無、任意入力で読んだもの）。
2. docs/dev/<対象>/basic-design.md が規約パスへ書き込み済みで、必須 4 セクションを持つ。
3. 機能一覧の全行に対応要求（REQ-#）が入っている、または - が残る理由を利用者へ明示済み。
4. セルフ機械検査が NG ゼロ、または残る NG の理由・スクリプト不在によるスキップを 利用者へ明示済み。

完了後の次の一手として、以下を 提案するに留める（本スキルは実行しない）:

• 正式ゲート: /test-review <対象> design-doc
• テスト設計: /test-design <対象>
• 実装フェーズ: 基本設計と test-case.md から実装計画を組み立てる

用語

• 基本設計（basic design）: 要求を実現する構造（モジュール・インターフェース・データの流れ）を 確定させる工程。内部実装の詳細には踏み込まない。
• インターフェース（interface）: モジュール間の公開契約。名前・入力・出力・エラー時の振る舞い。
• スコープ外混入: 要求に紐づかない機能が設計に紛れ込む状態。機能一覧の REQ-# 参照必須で 機械検出する。