writing-plans

编写计划

核心原则

编写计划时，应确保一位热情但品味不佳、判断力不足、缺乏项目背景且厌恶测试的初级工程师也能按计划执行。

计划结构

将计划保存到：docs/plans/YYYY-MM-DD-<feature-name>.md

# [Feature Name] Implementation Plan

> **For Claude:** Use executing-plans skill to implement this plan task-by-task.

## Overview
Brief description of what we're building and why.

## Prerequisites
- [ ] Dependency 1 installed
- [ ] Service 2 running
- [ ] Access to X configured

## Tasks

### Task 1: [Descriptive Name]
**File:** `path/to/file.ts`
**Test:** `path/to/file.test.ts`

#### Test First (RED)
```typescript
// Exact test code to write
describe('FeatureName', () => {
  it('should do specific thing', () => {
    // Arrange
    // Act  
    // Assert
  });
});

实现（GREEN）

// Exact implementation code
export function featureName() {
  // Implementation
}

验证

npm test -- --grep "FeatureName"
# Expected: 1 passing

任务 2：[下一项任务]

...

集成测试

所有任务完成后：

# Commands to run
npm run test:integration

手动验证

手动验证功能正常运行的步骤：

1. 步骤 1
2. 步骤 2
3. 预期结果

回滚计划

如果出现问题：

1. git revert HEAD
2. ...

## 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"

### Be Complete
❌ "Update the config"
✅ ```json
{
  "setting": "value",
  "newSetting": "newValue"
}

按顺序执行

任务应能按顺序执行：

1. 不存在前向依赖
2. 每项任务都基于前一项任务
3. 每项任务完成后测试都能通过

执行交接

保存计划后，提供执行方式选项：

“计划已完成并保存。有两种执行方式：

1. 子 Agent 驱动（本次会话）

• 每项任务使用一个全新的子 Agent
• 在任务之间进行审查
• 快速迭代

2. 并行会话（独立会话）

• 使用 executing-plans skill 开启新会话
• 分批执行并设置检查点

选择哪种方式？”

DRY、YAGNI、TDD 提醒

在每份计划的开头加入：

## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- DRY, YAGNI, TDD, frequent commits

反模式

不要这样做

• 任务描述含糊
• 缺少文件路径
• 代码片段不完整
• 先实现再编写测试
• 没有验证步骤
• 假设读者了解背景