--- description: "仕様駆動ワークフローv1は、要件が明確に定義され、設計が綿密に計画され、実装が徹底的に文書化・検証される構造化されたソフトウェア開発アプローチを提供します。" applyTo: "**" --- # 仕様駆動ワークフロー v1 **仕様駆動ワークフロー：** 要件と実装の間のギャップを埋める。 **常に以下の成果物を維持する：** - **`requirements.md`**: 構造化された EARS 記法によるユーザーストーリーと受け入れ基準。 - **`design.md`**: 技術的アーキテクチャ、シーケンス図、実装の考慮事項。 - **`tasks.md`**: 詳細で追跡可能な実装計画。 ## ユニバーサル文書化フレームワーク **文書化ルール：** 詳細テンプレートをすべての文書化の**第一の情報源**として使用する。 **要約形式：** 変更履歴やプルリクエスト説明などの簡潔な成果物にのみ使用する。 ### 詳細文書化テンプレート #### アクション文書テンプレート（すべてのステップ/実行/テスト） ```bash ### [TYPE] - [ACTION] - [TIMESTAMP] **目的**: [達成される目標] **コンテキスト**: [現在の状態、要件、および前のステップへの参照] **決定**: [選択されたアプローチと根拠、該当する場合は決定記録を参照] **実行**: [使用されたパラメータとコマンドで実行されたステップ。コードの場合はファイルパスを含む。] **出力**: [完全で省略のない結果、ログ、コマンド出力、およびメトリクス] **検証**: [成功検証方法と結果。失敗した場合は、修復計画を含む。] **次**: [次の特定のアクションへの自動継続計画] ``` #### 決定記録テンプレート（すべての決定） ```bash ### Decision - [TIMESTAMP] **決定**: [決定されたこと] **コンテキスト**: [決定を必要とする状況とそれを駆動するデータ] **選択肢**: [評価された代替案と簡潔な長所と短所] **根拠**: [選択された選択肢が優れている理由、トレードオフを明示的に記述] **影響**: [実装、保守性、およびパフォーマンスに対する予想される結果] **レビュー**: [この決定を再評価する条件またはスケジュール] ``` ### 要約形式（レポート用） #### 簡潔なアクションログ 簡潔な変更履歴を生成するため。各ログエントリは完全なアクション文書から派生する。 `[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]` #### 圧縮された決定記録 プルリクエスト要約や執行要約での使用。 `Decision: [X] | Rationale: [Y] | Impact: [Z] | Review: [Date]` ## 実行ワークフロー（6 フェーズループ） **ステップをスキップしないこと。一貫した用語を使用すること。曖昧さを減らすこと。** ### **フェーズ 1: 分析** **目的：** - 問題を理解する。 - 既存システムを分析する。 - 明確でテスト可能な要件セットを作成する。 - 可能な解決策とその影響について考える。 **チェックリスト：** - [ ] 提供されたすべてのコード、文書、テスト、およびログを読む。 - ファイルインベントリ、要約、および初期分析結果を文書化する。 - [ ] **EARS 記法**で要件を定義する： - 機能リクエストを構造化されたテスト可能な要件に変換する。 - 形式: `WHEN [条件またはイベント], THE SYSTEM SHALL [期待される動作]` - [ ] 依存関係と制約を特定する。 - リスクと軽減戦略を含む依存関係グラフを文書化する。 - [ ] データフローと相互作用をマッピングする。 - システム相互作用図とデータモデルを文書化する。 - [ ] エッジケースと障害をカタログ化する。 - 包括的なエッジケースマトリクスと潜在的な障害ポイントを文書化する。 - [ ] 信頼度を評価する。 - 要件の明確性、複雑性、問題スコープに基づいて**信頼度スコア（0-100%）**を生成する。 - スコアとその根拠を文書化する。 **重要な制約：** - **すべての要件が明確で文書化されるまで先に進んではならない。** ### **フェーズ 2: 設計** **目的：** - 包括的な技術設計と詳細な実装計画を作成する。 **チェックリスト：** - [ ] **信頼度スコアに基づく適応実行戦略を定義する：** - **高い信頼度（>85%）** - 包括的なステップバイステップ実装計画を作成する。 - 概念実証ステップをスキップする。 - 完全な自動実装を進める。 - 標準的な包括文書化を維持する。 - **中程度の信頼度（66–85%）** - **概念実証（PoC）**または**最小実行可能製品（MVP）**を優先する。 - PoC/MVP の明確な成功基準を定義する。 - まず PoC/MVP を構築・検証し、その後計画を段階的に拡張する。 - PoC/MVP 目標、実行、および検証結果を文書化する。 - **低い信頼度（<66%）** - 最初のフェーズを研究と知識構築に充てる。 - セマンティック検索を使用し、類似実装を分析する。 - 所見を研究文書に統合する。 - 研究後に ANALYZE フェーズを再実行する。 - 信頼度が低いままの場合のみエスカレーションする。 - [ ] **`design.md`で技術設計を文書化する：** - **アーキテクチャ:** コンポーネントと相互作用の高レベル概要。 - **データフロー:** 図と説明。 - **インターフェース:** API コントラクト、スキーマ、公開機能シグネチャ。 - **データモデル:** データ構造とデータベーススキーマ。 - [ ] **エラーハンドリングを文書化する：** - 手順と期待される応答を含むエラーマトリクスを作成する。 - [ ] **単体テスト戦略を定義する。** - [ ] **`tasks.md`で実装計画を作成する：** - 各タスクについて、説明、期待される結果、および依存関係を含める。 **重要な制約：** - **設計と計画が完成・検証されるまで実装に進んではならない。** ### **フェーズ 3: 実装** **目的：** - 設計と計画に従って本番品質のコードを記述する。 **チェックリスト：** - [ ] 小さなテスト可能な増分でコーディングする。 - 各増分をコード変更、結果、およびテストリンクで文書化する。 - [ ] 依存関係から上向きに実装する。 - 解決順序、正当性、および検証を文書化する。 - [ ] 規約に従う。 - 遵守と決定記録による偏差を文書化する。 - [ ] 意味のあるコメントを追加する。 - 意図（「なぜ」）に焦点を当て、メカニズム（「何を」）ではない。 - [ ] 計画通りにファイルを作成する。 - ファイル作成ログを文書化する。 - [ ] リアルタイムでタスクステータスを更新する。 **重要な制約：** - **すべての実装ステップが文書化・テストされるまでコードをマージまたはデプロイしてはならない。** ### **フェーズ 4: 検証** **目的：** - 実装がすべての要件と品質基準を満たすことを確認する。 **チェックリスト：** - [ ] 自動テストを実行する。 - 出力、ログ、およびカバレッジレポートを文書化する。 - 失敗の場合、根本原因分析と修復を文書化する。 - [ ] 必要に応じて手動検証を実行する。 - 手順、チェックリスト、および結果を文書化する。 - [ ] エッジケースとエラーをテストする。 - 結果と正しいエラーハンドリングの証拠を文書化する。 - [ ] パフォーマンスを検証する。 - メトリクスを文書化し、重要なセクションをプロファイルする。 - [ ] 実行トレースをログに記録する。 - パス分析とランタイム動作を文書化する。 **重要な制約：** - **すべての検証ステップが完了し、すべての問題が解決されるまで先に進んではならない。** ### **フェーズ 5: 反省** **目的：** - コードベースを改善し、文書を更新し、パフォーマンスを分析する。 **チェックリスト：** - [ ] 保守性のためにリファクタリングする。 - 決定、前後の比較、および影響を文書化する。 - [ ] すべてのプロジェクト文書を更新する。 - すべての README、図、およびコメントが最新であることを確認する。 - [ ] 潜在的な改善を特定する。 - 優先順位付けを含むバックログを文書化する。 - [ ] 成功基準を検証する。 - 最終検証マトリクスを文書化する。 - [ ] メタ分析を実行する。 - 効率性、ツール使用、およびプロトコル遵守を振り返る。 - [ ] 技術的負債の問題を自動作成する。 - インベントリと修復計画を文書化する。 **重要な制約：** - **すべての文書化と改善アクションがログに記録されるまでフェーズを閉じてはならない。** ### **フェーズ 6: 引き継ぎ** **目的：** - レビューとデプロイのために作業をパッケージ化し、次のタスクに移行する。 **チェックリスト：** - [ ] 執行要約を生成する。 - **圧縮された決定記録**形式を使用する。 - [ ] プルリクエストを準備する（該当する場合）： 1. 執行要約。 2. **簡潔なアクションログ**からの変更履歴。 3. 検証成果物と決定記録へのリンク。 4. 最終的な`requirements.md`、`design.md`、および`tasks.md`へのリンク。 - [ ] ワークスペースを最終化する。 - 中間ファイル、ログ、および一時成果物を`.agent_work/`にアーカイブする。 - [ ] 次のタスクに続行する。 - 移行または完了を文書化する。 **重要な制約：** - **すべての引き継ぎステップが完了・文書化されるまでタスクを完了と見なしてはならない。** ## トラブルシューティングと再試行プロトコル **エラー、曖昧さ、またはブロッカーが発生した場合：** **チェックリスト：** 1. **再分析**： - ANALYZE フェーズを再訪する。 - すべての要件と制約が明確で完全であることを確認する。 2. **再設計**： - DESIGN フェーズを再訪する。 - 必要に応じて技術設計、計画、または依存関係を更新する。 3. **再計画**： - 新しい所見に対処するために`tasks.md`の実装計画を調整する。 4. **実行再試行**： - 修正されたパラメータまたはロジックで失敗したステップを再実行する。 5. **エスカレーション**： - 再試行後も問題が持続する場合、エスカレーションプロトコルに従う。 **重要な制約：** - **未解決のエラーや曖昧さで先に進んではならない。常にトラブルシューティングステップと結果を文書化する。** ## 技術的負債管理（自動化） ### 特定と文書化 - **コード品質**: 静的分析を使用して実装中にコード品質を継続的に評価する。 - **ショートカット**: 速度重視の品質決定をすべて決定記録でその結果とともに明示的に記録する。 - **ワークスペース**: 組織的な逸脱と命名の不整合を監視する。 - **文書化**: 不完全、古い、または欠落している文書を追跡する。 ### 自動課題作成テンプレート ```text **タイトル**: [技術的負債] - [簡潔な説明] **優先度**: [ビジネス影響と修復コストに基づく高/中/低] **場所**: [ファイルパスと行番号] **理由**: [負債が発生した理由、利用可能な場合は決定記録にリンク] **影響**: [現在および将来の結果（例：開発の遅延、バグリスクの増加）] **修復**: [具体的で実行可能な解決ステップ] **工数**: [解決の見積もり（例：Tシャツサイズ: S、M、L）] ``` ### 修復（自動優先順位付け） - 依存関係分析を伴うリスクベースの優先順位付け。 - 将来の計画を支援する工数見積もり。 - 大規模なリファクタリング作業のための移行戦略を提案する。 ## 品質保証（自動化） ### 継続的監視 - **静的分析**: コードスタイル、品質、セキュリティ脆弱性、およびアーキテクチャルール遵守のためのリンティング。 - **動的分析**: ステージング環境でのランタイム動作とパフォーマンスの監視。 - **文書化**: 文書の完全性と正確性の自動チェック（例：リンク、形式）。 ### 品質メトリクス（自動追跡） - コードカバレッジ率とギャップ分析。 - 関数/メソッドごとの循環複雑度スコア。 - 保守性インデックス評価。 - 技術的負債比率（例：推定修復時間対開発時間）。 - 文書カバレッジ率（例：コメント付き公開メソッド）。 ## EARS 記法リファレンス **EARS（Easy Approach to Requirements Syntax）** - 要件の標準形式： - **汎用**: `THE SYSTEM SHALL [期待される動作]` - **イベント駆動**: `WHEN [トリガーイベント] THE SYSTEM SHALL [期待される動作]` - **状態駆動**: `WHILE [特定の状態で] THE SYSTEM SHALL [期待される動作]` - **望ましくない動作**: `IF [望ましくない条件] THEN THE SYSTEM SHALL [必要な応答]` - **オプション**: `WHERE [機能が含まれる] THE SYSTEM SHALL [期待される動作]` - **複合**: 洗練された要件のための上記パターンの組み合わせ 各要件は以下でなければならない： - **テスト可能**: 自動または手動テストで検証可能 - **明確**: 単一の解釈のみ可能 - **必要**: システムの目的に貢献する - **実現可能**: 制約内で実装可能 - **追跡可能**: ユーザーニーズと設計要素にリンクされている