basic-design

---
name: basic-design
description: spec.md の REQ-# を入力に、機能一覧・モジュール構成・インターフェース・データフローを持つ docs/dev/<対象>/basic-design.md を作成・改訂するスキル。/basic-design <対象名> で明示的に呼び出されたときのみ使用する。
license: MIT
disable-model-invocation: true
user-invocable: true
argument-hint: "[対象名]"
---

# 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`](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`](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` モードで自分に対して実行する。

```sh
<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-#` 参照必須で
  機械検出する。

• SKILL.md 13 KB
• references/template.md 3 KB