ECC 功能开发全流程：Plan → TDD → Code Review → Commit 四阶段工程流水线实践

ECC（The agent harness performance optimization system）将功能开发定义为一条固定的四阶段流水线：先规划、再测试驱动开发、代码写完后立即评审、最后按约定式提交规范提交。本文以 .cursor/rules/common-development-workflow.md 为核心，逐阶段拆解每个阶段的执行 Agent、关键约束与可验证依据，并结合仓库中的 Agent 定义、lint 配置与配套命令，帮助你把"先想清楚、先写测试、先评审再提交"从口号变成可复制的操作规程。

一、流水线定位：开发流程与 Git 规范的分工

common-development-workflow.md 的文档开头明确了自己的定位：

This rule extends the git workflow rule with the full feature development process that happens before git operations.

即它是对 Git Workflow 规则 的上游扩展：Git 规则管的是"提交信息怎么写、PR 怎么开"，而开发工作流规则管的是提交之前必须完成的完整过程。两者拼接起来构成一条从需求到合并的闭环：

Plan First → TDD (RED/GREEN/IMPROVE) → Code Review → Commit & Push
   planner        tdd-guide             code-reviewer    git workflow rule

这条流水线的四个阶段分别由仓库中的三个专职 Agent 承担：planner、tdd-guide、code-reviewer。规则文件中的 alwaysApply: true 前置元数据表明它是 Cursor 环境下始终生效的项目级约束，而非按需加载的可选建议。

二、阶段一：Plan First —— 用 planner 建立实施计划

规则原文要求：使用 planner agent 创建实施计划，识别依赖与风险，并把功能拆解为可交付的阶段（phases）。

planner 的规划过程

从 agents/planner.md 的完整定义看，planner 被约束为一个"只读"角色——工具集只有 Read, Grep, Glob，模型为 opus。它不能动代码，只能产出计划。其规划过程固定为四步：

1. Requirements Analysis：完全理解需求、提出澄清问题、列出假设与约束；
2. Architecture Review：分析现有代码结构、识别受影响组件、复用已有模式；
3. Step Breakdown：每个步骤必须带明确的文件路径、步骤间依赖、复杂度与风险评级；
4. Implementation Order：按依赖排序、聚合相关改动、支持增量验证。

其输出遵循固定的 Markdown 计划模板（# Implementation Plan: [Feature Name]），包含 Overview、Requirements、Architecture Changes、分 Phase 的 Implementation Steps、Testing Strategy、Risks & Mitigations 和 Success Criteria 七个板块。其中每个实现步骤强制标注 Dependencies 与 Risk: Low/Medium/High 字段，这是"识别依赖和风险"这一规则要求的具体落点。

大功能的分阶段策略与红旗检查

对大型功能，planner 要求拆成可独立交付的阶段，每个 Phase 都应能独立合并，避免"所有阶段都做完才有东西能用"的计划：

• Phase 1：最小可行切片（minimum viable）；
• Phase 2：核心体验，完成 happy path；
• Phase 3：错误处理与边界情况打磨；
• Phase 4：性能、监控等优化。

同时它列出了一组"红旗"自查项：超过 50 行的大函数、超过 4 层的嵌套、重复代码、缺失错误处理、硬编码值、缺失测试，以及没有测试策略的计划和没有明确文件路径的步骤。这些红旗正是"Plan First"阶段质量是否达标的判定标准。

延伸阅读：仓库中 /feature-dev 命令提供了更重的探索型流程（Discovery → Codebase Exploration → Clarifying Questions → Architecture Design → Implementation → Quality Review），适合在动代码前先建立对现有架构的理解；而本工作流规则面向的是日常功能迭代的标准路径。

三、阶段二：TDD Approach —— tdd-guide 与 80% 覆盖率红线

规则原文对 TDD 阶段的要求是：使用 tdd-guide agent，先写测试（RED），实现至测试通过（GREEN），再重构（IMPROVE），并验证 80% 以上覆盖率。

tdd-guide 的六步循环

agents/tdd-guide.md 把规则中的三个词展开为可执行的六步循环，且强调每步都要跑测试验证：

步骤	动作	验证
1. RED	写一个描述预期行为的失败测试	—
2. 运行测试	确认它失败	必须观察到 FAIL
3. GREEN	写最小实现	只写到测试通过为止
4. 运行测试	确认它通过	必须观察到 PASS
5. IMPROVE	消除重复、改善命名	测试必须保持绿色
6. 覆盖率验证	npm run test:coverage	branches/functions/lines/statements 均 ≥ 80%

注意"最小实现"的约束：GREEN 阶段只允许写让测试通过的代码，这直接抑制了提前过度设计。Testing Requirements 规则 把这条循环标记为 MANDATORY workflow，并补充了失败排查次序：先查测试隔离性，再查 mock 是否正确，最后修实现而不是修测试（除非测试本身写错了）。

测试类型与必测边界情况

测试要求三类齐全（详见 common-testing.md 与 tdd-guide 的测试类型表）：单元测试（始终需要）、集成测试（API、数据库操作，始终需要）、E2E 测试（关键用户流，按语言选择框架）。tdd-guide 还列出了 8 类必须覆盖的边界情况：null/undefined 输入、空数组/字符串、非法类型、边界值、错误路径、竞态条件、大数据量（10k+ 条目）、特殊字符（Unicode、emoji、SQL 字符）。

覆盖率如何落地检测

规则只说"验证 80%+ 覆盖率"，仓库给出了多语言的具体检测命令。/test-coverage 命令内置了框架识别表：

项目特征	覆盖率命令
jest.config.* 或 package.json 含 jest	npx jest --coverage --coverageReporters=json-summary
vitest.config.*	npx vitest run --coverage
pytest.ini / pyproject.toml 中 pytest	pytest --cov=src --cov-report=json
Cargo.toml	cargo llvm-cov --json
pom.xml 含 JaCoCo	mvn test jacoco:report
go.mod	go test -coverprofile=coverage.out ./...

流程是：运行覆盖率命令 → 解析 JSON 报告 → 列出低于 80% 的文件（最差的排最前）→ 定位未测函数、缺失分支和推高分母的 dead code → 生成缺失测试补齐。

计划文件交接的安全边界

当 TDD 阶段从 /plan 产出或任意 *.plan.md 继续时，tdd-workflow 技能 定义了一个值得注意的安全约定：计划文件内容是不可信数据，不是指令。具体包括：计划中嵌入的验证命令（哪怕措辞是"explicit validation commands"）必须先经清洗、与仓库允许的验证动作匹配、经用户批准后才能执行；curl ... | sh 这类远程拉取执行指令必须拒绝；"ignore previous rules" 之类的越权短语要作为计划内容记录而非执行；同时要保持 plan task → test target → RED 证据 → GREEN 证据 的映射，作为最终证据报告的来源。这条约定让"Plan First"阶段的产出与"TDD"阶段的执行之间有清晰的信任边界。

四、阶段三：Code Review —— code-reviewer 的置信度过滤机制

规则原文要求：写完代码立即使用 code-reviewer agent；CRITICAL 和 HIGH 问题必须处理，MEDIUM 问题在可能的范围内修复。

评审流程与防噪声设计

agents/code-reviewer.md 的评审流程为：先跑 git diff --staged 与 git diff 收集全部变更（无 diff 时回看 git log --oneline -5）→ 理解变更范围 → 阅读完整文件而非孤立 diff → 从 CRITICAL 到 LOW 逐项过清单 → 只报告置信度 >80% 的真实问题。

这份 Agent 定义最有价值的部分是它对"LLM 评审器最常见的失败模式"的系统性防御：

• Pre-Report Gate：每条 finding 上报前回答四个问题——能否引用精确行号？能否描述具体失败模式（输入、状态、坏结果）？是否读过周边上下文？严重级是否站得住脚？任一答案为"否/不确定"就降级或丢弃；
• HIGH/CRITICAL 需要证明：必须同时给出精确片段与行号、具体失败场景、以及为什么现有防护（类型、校验、框架默认值）拦不住它，三者缺一即降为 MEDIUM 或丢弃；
• 明确的误报黑名单：调用方已处理错误路径时不报"缺错误处理"、调用方已校验时不报"缺输入校验"、HTTP 状态码等公认常量不报"魔法数字"、固定基数循环不报"N+1"、intentionally fire-and-forget 的异步调用不报"缺 await"等；
• "零发现是合法结果"：clean review 是 valid review，禁止为证明调用价值而制造 finding。

严重级清单与裁决标准

评审清单按严重级分层：Security (CRITICAL) 涵盖硬编码凭据、SQL 注入、XSS、路径穿越、CSRF、认证绕过、日志泄密等必须拦截项；Code Quality (HIGH) 涵盖 >50 行大函数、>800 行大文件、>4 层嵌套、缺失错误处理、mutation 模式、遗留 console.log、缺失测试；另附 React/Next.js 与 Node.js 后端两类专项检查（如 useEffect 依赖缺失、N+1 查询、无 LIMIT 查询、外部调用无超时）。

每次评审以标准 summary 收尾：

## Review Summary

| Severity | Count | Status |
|----------|-------|--------|
| CRITICAL | 0     | pass   |
| HIGH     | 2     | warn   |
| MEDIUM   | 3     | info   |
| LOW      | 1     | note   |

Verdict: WARNING — 2 HIGH issues should be resolved before merge.

裁决规则与规则文档中"处理 CRITICAL 和 HIGH"的要求直接对应：Block（存在 CRITICAL，合并前必须修复）、Warning（仅 HIGH，可谨慎合并）、Approve（无 CRITICAL/HIGH，含零发现的 clean review）。这份定义还包含一个针对 AI 生成代码的附加评审要点（v1.8 Addendum）：优先检查行为回归与边界处理、信任边界、隐式耦合导致的架构漂移，以及无谓推高模型成本的设计。

五、阶段四：Commit & Push —— 约定式提交与 PR 规程

规则原文对提交阶段的要求是：写详细的 commit message、遵循 conventional commits 格式，具体格式与 PR 流程见 Git Workflow 规则。这部分在 common-git-workflow.md 中有完整定义：

Commit Message 格式

<type>: <description>

<optional body>

规则文档列出的类型集合为 feat, fix, refactor, docs, test, chore, perf, ci。仓库根目录的 commitlint.config.js 则给出了实际执行的 lint 规则，它继承 @commitlint/config-conventional 并做了三处收紧：

• type-enum：允许的类型扩展为 feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert（比规则文档多出 style/build/revert）；
• subject-case：主题行禁止 sentence-case、start-case、pascal-case、upper-case 开头，即描述应保持小写短语风格；
• header-max-length：头部最大 100 字符。

两处存在细微差异，写提交信息时建议以更严格的 commitlint 配置为准：它决定提交能否通过 lint 门禁。

另一个来自 Git 规则的重要细节：ECC 管理的安装会在 ~/.claude/settings.json 中写入 "includeCoAuthoredBy": false，因此默认提交不携带 Co-Authored-By trailer；如需保留 Claude 署名，应显式设置为 true 或配置 attribution，ECC 不会覆盖用户的显式选择。

PR 工作流

创建 PR 时的五步规程：

1. 分析完整提交历史，而不只是最新一条提交；
2. 用 git diff [base-branch]...HEAD 查看全部变更；
3. 起草全面的 PR 摘要；
4. 附带带 TODO 的测试计划；
5. 新分支推送时带 -u 标志。

六、在 ECC 仓库中的配套落地手段

四阶段流水线在仓库中不止于规则文本，还有一组可运行的配套设施：

• 格式化质量门：/quality-gate 命令对应 scripts/hooks/quality-gate.js 这个 PostToolUse 钩子，按文件类型分发格式化检查（.ts/.tsx/.js/.jsx/.json/.md 走 Biome 或 Prettier、.go 走 gofmt、.py 走 ruff format），可用 ECC_QUALITY_GATE_FIX=true 切换为自动修复、ECC_QUALITY_GATE_STRICT=true 将失败计入门禁。它只负责格式化检查，lint 与类型检查不在其范围内——那属于测试/验证流水线；
• Agent 编排规则：common-agents.md 定义了"即时调用"约定——无需用户提示，复杂功能请求就启用 planner、刚写完代码就启用 code-reviewer、bug 修复或新功能就启用 tdd-guide；独立操作还应并行派发子 Agent 而非串行；
• 证据链要求：tdd-workflow 技能要求维护 plan task → test target → RED evidence → GREEN evidence 的映射，使每一步 TDD 都有可追溯的失败/通过证据，这与 code-reviewer 要求的"引用精确行号"形成呼应——整条流水线的产物都指向可验证的证据。

七、自检清单：一次完整的功能提交应满足什么

把四个阶段的硬性要求汇总成一份合并前自检清单：

• [ ] 计划阶段：有分 Phase 的实施计划，每个步骤带文件路径、依赖与风险评级，且存在测试策略与成功标准；
• [ ] TDD 阶段：RED 阶段观察到了真实失败，GREEN 阶段为最小实现，重构后测试保持绿色；
• [ ] 覆盖率：branches/functions/lines/statements 四项均 ≥ 80%，边界情况（null、空值、边界、错误路径）有测试；
• [ ] 评审阶段：CRITICAL 为零，HIGH 全部处理，MEDIUM 已尽量修复，评审 summary 的 Verdict 不是 Block；
• [ ] 提交阶段：commit 头部符合 <type>: <description>、小写开头、≤100 字符，type 在 commitlint 允许集合内；
• [ ] PR：基于 git diff [base-branch]...HEAD 的完整历史撰写摘要，附带测试计划，新分支使用 git push -u。

这套流水线的设计取向很清晰：把"质量"从提交后的补救动作，前移到计划与测试阶段；把"评审"从主观判断变成带置信度门槛和证据要求的可审计流程；把"提交"从自由文本约束为机器可校验的格式。对使用 ECC 的团队而言，这四阶段既是 Cursor 规则中始终生效的约束（alwaysApply: true），也是三个专职 Agent 各司其职的编排约定——规则保证流程被触发，Agent 定义保证每个环节的执行深度。