# 任务执行规范 — 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. 兜底原则

- **能读文件不靠猜**：不要假设文件内容，读它
- **能跑命令不空想**：不确定就执行确认
- **能测试不跳过**：改了什么要验证
- **能回滚才动手**：没有安全退路的修改先问
- **能问就别说"我猜"**：不确定就问，不丢人