implementation-plan-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Plan Best Practices

实施计划最佳实践

Proven best practices for creating implementation plans that prevent drift and maintain alignment with project standards.

创建可防止偏差、保持与项目标准一致的实施计划的经过验证的最佳实践。

Core Principle

核心原则

Models optimize locally; enforce global constraints with layered verification (prompt → IDE → commit → CI → runtime).

模型会进行局部优化；通过分层验证（prompt → IDE → 提交 → CI → 运行时）来强制执行全局约束。

1. Style Anchors

1. 风格锚点

Always include 2-3 exemplary files as templates in prompts
Reference exact paths and line numbers (e.g.,
```
src/auth/login.ts:45-78
```
)
Prefer concrete repository examples with code + tests + README

Example:

examples/style-anchor/pkg/greeter/greeter.go

(code),

greeter_test.go

(tests),

README.md

(docs)

Place anchors early in task instructions to prevent architectural drift

Template:

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-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. Task Sizing

2. 任务规模规划

Target duration: 30-150 minutes (0.5-2.5 hours)
File scope: 1-3 files per task (max 5 with justification)
Splitting strategy: tests + scaffolding → minimal implementation → refactor & polish
Commit after each small task; revert immediately on drift
If task <30m, document rationale or split it

Examples:

Small: Fix bug in
```
src/utils/parse.ts
```
— 30-60 mins
Medium: Add API endpoint
```
src/server/user.ts
```
with tests — 90-150 mins
Large: Migrate auth system — Split into design + 3-5 incremental tasks

目标时长： 30-150分钟（0.5-2.5小时）
文件范围： 每个任务1-3个文件（最多5个需提供理由）
拆分策略： 测试+脚手架搭建 → 最小化实现 → 重构与优化
完成每个小任务后提交；一旦出现偏差立即回滚
若任务时长<30分钟，需记录理由或拆分任务

示例：

小型：修复
```
src/utils/parse.ts
```
中的bug —— 30-60分钟
中型：为
```
src/server/user.ts
```
添加带测试的API端点 —— 90-150分钟
大型：迁移认证系统 —— 拆分为设计阶段+3-5个增量任务

3. Affirmative Instructions

3. 肯定式指令

State permitted actions explicitly (e.g.,

ONLY use: cobra, go-playground/validator, sqlite

)

Avoid negative framing ("Don't use X" → "ONLY use: Y, Z")

Specify exact file scopes:

Touch ONLY: src/api/handlers/user.ts, user.test.ts

明确说明允许的操作（例如：

ONLY use: cobra, go-playground/validator, sqlite

）

避免否定表述（将"Don't use X"改为"ONLY use: Y, Z"）

指定精确的文件范围：

Touch ONLY: src/api/handlers/user.ts, user.test.ts

4. Tiered Rules

4. 分层规则

Global: User prefs (format, language, length)
Project: Persistent rules in
```
CLAUDE.md
```
or
```
.cursor/rules/
```
(loaded every session)
Context-aware: Auto-attached rules per directory or file pattern

全局层： 用户偏好（格式、语言、长度）
项目层： 存储在
```
CLAUDE.md
```
或
```
.cursor/rules/
```
中的持久化规则（每次会话加载）
上下文感知层： 按目录或文件模式自动附加的规则

5. TDD as Anchor

5. 以TDD为锚点

Require TDD checklist: tests → minimal code → more tests → refactor
When tests fail: "Revise implementation to pass this test while keeping all previously passing tests. Do not modify the test. Do not add dependencies."
Include explicit validation commands:

bash

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

要求遵循TDD检查清单：编写测试 → 最小化代码实现 → 补充测试 → 重构
测试失败时："修改实现以通过测试，同时保持所有之前通过的测试正常运行。请勿修改测试。请勿添加依赖。"
包含明确的验证命令：

bash

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

6. Prompt Positioning

6. 提示语布局

Put critical specs, style anchors, and hard rules at the beginning
Reiterate them at the end of prompts
Avoid burying requirements in the middle

将关键规格、风格锚点和硬性规则放在开头
在提示语结尾再次重申
避免将要求隐藏在中间部分

7. Model Strategies

7. 模型策略

Claude: Use for surgical, minimal-diff edits; request

research → plan → implement

minimal diff, no renames, explain each edit

; use thinking triggers (

think

think hard

ultrathink

)

GPT: Use for exploratory/greenfield work and code review; ask for tactical plans and side-effect checks

Claude： 用于精准、最小差异的编辑；请求按
```
research → plan → implement
```
流程执行，要求
```
minimal diff, no renames, explain each edit
```
；使用思考触发词（
```
think
```
,
```
think hard
```
,
```
ultrathink
```
）
GPT： 用于探索性/全新项目开发和代码审查；要求提供战术计划和副作用检查

8. Self-Consistency & AI-on-AI Review

8. 自一致性与AI互查

Generate 3+ implementations (higher temperature), then ask model to pick most consistent
Use multi-model review (e.g., Claude writes, GPT/Gemini reviews) to catch subtle issues

生成3种以上实现方案（更高温度参数），然后让模型选择最符合一致性的方案
使用多模型审查（例如Claude编写，GPT/Gemini审查）以发现细微问题

9. Drift Handling

9. 偏差处理

Stop & revert immediately if:

New dependencies introduced (not in allowed list)
Files touched outside specified targets (>3 unexpected files)
Linting/type errors cannot be resolved within task scope
Tests fail and model proposes changing tests instead of implementation

Immediate actions:

Stop the session
Revert to pre-task state (only if changes produced by agent in this session)
Create incident note in
```
docs/drift-incidents/
```
with:
- What happened
- Files changed unexpectedly
- New dependencies proposed
- Remediation steps

Allowed deviations:

Minor formatting (editorconfig)
Whitespace-only edits
Single-line refactors within scope and type-checked

Recording learnings:

Update
```
.cursor/rules/
```
or
```
CLAUDE.md
```
with new rules after each session
Add to style anchors if new pattern discovered

出现以下情况立即停止并回滚：

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

立即执行的操作：

停止会话
回滚到任务前状态（仅限本次会话中Agent产生的更改）
在
```
docs/drift-incidents/
```
中创建事件记录，包含：
- 发生的问题
- 意外修改的文件
- 提议添加的新依赖
- 补救步骤

允许的偏差：

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

经验记录：

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

10. Quality Gates

10. 质量关卡

Pre-commit:

```
make lint
```
with zero warnings
```
make test
```
with all tests passing
```
make typecheck
```
with zero errors

CI gates:

Count violations (gofmt, lint, typecheck) and fail if threshold exceeded
Run tests with race detection (e.g.,
```
go test -race
```
)

Per-task validation:

yaml

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

提交前：

执行
```
make lint
```
且零警告
执行
```
make test
```
且所有测试通过
执行
```
make typecheck
```
且零错误

CI关卡：

统计违规情况（gofmt、lint、类型检查），超过阈值则失败
运行带竞争检测的测试（例如：
```
go test -race
```
）

单任务验证：

yaml

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. Layered Verification

11. 分层验证

Prompt level: Explicit constraints, style anchors, task sizing
IDE level: Linting, type checking, auto-formatting
Commit level: Pre-commit hooks, validation scripts
CI level: Quality gates, test suites, coverage thresholds
Runtime level: Input validation, proper error handling, monitoring

提示语层： 明确约束、风格锚点、任务规模
IDE层： 代码检查、类型校验、自动格式化
提交层： 提交前钩子、验证脚本
CI层： 质量关卡、测试套件、覆盖率阈值
运行时层： 输入验证、正确的错误处理、监控

12. Key Learnings from Milestone 0

12. 里程碑0的关键经验

Make templates explicit vs concrete: Include all schema-required top-level fields to avoid validation failures
Enforce concrete style anchors early: Include 2-3 concrete anchors (code + tests + README) on every planning task
Mark inferred edits: Use
```
assumption: true
```
with rationale for any inferred additions
Respect task-sizing constraints: Enforce 30-150m task estimates; split shorter tasks with rationale
Keep validation inline: Add
```
validation
```
summary with
```
quality_score
```
,
```
issues
```
, and
```
approval
```
Prefer concrete execution snippets: Add explicit validator commands in
```
instructions
```
Scope implementation rules: Keep implementation-only pattern checks scoped with
```
when: implementation_phase
```
Use repository examples as anchors: Small, well-scoped examples are high-leverage anchors

模板需明确具体： 包含所有 schema 要求的顶级字段，避免验证失败
尽早强制执行具体风格锚点： 在每个规划任务中包含2-3个具体锚点（代码+测试+README）
标记推断性编辑： 对任何推断添加的内容使用
```
assumption: true
```
并说明理由
遵守任务规模约束： 强制执行30-150分钟的任务估算；对更短的任务拆分并说明理由
保持验证内联： 添加包含
```
quality_score
```
、
```
issues
```
和
```
approval
```
的
```
validation
```
摘要
优先选择具体执行片段： 在
```
instructions
```
中添加明确的验证器命令
限定实现规则范围： 使用
```
when: implementation_phase
```
限定仅实现阶段的模式检查
使用仓库示例作为锚点： 小型、范围明确的示例是高效的锚点

Task Template Example

任务模板示例

yaml

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

yaml

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

Quick Practical Checklist

快速实用检查清单

When creating implementation plans:

Create
```
CLAUDE.md
```
or
```
.cursor/rules/
```
with prompt-level rules
Add 2-3 concrete style anchors to prompts (prefer repository examples)
Rescope tasks to 30m-2.5h and commit per task
Convert negative constraints to affirmative instructions
Enforce linting zero-warnings, pre-commit hooks, and CI gates
Require TDD plans and tests before making changes
Use proper error handling for runtime validation
Include all schema-required fields in generated YAML
Mark inferred additions with
```
assumption: true
```
and rationale
Place critical constraints at beginning AND end of prompts

创建实施计划时：

创建包含提示语层规则的
```
CLAUDE.md
```
或
```
.cursor/rules/
```
在提示语中添加2-3个具体风格锚点（优先选择仓库示例）
将任务调整为30分钟-2.5小时的规模，每个任务完成后提交
将否定约束转换为肯定式指令
强制执行零警告lint检查、提交前钩子和CI关卡
要求在修改前制定TDD计划并编写测试
为运行时验证使用正确的错误处理
在生成的YAML中包含所有schema要求的字段
对推断添加的内容标记
```
assumption: true
```
并说明理由
将关键约束放在提示语的开头和结尾

Common Anti-Patterns

常见反模式

Anti-Pattern	Problem	Fix
No style anchors	Model introduces inconsistent patterns	Add 2-3 concrete examples with line numbers
Tasks >2.5 hours	Difficult to review, easy to drift	Split into tests + implementation + refactor
Negative framing	"Don't use X" is harder to follow	"ONLY use: Y, Z"
Buried rules	Model misses important constraints	Put at beginning AND end
No validation commands	Unclear when task is complete	Include explicit lint/test/typecheck commands
Allowing test modification	Tests weakened to pass implementation	"Revise implementation, not tests"
No drift policy	Small drifts compound	Explicit stop criteria and revert process
No commit checkpoints	Large uncommitted changes hard to debug	Commit after each task

反模式	问题	修复方案
无风格锚点	模型引入不一致模式	添加2-3个带行号的具体示例
任务时长>2.5小时	难以审查，容易出现偏差	拆分为测试+实现+重构阶段
否定表述	"Don't use X"更难遵循	改为"ONLY use: Y, Z"
规则隐藏	模型遗漏重要约束	将规则放在开头和结尾
无验证命令	不清楚任务何时完成	包含明确的lint/测试/类型检查命令
允许修改测试	为适配实现而弱化测试	要求"修改实现，而非测试"
无偏差处理策略	小偏差逐渐累积	明确停止标准和回滚流程
无提交检查点	未提交的大型变更难以调试	每个任务完成后提交

Integration with Other Skills

与其他技能的集成

implementation-planner: Apply these practices when generating plans
implementation-plan-review: Validate plans against these practices
business-requirements-interview: Ensure requirements align with these practices
technical-requirements-interview: Technical specs should follow these practices

implementation-planner： 生成计划时应用这些实践
implementation-plan-review： 对照这些实践验证计划
business-requirements-interview： 确保需求与这些实践对齐
technical-requirements-interview： 技术规格应遵循这些实践

Examples

示例

See

examples/

directory for:

Well-structured task with all best practices applied
Before/after examples showing improvements
Common mistakes and how to fix them

查看

examples/

目录获取：

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