ECC 特性开发工作流：研究复用、TDD、代码评审到 Git 提交的全流水线实践指南

本文基于仓库中西班牙语文档 docs/es/rules/common/development-workflow.md（英文原版见 rules/common/development-workflow.md）展开。该规则文件作为 ECC（Everything Claude Code，Agent harness 性能优化系统）团队协作规则的一部分，完整定义了一次特性开发在真正触达 git 之前必须经过的完整流水线：研究复用 → 先规划 → TDD 驱动 → 代码评审 → 提交推送 → 评审前检查。它是对 common/git-workflow.md 的"前置流程扩展"——git-workflow 讲"怎么提交和提 PR"，而 development-workflow 讲"提交之前的代码是怎么一步步被保证质量的"。

读完本文，你将掌握在 ECC 中交付一个特性的端到端方法：先用 GitHub 搜索与包注册表把"重复造轮子"降到最低，再借助 planner / tdd-guide / code-reviewer 等内置 Agent 完成规划、红绿重构与分级评审，最后按 conventional commits 规范提交，并满足全部评审前置检查（CI 通过、无冲突、分支同步）后进入 PR 评审。

工作流全景：把"写代码"放进六步流水线

ECC 把特性的实现组织成编号阶段，其中第 0 步被强制标注为任何新实现之前必做，第 1～5 步构成递进的交付门槛：

阶段	名称	核心产出 / 动作	承担者
0	研究与复用（强制）	搜索现有实现、确认库文档、登记包注册表、寻找可复用的开源方案	开发者
1	先规划（Plan First）	PRD、架构、system_design、tech_doc、task_list	planner Agent
2	TDD 驱动	红 → 绿 → 重构，80%+ 覆盖率	tdd-guide Agent
3	代码评审	修复 CRITICAL / HIGH，尽量修复 MEDIUM	code-reviewer Agent
4	提交与推送	conventional commits，详细 commit message	开发者
5	评审前检查	CI/CD 全绿、无合并冲突、分支已同步	开发者 / CI

原文说明：本文件通过 > This file extends ...（西班牙语版为 > Este archivo extiende）声明与 git-workflow.md 的关系，即工作流链路中 git 阶段的具体 commit 格式与 PR 细则被单独收敛在 git-workflow 中。二者配套阅读才能形成完整闭环。

第 0 步：研究与复用——写新代码前必须回答"为什么找不到现成的"

规则将"研究"排在所有步骤之前并标为强制（obligatorio / mandatory），给出了严格的优先级序，以避免"面向空白实现"导致的重复劳动与不可维护性。

1. 先做 GitHub 代码搜索

• 执行 gh search repos 与 gh search code，在写任何新代码前寻找已有实现、模板（templates）与模式（patterns）。
• 目的：站在既有社区实现之上，而不是从零发明。

2. 其次查阅库文档

• 使用 Context7 或主厂商（primary vendor）官方文档，确认 API 行为、包用法以及版本相关细节（version-specific details）。
• 理由：仅凭记忆或陈旧示例编码是版本漂移（dependency drift）的常见来源。

3. Exa 只在"前两者不足"时启用

• 当前两步无法覆盖时才用 Exa 做更宽泛的 web 研究与发现（discovery）。
• 这确立了"仓库内证据优先 → 官方文档其次 → 泛互联网兜底"的信息分层。

4. 先查包注册表再写工具代码

• 依次搜索 npm、PyPI、crates.io 等注册表；凡是存在久经实战（battle-tested）的库，优先于手写（hand-rolled）实现。
• 对应到本仓库，ECC 本身就是"多语言规则 + 工具"的集合，其规则目录按语言组织（见 rules/ 下各语言子目录），强调每个技术栈都应有成熟约定而非各写一套。

5. 寻找"可适配实现"而非"完美匹配"

• 寻找能解决 80%+ 问题的开源项目，并且可被 fork、移植（ported）或包装（wrapped）。
• 最终偏好：当既有成熟方案满足需求时，采用或移植它，而不是编写全新（net-new）代码。

第 1 步：先规划（Plan First）——代码动手前先产出设计文档

规则要求在编码前调用 planner Agent 产出实施计划，并"生成规划文档"：PRD、architecture、system_design、tech_doc、task_list，同时识别依赖与风险、分解为阶段（phases）。

仓库中 agents/planner.md 完整刻画了这一 Agent 的行为，可作为实操细节的延伸：

• 工作范围：需求分析（明确成功标准、列出假设与约束）→ 架构评审（分析现有代码结构、识别受影响组件）→ 步骤分解（每个步骤带明确动作、文件路径、依赖、复杂度、风险）→ 实施顺序（按依赖排序、减少上下文切换、支持增量测试）。
• 计划模板骨架：# Implementation Plan: [Feature Name] → Overview → Requirements → Architecture Changes → Implementation Steps（按 Phase 分组，每个步骤含 Action / Why / Dependencies / Risk）→ Testing Strategy → Risks & Mitigations → Success Criteria。
• 阶段的独立可交付性：planner 建议把大特性切成 Phase 1（最小可用切片）、Phase 2（核心体验主路径）、Phase 3（错误处理与边界）、Phase 4（性能与可观测性），并且每个阶段都应可独立合并，避免"全部完成后才能工作的计划"。
• 红旗清单（Red Flags）：超过 50 行的函数、超过 4 层的嵌套、重复代码、缺失错误处理、硬编码值、缺测试、缺测试策略、步骤没有明确文件路径、无法独立交付的阶段。

从 ECC 的命令层看，"先规划后实现"并非孤例：交互式特性开发命令 commands/feature-dev.md 同样把 Discovery（读取需求/识别验收标准）与 Codebase Exploration（使用 code-explorer 分析既有代码）放在 Implementation 之前，并要求实现前先获得设计批准，验证了该规则在仓库内的可执行性。

第 2 步：TDD 驱动——红 / 绿 / 重构与 80%+ 覆盖率红线

规则第 2 步要求调用 tdd-guide Agent，流程为：先写测试（ROJO/RED）→ 实现到测试通过（VERDE/GREEN）→ 重构（MEJORAR/IMPROVE），并要求验证 80%+ 覆盖率。

agents/tdd-guide.md 把"80%"明确展开为四项指标：branches、functions、lines、statements 均 ≥ 80%，并给出可直接执行的命令：

# 先运行测试确认失败（RED）
npm test

# 写最小实现使其通过（GREEN）

# 重构并保持测试绿（IMPROVE）

# 最后核验覆盖率：branches/functions/lines/statements 均需 80%+
npm run test:coverage

配套规则 docs/es/rules/common/testing.md（英文版 rules/common/testing.md）进一步固定了测试要求：

• 三类测试全部必需：单元测试（单个函数/工具/组件）、集成测试（API 端点、数据库操作）、E2E（关键用户流，按语言选择框架）。
• TDD 为强制工作流：写测试 → 运行且必须失败 → 最小实现 → 必须通过 → 重构 → 核验覆盖率。
• 失败排查策略：先用 tdd-guide；检查测试隔离性；检查 mock 正确性；修实现而非改测试（除非测试本身写错）。
• 测试结构推荐 AAA 模式（Arrange-Act-Assert）。

tdd-guide 还定义了必测边界用例清单（null/undefined、空数组/字符串、非法类型、最小最大值边界、错误路径、竞态、10k+ 大数据量、Unicode/emoji/SQL 字符等）与应避免的反模式（测实现细节而非行为、测试间共享状态、断言过弱、不 mock Supabase/Redis/OpenAI 等外部依赖），并维护了发布关键路径需在合并前追求 pass@3 稳定性（v1.8 Eval-Driven TDD 附录）的评估驱动实践。

在本仓库自身，TDD 规范同样被身体力行：npm test（见 package.json）会依次执行 Unicode 安全检查、agents/commands/rules/skills/hooks/manifests 校验脚本后，再运行 tests/run-all.js 发现并执行 tests/**/*.test.js 下的全部测试；例如 tests/ci/code-reviewer-false-positive-guard.test.js 就是一个用断言守护 Agent 规则质量的单元测试样例。

第 3 步：代码评审——写完后立即评审，按严重级别分级处理

规则要求在写完代码立即调用 code-reviewer Agent，并给出明确的分级处理策略：

• 处理 CRITICAL 与 HIGH 问题；
• 在可能时修复 MEDIUM 问题。

agents/code-reviewer.md 展示了该 Agent 的专业化设计，值得作为评审实操细则引用：

• 评审输入：先跑 git diff --staged 与 git diff 观察全部变更；若无 diff 再以 git log --oneline -5 查看近期提交；随后通读整个文件与调用方，而非孤立评审改动。
• 基于置信度的过滤（>80%）：只有确信度 >80% 的"真问题"才报告；风格偏好、未改动代码中的非 CRITICAL 问题应跳过；相似问题合并报告；优先报告会导致 bug、安全漏洞或数据丢失的问题。
• 报告前四问门禁（Pre-Report Gate）：能否引用精确行号？能否描述具体失败模式（输入、状态、坏结果）？是否读过周围上下文（调用方、imports、测试）？严重级别是否站得住（缺 JSDoc 永远不是 HIGH；测试 fixture 里单个 any 永远不是 CRITICAL）？
• HIGH/CRITICAL 必须有证据：精确代码片段 + 行号、具体失败场景、为何现有防护（类型、校验、框架默认值）无法拦截；三者缺一则降级为 MEDIUM 或丢弃。
• 允许零发现："一份干净的评审是有效的评审"，不得为凑发现而制造噪音；最终以 Review Summary 表格（CRITICAL/HIGH/MEDIUM/LOW 各列计数）输出，结论为 APPROVE / WARNING / BLOCK。
• 常见误报黑名单：包括"建议加错误处理"（当错误路径已由调用方或框架兜底）、"缺输入校验"（内部函数且调用方已校验）、"魔法数字"（200/404/1000 等公认常量）、"函数太长"（用于穷举 switch / 配置对象 / 测试表）等；触发前自问"组内资深工程师真的会改吗"。
• AI 生成代码专项附录（v1.8）：优先检查行为回归与边界处理、安全假设与信任边界、隐藏耦合与架构漂移、无谓增加模型成本的不必要复杂度；对确定性重构默认推荐低成本模型档位。

这一整套防误报机制并非纸面文章——tests/ci/code-reviewer-false-positive-guard.test.js 会在 CI 中逐条断言 agents/code-reviewer.md 必须包含"Confidence-Based Filtering / Pre-Report Gate / HIGH & CRITICAL Require Proof / 允许零发现 / Common False Positives"等章节与关键措辞，包括 ">80% confident" 阈值，确保评审纪律不会在演进中被稀释。

第 4 步：提交与推送——遵循 conventional commits 格式

第 4 步要求提交时使用详细的 commit message 并遵循 conventional commits 格式，详细格式与 PR 流程被指向 git-workflow.md。

Commit Message 格式

规则文件给出的提交格式与类型如下：

<type>: <description>

<optional body>

类型（Types）：feat, fix, refactor, docs, test, chore, perf, ci

仓库 commitlint.config.js 提供了真实可执行的类型校验，可作为格式权威来源：它继承 @commitlint/config-conventional，并将 type-enum 扩展为 feat / fix / docs / style / refactor / perf / test / chore / ci / build / revert，同时禁止 sentence-case、start-case、pascal-case、upper-case 的 subject（即保持全小写描述），header-max-length 限制为 100 字符。这意味着"详细 message"在实践中被量化为：类型受控、subject 小写、首行不超过 100 字符、正文可包含可选 body。

Co-Authored-By 归属的默认配置

git-workflow 记录了一个重要的实际差异：ECC 管理的安装会在 ~/.claude/settings.json 中设置 "includeCoAuthoredBy": false，因此默认生成的 commit 不携带 Co-Authored-By trailer；若需保留 Claude 归属，可显式设置 "includeCoAuthoredBy": true 或配置 attribution——ECC 从不覆盖用户的显式选择。

Pull Request 工作流

创建 PR 时应遵循五步（见 git-workflow.md）：

1. 分析完整提交历史（而非只看最新一条 commit）；
2. 使用 git diff [base-branch]...HEAD 查看全部变更；
3. 撰写完整的 PR 摘要；
4. 附上带 TODO 的测试计划；
5. 新分支推送时使用 -u 标志（git push -u origin <branch>）。

第 5 步：评审前检查——"绿灯"是请求评审的前提

工作流以"评审前门禁"收尾，四类检查全部通过后才允许请求评审：

1. 所有自动化检查（CI/CD）均为通过状态——对应本仓库即 npm test 串联的校验与 tests/run-all.js 测试套件；格式层面还可配合 commands/quality-gate.md 描述的质量门禁（基于 Biome/Prettier/gofmt/ruff format 的单文件格式检查，支持 ECC_QUALITY_GATE_FIX、ECC_QUALITY_GATE_STRICT 环境开关）；
2. 解决所有合并冲突（merge conflicts）；
3. 确保分支已与目标分支同步（up to date）；
4. 以上全部通过后，才请求评审。

把流水线落到仓库：一张可循证的资源地图

工作流阶段	仓库内的真实载体（相对路径）
规则主体（西班牙语）	docs/es/rules/common/development-workflow.md
规则主体（英文原版）	rules/common/development-workflow.md
Git 提交与 PR 细则	docs/es/rules/common/git-workflow.md / rules/common/git-workflow.md
测试与覆盖率要求	docs/es/rules/common/testing.md / rules/common/testing.md
规划 Agent 实现	agents/planner.md
TDD Agent 实现	agents/tdd-guide.md
评审 Agent 实现	agents/code-reviewer.md
评审纪律的 CI 守护测试	tests/ci/code-reviewer-false-positive-guard.test.js
交互式特性开发命令	commands/feature-dev.md
质量门禁命令	commands/quality-gate.md
提交规范的可执行配置	commitlint.config.js
测试总入口	tests/run-all.js

小结：让每个特性都先过"质量流水线"，再进 git

development-workflow 的价值在于把软件工程中容易口头化、难以量化的环节——别重造轮子、先想清楚再写、测试先行、写完全面评审、提交规范、评审前自检——固化为编号步骤与强制顺序：研究复用（0）永远在实现之前，规划（1）先于编码，TDD（2）约束实现方式，评审（3）紧跟代码产出，提交（4）遵循 conventional commits，而评审前检查（5）把 CI、冲突与分支同步变成进入 PR 评审的硬前提。配合仓库内 planner、tdd-guide、code-reviewer 三个专职 Agent 与配套 CI 测试，这套规则在 ECC 中既是文档、又是可执行的工作协议；对任何希望在团队内落地"可度量、可门禁、可复现"的开发流水线的读者，它都是一份可以直接借鉴的范本。