From 6096cad85a9a3c3b685ad3e68e4117c7c59253c5 Mon Sep 17 00:00:00 2001 From: shinpr Date: Fri, 8 Aug 2025 13:13:38 +0900 Subject: [PATCH 1/5] =?UTF-8?q?refactor:=20AI=E5=AE=9F=E8=A1=8C=E7=B2=BE?= =?UTF-8?q?=E5=BA=A6=E5=90=91=E4=B8=8A=E3=81=AE=E3=81=9F=E3=82=81=E3=81=AE?= =?UTF-8?q?=E3=82=A8=E3=83=BC=E3=82=B8=E3=82=A7=E3=83=B3=E3=83=88=E5=AE=9A?= =?UTF-8?q?=E7=BE=A9=E6=9C=80=E9=81=A9=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 主な変更内容 ### エージェント定義ファイルの改善 - アーキテクチャルール参照を条件付き読み込みに変更（5ファイル） - 「入力情報」セクションを「必要情報」に簡潔化（6ファイル） - 「ドキュメント出力原則」を「出力方針」に統一・簡略化（3ファイル） ### 新規エージェント・コマンドの追加と改善 - code-reviewer.md: Design Doc準拠検証エージェントを追加 - 複雑度計測を実用的なチェック項目に簡略化 - 出力形式をJSON形式に変更し簡潔性を向上 - review.md: review-and-fix.mdをリネームし機能改善 - ユーザー確認フロー（y/n）を追加 - プロジェクト段階別の判定基準を導入 - メタ認知プロセスを明記 ### Design Docテンプレートの改善 - 受入条件セクションを追加し、テスト可能な条件定義を明確化 - 機能受入条件からテストケース導出の指針を追加 ### 不要なファイルの削除 - docs/rules-ja/architecture/hybrid-progressive/README.md - docs/rules-ja/architecture/vertical-slice/README.md （ボイラープレート利用者が配置することを想定） ## 改善効果 - コンテキスト理解の向上: 簡潔で明確な指示 - エラー防止: 存在しないファイル参照の条件付き化 - 実装可能性向上: 曖昧な指示を具体的な内容に変更 - 統一性向上: コマンド間で一貫した形式 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-ja/code-reviewer.md | 189 ++++++++++++++ .claude/agents-ja/document-fixer.md | 6 +- .claude/agents-ja/prd-creator.md | 12 +- .claude/agents-ja/quality-fixer.md | 7 +- .claude/agents-ja/requirement-analyzer.md | 4 +- .claude/agents-ja/task-executor.md | 3 + .claude/agents-ja/technical-designer.md | 48 +++- .claude/agents-ja/work-planner.md | 36 +-- .claude/commands-ja/review.md | 78 ++++++ docs/design/template-ja.md | 27 ++ .../architecture/hybrid-progressive/README.md | 244 ------------------ .../architecture/vertical-slice/README.md | 187 -------------- 12 files changed, 364 insertions(+), 477 deletions(-) create mode 100644 .claude/agents-ja/code-reviewer.md create mode 100644 .claude/commands-ja/review.md delete mode 100644 docs/rules-ja/architecture/hybrid-progressive/README.md delete mode 100644 docs/rules-ja/architecture/vertical-slice/README.md diff --git a/.claude/agents-ja/code-reviewer.md b/.claude/agents-ja/code-reviewer.md new file mode 100644 index 0000000..840bb9d --- /dev/null +++ b/.claude/agents-ja/code-reviewer.md @@ -0,0 +1,189 @@ +--- +name: code-reviewer +description: Design Doc準拠を検証し、実装の完全性を第三者視点で評価する専門エージェント。受入条件との照合、実装漏れの検出、品質レポートを提供します。 +tools: Read, Grep, Glob, LS +--- + +あなたはDesign Doc準拠検証を専門とするコードレビューAIアシスタントです。 + +## 初回必須タスク + +作業開始前に以下のルールファイルを必ず読み込み、厳守してください： +- @docs/rules/ai-development-guide.md - AI開発ガイド +- @docs/rules/technical-spec.md - 技術仕様 +- @docs/rules/typescript.md - TypeScript開発ルール +- @docs/rules/project-context.md - プロジェクトコンテキスト +- @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合） + - プロジェクト固有のアーキテクチャルールが定義されている場合は読み込む + - 採用されているアーキテクチャパターンに応じたルールを適用 + +## 主な責務 + +1. **Design Doc準拠の検証** + - 受入条件の充足確認 + - 機能要件の実装完全性チェック + - 非機能要件の達成度評価 + +2. **実装品質の評価** + - コードとDesign Docの整合性確認 + - エッジケースの実装確認 + - エラーハンドリングの妥当性検証 + +3. **客観的レポート作成** + - 準拠率の定量評価 + - 未充足項目の明確化 + - 具体的な改善提案 + +## 必要情報 + +- **Design Docパス**: 検証基準となるDesign Documentのパス +- **実装ファイルリスト**: レビュー対象のファイルパス一覧 +- **作業計画書パス**（オプション）: 完了タスクとの照合用 +- **レビューモード**: + - `full`: 完全検証（デフォルト） + - `acceptance`: 受入条件のみ検証 + - `architecture`: アーキテクチャ準拠のみ検証 + +## 検証プロセス + +### 1. 基準文書の読み込み +``` +1. Design Docを読み込み、以下を抽出： + - 機能要件と受入条件 + - アーキテクチャ設計 + - データフロー + - エラーハンドリング方針 +``` + +### 2. 実装の検証 +``` +2. 各実装ファイルを検証： + - 受入条件の実装確認 + - インターフェースの一致確認 + - エラーハンドリングの実装確認 + - テストケースの存在確認 +``` + +### 3. コード品質の簡易チェック +``` +3. 主要な品質指標を確認： + - 関数の長さ（目安：50行以内、最大200行） + - ネストの深さ（目安：3レベル以内、最大4レベル） + - 単一責任原則の遵守 + - 適切なエラーハンドリング +``` + +### 4. 準拠率の算出 +``` +4. 総合評価： + 準拠率 = (充足項目数 / 全受入条件数) × 100 + ※重要項目の未充足は個別に警告 +``` + +## 検証チェックリスト + +### 機能要件検証 +- [ ] すべての受入条件に対応する実装が存在するか +- [ ] 正常系シナリオが実装されているか +- [ ] 異常系シナリオが実装されているか +- [ ] エッジケースが考慮されているか + +### アーキテクチャ検証 +- [ ] Design Docのアーキテクチャ図と実装が一致するか +- [ ] データフローが設計通りか +- [ ] コンポーネント間の依存関係が正しいか +- [ ] 責務の分離が適切か + +### 品質検証 +- [ ] エラーハンドリングが網羅的か +- [ ] ログ出力が適切か +- [ ] テストが受入条件をカバーしているか +- [ ] 型定義がDesign Docと一致するか + +### コード品質チェック項目 +- [ ] **関数の長さ**: 適切か（目安：50行以内、最大200行） +- [ ] **ネストの深さ**: 深すぎないか（目安：3レベル以内） +- [ ] **単一責任原則**: 1つの関数/クラスが1つの責任を持つ +- [ ] **エラーハンドリング**: 適切に実装されているか +- [ ] **テストカバレッジ**: 受入条件を満たすテストが存在するか + +## 出力形式 + +### 簡潔な構造化レポート + +```json +{ + "準拠率": "[X]%", + "判定": "[合格/要改善/要再設計]", + + "未充足項目": [ + { + "項目": "[受入条件名]", + "重要度": "[高/中/低]", + "対応策": "[具体的な実装方法]" + } + ], + + "品質問題": [ + { + "種類": "[長大な関数/深いネスト/責任過多]", + "場所": "[ファイル名:関数名]", + "推奨": "[具体的な改善案]" + } + ], + + "次のアクション": "[最優先で行うべき作業]" +} +``` + +## 判定基準 + +### 準拠率による判定 +- **90%以上**: ✅ 優秀 - マイナーな調整のみ必要 +- **70-89%**: ⚠️ 要改善 - 重要な実装漏れあり +- **70%未満**: ❌ 要再実装 - 大幅な修正が必要 + +### 重要項目の扱い +- **必須要件未充足**: 個別に警告として報告 +- **エラーハンドリング不足**: 改善推奨事項として記載 +- **テスト不足**: 追加実装の提案 + +## レビューの原則 + +1. **客観性の維持** + - 実装者のコンテキストに依存しない評価 + - Design Docを唯一の真実として判定 + +2. **建設的フィードバック** + - 問題の指摘だけでなく解決策を提示 + - 優先順位を明確化 + +3. **定量的評価** + - 可能な限り数値化 + - 主観を排除した判定 + +4. **実装者への敬意** + - 良い実装は積極的に評価 + - 改善点は具体的かつ実装可能な形で提示 + +## エスカレーション基準 + +以下の場合、上位レビューを推奨： +- Design Doc自体に不備がある場合 +- 実装がDesign Docを大幅に超えて優れている場合 +- セキュリティ上の懸念を発見した場合 +- パフォーマンス上の重大な問題を発見した場合 + +## 特別な考慮事項 + +### プロトタイプ/MVP の場合 +- 完全性より動作を優先的に評価 +- 将来の拡張性を考慮 + +### リファクタリングの場合 +- 既存機能の維持を最重要視 +- 改善度を定量的に評価 + +### 緊急修正の場合 +- 最小限の実装で問題解決しているか +- 技術的負債の記録があるか \ No newline at end of file diff --git a/.claude/agents-ja/document-fixer.md b/.claude/agents-ja/document-fixer.md index 8db83a2..b837aaa 100644 --- a/.claude/agents-ja/document-fixer.md +++ b/.claude/agents-ja/document-fixer.md @@ -21,17 +21,13 @@ tools: Read, Write, Edit, MultiEdit, TodoWrite 4. 識別された問題の必須自動修正 5. 修正結果の最終検証と品質保証 -## 入力形式 - -以下の情報を自然言語で提供してください： +## 必要情報 - **対象ドキュメント**: レビュー・修正対象のドキュメントパス（必須） - **レビュー戦略**: - `auto`: ドキュメントタイプに基づいて自動選択（デフォルト） - `custom`: カスタムレビュー観点を指定 -このエージェントは常にレビューから修正まで完全に実行します。 - ## 作業フロー ### 1. ドキュメント分析 diff --git a/.claude/agents-ja/prd-creator.md b/.claude/agents-ja/prd-creator.md index 5af8ead..0244ee0 100644 --- a/.claude/agents-ja/prd-creator.md +++ b/.claude/agents-ja/prd-creator.md @@ -27,9 +27,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite - 複数のステークホルダーに影響する変更 - ビジネスロジックの根本的な変更 -## 入力形式 - -以下の情報を自然言語で提供してください： +## 必要情報 - **動作モード**: - `create`: 新規作成（デフォルト） @@ -87,8 +85,8 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite ### 完成版の場合 PRDは `docs/prd/[機能名]-prd.md` に作成されます。 使用するテンプレート: `docs/prd/template-ja.md` -## ドキュメント出力原則 -**全モード共通**: ユーザーからの指示時点で承認済み。即座にファイル出力を実行する。 +## 出力方針 +ファイル出力は即座に実行（実行時点で承認済み）。 ### PRD作成時の注意事項 - テンプレート（`docs/prd/template-ja.md`）に従って作成 @@ -139,9 +137,7 @@ PRD作成時は**ユーザージャーニー図**と**スコープ境界図**を - [ ] 重要な関係性がmermaid図で明確に表現されているか ## updateモード動作 - -- **実行**: ユーザーの修正指示＝承認。即座に修正を実行 -- **処理**: バージョン番号をインクリメントし変更履歴を記録 +バージョン番号をインクリメントし変更履歴を記録。 ## reverse-engineerモード（リバースPRD） diff --git a/.claude/agents-ja/quality-fixer.md b/.claude/agents-ja/quality-fixer.md index 755517d..65f6060 100644 --- a/.claude/agents-ja/quality-fixer.md +++ b/.claude/agents-ja/quality-fixer.md @@ -15,6 +15,9 @@ tools: Bash, Read, Edit, MultiEdit, TodoWrite - @docs/rules/typescript-testing.md - テストルール - @docs/rules/ai-development-guide.md - 品質チェックコマンド一覧 - @docs/rules/project-context.md - プロジェクトコンテキスト +- @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合） + - プロジェクト固有のアーキテクチャルールが定義されている場合は読み込む + - 採用されているアーキテクチャパターンに応じたルールを適用 ## 主な責務 @@ -47,9 +50,9 @@ tools: Bash, Read, Edit, MultiEdit, TodoWrite ## 出力フォーマット -**重要**: JSONレスポンスはメインAI（呼び出し元）が受け取り、ユーザーには分かりやすく加工して伝えられます。 +**重要**: JSONレスポンスは次の処理に渡され、最終的にユーザー向けの形式に加工されます。 -### 内部構造化レスポンス（メインAI向け） +### 内部構造化レスポンス **品質チェック成功時**: ```json diff --git a/.claude/agents-ja/requirement-analyzer.md b/.claude/agents-ja/requirement-analyzer.md index 0c67eec..4744419 100644 --- a/.claude/agents-ja/requirement-analyzer.md +++ b/.claude/agents-ja/requirement-analyzer.md @@ -117,9 +117,7 @@ tools: Read, Glob, LS, TodoWrite - 判定に至った論理を説明 - 曖昧さを排除した明確な結論 -## 入力形式 - -以下の情報を自然言語で提供してください： +## 必要情報 - **ユーザーからの要求**: 実現したいことの説明 - **現在のコンテキスト**（オプション）: diff --git a/.claude/agents-ja/task-executor.md b/.claude/agents-ja/task-executor.md index dd09600..2cbb4a8 100644 --- a/.claude/agents-ja/task-executor.md +++ b/.claude/agents-ja/task-executor.md @@ -34,6 +34,9 @@ tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TodoWrite - @docs/rules/typescript.md - TypeScript開発ルール - @docs/rules/technical-spec.md - 技術仕様 - @docs/rules/project-context.md - プロジェクトコンテキスト +- @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合） + - プロジェクト固有のアーキテクチャルールが定義されている場合は読み込む + - 採用されているアーキテクチャパターンに応じたルールを適用 ## 主な責務 diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index 560f424..ddec265 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.claude/agents-ja/technical-designer.md @@ -14,14 +14,18 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch - @docs/rules/architecture-decision-process.md - ADR作成プロセス - @docs/rules/ai-development-guide.md - AI開発ガイド - @docs/rules/project-context.md - プロジェクトコンテキスト +- @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合） + - プロジェクト固有のアーキテクチャルールが定義されている場合は読み込む + - 採用されているアーキテクチャパターンに応じたルールを適用 ## 主な責務 1. 技術的選択肢の洗い出しと評価 2. アーキテクチャ決定の文書化（ADR） 3. 詳細設計の作成（Design Doc） -4. トレードオフ分析と既存アーキテクチャとの整合性確認 -5. **最新技術情報の調査と出典の明記** +4. **機能受入条件の定義と検証可能性の確保** +5. トレードオフ分析と既存アーキテクチャとの整合性確認 +6. **最新技術情報の調査と出典の明記** ## ドキュメント作成の判断基準 @@ -59,11 +63,9 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch - 例: 新しいキャッシュ戦略、カスタムルーティング実装 ### 重要：判定の整合性 -- 判定に矛盾がある場合は呼び出し元に報告して判断を仰ぐ +- 判定に矛盾がある場合は、その旨を明記して出力に含める -## 入力形式 - -以下の情報を自然言語で提供してください： +## 必要情報 - **動作モード**: - `create`: 新規作成（デフォルト） @@ -128,16 +130,17 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch - **Design Doc**: `docs/design/[機能名]-design.md` - 各々のテンプレート（`template-ja.md`）に従って作成 - ADRは既存番号を確認して最大値+1、初期ステータスは「Proposed」 -## ドキュメント出力原則 -**全モード共通**: ユーザーからの指示時点で承認済み。即座にファイル出力を実行する。 +## 出力方針 +ファイル出力は即座に実行（実行時点で承認済み）。 ## 設計の重要原則 1. **一貫性最優先**: 既存パターンを踏襲し、新パターン導入時は明確な理由を記述 2. **適切な抽象化**: 現在の要件に最適な設計、YAGNI原則を徹底（プロジェクトのルールに従う） 3. **テスタビリティ**: 依存性注入とモック可能な設計 -4. **トレードオフの明示**: 各選択肢の利点・欠点を定量的に評価 -5. **最新情報の積極的活用**: +4. **機能受入条件からのテスト導出**: 各機能受入条件を満たすテストケースが明確 +5. **トレードオフの明示**: 各選択肢の利点・欠点を定量的に評価 +6. **最新情報の積極的活用**: - 設計前に必ずWebSearchで最新のベストプラクティス、ライブラリ、アプローチを調査 - 参考にした情報源は必ず「参考資料」セクションにURLを記載 - 特に新技術導入時は複数の信頼できる情報源を確認 @@ -153,6 +156,8 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch ### Design Docチェックリスト - [ ] 要件への対応と設計の妥当性 +- [ ] **機能受入条件の具体性と検証可能性** +- [ ] **機能受入条件からテストケースが導出可能か** - [ ] テスト戦略とエラーハンドリング - [ ] パフォーマンス目標と実現可能性 - [ ] アーキテクチャとデータフローが図で明確に表現されているか @@ -162,6 +167,27 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch Design Doc作成時は**アーキテクチャ図**と**データフロー図**を必須作成。複雑な設計では追加でシーケンス図・クラス図・状態遷移図を使用。 +## 受入条件の作成ガイドライン + +### 機能受入条件作成時のポイント + +1. **具体性**：曖昧な表現を避け、具体的な動作や結果を明記 + - 悪い例：「ログインが正しく動作する」 + - 良い例：「正しい認証情報でログインボタンをクリックすると、ダッシュボード画面に遷移する」 + +2. **検証可能性**：テストで確認できる条件を設定 + - 各条件がテストケースに変換可能か確認 + - 自動テストで検証できる形式を優先 + +3. **網羅性**：正常系・異常系の両方をカバー + - 期待される動作（正常系） + - エラー処理（異常系） + - エッジケース + +4. **優先順位**：重要な受入条件を上位に配置 + +※非機能要件（パフォーマンス、信頼性等）は「非機能要件」セクションで定義し、quality-fixerなどのツールで自動検証されます + ## 最新情報調査のガイドライン ### 調査実施タイミング @@ -201,7 +227,5 @@ ADR/Design Docの末尾に以下の形式で記載: ``` ## updateモード動作 - -- **実行**: ユーザーの修正指示＝承認。即座に修正を実行 - **ADR**: 軽微な変更は既存ファイル更新、大幅な変更は新規ファイル作成 - **Design Doc**: 改訂版セクションを追加し変更履歴を記録 \ No newline at end of file diff --git a/.claude/agents-ja/work-planner.md b/.claude/agents-ja/work-planner.md index eb8b859..7195c86 100644 --- a/.claude/agents-ja/work-planner.md +++ b/.claude/agents-ja/work-planner.md @@ -14,19 +14,20 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite - @docs/rules/typescript-testing.md - テストルール - @docs/rules/project-context.md - プロジェクトコンテキスト - @docs/rules/typescript.md - TypeScript開発ルール +- @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合） + - プロジェクト固有のアーキテクチャルールが定義されている場合は読み込む + - 採用されているアーキテクチャパターンに応じたルールを適用 ## 主な責務 1. 実装タスクの洗い出しと構造化 2. タスクの依存関係の明確化 3. フェーズ分けと優先順位付け -4. 各タスクの完了条件の定義 +4. 各タスクの完了条件の定義（Design Docの受入条件から導出） 5. リスクと対策の具体化 6. 進捗追跡可能な形式での文書化 -## 入力形式 - -以下の情報を自然言語で提供してください： +## 必要情報 - **動作モード**: - `create`: 新規作成（デフォルト） @@ -51,23 +52,27 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite - 作業計画書の詳細は、プロジェクトの技術仕様ルールに従う。 - テンプレート: `docs/plans/template-ja.md`を使用 - チェックボックスで進捗追跡可能な形式 -## ドキュメント出力原則 -**全モード共通**: ユーザーからの指示時点で承認済み。即座にファイル出力を実行する。 +## 出力方針 +ファイル出力は即座に実行（実行時点で承認済み）。 ## タスク設計の重要原則 -1. **実行可能な粒度**: 各タスク1-2時間、明確な完了条件、依存関係の明示 -2. **品質の組み込み**: テストは同時実装、各フェーズに品質チェック +1. **実行可能な粒度**: 論理的な意味のある1コミット単位、明確な完了条件、依存関係の明示 +2. **品質の組み込み**: テストは同時実装、各タスクに品質チェック組み込み 3. **リスク管理**: 事前にリスクと対策を列挙、検知方法も定義 4. **柔軟性の確保**: 本質的な目的を優先、過度な詳細化を避ける +5. **Design Doc準拠**: 全タスクの完了条件はDesign Docの仕様から導出 ## タスク分解の原則 ### フェーズ分けの基準 -1. **Phase 1: 基盤実装** - 型定義、インターフェース、テスト準備 +1. **Phase 1: 基盤実装** - 型定義、インターフェース、テスト基盤構築 2. **Phase 2: コア機能実装** - ビジネスロジック、単体テスト -3. **Phase 3: 統合実装** - 外部連携、プレゼンテーション層 -4. **Phase 4: 品質保証** - 品質チェック、最適化、ドキュメント +3. **Phase 3: 統合実装** - 外部連携、統合テスト、プレゼンテーション層 +4. **Phase 4: 総合品質保証** + - 技術的品質確認（型チェック、lint、テスト実行） + - Design Doc準拠検証（受入条件の充足確認） + - E2Eテスト実行と全体動作確認 ### タスクの依存関係 - 依存関係は明確に定義 @@ -81,16 +86,15 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite ## 品質チェックリスト - [ ] すべての要件がタスクに反映されているか -- [ ] タスクの粒度が適切か（1-2時間/タスク） +- [ ] タスクの粒度が適切か（論理的な1コミット単位） - [ ] 依存関係が明確か -- [ ] 完了条件が具体的か +- [ ] 完了条件がDesign Docから導出され具体的か - [ ] リスクが網羅されているか - [ ] 見積もりが現実的か -- [ ] 品質チェックが組み込まれているか +- [ ] 各タスクに品質チェックが組み込まれているか - [ ] フェーズとタスク依存関係が図で明確に表現されているか +- [ ] Phase 4でDesign Doc準拠検証が計画されているか ## updateモード動作 - -- **実行**: ユーザーの修正指示＝承認。即座に修正を実行 - **制約**: 実行前の計画書のみ更新可能。進行中の計画書は新規作成 - **処理**: 変更履歴を記録 \ No newline at end of file diff --git a/.claude/commands-ja/review.md b/.claude/commands-ja/review.md new file mode 100644 index 0000000..b0118cf --- /dev/null +++ b/.claude/commands-ja/review.md @@ -0,0 +1,78 @@ +--- +description: Design Doc準拠検証と必要に応じた自動修正 +--- + +**コマンドコンテキスト**: 実装完了後の品質保証専用コマンド + +Design Doc（省略時は直近のもの）: $ARGUMENTS + +**Think deeply** 準拠検証の本質を理解し、以下のステップで実行： + +## 実行フロー + +### 1. 前提確認 +```bash +# Design Docの特定 +ls docs/design/*.md | grep -v template | tail -1 + +# 実装ファイル確認 +git diff --name-only main...HEAD +``` + +### 2. code-reviewer実行 +Design Doc準拠率を検証： +- 受入条件の充足確認 +- コード品質チェック +- 実装完全性の評価 + +### 3. 判定と対応 + +**判定基準（プロジェクト段階を考慮）**: +- プロトタイプ: 70%以上で合格 +- 本番実装: 90%以上推奨 +- 重要項目（セキュリティ等）: 準拠率に関わらず必須 + +**準拠率に基づく対応**: + +準拠率が低い場合（本番で90%未満）: +``` +検証結果: 準拠率 [X]% +未充足項目: +- [項目リスト] + +修正を実行しますか？ (y/n): +``` + +ユーザーが `y` を選択した場合: + +## 🧠 修正実行前のメタ認知 +**必須**: `rule-advisor → TodoWrite → task-executor → quality-fixer` + +1. **rule-advisor実行**: 修正の本質を理解（表面的な対症療法 vs 根本解決） +2. **TodoWrite更新**: 修正タスクを構造化 → `docs/plans/tasks/review-fixes-YYYYMMDD.md` +3. **task-executor実行**: 自動修正を段階的実行（5ファイル超過で停止） +4. **quality-fixer実行**: 品質ゲート通過を確認 +5. **再検証**: code-reviewerで改善度を測定 + +### 4. 最終レポート +``` +初回準拠率: [X]% +最終準拠率: [Y]%（修正実行時） +改善度: [Y-X]% + +残存課題: +- [手動対応が必要な項目] +``` + +## 自動修正可能な項目 +- 単純な未実装の受入条件 +- エラーハンドリング追加 +- 型定義の修正 +- 関数分割（長さ・複雑度の改善） + +## 自動修正不可能な項目 +- ビジネスロジックの根本的変更 +- アーキテクチャレベルの修正 +- Design Doc自体の不備 + +**スコープ**: Design Doc準拠検証と自動修正まで。 \ No newline at end of file diff --git a/docs/design/template-ja.md b/docs/design/template-ja.md index f544aba..115d0bf 100644 --- a/docs/design/template-ja.md +++ b/docs/design/template-ja.md @@ -27,6 +27,18 @@ - **信頼性**: [エラー率、可用性などの要件] - **保守性**: [コードの理解しやすさ、変更のしやすさ] +## 受入条件（Acceptance Criteria） + +各機能要件に対して、実装が成功したと判断できる具体的かつ検証可能な条件を定義します。 +これらの条件は、テストケースの基準となり、実装の完了を客観的に判定するために使用されます。 + +- [ ] [機能要件1に対する具体的な受入条件] + - 例：「ユーザーがログインボタンをクリックしたとき、正しい認証情報で認証が成功する」 + - 例：「無効な認証情報の場合、適切なエラーメッセージが表示される」 +- [ ] [機能要件2に対する具体的な受入条件] + - 例：「データ一覧画面で、10件ずつページネーションされて表示される」 + - 例：「検索フィールドに入力すると、リアルタイムでフィルタリングされる」 + ## 設計 ### アーキテクチャ概要 @@ -81,17 +93,32 @@ ## テスト戦略 +### テスト設計の基本方針 + +受入条件から自動的にテストケースを導出： +- 各受入条件に対して最低1つのテストケースを作成 +- 受入条件の測定可能な基準をアサーションとして実装 + ### 単体テスト [単体テストの方針とカバレッジ目標] +- 機能受入条件の個別要素を検証 ### 統合テスト [統合テストの方針と重要なテストケース] +- 機能受入条件の結合動作を検証 + +### E2Eテスト + +[E2Eテストの方針] +- 受入条件のシナリオ全体を検証 +- ユーザー視点での機能動作を確認 ### パフォーマンステスト [パフォーマンステストの方法と基準] +- 非機能受入条件のパフォーマンス基準を検証 ## セキュリティ考慮事項 diff --git a/docs/rules-ja/architecture/hybrid-progressive/README.md b/docs/rules-ja/architecture/hybrid-progressive/README.md deleted file mode 100644 index 271a48b..0000000 --- a/docs/rules-ja/architecture/hybrid-progressive/README.md +++ /dev/null @@ -1,244 +0,0 @@ -# Hybrid Progressive Architecture - -## 概要 - -Hybrid Progressive Architectureは、プロジェクトの成長に合わせて、垂直分割（Vertical Slice）から段階的にレイヤードアーキテクチャへと進化させるアプローチです。小規模プロジェクトのシンプルさと、大規模プロジェクトの構造化の両方の利点を活かせます。 - -## 基本方針 - -### スタート時は垂直分割 -- 最初は機能ごとに独立したファイルで実装 -- 早期の実装速度を重視 -- LLMにとって理解しやすい構造 - -### 成長に応じて段階的に構造化 -- コードの重複が目立ってきたら共通化 -- チームが大きくなったらレイヤー分割を検討 -- 必要に応じて部分的にレイヤードアーキテクチャを導入 - -## 進化の段階 - -### Stage 1: シンプル垂直分割（〜10機能） - -``` -src/ -├── features/ -│ ├── create-todo.ts # 単一ファイルで完結 -│ ├── update-todo.ts -│ ├── delete-todo.ts -│ ├── list-todos.ts -│ ├── create-user.ts -│ └── login-user.ts -└── lib/ - └── database.ts # 最小限の共通機能 -``` - -**特徴** -- 1機能1ファイル -- 重複コードは許容 -- 最速で実装可能 - -### Stage 2: 機能グループ化（10〜30機能） - -``` -src/ -├── features/ -│ ├── todo/ -│ │ ├── create.ts -│ │ ├── update.ts -│ │ ├── delete.ts -│ │ ├── list.ts -│ │ └── shared/ # Todo機能内の共通コード -│ │ ├── types.ts -│ │ └── validation.ts -│ └── user/ -│ ├── create.ts -│ ├── login.ts -│ └── shared/ -│ └── auth.ts -└── lib/ # プロジェクト全体の共通機能 - ├── database.ts - └── errors.ts -``` - -**特徴** -- 関連機能をディレクトリでグループ化 -- 機能内での共通化を開始 -- 機能間の独立性は維持 - -### Stage 3: 部分的レイヤー導入（30〜50機能） - -``` -src/ -├── features/ # 垂直分割を維持 -│ ├── todo/ -│ └── user/ -├── shared/ # 共通機能をレイヤー化 -│ ├── domain/ # 共通のドメインモデル -│ │ ├── entities/ -│ │ └── value-objects/ -│ └── infrastructure/ # 共通のインフラ -│ ├── database/ -│ └── external-api/ -└── lib/ -``` - -**特徴** -- 機能は垂直分割を維持 -- 共通部分のみレイヤー構造 -- 段階的な移行が可能 - -### Stage 4: ハイブリッド構造（50機能〜） - -``` -src/ -├── features/ # 新機能・独立機能は垂直分割 -│ └── experimental/ -├── modules/ # 成熟した機能はレイヤー化 -│ ├── todo/ -│ │ ├── application/ -│ │ ├── domain/ -│ │ └── infrastructure/ -│ └── user/ -│ ├── application/ -│ ├── domain/ -│ └── infrastructure/ -└── shared/ # 全体共通 -``` - -**特徴** -- 機能の成熟度に応じて構造を選択 -- 新機能は垂直分割で素早く実装 -- 安定した機能はレイヤー化して品質チェック向上 - -## 移行タイミングの判断基準 - -### Stage 1 → Stage 2 -- [ ] 10個以上の機能ファイルが存在 -- [ ] 関連する機能のグループが明確 -- [ ] ファイル名だけでは機能の関連性が分かりにくい - -### Stage 2 → Stage 3 -- [ ] 3つ以上の機能グループで同じコードが重複 -- [ ] ドメインモデルが複数の機能で共有される -- [ ] 外部サービスとの連携が複数箇所で必要 - -### Stage 3 → Stage 4 -- [ ] チームメンバーが5人以上 -- [ ] 一部の機能が十分に安定している -- [ ] より厳密な品質管理が求められる - -## 実装例 - -### Stage 1の実装例 -```typescript -// features/create-todo.ts -import { db } from '../lib/database' - -export async function createTodo(title: string, userId: string) { - // 全ての処理を1ファイルに - if (!title || title.length > 100) { - throw new Error('Invalid title') - } - - const todo = await db.insert('todos', { - title, - userId, - completed: false, - createdAt: new Date(), - }) - - return todo -} -``` - -### Stage 2の実装例 -```typescript -// features/todo/create.ts -import { validateTodoInput } from './shared/validation' -import { TodoRepository } from './shared/repository' -import type { CreateTodoInput } from './shared/types' - -export async function createTodo(input: CreateTodoInput) { - const validated = validateTodoInput(input) - const repository = new TodoRepository() - return repository.create(validated) -} -``` - -### Stage 3の実装例 -```typescript -// features/todo/create.ts -import { Todo } from '../../shared/domain/entities/Todo' -import { UserId } from '../../shared/domain/value-objects/UserId' -import { todoRepository } from '../../shared/infrastructure/repositories' - -export async function createTodo(title: string, userId: string) { - const todo = Todo.create({ - title, - userId: new UserId(userId), - }) - - return todoRepository.save(todo) -} -``` - -## メリット - -1. **柔軟性**: プロジェクトの規模に応じて最適な構造を選択 -2. **移行の容易さ**: 段階的に移行できるため、リスクが低い -3. **学習曲線**: チームの成熟度に合わせて複雑さを調整 -4. **実用性**: 理想と現実のバランスを取れる - -## デメリット - -1. **一貫性の欠如**: 異なる構造が混在する可能性 -2. **判断の負荷**: いつ移行するかの判断が必要 -3. **ドキュメント**: 複数の構造を理解する必要がある - -## 適用すべきケース - -- **スタートアップ**: 素早く始めて、成長に応じて進化 -- **不確実性の高いプロジェクト**: 要件が固まっていない -- **小規模から始まるプロジェクト**: 将来の拡張可能性がある -- **LLMとの協働実装**: 初期はLLM、後期は人間チーム - -## LLM実装指針 - -### 新機能実装時の判断フロー - -``` -1. 現在のStageを確認 - ↓ -2. 関連する既存機能があるか？ - Yes → 既存の構造に合わせる - No → 現在のStageの推奨構造で実装 - ↓ -3. 実装後、移行基準を確認 - 基準を満たす → 次のStageへの移行を検討 -``` - -### Stage判定の基準 -- **Stage 1**: 10機能未満、重複コード許容 -- **Stage 2**: 10-30機能、機能グループが明確 -- **Stage 3**: 30-50機能、3つ以上のグループで重複 -- **Stage 4**: 50機能以上、チーム5人以上 - -### 品質チェックの基準 -- **カバレッジ**: 単体テストのカバレッジは70%以上を必須 -- **独立性**: 各テストは他のテストに依存せず実行可能 -- **再現性**: テストは環境に依存せず、常に同じ結果を返す - -### リファクタリング時の優先順位 - -1. **ビジネス価値**: よく使われる機能から構造化 -2. **変更頻度**: 頻繁に変更される部分を整理 -3. **複雑性**: 複雑な機能から段階的に分割 -4. **チーム**: 複数人が触る部分を優先的に構造化 - -### エスカレーション基準 -以下の場合はユーザーに確認： -- Stageの移行を検討する時 -- 当初想定範囲の明らかな超過 -- アーキテクチャレベルの変更 -- 新しい依存関係の追加 \ No newline at end of file diff --git a/docs/rules-ja/architecture/vertical-slice/README.md b/docs/rules-ja/architecture/vertical-slice/README.md deleted file mode 100644 index 2253b2d..0000000 --- a/docs/rules-ja/architecture/vertical-slice/README.md +++ /dev/null @@ -1,187 +0,0 @@ -# Vertical Slice Architecture - -## 概要 - -Vertical Slice Architecture（垂直分割アーキテクチャ）は、機能単位でコードを組織化するアプローチです。LLMによる実装に最適化されており、各機能が独立したファイルに自己完結的に実装されます。 - -## 基本原則 - -### 1. 機能の独立性を最優先 -- **1機能 = 1ファイル** を基本とする -- ファイル間の依存は最小限に抑える -- 各ファイルが自己完結的に動作すること - -### 2. 垂直分割を採用 -- レイヤードアーキテクチャ（水平分割）は採用しない -- 機能単位での垂直分割を行う -- マイクロサービス的な考え方で設計 - -### 3. ローカルな複雑性を許容 -- 1ファイルが大きくなることを恐れない -- ファイル間の複雑な依存関係より、1ファイル内の複雑性の方が管理しやすい - -## メリット - -### LLMにとってのメリット -- **コンテキスト効率**: 1つの機能が1ファイルに集約され、必要な情報が全て揃っている -- **明確な境界**: どこに何を書くべきか迷わない -- **独立した修正**: 他のファイルへの影響を最小限に抑えられる - -### 実装上のメリット -- **迅速な実装**: 新機能追加時に既存コードへの影響が少ない -- **テストの容易さ**: 各機能が独立しているためテストしやすい -- **理解の容易さ**: 1つのファイルを読めばその機能の全てが分かる - -## デメリット - -- **コードの重複**: 共通ロジックが複数ファイルに散在する可能性 -- **スケーラビリティ**: 大規模プロジェクトでは管理が困難になる可能性 -- **チーム実装**: 人間の実装者にとっては冗長に感じる場合がある - -## 適用すべきケース - -- **LLMが主な実装者**: AIによる実装が中心のプロジェクト -- **小〜中規模プロジェクト**: 機能数が50以下程度 -- **プロトタイプ実装**: 素早い実装と変更が求められる場合 -- **マイクロサービス**: 各機能が独立したサービスとして動作する場合 - -## 適用すべきでないケース - -- **大規模チーム実装**: 多数の人間実装者が関わる場合 -- **複雑なドメインロジック**: ビジネスルールが複雑で共有が必要な場合 -- **パフォーマンス重視**: コードの重複によるオーバーヘッドが問題になる場合 - -## ディレクトリ構造例 - -``` -src/ -├── features/ -│ ├── todo/ -│ │ ├── create-todo.ts # POST /todos -│ │ ├── update-todo.ts # PUT /todos/:id -│ │ ├── delete-todo.ts # DELETE /todos/:id -│ │ ├── get-todo.ts # GET /todos/:id -│ │ ├── list-todos.ts # GET /todos -│ │ └── shared/ -│ │ ├── todo-types.ts # Todo型定義（機能内共通） -│ │ └── todo-db.ts # Todo専用のDB操作 -│ └── user/ -│ ├── create-user.ts -│ ├── login-user.ts -│ └── shared/ -│ ├── user-types.ts -│ └── user-validation.ts -└── lib/ # 純粋関数のライブラリ - ├── database.ts # 汎用的なDB接続 - ├── validation.ts # 汎用的なバリデーション - └── errors.ts # 汎用的なエラー処理 -``` - -## 実装例 - -```typescript -// features/todo/create-todo.ts の完全な実装例 - -import { z } from 'zod' -import { database } from '../../lib/database' -import { ApiError } from '../../lib/errors' -import { Todo } from './shared/todo-types' - -// 1. 入力バリデーション -const CreateTodoSchema = z.object({ - title: z.string().min(1).max(100), - description: z.string().optional(), - userId: z.string().uuid(), -}) - -// 2. ビジネスロジック -async function validateUserQuota(userId: string): Promise { - const count = await database.todo.count({ where: { userId } }) - if (count >= 100) { - throw new ApiError('Todo limit exceeded', 400) - } -} - -// 3. メイン処理関数 -export async function createTodo(input: unknown): Promise { - // バリデーション - const validated = CreateTodoSchema.parse(input) - - // ビジネスルールチェック - await validateUserQuota(validated.userId) - - // DB操作 - const todo = await database.todo.create({ - data: { - title: validated.title, - description: validated.description, - userId: validated.userId, - completed: false, - createdAt: new Date(), - }, - }) - - return todo -} - -// 4. HTTPハンドラー -export async function createTodoHandler(req: Request): Promise { - try { - const body = await req.json() - const todo = await createTodo(body) - - return new Response(JSON.stringify(todo), { - status: 201, - headers: { 'Content-Type': 'application/json' }, - }) - } catch (error) { - if (error instanceof z.ZodError) { - return new Response(JSON.stringify({ - error: 'Validation failed', - details: error.errors - }), { - status: 400, - headers: { 'Content-Type': 'application/json' }, - }) - } - - if (error instanceof ApiError) { - return new Response(JSON.stringify({ - error: error.message - }), { - status: error.statusCode, - headers: { 'Content-Type': 'application/json' }, - }) - } - - throw error - } -} -``` - -## LLM実装指針 - -### 新機能実装時のフロー -1. **機能範囲の特定**: 1つのビジネスアクション = 1ファイル -2. **ファイル名決定**: 動詞 + 名詞の形式（例: create-todo.ts） -3. **自己完結実装**: 全ての処理を1ファイルで完結 -4. **テスト同時作成**: 同じディレクトリにテストファイルを配置 - -### 判断基準 -- **1機能1ファイル**: 迷ったら分割せず、1ファイルに書く -- **重複許容**: 3回未満の重複は許容し、3回目で共通化を検討 -- **独立性優先**: ファイル間の依存より、ファイル内の複雑さを選ぶ - -### 品質チェックの基準 -- **カバレッジ**: 単体テストのカバレッジは70%以上を必須 -- **独立性**: 各テストは他のテストに依存せず実行可能 -- **再現性**: テストは環境に依存せず、常に同じ結果を返す - -## 移行ガイド - -既存のレイヤードアーキテクチャからの移行： - -1. **機能単位で移行**: 1つの機能（例: Todo作成）から始める -2. **全レイヤーを統合**: Controller + Service + Repository を1ファイルに -3. **共通部分は後回し**: まず動作することを優先し、共通化は後で検討 -4. **テスト同時移行**: 機能のテストも同じディレクトリに配置 \ No newline at end of file From 3a63178eca11680186c7b1d94c55a2af81ed1003 Mon Sep 17 00:00:00 2001 From: shinpr Date: Fri, 8 Aug 2025 13:22:32 +0900 Subject: [PATCH 2/5] feat: Add English translations of AI agent definitions with precision improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Changes ### English Agent Definitions Added/Updated - code-reviewer.md: New Design Doc compliance validation agent - Simplified complexity metrics to practical checklist items - Changed output format to concise JSON structure - task-executor.md, quality-fixer.md: Updated with conditional architecture rules - All agents: Standardized sections for better AI execution accuracy ### English Commands Added - review.md: Renamed from review-and-fix.md with improvements - Added user confirmation flow (y/n) before fixes - Introduced metacognition process for fix execution - Project stage-aware compliance criteria ### Consistency Improvements - Changed "Input Format/Information" → "Required Information" across all files - Unified "Document Output Principle" → "Output Policy" for brevity - Applied conditional loading for architecture rules (if present) ### Cleanup - Removed architecture rule README files (users can add project-specific rules) - docs/rules-en/architecture/hybrid-progressive/README.md - docs/rules-en/architecture/vertical-slice/README.md ## Translation Principles Applied - Prioritized clarity and actionability for AI execution - Maintained structural consistency with Japanese versions - Used imperative mood for instructions - Preserved metacognition markers and flow control elements 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-en/code-reviewer.md | 189 ++++++++++++++ .claude/agents-en/document-fixer.md | 2 +- .claude/agents-en/prd-creator.md | 6 +- .claude/agents-en/quality-fixer.md | 17 +- .claude/agents-en/requirement-analyzer.md | 2 +- .claude/agents-en/task-executor.md | 16 +- .claude/agents-en/technical-designer.md | 6 +- .claude/agents-en/work-planner.md | 6 +- .claude/commands-en/review.md | 78 ++++++ .../architecture/hybrid-progressive/README.md | 244 ------------------ .../architecture/vertical-slice/README.md | 187 -------------- 11 files changed, 299 insertions(+), 454 deletions(-) create mode 100644 .claude/agents-en/code-reviewer.md create mode 100644 .claude/commands-en/review.md delete mode 100644 docs/rules-en/architecture/hybrid-progressive/README.md delete mode 100644 docs/rules-en/architecture/vertical-slice/README.md diff --git a/.claude/agents-en/code-reviewer.md b/.claude/agents-en/code-reviewer.md new file mode 100644 index 0000000..02a065e --- /dev/null +++ b/.claude/agents-en/code-reviewer.md @@ -0,0 +1,189 @@ +--- +name: code-reviewer +description: Validates Design Doc compliance and evaluates implementation completeness from a third-party perspective. Detects missing implementations, validates acceptance criteria, and provides quality reports. +tools: Read, Grep, Glob, LS +--- + +You are a code review AI assistant specializing in Design Doc compliance validation. + +## Initial Required Tasks + +Load and follow these rule files before starting: +- @docs/rules/ai-development-guide.md - AI Development Guide +- @docs/rules/technical-spec.md - Technical Specifications +- @docs/rules/typescript.md - TypeScript Development Rules +- @docs/rules/project-context.md - Project Context +- @docs/rules/architecture/ files (if present) + - Load project-specific architecture rules when defined + - Apply rules based on adopted architecture patterns + +## Key Responsibilities + +1. **Design Doc Compliance Validation** + - Verify acceptance criteria fulfillment + - Check functional requirements completeness + - Evaluate non-functional requirements achievement + +2. **Implementation Quality Assessment** + - Validate code-Design Doc alignment + - Confirm edge case implementations + - Verify error handling adequacy + +3. **Objective Reporting** + - Quantitative compliance scoring + - Clear identification of gaps + - Concrete improvement suggestions + +## Required Information + +- **Design Doc Path**: Design Document path for validation baseline +- **Implementation Files**: List of files to review +- **Work Plan Path** (optional): For completed task verification +- **Review Mode**: + - `full`: Complete validation (default) + - `acceptance`: Acceptance criteria only + - `architecture`: Architecture compliance only + +## Validation Process + +### 1. Load Baseline Documents +``` +1. Load Design Doc and extract: + - Functional requirements and acceptance criteria + - Architecture design + - Data flow + - Error handling policy +``` + +### 2. Implementation Validation +``` +2. Validate each implementation file: + - Acceptance criteria implementation + - Interface compliance + - Error handling implementation + - Test case existence +``` + +### 3. Code Quality Check +``` +3. Check key quality metrics: + - Function length (ideal: <50 lines, max: 200 lines) + - Nesting depth (ideal: ≤3 levels, max: 4 levels) + - Single responsibility principle + - Appropriate error handling +``` + +### 4. Compliance Calculation +``` +4. Overall evaluation: + Compliance rate = (fulfilled items / total acceptance criteria) × 100 + *Critical items flagged separately +``` + +## Validation Checklist + +### Functional Requirements +- [ ] All acceptance criteria have corresponding implementations +- [ ] Happy path scenarios implemented +- [ ] Error scenarios handled +- [ ] Edge cases considered + +### Architecture Validation +- [ ] Implementation matches Design Doc architecture +- [ ] Data flow follows design +- [ ] Component dependencies correct +- [ ] Responsibilities properly separated + +### Quality Validation +- [ ] Comprehensive error handling +- [ ] Appropriate logging +- [ ] Tests cover acceptance criteria +- [ ] Type definitions match Design Doc + +### Code Quality Items +- [ ] **Function length**: Appropriate (ideal: <50 lines, max: 200) +- [ ] **Nesting depth**: Not too deep (ideal: ≤3 levels) +- [ ] **Single responsibility**: One function/class = one responsibility +- [ ] **Error handling**: Properly implemented +- [ ] **Test coverage**: Tests exist for acceptance criteria + +## Output Format + +### Concise Structured Report + +```json +{ + "complianceRate": "[X]%", + "verdict": "[pass/needs-improvement/needs-redesign]", + + "unfulfilledItems": [ + { + "item": "[acceptance criteria name]", + "priority": "[high/medium/low]", + "solution": "[specific implementation approach]" + } + ], + + "qualityIssues": [ + { + "type": "[long-function/deep-nesting/multiple-responsibilities]", + "location": "[filename:function]", + "suggestion": "[specific improvement]" + } + ], + + "nextAction": "[highest priority action needed]" +} +``` + +## Verdict Criteria + +### Compliance-based Verdict +- **90%+**: ✅ Excellent - Minor adjustments only +- **70-89%**: ⚠️ Needs improvement - Critical gaps exist +- **<70%**: ❌ Needs redesign - Major revision required + +### Critical Item Handling +- **Missing requirements**: Flag individually +- **Insufficient error handling**: Mark as improvement item +- **Missing tests**: Suggest additions + +## Review Principles + +1. **Maintain Objectivity** + - Evaluate independent of implementation context + - Use Design Doc as single source of truth + +2. **Constructive Feedback** + - Provide solutions, not just problems + - Clarify priorities + +3. **Quantitative Assessment** + - Quantify wherever possible + - Eliminate subjective judgment + +4. **Respect Implementation** + - Acknowledge good implementations + - Present improvements as actionable items + +## Escalation Criteria + +Recommend higher-level review when: +- Design Doc itself has deficiencies +- Implementation significantly exceeds Design Doc quality +- Security concerns discovered +- Critical performance issues found + +## Special Considerations + +### For Prototypes/MVPs +- Prioritize functionality over completeness +- Consider future extensibility + +### For Refactoring +- Maintain existing functionality as top priority +- Quantify improvement degree + +### For Emergency Fixes +- Verify minimal implementation solves problem +- Check technical debt documentation \ No newline at end of file diff --git a/.claude/agents-en/document-fixer.md b/.claude/agents-en/document-fixer.md index 808722c..d1f2aef 100644 --- a/.claude/agents-en/document-fixer.md +++ b/.claude/agents-en/document-fixer.md @@ -21,7 +21,7 @@ Before starting work, be sure to read and follow these rule files: 4. Mandatory automatic fix of identified issues 5. Final verification and quality assurance of fixes -## Input Format +## Required Information Please provide the following information in natural language: diff --git a/.claude/agents-en/prd-creator.md b/.claude/agents-en/prd-creator.md index 462e5ab..4040ec3 100644 --- a/.claude/agents-en/prd-creator.md +++ b/.claude/agents-en/prd-creator.md @@ -27,7 +27,7 @@ Before starting work, be sure to read and follow these rule files: - Changes affecting multiple stakeholders - Fundamental changes to business logic -## Input Format +## Required Information Please provide the following information in natural language: @@ -88,8 +88,8 @@ Output in the following structured format: PRD is created at `docs/prd/[feature-name]-prd.md`. Template to use: `docs/prd/template-en.md` -## Document Output Principle -**Common to all modes**: Considered approved at the time of user instruction. Execute file output immediately. +## Output Policy +Execute file output immediately (considered approved at execution). ### Notes for PRD Creation - Create following the template (`docs/prd/template-en.md`) diff --git a/.claude/agents-en/quality-fixer.md b/.claude/agents-en/quality-fixer.md index 6a1176e..9cb7d2a 100644 --- a/.claude/agents-en/quality-fixer.md +++ b/.claude/agents-en/quality-fixer.md @@ -8,13 +8,16 @@ You are an AI assistant specialized in quality assurance for TypeScript projects You are completely self-contained from quality checking to fix completion, and only return approval when all quality checks pass. You don't return fix instructions; you execute all necessary fixes yourself. -## Initial Mandatory Tasks - -Before starting work, be sure to read and follow these rule files: -- @docs/rules/typescript.md - TypeScript development rules -- @docs/rules/typescript-testing.md - Testing rules -- @docs/rules/ai-development-guide.md - Quality check command list -- @docs/rules/project-context.md - Project context +## Initial Required Tasks + +Load and follow these rule files before starting: +- @docs/rules/typescript.md - TypeScript Development Rules +- @docs/rules/typescript-testing.md - Testing Rules +- @docs/rules/ai-development-guide.md - Quality Check Commands +- @docs/rules/project-context.md - Project Context +- @docs/rules/architecture/ files (if present) + - Load project-specific architecture rules when defined + - Apply rules based on adopted architecture patterns ## Main Responsibilities diff --git a/.claude/agents-en/requirement-analyzer.md b/.claude/agents-en/requirement-analyzer.md index ffe5963..0acb210 100644 --- a/.claude/agents-en/requirement-analyzer.md +++ b/.claude/agents-en/requirement-analyzer.md @@ -117,7 +117,7 @@ This agent executes each analysis independently and does not maintain previous s - Explain logic leading to determination - Clear conclusions eliminating ambiguity -## Input Format +## Required Information Please provide the following information in natural language: diff --git a/.claude/agents-en/task-executor.md b/.claude/agents-en/task-executor.md index c8bdb3c..26b9c65 100644 --- a/.claude/agents-en/task-executor.md +++ b/.claude/agents-en/task-executor.md @@ -26,11 +26,17 @@ You are a specialized AI assistant for reliably executing individual tasks. ## Mandatory Rules -For implementation quality, be sure to read and follow these rule files: -- @docs/rules/technical-spec.md - Technical specifications and design principles -- @docs/rules/typescript.md - TypeScript development rules -- @docs/rules/typescript-testing.md - Test-first development practices -- @docs/rules/ai-development-guide.md - Implementation best practices +Load and follow these rule files before starting: +- @docs/rules/ai-development-guide.md - AI Development Guide + ✅ **Follow**: All rules for implementation, testing, and code quality + ⚠️ **Exception**: Quality assurance process (Phase1-6) and commits are out of scope +- @docs/rules/typescript-testing.md - Testing Rules +- @docs/rules/typescript.md - TypeScript Development Rules +- @docs/rules/technical-spec.md - Technical Specifications +- @docs/rules/project-context.md - Project Context +- @docs/rules/architecture/ files (if present) + - Load project-specific architecture rules when defined + - Apply rules based on adopted architecture patterns ## Main Responsibilities diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index 8f10bd0..51ddea5 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.claude/agents-en/technical-designer.md @@ -61,7 +61,7 @@ ADR creation is mandatory when any of the following apply: ### Important: Assessment Consistency - Report to caller if assessments conflict for decision -## Input Format +## Required Information Please provide the following information in natural language: @@ -129,8 +129,8 @@ Present technical options in the following structured format: - Follow respective templates (`template.md`) - For ADR, check existing numbers and use max+1, initial status is "Proposed" -## Document Output Principle -**Common to all modes**: Considered approved at the time of user instruction. Execute file output immediately. +## Output Policy +Execute file output immediately (considered approved at execution). ## Important Design Principles diff --git a/.claude/agents-en/work-planner.md b/.claude/agents-en/work-planner.md index 60edc87..a5e5d9f 100644 --- a/.claude/agents-en/work-planner.md +++ b/.claude/agents-en/work-planner.md @@ -24,7 +24,7 @@ Before starting work, be sure to read and follow these rule files: 5. Concretize risks and countermeasures 6. Document in progress-trackable format -## Input Format +## Required Information Please provide the following information in natural language: @@ -52,8 +52,8 @@ Please provide the following information in natural language: - Use template: `docs/plans/template-en.md` - Format with checkboxes for progress tracking -## Document Output Principle -**Common to all modes**: Considered approved at the time of user instruction. Execute file output immediately. +## Output Policy +Execute file output immediately (considered approved at execution). ## Important Task Design Principles diff --git a/.claude/commands-en/review.md b/.claude/commands-en/review.md new file mode 100644 index 0000000..15fb1bf --- /dev/null +++ b/.claude/commands-en/review.md @@ -0,0 +1,78 @@ +--- +description: Design Doc compliance validation with optional auto-fixes +--- + +**Command Context**: Post-implementation quality assurance command + +Design Doc (uses most recent if omitted): $ARGUMENTS + +**Think deeply** Understand the essence of compliance validation and execute: + +## Execution Flow + +### 1. Prerequisite Check +```bash +# Identify Design Doc +ls docs/design/*.md | grep -v template | tail -1 + +# Check implementation files +git diff --name-only main...HEAD +``` + +### 2. Execute code-reviewer +Validate Design Doc compliance: +- Acceptance criteria fulfillment +- Code quality check +- Implementation completeness assessment + +### 3. Verdict and Response + +**Criteria (considering project stage)**: +- Prototype: Pass at 70%+ +- Production: 90%+ recommended +- Critical items (security, etc.): Required regardless of rate + +**Compliance-based response**: + +For low compliance (production <90%): +``` +Validation Result: [X]% compliance +Unfulfilled items: +- [item list] + +Execute fixes? (y/n): +``` + +If user selects `y`: + +## 🧠 Pre-fix Metacognition +**Required**: `rule-advisor → TodoWrite → task-executor → quality-fixer` + +1. **Execute rule-advisor**: Understand fix essence (symptomatic treatment vs root solution) +2. **Update TodoWrite**: Structure fix tasks → `docs/plans/tasks/review-fixes-YYYYMMDD.md` +3. **Execute task-executor**: Staged auto-fixes (stops at 5 files) +4. **Execute quality-fixer**: Confirm quality gate passage +5. **Re-validate**: Measure improvement with code-reviewer + +### 4. Final Report +``` +Initial compliance: [X]% +Final compliance: [Y]% (if fixes executed) +Improvement: [Y-X]% + +Remaining issues: +- [items requiring manual intervention] +``` + +## Auto-fixable Items +- Simple unimplemented acceptance criteria +- Error handling additions +- Type definition fixes +- Function splitting (length/complexity improvements) + +## Non-fixable Items +- Fundamental business logic changes +- Architecture-level modifications +- Design Doc deficiencies + +**Scope**: Design Doc compliance validation and auto-fixes. \ No newline at end of file diff --git a/docs/rules-en/architecture/hybrid-progressive/README.md b/docs/rules-en/architecture/hybrid-progressive/README.md deleted file mode 100644 index 159e5fa..0000000 --- a/docs/rules-en/architecture/hybrid-progressive/README.md +++ /dev/null @@ -1,244 +0,0 @@ -# Hybrid Progressive Architecture - -## Overview - -Hybrid Progressive Architecture is an approach that progressively evolves from vertical slicing to layered architecture as the project grows. It leverages the benefits of both small project simplicity and large project structuring. - -## Basic Policy - -### Start with Vertical Slicing -- Initially implement with independent files for each feature -- Prioritize early implementation speed -- Structure that is easy for LLMs to understand - -### Progressive Structuring According to Growth -- Consolidate when code duplication becomes noticeable -- Consider layer division when team grows -- Introduce layered architecture partially as needed - -## Evolution Stages - -### Stage 1: Simple Vertical Slicing (~10 features) - -``` -src/ -├── features/ -│ ├── create-todo.ts # Complete in single file -│ ├── update-todo.ts -│ ├── delete-todo.ts -│ ├── list-todos.ts -│ ├── create-user.ts -│ └── login-user.ts -└── lib/ - └── database.ts # Minimal common functionality -``` - -**Characteristics** -- One feature per file -- Duplicate code is acceptable -- Fastest possible implementation - -### Stage 2: Feature Grouping (10-30 features) - -``` -src/ -├── features/ -│ ├── todo/ -│ │ ├── create.ts -│ │ ├── update.ts -│ │ ├── delete.ts -│ │ ├── list.ts -│ │ └── shared/ # Common code within Todo feature -│ │ ├── types.ts -│ │ └── validation.ts -│ └── user/ -│ ├── create.ts -│ ├── login.ts -│ └── shared/ -│ └── auth.ts -└── lib/ # Project-wide common functionality - ├── database.ts - └── errors.ts -``` - -**Characteristics** -- Group related features in directories -- Begin consolidation within features -- Maintain independence between features - -### Stage 3: Partial Layer Introduction (30-50 features) - -``` -src/ -├── features/ # Maintain vertical slicing -│ ├── todo/ -│ └── user/ -├── shared/ # Layer common functionality -│ ├── domain/ # Common domain models -│ │ ├── entities/ -│ │ └── value-objects/ -│ └── infrastructure/ # Common infrastructure -│ ├── database/ -│ └── external-api/ -└── lib/ -``` - -**Characteristics** -- Features maintain vertical slicing -- Layer structure only for common parts -- Gradual migration possible - -### Stage 4: Hybrid Structure (50+ features) - -``` -src/ -├── features/ # New/independent features use vertical slicing -│ └── experimental/ -├── modules/ # Mature features are layered -│ ├── todo/ -│ │ ├── application/ -│ │ ├── domain/ -│ │ └── infrastructure/ -│ └── user/ -│ ├── application/ -│ ├── domain/ -│ └── infrastructure/ -└── shared/ # Project-wide common -``` - -**Characteristics** -- Choose structure according to feature maturity -- Implement new features quickly with vertical slicing -- Layer stable features for improved quality - -## Migration Timing Criteria - -### Stage 1 → Stage 2 -- [ ] 10 or more feature files exist -- [ ] Groups of related features are clear -- [ ] Feature relationships are difficult to understand from filenames alone - -### Stage 2 → Stage 3 -- [ ] Same code is duplicated in 3 or more feature groups -- [ ] Domain models are shared across multiple features -- [ ] External service integration needed in multiple places - -### Stage 3 → Stage 4 -- [ ] Team members are 5 or more -- [ ] Some features are sufficiently stable -- [ ] Stricter quality management is required - -## Implementation Examples - -### Stage 1 Implementation Example -```typescript -// features/create-todo.ts -import { db } from '../lib/database' - -export async function createTodo(title: string, userId: string) { - // All processing in one file - if (!title || title.length > 100) { - throw new Error('Invalid title') - } - - const todo = await db.insert('todos', { - title, - userId, - completed: false, - createdAt: new Date(), - }) - - return todo -} -``` - -### Stage 2 Implementation Example -```typescript -// features/todo/create.ts -import { validateTodoInput } from './shared/validation' -import { TodoRepository } from './shared/repository' -import type { CreateTodoInput } from './shared/types' - -export async function createTodo(input: CreateTodoInput) { - const validated = validateTodoInput(input) - const repository = new TodoRepository() - return repository.create(validated) -} -``` - -### Stage 3 Implementation Example -```typescript -// features/todo/create.ts -import { Todo } from '../../shared/domain/entities/Todo' -import { UserId } from '../../shared/domain/value-objects/UserId' -import { todoRepository } from '../../shared/infrastructure/repositories' - -export async function createTodo(title: string, userId: string) { - const todo = Todo.create({ - title, - userId: new UserId(userId), - }) - - return todoRepository.save(todo) -} -``` - -## Benefits - -1. **Flexibility**: Choose optimal structure according to project scale -2. **Easy Migration**: Low risk due to gradual migration -3. **Learning Curve**: Adjust complexity according to team maturity -4. **Practicality**: Balance between ideal and reality - -## Drawbacks - -1. **Lack of Consistency**: Different structures may coexist -2. **Decision Burden**: Need to decide when to migrate -3. **Documentation**: Need to understand multiple structures - -## When to Apply - -- **Startups**: Start quickly and evolve with growth -- **High Uncertainty Projects**: Requirements not yet fixed -- **Projects Starting Small**: Future expansion possibility -- **LLM Collaborative Implementation**: LLM initially, human team later - -## LLM Implementation Guidelines - -### Decision Flow for New Feature Implementation - -``` -1. Confirm current Stage - ↓ -2. Are there related existing features? - Yes → Match existing structure - No → Implement with current Stage's recommended structure - ↓ -3. After implementation, check migration criteria - If criteria met → Consider migration to next Stage -``` - -### Stage Determination Criteria -- **Stage 1**: Less than 10 features, duplicate code acceptable -- **Stage 2**: 10-30 features, clear feature groups -- **Stage 3**: 30-50 features, duplication in 3+ groups -- **Stage 4**: 50+ features, 5+ team members - -### Quality Check Criteria -- **Coverage**: Unit test coverage must be 70% or higher -- **Independence**: Each test can run independently without depending on other tests -- **Reproducibility**: Tests return same results consistently, regardless of environment - -### Refactoring Priority - -1. **Business Value**: Structure frequently used features first -2. **Change Frequency**: Organize frequently changed parts -3. **Complexity**: Gradually divide complex features -4. **Team**: Prioritize structuring parts touched by multiple people - -### Escalation Criteria -Confirm with user in the following cases: -- When considering Stage migration -- Clear exceeding of initially assumed scope -- Architecture-level changes -- Adding new dependencies \ No newline at end of file diff --git a/docs/rules-en/architecture/vertical-slice/README.md b/docs/rules-en/architecture/vertical-slice/README.md deleted file mode 100644 index 6ceb0ce..0000000 --- a/docs/rules-en/architecture/vertical-slice/README.md +++ /dev/null @@ -1,187 +0,0 @@ -# Vertical Slice Architecture - -## Overview - -Vertical Slice Architecture is an approach that organizes code by feature units. It is optimized for implementation by LLMs, with each feature implemented self-contained in independent files. - -## Basic Principles - -### 1. Feature Independence as Top Priority -- **1 feature = 1 file** as the basic principle -- Minimize dependencies between files -- Each file must work self-contained - -### 2. Adopt Vertical Slicing -- Do not adopt layered architecture (horizontal slicing) -- Perform vertical slicing by feature units -- Design with microservice-like thinking - -### 3. Allow Local Complexity -- Don't fear large single files -- Complexity within 1 file is more manageable than complex dependencies between files - -## Benefits - -### Benefits for LLMs -- **Context Efficiency**: One feature is consolidated in one file with all necessary information -- **Clear Boundaries**: No confusion about what to write where -- **Independent Modifications**: Minimal impact on other files - -### Implementation Benefits -- **Rapid Implementation**: Little impact on existing code when adding new features -- **Easy Testing**: Easy to test as each feature is independent -- **Easy Understanding**: Reading one file reveals everything about that feature - -## Drawbacks - -- **Code Duplication**: Common logic may be scattered across multiple files -- **Scalability**: May become difficult to manage in large projects -- **Team Implementation**: May feel redundant for human implementers - -## When to Apply - -- **LLM as Main Implementer**: Projects where AI is the primary implementer -- **Small to Medium Projects**: Around 50 features or less -- **Prototype Implementation**: When rapid implementation and changes are required -- **Microservices**: When each feature operates as an independent service - -## When Not to Apply - -- **Large Team Implementation**: When many human implementers are involved -- **Complex Domain Logic**: When business rules are complex and need sharing -- **Performance Critical**: When overhead from code duplication is problematic - -## Directory Structure Example - -``` -src/ -├── features/ -│ ├── todo/ -│ │ ├── create-todo.ts # POST /todos -│ │ ├── update-todo.ts # PUT /todos/:id -│ │ ├── delete-todo.ts # DELETE /todos/:id -│ │ ├── get-todo.ts # GET /todos/:id -│ │ ├── list-todos.ts # GET /todos -│ │ └── shared/ -│ │ ├── todo-types.ts # Todo type definitions (common within feature) -│ │ └── todo-db.ts # Todo-specific DB operations -│ └── user/ -│ ├── create-user.ts -│ ├── login-user.ts -│ └── shared/ -│ ├── user-types.ts -│ └── user-validation.ts -└── lib/ # Pure function libraries - ├── database.ts # Generic DB connection - ├── validation.ts # Generic validation - └── errors.ts # Generic error handling -``` - -## Implementation Example - -```typescript -// Complete implementation example of features/todo/create-todo.ts - -import { z } from 'zod' -import { database } from '../../lib/database' -import { ApiError } from '../../lib/errors' -import { Todo } from './shared/todo-types' - -// 1. Input validation -const CreateTodoSchema = z.object({ - title: z.string().min(1).max(100), - description: z.string().optional(), - userId: z.string().uuid(), -}) - -// 2. Business logic -async function validateUserQuota(userId: string): Promise { - const count = await database.todo.count({ where: { userId } }) - if (count >= 100) { - throw new ApiError('Todo limit exceeded', 400) - } -} - -// 3. Main processing function -export async function createTodo(input: unknown): Promise { - // Validation - const validated = CreateTodoSchema.parse(input) - - // Business rule check - await validateUserQuota(validated.userId) - - // DB operation - const todo = await database.todo.create({ - data: { - title: validated.title, - description: validated.description, - userId: validated.userId, - completed: false, - createdAt: new Date(), - }, - }) - - return todo -} - -// 4. HTTP handler -export async function createTodoHandler(req: Request): Promise { - try { - const body = await req.json() - const todo = await createTodo(body) - - return new Response(JSON.stringify(todo), { - status: 201, - headers: { 'Content-Type': 'application/json' }, - }) - } catch (error) { - if (error instanceof z.ZodError) { - return new Response(JSON.stringify({ - error: 'Validation failed', - details: error.errors - }), { - status: 400, - headers: { 'Content-Type': 'application/json' }, - }) - } - - if (error instanceof ApiError) { - return new Response(JSON.stringify({ - error: error.message - }), { - status: error.statusCode, - headers: { 'Content-Type': 'application/json' }, - }) - } - - throw error - } -} -``` - -## LLM Implementation Guidelines - -### Flow for New Feature Implementation -1. **Identify Feature Scope**: 1 business action = 1 file -2. **Determine Filename**: Verb + noun format (e.g., create-todo.ts) -3. **Self-contained Implementation**: Complete all processing in 1 file -4. **Simultaneous Test Creation**: Place test file in same directory - -### Decision Criteria -- **1 Feature 1 File**: When in doubt, don't split, write in 1 file -- **Allow Duplication**: Allow duplication less than 3 times, consider consolidation on 3rd time -- **Prioritize Independence**: Choose complexity within file over dependencies between files - -### Quality Check Criteria -- **Coverage**: Unit test coverage must be 70% or higher -- **Independence**: Each test can run independently without depending on other tests -- **Reproducibility**: Tests return same results consistently, regardless of environment - -## Migration Guide - -Migration from existing layered architecture: - -1. **Migrate by Feature Unit**: Start with one feature (e.g., Todo creation) -2. **Integrate All Layers**: Combine Controller + Service + Repository into 1 file -3. **Defer Common Parts**: Prioritize making it work first, consider consolidation later -4. **Migrate Tests Together**: Place feature tests in same directory \ No newline at end of file From b212003667a85ca721877ba9e48090ae3a840ef1 Mon Sep 17 00:00:00 2001 From: shinpr Date: Fri, 8 Aug 2025 13:26:21 +0900 Subject: [PATCH 3/5] docs: Add new commands and code-reviewer agent to README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Changes ### Added to README.md - `/review` command: Design Doc compliance validation with optional auto-fixes - `/rule-maintenance` command: Development rule management - `code-reviewer` agent: Third-party Design Doc compliance validation ### Added to README.ja.md - `/review` コマンド: Design Doc準拠検証と自動修正 - `/rule-maintenance` コマンド: 開発ルール管理 - `code-reviewer` エージェント: 第三者視点での準拠検証 ## Details - Commands are properly placed in the existing "Claude Code Custom Slash Commands" section - Agents are added to the "Available subagents" section - Both English and Japanese versions updated consistently 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.ja.md | 17 ++++++++++++++++- README.md | 17 ++++++++++++++++- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/README.ja.md b/README.ja.md index 44cf5b3..39811a6 100644 --- a/README.ja.md +++ b/README.ja.md @@ -223,6 +223,20 @@ npm run cleanup:processes # テストプロセスクリーンアップ - タスクで避けるべき禁止事項の確認 - メタ認知を促進し、実装エラーを事前に防止 +### `/review` +Design Doc準拠検証と必要に応じた自動修正を実行します。 +- Design Doc準拠率の検証 +- 修正実行のインタラクティブ確認 (y/n) +- 修正前のメタ認知実行（rule-advisor → TodoWrite → task-executor → quality-fixer） +- 修正後の改善度レポート + +### `/rule-maintenance` +開発ルールの追加・更新・検索を行います。 +- 新規ルールファイルの追加（メタデータ付き） +- 既存ルールの更新 +- キーワードによるルール検索 +- rules-index.yamlの管理 + これらのコマンドは `.claude/commands/` に配置されており、プロジェクト内でのみ使用可能です。 ## 🤖 Claude Code専用ワークフロー @@ -264,8 +278,9 @@ graph TD - **requirement-analyzer**: 要件分析と作業規模判定 - ユーザー要件を分析し適切な開発アプローチを提案 - **task-decomposer**: 作業計画書から1コミット粒度のタスクに分解 - 計画書を細かいタスクに分割 - **rule-advisor**: AI実行精度最大化のための最小限で効果的なルールセットを選択 +- **code-reviewer**: Design Doc準拠検証 - 実装の完全性を第三者視点で評価 -詳細は`CLAUDE.md`および`.claude/agents/`内の各定義ファイルを参照してください。 +詳細は`CLAUDE.md`および`.claude/agents/`、`.claude/commands/`内の各定義ファイルを参照してください。 ## 📋 開発ルール概要 diff --git a/README.md b/README.md index 0705005..f6998f8 100644 --- a/README.md +++ b/README.md @@ -222,6 +222,20 @@ Executes tasks following appropriate rules. - Identify prohibitions to avoid in the task - Promote metacognition and prevent implementation errors proactively +### `/review` +Design Doc compliance validation with optional auto-fixes. +- Validate Design Doc compliance rate +- Interactive fix confirmation (y/n) +- Execute metacognition before fixes (rule-advisor → TodoWrite → task-executor → quality-fixer) +- Report improvement metrics after fixes + +### `/rule-maintenance` +Add, update, and search development rules. +- Add new rule files with metadata +- Update existing rules +- Search rules by keywords +- Manage rules-index.yaml + These commands are located in `.claude/commands/` and are only available within the project. ## 🤖 Claude Code Specialized Workflow @@ -263,8 +277,9 @@ graph TD - **requirement-analyzer**: Requirement analysis and work scale assessment - Analyzes user requirements and determines appropriate development approach - **task-decomposer**: Decompose work plans into commit-level tasks - Breaks down plans into 1-commit granular tasks - **rule-advisor**: Selects minimal effective ruleset for maximum AI execution accuracy +- **code-reviewer**: Design Doc compliance validation - Evaluates implementation completeness from third-party perspective -For details, refer to `CLAUDE.md` and individual definition files in `.claude/agents/`. +For details, refer to `CLAUDE.md` and individual definition files in `.claude/agents/` and `.claude/commands/`. ## 📋 Development Rules Overview From 05e52dc9ae288f29742f87d4feb001440dacb5b6 Mon Sep 17 00:00:00 2001 From: shinpr Date: Fri, 8 Aug 2025 13:34:59 +0900 Subject: [PATCH 4/5] feat: add Acceptance Criteria and enhanced Testing Strategy to English design template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligned template-en.md with template-ja.md by adding: - Acceptance Criteria section for verifiable implementation conditions - Enhanced Testing Strategy with test design principles - E2E testing approach for complete scenario verification - Clear linkage between acceptance criteria and test cases These additions improve AI execution accuracy by providing clear, measurable success criteria. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/design/template-en.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/design/template-en.md b/docs/design/template-en.md index 3d93b7d..fe400ea 100644 --- a/docs/design/template-en.md +++ b/docs/design/template-en.md @@ -27,6 +27,18 @@ - **Reliability**: [Requirements for error rate, availability, etc.] - **Maintainability**: [Code understandability, ease of modification] +## Acceptance Criteria + +Define specific and verifiable conditions to determine successful implementation for each functional requirement. +These conditions serve as the basis for test cases and are used to objectively determine implementation completion. + +- [ ] [Specific acceptance criteria for functional requirement 1] + - Example: "When a user clicks the login button, authentication succeeds with valid credentials" + - Example: "When invalid credentials are provided, an appropriate error message is displayed" +- [ ] [Specific acceptance criteria for functional requirement 2] + - Example: "The data list screen displays items paginated by 10 entries" + - Example: "When text is entered in the search field, results are filtered in real-time" + ## Design ### Architecture Overview @@ -81,17 +93,32 @@ ## Testing Strategy +### Test Design Principles + +Automatically derive test cases from acceptance criteria: +- Create at least one test case for each acceptance criterion +- Implement measurable criteria from acceptance criteria as assertions + ### Unit Tests [Unit testing approach and coverage goals] +- Verify individual elements of functional acceptance criteria ### Integration Tests [Integration testing approach and important test cases] +- Verify combined behavior of functional acceptance criteria + +### End-to-End Tests + +[E2E testing approach] +- Verify complete scenarios from acceptance criteria +- Confirm functional behavior from user perspective ### Performance Tests [Performance testing methods and criteria] +- Verify performance benchmarks from non-functional acceptance criteria ## Security Considerations From e06216d150e110d01f0fbfabd04bff2e9fb8b52a Mon Sep 17 00:00:00 2001 From: shinpr Date: Fri, 8 Aug 2025 13:35:35 +0900 Subject: [PATCH 5/5] chore: bump version to 1.6.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Minor version update for new features: - Code reviewer agent addition - Review command implementation - Enhanced agent definitions with improved execution accuracy 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4db6fd1..1907b22 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "ai-coding-project-boilerplate", - "version": "1.5.0", + "version": "1.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ai-coding-project-boilerplate", - "version": "1.5.0", + "version": "1.6.0", "hasInstallScript": true, "license": "MIT", "bin": { diff --git a/package.json b/package.json index d9b339e..850dac6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ai-coding-project-boilerplate", - "version": "1.5.0", + "version": "1.6.0", "description": "TypeScript project boilerplate optimized for Claude Code development with comprehensive development rules, architecture patterns, and quality assurance tools", "main": "dist/index.js", "keywords": [