commit f2613ae15b3d5052a0aaaaf25f1cb079b8b2e35c Author: Zhongwei Li Date: Sun Nov 30 08:39:29 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..a6cd8d3 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "sdd", + "description": "Spec Driven Development (SDD) ワークフロー支援コマンド集", + "version": "0.1.0", + "author": { + "name": "masseater", + "email": "zhongweili@tubi.tv" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..eec04f4 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# sdd + +Spec Driven Development (SDD) ワークフロー支援コマンド集 diff --git a/agents/contradiction-checker.md b/agents/contradiction-checker.md new file mode 100644 index 0000000..bce7a69 --- /dev/null +++ b/agents/contradiction-checker.md @@ -0,0 +1,298 @@ +--- +agent-type: "contradiction-checker" +when-to-use: "仕様書（specs/[taskname]/）内のドキュメント間の矛盾を検出する時。Phase情報、機能定義、データ設計などの整合性をチェックする。指摘のみを行い、修正は行わない。" +allowed-tools: ["Read", "Glob", "Grep"] +--- + +# contradiction-checker SubAgent + +このSubAgentは、仕様書内のドキュメント間の矛盾を検出し、詳細な報告を行います。 + +## 役割 + +- **指摘専門**: 矛盾を発見して報告するのみ（修正は行わない） +- **包括的チェック**: 複数ドキュメント間の整合性を横断的に検証 +- **詳細報告**: 矛盾箇所と理由を具体的に説明 + +## チェック対象 + +### 1. Phase情報の整合性 + +**対象ドキュメント**: +- `specs/[taskname]/overview.md` - Phase概要と依存関係 +- `specs/[taskname]/tasks/phase*.md` - 各Phase詳細計画 + +**チェック項目**: +- Phase番号と名前の一致 +- Phase目標の整合性 +- Phase依存関係の矛盾（循環依存など） +- Phase状態の矛盾（overview.mdとphase*.mdで異なる状態） +- タスク番号の重複や欠番 + +**矛盾例**: +``` +❌ overview.md: "Phase 1: 基盤構築 (完了)" + tasks/phase1-foundation.md: "状態: 進行中" + → Phase状態が不一致 +``` + +### 2. 機能定義の整合性 + +**対象ドキュメント**: +- `specs/[taskname]/overview.md` - 機能概要 +- `specs/[taskname]/specification.md` - 詳細要件 +- `specs/[taskname]/technical-details.md` - 技術仕様 + +**チェック項目**: +- 機能名と説明の一致 +- 機能スコープの矛盾 +- 機能の優先度や必須/オプションの不一致 +- overview.mdで言及されているが他ドキュメントに記載がない機能 +- specification.mdやtechnical-details.mdにあるがoverview.mdに記載がない機能 + +**矛盾例**: +``` +❌ overview.md: "ユーザー認証機能（オプション）" + specification.md: "ユーザー認証機能（必須）" + → 優先度の矛盾 +``` + +### 3. データ設計の整合性 + +**対象ドキュメント**: +- `specs/[taskname]/specification.md` - データ要件 +- `specs/[taskname]/technical-details.md` - データベース設計 + +**チェック項目**: +- フィールド名の一致 +- データ型の整合性 +- 必須/オプションフィールドの一致 +- リレーションの矛盾 +- specification.mdで要求されているがtechnical-details.mdにないフィールド +- technical-details.mdにあるがspecification.mdで言及されていないフィールド + +**矛盾例**: +``` +❌ specification.md: "ユーザーは複数のロールを持つ" + technical-details.md: "users.role_id (単一のロールID)" + → データ構造の矛盾（1対多 vs 1対1） +``` + +### 4. API設計の整合性 + +**対象ドキュメント**: +- `specs/[taskname]/specification.md` - API要件 +- `specs/[taskname]/technical-details.md` - API設計詳細 + +**チェック項目**: +- エンドポイント名とパスの一致 +- HTTPメソッドの一致 +- リクエスト/レスポンス形式の整合性 +- エラーハンドリングの一貫性 + +**矛盾例**: +``` +❌ specification.md: "GET /api/users/:id - ユーザー詳細取得" + technical-details.md: "POST /api/user/:id - ユーザー情報取得" + → HTTPメソッドとパスの矛盾 +``` + +### 5. セキュリティ要件の整合性 + +**対象ドキュメント**: +- `specs/[taskname]/specification.md` - セキュリティ要件 +- `specs/[taskname]/technical-details.md` - セキュリティ実装 + +**チェック項目**: +- 認証方式の一致 +- 認可レベルの整合性 +- データ保護要件の実装状況 + +### 6. Phase間の依存関係の妥当性 + +**対象ドキュメント**: +- `specs/[taskname]/overview.md` +- `specs/[taskname]/tasks/phase*.md` + +**チェック項目**: +- 依存関係の循環参照 +- 前Phaseで提供されない機能への依存 +- Phase順序の論理的妥当性 + +**矛盾例**: +``` +❌ Phase 2が「ユーザー認証API」に依存 + Phase 3で「ユーザー認証API」を実装 + → 依存順序の矛盾 +``` + +## 実行手順 + +### 1. 対象ドキュメントの収集 + +```bash +# 対象タスクの全ドキュメントを確認 +Read: specs/[taskname]/overview.md +Read: specs/[taskname]/research.md (存在する場合) +Read: specs/[taskname]/specification.md +Read: specs/[taskname]/technical-details.md +Glob: specs/[taskname]/tasks/phase*.md +``` + +### 2. 各ドキュメントの重要情報を抽出 + +**overview.md**から: +- Phase一覧（番号、名前、状態、目標） +- 機能概要 +- プロジェクト全体の方針 + +**specification.md**から: +- 機能要件一覧 +- データ要件 +- API要件 +- 非機能要件 + +**technical-details.md**から: +- データベース設計 +- API設計 +- 技術スタック +- アーキテクチャ + +**tasks/phase*.md**から: +- Phase名と番号 +- Phase状態 +- タスク一覧と依存関係 + +### 3. 矛盾の検出と分類 + +各チェック項目について、以下の形式で矛盾を記録: + +``` +【矛盾タイプ】: Phase情報の不一致 +【重要度】: 高/中/低 +【影響範囲】: 実装作業に影響 / ドキュメント整合性のみ +【詳細】: + ファイル1: overview.md:45 + 記載内容: "Phase 1: 基盤構築 (完了)" + ファイル2: tasks/phase1-foundation.md:3 + 記載内容: "状態: 進行中" + 矛盾理由: Phase完了状態が不一致 +【推奨対応】: + - overview.mdをphase1-foundation.mdに合わせて「進行中」に更新 + - または phase1-foundation.mdを「完了」に更新 +``` + +### 4. 矛盾レポートの生成 + +すべての矛盾を以下の形式でレポート: + +```markdown +# 矛盾チェックレポート + +## サマリー + +- **対象タスク**: [taskname] +- **チェック日時**: YYYY-MM-DD HH:MM +- **検出された矛盾**: X件 + - 高重要度: Y件 + - 中重要度: Z件 + - 低重要度: W件 + +## 重要度別の矛盾一覧 + +### 🔴 高重要度の矛盾（実装作業に影響） + +#### 1. [矛盾タイプ] +- **ファイル**: file1.md:line vs file2.md:line +- **内容**: 具体的な矛盾の説明 +- **影響**: この矛盾が実装に与える影響 +- **推奨対応**: 具体的な修正案 + +### 🟡 中重要度の矛盾（ドキュメント整合性） + +#### 2. [矛盾タイプ] +... + +### 🟢 低重要度の矛盾（軽微な不一致） + +#### 3. [矛盾タイプ] +... + +## チェック完了項目 + +✅ Phase情報の整合性 +✅ 機能定義の整合性 +✅ データ設計の整合性 +✅ API設計の整合性 +✅ セキュリティ要件の整合性 +✅ Phase間依存関係の妥当性 + +## 総合評価 + +- ✅ 矛盾なし - 実装開始可能 +- ⚠️ 軽微な矛盾あり - 修正推奨だが実装は可能 +- ❌ 重大な矛盾あり - 修正必須、実装前に解決すること +``` + +## 重要な原則 + +### ✅ 実施すること + +1. **客観的な報告**: 事実に基づいた矛盾のみを報告 +2. **具体的な箇所の特定**: ファイル名と行番号を明記 +3. **影響範囲の評価**: 実装への影響度を明確に +4. **修正案の提示**: 複数の選択肢を提示（どれが正しいかは判断しない） + +### ❌ 実施しないこと + +1. **修正作業**: ドキュメントの編集や修正は行わない +2. **主観的判断**: どちらが正しいかの判断はユーザーに委ねる +3. **推測による指摘**: 明確に矛盾していない箇所を指摘しない +4. **過度な詳細**: 些細な表現の違いを矛盾として報告しない + +## 使用例 + +**コマンドから呼び出す場合**: +```bash +Task(contradiction-checker): specs/user-authentication/ の全ドキュメント間の矛盾をチェックしてください。特にPhase情報とデータ設計の整合性を重点的に確認してください。 +``` + +**特定の観点に絞る場合**: +```bash +Task(contradiction-checker): specs/user-authentication/specification.md と technical-details.md のAPI設計の整合性のみをチェックしてください。 +``` + +## 矛盾検出のベストプラクティス + +1. **Phase情報は必ず確認**: overview.mdとtasks/phase*.mdの状態は常にチェック +2. **データ構造の詳細確認**: フィールド名だけでなく、データ型やリレーションも確認 +3. **用語の一貫性**: 同じ概念が異なる名前で表現されていないか注意 +4. **暗黙の矛盾も検出**: 明示的な記載はないが、論理的に矛盾する箇所も指摘 +5. **重要度の適切な評価**: 実装への影響を考慮して重要度を設定 + +## 矛盾が見つからなかった場合 + +矛盾が1件も検出されなかった場合も、以下の形式でレポート: + +```markdown +# 矛盾チェックレポート + +## サマリー + +- **対象タスク**: [taskname] +- **チェック日時**: YYYY-MM-DD HH:MM +- **検出された矛盾**: 0件 + +## チェック完了項目 + +✅ Phase情報の整合性 +✅ 機能定義の整合性 +✅ データ設計の整合性 +✅ API設計の整合性 +✅ セキュリティ要件の整合性 +✅ Phase間依存関係の妥当性 + +## 総合評価 + +✅ **矛盾なし** - すべてのドキュメントが整合性を保っています。実装開始可能です。 +``` diff --git a/agents/steering-reviewer.md b/agents/steering-reviewer.md new file mode 100644 index 0000000..86b12d6 --- /dev/null +++ b/agents/steering-reviewer.md @@ -0,0 +1,158 @@ +--- +agent-type: "steering-reviewer" +when-to-use: "ステアリングドキュメント(specs/_steering/)に基づいてコードやドキュメントがプロジェクト方針に準拠しているかレビューする時。指摘のみを行い、修正は行わない。" +allowed-tools: ["Read", "Glob", "Grep", "Bash"] +--- + +# Steering Document Reviewer SubAgent + +このSubAgentはステアリングドキュメントに基づいてコードやドキュメントの問題点を指摘します。 +**対応は行わず、指摘のみを行います。** + +## 役割 + +プロジェクトのステアリングドキュメント（product.md, tech.md, structure.md）を読み込み、 +現在のコード、ドキュメント、または変更内容がプロジェクトの方針に沿っているかレビューします。 + +## 使用可能なツール + +- Read: ステアリングドキュメントとレビュー対象ファイルの読み込み +- Glob: レビュー対象ファイルの検索 +- Grep: コード内のパターン検索 +- Bash: git diffなどの取得 + +## 実行手順 + +### 1. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込みます： + +**`specs/_steering/product.md`**: +- プロダクトの目的とビジョン +- ターゲットユーザー +- 主要機能とビジネス目標 + +**`specs/_steering/tech.md`**: +- 技術スタックとアーキテクチャ +- 開発標準（型安全性、コード品質、テスト戦略） +- 重要な技術的決定事項 + +**`specs/_steering/structure.md`**: +- プロジェクト構造と命名規則 +- コード組織原則 +- モジュール境界 + +**ステアリングドキュメントが存在しない場合**: +- エラーメッセージを表示: 「❌ ステアリングドキュメントが見つかりません。`/sdd:steering` でステアリングドキュメントを作成してください。」 +- 処理を中断 + +### 2. レビュー対象の特定 + +ユーザーの指示に基づいてレビュー対象を特定： +- コードファイル +- ドキュメントファイル +- 変更差分（git diff） +- 特定のディレクトリ +- PR全体 + +### 3. ステアリングドキュメントとの整合性チェック + +以下の観点でチェック： + +#### プロダクト方針（product.md）との整合性 +- ビジネス目標に沿った実装になっているか +- ターゲットユーザーの要求を満たしているか +- プロダクトのビジョンと矛盾していないか + +#### 技術方針（tech.md）との整合性 +- 指定された技術スタックを使用しているか +- アーキテクチャパターンに従っているか +- コーディング標準を遵守しているか +- テスト戦略に沿っているか +- セキュリティ要件を満たしているか + +#### プロジェクト構造（structure.md）との整合性 +- ディレクトリ構造の規約に従っているか +- 命名規則を遵守しているか +- モジュール境界を尊重しているか +- ファイルの配置が適切か + +### 4. 問題点の指摘 + +発見した問題点を以下の形式で報告： + +```markdown +## ステアリングドキュメントレビュー結果 + +### ✅ 準拠している点 +- [準拠している点をリストアップ] + +### ⚠️ 指摘事項 + +#### 1. [問題のカテゴリ] +**ファイル**: `path/to/file.ts:123` +**違反内容**: [どのステアリングドキュメントのどの項目に違反しているか] +**現状**: [現在の実装] +**期待**: [ステアリングドキュメントで定義されている期待値] +**重大度**: [高/中/低] + +#### 2. [問題のカテゴリ] +... + +### 📊 サマリー +- 準拠項目: X件 +- 指摘事項: Y件 +- 重大度: 高 (Z件), 中 (W件), 低 (V件) +``` + +### 5. 重大度の判定 + +各指摘事項に重大度を設定： + +- **高**: セキュリティ、アーキテクチャの根本的な違反、ビジネス目標との矛盾 +- **中**: コーディング標準の違反、命名規則の不一致、推奨パターンからの逸脱 +- **低**: 軽微なスタイルの不一致、改善余地がある部分 + +### 6. 完了報告 + +``` +✅ ステアリングドキュメントレビューを完了しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 レビュー対象: [対象の説明] +📝 ステアリングドキュメント: + - specs/_steering/product.md + - specs/_steering/tech.md + - specs/_steering/structure.md + +📊 結果: + - 準拠項目: X件 + - 指摘事項: Y件 (高: Z件, 中: W件, 低: V件) + +💡 次のアクション: + - 指摘事項を確認し、修正が必要か判断してください + - 修正が必要な場合は、ステアリングドキュメントに沿った修正を行ってください + - ステアリングドキュメント自体を更新する必要がある場合は、`/sdd:steering` を実行してください +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 重要な注意事項 + +- **このSubAgentは指摘のみを行い、コードの修正は行いません** +- ステアリングドキュメントが存在しない場合はエラーを返します +- 指摘事項は具体的かつ建設的に記述します +- 必ず該当するファイル名と行数を明記します +- ステアリングドキュメントの該当箇所を引用します +- レビュー結果は必ず上記のフォーマットで出力します + +## 使用例 + +```bash +# 特定のファイルをレビュー +/task steering-reviewer: specs/_steering/ のドキュメントを読み込んで、src/auth/login.ts がステアリングドキュメントに沿っているかレビューしてください + +# 変更差分をレビュー +/task steering-reviewer: 最新のgit diffをステアリングドキュメントに照らしてレビューしてください + +# ディレクトリ全体をレビュー +/task steering-reviewer: src/api/ ディレクトリ全体がステアリングドキュメントに準拠しているかレビューしてください +``` diff --git a/commands/archive-spec.md b/commands/archive-spec.md new file mode 100644 index 0000000..7c87f07 --- /dev/null +++ b/commands/archive-spec.md @@ -0,0 +1,84 @@ +--- +argument-hint: "" +--- + +# 完了または不要になったspecsをアーカイブします + +specs/配下のタスクを一覧表示し、選択したタスクを`specs/_archived/`ディレクトリに移動します。アーカイブ理由はoverview.mdのPhase statusから自動判定します。 + +## 実行手順 + +### 1. タスク一覧の取得 +1. `specs/`ディレクトリが存在するか確認 +2. 存在しない場合、エラーメッセージを表示して終了 +3. `specs/`配下のディレクトリ一覧を取得（`_archived`を除外） +4. タスクが存在しない場合、「アーカイブ可能なタスクがありません」と表示して終了 + +### 2. 各タスクのプロジェクトステータス確認 +各タスクについて以下を実行: + +1. `specs/[taskname]/overview.md`を読み込む +2. 「## プロジェクトステータス」セクションの「**ステータス**:」フィールドを読み取る +3. ステータスが「完了」または「却下」のタスクのみをアーカイブ対象とする +4. `overview.md`が存在しない、またはプロジェクトステータスが取得できない場合 → アーカイブ対象外 + +### 3. AskUserQuestionツールでタスクを選択 +1. アーカイブ対象タスク（ステータスが「完了」または「却下」）の一覧を「タスク名（ステータス）」の形式で表示 + - 例: `user-authentication（完了）`、`payment-integration（却下）` +2. ユーザーに選択させる +3. 選択されたタスク名とステータスを取得 + +### 4. アーカイブディレクトリの準備 +1. `specs/_archived/`ディレクトリが存在するか確認 +2. 存在しない場合、作成する +3. `specs/_archived/[taskname]/`が既に存在する場合、エラーメッセージを表示して終了 + - エラーメッセージ: 「既にアーカイブされています: specs/_archived/[taskname]/」 + +### 5. Gitリポジトリの確認と移動 +1. `git rev-parse --is-inside-work-tree`を実行して確認 +2. 成功した場合（Gitリポジトリ内）: + - `git mv specs/[taskname] specs/_archived/[taskname]`を実行 + - コミットメッセージ: `Archive spec: [taskname] ([ステータス])` +3. 失敗した場合（Gitリポジトリ外）: + - `mv specs/[taskname] specs/_archived/[taskname]`を実行 + +### 6. Gitコミット（Gitリポジトリの場合のみ） +Gitリポジトリ内の場合: +```bash +git commit -m "$(cat <<'EOF' +Archive spec: [taskname] ([ステータス]) + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +EOF +)" +``` + +### 7. 完了報告 +以下を報告: +- アーカイブ先パス: `specs/_archived/[taskname]/` +- プロジェクトステータス: [完了/却下] + +## エラーハンドリング + +### specs/ディレクトリが存在しない場合 +``` +エラー: specs/ディレクトリが見つかりません +``` + +### アーカイブ可能なタスクがない場合 +``` +アーカイブ可能なタスクがありません +``` + +### 既にアーカイブされている場合 +``` +エラー: タスク「[taskname]」は既にアーカイブされています +specs/_archived/[taskname]/ が既に存在します +``` + +## 注意事項 +- アーカイブしたタスクを復元する場合は、手動で`git mv specs/_archived/[taskname] specs/[taskname]`を実行してください（Gitの場合） +- アーカイブ対象は、overview.mdの「プロジェクトステータス」が「完了」または「却下」のタスクのみです +- 既にアーカイブされているタスクは上書きできません diff --git a/commands/breakdown-phase.md b/commands/breakdown-phase.md new file mode 100644 index 0000000..fc147b7 --- /dev/null +++ b/commands/breakdown-phase.md @@ -0,0 +1,378 @@ +--- +argument-hint: <タスク名> +description: 指定されたPhaseの詳細タスク計画書を生成 +allowed-tools: ["Read", "Write", "Task", "AskUserQuestion"] +--- + +# 指定されたPhaseの詳細タスク計画書を生成します + +このコマンドは、**TDD（Test-Driven Development）とSOLID原則**に基づいた指定Phaseの詳細計画書を `specs/[taskname]/tasks/phase{N}-{name}.md` として生成します。 + +**重要**: Phase構成は `/sdd:plan-phases` で決定済みであることが前提です。 + +【引数】 +$ARGUMENTS + +**引数の形式**: +- `<タスク名>` - 必須 +- `` - 必須（例: 1, 2, 3） + +## Phase分けの基本方針 + +Phase分けは以下の原則に基づいて行います： + +### 重要な前提条件 + +**⚠️ 調査・設計はPhase分け前に完了させること** +- Phase内のタスクには調査・設計タスクを含めてはいけません +- 技術選定、アーキテクチャ設計、実装方法の検討など、全ての調査・設計作業は `/sdd:conduct-research` コマンドで完了させてください +- Phase内のタスクは「実装」のみに焦点を当てます + +**Phase内に含めてはいけないタスクの例**: +- ❌ 「認証ライブラリの選定」 +- ❌ 「データベーススキーマの設計検討」 +- ❌ 「API設計の方針決定」 +- ❌ 「パフォーマンスの実現可能性調査」 + +**Phase内に含めるべきタスクの例**: +- ✅ 「ユーザーテーブルのマイグレーション作成」 +- ✅ 「認証APIエンドポイントの実装」 +- ✅ 「ログインUIコンポーネントの実装」 +- ✅ 「ユニットテストの作成」 + +### タスク分解の方針 + +#### Phase分けの基準 +Phaseは以下の基準で分割してください： + +1. **独立してデプロイ・リリース可能な単位** + - 各Phaseは独立して動作確認とリリースができる状態になるように分割 + - Phase完了時点で品質チェックに成功する状態であること（必須） + +2. **機能の依存関係による分割** + - 後続Phaseが前Phaseの成果物に依存する構造 + - 並行開発可能なPhaseは別々に分ける + +3. **リスクとビジネス価値による優先順位付け** + - 高リスク・高価値の機能は早期のPhaseで実装 + - 基盤機能 → コア機能 → 拡張機能の順に配置 + +#### Phase内のタスク分けの基準 +各Phase内でさらに小さいタスクに分ける場合、以下の基準を適用してください： + +1. **適切な粒度の単位** + - 大きすぎる場合はさらに分割を検討 + - 小さすぎる場合は統合を検討 + +2. **TDDサイクルが完結する単位** + - Red → Green → Refactor のサイクルが1回以上完結すること + - テストと実装がセットで完了すること + +3. **単一の機能または責任を持つ単位** + - 単一責任の原則に従う + - タスク名が「〇〇と△△」のように複数の責任を示す場合は分割 + +4. **他のタスクとの依存関係が明確** + - タスクAが完了しないとタスクBに着手できない場合は依存関係を明記 + - 並行作業可能なタスクは独立させる + +#### 具体例：空のWebアプリにログイン機能を実装する場合 + +**Phase 1: ユーザーテーブルとモデル** +- タスク1: ユーザーテーブルのマイグレーションファイル作成 +- タスク2: マイグレーション実行とテスト +- タスク3: ユーザーモデルの基本構造作成（ID、メール、パスワードハッシュフィールド） + +**Phase 2: ログインAPI** +- タスク1: ログインエンドポイントの骨組み作成（POST /api/auth/login、リクエスト受付のみ） +- タスク2: パスワード検証ロジックの実装 +- タスク3: JWTトークン生成機能の実装 + +**Phase 3: ログインUI** +- タスク1: ログインフォームコンポーネントの骨組み作成（メール・パスワード入力欄のみ） +- タスク2: フォーム送信処理とAPIとの連携 +- タスク3: エラー表示UI（バリデーションエラー、認証エラー） + +各タスクはTDDサイクル（Red→Green→Refactor）が1回完結する粒度です。 + +### 開発原則 +各Phaseでは `specs/_steering/principles.md` に記載された以下の原則を適用します： +- **TDD（Test-Driven Development）**: Red-Green-Refactorサイクル +- **SOLID原則**: 単一責任、開放/閉鎖、リスコフの置換、インターフェース分離、依存性逆転 +- **YAGNI原則**: 実際に必要になるまで機能を追加しない + +### ⚠️ 重要な制約事項 +- **過度な抽象化を避ける**: インターフェース（抽象）を作ることが目的化してはいけない +- **型定義だけを先に作ることは禁止**: 実装と共に型を作成し、必要に応じて分離する +- **YAGNI原則の徹底**: 将来の要件を予測した実装は行わない + +## 実行手順 + +### 1. 引数のパースと検証 + +`$ARGUMENTS` から タスク名 と Phase番号 を抽出： + +**引数が不足している場合**: +- タスク名のみ指定: エラーメッセージ「Phase番号を指定してください。使用方法: /sdd:breakdown-phase 」 +- 両方未指定: `specs/` ディレクトリ内のタスクをリスト表示し、**AskUserQuestionツールで選択**を求める + +**Phase番号が数値でない場合**: +- エラーメッセージ「Phase番号は数値で指定してください」 + +### 2. タスクディレクトリの確認 + +- `specs/[taskname]/` ディレクトリの存在を確認 +- 必須ファイルの存在確認: + - `overview.md` （Phase構成が含まれているはず） + - `specification.md` + - `technical-details.md` +- `specs/[taskname]/tasks/` ディレクトリが存在しない場合は作成 + +### 3. ステアリングドキュメントの読み込み + +プロジェクト全体のコンテキストを把握するため、以下のステアリングドキュメントを読み込みます： + +**`specs/_steering/product.md`**: +- プロダクトの目的とビジョン +- ターゲットユーザー +- 主要機能とビジネス目標 + +**`specs/_steering/tech.md`**: +- 技術スタックとアーキテクチャ +- 開発標準（型安全性、コード品質、テスト戦略） +- 重要な技術的決定事項 + +**`specs/_steering/structure.md`**: +- プロジェクト構造と命名規則 +- コード組織原則 +- モジュール境界 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。プロジェクト固有のコンテキストなしで進めます。」 +- `/sdd:steering` コマンドでステアリングドキュメントを作成することを推奨 +- 処理は続行（ステアリングドキュメントは必須ではない） + +### 4. 調査完了の確認 + +詳細タスク計画作成前に、必ず調査が完了していることを確認: + +1. **overview.mdの調査セクション確認** + - `specs/[taskname]/overview.md` の調査項目表を読み込み + - 全ての調査項目の状態を確認 + +2. **調査ステータスの判定** + - 全て「完了」の場合: 次のステップへ進む + - 「未着手」がある場合: + - 警告メッセージを表示: 「⚠️ 調査が完了していません」 + - 未完了の調査項目をリスト表示 + - AskUserQuestionツールで確認して続行するか判断 + - 続行しない場合: `/sdd:conduct-research [taskname]` を推奨 + +### 5. 既存ドキュメントの分析 + +以下のドキュメントから情報を抽出: + +**`overview.md`**: +- 調査結果（調査セクションおよびspecs/research/配下の個別ファイル） +- **指定されたPhase番号のPhase情報のみ**を抽出 +- Phase名、状態、目標、依存関係、成果物 +- Phase番号が overview.md に存在しない場合: + - エラーメッセージ「Phase {N} は overview.md に存在しません。/sdd:plan-phases でPhase構成を作成してください。」 + - 処理を中断 + +**`specification.md`**: +- 機能要件の詳細 +- 指定Phaseで実装する機能 +- 非機能要件 + +**`technical-details.md`**: +- 技術スタックと技術選定 +- データ設計とAPI設計 +- セキュリティ要件 + +### 6. Phase計画書の生成/更新 + +指定されたPhase番号に対して `specs/[taskname]/tasks/phase{N}-{phaseName}.md` ファイルを生成または更新: + +**ファイル名の決定**: +- Phase番号: 引数で指定された番号 +- Phase名: overview.mdから抽出したPhase名（kebab-case に変換） +- 例: Phase 2 "Core Features" → `phase2-core-features.md` + +**生成・更新モードの判定**: +- ファイルが存在しない場合: 新規作成 +- ファイルが存在する場合: + - 既存内容を確認 + - **AskUserQuestionツール**で「上書き/スキップ/マージ」を確認 + - マージの場合は既存の進捗情報（チェックボックスの状態、開始日時、完了済みタスク）を保持しながら更新 + +**Phase内タスクの検証**: +- 各タスクが実装タスクのみであることを確認 +- 調査・設計タスクが含まれていないかチェック +- 調査・設計タスクが見つかった場合: 警告を表示し、research.mdへの移動を提案 + +**ファイルフォーマット**: + +```markdown +# Phase {N}: {phaseName} 計画書 + +## タスク目次 + +- 1. [タスク名] +- 2.1. [タスク名]（2.x系は並列実行可能） +- 2.2. [タスク名] +- 2.3. [タスク名] +- 3. [タスク名] + +**並列実行の判断基準（明示的並列宣言方式）:** +- デフォルトは全て直列実行 +- 並列実行するタスクは明示的にn.x形式で番号付け（例: 2.1, 2.2, 2.3） +- タスク作成者が並列実行して問題ないことを保証する責任を持つ +- Phase分け時にユーザーに依存関係の妥当性を確認する + +## Phase概要 +- **Phase名**: {phaseName} +- **状態**: 未着手/進行中/完了 +- **目標**: + +## 開発原則 + +このPhaseでは `specs/_steering/principles.md` に記載された開発原則を適用します。 +各タスクでTDD（Red-Green-Refactor）サイクルを実施してください。 + +## 依存関係 +- **前提条件**: [Phase N-1の完了、必要なライブラリの選定など] +- **ブロッカー**: [なし、または現在のブロッカー] +- **後続Phaseへの影響**: [Phase N+1が依存する機能] + +## 実装する機能 +- 機能1 +- 機能2 +- 機能3 + +## タスク詳細 + +### タスク1: [タスク名] +- **説明**: [実装内容] +- **状態**: 未着手 +- **開始日時**: +- **TDDステップ**: + - [ ] Red: テストケース作成 + - [ ] Green: 最小実装 + - [ ] Refactor: リファクタリング +- **依存関係**: なし + +### タスク2.1: [タスク名] +- **説明**: [実装内容] +- **状態**: 未着手 +- **開始日時**: +- **TDDステップ**: + - [ ] Red: テストケース作成 + - [ ] Green: 最小実装 + - [ ] Refactor: リファクタリング +- **依存関係**: タスク1 + +### タスク2.2: [タスク名] +- **説明**: [実装内容] +- **状態**: 未着手 +- **開始日時**: +- **TDDステップ**: + - [ ] Red: テストケース作成 + - [ ] Green: 最小実装 + - [ ] Refactor: リファクタリング +- **依存関係**: タスク1 + +### タスク3: [タスク名] +- **説明**: [実装内容] +- **状態**: 未着手 +- **開始日時**: +- **TDDステップ**: + - [ ] Red: テストケース作成 + - [ ] Green: 最小実装 + - [ ] Refactor: リファクタリング +- **依存関係**: タスク2.x系全て + +## テスト戦略 + +- **単体テスト**: 各関数/メソッドの振る舞いを検証 +- **統合テスト**: モジュール間の連携を検証 +- **E2Eテスト**: エンドユーザーの視点からの動作を検証 + +## Phase完了条件 +- [ ] 全タスク完了 +- [ ] 全テスト通過 +- [ ] 品質チェックコマンドが成功（lint、type check、buildなど） +- [ ] コードレビュー承認 + +## 技術的課題と解決方針（必要な場合のみ） +[想定される課題と解決方針がある場合に記述] + +## リスク管理（必要な場合のみ） +[Phase固有のリスクがある場合に記述] + +## 次Phaseへの引き継ぎ事項（必要な場合のみ） +[引き継ぎ事項がある場合に記述] +``` + +### 7. 完了報告 + +``` +✅ Phase {N} の詳細計画書を生成/更新しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 対象ファイル: specs/[taskname]/tasks/phase{N}-{name}.md +📝 モード: [新規作成/更新/マージ] + +📊 Phase {N} 概要: + - Phase名: {name} + - 状態: {status} + - 目標: {goal} + - タスク数: {count} + +💡 次のアクション: + - Phase計画書の内容を確認・編集してください + - TDDサイクル（Red→Green→Refactor）を意識して進めてください + - 他のPhaseの計画書を作成する場合: `/sdd:breakdown-phase [taskname] [phase番号]` + - Phase実装を開始する場合: `/sdd:implement-phase [taskname] [phase番号]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: このコマンドは**指定された1つのPhase**の詳細計画のみを生成します +- **⚠️ 重要**: Phase構成は事前に `/sdd:plan-phases` で決定されている必要があります +- **⚠️ 重要**: 詳細であれば詳細であるほど良いわけではない。必要な部分だけを必要なだけ書くこと +- **⚠️ 重要**: インターフェースや抽象クラスは、それを使用しなければ実現できない時以外は使用禁止 +- **⚠️ 重要**: 型定義だけを先に作ることは絶対に行わないこと。タスク単位で型定義だけを作ることは禁止。実装を作った後、他でもその型を使用する場合に分離する +- **⚠️ 重要**: 推測される開発期間、工数、見積もり時間などは一切記載しないこと（タスクの開始日時は記録する） +- **⚠️ 重要**: 「将来的に必要になる」「今後〜が必要」といった適当な推測に基づいた記述は禁止。現時点で明確に必要なことのみを記載すること +- **⚠️ 重要**: 不明なところは勝手に決めずに「**不明**」と明記し、複数の案（案A、案B、案Cなど）を記述すること。ユーザーは `/sdd:clarify-spec [taskname]` コマンドで不明箇所を明確化できる +- **配置先**: `specs/[taskname]/tasks/phase{N}-{name}.md` +- 既存のPhase計画書がある場合、進捗情報（状態、タスクの開始日時、チェックボックス、完了済みタスク）は保持する +- **TDD原則**: 各タスクでRed→Green→Refactorサイクルを明記 +- **設計原則**: 各Phase/タスクでどの設計原則を適用するか明確に記述 +- 依存関係は具体的かつ明確に記述し、依存性注入（関数やオブジェクトを引数として渡す）を活用 +- overview.mdの「Phase概要と依存関係」セクションと整合性を保つ +- Phase名は overview.md から自動抽出し、ファイル名は `phase{N}-{kebab-case-name}.md` 形式とする + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +Phase詳細計画書生成後、内部的にステアリングドキュメントとの整合性を確認： +- tech.mdのコーディング標準・テスト戦略への準拠 +- structure.mdのモジュール境界・命名規則の遵守 +- product.mdのビジネス目標との整合性 +- principles.mdの開発原則（TDD、SOLID、YAGNI）への従属 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +Phase詳細計画書作成後、内部的に仕様書間の矛盾を確認： +- overview.mdとの整合性 +- specification.mdとの一致 +- technical-details.mdとの整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/clarify-spec.md b/commands/clarify-spec.md new file mode 100644 index 0000000..69a0ef2 --- /dev/null +++ b/commands/clarify-spec.md @@ -0,0 +1,161 @@ +--- +argument-hint: <タスク名> +allowed-tools: ["Read", "Edit", "Task", "AskUserQuestion", "TodoWrite"] +--- + +# specs内の不明箇所をユーザーに質問して明確化します + +このコマンドは `specs/[taskname]/` ディレクトリ内の全ドキュメントから「**不明**」と記載された箇所を抽出し、ユーザーに質問して明確化します。 + +## コマンドの役割 + +**`/sdd:clarify-spec`（このコマンド）の役割**: +- **ビジネス要件やユーザーの意思決定**が必要な不明箇所をユーザーに質問 +- AIだけでは判断できず、ユーザー（プロダクトオーナー、ステークホルダー）の意思決定が必要な項目 +- 例： + - 機能の優先順位や範囲 + - UIの具体的な仕様（表示項目、レイアウトなど） + - ビジネスルール（承認フロー、権限設定など） + - ユーザー体験に関する選択（エラー時の挙動など） + +**`/sdd:conduct-research` との違い**: +- **clarify-spec**: ビジネス要件やユーザーの意思決定が必要な項目をユーザーに質問 +- **conduct-research**: 技術的な調査が必要な項目をAIが調査・検証 +- clarify-specは「ユーザーに聞く」、conduct-researchは「AIが調べる」 + +**使い分けの例**: +- ✅ clarify: 「ログイン時にメールアドレスとユーザー名のどちらを使うか」（ビジネス要件） +- ✅ research: 「JWT vs セッション認証のパフォーマンス比較」（技術的検証） +- ✅ clarify: 「管理者画面の公開範囲（社内のみ or 顧客も使用）」（ビジネス要件） +- ✅ research: 「PostgreSQL vs MySQL のベンチマーク」（技術的検証） + +【対象タスク名】 +$ARGUMENTS + +## 実行手順 + +### 1. タスクディレクトリの確認 + +タスク名が指定されている場合: +- `specs/[taskname]/` ディレクトリの存在を確認 +- ディレクトリ内の全マークダウンファイルを取得 + +タスク名が指定されていない場合: +- `specs/` ディレクトリ内の利用可能なタスクをリスト表示 +- ユーザーに選択を求める + +### 2. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針 +- `specs/_steering/tech.md` - 技術スタック +- `specs/_steering/structure.md` - プロジェクト構造 +- `specs/_steering/principles.md` - 開発原則 + +ステアリングドキュメントが存在しない場合は警告を表示し、処理を続行。 + +### 3. 不明箇所の抽出 + +`specs/[taskname]/` および `specs/[taskname]/tasks/` 内の全マークダウンファイルを検索し、以下のパターンを抽出: + +- 「**不明**」または「不明」と記載された箇所 +- その周辺のコンテキスト（前後数行） +- 記載されている複数の案（案A、案B、案Cなど） + +各不明箇所について以下の情報を収集: +- **ファイル名**: どのファイルに記載されているか +- **セクション名**: どのセクションの内容か +- **不明な内容**: 何が不明なのか +- **提示されている案**: 案A、案B、案Cなど + +### 4. 不明箇所の整理とタスク化 + +抽出した不明箇所をTodoWriteツールでタスク化: + +``` +TodoWrite: +- [不明箇所1: 認証方式を決定] - pending +- [不明箇所2: データベースを選択] - pending +- [不明箇所3: デプロイ環境を選択] - pending +``` + +不明箇所をユーザーに提示: +- ファイル名、セクション名、不明な内容、提示されている案を表示 + +### 5. ユーザーへの質問 + +各不明箇所について、AskUserQuestionツールを使用してユーザーに質問: + +- 質問は明確で具体的にすること +- 提示されている案をそのまま選択肢として提示 +- 1つずつ順番に質問するのではなく、可能な限り複数の質問をまとめて提示 +- ユーザーが「その他」を選択した場合は自由記述で詳細を取得 + +例: +``` +質問: Phase 1で使用する認証方式を選択してください +選択肢: +- 案A: JWT認証 +- 案B: セッションベース認証 +- 案C: OAuth2.0 +``` + +### 6. 回答の反映 + +各不明箇所について： + +1. TodoWriteで該当タスクを`in_progress`に更新 +2. ユーザーの回答を元に該当ファイルの「**不明**」箇所を更新 +3. TodoWriteで該当タスクを`completed`に更新 + +**更新例**: +```markdown +# 更新前 +**不明**: JWT認証 or セッションベース認証 + +# 更新後 +JWT認証を使用する +``` + +### 7. 完了報告 + +``` +✅ 不明箇所を明確化しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 対象: specs/[taskname]/ +📝 明確化: [N]箇所 + +💡 次のアクション: + - 仕様書の内容を確認 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- 不明箇所が見つからない場合は、その旨を報告してコマンドを終了 +- ユーザーが「その他」を選択した場合は、その内容をそのまま反映 +- 更新時は「**不明**」の記述と案のリストを全て削除し、選択された内容のみを記載 +- 複数ファイルにまたがる不明箇所も漏れなく更新すること +- 更新前に必ずファイルの内容を読み込み、正確な位置を特定すること + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +明確化後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標との整合性 +- tech.mdの技術方針との整合性 +- principles.mdの開発原則との一致 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +明確化後、内部的に仕様書間の矛盾を確認： +- 明確化による変更が他のドキュメントと整合しているか +- 依存関係のあるドキュメント間で矛盾が生じていないか + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/conduct-research.md b/commands/conduct-research.md new file mode 100644 index 0000000..1d4c569 --- /dev/null +++ b/commands/conduct-research.md @@ -0,0 +1,247 @@ +--- +argument-hint: <タスク名> [調査項目名] +allowed-tools: ["Read", "Write", "Edit", "Bash", "WebSearch", "Task"] +--- + +# overview.mdの調査項目を実施し、個別ファイルとして保存します + +このコマンドは `specs/[taskname]/overview.md` の調査セクションから調査項目を読み取り、調査を実施して `specs/research/[調査項目名].md` として保存します。 + +## コマンドの役割 + +**`/sdd:conduct-research`（このコマンド）の役割**: +- **技術的な調査・検証**を実施 +- AIが自律的に調査・実験・ベンチマークなどを行って判断できる項目 +- 例： + - ライブラリやフレームワークの選定（性能比較、機能比較） + - 実装方法の検証（PoC作成、パフォーマンス測定） + - アーキテクチャの実現可能性調査 + - セキュリティ手法の選定と検証 + +**`/sdd:clarify-spec` との違い**: +- **clarify-spec**: ビジネス要件やユーザーの意思決定が必要な項目をユーザーに質問 +- **conduct-research**: 技術的な調査が必要な項目をAIが調査・検証 +- clarify-specは「ユーザーに聞く」、conduct-researchは「AIが調べる」 + +**使い分けの例**: +- ✅ research: 「JWT vs セッション認証のパフォーマンス比較」（技術的検証） +- ✅ clarify: 「ログイン時にメールアドレスとユーザー名のどちらを使うか」（ビジネス要件） +- ✅ research: 「PostgreSQL vs MySQL のベンチマーク」（技術的検証） +- ✅ clarify: 「管理者画面の公開範囲（社内のみ or 顧客も使用）」（ビジネス要件） + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `[taskname]` - タスク名のみ指定した場合、全ての未完了調査項目を順に実施 +- `[taskname] [調査項目名]` - 特定の調査項目のみ実施 + - 例: `user-authentication JWT認証のパフォーマンス検証` → 指定された調査項目のみ実施 + +## 実行手順 + +### 1. タスクと調査項目の特定 + +1. **引数が指定されている場合** + - `[taskname]`のみ: specs/[taskname]/overview.mdの調査セクションから未完了の調査項目を抽出 + - `[taskname] [調査項目名]`: 指定された調査項目のみを対象 + +2. **引数が指定されていない場合** + - `specs/`ディレクトリ内のサブディレクトリを一覧表示 + - 複数のタスクがある場合、AskUserQuestionツールでユーザーに選択させる + - 単一のタスクのみの場合は自動選択 + +3. **指定されたタスクディレクトリが存在しない場合** + - エラーメッセージを表示: 「specs/[taskname]/ ディレクトリが見つかりません」 + - specs/配下の利用可能なタスクを一覧表示 + +### 2. overview.mdの確認 + +1. **ファイルの存在確認** + - `specs/[taskname]/overview.md` の存在を確認 + - 存在しない場合: エラーメッセージを表示し、`/sdd:init-task` コマンドの実行を提案 + +2. **調査項目の抽出** + - overview.mdの「調査項目」セクション（表形式）から調査項目を抽出 + - 各調査項目の以下の情報を取得: + - 状態（未着手/完了） + - 調査項目名 + - 理由 + +3. **未完了調査項目のリスト表示** + - 状態が「未着手」の項目を表示 + - 調査項目が全て完了している場合: 完了メッセージを表示して終了 + +### 3. ステアリングドキュメントの読み込み + +プロジェクト全体のコンテキストを把握するため、以下のステアリングドキュメントを読み込みます： + +**`specs/_steering/product.md`**: +- プロダクトの目的とビジョン +- ターゲットユーザー +- 主要機能とビジネス目標 + +**`specs/_steering/tech.md`**: +- 技術スタックとアーキテクチャ +- 開発標準（型安全性、コード品質、テスト戦略） +- 重要な技術的決定事項 + +**`specs/_steering/structure.md`**: +- プロジェクト構造と命名規則 +- コード組織原則 +- モジュール境界 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。プロジェクト固有のコンテキストなしで進めます。」 +- `/sdd:steering` コマンドでステアリングドキュメントを作成することを推奨 +- 処理は続行（ステアリングドキュメントは必須ではない） + +### 4. 調査項目の選択 + +**調査項目名が指定されている場合**: +- 指定された名前の調査項目を特定 +- その調査項目の詳細を表示 +- 手順5へ進む + +**調査項目名が指定されていない場合**: +- 未完了の調査項目を表示 +- AskUserQuestionツールを使用してユーザーに選択させる + - 各調査項目を選択肢として提示 + - 「全て順番に実施」オプションも含める + +### 5. 調査の実施 + +選択された調査項目について、以下の手順で調査を実施: + +#### 5-1. 調査内容の確認 +1. **調査項目の詳細を確認** + - overview.mdから調査項目名と理由を取得 + - 何を調査すべきかを明確に理解 + +2. **調査プランの作成（内部処理）** + - TodoWriteツールを使用して調査ステップを計画 + - 例: + - コードベースの既存実装を調査 + - ドキュメント・ベストプラクティスを調査（WebSearchツール使用） + - PoC実装（必要な場合） + - ベンチマーク実施（必要な場合） + - 結果の比較と分析 + - **調査プランはspecファイルには書かない**（内部処理のみ） + +#### 5-2. 調査の実行 + +調査方法に応じて適切なアプローチを選択: + +**A. コードベース調査** +- 既存の実装パターンを確認 +- 使用されているライブラリやフレームワークを確認 +- 類似機能の実装方法を分析 + +**B. ドキュメント調査** +- WebSearchツールを使用して最新のベストプラクティスを調査 +- 公式ドキュメントを参照 +- 技術記事やブログを調査 + +**C. PoC（Proof of Concept）実装** +- 小規模な実装例を作成 +- 動作確認とパフォーマンス測定 +- 実装の難易度や工数を評価 + +**D. ベンチマーク** +- 複数の選択肢を比較 +- パフォーマンス測定 +- リソース使用量の確認 + +#### 5-3. 調査結果のまとめと保存 + +調査完了後、以下の情報をまとめて `specs/[taskname]/research/[調査項目名].md` として保存: + +```markdown +# [調査項目名] + +## 結論 +- 選択: [選択した技術/手法] +- 理由: [選択の理由を1-3行で簡潔に] + +## 詳細（必要な場合のみ） +- パフォーマンス測定結果 +- セキュリティ考慮事項 +- 実装の難易度評価 +- 注意点やリスク + +## 関連タスク +- specs/[taskname]/ +``` + +**ファイル名の決定**: +- 調査項目名をそのままファイル名にする +- 例: 「JWT認証のパフォーマンス検証」→ `JWT認証のパフォーマンス検証.md` + +### 6. overview.mdの調査セクション更新 + +#### 6-1. 表の更新 +- overview.mdの調査項目表で、該当行の「状態」列を「完了」に更新 +- 「概要」列に調査結果の簡潔なサマリーと結果ファイルへのリンクを追加: + ```markdown + | 完了 | [調査項目名] | [理由] | [選択した技術/手法](research/[調査項目名].md) | + ``` + +#### 6-2. 全調査項目完了時の処理 +- 全ての調査項目の状態が「完了」になっている場合 +- overview.mdの「次のステップ」を更新: + ```markdown + **次のステップ**: `/sdd:define-requirements [taskname]` で要件定義を開始してください + ``` + +### 7. 完了報告 + +``` +✅ 調査項目を完了しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 対象タスク: [taskname] +📝 完了した調査項目: [調査項目名] +🔍 結論: [選択した技術/手法] + +📄 保存先: specs/[taskname]/research/[調査項目名].md +📊 調査の進捗: 完了 {完了数} / {総数} + +💡 次のアクション: + - 残りの調査項目: `/sdd:conduct-research [taskname]` + - 全調査完了: `/sdd:define-requirements [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**複数の調査項目を順に実施する場合**: +- 1つの調査項目が完了したら、次の未完了項目を自動的に表示 +- ユーザーに「続けて次の調査項目を実施しますか？」と確認 +- 承認されたら手順4に戻って次の調査項目を実施 + +## 重要な注意事項 + +- **調査は丁寧に**: 調査は実装の品質を左右する重要なステップです。時間をかけて丁寧に調査してください +- **エビデンスベース**: 推測ではなく、調査結果（ベンチマーク、ドキュメント、PoC）に基づいて判断すること +- **調査結果は簡潔に**: 結論と理由を明確に。詳細は必要な場合のみ記載 +- **個別ファイルで管理**: 各調査項目は `specs/research/[調査項目名].md` として個別に保存 +- **調査プランはspecに書かない**: 調査プランは内部処理のみ。結果だけをファイルに保存 + +## 使用例 + +1. タスク全体の調査を順に実施: + `/sdd:conduct-research user-authentication` + +2. 特定の調査項目のみ実施: + `/sdd:conduct-research user-authentication JWT認証のパフォーマンス検証` + +3. 引数なしで対話的に選択: + `/sdd:conduct-research` + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +調査結果ファイル生成後、内部的にステアリングドキュメントとの整合性を確認： +- tech.mdの技術方針と調査結果の整合性 +- product.mdのビジネス目標との整合性 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 diff --git a/commands/contradiction-check.md b/commands/contradiction-check.md new file mode 100644 index 0000000..d3c3b50 --- /dev/null +++ b/commands/contradiction-check.md @@ -0,0 +1,108 @@ +--- +argument-hint: <タスク名> +allowed-tools: ["Read", "Edit", "Task"] +--- + +# specsドキュメント間の矛盾をチェックし、修正します + +`specs/[taskname]/` ディレクトリ内の仕様書のドキュメント間の矛盾をチェックし、修正してください。 + +【対象タスク名】 +$ARGUMENTS + +## 実行手順 + +### 1. タスクディレクトリの確認 + +タスク名が指定されている場合: +- `specs/[taskname]/` ディレクトリの存在を確認 +- 必須ファイルの存在確認: + - `overview.md` + - `specification.md` + - `technical-details.md` + - `tasks/` ディレクトリ（Phase別計画書） + +タスク名が指定されていない場合: +- `specs/` ディレクトリ内の利用可能なタスクをリスト表示 +- ユーザーに選択を求める + +### 2. ステアリングドキュメントの読み込み + +プロジェクト全体のコンテキストを把握するため、以下のステアリングドキュメントを読み込みます： + +**`specs/_steering/product.md`**: +- プロダクトの目的とビジョン +- ターゲットユーザー +- 主要機能とビジネス目標 + +**`specs/_steering/tech.md`**: +- 技術スタックとアーキテクチャ +- 開発標準（型安全性、コード品質、テスト戦略） +- 重要な技術的決定事項 + +**`specs/_steering/structure.md`**: +- プロジェクト構造と命名規則 +- コード組織原則 +- モジュール境界 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。プロジェクト固有のコンテキストなしで進めます。」 +- `/sdd:steering` コマンドでステアリングドキュメントを作成することを推奨 +- 処理は続行（ステアリングドキュメントは必須ではない） + +### 3. ドキュメント間の矛盾チェック（contradiction-checker SubAgent使用） + +**contradiction-checker SubAgent** を使用して包括的な矛盾チェックを実施します： + +```bash +# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない） +Task(contradiction-checker): specs/[taskname]/ の全ドキュメント間の矛盾をチェックしてください。Phase情報、機能定義、データ設計、API設計、セキュリティ要件、Phase間依存関係の整合性を確認してください。 +``` + +**SubAgentがチェックする項目**: +- Phase情報の整合性（overview.md ⇔ tasks/phase*.md） +- 機能定義の整合性（overview.md ⇔ specification.md ⇔ technical-details.md） +- データ設計の整合性（specification.md ⇔ technical-details.md） +- API設計の整合性 +- セキュリティ要件の整合性 +- Phase間依存関係の妥当性 + +SubAgentは検出した矛盾を重要度別（高/中/低）にレポートします。 + +### 4. 矛盾の修正 + +**contradiction-checker SubAgentが矛盾を報告した場合:** + +1. **SubAgentのレポートを確認**: + - 重要度別の矛盾一覧を確認 + - 各矛盾の影響範囲と推奨対応を確認 + +2. **高重要度の矛盾から対応**: + - 実装作業に影響する矛盾を優先的に修正 + +3. **AskUserQuestionツールを使用**して修正方針を確認: + - 各矛盾に対して、どちらのドキュメントを正とするか + - または新しい内容にするか + - 複数の矛盾がある場合は、まとめて質問 + +4. **ユーザーの回答に基づいて該当ドキュメントを修正**: + - Editツールを使用してドキュメントを更新 + - 修正内容を明確に報告 + +5. **修正完了後、再度矛盾チェック**: + - 修正によって新たな矛盾が発生していないか確認 + - 必要に応じてcontradiction-checker SubAgentを再実行 + +**矛盾がない場合:** +- SubAgentのレポートを基に「矛盾は見つかりませんでした」と報告 +- 次のステップ（実装開始など）を提案 + +## ステアリングドキュメントレビュー（必須） + +矛盾修正後のドキュメントがステアリングドキュメントに準拠しているか必ず steering-reviewer SubAgent を使用して確認してください： + +```bash +# steering-reviewer SubAgentを使用（指摘のみ、修正は行わない） +# レビュー観点を明示的に指定 +Task(steering-reviewer): specs/[taskname]/ 配下の全ドキュメントをレビューしてください。product.mdのビジネス目標との整合性、tech.mdの技術方針との整合性、structure.mdのプロジェクト構造との整合性を確認してください。 +``` diff --git a/commands/define-requirements.md b/commands/define-requirements.md new file mode 100644 index 0000000..93f71c8 --- /dev/null +++ b/commands/define-requirements.md @@ -0,0 +1,210 @@ +--- +argument-hint: <タスク名> +description: 機能要件と非機能要件の詳細仕様を作成 +allowed-tools: ["Read", "Write", "Task", "AskUserQuestion"] +--- + +# 詳細要件仕様書を作成します + +タスクの機能要件と非機能要件を詳細化し、`specification.md` を生成します。 + +【対象タスク名】 +$ARGUMENTS + +## 実行手順 + +### 0. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針、ビジネス目標 +- `specs/_steering/tech.md` - 技術標準 +- `specs/_steering/structure.md` - プロジェクト構造 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。先に `/sdd:steering` を実行することを推奨します。」 + +### 1. タスクディレクトリの確認 + +タスク名が指定されている場合: +- `specs/[taskname]/` ディレクトリの存在を確認 +- `specs/[taskname]/overview.md` が存在するか確認 + +タスク名が指定されていない場合: +- `specs/` ディレクトリ内の利用可能なタスクをリスト表示 +- **AskUserQuestionツールを使用**してどのタスクについて作業するかユーザーに選択を求める + +### 2. 既存ドキュメントの読み込み + +以下のドキュメントを読み込み、要件定義に必要な情報を抽出： + +- `specs/[taskname]/overview.md` - プロジェクト概要、主要機能 +- `specs/_steering/product.md` - プロダクトの Non-Goals、Business Objectives +- `specs/_steering/tech.md` - 技術的制約 + +### 3. 非機能要件の確認 + +以下の非機能要件について、ユーザーに必要かどうかを確認してください： + +**AskUserQuestionツールを使用**して、以下を確認： + +``` +以下の非機能要件について、このタスクで必要なものを選択してください（複数選択可）： + +□ パフォーマンス要件（レスポンスタイム、同時接続数、データ処理量など） +□ 可用性要件（稼働率目標、ダウンタイム許容範囲、障害復旧時間など） +□ 保守性要件（コード品質基準、ドキュメント要件、技術的負債の管理など） +□ ユーザビリティ要件（UI/UX要件、アクセシビリティ、多言語対応など） +□ 制約条件（技術的制約、ビジネス的制約、法的・規制上の制約など） +□ テスト戦略（テストの種類、カバレッジ目標など） +□ 開発環境（必要なツール、セットアップ手順など） + +注: セキュリティ要件は常に含まれます +``` + +### 4. specification.mdの生成 + +`specs/[taskname]/specification.md` を生成： + +```markdown +# 詳細仕様書 + +## 機能要件 + +[overview.mdの主要機能を詳細化] + +### 機能1: [機能名] +- **概要**: [1-2行で機能を説明] +- **優先度**: High/Medium/Low +- **実装Phase**: Phase N（plan-phasesで決定後に追加） +- **入出力定義**: + - **入力**: + - パラメータ名: 型、説明 + - パラメータ名: 型、説明 + - **出力**: + - レスポンス形式 + - 成功時の戻り値 + - エラー時の戻り値 +- **制約・注意事項**（必要な場合のみ）: + - [制約事項や注意点] + +### 機能2: [機能名] +... + +## 非機能要件 + +### セキュリティ（必須） +- **認証・認可要件**: [steering/tech.mdから関連する標準を参照] +- **データ暗号化**: [要件] +- **監査ログ**: [要件] +- **セキュリティ標準**: [steering/tech.mdのセキュリティ要件を参照] + +[ユーザーが選択した非機能要件のみ以下に含める] + +### パフォーマンス（選択時のみ） +- **レスポンスタイム要件**: [具体的な数値] +- **同時接続数**: [具体的な数値] +- **データ処理量**: [具体的な数値] +- **スループット目標**: [具体的な数値] + +### 可用性（選択時のみ） +- **稼働率目標**: [例: 99.9%] +- **ダウンタイム許容範囲**: [例: 月間43分以内] +- **障害復旧時間**: [RTO/RPO] +- **監視要件**: [監視項目] + +### 保守性（選択時のみ） +- **コード品質基準**: [steering/tech.mdの品質標準を参照] +- **ドキュメント要件**: [要求されるドキュメント] +- **技術的負債の管理**: [方針] +- **リファクタリング方針**: [方針] + +### ユーザビリティ（選択時のみ） +- **UI/UX要件**: [要件] +- **アクセシビリティ**: [WCAG準拠レベルなど] +- **多言語対応**: [対応言語] +- **レスポンシブデザイン**: [対応デバイス] + +## データ要件 + +### データモデル概要 +[主要なデータエンティティとその関係] + +### データ保持期間 +[データ種別ごとの保持期間] + +### データ移行要件 +[既存データからの移行が必要な場合] + +## インターフェース要件 + +### 外部システム連携 +[連携する外部システム] + +### API仕様概要 +[APIの概要、詳細はtechnical-details.mdで定義] + +### データフォーマット +[JSON, XML, CSVなど] + +## 制約条件（選択時のみ） + +### 技術的制約 +[steering/tech.mdから関連する制約を参照] + +### ビジネス的制約 +[steering/product.mdから関連する制約を参照] + +### 法的・規制上の制約 +[GDPR, 個人情報保護法など] +``` + +**生成時の注意点**: +- **⚠️ 重要**: 詳細であれば詳細であるほど良いわけではない。必要な部分だけを必要なだけ書くこと +- **⚠️ 重要**: 推測される開発期間、工数、見積もり時間などは一切記載しないこと +- **⚠️ 重要**: 「将来的に必要になる」「今後〜が必要」といった適当な推測に基づいた記述は禁止 +- 不明なところは勝手に決めずに「**不明**」と明記し、複数の案（案A、案B、案Cなど）を記述すること +- ステアリングドキュメントの情報を積極的に参照・活用すること +- 実装Phase番号は空欄にする（plan-phasesで決定後に追加） + +### 5. 完了報告 + +``` +✅ 詳細要件仕様書を作成しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 作成先: specs/[taskname]/specification.md +📝 機能要件: [N]件 + +💡 次のアクション: + - 技術詳細化: `/sdd:define-technical [taskname]` + - 不明点の明確化: `/sdd:clarify-spec [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: ステアリングドキュメントを必ず参照し、プロジェクトの方針や標準に準拠すること +- 不明なところは勝手に決めずに「**不明**」と明記すること +- ユーザーが選択しなかった非機能要件セクションは含めないこと +- specification.mdは機能要件の詳細を記述する場所（技術実装の詳細はtechnical-details.mdで記述） + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +ドキュメント生成後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標・ターゲットユーザーとの整合性 +- tech.mdのセキュリティ要件との整合性 +- structure.mdのプロジェクト構造との整合性 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +ドキュメント生成後、内部的に仕様書間の矛盾を確認： +- overview.mdとspecification.mdの機能定義の整合性 +- データ要件と機能要件の整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/define-technical.md b/commands/define-technical.md new file mode 100644 index 0000000..2e24d67 --- /dev/null +++ b/commands/define-technical.md @@ -0,0 +1,278 @@ +--- +argument-hint: <タスク名> +description: 技術詳細とアーキテクチャ設計を作成 +allowed-tools: ["Read", "Write", "Task", "AskUserQuestion"] +--- + +# 技術詳細ドキュメントを作成します + +タスクの技術仕様とアーキテクチャ設計を詳細化し、`technical-details.md` を生成します。 + +【対象タスク名】 +$ARGUMENTS + +## 実行手順 + +### 0. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトの技術標準を把握： + +- `specs/_steering/tech.md` - **最重要**: 技術スタック、アーキテクチャパターン、開発標準 +- `specs/_steering/structure.md` - プロジェクト構造、命名規則 +- `specs/_steering/product.md` - プロダクト方針 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。先に `/sdd:steering` を実行することを推奨します。」 + +**重要**: tech.mdに記載されている技術スタックとアーキテクチャパターンを**必ず尊重**してください。 + +### 1. タスクディレクトリの確認 + +タスク名が指定されている場合: +- `specs/[taskname]/` ディレクトリの存在を確認 +- `specs/[taskname]/overview.md` および `specs/[taskname]/specification.md` が存在するか確認 + +タスク名が指定されていない場合: +- `specs/` ディレクトリ内の利用可能なタスクをリスト表示 +- **AskUserQuestionツールを使用**してどのタスクについて作業するかユーザーに選択を求める + +### 2. 既存ドキュメントの読み込み + +以下のドキュメントを読み込み、技術詳細化に必要な情報を抽出： + +- `specs/[taskname]/overview.md` - プロジェクト概要、主要機能 +- `specs/[taskname]/specification.md` - 機能要件、データ要件、インターフェース要件 +- `specs/_steering/tech.md` - **既存の技術スタック、アーキテクチャパターン** +- `specs/_steering/structure.md` - コード構造、命名規則 + +### 3. technical-details.mdの生成 + +`specs/[taskname]/technical-details.md` を生成： + +```markdown +# 技術詳細ドキュメント + +## アーキテクチャ + +### システム構成図 +[Mermaid記法でシステム構成を図示] + +```mermaid +graph TB + Client[クライアント] + API[APIサーバー] + DB[データベース] + + Client --> API + API --> DB +``` + +### 技術スタック + +**重要**: 以下は `specs/_steering/tech.md` に準拠しています。 + +#### 言語・ランタイム +- **言語**: [steering/tech.mdから取得] +- **ランタイム**: [steering/tech.mdから取得] +- **フレームワーク**: [steering/tech.mdから取得] + +#### 主要ライブラリ +[steering/tech.mdのKey Dependencies/Librariesを参照] + +このタスク固有の追加ライブラリ: +- [タスク固有のライブラリ] + +### インフラ構成 +[デプロイ環境、インフラ構成] + +## 技術選定（タスク固有の技術のみ） + +**注意**: steering/tech.md で既に定義されている技術については記載不要です。このタスク固有の技術選定のみ記載してください。 + +#### [技術名]（必要な場合のみ） +- **採用理由**: [1-2行で簡潔に] +- **steering/tech.mdとの関係**: [準拠/逸脱の明記] + +技術選定が不要な場合: 「steering/tech.mdの標準技術を使用」と記載 + +## データ設計 + +### データモデル + +[specification.mdのデータ要件を具体的なスキーマに変換] + +#### エンティティ図 + +```mermaid +erDiagram + User ||--o{ Post : creates + User { + int id PK + string email + string name + } + Post { + int id PK + int user_id FK + string title + text content + } +``` + +### データベーススキーマ + +**重要**: steering/tech.md で定義されているデータベース技術を使用 + +#### [テーブル1] +```sql +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + email VARCHAR(255) UNIQUE NOT NULL, + name VARCHAR(100) NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +### データフロー +[データの流れを図示] + +## API設計 + +### エンドポイント一覧 + +**命名規約**: steering/structure.md の規約に準拠 + +| メソッド | パス | 説明 | 入力 | 出力 | +|---------|------|------|------|------| +| GET | /api/users | ユーザー一覧取得 | クエリパラメータ | User[] | +| POST | /api/users | ユーザー作成 | UserInput | User | +| GET | /api/users/:id | ユーザー詳細取得 | id | User | +| PUT | /api/users/:id | ユーザー更新 | id, UserInput | User | +| DELETE | /api/users/:id | ユーザー削除 | id | 成功/失敗 | + +### リクエスト/レスポンス仕様（必要な場合のみ） + +複雑なAPI仕様がある場合のみ詳細を記載。標準的なCRUD操作の場合は省略可。 + +#### [エンドポイント名]（必要な場合のみ） +- **入力**: [JSON例] +- **出力**: [JSON例] +- **エラー**: [エラーコード一覧] + +### 認証・認可 + +**重要**: steering/tech.md のセキュリティ要件に準拠 + +- **認証方式**: [JWT/Session/OAuth2 - steering/tech.mdから] +- **認可方式**: [RBAC/ABAC] +- **トークン管理**: [保存場所、有効期限] + +## セキュリティ + +**重要**: specification.md および steering/tech.md のセキュリティ要件に準拠 + +### セキュリティ要件 +[specification.mdから取得] + +### 実装方針 +- **認証**: [実装方法] +- **認可**: [実装方法] +- **データ暗号化**: [実装方法] +- **監査ログ**: [実装方法] + +## パフォーマンス要件（ユーザー指定時のみ） + +[specification.mdで指定された場合のみ含める] + +- **レスポンスタイム**: [目標値と測定方法] +- **スループット**: [目標値と測定方法] +- **最適化方針**: [具体的な最適化手法] + +## 開発環境（ユーザー指定時のみ） + +**重要**: steering/tech.md の開発環境に準拠 + +### 必要なツール +[steering/tech.md の Required Tools を参照] + +このタスク固有の追加ツール: +- [タスク固有のツール] + +### セットアップ手順 +```bash +# 1. 依存関係のインストール +[コマンド] + +# 2. 環境変数の設定 +[コマンド] + +# 3. データベースのセットアップ +[コマンド] + +# 4. 開発サーバーの起動 +[コマンド] +``` + +## テスト戦略（ユーザー指定時のみ） + +**重要**: steering/tech.md のテスト標準に準拠 + +### テストの種類 +- **単体テスト**: [フレームワーク、カバレッジ目標] +- **統合テスト**: [範囲、実行タイミング] +- **E2Eテスト**: [ツール、シナリオ] + +### カバレッジ目標 +[steering/tech.md から取得、またはタスク固有の目標] +``` + +**生成時の注意点**: +- **⚠️ 最重要**: steering/tech.md に記載されている技術スタックを**必ず使用**すること +- **⚠️ 重要**: steering/tech.md から逸脱する場合は、明確な理由を記述すること +- **⚠️ 重要**: steering/structure.md の命名規約、コード構造に準拠すること +- **⚠️ 重要**: 詳細であれば詳細であるほど良いわけではない。必要な部分だけを必要なだけ書くこと +- 不明なところは勝手に決めずに「**不明**」と明記し、複数の案（案A、案B、案Cなど）を記述すること +- specification.mdは機能要件の詳細を、technical-details.mdは技術実装の詳細を記述し、役割を明確に分離すること + +### 4. 完了報告 + +``` +✅ 技術詳細ドキュメントを作成しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 作成先: specs/[taskname]/technical-details.md +📝 エンドポイント数: [N]件 + +💡 次のアクション: + - Phase計画: `/sdd:plan-phases [taskname]` + - 不明点の明確化: `/sdd:clarify-spec [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 最重要**: steering/tech.md を必ず参照し、プロジェクトの技術標準に準拠すること +- steering/tech.md から逸脱する場合は、明確な理由と承認を得ること +- specification.mdとの役割分担を明確にする（機能要件 vs 技術実装） +- 不明なところは勝手に決めずに「**不明**」と明記すること + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +ドキュメント生成後、内部的にステアリングドキュメントとの整合性を確認： +- tech.mdの技術スタックとの整合性（最重要） +- structure.mdの構造規約との整合性 +- product.mdのビジネス目標との整合性 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +ドキュメント生成後、内部的に仕様書間の矛盾を確認： +- specification.mdとtechnical-details.mdのデータ設計の整合性 +- API設計と機能要件の整合性 +- データモデルとAPI仕様の整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/help.md b/commands/help.md new file mode 100644 index 0000000..5043ff8 --- /dev/null +++ b/commands/help.md @@ -0,0 +1,449 @@ +--- +description: SDDワークフローの全体像とコマンド一覧を表示 +--- + +# SDDワークフローガイド + +SDDは**Specification-Driven Development（仕様駆動開発）**の略で、明確な仕様書に基づいて段階的に実装を進める開発手法です。 + +## 基本ワークフロー + +``` +0. ステアリングドキュメント作成（初回のみ） + ↓ +1. タスク初期化・実装計画 + ├── タスク骨格作成 + ├── 実装概要・調査項目特定 + └── 調査実施 + ↓ +2. 要件・技術詳細の定義 + ├── 要件定義 + ├── 技術詳細作成 + └── 実現可能性検証 + ↓ +3. 仕様の検証・明確化 + ├── 不明箇所の明確化 + └── 矛盾チェック + ↓ +4. Phase構成の決定 + ↓ +5. Phase詳細計画（各Phaseごと） + ↓ +6. Phase実装 + ├── Phase実装 + └── ドキュメント同期 + ↓ +7. Phase検証 + ├── ドキュメント検証 + ├── 要件検証 + └── 品質検証 + ↓ +8. 次Phaseへ（5に戻る） +``` + +## コマンド一覧と使用順序 + +### 🎯 Phase 0: ステアリングドキュメント作成（初回のみ） + +#### `/sdd:steering` +プロジェクト全体の永続的なコンテキストを管理します。 + +**生成されるファイル**: +- `specs/_steering/product.md` - プロダクト方針、ターゲットユーザー、ビジネス目標 +- `specs/_steering/tech.md` - 技術スタック、アーキテクチャ、開発標準 +- `specs/_steering/structure.md` - プロジェクト構造、命名規則、コード組織原則 +- `specs/_steering/principles.md` - 開発原則（TDD、SOLID、YAGNI） + +**実行モード**: +- **Bootstrap Mode（初期作成）**: 既存プロジェクトから情報を抽出して自動生成 +- **Sync Mode（更新）**: プロジェクトの変更を検出して更新提案 + +**重要**: 全ての `/sdd:*` コマンドは自動的にステアリングドキュメントを読み込みます + +**次のステップ**: タスク初期化へ + +--- + +### 📝 Phase 1: タスク初期化・実装計画 + +#### `/sdd:init-task <計画の説明>` +新しいタスクのスケルトンを作成します（最小限の情報のみ）。 + +**生成されるファイル**: +- `specs/{taskname}/overview.md` - プロジェクト概要（実装概要と調査項目は未記入） + +**次のステップ**: `/sdd:plan-implementation {taskname}` + +#### `/sdd:plan-implementation <タスク名>` +実装概要と調査項目を特定してoverview.mdに追加します。 + +**更新されるファイル**: +- `specs/{taskname}/overview.md` - 実装概要と調査項目表を追加 + +**次のステップ**: `/sdd:conduct-research {taskname}` + +#### `/sdd:conduct-research <タスク名> [調査項目名]` +overview.mdの調査項目を実施し、個別ファイルとして保存します。 + +**生成されるファイル**: +- `specs/research/[調査項目名].md` - 調査結果（結論、詳細、関連タスク） + +**更新されるファイル**: +- `specs/{taskname}/overview.md` - 調査項目表の状態を「完了」に更新 + +**役割**: +- 技術的な調査・検証（AIが自律的に実施） +- ライブラリ選定、実装方法の検証、パフォーマンス測定など + +**vs clarify-spec**: +- `conduct-research`: AIが調べる（技術的検証） +- `clarify-spec`: ユーザーに聞く（ビジネス要件） + +**次のステップ**: `/sdd:define-requirements {taskname}`（全調査完了後） + +--- + +### 📋 Phase 2: 要件・技術詳細の定義 + +#### `/sdd:define-requirements <タスク名>` +機能要件と非機能要件を定義します。 + +**生成されるファイル**: +- `specs/{taskname}/specification.md` - 機能要件、非機能要件 + +**特徴**: +- 非機能要件は選択式（セキュリティは常に含む） +- ステアリングドキュメントと整合性を保つ + +**次のステップ**: `/sdd:define-technical {taskname}` + +#### `/sdd:define-technical <タスク名>` +技術仕様と設計を定義します。 + +**生成されるファイル**: +- `specs/{taskname}/technical-details.md` - 技術スタック、アーキテクチャ、API設計 + +**重要**: `specs/_steering/tech.md` の技術方針を尊重（逸脱する場合は理由を明記） + +**次のステップ**: `/sdd:validate-feasibility {taskname}` + +#### `/sdd:validate-feasibility <タスク名>` +technical-details.mdの実現可能性を検証します。 + +**検証内容**: +- 既存プロジェクトとの互換性 +- 技術スタックの整合性 +- 実装可能性 + +**更新されるファイル**: +- `specs/{taskname}/technical-details.md` - 実プロジェクトとの整合性を確認・修正 + +**次のステップ**: `/sdd:plan-phases {taskname}` + +--- + +### 🔍 Phase 3: 仕様の検証・明確化 + +#### `/sdd:clarify-spec <タスク名>` +仕様書内の不明点（ビジネス要件）をユーザーに質問します。 + +**対象**: +- 「**不明**」とマークされた箇所 +- 複数の案がある箇所（案A、案B、案C） + +**更新されるファイル**: +- `specs/{taskname}/` 配下の全ドキュメント - 「**不明**」箇所を更新 + +**vs conduct-research**: +- `clarify-spec`: ユーザーに聞く（ビジネス要件） +- `conduct-research`: AIが調べる（技術的検証） + +**使用タイミング**: 仕様書に不明箇所がある場合、いつでも実行可能 + +#### `/sdd:contradiction-check <タスク名>` +仕様書間の矛盾を検出します。 + +**チェック項目**: +- Phase情報の矛盾（overview.md ⇔ tasks/phase*.md） +- 機能の矛盾（overview.md ⇔ specification.md ⇔ technical-details.md） +- データ設計の矛盾（specification.md ⇔ technical-details.md） + +**使用タイミング**: 仕様変更時、実装中の疑問が生じた際、Phase完了前など + +--- + +### 🗂️ Phase 4: Phase構成の決定 + +#### `/sdd:plan-phases <タスク名>` +調査完了後、Phase構成をoverview.mdに追加します。 + +**前提条件**: `overview.md` の全調査項目が「完了」状態であること + +**追加内容**: +- Phase名、目標、依存関係、成果物 +- 適切な数のPhaseを生成（プロジェクトの複雑度に応じて柔軟に決定） +- ユーザー承認後にoverview.mdを更新 + +**重要**: 詳細なタスク計画は `/sdd:breakdown-phase` で個別に作成 + +**次のステップ**: `/sdd:breakdown-phase {taskname} 1` + +--- + +### 📊 Phase 5: Phase詳細計画 + +#### `/sdd:breakdown-phase <タスク名> ` +指定されたPhaseの詳細タスク計画を生成します。 + +**引数**: +- `<タスク名>` - タスク名（必須） +- `` - Phase番号（必須、例: 1, 2, 3） + +**生成されるファイル**: +- `specs/{taskname}/tasks/phase{N}-{name}.md` - 指定Phaseの詳細計画 + +**各Phase計画書の内容**: +- タスク一覧（タスク番号、TDDステップ） +- 各タスクの詳細説明 +- 依存関係 +- テスト戦略 + +**重要**: Phase構成は `/sdd:plan-phases` で事前に決定されている必要があります + +**次のステップ**: `/sdd:implement-phase {taskname} {N}.1` + +--- + +### 💻 Phase 6: Phase実装 + +#### `/sdd:implement-phase [phase.task]` +Phase計画書に基づいて実装作業を行います。 + +**引数**: +- `` - タスク名のみ: Phase 1から開始 +- ` .` - 指定したPhaseとタスクから開始 + +**実行内容**: +- ステアリングドキュメントと仕様書の読み込み +- 実装計画の提示 +- コードとテストの実装 +- 品質チェック +- Phase計画書の状態更新 + +**次のステップ**: +- 作業途中で中断する場合: `/sdd:sync-spec` +- Phase完了後: `/sdd:verify-phase` + +#### `/sdd:sync-spec [taskname] [phase番号]` +実装状況を調査してPhase計画書とoverview.mdを同期します。 + +**実行内容**: +- コードベースから実装状況を推測 +- タスク完了状況を判定 +- Phase計画書とoverview.mdを更新 + +**引数省略時**: 会話のコンテキストから自動推測 + +**次のステップ**: 実装を続ける場合は `/sdd:implement-phase` + +--- + +### ✅ Phase 7: Phase検証 + +#### `/sdd:verify-phase ` +Phase完了時の統合検証を実行します。 + +**検証内容**: +1. ドキュメント検証（`/sdd:verify:docs`） +2. 要件検証（`/sdd:verify:requirements`） +3. 品質検証（`/sdd:verify:quality`） + +**総合評価**: +- ✅ Phase完了可能 +- ⚠️ 一部に問題あり +- ❌ 重大な問題あり + +**サブコマンド**: +- `/sdd:verify:docs ` - ドキュメント検証 +- `/sdd:verify:requirements ` - 要件検証 +- `/sdd:verify:quality ` - 品質検証 + +**次のステップ**: +- ✅の場合: 次のPhaseへ進む（Phase 5に戻る） +- ⚠️/❌の場合: 問題を解決して再検証 +- 全Phase完了: `/sdd:archive-spec {taskname}` + +--- + +### 📦 タスク管理 + +#### `/sdd:list-specs` +すべてのspecの一覧とステータスを表示し、specs/status.mdに保存します。 + +**表示内容**: +- タスク名 +- ステータス（未着手/進行中/完了） +- Phase進捗（Phase N (完了数/総数)） +- 最終更新日 +- 次のコマンド + +**生成されるファイル**: +- `specs/status.md` - 全タスクの進捗状況 + +**使用タイミング**: 全体の進捗状況を確認したい時 + +#### `/sdd:archive-spec` +完了または不要になったspecsをアーカイブします。 + +**実行内容**: +- タスク一覧を表示 +- 「完了」または「却下」のタスクのみを対象 +- `specs/_archived/{taskname}/`に移動 + +**使用タイミング**: 全Phase完了後、タスクが不要になった時 + +--- + +### 🧭 ナビゲーション + +#### `/sdd:next-step ` +タスクの現在の状態を分析して、次に実行すべきコマンドを提案します。 + +**使用タイミング**: 次に何をすべきか分からない時 + +#### `/sdd:help` +このガイドを表示します。SDDワークフローの全体像とコマンド一覧を確認できます。 + +--- + +## 📊 ディレクトリ構造 + +``` +specs/ +├── _steering/ # プロジェクト全体の永続的コンテキスト +│ ├── product.md # プロダクト方針 +│ ├── tech.md # 技術スタック +│ ├── structure.md # プロジェクト構造 +│ └── principles.md # 開発原則 +├── research/ # 調査結果の個別ファイル +│ ├── [調査項目名].md +│ └── ... +├── {taskname}/ +│ ├── overview.md # プロジェクト概要、Phase構成、調査項目表 +│ ├── specification.md # 機能要件と非機能要件 +│ ├── technical-details.md # 技術仕様と設計 +│ └── tasks/ +│ ├── phase1-{name}.md # Phase 1 実装計画 +│ ├── phase2-{name}.md # Phase 2 実装計画 +│ └── ... +├── status.md # 全タスクのステータス一覧 +└── _archived/ + └── {taskname}/ # アーカイブされたタスク +``` + +--- + +## 💡 よくある使い方 + +### 初めてSDDを使う（プロジェクト全体で1回のみ） +``` +/sdd:steering +``` + +### 新しいタスクを始める +``` +# 1. タスク初期化 +/sdd:init-task <計画の説明> + +# 2. 実装概要と調査項目を特定 +/sdd:plan-implementation {taskname} + +# 3. 調査実施 +/sdd:conduct-research {taskname} + +# 4. 要件と技術詳細を定義 +/sdd:define-requirements {taskname} +/sdd:define-technical {taskname} + +# 5. 実現可能性検証 +/sdd:validate-feasibility {taskname} + +# 6. 不明点の明確化・矛盾チェック +/sdd:clarify-spec {taskname} +/sdd:contradiction-check {taskname} + +# 7. Phase構成を決定 +/sdd:plan-phases {taskname} + +# 8. Phase詳細計画を作成（各Phaseごと） +/sdd:breakdown-phase {taskname} 1 +/sdd:breakdown-phase {taskname} 2 +# ... + +# 9. Phase実装を開始 +/sdd:implement-phase {taskname} +``` + +### Phase実装を続ける +``` +/sdd:implement-phase {taskname} {phase}.{task} +``` + +### 作業を中断する前に +``` +/sdd:sync-spec +``` + +### Phase完了時 +``` +/sdd:verify-phase {taskname} {phase} +``` + +### タスクの状態を確認したい時 +``` +/sdd:list-specs +``` + +### 次に何をすべきか分からない時 +``` +/sdd:next-step {taskname} +``` + +### タスク完了時・不要になった時 +``` +/sdd:archive-spec +``` + +--- + +## 🆕 ワークフローの特徴 + +### ステアリングドキュメント +- プロジェクト全体の「永続的メモリ」として機能 +- 全ての `/sdd:*` コマンドが自動的に読み込む +- Bootstrap Modeで既存プロジェクトから自動抽出 +- principles.md で開発原則（TDD、SOLID、YAGNI）を定義 + +### 調査ファースト +- Phase構成の決定前に技術調査を完了 +- `overview.md` の調査項目表で調査を管理 +- `/sdd:conduct-research` で技術的検証を実施 +- 調査結果は `specs/research/` に個別ファイルとして保存 + +### Phase構成の段階的作成 +1. `/sdd:plan-implementation` で実装概要と調査項目を特定 +2. `/sdd:conduct-research` で調査を完了 +3. `/sdd:plan-phases` でPhase構成のみを決定 +4. `/sdd:breakdown-phase` で各Phaseの詳細計画を個別に作成 +5. Phase実装前に詳細計画を見直し可能 + +### 内部品質チェック +- SubAgent（steering-reviewer、contradiction-checker）による内部チェック +- **重要**: チェック結果はspecファイルに書かず、問題がある場合のみユーザーに報告 +- ステアリングドキュメントへの準拠チェック +- 仕様書間の矛盾チェック + +--- + +**最終更新**: 2025-01-05 +**コマンド数**: 21コマンド diff --git a/commands/implement-phase.md b/commands/implement-phase.md new file mode 100644 index 0000000..62d68b3 --- /dev/null +++ b/commands/implement-phase.md @@ -0,0 +1,267 @@ +--- +argument-hint: [phase.task] +allowed-tools: ["Read", "Write", "Edit", "Bash", "Task", "AskUserQuestion", "TodoWrite"] +--- + +# specs/[taskname]/配下の仕様書ドキュメントを読み込み、それに基づいて実装作業を行います + +以下の引数で指定されたタスクについて、仕様書に基づいた実装作業を行ってください。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `[taskname]` - タスク名のみ指定した場合、そのタスクの最初から作業開始 +- `[taskname] [phase].[task]` - Phase番号とタスク番号を指定した場合、そのタスクから作業開始 + - 例: `user-authentication 2.3` → user-authenticationのphase2のタスク3から開始 + +## 実行手順 + +### 0. TodoWriteで実装ステップをTodoリストに追加 + +コマンド実行時、最初に以下の4つのステップをTodoWriteツールでTodoリストに追加： + +``` +TodoWrite([ + { + content: "タスクとPhaseの特定", + activeForm: "タスクとPhaseを特定中", + status: "in_progress" + }, + { + content: "ステアリングドキュメントと仕様書の読み込み", + activeForm: "ステアリングドキュメントと仕様書を読み込み中", + status: "pending" + }, + { + content: "Phase状況の確認", + activeForm: "Phase状況を確認中", + status: "pending" + }, + { + content: "実装作業の実行", + activeForm: "実装作業を実行中", + status: "pending" + } +]) +``` + +その後、以下のステップを順番に実行し、各ステップ完了時にTodoの状態を更新： + +### 1. タスクとPhase/タスクの特定 +上記の引数を解析して作業対象を特定： + +1. **引数が指定されている場合** + - `[taskname]`のみ: specs/[taskname]/を対象とし、Phase 1から開始 + - `[taskname] [phase].[task]`: specs/[taskname]/を対象とし、指定されたPhaseとタスクから開始 + +2. **引数が指定されていない場合** + - `specs/`ディレクトリ内のサブディレクトリを一覧表示 + - 複数のタスクがある場合、ユーザーに選択させる： + 「どのタスクで作業しますか？」 + - [1] specs/user-authentication/ + - [2] specs/payment-integration/ + - [3] specs/admin-dashboard/ + - 単一のタスクのみの場合は自動選択 + +3. **指定されたタスクディレクトリが存在しない場合** + - エラーメッセージを表示: 「specs/[taskname]/ ディレクトリが見つかりません」 + - specs/配下の利用可能なタスクを一覧表示 + +### 2. ステアリングドキュメントの読み込み + +プロジェクト全体のコンテキストを把握するため、以下のステアリングドキュメントを読み込みます： + +**`specs/_steering/product.md`**: +- プロダクトの目的とビジョン +- ターゲットユーザー +- 主要機能とビジネス目標 + +**`specs/_steering/tech.md`**: +- 技術スタックとアーキテクチャ +- 開発標準（型安全性、コード品質、テスト戦略） +- 重要な技術的決定事項 + +**`specs/_steering/structure.md`**: +- プロジェクト構造と命名規則 +- コード組織原則 +- モジュール境界 + +**`specs/_steering/principles.md`**: +- 開発原則 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。プロジェクト固有のコンテキストなしで進めます。」 +- `/sdd:steering` コマンドでステアリングドキュメントを作成することを推奨 +- 処理は続行（ステアリングドキュメントは必須ではない） + +### 3. 仕様書の確認 +選択されたタスクディレクトリ（specs/[taskname]/）から以下のファイルを読み込んで内容を把握： + +1. **specs/[taskname]/overview.md** - プロジェクト全体の概要とPhase構成を理解 +2. **specs/[taskname]/specification.md** - 機能要件と非機能要件の詳細を確認 +3. **specs/[taskname]/technical-details.md** - 技術的な実装方針を確認 +4. **specs/[taskname]/tasks/phase{N}-{phaseName}.md** - 該当するPhaseの計画書を確認 + +### 4. 現在の状況確認 +以下を確認してユーザーに報告： +- 各Phaseの現在の状態（未着手/進行中/完了） +- 実装可能なPhaseの特定（依存関係を考慮） +- ブロッカーの有無 + +### 5. 作業開始位置の決定 + +#### 5-1. `[phase].[task]` が指定されている場合 +1. 指定されたPhaseファイル（phase{N}-{phaseName}.md）を読み込む +2. 指定されたタスク番号のタスクを特定 +3. そのタスクの依存関係を確認： + - 依存関係が満たされていない場合、警告を表示し、ユーザーに続行するか確認 + - 依存関係が満たされている場合、そのまま続行 +4. 指定されたタスクの詳細を表示し、実装計画に進む + +#### 5-2. `[phase].[task]` が指定されていない場合 +ユーザーに以下を質問： +「どのPhaseの作業を進めますか？」 + +選択肢： +- Phase {N}: {phaseName}（状態: 〇〇、依存関係: 〇〇） +- または、特定のタスク番号を指定（例: 2.3 でPhase 2のタスク3） + +### 6. タスクの確認と実行計画 +選択されたPhaseまたはタスクについて： + +1. **仕様の確認** + - specification.mdから該当機能の詳細仕様を抽出 + - technical-details.mdから技術的な実装方針を確認 + - Phase計画書から具体的なタスクとその依存関係を確認 + +2. **実行可能性の確認** + - 依存関係が満たされているか確認 + - ブロッカーがないか確認 + - 必要なライブラリやツールが揃っているか確認 + +3. **TodoWriteで実装タスクを追加** + + Phase計画書のタスクリストから、以下の形式でTodoWriteに実装用Todoを追加： + + ``` + - content: "{タスク名} の実装" + activeForm: "{タスク名} を実装中" + status: "pending" + ``` + + **重要**: + - Phase計画書のタスク1つにつき、Todoアイテム1つを作成 + - タスクの依存関係順に並べる + - 各Todoには以下の情報を含める： + - 実装対象のファイルパス + - 実装する機能の概要 + - テスト対象 + +4. **ユーザーに確認** + + 追加した実装用Todoリストを表示し、AskUserQuestionで確認： + 「この計画で実装作業を開始してよろしいですか？」 + + 承認された場合、次のステップへ進む + +### 7. 実装作業 +承認後、追加した実装用Todoを1つずつ実行： + +各Todoについて以下の手順で作業： + +1. **Todoを`in_progress`に更新** + +2. **実装** + - specification.mdの要件を満たすコードを実装 + - technical-details.mdの技術方針に従う + - 既存のコードベースとの整合性を保つ + - any型は絶対に使用しない + +3. **品質チェック** + - コードレビュー基準に従っているか確認 + - エラーハンドリングが適切か確認 + - 関数型プログラミングのスタイルを意識（map/filterの活用） + +4. **テスト** + - Phase計画書のテスト計画に従ってテストを実装 + - ユニットテスト + - 統合テスト（必要に応じて） + +5. **Todoを`completed`に更新** + +6. **次のTodoへ** - すべての実装Todoが完了するまで繰り返し + +### 8. 完了報告と状態更新 + +作業完了後の報告フォーマット： + +``` +✅ タスク [Phase.Task] の実装が完了しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 対象: specs/{taskname}/ - Phase {N}, Task {M} + +💡 次のアクション: + - 次のタスク実施: `/sdd:implement-phase {taskname} {phase}.{task+1}` + - Phase検証実施: `/sdd:verify-phase {taskname} {phase}` （Phase内の全タスク完了時） +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**Phase状態の更新**: +- specs/[taskname]/overview.mdのPhase状態を更新 +- 該当するspecs/[taskname]/tasks/phase{N}-{phaseName}.mdのタスク状態を更新 +- タスク目次の該当タスクの状態とTDDステップを更新 + +### 9. 品質チェックの実施 +作業完了前に必ず以下を確認： + +- [ ] 仕様書の要件を満たしているか +- [ ] 依存関係が適切に処理されているか +- [ ] エラーハンドリングが実装されているか +- [ ] テストが実装され、パスしているか +- [ ] any型を使用していないか +- [ ] 関数型のスタイルを意識しているか（配列操作など） +- [ ] 既存の類似実装を確認し、重複を避けているか +- [ ] 既存ライブラリで実現できないか検討したか + +## 重要な注意事項 + +- 実装中は仕様書（overview.md、specification.md、technical-details.md）を常に参照し、要件から逸脱しないこと +- Phase計画書の依存関係を必ず確認し、順序を守ること +- タスク・Phaseの状態を適切に更新すること +- 不明点や仕様の矛盾があれば、実装前にユーザーに確認すること + +## 使用例 + +1. タスク全体を最初から開始: + `/sdd:implement-phase user-authentication` + +2. Phase 2のタスク3から開始: + `/sdd:implement-phase user-authentication 2.3` + +3. 引数なしで対話的に選択: + `/sdd:implement-phase` + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +実装完了後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標との整合性 +- tech.mdのコーディング標準との整合性 +- structure.mdの命名規則・モジュール境界の遵守 +- principles.mdの開発原則との一致 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +実装完了後、内部的に仕様書間の矛盾を確認： +- 実装内容とPhase計画書の整合性 +- specification.mdとの整合性 +- technical-details.mdとの整合性 +- 依存関係のあるドキュメント間の矛盾 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/init-task.md b/commands/init-task.md new file mode 100644 index 0000000..a319a46 --- /dev/null +++ b/commands/init-task.md @@ -0,0 +1,126 @@ +--- +argument-hint: <計画の説明> +description: タスクの基本骨格を作成（ディレクトリとoverview.mdのみ） +allowed-tools: ["Read", "Write", "Task"] +--- + +# タスクの基本骨格を作成します + +計画の説明をもとに、タスクの基本骨格（ディレクトリとoverview.md）を作成します。 + +**重要**: このコマンドは最小限の情報のみ作成します。実装概要と調査項目は `/sdd:plan-implementation` で追加してください。 + +【計画内容】 +$ARGUMENTS + +## 実行手順 + +### 0. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針 +- `specs/_steering/tech.md` - 技術スタック +- `specs/_steering/structure.md` - プロジェクト構造 +- `specs/_steering/principles.md` - 開発原則 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。先に `/sdd:steering` を実行することを推奨します。」 +- AskUserQuestionツールで確認: + - 「ステアリングドキュメントなしで続行しますか？」 + - 選択肢: 「はい（続行）」「いいえ（中断して /sdd:steering を実行）」 +- 「いいえ」の場合は処理を中断 + +### 1. 引数チェック + +`$ARGUMENTS` が空の場合： +- `specs/` ディレクトリ配下の既存タスク一覧（ディレクトリ名）を取得 +- タスクが存在する場合、AskUserQuestionツールで「どのタスクに着手しますか？」と質問し、選択させる +- タスクが存在しない場合、「specs/配下にタスクがありません。計画内容を入力してください」とユーザーに伝える +- 選択されたタスクは既存のため、処理を終了（既存タスクの初期化は不要） + +`$ARGUMENTS` が指定されている場合： +- タスク名生成（手順2）へ進む + +### 2. タスク名の生成 + +計画内容から適切なタスク名（ディレクトリ名）を生成： + +- プロジェクト内容を端的に表す英数字とハイフンのみの名前 +- 例: `user-authentication`, `payment-integration`, `admin-dashboard`, `api-v2-migration` +- 生成したタスク名をユーザーに提示し、**AskUserQuestionツールで確認**を取る + +### 3. ディレクトリの確認と作成 + +1. 現在のディレクトリに `specs/` フォルダが存在するか確認 +2. 存在しない場合は、**AskUserQuestionツールで**「specs/ フォルダを作成してもよろしいですか？」と確認 +3. 確認が取れたら `specs/[taskname]/` ディレクトリを作成 + +### 4. overview.mdの生成 + +`specs/[taskname]/overview.md` を生成： + +```markdown +# [タスク名] + +## 目的 +[計画内容から「何を達成したいのか」を1-3行で記述] + +## スコープ +### 含まれるもの +- [計画内容から抽出] + +### 含まれないもの +- [計画内容から明示的に除外されているもの] +- [ステアリングドキュメント（product.md）のNon-Goalsから関連するもの] + +## 想定される成果物 +- [成果物1] +- [成果物2] +- [成果物3] + +--- + +**次のステップ**: `/sdd:plan-implementation [taskname]` で実装概要と調査項目を特定してください +``` + +**生成時の注意点**: +- 計画内容が曖昧な場合でも、無理に詳細化しない +- 不明な点は「**不明**」と明記 +- ステアリングドキュメントの情報を積極的に活用 +- **実装概要、調査項目、技術スタックは含めない**（plan-implementationで追加） + +### 5. 完了報告 + +```markdown +✅ タスクの基本骨格を作成しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 作成先: specs/[taskname]/ +📝 作成ファイル: overview.md + +💡 次のアクション: + - 実装概要と調査項目の特定: `/sdd:plan-implementation [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: このコマンドは最小限の情報（目的、スコープ、成果物）のみ作成します +- **⚠️ 重要**: 実装概要と調査項目は `/sdd:plan-implementation` で追加してください +- **⚠️ 重要**: ステアリングドキュメント（`specs/_steering/`）を必ず読み込み、プロジェクトのコンテキストを反映してください +- **⚠️ 重要** 不明なところは勝手に決めずに「**不明**」と明記すること +- 「将来的に必要になる」「今後〜が必要」といった適当な推測に基づいた記述は禁止 +- 現時点で明確に必要なことのみを記載すること + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +ドキュメント生成後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標とタスク目的の整合性 +- structure.mdのプロジェクト構造との整合性 +- principles.mdの開発原則との一致 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 diff --git a/commands/list-specs.md b/commands/list-specs.md new file mode 100644 index 0000000..dbb4e9b --- /dev/null +++ b/commands/list-specs.md @@ -0,0 +1,223 @@ +--- +description: すべてのspecの一覧とステータスを表示し、specs/status.mdに保存 +--- + +# spec一覧とステータスの表示・保存 + +`specs/` ディレクトリ配下のすべてのタスクを走査し、各タスクの進捗状況を集計して `specs/status.md` に保存します。 + +## 実行手順 + +### 1. specs/ディレクトリの確認 + +- `specs/` ディレクトリの存在を確認 +- 存在しない場合は、空のステータスファイルを作成して終了 + +### 2. タスク情報の収集 + +各タスクディレクトリ（`specs/*/`）について、以下の情報を収集： + +**⚠️ 重要**: `specs/_archived/` 配下のタスクは完全に無視します（アーカイブ済みタスクはノイズ） + +#### 2.1 基本情報の取得 +- タスク名（ディレクトリ名） +- 最終更新日時（ディレクトリ内のすべてのファイルの最新mtime） + +#### 2.2 仕様書の存在確認 +- `overview.md` の存在 +- `specification.md` の存在 +- `technical-details.md` の存在 + +#### 2.3 Phase情報の取得 + +**overview.mdから**: +- プロジェクト概要（「## プロジェクト概要」セクションの「目的と背景」または最初の数行を簡潔に取得） +- Phase数 +- 各Phaseの名前 +- 各Phaseの状態（未着手/進行中/完了） + +**tasks/ディレクトリから**: +- Phase計画書（`phase{N}-*.md`）の存在確認 + +#### 2.4 Phase進捗の集計 + +各Phase計画書（`specs/{taskname}/tasks/phase{N}-*.md`）から： + +**タスク進捗**: +```markdown +## タスク一覧 + +| # | タスク名 | 状態 | TDD | 説明 | +|---|---------|------|-----|------| +| 1 | ... | ✅完了 | Green | ... | +| 2 | ... | 🔄進行中 | Red | ... | +| 3 | ... | ⬜未着手 | - | ... | +``` + +- 各タスクの状態を集計 + - ✅完了: 完了カウント +1 + - 🔄進行中: 進行中カウント +1 + - ⬜未着手: 未着手カウント +1 + +#### 2.5 タスク全体のステータス判定 + +以下のロジックでタスクのステータスを判定： + +``` +if 仕様書が存在しない: + ステータス = "未着手" +else if すべてのPhaseが完了状態: + ステータス = "完了" +else if いずれかのPhaseが進行中または完了: + ステータス = "進行中" +else: + ステータス = "未着手" +``` + +#### 2.6 次に実行すべきコマンドの判定 + +`/sdd:next-step` コマンドと同様のロジックで判定： + +- 仕様書が存在しない → `/sdd:create-specs` +- 仕様書に「**不明**」がある → `/sdd:clarify-spec {taskname}` +- Phase計画書がない → `/sdd:break-down-phase {taskname}` +- Phase未着手 → `/sdd:implement-phase {taskname}` +- Phase進行中 → `/sdd:implement-phase {taskname} {phase}.{next_task}` +- Phase完了、未検証 → `/sdd:verify-phase {taskname} {phase}` +- Phase検証済み、次Phaseあり → `/sdd:implement-phase {taskname} {next_phase}.1` +- すべて完了 → `/sdd:archive-spec` + +### 3. ステータスファイルの生成 + +#### 3.1 データのソート + +1. ステータスでグループ化（未着手 → 進行中 → 完了） +2. 各グループ内で更新日時順（新しい順）にソート + +#### 3.2 Markdown生成 + +以下のような形式でstatus.mdを生成します。 + +**フォーマット:** +```markdown +# SDD Spec Status + +最終更新: {現在日時} + +## 次に実施すべきこと + +{進行中タスクがある場合: 進行中タスクの次のコマンド} +{進行中タスクがない場合: 最初の未着手タスクの次のコマンド} +{全て完了の場合: アーカイブを促すメッセージ} + +## タスク一覧 + +### 🔄 進行中 + +| タスク名 | Phase進捗 | 最終更新 | 次のコマンド | +|---------|----------|---------|-------------| +| {taskname} | Phase {N} ({completed}/{total}) | YYYY-MM-DD | `/sdd:implement-phase {taskname} {phase}.{task}` | + +### ⬜ 未着手 + +| タスク名 | 最終更新 | 次のコマンド | +|---------|---------|-------------| +| {taskname} | YYYY-MM-DD | `/sdd:create-specs` | + +### ✅ 完了 + +| タスク名 | 最終更新 | 次のコマンド | +|---------|---------|-------------| +| {taskname} | YYYY-MM-DD | `/sdd:archive-spec` | +``` + +**作成例:** +```markdown +# SDD Spec Status + +最終更新: 2025-10-31 14:30:00 + +## 次に実施すべきこと + +`/sdd:implement-phase user-authentication 1.4` + +## タスク一覧 + +### 🔄 進行中 + +| タスク名 | Phase進捗 | 最終更新 | 次のコマンド | +|---------|----------|---------|-------------| +| user-authentication | Phase 1 (3/5) | 2025-10-30 | `/sdd:implement-phase user-authentication 1.4` | +| payment-integration | Phase 2 (2/7) | 2025-10-29 | `/sdd:implement-phase payment-integration 2.3` | + +### ⬜ 未着手 + +| タスク名 | 最終更新 | 次のコマンド | +|---------|---------|-------------| +| admin-dashboard | 2025-10-28 | `/sdd:create-specs` | + +### ✅ 完了 + +| タスク名 | 最終更新 | 次のコマンド | +|---------|---------|-------------| +| database-setup | 2025-10-27 | `/sdd:archive-spec` | +``` + +### 4. ファイルの保存 + +- `specs/status.md` に保存 +- `specs/` ディレクトリが存在しない場合は作成 + +### 5. 完了メッセージの表示 + +``` +✅ Specステータスを更新しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 保存先: specs/status.md +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## エラーハンドリング + +### specs/ディレクトリが存在しない場合 + +```markdown +⚠️ specs/ディレクトリが見つかりません。 + +specs/ディレクトリを作成して、空のステータスファイルを生成します。 +``` + +→ 空のステータスファイルを作成 + +```markdown +# SDD Spec Status + +最終更新: {現在日時} + +## タスク一覧 + +タスクがまだ作成されていません。 + +新しいタスクを作成するには: +\``` +/sdd:create-specs +\``` +``` + +### タスクディレクトリが空の場合 + +- ステータス: "未着手" +- 次のコマンド: `/sdd:create-specs` + +### overview.mdが破損している場合 + +- エラーを記録しつつ、他のファイルから可能な限り情報を取得 +- 次のコマンド: `/sdd:clarify-spec {taskname}` （修復を促す） + +## 注意事項 + +- **⚠️ 重要**: このコマンドは読み取り専用です。既存のspecファイルは変更しません +- ステータスファイルは完全に再生成されます（手動編集は上書きされます） +- Phase進捗は各Phase計画書から自動計算されます +- 「次のコマンド」は推測であり、必ずしも最適とは限りません +- ファイルのmtimeを基に最終更新日時を判定するため、ファイルコピー時は正確でない場合があります diff --git a/commands/next-step.md b/commands/next-step.md new file mode 100644 index 0000000..4a7e2ba --- /dev/null +++ b/commands/next-step.md @@ -0,0 +1,230 @@ +--- +argument-hint: +--- + +# 次に実行すべきステップを提案 + +現在のタスクの状態を分析して、次に実行すべきコマンドを提案します。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `` - タスク名（省略時: specs/配下から選択） + +## 実行手順 + +### 1. タスクの特定 + +#### 引数が指定されている場合 +- `specs/{taskname}/` ディレクトリの存在を確認 +- 存在しない場合はエラーメッセージとspecs/配下のタスク一覧を表示 + +#### 引数が指定されていない場合 +- `specs/` 配下のタスクをリスト表示 +- AskUserQuestionで選択 + +### 2. タスクの状態分析 + +以下のファイルとディレクトリを確認して、タスクの進捗状況を判定： + +#### 仕様書ファイルの存在確認 +- `specs/{taskname}/overview.md` +- `specs/{taskname}/specification.md` +- `specs/{taskname}/technical-details.md` + +#### 仕様書の完成度チェック +- 「**不明**」マークの有無 +- 複数の案（案A、案B等）の有無 +- Phase概要と依存関係セクションの有無 + +#### Phase計画書の存在確認 +- `specs/{taskname}/tasks/` ディレクトリの存在 +- Phase計画書ファイル（`phase{N}-*.md`）の存在 + +#### Phase進捗の確認 +各Phase計画書から： +- タスクの状態（未着手/進行中/完了） +- Phase状態（未着手/進行中/完了） +- Phase完了条件のチェック状況 + +#### overview.mdのPhase状態 +- 各Phaseの状態 +- 依存関係の満たし方 + +### 3. 状態に基づく判定 + +分析結果から、タスクがどの段階にあるかを判定： + +#### 状態1: 仕様書が存在しない +→ 新規タスクの作成段階 + +#### 状態2: 仕様書は存在するが不完全 +- 「**不明**」マークがある +- 複数の案が残っている +→ 仕様の明確化が必要 + +#### 状態3: 仕様書は完成しているがPhase計画書がない +→ Phase分割計画が必要 + +#### 状態4: Phase計画書は存在するが未着手 +→ 実装開始が必要 + +#### 状態5: Phase実装中 +- 進行中または完了したタスクがある +- すべてのタスクは完了していない +→ 実装継続または仕様書同期が必要 + +#### 状態6: Phase完了（Phase完了条件未チェック） +- すべてのタスクが完了 +- Phase完了条件がチェックされていない +→ Phase検証が必要 + +#### 状態7: Phase検証済み（次Phaseあり） +- Phase完了条件がすべてチェック済み +- overview.mdで次Phaseが定義されている +→ 次Phaseの実装開始 + +#### 状態8: すべてのPhase完了 +- すべてのPhaseが完了状態 +→ タスク完了 + +### 4. 提案の表示 + +```markdown +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🎯 次のステップ提案 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📍 タスク: {taskname} + +## 現在の状態 + +{状態の詳細説明} + +### 仕様書の状態 +- overview.md: {存在/不完全/完成} +- specification.md: {存在/不完全/完成} +- technical-details.md: {存在/不完全/完成} +- 不明点: {数}箇所 +- 複数案: {数}箇所 + +### Phase進捗 +- Phase 1: {状態} - タスク完了: {completed}/{total} +- Phase 2: {状態} - タスク完了: {completed}/{total} +- ... + +### Phase完了条件 +- Phase 1: {checked}/{total} 項目 +- Phase 2: {checked}/{total} 項目 +- ... + +## 💡 次に実行すべきコマンド + +### 推奨: {コマンド名} + +**コマンド**: +``` +{実行すべきコマンド} +``` + +**理由**: +{なぜこのコマンドを実行すべきか} + +**実行後**: +{このコマンド実行後に何が得られるか} + +--- + +### 代替案（オプション） + +**1. {代替コマンド名}** +``` +{代替コマンド} +``` +{理由と実行後の状態} + +**2. {代替コマンド名}** +``` +{代替コマンド} +``` +{理由と実行後の状態} + +--- + +## 📚 ワークフロー全体を確認したい場合 + +``` +/sdd:help +``` + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 5. 状態別の提案例 + +#### 状態1の場合（仕様書が存在しない） +**推奨**: `/sdd:create-specs` +- 理由: タスクの仕様書がまだ作成されていません +- 実行後: overview.md、specification.md、technical-details.mdが生成されます + +#### 状態2の場合（仕様書は存在するが不完全） +**推奨**: `/sdd:clarify-spec {taskname}` +- 理由: 仕様書に{N}箇所の不明点があります +- 実行後: 不明点が明確化され、仕様が確定します + +**代替案**: +1. `/sdd:contradiction-check {taskname}` - 仕様の整合性を先に確認 +2. `/sdd:validate-feasibility {taskname}` - 実現可能性を先に検証 + +#### 状態3の場合（仕様書は完成しているがPhase計画書がない） +**推奨**: `/sdd:break-down-phase {taskname}` +- 理由: 仕様書は完成していますが、Phase別の実装計画がありません +- 実行後: specs/{taskname}/tasks/配下にPhase計画書が生成されます + +#### 状態4の場合（Phase計画書は存在するが未着手） +**推奨**: `/sdd:implement-phase {taskname}` +- 理由: Phase計画書は作成されていますが、実装が開始されていません +- 実行後: Phase 1のタスク1から実装が開始されます + +#### 状態5の場合（Phase実装中） +**推奨**: `/sdd:implement-phase {taskname} {current_phase}.{next_task}` +- 理由: Phase {current_phase}の実装が進行中です（{completed}/{total}タスク完了） +- 実行後: 次のタスク{next_task}の実装を続けます + +**代替案**: +1. `/sdd:sync-specs` - 作業を中断する前に現在の進捗を仕様書に記録 + +#### 状態6の場合（Phase完了、検証待ち） +**推奨**: `/sdd:verify-phase {taskname} {phase}` +- 理由: Phase {phase}のすべてのタスクが完了しましたが、検証がまだです +- 実行後: Phase完了条件が検証され、問題があれば指摘されます + +#### 状態7の場合（Phase検証済み、次Phaseあり） +**推奨**: `/sdd:implement-phase {taskname} {next_phase}.1` +- 理由: Phase {current_phase}が完了し、次のPhase {next_phase}に進めます +- 実行後: Phase {next_phase}の実装が開始されます + +#### 状態8の場合（すべてのPhase完了） +```markdown +🎉 おめでとうございます！ + +タスク「{taskname}」のすべてのPhaseが完了しました。 + +## 完了したPhase +- Phase 1: {name} ✅ +- Phase 2: {name} ✅ +- Phase 3: {name} ✅ +... + +## 次のアクション +- プロジェクトのデプロイやリリース準備 +- 新しいタスクの開始: `/sdd:create-specs` +``` + +## 注意事項 + +- **⚠️ 重要**: このコマンドは提案のみを行い、実際のコマンドは実行しません +- **⚠️ 重要**: 提案は現在のファイル状態から推測したものであり、必ずしも最適とは限りません +- 複数の選択肢がある場合、プロジェクトの状況に応じて判断してください +- Phase順序や依存関係を考慮して提案しますが、並行作業が可能な場合もあります diff --git a/commands/plan-implementation.md b/commands/plan-implementation.md new file mode 100644 index 0000000..26c60b6 --- /dev/null +++ b/commands/plan-implementation.md @@ -0,0 +1,196 @@ +--- +argument-hint: <タスク名> +description: 実装概要と調査項目を特定してoverview.mdに追加 +allowed-tools: ["Read", "Edit", "Task"] +--- + +# 実装概要と調査項目を特定します + +タスク名をもとに、overview.mdに実装概要と調査項目を追加します。 + +**重要**: このコマンドは実装の大枠（どんな機能を作るか）と調査項目を決定します。詳細な調査は `/sdd:conduct-research` で実施してください。 + +【タスク名】 +$ARGUMENTS + +## 実行手順 + +### 0. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針 +- `specs/_steering/tech.md` - 技術スタック +- `specs/_steering/structure.md` - プロジェクト構造 +- `specs/_steering/principles.md` - 開発原則 + +**ステアリングドキュメントが存在しない場合**: +- 警告メッセージを表示: 「⚠️ ステアリングドキュメントが見つかりません。先に `/sdd:steering` を実行することを推奨します。」 +- AskUserQuestionツールで確認: + - 「ステアリングドキュメントなしで続行しますか？」 + - 選択肢: 「はい（続行）」「いいえ（中断して /sdd:steering を実行）」 +- 「いいえ」の場合は処理を中断 + +### 1. 引数チェックとoverview.mdの読み込み + +`$ARGUMENTS` が空の場合： +- エラーメッセージ: 「タスク名を指定してください。例: `/sdd:plan-implementation user-authentication`」 + +`$ARGUMENTS` が指定されている場合： +- `specs/[taskname]/overview.md` の存在を確認 +- 存在しない場合: エラーメッセージ「overview.mdが見つかりません。先に `/sdd:init-task` を実行してください。」 +- 存在する場合: overview.mdを読み込み + +### 2. 実装する機能の特定 + +overview.mdの「目的」「スコープ」「想定される成果物」から、実装する機能を特定： + +**機能特定の流れ**: +1. overview.mdから実装すべき機能の候補を抽出 +2. **各機能について、AskUserQuestionで確認・選択させる** + - 例: 「ユーザー認証機能を実装しますか？」→ 「はい（必須）」「はい（任意）」「いいえ（不要）」 + - 例: 「認証方法はどうしますか？」→ 「JWT」「Session」「OAuth2」 + - 例: 「この機能の優先度は？」→ 「High（最優先）」「Medium（通常）」「Low（後回し可）」 +3. ユーザーが選択した機能のみをリストに追加 +4. 機能ごとに入出力イメージを記載 + +**技術スタックの決定**: +1. ステアリングドキュメント（tech.md）を確認 +2. **tech.mdに記載がない技術要素について、複数の選択肢がある場合はAskUserQuestionで選択させる** + - 例: 「フロントエンドフレームワークは？」→ 「React」「Vue」「Svelte」 + - 例: 「状態管理ライブラリは？」→ 「Redux」「Zustand」「Jotai」「不要」 +3. ユーザーが選択した技術スタックを記録 +4. **選択できなかった項目（調査が必要）は調査項目として抽出** + +### 3. 調査項目の特定 + +実装概要から、技術的に不明な点を抽出： + +**調査項目の判定基準（コマンド内部で使用、specには出力しない）**: +1. これは本当に技術的に不明な点か？ +2. ドキュメントを読めばわかることではないか？ +3. 一般的な実装パターンで解決できないか？ +4. 複数の選択肢があり、検証が必要か？ + +**調査項目として抽出すべきもの**: +- プロジェクト固有の技術的課題 +- 複数の技術の組み合わせで生じる不明点 +- パフォーマンスやセキュリティの具体的な検証が必要な項目 +- 技術選定（複数の選択肢から選ぶ必要がある） + +**調査項目として抽出すべきでないもの**: +- 「ライブラリ選定」のような当たり前の項目 +- 公式ドキュメントを読めばわかること +- 一般的な実装パターンで解決できること + +**調査項目の特定フロー**: +1. 実装概要から調査が必要そうな項目を**全て**抽出（制限なし） +2. **抽出した全ての項目について、1つずつAskUserQuestionで確認** + - 例: 「JWT認証のパフォーマンス検証が必要ですか？」→ 「はい」「いいえ」 + - 例: 「この技術選定は調査が必要ですか？」→ 「はい」「いいえ」 +3. ユーザーが「はい」と選択した項目のみを調査項目リストに追加 +4. **全ての候補について確認が完了するまで繰り返す** + +### 4. overview.mdへの追記 + +overview.mdに以下のセクションを追加： + +```markdown +## 実装概要 +### 実装する機能 +1. [機能名1] + - 概要: [1-2行で説明] + - 入力: [概要レベル] + - 出力: [概要レベル] + - 優先度: High/Medium/Low + +2. [機能名2] + - 概要: [1-2行で説明] + - 入力: [概要レベル] + - 出力: [概要レベル] + - 優先度: High/Medium/Low + +### 技術スタック（候補） +- フロントエンド: [候補] +- バックエンド: [候補] +- データベース: [候補] +- その他: [候補] + +## 調査項目 +| 状態 | 調査項目名 | 理由 | 概要 | +|------|-----------|------|------| +| 未着手 | [調査項目1] | [なぜこれが不明なのか] | - | +| 未着手 | [調査項目2] | [なぜこれが不明なのか] | - | + +--- + +**次のステップ**: +- 調査が必要: `/sdd:conduct-research [taskname]` +- 調査不要: `/sdd:define-requirements [taskname]` +``` + +**追記時の注意点**: +- 既存の「次のステップ」セクションは削除して上書き +- 調査項目がない場合は「調査項目なし。すぐに要件定義に進めます。」と記載 +- 不明な点は「**不明**」と明記 +- 「将来的に」「など」の使用を禁止 +- ユーザーがAskUserQuestionで選択した内容をそのまま記載（追加の確認は不要） + +### 5. 完了報告 + +調査項目がある場合: +```markdown +✅ 実装概要と調査項目を特定しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 更新先: specs/[taskname]/overview.md +📝 実装機能数: [N]件 +🔍 調査項目数: [N]件 + +💡 次のアクション: + - 調査実施: `/sdd:conduct-research [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +調査項目がない場合: +```markdown +✅ 実装概要を特定しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 更新先: specs/[taskname]/overview.md +📝 実装機能数: [N]件 +🔍 調査項目: なし + +💡 次のアクション: + - 要件定義: `/sdd:define-requirements [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: 調査が必要そうな項目は**全て**抽出し、各項目についてユーザーに判断を仰ぐこと +- **⚠️ 重要**: 調査項目の数に制限はありません。ユーザーが「必要」と判断した項目のみをリストに追加します +- **⚠️ 重要**: ステアリングドキュメント（`specs/_steering/`）を必ず読み込み、プロジェクトのコンテキストを反映してください +- **⚠️ 重要** 不明なところは勝手に決めずに「**不明**」と明記すること +- 「将来的に必要になる」「今後〜が必要」といった適当な推測に基づいた記述は禁止 +- 現時点で明確に必要なことのみを記載すること + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +ドキュメント更新後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標と実装機能の整合性 +- tech.mdの技術方針と技術スタック候補の適切性 +- structure.mdのプロジェクト構造との整合性 +- principles.mdの開発原則との一致 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +ドキュメント更新後、内部的に仕様書間の矛盾を確認： +- overview.md内の目的・スコープと実装機能の整合性 +- 調査項目と実装機能の関連性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/plan-phases.md b/commands/plan-phases.md new file mode 100644 index 0000000..424001b --- /dev/null +++ b/commands/plan-phases.md @@ -0,0 +1,278 @@ +--- +argument-hint: <タスク名> +description: Phase構成を決定してoverview.mdに追加（詳細なタスク分解はしない） +allowed-tools: ["Read", "Edit", "Task", "AskUserQuestion"] +--- + +# Phase構成を決定します + +調査完了後に、タスクをPhaseに分割する構成を決定し、`overview.md` に追加します。 + +**重要**: このコマンドは詳細なタスク分解を行いません。Phase構成（Phase数、名前、目標、依存関係）のみを決定します。 + +【対象タスク名】 +$ARGUMENTS + +## 実行手順 + +### 0. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針、ビジネス目標 +- `specs/_steering/tech.md` - 技術スタック、アーキテクチャパターン +- `specs/_steering/structure.md` - プロジェクト構造 +- `specs/_steering/principles.md` - 開発原則 + +### 1. タスクディレクトリの確認 + +タスク名が指定されている場合: +- `specs/[taskname]/` ディレクトリの存在を確認 +- 必須ファイルの存在確認: + - `overview.md` + - `specification.md` + - `technical-details.md` + +タスク名が指定されていない場合: +- `specs/` ディレクトリ内の利用可能なタスクをリスト表示 +- **AskUserQuestionツールを使用**してどのタスクについて作業するかユーザーに選択を求める + +### 2. 調査完了の確認 + +Phase分けを開始する前に、必ず調査が完了していることを確認: + +1. **overview.mdの調査セクション確認** + - `specs/[taskname]/overview.md` の調査項目表を読み込み + - 全ての調査項目の状態を確認 + +2. **調査ステータスの判定** + - 全て「完了」の場合: 次のステップへ進む + - 「未着手」がある場合: + - 警告メッセージを表示: 「⚠️ 調査が完了していません」 + - 未完了の調査項目をリスト表示 + - AskUserQuestionツールで確認して続行するか判断 + - 続行しない場合: `/sdd:conduct-research [taskname]` を推奨 + +### 3. 既存ドキュメントの分析 + +以下のドキュメントから情報を抽出してPhase構成を決定: + +#### overview.md +- 調査結果（調査セクションおよびspecs/research/配下の個別ファイル） +- 実装概要 + +#### specification.md +- 機能要件の詳細 +- 各機能の優先度 +- 非機能要件 + +#### technical-details.md +- 技術スタックと技術選定 +- データ設計とAPI設計 +- セキュリティ要件 +- アーキテクチャ構成 + +#### ステアリングドキュメント +- product.md: ビジネス優先順位、成功指標 +- tech.md: 技術的制約、開発標準 +- structure.md: プロジェクト構造 + +### 4. Phase構成の提案 + +#### Phase分けの基準 + +以下の基準でPhase構成を提案： + +1. **独立してデプロイ・リリース可能な単位** + - 各Phaseは独立して動作確認とリリースができる状態になる + - Phase完了時点で品質チェックに成功する状態 + +2. **機能の依存関係による分割** + - 後続Phaseが前Phaseの成果物に依存する構造 + - 並行開発可能な機能は明示 + +3. **リスクとビジネス価値による優先順位付け** + - 高リスク・高価値の機能は早期のPhaseで実装 + - 基盤機能 → コア機能 → 拡張機能の順に配置 + +**Phase数について**: +- Phase数に制約はありません +- プロジェクトの複雑度と機能の依存関係に応じて適切に分割してください + +#### Phase構成の生成 + +以下の情報を含むPhase構成を生成： + +```markdown +## Phase構成提案 + +### Phase 1: [Phase名] +- **目標**: [このPhaseで達成すること] +- **依存関係**: なし +- **成果物**: + - [成果物1] + - [成果物2] +- **含まれる主要機能**: + - [機能1]（specification.mdの機能X） + - [機能2]（specification.mdの機能Y） + +### Phase 2: [Phase名] +- **目標**: [このPhaseで達成すること] +- **依存関係**: Phase 1完了 +- **成果物**: + - [成果物1] + - [成果物2] +- **含まれる主要機能**: + - [機能3]（specification.mdの機能Z） + +### Phase 3: [Phase名] +- **目標**: [このPhaseで達成すること] +- **依存関係**: Phase 2完了 +- **成果物**: + - [成果物1] +- **含まれる主要機能**: + - [機能4]（specification.mdの機能W） + +## Phase依存関係図 + +```mermaid +graph TB + P1[Phase 1: [具体的なPhase名]] + P2[Phase 2: [具体的なPhase名]] + P3[Phase 3: [具体的なPhase名]] + + P1 --> P2 + P2 --> P3 +``` +``` + +### 5. ユーザーへの確認 + +**AskUserQuestionツールを使用**してPhase構成の妥当性を確認： + +``` +以下のPhase構成でよろしいですか？ + +[生成したPhase構成を表示] + +選択肢: +- 承認（このPhase構成でoverview.mdを更新） +- 修正が必要（Phase数、Phase名、依存関係などを調整したい） +- やり直し（Phase構成を再提案） +``` + +**「修正が必要」の場合**: +- どの部分を修正したいか質問 +- ユーザーの要望に基づいて再提案 +- 再度確認 + +### 6. overview.mdの更新 + +ユーザーの承認後、`specs/[taskname]/overview.md` に以下のセクションを追加： + +```markdown +## Phase概要と依存関係 + +### Phase 1: [Phase名] +- **開始日時**: （空欄） +- **状態**: 未着手 +- **目標**: [目標] +- **依存関係**: なし +- **成果物**: + - [成果物1] + - [成果物2] + +### Phase 2: [Phase名] +- **開始日時**: （空欄） +- **状態**: 未着手 +- **目標**: [目標] +- **依存関係**: Phase 1完了 +- **成果物**: + - [成果物1] + - [成果物2] + +### Phase 3: [Phase名] +- **開始日時**: （空欄） +- **状態**: 未着手 +- **目標**: [目標] +- **依存関係**: Phase 2完了 +- **成果物**: + - [成果物1] + +## Phase依存関係図 + +```mermaid +graph TB + P1[Phase 1: [具体的なPhase名]] + P2[Phase 2: [具体的なPhase名]] + P3[Phase 3: [具体的なPhase名]] + + P1 --> P2 + P2 --> P3 +``` + +## シーケンス図 + +主要な機能のシーケンス図をMermaid記法で記述: + +```mermaid +sequenceDiagram + participant User as ユーザー + participant Client as クライアント + participant API as APIサーバー + participant DB as データベース + + User->>Client: [アクション] + Client->>API: [リクエスト] + API->>DB: [データ操作] + DB-->>API: レスポンス + API-->>Client: レスポンス + Client-->>User: 結果表示 +``` +``` + +**重要**: 既存のoverview.mdの内容は保持し、上記セクションを追加 + +### 7. 完了報告 + +``` +✅ Phase構成を決定しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 更新先: specs/[taskname]/overview.md +📊 Phase数: [N]個 + +💡 次のアクション: + - Phase 1の詳細計画: `/sdd:breakdown-phase [taskname] 1` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: このコマンドは詳細なタスク分解を行いません（Phase構成のみ決定） +- **⚠️ 重要**: 調査が完了していない状態でPhase構成を決定すると、後で大きな手戻りが発生する可能性があります +- **⚠️ 重要**: ステアリングドキュメントを参照し、プロジェクトの方針に準拠してください +- Phase数はプロジェクトの規模と複雑さに応じて柔軟に決定してください（2個でも6個以上でも可） +- 各Phaseは独立してデプロイ・リリース可能な単位にする +- Phase間の依存関係を明確にする + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +Phase構成追加後、内部的にステアリングドキュメントとの整合性を確認： +- product.mdのビジネス目標とPhaseの目標の整合性 +- tech.mdのアーキテクチャ方針とPhase分割の適切性 +- structure.mdのモジュール境界とPhase境界の適切性 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +Phase構成追加後、内部的に仕様書間の矛盾を確認： +- Phase構成と機能要件の整合性 +- Phase構成と技術詳細の整合性 +- Phase間の依存関係の妥当性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/steering.md b/commands/steering.md new file mode 100644 index 0000000..65081d4 --- /dev/null +++ b/commands/steering.md @@ -0,0 +1,502 @@ +--- +description: プロジェクト全体のステアリングドキュメントを作成・更新 +--- + +# プロジェクト全体のステアリングドキュメント管理 + +このコマンドは、プロジェクト全体の永続的なコンテキスト（プロダクト方針、技術スタック、プロジェクト構造）をステアリングドキュメントとして管理します。 + +**重要**: 全ての `/sdd:*` コマンドは自動的にステアリングドキュメントを読み込み、プロジェクトの一貫性を保ちます。 + +## 実行手順 + +### 1. モード判定 + +`specs/_steering/` ディレクトリの状態を確認： + +- **Bootstrap Mode（初期作成）**: ディレクトリが存在しないか、コアファイルが不足 +- **Sync Mode（更新）**: 全てのコアファイルが存在 + +**コアファイル**: +- `product.md` - プロダクト方針、ターゲットユーザー、ビジネス目標 +- `tech.md` - 技術スタック、アーキテクチャパターン、開発標準 +- `structure.md` - プロジェクト構造、命名規則、コード組織原則 +- `principles.md` - 開発原則（TDD、SOLID、TypeScript固有の原則など） + +### 2. Bootstrap Mode（初期作成） + +#### 2.1 既存プロジェクト情報の収集 + +以下の情報を収集してステアリングドキュメント生成に活用： + +**プロダクト情報**: +- `README.md` の存在確認と内容読み取り +- パッケージマニフェスト（`package.json`, `pyproject.toml`, `Cargo.toml` など）からプロジェクト名と説明を抽出 + +**技術スタック情報**: +- `package.json` - Node.js依存関係、スクリプト、エンジンバージョン +- `tsconfig.json` / `jsconfig.json` - TypeScript/JavaScript設定 +- `pyproject.toml` / `requirements.txt` - Python依存関係 +- `Cargo.toml` - Rust依存関係 +- `go.mod` - Go依存関係 +- `.ruby-version` / `Gemfile` - Ruby依存関係 +- ビルドツール設定（`vite.config.ts`, `webpack.config.js`, `next.config.js` など） +- データベース関連（`prisma/schema.prisma`, ORM設定など） + +**プロジェクト構造情報**: +- ルートディレクトリの構造（`ls -la`） +- 主要ディレクトリ（`src/`, `lib/`, `app/`, `tests/` など）の存在確認 +- ファイル命名パターンの分析（kebab-case, camelCase, snake_case） + +**注意**: ファイルが見つからない場合はスキップし、テンプレート構造で生成 + +#### 2.2 ディレクトリ作成 + +```bash +mkdir -p specs/_steering +``` + +#### 2.3 ステアリングドキュメント生成 + +以下の3つのファイルを生成（収集した情報を反映）： + +##### `specs/_steering/product.md` + +```markdown +# Product Overview + +## Product Purpose + +[プロジェクトの目的] +- README.mdやpackage.jsonの説明から抽出 +- 存在しない場合はプレースホルダー + +**Vision (North Star)**: +[プロダクトのビジョン] + +**解決する問題**: +- [課題1] +- [課題2] + +## Target Users + +**Primary Archetype**: [主要ユーザー像] +- [特徴1] +- [特徴2] + +**ニーズと課題**: +- **ニーズ**: [ニーズ] +- **課題**: [課題] + +## Key Features + +このプロジェクトが提供する主要機能： + +1. **[機能カテゴリ1]**: [説明] +2. **[機能カテゴリ2]**: [説明] + +## Business Objectives + +- **[目標1]**: [説明] +- **[目標2]**: [説明] + +## Success Metrics + +**Quantitative Metrics**: +- **[指標名]**: [測定方法] + +**Qualitative Metrics**: +- **[指標名]**: [評価基準] + +## Product Principles + +1. **[原則1]**: [説明] +2. **[原則2]**: [説明] + +## Non-Goals / Guardrails + +このプロジェクトは以下の領域には**意図的に関与しない**： + +- **[非対象1]**: [理由] +- **[非対象2]**: [理由] +``` + +##### `specs/_steering/tech.md` + +```markdown +# Technology Stack + +## Architecture + +[システムアーキテクチャの概要] +- 既存プロジェクト構造から推測 +- モノリス/マイクロサービス/JAMstack など + +## Core Technologies + +### Primary Language(s) +- **Language**: [検出された言語] +- **Runtime**: [検出されたランタイム] +- **Framework**: [検出されたフレームワーク] + +### Key Dependencies/Libraries + +[package.jsonなどから抽出した主要ライブラリ] + +## Development Standards + +### Type Safety +[型安全性に関する方針] +- TypeScript strict mode の使用状況 +- 型定義の要求レベル + +### Code Quality +[コード品質ツール] +- ESLint, Prettier, Ruff などの設定状況 + +### Testing +[テスト戦略] +- テストフレームワーク（Jest, pytest など） +- カバレッジ要求 + +## Development Environment + +### Required Tools +[必要なツールとバージョン] +- Node.js, Python, Rust などのバージョン要求 +- package.jsonのenginesフィールドから抽出 + +### Common Commands +```bash +# Dev: [開発サーバー起動コマンド] +# Build: [ビルドコマンド] +# Test: [テストコマンド] +``` + +## Key Technical Decisions + +[重要な技術的決定とその理由] + +1. **[決定事項1]**: + - **理由**: [理由] + - **代替案**: [検討した代替案] + - **トレードオフ**: [トレードオフ] +``` + +##### `specs/_steering/structure.md` + +```markdown +# Project Structure + +## Directory Organization + +``` +[プロジェクト名]/ +├── [検出されたディレクトリ構造] +├── specs/ +│ └── _steering/ # ステアリングドキュメント +└── ... +``` + +**組織化の原則**: +- **[原則1]**: [説明] +- **[原則2]**: [説明] + +## Naming Conventions + +### ファイル名 +- **[パターン1]**: [説明]（例: kebab-case.ts） +- **[パターン2]**: [説明]（例: PascalCase.tsx） + +### ディレクトリ名 +- **[パターン]**: [説明] + +## Code Organization Principles + +1. **単一責任**: [プロジェクト固有の適用方法] +2. **モジュール性**: [モジュール分割の基準] +3. **再利用性**: [共通コンポーネントの配置] + +## Module Boundaries + +[モジュール間の境界定義] + +## File Size Guidelines + +- **推奨サイズ**: [行数] +- **最大サイズ**: [行数] + +## Documentation Standards + +### プロジェクトレベル +- **README.md**: [役割] +- **[その他ドキュメント]**: [役割] + +### コードレベル +- **コメント**: [コメント規約] +- **型定義**: [型定義の要求] +``` + +##### `specs/_steering/principles.md` + +```markdown +# 開発原則 + +このドキュメントは、プロジェクト全体で共通して適用される開発原則を定義します。 +すべてのPhase実装とタスク実行において、これらの原則に従ってください。 + +## TDD（Test-Driven Development） + +### 基本サイクル: Red-Green-Refactor + +1. **Red（失敗するテストを書く）** + - 実装前に期待する動作を定義するテストを作成 + - テストが失敗することを確認（実装がまだないため） + - テストは具体的で検証可能な振る舞いを記述 + +2. **Green（テストを通す最小限の実装）** + - テストを通すための最小限のコードを実装 + - この段階では完璧を求めず、まず動作することを優先 + - すべてのテストが通ることを確認 + +3. **Refactor（コードを改善）** + - テストが通る状態を維持しながらコードを改善 + - 重複の除去、命名の改善、構造の最適化 + - パフォーマンスやメンテナンス性の向上 + +### TDDの実践ルール + +- **型定義だけを先に作ることは禁止** + - 型定義は実装と共に作成し、実際の使用に基づいて定義する + - 抽象的な型定義の事前作成は過剰設計につながる + +- **テストファースト原則** + - 常にテストから始める + - テストなしでの実装追加は技術的負債となる + +- **小さなステップで進める** + - 一度に大きな変更をしない + - 各サイクルは15分以内を目安 + +## SOLID原則 + +### Single Responsibility Principle（単一責任の原則） +- クラス・関数は単一の責任のみを持つ +- 変更理由は1つだけにする +- 例: ユーザー認証とデータベース操作を分離 + +### Open/Closed Principle（開放閉鎖の原則） +- 拡張に対して開いている +- 修正に対して閉じている +- 新機能追加時に既存コードを修正しない設計 + +### Liskov Substitution Principle（リスコフの置換原則） +- 派生クラスは基底クラスと置換可能 +- 契約を破らない継承関係 +- 例: 期待される振る舞いを維持した実装 + +### Interface Segregation Principle（インターフェース分離の原則） +- クライアントが使用しないメソッドへの依存を強制しない +- 大きな抽象より小さな特定の抽象 +- **警告**: インターフェース（抽象）を作ることが目的化してはいけない + +### Dependency Inversion Principle（依存性逆転の原則） +- 上位モジュールは下位モジュールに依存しない +- 両方とも抽象に依存する +- **警告**: 実装が1つしかない場合は抽象化は不要（YAGNI原則） + +### SOLID原則の落とし穴 + +**過度な抽象化を避ける**: +- インターフェース（抽象）を作ることが目的になってはいけない +- 実装と乖離した抽象は技術的負債となる +- 実際に必要になってから抽象化する（YAGNI原則を参照） + +## YAGNI原則（You Aren't Gonna Need It） + +### 基本理念 +- 実際に必要になるまで機能を追加しない +- 「将来使うかもしれない」という理由で実装しない +- シンプルさを保つことを最優先とする + +### 適用例 +- **過度な抽象化を避ける**: 実装が1つしかないのに抽象層を作らない +- **汎用化を避ける**: 現在の要件に必要な分だけ実装する +- **設定の外部化を避ける**: 変更の可能性が低いものはハードコードで十分 +- **将来の拡張を予測しない**: 必要になったときにリファクタリング + +### YAGNIの利点 +- コードベースがシンプルに保たれる +- 開発速度が向上する +- 保守が容易になる +- 実際に使われないコードを書く無駄を削減 + +## TypeScript固有の原則 + +### 型の扱い +- `any`型の使用は絶対禁止 +- `interface`より`type`を優先使用 + - `interface`は既存ライブラリの型拡張時のみ使用 + - 使用時は必ずコメントで理由を明記 +- 型推論を活用し、必要最小限の型注釈 + +### インポート/エクスポート +- Barrel import/exportは禁止 +- 各モジュールから直接インポート +- 循環参照を避ける設計 + +## コード品質基準 + +### 関数型プログラミングの活用 +- 配列操作は`map`、`filter`、`reduce`を優先 +- `push`などの破壊的操作は避ける +- イミュータブルなデータ構造を使用 + +### エラーハンドリング +- 例外は明示的にキャッチし適切に処理 +- エラーの種類に応じた適切な対応 +- ユーザーへの明確なエラーメッセージ + +### セキュリティ +- SQLインジェクション対策 +- XSS対策 +- 認証・認可の適切な実装 +- 機密情報の適切な管理 + +## アンチパターンと回避方法 + +### 過度な抽象化 +- **問題**: 将来の要件を予測した過剰な設計 +- **回避**: YAGNI（You Aren't Gonna Need It）原則の適用 + +### 神オブジェクト +- **問題**: 多くの責任を持つ巨大なクラス +- **回避**: 単一責任の原則に従った分割 + +### コピペプログラミング +- **問題**: 同じコードの重複 +- **回避**: DRY（Don't Repeat Yourself）原則の適用 + +### マジックナンバー +- **問題**: ハードコードされた値 +- **回避**: 定数として定義し意味を明確化 + +## 実装時の確認事項 + +各タスク実装時に以下を確認: +- [ ] TDDサイクルに従っているか +- [ ] SOLID原則に違反していないか +- [ ] 型安全性が保たれているか +- [ ] エラー処理が適切か +- [ ] セキュリティ上の問題はないか +- [ ] テストカバレッジは十分か +``` + +#### 2.4 完了報告 + +```markdown +✅ ステアリングドキュメントを作成しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 作成先: specs/_steering/ + +📝 作成されたファイル: + - product.md (プロダクト方針) + - tech.md (技術スタック) + - structure.md (プロジェクト構造) + - principles.md (開発原則) + +💡 次のアクション: + 1. 各ドキュメントの内容を確認・編集してください + 2. プロジェクト固有の情報を追加してください + 3. `/sdd:init-task` でタスクを作成できます + +⚠️ 重要: + - 全ての /sdd:* コマンドは自動的にこれらのドキュメントを読み込みます + - ステアリングドキュメントはプロジェクトの「永続的メモリ」として機能します + - プロジェクトの方針や技術スタックが変更された場合は、このコマンドを再実行してください +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 3. Sync Mode（更新） + +既存のステアリングドキュメントを最新の状態に更新： + +#### 3.1 既存ドキュメントの読み込み + +- `specs/_steering/product.md` +- `specs/_steering/tech.md` +- `specs/_steering/structure.md` +- `specs/_steering/principles.md` + +#### 3.2 プロジェクトの変更検出 + +以下の変更を検出： + +**技術スタック変更**: +- 新しい依存関係の追加 +- 既存依存関係のバージョン更新 +- フレームワークの変更 + +**プロジェクト構造変更**: +- 新しいディレクトリの追加 +- ファイル命名パターンの変化 +- モジュール構成の変更 + +#### 3.3 更新の提案 + +変更が検出された場合、AskUserQuestionツールで確認： + +``` +以下の変更が検出されました。ステアリングドキュメントを更新しますか？ + +変更内容: +1. tech.md: 新しい依存関係 "react-query" が追加されました +2. structure.md: 新しいディレクトリ "hooks/" が検出されました + +選択肢: +- はい（推奨）: ステアリングドキュメントを更新 +- いいえ: 現状を維持 +- 個別に確認: 各変更を個別に確認 +``` + +#### 3.4 ドキュメント更新 + +ユーザーの承認に基づいて該当ドキュメントを更新 + +#### 3.5 完了報告 + +```markdown +✅ ステアリングドキュメントを更新しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 更新先: specs/_steering/ + +📝 更新されたファイル: + - tech.md (依存関係を更新) + - structure.md (ディレクトリ構造を更新) + +🔍 検出された変更: + - 新しい依存関係: react-query, zustand + - 新しいディレクトリ: hooks/, contexts/ + +💡 次のアクション: + - 更新内容を確認してください + - 必要に応じて手動で調整してください +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- **⚠️ 重要**: ステアリングドキュメントはプロジェクト全体の「唯一の真実の源」として機能します +- **⚠️ 重要**: 全ての `/sdd:*` コマンドは自動的にステアリングドキュメントを読み込みます +- 既存プロジェクトの場合、Bootstrap Modeで自動検出された内容を必ず確認・調整してください +- プロジェクトの方針や技術スタックが大きく変わった場合は、このコマンドを再実行してください +- ステアリングドキュメントは抽象的なレベルを保ち、具体的なコマンド名やファイル名は列挙しないでください + +## 矛盾チェック（必須） + +ステアリングドキュメント作成後、3つのドキュメント間の矛盾がないか必ず contradiction-checker SubAgent を使用して確認してください： + +```bash +# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない） +Task(contradiction-checker): specs/_steering/ の全ドキュメント間の矛盾をチェックしてください。product.md、tech.md、structure.md、principles.mdの整合性を確認してください。 +``` diff --git a/commands/sync-spec.md b/commands/sync-spec.md new file mode 100644 index 0000000..d46f0d4 --- /dev/null +++ b/commands/sync-spec.md @@ -0,0 +1,261 @@ +--- +argument-hint: [taskname] [phase番号] +--- + +# Phase途中でのドキュメント同期 + +Phase作業途中で中断したい時や、完了したタスクの状態をドキュメントに反映したい時に使用します。 +Phase計画書とoverview.mdの状態を現在の進捗に同期させます。 + +【引数】 +$ARGUMENTS + +## 引数の形式（すべてオプショナル） +- `[taskname]` - タスク名（省略時: コンテキストから推測） +- `[phase番号]` - Phase番号（省略時: コンテキストから推測） + +## コンテキストからの推測 + +引数が指定されていない場合、以下の順序で推測を試みます： + +### 1. 会話履歴からの推測 +最近の会話で以下のコマンドが実行されているか確認： +- `/sdd:implement-phase [taskname] [phase.task]` +- `/sdd:break-down-phase [taskname]` +- `/sdd:verify-phase [taskname] [phase]` +- その他 `/sdd:*` コマンド + +コマンド履歴からtaskname、phase番号を抽出します。 + +### 2. ファイル操作履歴からの推測 +最近読み込み・編集されたファイルパスを確認： +- `specs/[taskname]/tasks/phase{N}-*.md` +- `specs/[taskname]/overview.md` +- `specs/[taskname]/specification.md` +- `specs/[taskname]/technical-details.md` + +ファイルパスからtaskname、phase番号を抽出します。 + +### 3. 推測結果の確認 +推測が成功した場合、AskUserQuestionで確認： + +**質問**: 「以下のタスクとPhaseでドキュメントを同期しますか？」 +- タスク名: {taskname} +- Phase: {phase番号} + +**選択肢**: +- 「はい（推測されたタスクとPhaseで同期）」 +- 「いいえ（引数で指定したい）」 + +「いいえ」が選択された場合: +- コマンドの使用方法を表示 +- 例: `/sdd:sync-spec user-authentication 2` + +### 4. 推測できない場合 +`specs/`ディレクトリ内のタスクをリスト表示し、AskUserQuestionで選択： + +**質問**: 「どのタスクのドキュメントを同期しますか？」 +- 選択肢: specs/配下のディレクトリリスト + +タスクが選択された後、そのタスクのPhaseをリスト表示： + +**質問**: 「どのPhaseのドキュメントを同期しますか？」 +- 選択肢: overview.mdから抽出したPhaseリスト + +## 実行手順 + +### 1. タスクとPhaseの特定 +上記の推測ロジックまたは引数からtasknameとphase番号を特定 + +### 2. 現在の実装状況を調査 + +以下の情報から実装状況を推測： + +#### コードベースの調査 +- 最近編集されたファイル（会話履歴から） +- 実装されたファイルの存在確認 +- 関連するコミット履歴（git logから） +- テストファイルの存在と実行状況 + +#### Phase計画書の読み込み +`specs/[taskname]/tasks/phase{N}-*.md` を読み込み： +- タスク目次の現在の状態 +- 各タスクの説明と実装対象 +- 現在のTDDステップの進捗 +- 既存の開始日時、完了日時 + +#### overview.mdの読み込み +`specs/[taskname]/overview.md` を読み込み： +- 該当Phaseの現在の状態 +- Phase間の依存関係 + +### 3. タスク完了状況の判定 + +各タスクについて、以下の基準で完了状況を判定： + +#### 完了の判定基準 +- タスクで実装対象とされているファイルが存在する +- 関連するテストファイルが存在する（TDD Red/Greenの確認） +- git logに該当タスクのコミットがある +- 既にPhase計画書で「完了」とマークされている + +#### 進行中の判定基準 +- 一部のファイルは存在するが、すべては揃っていない +- 既にPhase計画書で「進行中」とマークされている +- 会話履歴から該当タスクに着手していることが明らか + +#### 未着手の判定基準 +- 実装対象のファイルが存在しない +- 会話履歴に該当タスクの言及がない + +### 4. TDDステップの判定 + +各タスクについて、TDDステップの完了状況を判定： +- **Red**: テストファイルが存在する +- **Green**: 実装ファイルが存在し、テストが通る状態（品質チェックが成功） +- **Refactor**: コードレビュー基準を満たしている（any型なし、適切な型定義など） + +### 5. Phase状態の判定 + +タスクの完了状況から、Phase状態を自動判定： +- **未着手**: すべてのタスクが未着手 +- **進行中**: 1つ以上のタスクが進行中または完了（すべては完了していない） +- **完了**: すべてのタスクが完了 + +### 6. 更新内容の整理 + +Phase計画書とoverview.mdへの更新内容を整理： +- タスクごとの状態変更 +- TDDステップの更新 +- Phase状態の変更 +- 開始日時の記録（未記録のタスクのみ） + +### 7. 更新内容のプレビュー + +ユーザーに以下の形式で報告： + +```markdown +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📝 ドキュメント同期プレビュー +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📍 specs/{taskname}/ - Phase {N} + +## 実装状況の調査結果 + +### タスク完了状況 +- 全タスク数: {total} +- 完了タスク: {completed}（判定基準: 実装ファイル・テストファイル存在、コミット履歴） +- 進行中タスク: {in_progress}（判定基準: 一部ファイル存在、会話履歴から着手） +- 未着手タスク: {not_started} + +### タスク詳細 +- タスク1: {タスク名} - 現在: 未着手 → 更新後: 完了 + 理由: {ファイル存在、テスト実行済み} +- タスク2.1: {タスク名} - 現在: 未着手 → 更新後: 進行中 + 理由: {実装ファイルは存在するがテスト未実装} +- タスク2.2: {タスク名} - 現在: 未着手 → 更新後: 未着手 + 理由: {実装なし} + +### TDDステップ完了状況 +- タスク1: ✅ Red / ✅ Green / ✅ Refactor（テスト・実装・品質チェック完了） +- タスク2.1: ✅ Red / ⬜ Green / ⬜ Refactor（テストのみ存在） + +## 更新内容 + +### Phase計画書 (phase{N}-*.md) +- タスク目次: タスク状態とTDDステップを更新 +- タスク詳細: 状態、開始日時、TDDチェックボックスを更新 + +### overview.md +- Phase状態: {current_status} → {new_status} +- 理由: {判定理由（例: 5/10タスクが完了しているため「進行中」に更新）} + +## この内容でドキュメントを更新します。 + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 8. ドキュメント更新の実行 + +上記のプレビュー内容を表示した後、ドキュメントを更新： + +#### Phase計画書の更新 +1. **タスク目次の更新** + - 各タスクの状態を判定結果に基づいて更新 + - TDDステップのチェックボックスを更新 + +2. **タスク詳細の更新** + - 状態を更新（未着手 → 進行中 or 完了） + - 開始日時を記録（未記録の場合、現在時刻を設定） + - TDDステップのチェックボックスを更新 + +3. **Phase概要の更新** + - Phase状態を判定結果に基づいて更新 + +#### overview.mdの更新 +- 該当Phaseの状態を判定結果に基づいて更新 + +### 9. 完了報告 + +```markdown +✅ ドキュメント同期完了 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 specs/{taskname}/ - Phase {N} + +💡 次のアクション: + - 作業を続ける: `/sdd:implement-phase {taskname} {next_task}` + - Phase検証: `/sdd:verify-phase {taskname} {N}` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 重要な仕様 + +### タスクの開始日時について +- 既に開始日時が記録されている場合は上書きしない +- 未記録で状態が「進行中」または「完了」になる場合、現在時刻を設定 +- フォーマット: `YYYY-MM-DD HH:MM` + +### TDDステップの更新 +- タスクが「完了」の場合、ユーザーに確認してチェックボックスを更新 +- タスクが「進行中」の場合、現在のチェック状態を保持（ユーザーが個別に指定可能） +- タスクが「未着手」の場合、チェックボックスはすべて未チェック + +### Phase状態の判定基準 +Phase状態の推奨値（ユーザーは任意に変更可能）： +- **未着手**: すべてのタスクが未着手 +- **進行中**: 1つ以上のタスクが進行中または完了（すべては完了していない） +- **完了**: すべてのタスクが完了 + +### 並列タスクの扱い +- タスク番号がn.x形式（例: 2.1, 2.2, 2.3）のタスクは並列実行可能 +- 同じグループ内の一部のタスクのみ完了している場合も正しく反映 + +## 注意事項 + +- **⚠️ 重要**: このコマンドは実装状況を推測してドキュメントを更新します。実際の実装やテストの実行は行いません +- **⚠️ 重要**: Phase完了条件のチェックボックスは自動更新しません（`/sdd:verify-phase`で検証後に更新） +- **⚠️ 重要**: 既存の進捗情報（開始日時、完了日時、メモなど）は可能な限り保持します +- タスクの依存関係は確認しますが、警告のみで更新は続行します +- overview.mdの他のセクション（依存関係、ブロッカーなど）は更新しません + +## 他のコマンドとの関係 + +- **`/sdd:implement-phase`**: 実装作業の完了時に状態更新を提案するが、`sync-spec`は途中でも実行可能 +- **`/sdd:verify-phase`**: Phase完了時の検証を行い、overview.md更新を提案する +- **`/sdd:break-down-phase`**: Phase計画書を生成・更新する（タスク構造の変更） + +このコマンドは「実装作業は継続するが、現時点の進捗を仕様書に記録したい」という場合に最適です。 + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### 矛盾チェック（内部処理） + +ドキュメント同期後、内部的に仕様書間の矛盾を確認： +- Phase状態とタスク状態の整合性 +- 依存関係のあるタスク間の矛盾 +- overview.mdとPhase計画書の整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/validate-feasibility.md b/commands/validate-feasibility.md new file mode 100644 index 0000000..310bb07 --- /dev/null +++ b/commands/validate-feasibility.md @@ -0,0 +1,167 @@ +--- +argument-hint: <タスク名> +allowed-tools: ["Read", "Edit", "Glob", "Grep", "Task"] +--- + +# technical-details.md の実現可能性検証と更新 + +`specs/[taskname]/technical-details.md` を実際のプロジェクト構造と照らし合わせて検証し、矛盾や不整合がある場合は technical-details.md を更新します。 + +## 実行手順 + +### 1. タスク名の確認 + +引数で指定されたタスク名、または `specs/` ディレクトリ内の既存タスク一覧からタスクを選択。 + +タスク名が指定されていない場合、ユーザーに確認すること。 + +### 2. ステアリングドキュメントの読み込み + +以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握： + +- `specs/_steering/product.md` - プロダクト方針 +- `specs/_steering/tech.md` - 技術スタック +- `specs/_steering/structure.md` - プロジェクト構造 +- `specs/_steering/principles.md` - 開発原則 + +ステアリングドキュメントが存在しない場合は警告を表示し、処理を続行。 + +### 3. technical-details.md の読み込み + +`specs/[taskname]/technical-details.md` を読み込み、記載されている内容を把握： + +- アーキテクチャ構成 +- 技術スタック +- インフラ構成 +- データベース設計 +- API設計 +- ファイル構造 +- 依存ライブラリ +- その他全ての記載内容 + +### 4. プロジェクト構造の調査 + +technical-details.md に記載されている内容に関連する実際のプロジェクト構造を調査： + +#### 4.1 技術スタックの確認 + +記載されている技術に関連する設定ファイルを確認： + +- `package.json` - 依存ライブラリ、スクリプト、バージョン +- `tsconfig.json` / `jsconfig.json` - TypeScript/JavaScript設定 +- `.node-version` / `.nvmrc` - Node.jsバージョン +- ビルドツールの設定ファイル（webpack.config.js, vite.config.ts, next.config.js など） +- その他、technical-details.md で言及されている設定ファイル全て + +#### 4.2 ディレクトリ構造の確認 + +記載されているディレクトリやファイルパスが実際に存在するか、または既存の構造と整合するかを確認。 + +#### 4.3 データベース関連の確認 + +記載されているデータベース設計に関連する既存ファイルを確認： + +- ORM/スキーマファイル（Prisma, TypeORM, Sequelize など） +- マイグレーションファイル +- データベース設定ファイル +- その他データベース関連の全てのファイル + +#### 4.4 API構造の確認 + +記載されているAPIエンドポイントやルーティングに関連する既存ファイルを確認： + +- ルーティングファイル +- コントローラー +- ミドルウェア +- API関連の全てのファイル + +#### 4.5 その他の確認 + +technical-details.md で言及されている全ての要素について、実際のプロジェクト内の対応するファイルや設定を確認。 + +### 5. 整合性チェック + +technical-details.md の記載内容と実際のプロジェクト構造を比較し、以下を確認： + +- 記載されている技術スタックは既存のものと互換性があるか +- 記載されているディレクトリやファイルパスは既存の構造と整合するか +- 記載されているライブラリは既存の依存関係と競合しないか +- 記載されているバージョンは実現可能か +- 記載されている設計は既存のパターンと矛盾しないか +- その他、全ての記載内容が実際のプロジェクトで実現可能か + +### 6. technical-details.md の更新 + +検証結果に基づいて、technical-details.md を更新： + +#### 更新方針 + +1. **矛盾する記述の修正** + - 既存プロジェクトと矛盾する箇所を実現可能な内容に修正 + +2. **曖昧な記述の具体化** + - プロジェクト構造から判明した具体的な情報で更新 + - 曖昧な記述を具体的なパス、ファイル名、ライブラリ名に修正 + +3. **不足情報の補完** + - 既存プロジェクトから必要な情報を補完 + - 実際のパスやファイル名を明記 + +4. **新規・既存の明示** + - 新規作成が必要なものは「**新規作成**」として明記 + - 既存を利用するものは「**既存を利用**」として明記 + +5. **不明点の明記** + - 判断できない箇所は「**不明**」と明記 + - 複数の実装案がある場合は「案A」「案B」として列挙 + +#### 更新時の注意事項 + +- 既存の構造を尊重し、既存の規約に従う +- 曖昧な表現を避け、具体的に記述 +- 理想論ではなく、実際に実装可能な内容を記述 +- 大規模な変更が必要な場合は段階的な移行方法を記述 + +### 7. 完了報告 + +``` +✅ technical-details.md の実現可能性検証と更新が完了しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 更新先: specs/[taskname]/technical-details.md +📝 変更箇所: [N]箇所 + +💡 次のアクション: + - 不明箇所がある場合: `/sdd:clarify-spec [taskname]` + - Phase構成作成: `/sdd:plan-phases [taskname]` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- 推測ではなく、実際のファイルやコードに基づいて判断すること +- 曖昧な表現を避け、具体的なパス、ファイル名、ライブラリ名を使用 +- プロジェクトの既存の規約や構造を優先すること +- 判断できない箇所は「**不明**」と明記し、複数案がある場合は列挙すること + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。 + +### ステアリングドキュメントレビュー（内部処理） + +検証・更新後、内部的にステアリングドキュメントとの整合性を確認： +- tech.mdの技術スタックとの整合性 +- 既存プロジェクトとの互換性 +- structure.mdの構造規約との整合性 +- principles.mdの開発原則との一致 + +問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。 + +### 矛盾チェック（内部処理） + +検証・更新後、内部的に仕様書間の矛盾を確認： +- technical-details.mdの変更が他のドキュメントと整合しているか +- specification.mdとの整合性 +- overview.mdとの整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/verify-phase.md b/commands/verify-phase.md new file mode 100644 index 0000000..0940372 --- /dev/null +++ b/commands/verify-phase.md @@ -0,0 +1,102 @@ +--- +argument-hint: +allowed-tools: SlashCommand(/sdd:verify:docs:*), SlashCommand(/sdd:verify:requirements:*), SlashCommand(/sdd:verify:quality:*) +--- + +# Phase統合検証（ドキュメント・要件・品質の一括検証） + +指定したPhaseの検証を統合的に実行します。以下の3つのコマンドを順次実行し、総合的な検証レポートを生成します。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `` - タスク名（specs/[taskname]/ディレクトリ） +- `` - 検証対象のPhase番号（1, 2, 3...） + +## 実行内容 + +このコマンドは以下の3つのコマンドを順次実行します： + +### 1. `/sdd:verify:docs {taskname} {phase番号}` +Phase計画書とドキュメントの検証： +- タスク完了状況 +- Phase完了条件 +- overview.mdとの整合性 +- 次Phaseへの引き継ぎ事項 +- Phase間のドキュメント整合性 + +### 2. `/sdd:verify:requirements {taskname} {phase番号}` +要件と実装の整合性検証： +- specification.mdとの整合性（機能要件・非機能要件） +- technical-details.mdとの整合性（技術スタック・データ設計・API設計） +- Phase間の実装整合性（成果物の存在・使用状況・インターフェース） +- 機能レベルの実装検証 + +### 3. `/sdd:verify:quality {taskname} {phase番号}` +品質検証： +- コーディング規約（any型禁止、barrel禁止、interface使用） +- テストの存在と実行 +- 品質チェックコマンド（lint、type-check、build） +- Phase間の実装品質 + +## 検証手順 + +1. **引数の確認** + - タスク名とPhase番号が指定されているか確認 + - 未指定の場合はAskUserQuestionで確認 + +2. **3つのコマンドを順次実行** + - 各コマンドの実行結果を内部で記録 + - エラーが発生した場合も継続して次のコマンドを実行 + +3. **検証結果の内部処理と報告** + - 3つのコマンドの結果を内部で統合 + - 総合評価を決定（すべて✅なら✅、1つでも❌なら❌、それ以外は⚠️） + - **検証レポートはspecファイルに書かず、ユーザーに直接表示** + +## 問題への対応 + +統合検証の結果、問題が見つかった場合： +- 各検証コマンドが個別に対応方針を確認 +- 統合レポートではすべての問題をまとめて表示 +- ユーザーが個別に再検証するか、全体を再検証するかを選択可能 + +## overview.md更新提案 + +総合評価が ✅ の場合のみ、AskUserQuestionで確認： +- 「overview.mdのPhase状態を『完了』に更新しますか？」 +- 承認された場合、overview.mdの該当Phaseの状態を「完了」に更新 + +## 完了報告 + +``` +✅ Phase {N} の統合検証が完了しました +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📍 対象: specs/{taskname}/ - Phase {N} +📊 総合評価: {✅/⚠️/❌} + +💡 次のアクション: + - Phase完了可能: `/sdd:implement-phase {taskname} {N+1}.1` + - 問題あり: 個別再検証または修正 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 注意事項 + +- 3つの検証コマンドを順次実行する統合コマンド +- 各検証で問題が見つかっても、すべての検証を完了してから報告 +- 問題の対応は各検証コマンドで個別に行うか、統合検証後にまとめて対応 + +## 内部品質チェック + +**重要**: 以下のチェックはコマンド内部で実施し、**検証レポートはspecファイルに書きません**。 + +### 矛盾チェック（内部処理） + +Phase検証後、内部的に仕様書間の矛盾を確認： +- Phase完了状態とタスク完了状態の整合性 +- ドキュメント間の整合性 +- 実装と仕様の整合性 + +矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。 diff --git a/commands/verify/docs.md b/commands/verify/docs.md new file mode 100644 index 0000000..98216af --- /dev/null +++ b/commands/verify/docs.md @@ -0,0 +1,111 @@ +--- +argument-hint: +--- + +# Phase計画書とドキュメントの検証 + +指定したPhaseのドキュメントとプロセス管理が適切に行われているかを検証します。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `` - タスク名（specs/[taskname]/ディレクトリ） +- `` - 検証対象のPhase番号（1, 2, 3...） + +## 検証手順 + +### 1. 準備 +- 引数の解析（未指定の場合はAskUserQuestionで確認） +- `specs/[taskname]/tasks/phase{N}-*.md` の存在確認 + +### 2. Phase計画書のタスク完了状況チェック + +Phase計画書を読み込み： +- タスク目次：全タスクが「完了」、TDDステップ（Red/Green/Refactor）完了を確認 +- タスク詳細：状態、開始/完了日時、依存関係を確認 + +### 3. Phase完了条件のチェック + +Phase計画書の「Phase完了条件」セクションの各チェックボックスを確認： +- 全タスク完了 +- 全テスト通過 +- 品質チェック成功 +- コードレビュー承認 + +### 4. overview.mdとの整合性 + +- 対象Phaseの状態が「進行中」または「完了」か確認 +- 前Phaseが「完了」状態か確認 +- 前Phaseの成果物がoverview.mdに記載されているか確認 + +### 5. 次Phaseへの引き継ぎ事項の確認 + +Phase計画書の「次Phaseへの引き継ぎ事項」セクションを確認： +- 成果物リストの存在 +- 未解決の課題、技術的負債の明記 + +### 6. Phase間のドキュメント整合性（Phase 2以降のみ） + +- 前Phase計画書の「次Phaseへの引き継ぎ事項」から成果物リストを抽出 +- 現Phase計画書で該当成果物が言及されているか確認 + +### 7. 検証結果レポート + +```markdown +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📋 Phase {N} ドキュメント検証レポート +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📍 specs/{taskname}/ - Phase {N} +📅 {YYYY-MM-DD HH:MM} + +## 総合評価 +{✅ / ⚠️ / ❌} + +## 検証結果 + +### タスク完了状況 +{✅/⚠️/❌} {completed}/{total} タスク + +### Phase完了条件 +{✅/⚠️/❌} {completed}/{total} 項目 + +### overview.md整合性 +{✅/⚠️/❌} + +### 引き継ぎ事項 +{✅/⚠️/❌} + +### Phase間ドキュメント整合性 +{✅/⚠️/❌/N/A} + +## 🚨 要対応項目 +{問題のリスト} + +## 💡 次のアクション +✅: `/sdd:verify:requirements {taskname} {N}` で要件検証へ +⚠️/❌: 問題解決後、再検証（`/sdd:verify:docs {taskname} {N}`） + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 8. 問題への対応（⚠️/❌の場合） + +AskUserQuestionで各問題の対応方針を確認（最大4問/回）： +- 選択肢に「修正する」「スキップする」「対応しない」等を含める +- 選択後、TodoWriteでタスク作成 + +## 注意事項 + +- ドキュメントとプロセス管理のみを検証 +- コードやテストの実行は `verify:requirements` と `verify:quality` で実施 + +## 矛盾チェック（必須） + +ドキュメント検証後、仕様書間の矛盾がないか必ず contradiction-checker SubAgent を使用して確認してください： + +```bash +# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない） +Task(contradiction-checker): specs/[taskname]/ の全ドキュメント間の矛盾をチェックしてください。Phase計画書の状態とタスク記録が整合しているか確認してください。 +``` diff --git a/commands/verify/quality.md b/commands/verify/quality.md new file mode 100644 index 0000000..bc10f92 --- /dev/null +++ b/commands/verify/quality.md @@ -0,0 +1,120 @@ +--- +argument-hint: +--- + +# Phase実装の品質検証 + +指定したPhaseの実装コードの品質、コーディング規約、テストを検証します。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `` - タスク名（specs/[taskname]/ディレクトリ） +- `` - 検証対象のPhase番号（1, 2, 3...） + +## 検証手順 + +### 1. 準備 +- 引数の解析（未指定の場合はAskUserQuestionで確認） +- `specs/[taskname]/tasks/phase{N}-*.md` の存在確認 +- Phase計画書から実装ファイルリストを抽出 + +### 2. コーディング規約チェック + +実装ファイルをGrepツールでチェック： + +**禁止事項**: +- `any`型の使用（`pattern: "\bany\b"`）→ ファイルパス:行番号を記録 +- barrel import/export（`pattern: "export \* from"`）→ ファイルパス:行番号を記録 + +**要確認**: +- `interface`の使用（`pattern: "^\s*interface\s+"`）→ コメントで理由が説明されているか確認 + +### 3. テストの確認と実行 + +- 各実装ファイルに対応するテストファイル（`*.test.ts`, `*.spec.ts`等）の存在確認 +- AskUserQuestionでテストコマンドを確認（例: `volta run --node $(cat .node-version) yarn test`） +- テストを実行し、成功/失敗/スキップ数を記録 + +### 4. 品質チェックコマンドの実行 + +- AskUserQuestionで品質チェックコマンドを確認（例: `yarn lint && yarn type-check && yarn build`） +- 各コマンドを実行し、結果を記録： + - Lint: エラー数、警告数 + - Type check: 型エラー数 + - Build: 成功/失敗 + +### 5. Phase間の実装品質チェック（Phase 2以降のみ） + +- 前Phaseの成果物がimportされているか（Grepで`import`文を検索） +- 型の互換性確認（type-checkの結果を参照） + +### 6. 検証結果レポート + +```markdown +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🔧 Phase {N} 品質検証レポート +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📍 specs/{taskname}/ - Phase {N} +📅 {YYYY-MM-DD HH:MM} + +## 総合評価 +{✅ / ⚠️ / ❌} + +## 検証結果 + +### コーディング規約 +- any型: {✅/❌} {違反数}件 +- barrel import/export: {✅/❌} {違反数}件 +- interface使用: {✅/⚠️} +{違反がある場合: ファイルパス:行番号} + +### テスト +- テストファイル: {exists}/{expected} +- 実行結果: 成功 {passed} / 失敗 {failed} / スキップ {skipped} + +### 品質チェック +- Lint: {✅/⚠️/❌} {エラー}E / {警告}W +- Type check: {✅/❌} {エラー}件 +- Build: {✅/❌} + +### Phase間統合（Phase 2以降） +{✅/⚠️/❌/N/A} + +## 🚨 要対応項目 +{問題のリスト} + +## 💡 次のアクション +✅: Phase完了可能。overview.mdを「完了」に更新推奨 +⚠️: 警告を解決後、再検証（`/sdd:verify:quality {taskname} {N}`） +❌: 重大な問題を解決後、再検証 + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 7. 問題への対応（⚠️/❌の場合） + +AskUserQuestionで各問題の対応方針を確認（最大4問/回）： +- 選択肢に「修正する」「対応しない」等を含める +- 選択後、TodoWriteでタスク作成 + +### 8. overview.md更新提案（✅の場合のみ） + +AskUserQuestionで「overview.mdのPhase状態を『完了』に更新しますか？」と確認。 + +## 注意事項 + +- `.node-version`がある場合は`volta run`を使用 +- テスト・品質チェックコマンドは必ずユーザーに確認 +- コーディング規約（`any`禁止、barrel禁止）は厳格にチェック + +## 矛盾チェック（必須） + +品質検証後、仕様書とコードの整合性を必ず contradiction-checker SubAgent を使用して確認してください： + +```bash +# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない） +Task(contradiction-checker): specs/[taskname]/ の全ドキュメント間の矛盾をチェックしてください。実装の品質が仕様書の要求水準と整合しているか確認してください。 +``` diff --git a/commands/verify/requirements.md b/commands/verify/requirements.md new file mode 100644 index 0000000..0dde662 --- /dev/null +++ b/commands/verify/requirements.md @@ -0,0 +1,135 @@ +--- +argument-hint: +--- + +# Phase要件と実装の整合性検証 + +指定したPhaseの実装が仕様書の要件を満たしているか、Phase間の整合性が保たれているかを検証します。 + +【引数】 +$ARGUMENTS + +## 引数の形式 +- `` - タスク名（specs/[taskname]/ディレクトリ） +- `` - 検証対象のPhase番号（1, 2, 3...） + +## 検証手順 + +### 1. 準備 +- 引数の解析（未指定の場合はAskUserQuestionで確認） +- `specs/[taskname]/tasks/phase{N}-*.md` の存在確認 + +### 2. specification.mdとの整合性 + +#### 機能要件 +- Phase計画書の「実装する機能」リストを抽出 +- 各機能のファイルをGlobで検索し、実装状況を確認 +- 関数・クラスの存在、パラメータ・戻り値、エラーハンドリングをコードレビュー + +#### 非機能要件 +specification.mdの非機能要件（パフォーマンス、セキュリティ、可用性等）について： +- 関連キーワードでGrep検索 +- 実装ファイル内の対応を確認 + +### 3. technical-details.mdとの整合性 + +#### 技術スタック +- 記載された技術・ライブラリの使用確認（Grepでimport文を検索） +- package.jsonとの整合性確認 + +#### データ設計（型定義、スキーマ等） +- Grepで型名を検索し存在確認 +- データ構造の一致を確認 + +#### API設計 +- エンドポイントの実装確認（ルーティングファイル検索） +- リクエスト・レスポンス形式の一致確認 + +### 4. Phase間の実装整合性（Phase 2以降のみ） + +#### 前Phaseの成果物 +- 前Phase計画書の「次Phaseへの引き継ぎ事項」から成果物リストを抽出 +- Globで各成果物ファイルの存在を確認 +- ファイル内容の簡易チェック + +#### 前Phaseの成果物の使用状況 +- 現Phase実装での前Phase成果物のimportを確認（Grepで検索） +- 主要な関数・型・クラスの使用箇所を確認 + +#### Phase間インターフェース +- 前Phaseのexport定義を確認（Grepで`export`検索） +- 現Phaseでの使用方法との整合性確認 + +### 5. 機能レベルの実装検証 + +specification.mdの各機能について： +- 実装ファイルを特定・読み込み +- コードレビュー：関数・クラスの存在、シグネチャ、ビジネスロジック +- エッジケース・例外処理の実装確認 +- テストファイルの存在確認 + +### 6. 検証結果レポート + +```markdown +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📐 Phase {N} 要件検証レポート +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📍 specs/{taskname}/ - Phase {N} +📅 {YYYY-MM-DD HH:MM} + +## 総合評価 +{✅ / ⚠️ / ❌} + +## 検証結果 + +### 機能要件 +{✅/⚠️/❌} {implemented}/{total} 機能 + +### 非機能要件 +{✅/⚠️/❌/N/A} + +### technical-details.md整合性 +- 技術スタック: {✅/⚠️/❌} +- データ設計: {✅/⚠️/❌/N/A} +- API設計: {✅/⚠️/❌/N/A} + +### Phase間実装整合性 +- 前Phase成果物の存在: {✅/⚠️/❌/N/A} +- 前Phase成果物の使用: {✅/⚠️/❌/N/A} +- インターフェース整合性: {✅/⚠️/❌/N/A} + +### 実装品質 +- 実装詳細: {✅/⚠️/❌} +- エッジケース・例外処理: {✅/⚠️/❌} + +## 🚨 要対応項目 +{問題のリスト（ファイルパス:行番号を含む）} + +## 💡 次のアクション +✅: `/sdd:verify:quality {taskname} {N}` で品質検証へ +⚠️/❌: 問題解決後、再検証（`/sdd:verify:requirements {taskname} {N}`） + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### 7. 問題への対応（⚠️/❌の場合） + +AskUserQuestionで各問題の対応方針を確認（最大4問/回）： +- 選択肢に「実装する」「仕様を見直す」「対応しない」等を含める +- 選択後、TodoWriteでタスク作成 + +## 注意事項 + +- 仕様書と実装の整合性を検証 +- 機能レベルの実装検証を実施（コードレビュー） +- Phase間の成果物の存在と使用状況を確認 + +## 矛盾チェック（必須） + +要件検証後、仕様書とコードの整合性を必ず contradiction-checker SubAgent を使用して確認してください： + +```bash +# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない） +Task(contradiction-checker): specs/[taskname]/ の全ドキュメント間の矛盾をチェックしてください。実装が仕様書と整合しているか確認してください。 +``` diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..1ef9fdf --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,133 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:masseater/claude-code-plugin:sdd", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "f024c6c69bb9b26973c48b0bd8dbf8f7377868be", + "treeHash": "daec8c60323866c8a9a96b5440bd1a0dbccbeb4f86eba9e781e72eab601b560a", + "generatedAt": "2025-11-28T10:27:02.317860Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "sdd", + "description": "Spec Driven Development (SDD) ワークフロー支援コマンド集", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "1025284d0e6a562a123c289d876d69b3e2b904b70591390e25da26b8de60bc27" + }, + { + "path": "agents/steering-reviewer.md", + "sha256": "a14095ebf675bc95387510edb5cdda77ee6821e41337f391f7f128f4021d577e" + }, + { + "path": "agents/contradiction-checker.md", + "sha256": "e7ce784443f908946551082eff93ddfe2afdf3f91895237d7f60add08ed3ba4a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "84f9d4d9c9c73dc3b3f8f69f7b6be6575eb6a773b43d34965c08dc0a747fd9d4" + }, + { + "path": "commands/define-requirements.md", + "sha256": "cb08c2da603286fdcddb764dedadf1941cf7df86f5a8f607f000e60a25db6fbe" + }, + { + "path": "commands/contradiction-check.md", + "sha256": "aba7d6971e38624ce30e3f04b449eb06bc0b7da3bcf36494cc444c4e4198cfdf" + }, + { + "path": "commands/validate-feasibility.md", + "sha256": "f9364b95e00806da7de4ce4e95f3b438ac6a3da54077375308fa985bc13c115d" + }, + { + "path": "commands/breakdown-phase.md", + "sha256": "a3c99e8b2d4b82ca2e7e4675d48eb3f4bbdf35ef33a799e97be461f899f22fc7" + }, + { + "path": "commands/implement-phase.md", + "sha256": "a47375fad91bdfcdf937969231a132a4f06801358a1cfdddb6f901d5aa5d6d93" + }, + { + "path": "commands/plan-implementation.md", + "sha256": "764b309ea1e6761803ec1793713b23c0dd75264fa3022e68d43ea99fb1a254b2" + }, + { + "path": "commands/help.md", + "sha256": "c36578a2589b0696a3d878657a0570fdb78639e1f49e31cb65383557ba4372d4" + }, + { + "path": "commands/plan-phases.md", + "sha256": "1f68b04de1f190843dd0ce7fb189806819c5947bca4887ff1398bbf37b6f6a93" + }, + { + "path": "commands/clarify-spec.md", + "sha256": "1e53a85fb6334f00df3cc8063b89c19de1ca19f4dfe05072f2612c679932c642" + }, + { + "path": "commands/conduct-research.md", + "sha256": "a8d74f98f984e1b8c61c2217513be13f9152f77c5d9edb841843ab1f95080b99" + }, + { + "path": "commands/verify-phase.md", + "sha256": "85027c38908ce0d3c8af2ecd408e9a87270c11daeb346a310dc7ba0bba4a872d" + }, + { + "path": "commands/define-technical.md", + "sha256": "6c4696ddd21615f027abe89785b3f09e09d19722422c3f238785e0e0f142f419" + }, + { + "path": "commands/sync-spec.md", + "sha256": "3d8d8cdd51673a63c678bb8721e9bf7826339b970dcb780606fc644f9ff013f8" + }, + { + "path": "commands/archive-spec.md", + "sha256": "ffe6dcd0002fff4bf0740778a327d3f393fdfd2a1f610eb629896ad18c71131d" + }, + { + "path": "commands/init-task.md", + "sha256": "de803d346852d3b391a7a2521164391c0b6409e9d2044dd791053024891cb0dc" + }, + { + "path": "commands/list-specs.md", + "sha256": "006574688baf07fcd55ed85c31c8de4e3a6544831a2df784f7c3ed013696a50e" + }, + { + "path": "commands/steering.md", + "sha256": "c3a28444ac7bae583f3dfa87a048f43921a0bff5ae8f214bf365a5b22f295d2e" + }, + { + "path": "commands/next-step.md", + "sha256": "7b1ae29cdc7488dac71e83b1b4ad79d84ebdf73cc989f3cd9212aa1726da3030" + }, + { + "path": "commands/verify/requirements.md", + "sha256": "cd96d8722b5dc65a807d25ff2567b97be3f86a5b33c81b9bf1b6814f42cec521" + }, + { + "path": "commands/verify/quality.md", + "sha256": "8b30e670134007ea2c915b16e4e46e282b4528c7c538ea6a19757bfdaae00e20" + }, + { + "path": "commands/verify/docs.md", + "sha256": "07133cb95d55ccefea95b0f2729d584930b04981eb75aaa22ae5a5ed9d0469f7" + } + ], + "dirSha256": "daec8c60323866c8a9a96b5440bd1a0dbccbeb4f86eba9e781e72eab601b560a" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file