以"开发上下文"约束 Agent 编码行为：解读 ECC 的 Development Context 规范

这篇指南围绕 ECC（Everything Claude Code）仓库中一份短小却关键的规范文件 contexts/dev.md（及其西班牙语镜像 docs/es/contexts/dev.md）展开，说明它如何定义 Agent 在"主动开发（Active development）"模式下应遵循的行为基线、优先级与工具偏好。读完本文，你将理解 ECC 中 dev / research / review 三种上下文如何构成"先理解、再实现、后把关"的工程闭环，并能直接把这份上下文规范迁移到自己的 Agent 工作流或团队规范中。

一、Context 是什么：一份 20 行的 Agent 行为契约

ECC 将仓库根目录下的 contexts 目录作为"工作上下文"的存放处，目前包含三个文件，分别对应三种工作模式：

文件	模式	定位
contexts/dev.md	Active development	实现、编码、构建功能
contexts/research.md	Exploration / investigation	先理解后行动
contexts/review.md	PR review / code analysis	质量、安全、可维护性

原文档的西班牙语版本 docs/es/contexts/dev.md 与英文根文件逐行对应，这说明 contexts 是一套"语言无关"的约定层：它不绑定具体编程语言，也不绑定具体 harness（项目定位是面向 Claude Code、Codex、Opencode、Cursor 等环境的 Agent 性能优化系统），而是约束 Agent 在不同工作阶段的表现形态。整个 contexts 目录内容非常克制——没有配置样板、没有依赖说明，只有一段宣言式的行为契约，这恰恰是它的设计意图：上下文文件应当"薄"，把厚重的内容留给 rules/、skills/ 与 agents/。

二、开发上下文的四维行为基线

dev.md 的 ## Comportamiento（行为）一节给出了四条不可妥协的行为准则，正文如下（西班牙语原文保留，便于与镜像文件对照）：

- Escribir código primero, explicar después      # 先写代码，后做解释
- Preferir soluciones funcionales sobre soluciones perfectas  # 可用优于完美
- Ejecutar pruebas después de los cambios        # 每次改动后运行测试
- Mantener los commits atómicos                  # 保持提交原子性

2.1 先写代码，后做解释

开发模式下，Agent 应当直接产出可运行代码，而非长篇论证。这与 contexts/research.md 中的 Don't write code until understanding is clear（理解未清晰前不写代码）正好构成互补：research 模式负责收敛认知、产出结论，一旦切换到 dev 模式，重心就从"解释"转为"产出"。这两条规则叠加，形成一条清晰的责任边界——调研阶段的产出是文档与假设，开发阶段的产出是代码与提交。

2.2 可用优于完美：与测试纪律的张力

"可用性优先于完美性"常被误读为"可以跳过工程纪律"，但 dev.md 用紧随其后的两条规则（运行测试、原子提交）收紧了这一口子。对照 AGENTS.md 中 Test-Driven、80%+ coverage required 以及 Plan Before Execute 等核心原则可以看出：ECC 对"functional > perfect"的理解是先打通端到端路径，再用测试与重构收紧，而不是先追求完美设计再动手。

2.3 改动后必跑测试

Ejecutar pruebas después de los cambios 在仓库中有一整套配套设施。ECC 维护了规模庞大的测试树：tests 下按 ci / commands / docs / hooks / lib / scripts / skills 等维度组织用例，根目录 package.json 承载测试脚本入口，tests/run-all.js 提供全量执行入口，Python 侧另有 src/llm 对应的 tests/conftest.py 与一系列 test_*.py。与 dev.md 相比，AGENTS.md 的 Testing Requirements 更进一步，把 TDD 规定为强制工作流：先写测试（RED，应当失败）、再写最小实现（GREEN，应当通过）、最后重构（IMPROVE）并确认覆盖率不低于 80%。因此 dev 上下文中的"改完跑测试"是底线，TDD 则是把测试前移到改动之前的进阶纪律。

2.4 原子提交

Mantener los commits atómicos 与仓库的 Git 工作流约定直接呼应。AGENTS.md 明确规定提交格式为 <type>: <description>，type 取 feat / fix / refactor / docs / test / chore / perf / ci。原子提交意味着每个 commit 只承担一个职责变更，这为后续的 code-reviewer 审查与回滚提供了最小颗粒度，也与仓库 commitlint.config.js 所表达的提交规范约束一致。

三、优先级模型：working → right → clean

## Prioridades 一节给出了开发模式下决策取舍的排位：

1. Hacer que funcione   # 让它跑起来
2. Hacerlo bien         # 把它做对
3. Hacerlo limpio       # 把它做干净

这个三级漏斗实际上是工程质量的"阶段时钟"：先把功能点亮，再保证逻辑正确，最后才谈整洁度。值得注意的是它与 AGENTS.md 中 TDD 的 RED→GREEN→IMPROVE 三段式节奏同构——Hacerlo bien 对应测试通过意义上的正确，而 Hacerlo limpio 对应 refactor 阶段。仓库对"干净"的下限不是个人口味，而是 AGENTS.md 中可核查的编码规范：函数不超过 50 行、单文件聚焦（典型 200–400 行，上限 800）、禁止深层嵌套（不超过 4 层）、不可变对象优先（immutability）、错误处理不静默吞掉异常、系统边界做输入校验并快速失败。也就是说，dev 上下文允许你"先跑起来"，但不允许你在"跑起来"之后跳过对正确性与整洁度的收敛。

四、工具偏好：开发模式的"最小执行套件"

## Herramientas a favorecer 给出的工具清单刻意保持精简：

- Edit, Write 用于代码变更
- Bash 用于运行测试与构建
- Grep, Glob 用于定位代码

4.1 与 research / review 上下文的工具对比

将三者并列能看出 ECC 在"按模式分配工具预算"上的设计：

上下文	工具偏好	意图
dev	Edit / Write、Bash、Grep / Glob	聚焦写入、执行与快速定位
research	Read、Grep / Glob、WebSearch / WebFetch、Task + Explore	面向外部资料与全库调查
review	以严重度排序的审查流程，配合 checklist	面向批判性阅读

research 上下文把 Read、WebSearch、Task（Explore agent）放在首位，因为它的产出是理解；dev 上下文把 Edit / Write 放在首位，因为它的产出是变更。工具的取舍即模式的表达。

4.2 Grep / Glob 在大型多语言仓库中的现实含义

ECC 的知识树横跨 skills/（数百个技能）、rules/（common 与二十余种语言规则）、agents/、commands/ 等目录，且文档被镜像到 docs 下的多语言树（如 docs/es、docs/ja-JP）。在这种规模下用 Grep / Glob 快速定位代码时，合理的 glob 排除策略（例如按目录白名单搜索、排除镜像语言目录）能显著提升命中率——这也解释了为何 dev 上下文要把它们列为"应优先使用的工具"而不是可选项。

五、三种上下文构成工程闭环：research → dev → review

单独看 dev.md 只是一份开发行为规范，放入 contexts/ 三件套后它才显现出完整价值：

1. research（理解）：contexts/research.md 定义五步研究流程——理解问题、探索代码/文档、形成假设、用证据验证、总结结论；其输出规范是"结论优先，建议次之"。
2. dev（产出）：研究收敛后进入本文件所定义的实现阶段，按"代码优先、改完跑测、原子提交"落地。
3. review（把关）：contexts/review.md 要求按严重度（critical > high > medium > low）排序问题、给出修复建议而不只指出毛病、并检查逻辑错误 / 边界情况 / 错误处理 / 安全（注入、鉴权、密钥）/ 性能 / 可读性 / 测试覆盖。其输出格式为"按文件分组，严重度优先"。

这条闭环与 AGENTS.md 的 Agent Orchestration 策略互为表里：复杂功能先交给 planner，实现阶段由 tdd-guide 兜底测试纪律，写完立即交给 code-reviewer 审查，敏感代码在上交前走 security-reviewer。上下文负责切换"思考姿态"，专门的 agent 负责提供领域能力，两者叠加构成了 ECC 的工程流水线。从源码结构看，这正契合项目自述中强调的 research-first 开发理念——先用 research 上下文保证"想清楚"，再用 dev 上下文保证"写出来"。

六、团队实践：如何在自己的工作流中落地这一规范

dev.md 的价值不在于它是 ECC 的私有约定，而在于它提炼出的模式可以被任何 Agent 工程团队复用：

• 用三个文件表达三种姿态：仿照 contexts/ 目录，把"开发 / 调研 / 审查"各写成一份 20 行以内的行为契约，聚焦于行为、优先级与工具偏好，而不是长篇配置。
• 优先级即决策规则：当 Agent 在"可用方案"与"完美方案"之间犹豫时，working → right → clean 提供唯一裁决依据；但要像 ECC 一样用"改后必测、原子提交"两条硬规则防止优先级被滥用为偷工减料的借口。
• 工具清单 = 模式声明：通过限制工具范围（dev 用 Edit/Bash/Grep，research 加 Read/WebSearch），间接约束 Agent 在每个阶段的行为边界，比在提示词里反复强调"专注"更有效。
• 上下文可翻译、可镜像：docs/es/contexts/dev.md 等镜像文件表明，这类行为契约可以（也应该）随团队语言本地化，从而让非英语母语成员获得完全一致的执行基线。
• 与更高层规范保持层级一致：把细颗粒的纪律（覆盖率、TDD、提交格式、编码风格）放在 AGENTS.md / rules 层，而让 context 文件保持"薄"——上下文负责姿态切换，规范库负责刚性要求。

七、速查：开发上下文一页纸

维度	规定	仓库落点
模式 / 焦点	Active development；实现、编码、构建 feature	contexts/dev.md
行为	先代码后解释；可用优于完美；改后跑测；原子提交	AGENTS.md Testing Requirements、Git Workflow
优先级	让它工作 → 做对 → 做干净	AGENTS.md Coding Style
工具	Edit / Write、Bash、Grep / Glob	与 contexts/research.md、contexts/review.md 对照
配套流程	research 五步法先行，review checklist 收尾	contexts/research.md、contexts/review.md

对于在自己的项目中使用 ECC 的开发团队，建议把这一文件当作"实现阶段的默认入场券"：进入新功能开发时先确认当前处于 dev 上下文，并让 run tests after changes 与 atomic commits 成为每次迭代不可跳过的收尾动作。