mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: 完成 Codex Issue Plan-Execute Skill v2.0 优化
- 新增 OPTIMIZATION_SUMMARY.md，详细记录优化过程和成果 - 新增 README_OPTIMIZATION.md，概述优化后的文件结构和关键指标 - 创建 specs/agent-roles.md，整合 Planning Agent 和 Execution Agent 的角色定义 - 合并多个提示词文件，减少内容重复，优化 Token 使用 - 新建 ARCHITECTURE.md 和 INDEX.md，提供系统架构和文档导航 - 添加 CONTENT_MIGRATION_REPORT.md，确保内容迁移的完整性和零丢失 - 更新文件引用，确保向后兼容性，添加弃用通知
This commit is contained in:
catlog22
@@ -1,268 +1,32 @@
|
||||
# Subagent Roles Definition
|
||||
⚠️ **DEPRECATED** - This file is deprecated as of v2.0 (2025-01-29)
|
||||
|
||||
Subagent 的角色定义和职责范围。
|
||||
**Use instead**: [`agent-roles.md`](agent-roles.md)
|
||||
|
||||
## Role Assignment
|
||||
This file has been superseded by a consolidated `agent-roles.md` that improves organization and eliminates duplication.
|
||||
|
||||
### 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 的信息
|
||||
|
||||
### 上下文加载策略
|
||||
**Why the change?**
|
||||
- Consolidates all agent role definitions in one place
|
||||
- Eliminates duplicated role descriptions
|
||||
- Single source of truth for agent capabilities
|
||||
- Better organization with unified reference format
|
||||
|
||||
**Migration**:
|
||||
```javascript
|
||||
// Planning Agent 自己加载
|
||||
const issueDetails = ReadFromIssueStore(issueId);
|
||||
const techStack = Read('.workflow/project-tech.json');
|
||||
const guidelines = Read('.workflow/project-guidelines.json');
|
||||
// OLD (v1.0)
|
||||
// Reference: specs/subagent-roles.md
|
||||
|
||||
// Execution Agent 自己加载
|
||||
const solution = ReadFromSolutionStore(solutionId);
|
||||
const project = Read('.workflow/project-guidelines.json');
|
||||
// NEW (v2.0)
|
||||
// Reference: specs/agent-roles.md
|
||||
```
|
||||
|
||||
## 错误处理与重试
|
||||
**Timeline**:
|
||||
- v2.0 (2025-01-29): Old file kept for backward compatibility
|
||||
- v2.1 (2025-03-31): Old file will be removed
|
||||
|
||||
### Planning 错误
|
||||
---
|
||||
|
||||
| 错误 | 原因 | 重试策略 |
|
||||
|------|------|----------|
|
||||
| Subagent 超时 | 分析复杂 | 增加 timeout，重试 1 次 |
|
||||
| 无效 solution | 生成不符合 schema | 返回用户，标记失败 |
|
||||
| 依赖循环 | DAG 错误 | 返回用户进行修正 |
|
||||
# Subagent Roles Definition (Legacy - See agent-roles.md instead)
|
||||
|
||||
### Execution 错误
|
||||
See [`agent-roles.md`](agent-roles.md) for the current consolidated agent roles specification.
|
||||
|
||||
| 错误 | 原因 | 重试策略 |
|
||||
|------|------|----------|
|
||||
| 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. 提交一次包含所有更改
|
||||
```
|
||||
All content has been merged into the new agent-roles.md file with improved organization and formatting.
|
||||
|
||||
Reference in New Issue
Block a user