Back to Details

writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

编写计划

Writing a Plan

概述

Overview

编写全面的实施计划，假设工程师对我们的代码库一无所知且品味堪忧。记录他们需要知道的一切：每个任务要接触哪些文件、代码、测试、可能需要检查的文档、如何测试。将整个计划分解为小任务。DRY。YAGNI。TDD。
假设他们是一位熟练的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太了解良好的测试设计。
开始时声明： "我正在使用 writing-plans 技能来创建实施计划。"
保存计划到： 
docs/plans/YYYY-MM-DD-<feature-name>.md
Write a comprehensive implementation plan assuming the engineer knows nothing about our codebase and has poor taste. Document everything they need to know: which files, code, tests, documentation they might need to check for each task, and how to test. Break down the entire plan into small tasks. DRY. YAGNI. TDD.
Assume they are a skilled developer but know little about our toolset or problem domain. Assume they have limited knowledge of good test design.
Start with this statement: "I am using the writing-plans skill to create an implementation plan."
Save the plan to: 
docs/plans/YYYY-MM-DD-<feature-name>.md

范围检查

Scope Check

如果规范涵盖多个独立的子系统，它应该在头脑风暴阶段被拆分为子项目规范。如果没有，建议将其拆分为独立的计划——每个子系统一个计划。每个计划都应该独立产出可运行、可测试的软件。
If the specification covers multiple independent subsystems, it should be split into sub-project specifications during the brainstorming phase. If not, suggest splitting it into independent plans—one plan per subsystem. Each plan should independently produce runnable, testable software.

文件结构

File Structure

在定义任务之前，先规划将要创建或修改哪些文件，以及每个文件负责什么。这是分解决策被确定的地方。
  • 设计具有清晰边界和明确定义接口的单元。每个文件应该有一个清晰的责任。
  • 你能一次性在脑海中容纳的代码，你的推理效果就最好；文件越聚焦，你的编辑就越可靠。优先选择小而聚焦的文件，而不是做太多事情的大文件。
  • 一起变化的文件应该放在一起。按责任拆分，而不是按技术层拆分。
  • 在现有代码库中，遵循已建立的模式。如果代码库使用大文件，不要单方面重组——但如果你正在修改的文件已经变得难以管理，在计划中包含拆分是合理的。
这个结构指导任务分解。每个任务都应该产生独立的、有意义的自包含变更。
Before defining tasks, plan which files will be created or modified, and what each file is responsible for. This is where decomposition decisions are made.
  • Design units with clear boundaries and well-defined interfaces. Each file should have a single, clear responsibility.
  • You reason best about code you can hold in your head at once; the more focused a file is, the more reliable your edits will be. Prefer small, focused files over large files that do too many things.
  • Files that change together should be kept together. Split by responsibility, not by technical layer.
  • In an existing codebase, follow established patterns. If the codebase uses large files, do not unilaterally restructure it—but if the file you're modifying has become unmanageable, it's reasonable to include splitting it in the plan.
This structure guides task decomposition. Each task should produce an independent, meaningful, self-contained change.

小任务粒度

Task Granularity

每个步骤是一个动作（2-5 分钟）：
  • "编写失败的测试" - 步骤
  • "运行它以确保失败" - 步骤
  • "实现最小代码使测试通过" - 步骤
  • "运行测试并确保它们通过" - 步骤
Each step is an action (2-5 minutes):
  • "Write a failing test" - Step
  • "Run it to ensure it fails" - Step
  • "Implement minimal code to make the test pass" - Step
  • "Run the tests and ensure they pass" - Step

计划文档头部

Plan Document Header

每个计划必须以这个头部开始：
markdown
undefined
Every plan must start with this header:
markdown
undefined

[功能名称] 实施计划

[Feature Name] Implementation Plan

目标： [一句话描述构建的内容]
架构： [关于方法的 2-3 句话]
技术栈： [关键技术/库]
undefined
Goal: [One-sentence description of what's being built]
Architecture: [2-3 sentences about the approach]
Tech Stack: [Key technologies/libraries]
undefined

任务结构

Task Structure

markdown
undefined
markdown
undefined

任务 N: [组件名称]

Task N: [Component Name]

文件：
  • 创建: 
    exact/path/to/file.py
  • 修改: 
    exact/path/to/existing.py:123-145
  • 测试: 
    tests/exact/path/to/test.py
  • 步骤 1: 编写失败的测试
python
def test_specific_behavior():
    result = function(input)
    assert result == expected
  • 步骤 2: 运行测试以验证失败
运行: 
pytest tests/path/test.py::test_name -v
预期: 失败，显示 "function not defined"
  • 步骤 3: 编写最小实现
python
def function(input):
    return expected
  • 步骤 4: 运行测试以验证通过
运行: 
pytest tests/path/test.py::test_name -v
预期: 通过
undefined
Files:
  • Create: 
    exact/path/to/file.py
  • Modify: 
    exact/path/to/existing.py:123-145
  • Test: 
    tests/exact/path/to/test.py
  • Step 1: Write a failing test
python
def test_specific_behavior():
    result = function(input)
    assert result == expected
  • Step 2: Run the test to verify failure
Run: 
pytest tests/path/test.py::test_name -v
Expected: Fails with "function not defined"
  • Step 3: Write the minimal implementation
python
def function(input):
    return expected
  • Step 4: Run the test to verify pass
Run: 
pytest tests/path/test.py::test_name -v
Expected: Passes
undefined

记住

Remember

  • 始终使用精确的文件路径
  • 计划中包含完整代码（而不是"添加验证"）
  • 精确的命令和预期输出
  • 使用 @ 语法引用相关技能
  • DRY、YAGNI、TDD
  • Always use exact file paths
  • Include full code in the plan (instead of "add validation")
  • Exact commands and expected output
  • Use @ syntax to reference related skills
  • DRY, YAGNI, TDD

计划审查循环

Plan Review Loop

完成计划的每个块后：
  1. 分派计划文档审查子代理（参见 plan-document-reviewer-prompt.md），并提供精心制作的审查上下文——绝不是你的会话历史。这能让审查者专注于计划本身，而不是你的思考过程。
    • 提供：块内容、规范文档路径
  2. 如果发现 ❌ 问题：
    • 修复该块中的问题
    • 重新分派审查者审查该块
    • 重复直到 ✅ 批准
  3. 如果 ✅ 批准：继续下一个块（如果是最后一个块，则进入执行交接）
块边界： 使用 
## Chunk N: <name>
标题来界定块。每个块应 ≤1000 行且逻辑上自包含。
审查循环指导：
  • 编写计划的同一个代理修复它（保留上下文）
  • 如果循环超过 5 次迭代，向人类寻求指导
  • 审查者是顾问——如果你认为反馈不正确，解释你的分歧
After completing each chunk of the plan:
  1. Dispatch the plan document review sub-agent (see plan-document-reviewer-prompt.md) with carefully crafted review context—never your conversation history. This keeps the reviewer focused on the plan itself, not your thought process.
    • Provide: Chunk content, specification document path
  2. If ❌ issues are found:
    • Fix the issues in the chunk
    • Re-dispatch the reviewer to review the chunk
    • Repeat until ✅ approved
  3. If ✅ approved: Proceed to the next chunk (if it's the last chunk, move to execution handoff)
Chunk Boundaries: Use 
## Chunk N: <name>
headers to define chunks. Each chunk should be ≤1000 lines and logically self-contained.
Review Loop Guidelines:
  • The same agent that wrote the plan fixes it (retains context)
  • If the loop exceeds 5 iterations, seek guidance from a human
  • The reviewer is an advisor—if you disagree with feedback, explain your reasoning

执行交接

Execution Handoff

保存计划后：
"计划已完成并保存到 
docs/plans/<filename>.md
。准备执行？"
After saving the plan:
"Plan completed and saved to 
docs/plans/<filename>.md
. Ready for execution?"