大海
140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# 任务执行规范 — Planning vs Reactive
|
||
|
||
> 此规范是 AGENTS.md Execution Protocol 的详细参考。
|
||
> 实际执行以 AGENTS.md（注入上下文）为准。
|
||
|
||
## 0. 总则 — 先分类，再执行
|
||
|
||
**收到任务后，第一步是分类，不是执行。**
|
||
|
||
- **Simple Task**（单文件/单命令/查询/对话）→ 直接执行
|
||
- **Complex Task**（多文件/多步骤/Schema变更/跨项目/新功能）→ 先输出 PLAN，再执行
|
||
|
||
分类标准见 AGENTS.md §0. Complexity Classification。
|
||
|
||
## 1. 任务理解
|
||
|
||
明确回答以下问题：
|
||
- 用户要解决什么问题？
|
||
- 目标是什么？（可衡量的标准）
|
||
- 输入是什么？（文件/参数/数据）
|
||
- 输出是什么？（代码/文档/分析/配置）
|
||
- 约束是什么？（时间/平台/兼容性/安全）
|
||
- 风险是什么？（数据丢失/功能破坏/回滚难度）
|
||
- 是否需要读文件/跑命令/查文档/测试？
|
||
|
||
**如果答案不明确，先问我，不要假设。**
|
||
|
||
## 2. 上下文建立
|
||
|
||
- 扫描项目顶层结构（`ls` / `find` / `wc -l`）
|
||
- 扫描技术栈（`package.json` / `pyproject.toml` / `pom.xml` / `go.mod`）
|
||
- 定位相关文件（入口文件、核心模块、配置文件）
|
||
- 理解已有的代码风格和架构约定
|
||
- 查找是否有类似已有实现
|
||
|
||
**不在没看项目的情况下写代码。**
|
||
|
||
## 3. 任务拆解
|
||
|
||
如果任务可以拆成多个子任务，必须拆解。每个子任务明确：
|
||
- 任务目标
|
||
- 输入 / 输出
|
||
- 依赖关系 / 执行顺序
|
||
- 验收标准
|
||
- 失败处理策略
|
||
|
||
并行子任务要分别列出（前端/后端/数据库/配置/测试/文档）。
|
||
|
||
## 4. Skill 匹配
|
||
|
||
- 是否处理过类似任务？→ 查 MEMORY.md
|
||
- 是否有类似项目的经验？→ 查 memory/daily/
|
||
- 是否有已有的 skill？→ 查 tools/、scripts/
|
||
- 如果有，优先复用并调整；如果没有，完成后判断是否创建新 skill
|
||
|
||
## 5. 方案设计
|
||
|
||
动手前给出方案：
|
||
- 推荐方案是什么？
|
||
- 为什么选这个？（选型理由）
|
||
- 最小改动点是什么？
|
||
- 影响范围是什么？
|
||
- 风险是什么？
|
||
- 如何验证？
|
||
|
||
**优先选择：低风险、可回滚、符合项目风格、可测试、可维护、不破坏现有功能。**
|
||
|
||
## 6. 执行修改
|
||
|
||
- 保持原有代码风格（缩进、命名、注释风格）
|
||
- **所有代码必须有注释** — 注释写 WHY，不重复代码本身
|
||
- 不做无关重构（除非安全或性能必须）
|
||
- 不引入不必要依赖
|
||
- 不硬编码敏感信息（路径/token/密码）
|
||
- 不删用户原有代码（除非明确要求）
|
||
- 不编造不存在的文件或 API
|
||
- 不跳过错误处理
|
||
- 不留下调试代码
|
||
|
||
## 7. 验证结果
|
||
|
||
明确回答：
|
||
- 如何运行？（命令或操作）
|
||
- 如何测试？（单元测试/集成测试/手动测试）
|
||
- 如何构建？（编译/打包）
|
||
- 如何手动验证？（UI 截图/日志/响应）
|
||
- 边界情况覆盖了吗？
|
||
- 失败时如何排查？
|
||
|
||
如果不能实际运行，也要给出用户可执行的验证命令。
|
||
|
||
## 8. 经验沉淀
|
||
|
||
任务完成后，必须判断：
|
||
- 是否有可复用的经验？
|
||
- 应创建 skill？（适用场景 + 输入 + 步骤 + 风险 + 验证 + 输出）
|
||
- 应更新 MEMORY.md？
|
||
- 应更新默认工作流？
|
||
- 有不该再重复的错误？
|
||
|
||
**输出一段简短的"经验沉淀"。**
|
||
|
||
## 9. 输出格式
|
||
|
||
任务结果**必须**按以下格式组织：
|
||
|
||
```
|
||
## 任务结果
|
||
|
||
说明完成了什么，解决了什么问题。
|
||
|
||
## 关键修改 / 关键判断
|
||
|
||
核心改动或核心分析，不列无关细节。
|
||
|
||
## 影响范围
|
||
|
||
涉及哪些模块、文件、接口、数据或页面。
|
||
|
||
## 验证方式
|
||
|
||
如何运行、测试、构建或手动验证。给出可执行命令。
|
||
|
||
## 风险与注意事项
|
||
|
||
可能的问题、后续建议、未处理的情况。
|
||
|
||
## 经验沉淀
|
||
|
||
可复用经验 / skill 建议 / memory 更新 / 工作流改进。
|
||
```
|
||
|
||
## 10. 兜底原则
|
||
|
||
- **能读文件不靠猜**：不要假设文件内容，读它
|
||
- **能跑命令不空想**：不确定就执行确认
|
||
- **能测试不跳过**：改了什么要验证
|
||
- **能回滚才动手**：没有安全退路的修改先问
|
||
- **能问就别说"我猜"**：不确定就问，不丢人
|