implementation-plan-best-practices

实施计划最佳实践

经实践验证的最佳实践，可用于制定实施计划，避免偏离方向并确保与项目标准保持一致。

核心原则

模型会在局部进行优化；应通过分层验证（提示词 → IDE → 提交 → CI → 运行时）来确保全局约束。

1. 风格锚点

• 始终在提示词中包含 2-3 个示范文件作为模板
• 引用确切的路径和行号（例如 src/auth/login.ts:45-78）
• 优先采用包含代码、测试和 README 的具体仓库示例
• 示例：examples/style-anchor/pkg/greeter/greeter.go（代码）、greeter_test.go（测试）、README.md（文档）
• 在任务说明开头放置锚点，以避免架构偏离

模板：

Style Anchors:
- src/auth/login.ts:45-78 (authentication pattern with proper error handling)
- src/auth/login.test.ts:12-34 (test structure for auth flows)
- src/middleware/validation.ts:15-30 (input validation pattern)

2. 任务规模

• 目标时长： 30-150 分钟（0.5-2.5 小时）
• 文件范围： 每项任务 1-3 个文件（最多 5 个，需说明理由）
• 拆分策略： 测试 + 脚手架 → 最小化实现 → 重构与完善
• 每完成一项小任务就提交；一旦偏离，立即还原
• 如果任务少于 30 分钟，应记录理由或拆分任务

示例：

• 小型：修复 src/utils/parse.ts 中的 bug — 30-60 分钟
• 中型：新增 API 端点 src/server/user.ts 并编写测试 — 90-150 分钟
• 大型：迁移认证系统 — 拆分为设计阶段 + 3-5 项渐进式任务

3. 正向指令

• 明确说明允许执行的操作（例如，ONLY use: cobra, go-playground/validator, sqlite）
• 避免使用否定表述（“不要使用 X” → “ONLY use: Y, Z”）
• 指定确切的文件范围：Touch ONLY: src/api/handlers/user.ts, user.test.ts

4. 分层规则

• 全局： 用户偏好（格式、语言、长度）
• 项目： CLAUDE.md 或 .cursor/rules/ 中的持久规则（每个会话都会加载）
• 上下文感知： 根据目录或文件模式自动附加的规则

5. 以 TDD 为锚点

• 要求遵循 TDD 清单：测试 → 最小化代码 → 更多测试 → 重构
• 测试失败时：“修改实现，使其通过此测试，同时确保所有之前通过的测试仍然通过。不要修改测试。不要添加依赖项。”
• 包含明确的验证命令：

npm test src/auth/login.test.ts
go test ./pkg/auth -v
pytest tests/test_auth.py -v

6. 提示词布局

• 将关键规格、风格锚点和硬性规则放在开头
• 在提示词结尾重申这些内容
• 避免将要求埋在中间

7. 模型策略

• Claude： 用于精准、最小差异的编辑；要求按 research → plan → implement 执行，并遵循 minimal diff, no renames, explain each edit；使用思考触发词（think、think hard、ultrathink）
• GPT： 用于探索性工作、从零开始的工作和代码审查；要求制定战术计划并检查副作用

8. 自我一致性与 AI 对 AI 审查

• 生成 3 个或更多实现（使用较高温度），然后让模型选出最一致的方案
• 使用多模型审查（例如 Claude 编写，GPT/Gemini 审查），以发现细微问题

9. 偏离处理

出现以下情况时，立即停止并还原：

• 引入了不在允许列表中的新依赖项
• 修改了指定目标之外的文件（超过 3 个意外文件）
• 无法在任务范围内解决 lint 或类型错误
• 测试失败，且模型提议修改测试而非实现

立即采取以下措施：

1. 停止会话
2. 还原到任务开始前的状态（仅限本会话中由 Agent 产生的更改）
3. 在 docs/drift-incidents/ 中创建事件记录，包含：
   • 发生了什么
   • 意外修改的文件
   • 提议的新依赖项
   • 补救步骤

允许的偏差：

• 轻微格式调整（editorconfig）
• 仅涉及空白字符的编辑
• 范围内且已通过类型检查的单行重构

记录经验：

• 每次会话后，将新规则更新到 .cursor/rules/ 或 CLAUDE.md
• 如果发现新的模式，将其添加到风格锚点中

10. 质量门禁

提交前：

• 执行 make lint，确保没有警告
• 执行 make test，确保所有测试通过
• 执行 make typecheck，确保没有错误

CI 门禁：

• 统计违规项（gofmt、lint、typecheck），超出阈值则失败
• 运行带竞态检测的测试（例如，go test -race）

每项任务的验证：

validation:
  commands:
    - npm run lint
    - npm test src/[module].test.ts
    - npm run typecheck
  expected_output: "All tests passing, 0 lint errors"
  failure_handling: "STOP and report. Do not continue to next task."

11. 分层验证

1. 提示词级别： 明确约束、风格锚点、任务规模
2. IDE 级别： Lint、类型检查、自动格式化
3. 提交级别： 提交前钩子、验证脚本
4. CI 级别： 质量门禁、测试套件、覆盖率阈值
5. 运行时级别： 输入验证、妥善的错误处理、监控

12. 里程碑 0 的主要经验

• 明确指定模板，而非具体实现： 包含架构要求的所有顶层字段，避免验证失败
• 尽早设定具体的风格锚点： 每项规划任务都包含 2-3 个具体锚点（代码 + 测试 + README）
• 标记推断出的修改： 对任何推断出的新增内容，使用 assumption: true 并说明理由
• 遵守任务规模约束： 将任务估时控制在 30-150 分钟；对于更短的任务，说明理由后拆分
• 内联验证信息： 添加包含 quality_score、issues 和 approval 的 validation 摘要
• 优先使用具体的执行片段： 在 instructions 中添加明确的验证器命令
• 限定实现规则的适用范围： 将仅适用于实现阶段的模式检查限定为 when: implementation_phase
• 以仓库示例作为锚点： 小巧且范围明确的示例是高效的锚点

任务模板示例

task:
  id: t-auth-001
  name: "Add login endpoint with JWT validation"
  estimate_minutes: 90

  files:
    touch_only: [src/api/handlers/auth.ts, src/api/handlers/auth.test.ts]
    modify_only: [src/api/routes.ts]

  style_anchors:
    - {path: src/api/handlers/user.ts, lines: 45-78, pattern: "Handler with proper error handling"}
    - {path: src/api/handlers/user.test.ts, lines: 12-45, pattern: "Test structure for API handlers"}

  constraints:
    dependencies:
      only_use: [jsonwebtoken, express-validator]
    file_scope:
      max_files: 3
      stop_if_exceeded: true

  instructions: |
    ## CRITICAL CONSTRAINTS
    - ONLY modify files listed above
    - ONLY use dependencies: jsonwebtoken, express-validator
    - MUST pass: npm test, npm run lint

    ## Style Anchors
    See src/api/handlers/user.ts:45-78 for handler pattern
    See src/api/handlers/user.test.ts:12-45 for test structure

    ## TDD Checklist
    - [ ] Write failing test for POST /auth/login
    - [ ] Implement minimal handler to pass
    - [ ] Add tests for edge cases
    - [ ] Refactor for clarity

    ## Drift Policy
    STOP if: files touched >3, new dependencies, tests fail

    ## Validation
    npm test src/api/handlers/auth.test.ts && npm run lint && npm run typecheck

  validation:
    commands: [npm test src/api/handlers/auth.test.ts, npm run lint, npm run typecheck]
    expected_output: "All tests passing, 0 errors"
    failure_handling: "STOP. Revise implementation to pass tests."

快速实用检查清单

创建实现计划时：

1. 创建 CLAUDE.md 或 .cursor/rules/，添加提示词级别的规则
2. 在提示词中添加 2-3 个具体的风格锚点（优先使用仓库示例）
3. 将任务重新调整为 30 分钟至 2.5 小时，并逐项提交
4. 将否定式约束改为肯定式指令
5. 强制执行零警告 lint、提交前钩子和 CI 门禁
6. 要求制定 TDD 计划，并在修改前编写测试
7. 在运行时验证中使用恰当的错误处理
8. 在生成的 YAML 中包含架构要求的所有字段
9. 对推断出的新增内容标记 assumption: true 并说明理由
10. 将关键约束放在提示词的开头和结尾

常见反模式

反模式	问题	修正方法
没有风格锚点	模型引入不一致的模式	添加 2-3 个带行号的具体示例
任务超过 2.5 小时	难以审查，也容易偏离方向	拆分为测试 + 实现 + 重构
否定式表述	“不要使用 X”更难遵循	“仅使用：Y、Z”
规则埋得太深	模型会漏掉重要约束	将规则放在开头和结尾
没有验证命令	不清楚任务何时完成	包含明确的 lint/test/typecheck 命令
允许修改测试	为了让实现通过而弱化测试	“修改实现，而不是测试”
没有偏移处理策略	微小偏移会不断累积	明确停止标准和回退流程
没有提交检查点	大量未提交的修改难以调试	每项任务完成后提交

与其他技能的集成

• implementation-planner： 生成计划时应用这些实践
• implementation-plan-review： 根据这些实践验证计划
• business-requirements-interview： 确保需求符合这些实践
• technical-requirements-interview： 技术规格应遵循这些实践

示例

请参阅 examples/ 目录，了解：

• 应用了所有最佳实践的结构良好的任务
• 展示改进效果的前后对比示例
• 常见错误及其修正方法