| name | teams-docs-design |
| description | Generate Design phase documents (non-functional requirements, domain modeling, ADR, specifications) in the teams/ directory. Phase 2 of the /start-teams-doc workflow. Requires Discovery phase approval. Use when creating design documents, ADRs, ER diagrams, or non-functional requirements. |
Teams Docs — Design スキル
トリガー条件
/teams-docs-design コマンドが呼ばれたとき/start-teams-doc の第2フェーズ（design フェーズ）として呼ばれたとき- ユーザーが「設計ドキュメントを作りたい」「ADRを作りたい」「非機能要件を定義したい」と言ったとき
入力パラメータ
/start-teams-doc から以下が引き渡される:
docs_root: ドキュメントルートパス（sdd-docs または .）team, project, feature, feature_id, goal, scope_in, scope_out- 任意:
constraints
実行前チェック
{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml を読み込むdiscovery.status != approved の場合は停止して Discovery フェーズの承認を促すdesign.status == changes_requested の場合は修正モードで実行design.status == in_review の場合はドキュメント生成をスキップし、構造バリデーションのみ再実行して承認確認メッセージに直接進む
手順
1. ディレクトリ準備
{docs_root}/teams/{team}/{project}/{feature}/design/
├── 非機能要件.md
├── モデリング.md
├── adr/
│ └── ADR-{NNN}-{概要}.md
└── spec/
└── {仕様タイトル}.md
1.5. 改修範囲の事前調査
_interview-notes.yaml の design-005 の回答に基づき、ドキュメント生成前にソースコードを重点的に調査する。
| 回答 | アクション |
|---|
| 具体的に把握している | ユーザーが指定したファイル・モジュール・テーブルを優先的に読み込み、関連する呼び出し元・依存先も探索する。調査結果をもとに spec・モデリングを作成する |
| おおまかに把握している | ユーザーが示した領域を起点に、Grep/Glob で関連コードを探索する。特定できたファイル群を読み込んでから spec・モデリングを作成する |
| 把握していない / 未回答 | PRD・ユーザーストーリーのキーワードをもとに広く探索する（従来動作） |
調査で得た情報（ファイルパス、既存の実装パターン、DB スキーマ、API 定義等）は、以降のステップで生成する各ドキュメントに具体的に反映すること。
2. 非機能要件.md 生成
3. モデリング.md 生成
4. spec/ 生成
- テンプレート: assets/spec-template.md
- US ごとに関連する spec ファイルを作成（複数 US をカバーしてよい）
- SPEC ID を
SPEC-{feature_id}-NNN 形式で採番
Related: [US-{feature_id}-NNN] を各ファイルに記入- システム境界・失敗モードを必ず記載
5. adr/ 生成（設計上の重要な決定がある場合）
- テンプレート: assets/adr-template.md
- ファイル名:
ADR-{NNN}-{概要}.md（概要は日本語可）
- Context / Decision / Consequences をすべて記入
- 代替案を最低1件記載
6. Traceability Matrix 更新
各ドキュメントの末尾 Matrix に US→SPEC/ADR の対応を記入する。
品質ゲート（承認前チェック）
references/quality-checklist.md の全項目を確認する。
Mermaid 構文エラーがある場合は修正する。
バリデーションスクリプトを実行して Mermaid 構文・必須セクション・ID 整合を自動チェックする:
python <this_skill_dir>/scripts/validate-mermaid.py <feature_dir>
<this_skill_dir> は、この SKILL.md が配置されているディレクトリの実際のパスに解決すること。
エラーが出た場合は修正してから承認確認を行う。
承認確認メッセージ
品質ゲート通過後、承認確認メッセージを表示する前に _approval-status.yaml の design.status を in_review に更新する。
これにより、ユーザーが承認確認中にセッションを中断しても、次回再開時にドキュメント生成をスキップできる。
✅ [design] フェーズの品質ゲートを通過しました。
承認しますか？
1. Approve & Continue（_approval-status.yaml を更新して完了）
2. Request Changes（修正点を確認して停止）
3. Pause Review（レビューを中断して後で再開）
承認時: _approval-status.yaml の design.status を approved、approved_at を本日付で更新する。
修正要求時: _approval-status.yaml の design.status を changes_requested に更新し、ユーザーが指摘した修正点の一覧を表示して停止する。
レビュー中断時: status は in_review のまま維持。以下を表示して停止する:
⏸️ [design] フェーズのレビューを中断しました。
`/start-teams-doc` で再開できます。
出力ファイル一覧
| ファイル | 必須 |
|---|
design/非機能要件.md | ✅ |
design/モデリング.md | ✅ |
design/spec/{タイトル}.md | ✅（最低1件） |
design/adr/ADR-{NNN}-{概要}.md | 設計判断がある場合 |
ソースコード参照
サブモジュールモード（docs_root = sdd-docs）の場合、ワークスペースルートにメインリポジトリのソースコードが存在する。以下を積極的に参照してドキュメントの精度を高めること:
- 既存の DB スキーマ定義・マイグレーションファイル → モデリング.md に反映
- API 定義（OpenAPI, GraphQL schema 等）→ spec に反映
- アーキテクチャ構成（ディレクトリ構造、DI 設定等）→ ADR の Context に反映
改修範囲が特定されている場合（ステップ 1.5 で調査済み）:
- 調査済みのファイル・モジュールの実装詳細を spec の「主要ロジック」「システム境界・外部I/F」に反映する
- 既存コードのエラーハンドリングパターンを spec の「失敗モード・エラーハンドリング」に反映する
- 既存のテーブル定義・リレーションをモデリング.md の ER 図・変更影響範囲に正確に反映する
Troubleshooting
- validate-mermaid.py が構文エラーを報告する → Mermaid ダイアグラムの括弧の対応（
{}, [], ()）を確認する。erDiagram, classDiagram 等のダイアグラムタイプ宣言が正しいかも確認する。
- SPEC に US への参照がない → spec ファイルの冒頭に
<!-- Related: [US-{feature_id}-NNN] --> ヘッダーを追加する。
- 非機能要件の閾値が未記入 → 各指標（可用性・応答時間・スループット等）に具体的な数値目標を記入する。「高い」「速い」等の定性的な表現は不可。
参照
