Plan
Plan 模式:将一份可执行的 markdown 计划写入 .kopi/plans/,不执行任何操作。任务拆分为小块、路径精确、代码完整。
Skill 元数据
| Source | Bundled(默认安装) |
| Path | skills/software-development/plan |
| Version | 2.0.0 |
| Author | KOPI AI AGENT(writing-craft 改编自 obra/superpowers) |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | planning, plan-mode, implementation, workflow, design, documentation |
| Related skills | subagent-driven-development, test-driven-development, requesting-code-review |
Reference:完整的 SKILL.md
以下是触发此 skill 时 Kopi Agent 加载的完整 skill 定义。当 skill 处于激活状态时,agent 看到的指令就是这些内容。
Plan Mode
当用户想要一份计划而非直接执行时,使用此 skill。
核心行为
在本轮对话中,你只负责规划。
- 不要实现代码。
- 除计划 markdown 文件外,不要编辑项目文件。
- 不要运行会修改状态的终端命令,不要 commit、push 或执行任何外部操作。
- 需要时,你可以使用只读命令/工具来查看 repo 或其他上下文。
- 你的交付物是一份 markdown 计划,保存在当前活动 workspace 下的
.kopi/plans/中。
输出要求
编写一份具体、可执行的 markdown 计划。
在相关内容中包含:
- Goal(目标)
- 当前上下文 / 假设
- 提议的方法
- 分步计划
- 可能变更的文件
- 测试 / 验证
- 风险、权衡与待决问题
如果任务与代码相关,请包含精确的文件路径、可能的测试目标和验证步骤。
保存位置
使用 write_file 将计划保存到以下位置:
.kopi/plans/YYYY-MM-DD_HHMMSS-<slug>.md
请将其视为相对于活动工作目录 / backend workspace 的路径。Kopi Agent 的文件工具能感知 backend,因此使用这个相对路径可以让计划在 local、docker、ssh、modal 和 daytona 这些 backend 上都随 workspace 一同保存。
如果运行时提供了特定的目标路径,请使用该确切路径。
如果没有,请自行在 .kopi/plans/ 下创建一个合理的带时间戳的文件名。
交互风格
- 如果请求已经足够清晰,就直接编写计划。
- 如果
/plan没有伴随明确的指令,请从当前对话上下文中推断任务。 - 如果确实不明确,就简短地提一个澄清问题,而不要猜测。
- 保存计划后,简要回复你规划了什么以及保存的路径。
如何写好计划
此 skill 的后续内容是编写一份优秀实现计划的技巧——也就是写入上述 markdown 文件的内容。
概述
编写全面的实现计划,并假设计划的执行者对代码库零上下文、品味也令人怀疑。记录下他们需要的一切:要改动哪些文件、完整代码、测试命令、需要查阅的文档、如何验证。给他们小块的任务。DRY。YAGNI。TDD。频繁提交。
假设执行者是一名熟练的开发者,但对工具链或问题域几乎一无所知。假设他们并不擅长良好的测试设计。
**核心原则:**一份好的计划让实现变得显而易见。如果有人必须去猜测,说明计划还不完整。
何时需要完整的实现计划
务必在以下情况之前使用:
- 实现多步骤功能
- 拆解复杂需求
- 通过 subagent-driven-development 委派给 subagent
以下情况不要跳过:
- 功能看起来很简单(假设会导致 bug)
- 你打算自己实现它(未来的你需要指引)
- 独自工作(文档很重要)
小块任务粒度
每个任务 = 2-5 分钟的专注工作。
每个步骤都是一个动作:
- "编写失败的测试" —— 一个步骤
- "运行它,确认它失败" —— 一个步骤
- "实现让测试通过的最小代码" —— 一个步骤
- "运行测试并确认它们通过" —— 一个步骤
- "提交" —— 一个步骤
太大:
### Task 1: Build authentication system
[50 lines of code across 5 files]
合适的大小:
### Task 1: Create User model with email field
[10 lines, 1 file]
### Task 2: Add password hash field to User
[8 lines, 1 file]
### Task 3: Create password hashing utility
[15 lines, 1 file]
计划文档结构
Header(必需)
每份计划都必须以以下内容开头:
# [Feature Name] Implementation Plan
> **For Kopi Agent:** Use subagent-driven-development skill to implement this plan task-by-task.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
任务结构
每个任务遵循以下格式:
### Task N: [Descriptive Name]
**Objective:** What this task accomplishes (one sentence)
**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`
**Step 1: Write failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
**Step 2: Run test to verify failure**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"
**Step 3: Write minimal implementation**
```python
def function(input):
return expected
```
**Step 4: Run test to verify pass**
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS
**Step 5: Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
编写流程
步骤 1:理解需求
阅读并理解:
- 功能需求
- 设计文档或用户描述
- 验收标准
- 约束条件
步骤 2:探索代码库
使用 Kopi Agent 工具来理解项目:
# Understand project structure
search_files("*.py", target="files", path="src/")
# Look at similar features
search_files("similar_pattern", path="src/", file_glob="*.py")
# Check existing tests
search_files("*.py", target="files", path="tests/")
# Read key files
read_file("src/app.py")
步骤 3:设计方法
确定:
- 架构模式
- 文件组织方式
- 所需依赖
- 测试策略
步骤 4:编写任务
按顺序创建任务:
- 设置/基础设施
- 核心功能(每个都采用 TDD)
- 边界情况
- 集成
- 清理/文档
步骤 5:添加完整细节
对每个任务,包含:
- 精确的文件路径(不是"那个配置文件",而是
src/config/settings.py) - 完整的代码示例(不是"添加校验",而是实际的代码)
- 精确的命令及预期输出
- 验证步骤,证明该任务确实有效
步骤 6:审查计划
检查:
- 任务是有序且合乎逻辑的
- 每个任务都很小(2-5 分钟)
- 文件路径是精确的
- 代码示例是完整的(可直接复制粘贴)
- 命令是精确的,并附有预期输出
- 没有遗漏的上下文
- 应用了 DRY、YAGNI、TDD 原则
原则
DRY(不要重复自己)
错误: 在 3 处复制粘贴验证逻辑 正确: 提取验证函数,统一在各处使用
YAGNI(你不会需要它)
错误: 为未来可能的需求添加"灵活性" 正确: 只实现当前需要的功能
# Bad — YAGNI violation
class User:
def __init__(self, name, email):
self.name = name
self.email = email
self.preferences = {} # Not needed yet!
self.metadata = {} # Not needed yet!
# Good — YAGNI
class User:
def __init__(self, name, email):
self.name = name
self.email = email
TDD(测试驱动开发)
每个产出代码的任务都应包含完整的 TDD 周期:
- 编写失败的测试
- 运行以验证测试失败
- 编写最简代码
- 运行以验证测试通过
详情请参见 test-driven-development skill。
频繁提交
每个任务完成后都进行提交:
git add [files]
git commit -m "type: description"
常见错误
模糊的任务
错误: "添加身份验证" 正确: "创建 User model,包含 email 和 password_hash 字段"
不完整的代码
错误: "步骤 1:添加验证函数" 正确: "步骤 1:添加验证函数" 并附上完整的函数代码
缺少验证
错误: "步骤 3:测试它能正常工作"
正确: "步骤 3:运行 pytest tests/test_auth.py -v,预期:3 passed"
缺少文件路径
错误: "创建模型文件"
正确: "创建:src/models/user.py"
执行交接
保存计划后,提供执行方案供选择:
"计划已完成并保存。准备使用 subagent-driven-development 执行 —— 我会为每个任务分派一个全新的 subagent,并进行两阶段评审(先检查规格符合性,再检查代码质量)。要继续吗?"
执行时,使用 subagent-driven-development skill:
- 每个任务分派一个全新的
delegate_task,并提供完整上下文 - 每个任务完成后进行规格符合性评审
- 规格通过后进行代码质量评审
- 仅当两轮评审都通过后才继续
记住
Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits
一份好的计划能让实现变得一目了然。