计划模式
Harness-agent 工具
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
当用户需要计划而非执行时,使用此技能。
核心行为
在这一轮中,你只做计划:
- 不要实现代码。
- 不要编辑项目文件(计划 markdown 文件除外)。
- 不要运行变更性终端命令、提交、推送或执行外部操作。
- 你可以使用只读命令/工具检查仓库或其他上下文。
- 你的交付物是保存在活动工作区内
plans/下的 markdown 计划。
输出要求
编写具体且可执行的 markdown 计划。
相关时包含:
- 目标
- 当前上下文/假设
- 提议的方法
- 分步计划
- 可能变更的文件
- 测试/验证
- 风险、权衡和开放问题
如果任务与代码相关,包含确切的文件路径、可能的测试目标和验证步骤。
保存位置
使用 write_file 保存到:
plans/YYYY-MM-DD_HHMMSS-<slug>.md
将其视为相对于活动工作目录/backend 工作区。
如果运行时提供了特定目标路径,使用确切路径。
如果没有,在 plans/ 下自己创建一个合理的时间戳文件名。
交互风格
- 如果请求足够清晰,直接编写计划。
- 如果没有明确指令伴随
/plan,从当前对话上下文推断任务。 - 如果确实未充分指定,提出简短的澄清问题而不是猜测。
- 保存计划后,简要回复你计划了什么以及保存路径。
写好计划
本技能的其余部分是编写优秀实施计划的技艺——即上述 markdown 文件内的内容。
概述
编写全面的实施计划,假设实施者对代码库零上下文且品味可疑。记录他们需要的一切:要接触哪些文件、完整代码、测试命令、要检查的文档、如何验证。给他们细粒度的任务。DRY。YAGNI。TDD。频繁提交。
假设实施者是一位熟练的开发者,但对工具集或问题领域几乎一无所知。假设他们不太了解好的测试设计。
核心原则: 好的计划让实施变得显而易见。如果有人需要猜测,说明计划不完整。
何时需要完整实施计划
始终在之前使用:
- 实施多步骤功能
- 分解复杂需求
- 通过基于任务的执行委派给子代理
不要跳过当:
- 功能看起来简单(假设会导致 bug)
- 你计划自己实施(未来的你需要指导)
- 独自工作(文档很重要)
细粒度任务
每个任务 = 2-5 分钟的专注工作。
每一步是一个动作:
- "编写失败测试" — 步骤
- "运行它以确保失败" — 步骤
- "实施最小代码使测试通过" — 步骤
- "运行测试并确保它们通过" — 步骤
- "提交" — 步骤
太大:
### 任务1:构建认证系统
[跨 5 个文件的 50 行代码]
正确大小:
### 任务1:创建带 email 字段的 User 模型
[10 行,1 个文件]
### 任务2:向 User 添加密码哈希字段
[8 行,1 个文件]
### 任务3:创建密码哈希工具
[15 行,1 个文件]
计划文档结构
头部(必需)
每个计划必须以以下内容开头:
# [功能名称] 实施计划
> **给代理:** 使用基于任务的执行技能逐任务实施此计划。
**目标:** [一句话描述构建了什么]
**架构:** [关于方法的 2-3 句话]
**技术栈:** [关键技术/库]
---
任务结构
每个任务遵循此格式:
### 任务 N:[描述性名称]
**目标:** 此任务完成什么(一句话)
**文件:**
- 创建:`exact/path/to/new_file.py`
- 修改:`exact/path/to/existing.py:45-67`(如果知道行号)
- 测试:`tests/path/to/test_file.py`
**步骤1:编写失败测试**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
**步骤2:运行测试以验证失败**
运行:`pytest tests/path/test.py::test_specific_behavior -v`
预期:失败 — "function not defined"
**步骤3:编写最小实现**
```python
def function(input):
return expected
```
**步骤4:运行测试以验证通过**
运行:`pytest tests/path/test.py::test_specific_behavior -v`
预期:通过
**步骤5:提交**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
编写流程
步骤1:理解需求
阅读并理解:
- 功能需求
- 设计文档或用户描述
- 验收标准
- 约束
步骤2:探索代码库
使用 harness 文件系统工具理解项目:
# 理解项目结构
glob(pattern="**/*.py", path="src/")
# 查看类似功能
grep(pattern="similar_pattern", path="src/")
# 列出测试文件
glob(pattern="tests/**/*.py")
# 读取关键文件
read_file("src/app.py")
步骤3:设计方法
决定:
- 架构模式
- 文件组织
- 需要的依赖
- 测试策略
步骤4:编写任务
按顺序创建任务:
- 设置/基础设施
- 核心功能(每个都 TDD)
- 边界情况
- 集成
- 清理/文档
步骤5:添加完整细节
对于每个任务,包含:
- 确切文件路径(不是"配置文件"而是
src/config/settings.py) - 完整代码示例(不是"添加验证"而是实际代码)
- 确切命令与预期输出
- 验证步骤证明任务有效
步骤6:审查计划
检查:
- 任务按顺序且逻辑清晰
- 每个任务细粒度(2-5 分钟)
- 文件路径确切
- 代码示例完整(可复制粘贴)
- 命令确切且预期输出明确
- 没有缺失的上下文
- 应用了 DRY、YAGNI、TDD 原则
原则
DRY(不要重复自己)
坏: 在 3 个地方复制粘贴验证 好: 提取验证函数,到处使用
YAGNI(你不会需要它)
坏: 为未来需求添加"灵活性" 好: 只实施现在需要的东西
# 坏 — YAGNI 违反
class User:
def __init__(self, name, email):
self.name = name
self.email = email
self.preferences = {} # 还不需要!
self.metadata = {} # 还不需要!
# 好 — YAGNI
class User:
def __init__(self, name, email):
self.name = name
self.email = email
TDD(测试驱动开发)
每个产生代码的任务应包含完整的 TDD 循环:
- 编写失败测试
- 运行以验证失败
- 编写最小代码
- 运行以验证通过
详情参见 test-driven-development 技能。
频繁提交
每个任务后提交:
git add [files]
git commit -m "type: description"
常见错误
模糊的任务
坏: "添加认证" 好: "创建带 email 和 password_hash 字段的 User 模型"
不完整的代码
坏: "步骤1:添加验证函数" 好: "步骤1:添加验证函数"后跟完整的函数代码
缺失验证
坏: "步骤3:测试它是否有效"
好: "步骤3:运行 pytest tests/test_auth.py -v,预期:3 个通过"
缺失文件路径
坏: "创建模型文件"
好: "创建:src/models/user.py"
执行交接
保存计划后,提供执行方法:
"计划完成并已保存。准备使用 task 工具执行——每个计划任务一个子代理。我可以继续吗?"
执行时:
- 每个计划任务使用来自保存计划的完整上下文进行新的
task调度 - 在移动到下一个任务之前审查输出
记住
细粒度任务(每个 2-5 分钟)
确切文件路径
完整代码(可复制粘贴)
确切命令与预期输出
验证步骤
DRY、YAGNI、TDD
频繁提交
好的计划让实施变得显而易见。