SDD ドキュメンテーションスキル

ソフトウェア設計ドキュメント（SDD）の作成・管理・実装を統括するオーケストレータースキルです。

既定の記録先が変わりました。

対象	既定の記録先	旧サブスキル
要求・ユーザーストーリー・理由	requirement-management（docs/requirements/*.yaml）	requirements-defining（非推奨）
設計	PR本文とGitHubコメント（永続化しない）	software-designing（非推奨）
要求の整合性チェック	reqctl.py validate	sdd-document-management（非推奨）
タスク	GitHub Issue（label:sdd:task）	変更なし

非推奨サブスキルは、既存の docs/sdd/ を保守・参照する場合にのみ使用します。移行手順は sdd/requirement-management/references/migration_from_sdd_ja.md を参照してください。

実行原則（タイムアウト防止）

スキルが長時間応答しない問題を防止するため、以下のルールを厳守すること。

1フェーズ1応答の原則

オーケストレーターは1つのサブスキル工程を完了するごとに、必ずユーザーに結果を報告して応答を返すこと。複数のサブスキルを連続実行してはならない。

禁止パターン（タイムアウトの原因）:
  スキル呼び出し → requirements作成 → design作成 → tasks作成 → ... → 40分以上無応答

必須パターン:
  スキル呼び出し → requirements作成 → ユーザーに報告・確認待ち
  ユーザー承認   → design作成     → ユーザーに報告・確認待ち
  ユーザー承認   → tasks作成      → ユーザーに報告・確認待ち

テンプレート・リファレンスの遅延読み込み

• 事前に全ファイルを読み込まない: 使用するテンプレートのみ、使用する直前に1つずつ読み込む
• リファレンスは必要時のみ参照: 詳細ガイドは問題発生時や判断に迷った時にのみ読み込む

禁止: 19個のテンプレートと19個のリファレンスを一括読み込み
必須: 「今からrequirements/index.mdを作成する」→ その時点でindex用テンプレートのみ読み込む

並列処理判定の適用タイミング

• ドキュメント作成フェーズ（requirements/design/tasks）: 並列処理判定は不要。順次作成する
• タスク実行フェーズ: タスク特定後に並列処理判定を実施（Agent tool + worktree）
• トラブルシューティング: 原因候補列挙後に並列処理判定を実施（Agent tool）
• ドキュメント管理フルスキャン: 5機能をAgent tool + worktreeで並列実行

進捗の可視化

各サブスキル実行中は、処理ステップをユーザーに出力して進捗を可視化すること。

出力例:
  [requirement-management] ステップ 1/6: 入力要件を読み込み中...
  [requirement-management] ステップ 2/6: 情報を分類中（明示/不明）...
  [requirement-management] ステップ 3/6: 既存要求との衝突を確認中...
  [requirement-management] ステップ 4/6: 要求とストーリーをYAMLに追記中...
  [requirement-management] ステップ 5/6: validate で検査中...
  [requirement-management] 完了: 要求5件を追加、エラー0件

情報分類の段階的処理

ユーザーからの入力が長文の場合、情報分類を一括で行わず段階的に処理すること。

禁止: 長文入力を一度に全て分類（LLMへの単一リクエストが重くなりハングの原因）

必須: 段階的に分類
  Phase 1: 必須情報のみ確認（プロジェクト名、目的、対象ユーザー）
  Phase 2: 機能要件の整理
  Phase 3: 非機能要件の整理

フォールバック戦略

スキルが正常に動作しない場合（長時間応答なし、エラー等）の代替手段を明確にしておくこと。

フォールバック手順:
  1. スキル実行を中断
  2. テンプレートファイルを直接参照:
     - requirements: requirement-management/assets/templates/
     - tasks: task-planning/assets/templates/
  3. Writeツールでテンプレートに基づきドキュメントを手動作成
  4. 作成後にチェックリストで品質確認

スキルの代わりにテンプレートを直接使用する手動作成は、スキル経由と同等の品質を達成できる。実績として手動作成は約5分で完了する。

概要

このスキルは、以下のサブスキルを連携させて、要求管理から実装・メンテナンスまでの全工程を管理します（先頭4件が現行、残り3件は非推奨）：

サブスキル	役割	成果物
requirement-management	要求・ストーリー・理由の管理と矛盾の機械検証	docs/requirements/
requirements-defining（非推奨）	EARS記法による要件定義	docs/sdd/requirements/（保守のみ）
software-designing（非推奨）	技術アーキテクチャ設計	docs/sdd/design/（保守のみ）。今後の設計はPR本文へ
task-planning	AIエージェント向けタスク分解	GitHub Issue（デフォルト） / docs/sdd/tasks/（オプション）
task-executing	タスク実行・逆順レビュー	実装コード
sdd-troubleshooting	問題分析・修正方針策定	docs/sdd/troubleshooting/, GitHub Issue（修正タスク）
sdd-document-management（非推奨）	ドキュメント管理・メンテナンス	docs/sdd/archive/, docs/sdd/reports/（保守のみ）

タスクの出力先（重要）: タスクはデフォルトでGitHub Issueとして起票する（1タスク＝1 Issue、詳細はIssue本文に集約、label:sdd:task で一覧＝目次）。ユーザーが「ファイルで管理」を明示した場合のみ docs/sdd/tasks/ にファイル生成する。詳細は task-planning/SKILL.md を参照。

ドキュメント構成

docs/sdd/
├── requirements/           # 要件定義
│   ├── index.md           # 目次・概要
│   ├── stories/US-XXX.md  # ユーザーストーリー詳細
│   └── nfr/*.md           # 非機能要件
├── design/                # 設計
│   ├── index.md           # 目次・アーキテクチャ概要
│   ├── components/*.md    # コンポーネント詳細
│   ├── api/*.md           # API設計詳細
│   ├── database/schema.md # データベーススキーマ
│   └── decisions/DEC-XXX.md # 技術的決定事項
├── tasks/                 # タスク管理（ファイルモード＝オプション時のみ）
│   ├── index.md           # 目次・進捗サマリ
│   └── phase-N/TASK-XXX.md # タスク詳細
│                          # ※デフォルトはGitHub Issue起票（このディレクトリは作成しない）
├── troubleshooting/       # トラブルシューティング
│   └── [YYYY-MM-DD]-[issue-name]/
├── archive/               # アーカイブ（完了済み）
│   ├── tasks/             # 完了済みタスク
│   ├── decisions/         # 古い決定事項
│   └── troubleshooting/   # 完了した問題分析
└── reports/               # 管理レポート
    ├── consistency/       # 整合性チェックレポート
    ├── sync/              # 実装同期チェックレポート
    ├── archive/           # アーカイブレポート
    └── optimize/          # 最適化レポート

このスキルを使用する場面

一括初期化

• 新規プロジェクトでSDDドキュメント一式が必要な場合

全体管理

• 3つのドキュメント間の整合性を確認したい場合
• 逆順レビュー（実装 → タスク → 要求）を実施したい場合

実装フェーズ

• docs/sdd/tasks/に沿って実装を行う場合
• 実装後の逆順レビューが必要な場合

トラブルシューティング・デバッグ（必須）

以下の状況では、必ずsdd-troubleshootingサブスキルを使用してください：

• テストエラー - テストが失敗した場合（原因分析が必須）
• ビルドエラー - コンパイルエラー、型エラーが発生した場合
• 実行時エラー - 例外、クラッシュ、異常終了が発生した場合
• 動作不良 - 期待と異なる動作をしている場合
• バグ報告 - ユーザーからバグが報告された場合

重要: 修正コードを書く前に、必ず根本原因を分析してください。推測に基づく修正は禁止です。

ドキュメント管理

• ドキュメント間の矛盾を検出・解消したい場合
• 実装とドキュメントの同期を確認したい場合
• 完了済みタスクをアーカイブしたい場合
• 肥大化したファイルを整理したい場合

個別作業が必要な場合

特定の工程のみ実施する場合は、各サブスキルを直接使用：

• 要求の追加・変更・廃止のみ → requirement-management
• タスク計画のみ → task-planning
• 実装のみ → task-executing
• 問題分析のみ → sdd-troubleshooting
• 設計のみ → スキルは使わない。実装時にPR本文へ設計ノートを書く
• 既存 docs/sdd/ の保守のみ → 非推奨サブスキル（requirements-defining / software-designing / sdd-document-management）

ワークフロー

新規開発フロー

重要: 各ステップ完了後に必ずユーザーに結果を報告し、承認を得てから次のステップに進むこと。

1. 初期化 → docs/sdd/ディレクトリ構造を作成
      ↓ ★ ユーザーに報告 ★
2. requirement-management → docs/requirements/（要求・ストーリー・理由）
      ↓ ★ ユーザーに結果を提示・承認待ち ★（ここで応答を返す）
3. 設計はここでは作らない（実装時にPR本文へ記載する）
      ↓
4. task-planning → GitHub Issue起票（デフォルト） / docs/sdd/tasks/（オプション）
      ↓ ★ ユーザーに結果（起票Issue番号一覧）を提示・承認待ち ★（ここで応答を返す）
5. 実行モード判定: Jules API / Agent tool並列処理（タスク実行フェーズのみ）
      ↓
6. ドキュメント逆順レビュー
      ↓ ★ ユーザーに結果を提示・承認待ち ★（ここで応答を返す）
7. task-executing → 実装コード
      ↓ ★ ユーザーに結果を提示 ★（ここで応答を返す）
8. 実装逆順レビュー → 完了

各ステップの所要時間目安: 1ステップあたり3-10分。10分を超える場合は作業が肥大化している可能性があるため、スコープを見直すこと。

並列処理判定基準

注意: 並列処理判定はタスク実行フェーズ（ステップ5）でのみ実施する。ドキュメント作成フェーズ（ステップ1-4）では判定不要。

判定条件:

1. 並列実行可能なタスクが2つ以上ある
2. タスク間に依存関係がない（同一グループ内）
3. 同一ファイルを変更する可能性が低い（高い場合は統合時コンフリクト多発のため順次実行を推奨）

• すべてYES → Agent tool（isolation: worktree）で並列実行
• いずれかNO → 単一セッションで順次実行

方式: Agent toolのisolation: worktreeを使用し、各サブエージェントが独立したgit worktreeで動作。並行作業中の上書き衝突を防止できるが、統合時にマージコンフリクトが発生し得るため必要に応じて手動解決する。

並列処理パターンと呼び出し例: references/agent_teams_guide_ja.md

タスク実行モード判定（Jules API統合）

Jules API（JULES_API_KEY）が利用可能な場合のモード判定とアサイン戦略の詳細は task-executing/references/jules_integration_ja.md を参照。

トラブルシューティングフロー（デバッグ・エラー修正時は必須）

エラーやバグに遭遇したら、このフローに従ってください。修正コードを先に書くことは禁止です。

エラー/バグ発生
      ↓
┌─────────────────────────────────────────────────┐
│ ⚠️ 禁止: 推測で修正、原因不明のまま修正          │
└─────────────────────────────────────────────────┘
      ↓
1. 問題事象の確認（エラーメッセージ、再現手順、期待動作）
      ↓
2. 根本原因の分析（コードを追跡して原因を特定）
      ↓
3. 仕様との照合（docs/sdd/requirements/, docs/sdd/design/）
      ↓
4. 修正方針の策定（どう直すか、影響範囲は）
      ↓
5. ★ ユーザー承認 ★（必須ゲート - 承認なしで実装禁止）
      ↓
6. タスク分割 → GitHub Issue起票（ラベル `sdd:task` + `sdd:bugfix`）※デフォルト
      ↓
7. task-executing → 修正実装

ドキュメント初期化

「docsディレクトリを初期化してください」と依頼されたら：

1. ディレクトリ構造の作成
2. docs/requirements/ - requirement-management の初期化手順に従い、glossary.yaml と <ドメイン>.yaml を作成する
3. design/: 作成しない。設計は実装時にPR本文へ記載する
4. タスク: デフォルトはGitHub Issue起票のため tasks/ は作成しない。ファイルモード（オプション）指定時のみ tasks/index.md を作成 - テンプレート: task-planning/assets/templates/tasks_index_template_ja.md

逆順レビュープロセス

docs/sdd/tasks/ → docs/sdd/design/ → docs/sdd/requirements/

詳細なチェック項目は references/checklist_ja.md を参照。

EARS記法

詳細は requirements-defining/references/ears_notation_ja.md を参照（同スキルは非推奨だが、EARS記法のリファレンスとしては引き続き有効）。

自律実行モード（orchestrating-agents連携）

複数フェーズを自律的に実行する場合は、orchestrating-agents スキルの3階層エージェント構造を活用する。

事前確認（明示情報 / 不明情報）

自律実行モード開始前に以下を分類する:

• 明示情報: ユーザーが指定した対象フェーズ・成果物・制約
• 不明情報: 受入基準、優先順位、停止条件、並列化可否の根拠

不明情報がある場合は、実行を開始せずユーザーに確認してから進行する。

• 親（Director）がSDDワークフロー全体を管理
• 子（Manager）が各フェーズ（requirements/design/tasks/executing）を担当
• 孫（Worker）が個別タスクを並列実行（task-executingフェーズのみ）

詳細: orchestrating-agents/SKILL.md

SDDスキルへの適用マッピング

サブスキル	階層モード	理由
requirement-management	2階層	単一作業、並列化不要
task-planning	2階層	同上
task-executing	3階層	複数タスクの並列実行が可能
sdd-troubleshooting	条件分岐	仮説3つ以上なら3階層
sdd-document-management	3階層	フルスキャン時に5機能を並列実行

並列処理（Agent tool活用）

条件を満たす場合は積極的に使用する。 判定基準・パターン・呼び出し例は references/agent_teams_guide_ja.md を参照。

タスク同期プロトコル

docs/sdd/tasks/のタスクとTodoWriteの同期ルール。詳細は references/task_sync_guide_ja.md を参照。

リソース

リファレンス

• ワークフローガイド: references/workflow_guide_ja.md
• 検証チェックリスト: references/checklist_ja.md
• 並列処理ガイド: references/agent_teams_guide_ja.md
• タスク同期ガイド: references/task_sync_guide_ja.md

サブスキル

• 要求管理: requirement-management/SKILL.md
• タスク計画: task-planning/SKILL.md
• タスク実行: task-executing/SKILL.md
• トラブルシューティング: sdd-troubleshooting/SKILL.md
• 移行手順: requirement-management/references/migration_from_sdd_ja.md

非推奨（既存 docs/sdd/ の保守時のみ）:

• requirements-defining/SKILL.md / software-designing/SKILL.md / sdd-document-management/SKILL.md