跳到主要内容

Plan

Plan 模式:将一份可执行的 markdown 计划写入 .kopi/plans/,不执行任何操作。任务拆分为小块、路径精确、代码完整。

Skill 元数据​

SourceBundled(默认安装)
Pathskills/software-development/plan
Version2.0.0
AuthorKOPI AI AGENT(writing-craft 改编自 obra/superpowers)
LicenseMIT
Platformslinux, macos, windows
Tagsplanning, plan-mode, implementation, workflow, design, documentation
Related skillssubagent-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:编写任务​

按顺序创建任务:

  1. 设置/基础设施
  2. 核心功能(每个都采用 TDD)
  3. 边界情况
  4. 集成
  5. 清理/文档

步骤 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 周期:

  1. 编写失败的测试
  2. 运行以验证测试失败
  3. 编写最简代码
  4. 运行以验证测试通过

详情请参见 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

一份好的计划能让实现变得一目了然。