Back to Details

writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Plans

编写实施计划

Core Principle

核心原则

Write plans clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow.
编写的计划要足够清晰，即使是一个审美差、缺乏判断力、不了解项目背景且讨厌测试的热情初级工程师也能遵循。

Plan Structure

计划结构

Save plans to: 
docs/plans/YYYY-MM-DD-<feature-name>.md
markdown
undefined
将计划保存至：
docs/plans/YYYY-MM-DD-<feature-name>.md
markdown
undefined

[Feature Name] Implementation Plan

[功能名称] 实施计划

For Claude: Use executing-plans skill to implement this plan task-by-task.
致Claude： 使用executing-plans技能逐项执行本计划任务。

Overview

概述

Brief description of what we're building and why.
简要说明我们要构建的内容及原因。

Prerequisites

前置条件

  • Dependency 1 installed
  • Service 2 running
  • Access to X configured
  • 已安装依赖1
  • 服务2已启动
  • 已配置X的访问权限

Tasks

任务

Task 1: [Descriptive Name]

任务1：[描述性名称]

File: 
path/to/file.ts
Test: 
path/to/file.test.ts
文件： 
path/to/file.ts
测试： 
path/to/file.test.ts

Test First (RED)

先写测试（RED阶段）

typescript
// Exact test code to write
describe('FeatureName', () => {
  it('should do specific thing', () => {
    // Arrange
    // Act  
    // Assert
  });
});
typescript
// 要编写的完整测试代码
describe('FeatureName', () => {
  it('should do specific thing', () => {
    // 准备
    // 执行  
    // 断言
  });
});

Implementation (GREEN)

代码实现（GREEN阶段）

typescript
// Exact implementation code
export function featureName() {
  // Implementation
}
typescript
// 完整的实现代码
export function featureName() {
  // 实现逻辑
}

Verification

验证

bash
npm test -- --grep "FeatureName"
bash
npm test -- --grep "FeatureName"

Expected: 1 passing

预期结果：1个测试通过

undefined
undefined

Task 2: [Next Task]

任务2：[下一任务]

...
...

Integration Tests

集成测试

After all tasks complete:
bash
undefined
所有任务完成后执行：
bash
undefined

Commands to run

要运行的命令

npm run test:integration
undefined
npm run test:integration
undefined

Manual Verification

手动验证

Steps to manually verify the feature works:
  1. Step 1
  2. Step 2
  3. Expected result
手动验证功能正常的步骤：
  1. 步骤1
  2. 步骤2
  3. 预期结果

Rollback Plan

回滚计划

If something goes wrong:
  1. git revert HEAD
  2. ...
undefined
若出现问题：
  1. git revert HEAD
  2. ...
undefined

Plan Quality Checklist

计划质量检查清单

Every Task Must Have:

每个任务必须包含：

  • Exact file paths
  • Complete code (not "add validation")
  • Test written BEFORE implementation
  • Verification command with expected output
  • Clear success criteria
  • 明确的文件路径
  • 完整的代码（而非“添加验证”这类模糊描述）
  • 先于实现编写测试
  • 带有预期输出的验证命令
  • 清晰的成功标准

Plan Must Include:

计划必须包含：

  • Prerequisites listed
  • Tasks in dependency order
  • Integration test at end
  • Rollback instructions
  • 列出前置条件
  • 按依赖顺序排列的任务
  • 末尾的集成测试
  • 回滚说明

Writing Guidelines

编写指南

Be Explicit

表述明确

❌ "Add error handling" ✅ "Wrap the API call in try/catch, log errors with context, return null on failure"
❌ “添加错误处理” ✅ “将API调用包裹在try/catch中，附带上下文日志错误，失败时返回null”

Be Complete

内容完整

❌ "Update the config" ✅ ```json { "setting": "value", "newSetting": "newValue" }
undefined
❌ “更新配置” ✅ ```json { "setting": "value", "newSetting": "newValue" }
undefined

Be Ordered

顺序合理

Tasks should be executable in sequence:
  1. No forward dependencies
  2. Each task builds on previous
  3. Tests pass after each task
任务应可按顺序执行：
  1. 无前置依赖问题
  2. 每个任务基于前序任务构建
  3. 每个任务完成后测试均可通过

Execution Handoff

执行交接

After saving the plan, offer execution choice:
"Plan complete and saved. Two execution options:
1. Subagent-Driven (this session)
  • Fresh subagent per task
  • Review between tasks
  • Fast iteration
2. Parallel Session (separate)
  • Open new session with executing-plans skill
  • Batch execution with checkpoints
Which approach?"
保存计划后，提供执行选项：
“计划已完成并保存。有两种执行方式：
1. 子Agent驱动（本次会话）
  • 每个任务分配新的子Agent
  • 任务间进行评审
  • 迭代速度快
2. 并行会话（独立进行）
  • 开启新会话并使用executing-plans技能
  • 批量执行并设置检查点
选择哪种方式？"

DRY, YAGNI, TDD Reminders

DRY、YAGNI、TDD 提醒

Include at top of every plan:
markdown
undefined
在每个计划顶部添加：
markdown
undefined

Remember

注意事项

  • Exact file paths always
  • Complete code in plan (not "add validation")
  • Exact commands with expected output
  • DRY, YAGNI, TDD, frequent commits
undefined
  • 始终使用明确的文件路径
  • 计划中包含完整代码（而非“添加验证”这类模糊描述）
  • 带有预期输出的明确命令
  • 遵循DRY、YAGNI、TDD原则，频繁提交代码
undefined

Anti-Patterns

反模式

Don't Do This

请勿这样做

  • Vague task descriptions
  • Missing file paths
  • Incomplete code snippets
  • Implementation before tests
  • No verification steps
  • Assuming context
  • 模糊的任务描述
  • 缺失文件路径
  • 不完整的代码片段
  • 先实现后写测试
  • 无验证步骤
  • 假设开发者了解项目背景