mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
Add execution and planning agent prompts, specifications, and quality standards
- Created execution agent prompt for issue execution with detailed deliverables and validation criteria. - Developed planning agent prompt to analyze issues and generate structured solution plans. - Introduced issue handling specifications outlining the workflow and issue structure. - Established quality standards for evaluating completeness, consistency, correctness, and clarity of solutions. - Defined solution schema specification detailing the required structure and validation rules for solutions. - Documented subagent roles and responsibilities, emphasizing the dual-agent strategy for improved workflow efficiency.
This commit is contained in:
catlog22
187
.codex/skills/codex-issue-plan-execute/specs/issue-handling.md
Normal file
187
.codex/skills/codex-issue-plan-execute/specs/issue-handling.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Issue Handling Specification
|
||||
|
||||
Issue 处理的核心规范和约定。
|
||||
|
||||
## When to Use
|
||||
|
||||
| Phase | Usage | Section |
|
||||
|-------|-------|---------|
|
||||
| Phase: action-list | Issue 列表展示 | Issue Status & Display |
|
||||
| Phase: action-plan | Issue 规划 | Solution Planning |
|
||||
| Phase: action-execute | Issue 执行 | Solution Execution |
|
||||
|
||||
---
|
||||
|
||||
## Issue Structure
|
||||
|
||||
### 基本字段
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ISS-20250129-001",
|
||||
"title": "Fix authentication token expiration bug",
|
||||
"description": "Tokens expire too quickly in production",
|
||||
"status": "registered",
|
||||
"priority": "high",
|
||||
"tags": ["auth", "bugfix"],
|
||||
"created_at": "2025-01-29T10:00:00Z",
|
||||
"updated_at": "2025-01-29T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 工作流状态
|
||||
|
||||
| Status | Phase | 说明 |
|
||||
|--------|-------|------|
|
||||
| `registered` | Initial | Issue 已创建，待规划 |
|
||||
| `planning` | List → Plan | 正在规划中 |
|
||||
| `planned` | Plan → Execute | 规划完成，解决方案已绑定 |
|
||||
| `executing` | Execute | 正在执行 |
|
||||
| `completed` | Execute → Complete | 执行完成 |
|
||||
| `failed` | Any | 执行失败 |
|
||||
|
||||
### 工作流字段
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ISS-xxx",
|
||||
"status": "registered|planning|planned|executing|completed|failed",
|
||||
"solution_id": "SOL-xxx-1",
|
||||
"planned_at": "2025-01-29T11:00:00Z",
|
||||
"executed_at": "2025-01-29T12:00:00Z",
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
## Issue 列表显示
|
||||
|
||||
### 格式规范
|
||||
|
||||
```
|
||||
Status Matrix:
|
||||
Total: 5 | Registered: 2 | Planned: 2 | Completed: 1
|
||||
|
||||
Issue Details:
|
||||
○ [1] ISS-001: Fix login bug (registered)
|
||||
→ [2] ISS-002: Add MFA support (planning)
|
||||
✓ [3] ISS-003: Refactor auth (completed)
|
||||
✗ [4] ISS-004: Update password policy (failed)
|
||||
```
|
||||
|
||||
### 显示字段
|
||||
|
||||
- ID: 唯一标识
|
||||
- Title: 简短描述
|
||||
- Status: 当前状态
|
||||
- Solution ID: 绑定的解决方案（如有）
|
||||
|
||||
## Solution Planning
|
||||
|
||||
### 规划输入
|
||||
|
||||
- Issue ID 和 Title
|
||||
- Issue 描述和上下文
|
||||
- 项目技术栈和指南
|
||||
|
||||
### 规划输出
|
||||
|
||||
- Solution ID：`SOL-{issue-id}-{sequence}`
|
||||
- Tasks 数组：可执行的任务列表
|
||||
- Acceptance Criteria：验收标准
|
||||
- 估计时间
|
||||
|
||||
### Planning Subagent 职责
|
||||
|
||||
1. 分析 issue 描述
|
||||
2. 探索相关代码路径
|
||||
3. 设计解决方案
|
||||
4. 分解为可执行任务
|
||||
5. 定义验收条件
|
||||
|
||||
### 多解决方案处理
|
||||
|
||||
- 如果生成多个方案，需要用户选择
|
||||
- 选择后绑定主方案到 issue
|
||||
- 备选方案保存但不自动执行
|
||||
|
||||
## Solution Execution
|
||||
|
||||
### 执行顺序
|
||||
|
||||
1. 加载已规划的解决方案
|
||||
2. 逐个执行每个 solution 中的所有 tasks
|
||||
3. 每个 task：implement → test → verify
|
||||
4. 完成后提交一次
|
||||
|
||||
### Execution Subagent 职责
|
||||
|
||||
1. 加载 solution JSON
|
||||
2. 实现所有任务
|
||||
3. 运行测试
|
||||
4. 验收条件检查
|
||||
5. 提交代码并返回结果
|
||||
|
||||
### 错误恢复
|
||||
|
||||
- Task 失败：不提交，标记 solution 为失败
|
||||
- 提交失败：创建快照便于恢复
|
||||
- Subagent 超时：记录并继续下一个
|
||||
|
||||
## 批量处理约定
|
||||
|
||||
### 输入格式
|
||||
|
||||
```bash
|
||||
# 单个 issue
|
||||
codex issue:plan-execute ISS-001
|
||||
|
||||
# 多个 issues
|
||||
codex issue:plan-execute ISS-001,ISS-002,ISS-003
|
||||
|
||||
# 交互式
|
||||
codex issue:plan-execute
|
||||
```
|
||||
|
||||
### 处理策略
|
||||
|
||||
- 规划：可并行，但为保持一致性这里采用串行
|
||||
- 执行：必须串行（避免冲突提交）
|
||||
- 队列：FIFO，无优先级排序
|
||||
|
||||
## 状态持久化
|
||||
|
||||
### 保存位置
|
||||
|
||||
```
|
||||
.workflow/.scratchpad/codex-issue-{timestamp}/
|
||||
├── state.json # 当前状态快照
|
||||
├── state-history.json # 状态变更历史
|
||||
├── queue.json # 执行队列
|
||||
├── solutions/ # 解决方案文件
|
||||
├── snapshots/ # 流程快照
|
||||
└── final-report.md # 最终报告
|
||||
```
|
||||
|
||||
### 快照用途
|
||||
|
||||
- 流程恢复：允许从中断点恢复
|
||||
- 调试：记录每个阶段的状态变化
|
||||
- 审计：跟踪完整的执行过程
|
||||
|
||||
## 质量保证
|
||||
|
||||
### 验收清单
|
||||
|
||||
- [ ] Issue 规范明确
|
||||
- [ ] Solution 遵循 schema
|
||||
- [ ] All tasks 有 acceptance criteria
|
||||
- [ ] 执行成功率 >= 80%
|
||||
- [ ] 报告生成完整
|
||||
|
||||
### 错误分类
|
||||
|
||||
| 级别 | 类型 | 处理 |
|
||||
|------|------|------|
|
||||
| Critical | 规划失败、提交失败 | 中止该 issue |
|
||||
| Warning | 测试失败、条件未满足 | 记录但继续 |
|
||||
| Info | 超时、网络延迟 | 日志记录 |
|
||||
@@ -0,0 +1,231 @@
|
||||
# Quality Standards
|
||||
|
||||
质量评估标准和验收条件。
|
||||
|
||||
## Quality Dimensions
|
||||
|
||||
### 1. Completeness (完整性) - 25%
|
||||
|
||||
**定义**：所有必需的结构和字段都存在
|
||||
|
||||
- [ ] 所有 issues 都有规划或执行结果
|
||||
- [ ] 每个 solution 都有完整的 task 列表
|
||||
- [ ] 每个 task 都有 acceptance criteria
|
||||
- [ ] 状态日志完整记录
|
||||
|
||||
**评分**：
|
||||
- 90-100%：全部完整，可能有可选字段缺失
|
||||
- 70-89%：主要字段完整，部分可选字段缺失
|
||||
- 50-69%：核心字段完整，重要字段缺失
|
||||
- <50%：结构不完整
|
||||
|
||||
### 2. Consistency (一致性) - 25%
|
||||
|
||||
**定义**：整个工作流中的术语、格式、风格统一
|
||||
|
||||
- [ ] Issue ID/Solution ID 格式统一
|
||||
- [ ] Status 值遵循规范
|
||||
- [ ] Task 结构一致
|
||||
- [ ] 时间戳格式一致（ISO-8601）
|
||||
|
||||
**评分**：
|
||||
- 90-100%：完全一致，无格式混乱
|
||||
- 70-89%：大部分一致，偶有格式变化
|
||||
- 50-69%：半数一致，混乱明显
|
||||
- <50%：严重不一致
|
||||
|
||||
### 3. Correctness (正确性) - 25%
|
||||
|
||||
**定义**：执行过程中没有错误，验收条件都通过
|
||||
|
||||
- [ ] 无 DAG 循环依赖
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 所有 acceptance criteria 验证通过
|
||||
- [ ] 无代码冲突
|
||||
|
||||
**评分**：
|
||||
- 90-100%：完全正确，无错误
|
||||
- 70-89%：基本正确，<10% 错误率
|
||||
- 50-69%：有明显错误，10-30% 错误率
|
||||
- <50%：错误过多，>30% 错误率
|
||||
|
||||
### 4. Clarity (清晰度) - 25%
|
||||
|
||||
**定义**：文档清晰易读，逻辑清晰
|
||||
|
||||
- [ ] Task 描述明确可操作
|
||||
- [ ] Acceptance criteria 具体明确
|
||||
- [ ] 报告结构清晰，易理解
|
||||
- [ ] 错误信息详细有帮助
|
||||
|
||||
**评分**：
|
||||
- 90-100%：非常清晰，一目了然
|
||||
- 70-89%：大部分清晰，有基本可读性
|
||||
- 50-69%：部分清晰，理解有难度
|
||||
- <50%：极不清晰，难以理解
|
||||
|
||||
## Quality Gates
|
||||
|
||||
### Pass (通过)
|
||||
|
||||
**条件**：总分 >= 80%
|
||||
|
||||
**结果**：工作流正常完成，可进入下一阶段
|
||||
|
||||
**检查清单**：
|
||||
- [ ] 所有 issues 已规划或执行
|
||||
- [ ] 成功率 >= 80%
|
||||
- [ ] 无关键错误
|
||||
- [ ] 报告完整
|
||||
|
||||
### Review (需审查)
|
||||
|
||||
**条件**：总分 60-79%
|
||||
|
||||
**结果**：工作流部分完成，有可改进项
|
||||
|
||||
**常见问题**：
|
||||
- 部分 task 失败
|
||||
- 某些验收条件未满足
|
||||
- 文档不够完整
|
||||
|
||||
**改进方式**：
|
||||
- 检查失败的 task
|
||||
- 添加缺失的文档
|
||||
- 优化工作流配置
|
||||
|
||||
### Fail (失败)
|
||||
|
||||
**条件**：总分 < 60%
|
||||
|
||||
**结果**：工作流失败，需重做
|
||||
|
||||
**常见原因**：
|
||||
- 关键 task 失败
|
||||
- 规划过程中断
|
||||
- 系统错误过多
|
||||
- 无法生成有效报告
|
||||
|
||||
**恢复方式**：
|
||||
- 从快照恢复
|
||||
- 修复根本问题
|
||||
- 重新规划和执行
|
||||
|
||||
## Issue Classification
|
||||
|
||||
### Errors (必须修复)
|
||||
|
||||
| 错误 | 影响 | 处理 |
|
||||
|------|------|------|
|
||||
| DAG 循环依赖 | Critical | 中止规划 |
|
||||
| 任务无 acceptance | High | 补充条件 |
|
||||
| 提交失败 | High | 调查并重试 |
|
||||
| 规划 subagent 超时 | Medium | 重试或跳过 |
|
||||
| 无效的 solution ID | Medium | 重新生成 |
|
||||
|
||||
### Warnings (应该修复)
|
||||
|
||||
| 警告 | 影响 | 处理 |
|
||||
|------|------|------|
|
||||
| Task 执行时间过长 | Medium | 考虑拆分 |
|
||||
| 测试覆盖率低 | Medium | 补充测试 |
|
||||
| 多个解决方案 | Low | 明确选择 |
|
||||
| Criteria 不具体 | Low | 改进措辞 |
|
||||
|
||||
### Info (可选改进)
|
||||
|
||||
| 信息 | 说明 |
|
||||
|------|------|
|
||||
| 建议任务数 | 2-7 个任务为最优 |
|
||||
| 时间建议 | 总耗时 <= 2 小时为佳 |
|
||||
| 代码风格 | 检查是否遵循项目规范 |
|
||||
|
||||
## 执行检查清单
|
||||
|
||||
### 规划阶段
|
||||
|
||||
- [ ] Issue 描述清晰
|
||||
- [ ] 生成了有效的 solution
|
||||
- [ ] 所有 task 有 acceptance criteria
|
||||
- [ ] 依赖关系正确
|
||||
|
||||
### 执行阶段
|
||||
|
||||
- [ ] 每个 task 实现完整
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 所有 acceptance criteria 验证通过
|
||||
- [ ] 提交信息规范
|
||||
|
||||
### 完成阶段
|
||||
|
||||
- [ ] 生成了最终报告
|
||||
- [ ] 统计信息准确
|
||||
- [ ] 状态持久化完整
|
||||
- [ ] 快照保存无误
|
||||
|
||||
## 自动化验证函数
|
||||
|
||||
```javascript
|
||||
function runQualityChecks(workDir) {
|
||||
const state = JSON.parse(Read(`${workDir}/state.json`));
|
||||
const issues = state.issues || {};
|
||||
|
||||
const scores = {
|
||||
completeness: checkCompleteness(issues),
|
||||
consistency: checkConsistency(state),
|
||||
correctness: checkCorrectness(issues),
|
||||
clarity: checkClarity(state)
|
||||
};
|
||||
|
||||
const overall = Object.values(scores).reduce((a, b) => a + b) / 4;
|
||||
|
||||
return {
|
||||
scores: scores,
|
||||
overall: overall.toFixed(1),
|
||||
gate: overall >= 80 ? 'pass' : overall >= 60 ? 'review' : 'fail',
|
||||
details: {
|
||||
issues_total: Object.keys(issues).length,
|
||||
completed: Object.values(issues).filter(i => i.status === 'completed').length,
|
||||
failed: Object.values(issues).filter(i => i.status === 'failed').length
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 报告模板
|
||||
|
||||
```markdown
|
||||
# Quality Report
|
||||
|
||||
## Scores
|
||||
|
||||
| Dimension | Score | Status |
|
||||
|-----------|-------|--------|
|
||||
| Completeness | 90% | ✓ |
|
||||
| Consistency | 85% | ✓ |
|
||||
| Correctness | 92% | ✓ |
|
||||
| Clarity | 88% | ✓ |
|
||||
| **Overall** | **89%** | **PASS** |
|
||||
|
||||
## Issues Summary
|
||||
|
||||
- Total: 10
|
||||
- Completed: 8 (80%)
|
||||
- Failed: 2 (20%)
|
||||
- Pending: 0 (0%)
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. ...
|
||||
2. ...
|
||||
|
||||
## Errors & Warnings
|
||||
|
||||
### Errors (0)
|
||||
|
||||
None
|
||||
|
||||
### Warnings (1)
|
||||
|
||||
- Task T4 in ISS-003 took 45 minutes (expected 30)
|
||||
```
|
||||
270
.codex/skills/codex-issue-plan-execute/specs/solution-schema.md
Normal file
270
.codex/skills/codex-issue-plan-execute/specs/solution-schema.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Solution Schema Specification
|
||||
|
||||
解决方案数据结构和验证规则。
|
||||
|
||||
## When to Use
|
||||
|
||||
| Phase | Usage | Section |
|
||||
|-------|-------|---------|
|
||||
| Phase: action-plan | Solution 生成 | Solution Structure |
|
||||
| Phase: action-execute | Task 解析 | Task Definition |
|
||||
|
||||
---
|
||||
|
||||
## Solution Structure
|
||||
|
||||
### 完整 Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "SOL-ISS-001-1",
|
||||
"issue_id": "ISS-001",
|
||||
"description": "Fix authentication token expiration by extending TTL",
|
||||
"strategy_type": "bugfix",
|
||||
"created_at": "2025-01-29T11:00:00Z",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "T1",
|
||||
"title": "Update token TTL configuration",
|
||||
"action": "Modify",
|
||||
"scope": "src/config/auth.ts",
|
||||
"description": "Increase JWT token expiration from 1h to 24h",
|
||||
"modification_points": [
|
||||
{
|
||||
"file": "src/config/auth.ts",
|
||||
"target": "JWT_EXPIRY",
|
||||
"change": "Change value from 3600 to 86400"
|
||||
}
|
||||
],
|
||||
"implementation": [
|
||||
"Open src/config/auth.ts",
|
||||
"Locate JWT_EXPIRY constant",
|
||||
"Update value: 3600 → 86400",
|
||||
"Add comment explaining change"
|
||||
],
|
||||
"test": {
|
||||
"commands": ["npm test -- auth.config.test.ts"],
|
||||
"unit": ["Token expiration should be 24h"],
|
||||
"integration": []
|
||||
},
|
||||
"acceptance": {
|
||||
"criteria": [
|
||||
"Unit tests pass",
|
||||
"Token TTL is correctly set",
|
||||
"No breaking changes to API"
|
||||
],
|
||||
"verification": [
|
||||
"Run: npm test",
|
||||
"Manual: Verify token in console"
|
||||
]
|
||||
},
|
||||
"depends_on": [],
|
||||
"estimated_minutes": 15,
|
||||
"priority": 1
|
||||
}
|
||||
],
|
||||
"exploration_context": {
|
||||
"relevant_files": [
|
||||
"src/config/auth.ts",
|
||||
"src/services/auth.service.ts",
|
||||
"tests/auth.test.ts"
|
||||
],
|
||||
"patterns": "Follow existing config pattern in .env",
|
||||
"integration_points": "Used by AuthService in middleware"
|
||||
},
|
||||
"analysis": {
|
||||
"risk": "low",
|
||||
"impact": "medium",
|
||||
"complexity": "low"
|
||||
},
|
||||
"score": 0.95,
|
||||
"is_bound": true
|
||||
}
|
||||
```
|
||||
|
||||
## 字段说明
|
||||
|
||||
### 基础字段
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | ✓ | 唯一 ID：SOL-{issue-id}-{seq} |
|
||||
| `issue_id` | string | ✓ | 关联的 Issue ID |
|
||||
| `description` | string | ✓ | 解决方案描述 |
|
||||
| `strategy_type` | string | | 策略类型：bugfix/feature/refactor |
|
||||
| `tasks` | array | ✓ | 任务列表，至少 1 个 |
|
||||
|
||||
### Task 字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 任务 ID：T1, T2, ... |
|
||||
| `title` | string | 任务标题 |
|
||||
| `action` | string | 动作类型：Create/Modify/Fix/Refactor |
|
||||
| `scope` | string | 作用范围：文件或目录 |
|
||||
| `modification_points` | array | 具体修改点列表 |
|
||||
| `implementation` | array | 实现步骤 |
|
||||
| `test` | object | 测试命令和用例 |
|
||||
| `acceptance` | object | 验收条件和验证步骤 |
|
||||
| `depends_on` | array | 任务依赖：[T1, T2] |
|
||||
| `estimated_minutes` | number | 预计耗时（分钟） |
|
||||
|
||||
### 验收条件
|
||||
|
||||
```json
|
||||
{
|
||||
"acceptance": {
|
||||
"criteria": [
|
||||
"Unit tests pass",
|
||||
"Function returns correct result",
|
||||
"No performance regression"
|
||||
],
|
||||
"verification": [
|
||||
"Run: npm test -- module.test.ts",
|
||||
"Manual: Call function and verify output"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 验证规则
|
||||
|
||||
### 必需字段检查
|
||||
|
||||
```javascript
|
||||
function validateSolution(solution) {
|
||||
if (!solution.id) throw new Error("Missing: id");
|
||||
if (!solution.issue_id) throw new Error("Missing: issue_id");
|
||||
if (!solution.description) throw new Error("Missing: description");
|
||||
if (!Array.isArray(solution.tasks)) throw new Error("tasks must be array");
|
||||
if (solution.tasks.length === 0) throw new Error("tasks cannot be empty");
|
||||
return true;
|
||||
}
|
||||
|
||||
function validateTask(task) {
|
||||
if (!task.id) throw new Error("Missing: task.id");
|
||||
if (!task.title) throw new Error("Missing: task.title");
|
||||
if (!task.action) throw new Error("Missing: task.action");
|
||||
if (!Array.isArray(task.implementation)) throw new Error("implementation must be array");
|
||||
if (!task.acceptance) throw new Error("Missing: task.acceptance");
|
||||
if (!Array.isArray(task.acceptance.criteria)) throw new Error("acceptance.criteria must be array");
|
||||
if (task.acceptance.criteria.length === 0) throw new Error("acceptance.criteria cannot be empty");
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
### 格式验证
|
||||
|
||||
- ID 格式：`SOL-ISS-\d+-\d+`
|
||||
- Action 值：Create | Modify | Fix | Refactor | Add | Remove
|
||||
- Risk/Impact/Complexity 值：low | medium | high
|
||||
- Score 范围：0.0 - 1.0
|
||||
|
||||
## 任务依赖
|
||||
|
||||
### 表示方法
|
||||
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"id": "T1",
|
||||
"title": "Create auth module",
|
||||
"depends_on": []
|
||||
},
|
||||
{
|
||||
"id": "T2",
|
||||
"title": "Add authentication logic",
|
||||
"depends_on": ["T1"]
|
||||
},
|
||||
{
|
||||
"id": "T3",
|
||||
"title": "Add tests",
|
||||
"depends_on": ["T1", "T2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### DAG 验证
|
||||
|
||||
```javascript
|
||||
function validateDAG(tasks) {
|
||||
const visited = new Set();
|
||||
const recursionStack = new Set();
|
||||
|
||||
function hasCycle(taskId) {
|
||||
visited.add(taskId);
|
||||
recursionStack.add(taskId);
|
||||
|
||||
const task = tasks.find(t => t.id === taskId);
|
||||
if (!task || !task.depends_on) return false;
|
||||
|
||||
for (const dep of task.depends_on) {
|
||||
if (!visited.has(dep)) {
|
||||
if (hasCycle(dep)) return true;
|
||||
} else if (recursionStack.has(dep)) {
|
||||
return true; // 发现循环
|
||||
}
|
||||
}
|
||||
|
||||
recursionStack.delete(taskId);
|
||||
return false;
|
||||
}
|
||||
|
||||
for (const task of tasks) {
|
||||
if (!visited.has(task.id) && hasCycle(task.id)) {
|
||||
throw new Error(`Circular dependency detected: ${task.id}`);
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
## 文件保存
|
||||
|
||||
### 位置
|
||||
|
||||
```
|
||||
.workflow/.scratchpad/codex-issue-{timestamp}/solutions/
|
||||
├── ISS-001-plan.json # 规划结果
|
||||
├── ISS-001-execution.json # 执行结果
|
||||
├── ISS-002-plan.json
|
||||
└── ISS-002-execution.json
|
||||
```
|
||||
|
||||
### 文件内容
|
||||
|
||||
**规划结果**：包含 solution 完整定义
|
||||
**执行结果**：包含执行状态和提交信息
|
||||
|
||||
```json
|
||||
{
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"status": "completed|failed",
|
||||
"executed_at": "ISO-8601",
|
||||
"execution_result": {
|
||||
"files_modified": ["src/auth.ts"],
|
||||
"commit_hash": "abc123...",
|
||||
"tests_passed": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 质量门控
|
||||
|
||||
### Solution 评分标准
|
||||
|
||||
| 指标 | 权重 | 评分方法 |
|
||||
|------|------|----------|
|
||||
| 任务完整性 | 30% | 无空任务，每个任务有 acceptance |
|
||||
| 依赖合法性 | 20% | 无循环依赖，依赖链清晰 |
|
||||
| 验收可测 | 30% | Criteria 明确可测，有验证步骤 |
|
||||
| 复杂度评估 | 20% | Risk/Impact/Complexity 合理评估 |
|
||||
|
||||
### 通过条件
|
||||
|
||||
- 所有必需字段存在
|
||||
- 无格式错误
|
||||
- 无循环依赖
|
||||
- Score >= 0.8
|
||||
268
.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md
Normal file
268
.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Subagent Roles Definition
|
||||
|
||||
Subagent 的角色定义和职责范围。
|
||||
|
||||
## Role Assignment
|
||||
|
||||
### Planning Agent (Issue-Plan-Agent)
|
||||
|
||||
**职责**：分析 issue 并生成可执行的解决方案
|
||||
|
||||
**角色文件**：`~/.codex/agents/issue-plan-agent.md`
|
||||
|
||||
#### Capabilities
|
||||
|
||||
- **允许**：
|
||||
- 读取代码、文档、配置
|
||||
- 探索项目结构和依赖关系
|
||||
- 分析问题和设计解决方案
|
||||
- 分解任务为可执行步骤
|
||||
- 定义验收条件
|
||||
|
||||
- **禁止**：
|
||||
- 修改代码
|
||||
- 执行代码
|
||||
- 推送到远程
|
||||
|
||||
#### 输入
|
||||
|
||||
```json
|
||||
{
|
||||
"issue_id": "ISS-001",
|
||||
"title": "Fix authentication timeout",
|
||||
"description": "User sessions timeout too quickly",
|
||||
"project_context": {
|
||||
"tech_stack": "Node.js + Express + JWT",
|
||||
"guidelines": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 输出
|
||||
|
||||
```json
|
||||
{
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "T1",
|
||||
"title": "Update JWT configuration",
|
||||
"...": "..."
|
||||
}
|
||||
],
|
||||
"acceptance": {
|
||||
"criteria": [...],
|
||||
"verification": [...]
|
||||
},
|
||||
"score": 0.95
|
||||
}
|
||||
```
|
||||
|
||||
### Execution Agent (Issue-Execute-Agent)
|
||||
|
||||
**职责**：执行规划的解决方案，实现所有任务
|
||||
|
||||
**角色文件**：`~/.codex/agents/issue-execute-agent.md`
|
||||
|
||||
#### Capabilities
|
||||
|
||||
- **允许**：
|
||||
- 读取代码和配置
|
||||
- 修改代码
|
||||
- 运行测试
|
||||
- 提交代码
|
||||
- 验证 acceptance criteria
|
||||
|
||||
- **禁止**：
|
||||
- 推送到远程分支
|
||||
- 创建 PR（除非明确授权）
|
||||
- 删除分支或文件
|
||||
|
||||
#### 输入
|
||||
|
||||
```json
|
||||
{
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"issue_id": "ISS-001",
|
||||
"solution": {
|
||||
"tasks": [...],
|
||||
"exploration_context": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 输出
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed|failed",
|
||||
"files_modified": ["src/auth.ts", "src/config.ts"],
|
||||
"commit_hash": "abc123def456",
|
||||
"tests_passed": true,
|
||||
"acceptance_verified": true,
|
||||
"errors": []
|
||||
}
|
||||
```
|
||||
|
||||
## Dual-Agent Strategy
|
||||
|
||||
### 为什么使用双 Agent 模式
|
||||
|
||||
1. **关注点分离**：规划和执行各自专注一个任务
|
||||
2. **并行优化**：虽然执行依然串行，但规划可独立优化
|
||||
3. **上下文最小化**：仅传递 solution ID，避免上下文膨胀
|
||||
4. **错误隔离**：规划失败不影响执行，反之亦然
|
||||
|
||||
### 工作流程
|
||||
|
||||
```
|
||||
┌────────────────────────┐
|
||||
│ Planning Agent │
|
||||
│ • Analyze issue │
|
||||
│ • Design solution │
|
||||
│ • Generate tasks │
|
||||
│ → Output: SOL-xxx-1 │
|
||||
└────────┬───────────────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Bind solution│
|
||||
│ Update state │
|
||||
└──────┬───────┘
|
||||
↓
|
||||
┌─────────────────────────┐
|
||||
│ Execution Agent │
|
||||
│ • Load SOL-xxx-1 │
|
||||
│ • Execute all tasks │
|
||||
│ • Run tests │
|
||||
│ • Commit changes │
|
||||
│ → Output: commit hash │
|
||||
└─────────────────────────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Save results │
|
||||
│ Update state │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
## Context Minimization
|
||||
|
||||
### 信息传递原则
|
||||
|
||||
**目标**：最小化上下文，减少 token 浪费
|
||||
|
||||
#### Planning Phase
|
||||
|
||||
**传递内容**：
|
||||
- Issue ID 和 Title
|
||||
- Issue Description
|
||||
- Project tech stack
|
||||
- Project guidelines
|
||||
|
||||
**不传递**：
|
||||
- 完整的代码库快照
|
||||
- 所有相关文件内容
|
||||
- 历史执行结果
|
||||
|
||||
#### Execution Phase
|
||||
|
||||
**传递内容**：
|
||||
- Solution ID（仅 ID，不传递完整 solution）
|
||||
- 执行参数（worktree 路径等）
|
||||
|
||||
**不传递**：
|
||||
- 规划阶段的完整上下文
|
||||
- 其他 issues 的信息
|
||||
|
||||
### 上下文加载策略
|
||||
|
||||
```javascript
|
||||
// Planning Agent 自己加载
|
||||
const issueDetails = ReadFromIssueStore(issueId);
|
||||
const techStack = Read('.workflow/project-tech.json');
|
||||
const guidelines = Read('.workflow/project-guidelines.json');
|
||||
|
||||
// Execution Agent 自己加载
|
||||
const solution = ReadFromSolutionStore(solutionId);
|
||||
const project = Read('.workflow/project-guidelines.json');
|
||||
```
|
||||
|
||||
## 错误处理与重试
|
||||
|
||||
### Planning 错误
|
||||
|
||||
| 错误 | 原因 | 重试策略 |
|
||||
|------|------|----------|
|
||||
| Subagent 超时 | 分析复杂 | 增加 timeout，重试 1 次 |
|
||||
| 无效 solution | 生成不符合 schema | 返回用户，标记失败 |
|
||||
| 依赖循环 | DAG 错误 | 返回用户进行修正 |
|
||||
|
||||
### Execution 错误
|
||||
|
||||
| 错误 | 原因 | 重试策略 |
|
||||
|------|------|----------|
|
||||
| Task 失败 | 代码有问题 | 记录错误，标记 solution 失败 |
|
||||
| 测试失败 | 测试用例不符 | 不提交，标记失败 |
|
||||
| 提交失败 | 冲突或权限 | 创建快照，让用户决定 |
|
||||
|
||||
## 交互指南
|
||||
|
||||
### 向 Planning Agent 的问题
|
||||
|
||||
```
|
||||
这个 issue 描述了什么问题？
|
||||
→ 返回：问题分析 + 根本原因
|
||||
|
||||
解决这个问题需要修改哪些文件？
|
||||
→ 返回：文件列表 + 修改点
|
||||
|
||||
如何验证解决方案是否有效？
|
||||
→ 返回：验收条件 + 验证步骤
|
||||
```
|
||||
|
||||
### 向 Execution Agent 的问题
|
||||
|
||||
```
|
||||
这个 task 有哪些实现步骤？
|
||||
→ 返回：逐步指南 + 代码示例
|
||||
|
||||
所有测试都通过了吗？
|
||||
→ 返回：测试结果 + 失败原因（如有）
|
||||
|
||||
acceptance criteria 都满足了吗？
|
||||
→ 返回：验证结果 + 不符合项（如有）
|
||||
```
|
||||
|
||||
## Role 文件位置
|
||||
|
||||
```
|
||||
~/.codex/agents/
|
||||
├── issue-plan-agent.md # 规划角色
|
||||
├── issue-execute-agent.md # 执行角色
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 如果角色文件不存在
|
||||
|
||||
Orchestrator 会使用 `universal-executor` 或 `code-developer` 作为备用角色。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 为 Planning Agent 设计提示词
|
||||
|
||||
```markdown
|
||||
1. 从 issue 描述提取关键信息
|
||||
2. 探索相关代码和类似实现
|
||||
3. 设计最小化解决方案
|
||||
4. 分解为 2-7 个可执行任务
|
||||
5. 为每个 task 定义明确的 acceptance criteria
|
||||
```
|
||||
|
||||
### 为 Execution Agent 设计提示词
|
||||
|
||||
```markdown
|
||||
1. 加载 solution 和所有 task 定义
|
||||
2. 按依赖顺序执行 tasks
|
||||
3. 为每个 task：implement → test → verify
|
||||
4. 确保所有 acceptance criteria 通过
|
||||
5. 提交一次包含所有更改
|
||||
```
|
||||
Reference in New Issue
Block a user