diff --git a/builtins/en/instructions/plan.md b/builtins/en/instructions/plan.md index 9916bb1..f77bf7a 100644 --- a/builtins/en/instructions/plan.md +++ b/builtins/en/instructions/plan.md @@ -1,9 +1,18 @@ -Analyze the task and formulate an implementation plan. +Analyze the task and formulate an implementation plan including design decisions. **Note:** If a Previous Response exists, this is a replan due to rejection. Revise the plan taking that feedback into account. +**Criteria for small tasks:** +- Only 1-2 file changes +- No design decisions needed +- No technology selection needed + +For small tasks, skip the design sections in the report. + **Actions:** 1. Understand the task requirements -2. Identify the impact area -3. Decide on the implementation approach +2. Investigate code to resolve unknowns +3. Identify the impact area +4. Determine file structure and design patterns (if needed) +5. Decide on the implementation approach diff --git a/builtins/en/output-contracts/plan.md b/builtins/en/output-contracts/plan.md index eaf4348..12d47df 100644 --- a/builtins/en/output-contracts/plan.md +++ b/builtins/en/output-contracts/plan.md @@ -12,9 +12,22 @@ ### Scope {Impact area} +### Design Decisions (only when design is needed) + +#### File Structure +| File | Role | +|------|------| +| `src/example.ts` | Overview | + +#### Design Patterns +- {Adopted patterns and where they apply} + ### Implementation Approach {How to proceed} +## Implementation Guidelines (only when design is needed) +- {Guidelines the Coder should follow during implementation} + ## Open Questions (if any) - {Unclear points or items that need confirmation} ``` diff --git a/builtins/en/personas/planner.md b/builtins/en/personas/planner.md index af2d064..fb858be 100644 --- a/builtins/en/personas/planner.md +++ b/builtins/en/personas/planner.md @@ -1,17 +1,18 @@ # Planner Agent -You are a **task analysis expert**. You analyze user requests and create implementation plans. +You are a **task analysis and design planning specialist**. You analyze user requirements, investigate code to resolve unknowns, and create structurally sound implementation plans. ## Role -- Analyze and understand user requests +- Analyze and understand user requirements +- Resolve unknowns by reading code yourself - Identify impact scope -- Formulate implementation approach +- Determine file structure and design patterns +- Create implementation guidelines for Coder -**Don't:** -- Implement code (Coder's job) -- Make design decisions (Architect's job) -- Review code +**Not your job:** +- Writing code (Coder's job) +- Code review (Reviewer's job) ## Analysis Phases @@ -25,26 +26,27 @@ Analyze user request and identify: | Scope | What areas are affected? | | Deliverables | What should be created? | -### 2. Impact Scope Identification +### 2. Investigating and Resolving Unknowns -Identify the scope of changes: - -- Files/modules that need modification -- Dependencies -- Impact on tests - -### 3. Fact-Checking (Source of Truth Verification) - -Always verify information used in your analysis against the source of truth: +When the task has unknowns or Open Questions, resolve them by reading code instead of guessing. | Information Type | Source of Truth | |-----------------|-----------------| | Code behavior | Actual source code | | Config values / names | Actual config files / definition files | | APIs / commands | Actual implementation code | -| Documentation claims | Cross-check with actual codebase | +| Data structures / types | Type definition files / schemas | -**Don't guess.** Always verify names, values, and behaviors against actual code. +**Don't guess.** Verify names, values, and behavior in the code. +**Don't stop at "unknown."** If the code can tell you, investigate and resolve it. + +### 3. Impact Scope Identification + +Identify the scope of changes: + +- Files/modules that need modification +- Dependencies (callers and callees) +- Impact on tests ### 4. Spec & Constraint Verification @@ -59,19 +61,42 @@ Always verify information used in your analysis against the source of truth: **Don't plan against the specs.** If specs are unclear, explicitly state so. -### 5. Implementation Approach +### 5. Structural Design -Determine the implementation direction: +Always choose the optimal structure. Do not follow poor existing code structure. + +**File Organization:** +- 1 module, 1 responsibility +- File splitting follows de facto standards of the programming language +- Target 200-400 lines per file. If exceeding, include splitting in the plan +- If existing code has structural problems, include refactoring within the task scope + +**Module Design:** +- High cohesion, low coupling +- Maintain dependency direction (upper layers → lower layers) +- No circular dependencies +- Separation of concerns (reads vs. writes, business logic vs. IO) + +### 6. Implementation Approach + +Based on investigation and design, determine the implementation direction: - What steps to follow +- File organization (list of files to create/modify) - Points to be careful about -- Items requiring confirmation -- **Spec constraints** (schemas, formats, ignored fields, etc.) +- Spec constraints -## Important +## Design Principles -**Do not include backward compatibility code in plans.** Unless explicitly instructed, fallbacks, re-exports, and migration code are unnecessary. -**Keep analysis simple.** Overly detailed plans are unnecessary. Provide enough direction for Coder to proceed with implementation. +**Backward Compatibility:** +- Do not include backward compatibility code unless explicitly instructed +- Plan to delete things that are unused -**Make unclear points explicit.** Don't proceed with guesses, report unclear points. +**Don't Generate Unnecessary Code:** +- Don't plan "just in case" code, future fields, or unused methods +- Don't plan to leave TODO comments. Either do it now, or don't + +**Important:** +**Investigate before planning.** Don't plan without reading existing code. +**Design simply.** No excessive abstractions or future-proofing. Provide enough direction for Coder to implement without hesitation. **Ask all clarification questions at once.** Do not ask follow-up questions in multiple rounds. diff --git a/builtins/en/pieces/coding-hybrid-codex.yaml b/builtins/en/pieces/coding-hybrid-codex.yaml index 1e92a5c..5b564f0 100644 --- a/builtins/en/pieces/coding-hybrid-codex.yaml +++ b/builtins/en/pieces/coding-hybrid-codex.yaml @@ -7,7 +7,7 @@ max_iterations: 20 knowledge: architecture: ../knowledge/architecture.md personas: - architect-planner: ../personas/architect-planner.md + planner: ../personas/planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -25,7 +25,8 @@ initial_movement: plan movements: - name: plan edit: false - persona: architect-planner + persona: planner + knowledge: architecture allowed_tools: - Read - Glob diff --git a/builtins/en/pieces/coding.yaml b/builtins/en/pieces/coding.yaml index 6571911..2cc3841 100644 --- a/builtins/en/pieces/coding.yaml +++ b/builtins/en/pieces/coding.yaml @@ -9,7 +9,7 @@ policies: knowledge: architecture: ../knowledge/architecture.md personas: - architect-planner: ../personas/architect-planner.md + planner: ../personas/planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -23,7 +23,8 @@ initial_movement: plan movements: - name: plan edit: false - persona: architect-planner + persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -43,6 +44,7 @@ movements: report: - name: 00-plan.md format: plan + - name: implement edit: true persona: coder @@ -77,6 +79,7 @@ movements: report: - Scope: 02-coder-scope.md - Decisions: 03-coder-decisions.md + - name: reviewers parallel: - name: ai_review @@ -123,6 +126,7 @@ movements: next: COMPLETE - condition: any("AI-specific issues found", "needs_fix") next: fix + - name: fix edit: true persona: coder diff --git a/builtins/en/pieces/default-hybrid-codex.yaml b/builtins/en/pieces/default-hybrid-codex.yaml index 77d9f51..955770c 100644 --- a/builtins/en/pieces/default-hybrid-codex.yaml +++ b/builtins/en/pieces/default-hybrid-codex.yaml @@ -9,7 +9,6 @@ knowledge: architecture: ../knowledge/architecture.md personas: planner: ../personas/planner.md - architect-planner: ../personas/architect-planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -17,7 +16,6 @@ personas: supervisor: ../personas/supervisor.md instructions: plan: ../instructions/plan.md - architect: ../instructions/architect.md implement: ../instructions/implement.md ai-review: ../instructions/ai-review.md ai-fix: ../instructions/ai-fix.md @@ -28,7 +26,6 @@ instructions: supervise: ../instructions/supervise.md report_formats: plan: ../output-contracts/plan.md - architecture-design: ../output-contracts/architecture-design.md ai-review: ../output-contracts/ai-review.md architecture-review: ../output-contracts/architecture-review.md qa-review: ../output-contracts/qa-review.md @@ -64,6 +61,7 @@ movements: - name: plan edit: false persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -73,7 +71,7 @@ movements: - WebFetch rules: - condition: Requirements are clear and implementable - next: architect + next: implement - condition: User is asking a question (not an implementation task) next: COMPLETE - condition: Requirements unclear, insufficient info @@ -87,27 +85,6 @@ movements: report: - name: 00-plan.md format: plan - - name: architect - edit: false - persona: architect-planner - allowed_tools: - - Read - - Glob - - Grep - - WebSearch - - WebFetch - rules: - - condition: Small task (no design needed) - next: implement - - condition: Design complete - next: implement - - condition: Insufficient info, cannot proceed - next: ABORT - instruction: architect - output_contracts: - report: - - name: 01-architecture.md - format: architecture-design - name: implement edit: true persona: coder diff --git a/builtins/en/pieces/default.yaml b/builtins/en/pieces/default.yaml index dc7b9fc..c52266d 100644 --- a/builtins/en/pieces/default.yaml +++ b/builtins/en/pieces/default.yaml @@ -12,7 +12,6 @@ knowledge: architecture: ../knowledge/architecture.md personas: planner: ../personas/planner.md - architect-planner: ../personas/architect-planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -20,7 +19,6 @@ personas: supervisor: ../personas/supervisor.md instructions: plan: ../instructions/plan.md - architect: ../instructions/architect.md implement: ../instructions/implement.md ai-review: ../instructions/ai-review.md ai-fix: ../instructions/ai-fix.md @@ -59,6 +57,7 @@ movements: - name: plan edit: false persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -68,7 +67,7 @@ movements: - WebFetch rules: - condition: Requirements are clear and implementable - next: architect + next: implement - condition: User is asking a question (not an implementation task) next: COMPLETE - condition: Requirements unclear, insufficient info @@ -82,27 +81,7 @@ movements: report: - name: 00-plan.md format: plan - - name: architect - edit: false - persona: architect-planner - allowed_tools: - - Read - - Glob - - Grep - - WebSearch - - WebFetch - rules: - - condition: Small task (no design needed) - next: implement - - condition: Design complete - next: implement - - condition: Insufficient info, cannot proceed - next: ABORT - instruction: architect - output_contracts: - report: - - name: 01-architecture.md - format: architecture-design + - name: implement edit: true persona: coder @@ -139,6 +118,7 @@ movements: report: - Scope: 02-coder-scope.md - Decisions: 03-coder-decisions.md + - name: ai_review edit: false persona: ai-antipattern-reviewer @@ -161,6 +141,7 @@ movements: report: - name: 04-ai-review.md format: ai-review + - name: ai_fix edit: true persona: coder @@ -189,6 +170,7 @@ movements: - condition: Cannot proceed, insufficient info next: ai_no_fix instruction: ai-fix + - name: ai_no_fix edit: false persona: architecture-reviewer @@ -203,6 +185,7 @@ movements: - condition: ai_fix's judgment is valid (no fix needed) next: reviewers instruction: arbitrate + - name: reviewers parallel: - name: arch-review @@ -251,6 +234,7 @@ movements: next: supervise - condition: any("needs_fix") next: fix + - name: fix edit: true persona: coder @@ -276,6 +260,7 @@ movements: - condition: Cannot proceed, insufficient info next: plan instruction: fix + - name: supervise edit: false persona: supervisor @@ -299,7 +284,6 @@ movements: - Summary: summary.md report_formats: plan: ../output-contracts/plan.md - architecture-design: ../output-contracts/architecture-design.md ai-review: ../output-contracts/ai-review.md architecture-review: ../output-contracts/architecture-review.md qa-review: ../output-contracts/qa-review.md diff --git a/builtins/ja/instructions/plan.md b/builtins/ja/instructions/plan.md index 19765a3..a1f6ea2 100644 --- a/builtins/ja/instructions/plan.md +++ b/builtins/ja/instructions/plan.md @@ -1,9 +1,18 @@ -タスクを分析し、実装方針を立ててください。 +タスクを分析し、設計を含めた実装方針を立ててください。 **注意:** Previous Responseがある場合は差し戻しのため、 その内容を踏まえて計画を見直してください(replan)。 +**小規模タスクの判断基準:** +- 1-2ファイルの変更のみ +- 設計判断が不要 +- 技術選定が不要 + +小規模タスクの場合は設計セクションを省略してください。 + **やること:** 1. タスクの要件を理解する -2. 影響範囲を特定する -3. 実装アプローチを決める +2. コードを調査して不明点を解決する +3. 影響範囲を特定する +4. ファイル構成・設計パターンを決定する(必要な場合) +5. 実装アプローチを決める diff --git a/builtins/ja/output-contracts/plan.md b/builtins/ja/output-contracts/plan.md index 743e6c8..7e45c9f 100644 --- a/builtins/ja/output-contracts/plan.md +++ b/builtins/ja/output-contracts/plan.md @@ -12,9 +12,22 @@ ### スコープ {影響範囲} +### 設計判断(設計が必要な場合のみ) + +#### ファイル構成 +| ファイル | 役割 | +|---------|------| +| `src/example.ts` | 概要 | + +#### 設計パターン +- {採用するパターンと適用箇所} + ### 実装アプローチ {どう進めるか} +## 実装ガイドライン(設計が必要な場合のみ) +- {Coderが実装時に従うべき指針} + ## 確認事項(あれば) - {不明点や確認が必要な点} ``` diff --git a/builtins/ja/personas/planner.md b/builtins/ja/personas/planner.md index c302338..afecb15 100644 --- a/builtins/ja/personas/planner.md +++ b/builtins/ja/personas/planner.md @@ -1,24 +1,25 @@ # Planner -あなたはタスク分析の専門家です。ユーザー要求を分析し、実装方針を立てます。 +あなたはタスク分析と設計計画の専門家です。ユーザー要求を分析し、コードを調査して不明点を解決し、構造を意識した実装方針を立てます。 ## 役割の境界 **やること:** - ユーザー要求の分析・理解 +- コードを読んで不明点を自力で解決する - 影響範囲の特定 -- 実装アプローチの策定 +- ファイル構成・設計パターンの決定 +- Coder への実装ガイドライン作成 **やらないこと:** - コードの実装(Coder の仕事) -- 設計判断(Architect の仕事) -- コードレビュー +- コードレビュー(Reviewer の仕事) ## 行動姿勢 -- 推測で書かない。名前・値・振る舞いは必ずコードで確認する -- シンプルに分析する。過度に詳細な計画は不要 -- 不明点は明確にする。推測で進めない +- 調査してから計画する。既存コードを読まずに計画を立てない +- 推測で書かない。名前・値・振る舞いは必ずコードで確認する。「不明」で止まらない +- シンプルに設計する。過度な抽象化や将来への備えは不要 - 確認が必要な場合は質問を一度にまとめる。追加の確認質問を繰り返さない - 後方互換コードは計画に含めない。明示的な指示がない限り不要 @@ -33,4 +34,26 @@ | コードの振る舞い | 実際のソースコード | | 設定値・名前 | 実際の設定ファイル・定義ファイル | | API・コマンド | 実際の実装コード | -| ドキュメント記述 | 実際のコードベースと突合 | +| データ構造・型 | 型定義ファイル・スキーマ | + +### 構造設計 + +常に最適な構造を選択する。既存コードが悪い構造でも踏襲しない。 + +**ファイル構成:** +- 1 モジュール 1 責務 +- ファイル分割はプログラミング言語のデファクトスタンダードに従う +- 1 ファイル 200-400 行を目安。超える場合は分割を計画に含める +- 既存コードに構造上の問題があれば、タスクスコープ内でリファクタリングを計画に含める + +**モジュール設計:** +- 高凝集・低結合 +- 依存の方向を守る(上位層 → 下位層) +- 循環依存を作らない +- 責務の分離(読み取りと書き込み、ビジネスロジックと IO) + +### 計画の原則 + +- 後方互換コードは計画に含めない(明示的な指示がない限り不要) +- 使われていないものは削除する計画を立てる +- TODO コメントで済ませる計画は立てない。今やるか、やらないか diff --git a/builtins/ja/pieces/coding-hybrid-codex.yaml b/builtins/ja/pieces/coding-hybrid-codex.yaml index cc268be..56106ca 100644 --- a/builtins/ja/pieces/coding-hybrid-codex.yaml +++ b/builtins/ja/pieces/coding-hybrid-codex.yaml @@ -7,7 +7,7 @@ max_iterations: 20 knowledge: architecture: ../knowledge/architecture.md personas: - architect-planner: ../personas/architect-planner.md + planner: ../personas/planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -25,7 +25,8 @@ initial_movement: plan movements: - name: plan edit: false - persona: architect-planner + persona: planner + knowledge: architecture allowed_tools: - Read - Glob diff --git a/builtins/ja/pieces/coding.yaml b/builtins/ja/pieces/coding.yaml index b8bd33d..8b7413c 100644 --- a/builtins/ja/pieces/coding.yaml +++ b/builtins/ja/pieces/coding.yaml @@ -9,7 +9,7 @@ policies: knowledge: architecture: ../knowledge/architecture.md personas: - architect-planner: ../personas/architect-planner.md + planner: ../personas/planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -23,7 +23,8 @@ initial_movement: plan movements: - name: plan edit: false - persona: architect-planner + persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -43,6 +44,7 @@ movements: report: - name: 00-plan.md format: plan + - name: implement edit: true persona: coder @@ -77,6 +79,7 @@ movements: report: - Scope: 02-coder-scope.md - Decisions: 03-coder-decisions.md + - name: reviewers parallel: - name: ai_review @@ -123,6 +126,7 @@ movements: next: COMPLETE - condition: any("AI特有の問題あり", "needs_fix") next: fix + - name: fix edit: true persona: coder diff --git a/builtins/ja/pieces/default-hybrid-codex.yaml b/builtins/ja/pieces/default-hybrid-codex.yaml index 291b330..68ea3cc 100644 --- a/builtins/ja/pieces/default-hybrid-codex.yaml +++ b/builtins/ja/pieces/default-hybrid-codex.yaml @@ -9,7 +9,6 @@ knowledge: backend: ../knowledge/backend.md personas: planner: ../personas/planner.md - architect-planner: ../personas/architect-planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -17,7 +16,6 @@ personas: supervisor: ../personas/supervisor.md instructions: plan: ../instructions/plan.md - architect: ../instructions/architect.md implement: ../instructions/implement.md ai-review: ../instructions/ai-review.md ai-fix: ../instructions/ai-fix.md @@ -28,7 +26,6 @@ instructions: supervise: ../instructions/supervise.md report_formats: plan: ../output-contracts/plan.md - architecture-design: ../output-contracts/architecture-design.md ai-review: ../output-contracts/ai-review.md architecture-review: ../output-contracts/architecture-review.md qa-review: ../output-contracts/qa-review.md @@ -64,6 +61,7 @@ movements: - name: plan edit: false persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -73,7 +71,7 @@ movements: - WebFetch rules: - condition: 要件が明確で実装可能 - next: architect + next: implement - condition: ユーザーが質問をしている(実装タスクではない) next: COMPLETE - condition: 要件が不明確、情報不足 @@ -87,27 +85,6 @@ movements: report: - name: 00-plan.md format: plan - - name: architect - edit: false - persona: architect-planner - allowed_tools: - - Read - - Glob - - Grep - - WebSearch - - WebFetch - rules: - - condition: 小規模タスク(設計不要) - next: implement - - condition: 設計完了 - next: implement - - condition: 情報不足、判断できない - next: ABORT - instruction: architect - output_contracts: - report: - - name: 01-architecture.md - format: architecture-design - name: implement edit: true persona: coder diff --git a/builtins/ja/pieces/default.yaml b/builtins/ja/pieces/default.yaml index 496d4f1..dd7888c 100644 --- a/builtins/ja/pieces/default.yaml +++ b/builtins/ja/pieces/default.yaml @@ -12,7 +12,6 @@ knowledge: backend: ../knowledge/backend.md personas: planner: ../personas/planner.md - architect-planner: ../personas/architect-planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md @@ -20,7 +19,6 @@ personas: supervisor: ../personas/supervisor.md instructions: plan: ../instructions/plan.md - architect: ../instructions/architect.md implement: ../instructions/implement.md ai-review: ../instructions/ai-review.md ai-fix: ../instructions/ai-fix.md @@ -59,6 +57,7 @@ movements: - name: plan edit: false persona: planner + knowledge: architecture allowed_tools: - Read - Glob @@ -68,7 +67,7 @@ movements: - WebFetch rules: - condition: 要件が明確で実装可能 - next: architect + next: implement - condition: ユーザーが質問をしている(実装タスクではない) next: COMPLETE - condition: 要件が不明確、情報不足 @@ -82,27 +81,7 @@ movements: report: - name: 00-plan.md format: plan - - name: architect - edit: false - persona: architect-planner - allowed_tools: - - Read - - Glob - - Grep - - WebSearch - - WebFetch - rules: - - condition: 小規模タスク(設計不要) - next: implement - - condition: 設計完了 - next: implement - - condition: 情報不足、判断できない - next: ABORT - instruction: architect - output_contracts: - report: - - name: 01-architecture.md - format: architecture-design + - name: implement edit: true persona: coder @@ -139,6 +118,7 @@ movements: report: - Scope: 02-coder-scope.md - Decisions: 03-coder-decisions.md + - name: ai_review edit: false persona: ai-antipattern-reviewer @@ -161,6 +141,7 @@ movements: report: - name: 04-ai-review.md format: ai-review + - name: ai_fix edit: true persona: coder @@ -189,6 +170,7 @@ movements: - condition: 判断できない、情報不足 next: ai_no_fix instruction: ai-fix + - name: ai_no_fix edit: false persona: architecture-reviewer @@ -203,6 +185,7 @@ movements: - condition: ai_fixの判断が妥当(修正不要) next: reviewers instruction: arbitrate + - name: reviewers parallel: - name: arch-review @@ -251,6 +234,7 @@ movements: next: supervise - condition: any("needs_fix") next: fix + - name: fix edit: true persona: coder @@ -276,6 +260,7 @@ movements: - condition: 判断できない、情報不足 next: plan instruction: fix + - name: supervise edit: false persona: supervisor @@ -299,7 +284,6 @@ movements: - Summary: summary.md report_formats: plan: ../output-contracts/plan.md - architecture-design: ../output-contracts/architecture-design.md ai-review: ../output-contracts/ai-review.md architecture-review: ../output-contracts/architecture-review.md qa-review: ../output-contracts/qa-review.md diff --git a/tools/prompt-log-viewer.html b/tools/prompt-log-viewer.html new file mode 100644 index 0000000..29d8cf6 --- /dev/null +++ b/tools/prompt-log-viewer.html @@ -0,0 +1,714 @@ + + +
+ + +*-prompts.jsonl ファイルをドラッグ&ドロップ