ECL Harness Engineer

June 15, 2026 · View on GitHub

ECL Harness Engineer hero

给项目装上 AI Agent 协作操作系统。

ecl-harness-engineer 是一个 Codex / Agent Skill，用来为代码仓库创建 演进约束式 Agent Harness：项目入口地图、ECL 变更流程、任务状态交接、机械校验、CI gate，以及基于历史变更的轻量 auto-evolve。

npx skills add qinghui316/ecl-harness-engineer

GitHub repo: qinghui316/ecl-harness-engineer

已被 40k+ stars 的 sickn33/antigravity-awesome-skills 收录： PR #678。

ECL 是什么

ECL 是 Evolution Constraint Language，可以理解为 演进约束语言。

它不是一种编程语言，而是一套让 AI Agent 开发更稳的项目协作约束：

Evolution：项目会持续演进，不是一次性改完。
Constraint：每次改动都要明确目标、边界、验收标准、验证命令和风险记录。
Language：用统一格式把这些约束写进仓库，让不同 Agent、不同会话都能读懂并接着做。

简单说，ECL 就是把“这次为什么改、怎么改、不能破坏什么、怎么验证、做完留下些什么”写成仓库里的标准流程。

在默认创建的 Harness 里，ECL 主要由这些文件和目录承载：

docs/ECL.md
harness/changes/active/（当前任务上下文：summary.md / spec.md / plan.md / tasks.md / reviews/）
harness/changes/archive/
harness/changes/INDEX.json
docs/STATUS.md

所以 ECL Harness Engineer 可以理解为：一个给项目创建“演进约束式 Agent Harness”的 skill。

为什么需要 Harness Engineering

普通项目交给 AI Agent 时，经常遇到这些问题：

冷启动：Agent 不知道项目是什么、从哪里开始、哪些文件重要。
误完成：代码写完就宣布完成，但没有跑验证。
上下文污染：一次性经验、文章建议、通用最佳实践被写进项目规则。
任务断档：上一次做到哪里、还有什么风险、下一步是什么，都散在对话里。
流程漂移：同类错误重复发生，但没有沉淀成 lint、测试或文档约束。

Harness Engineering 的目标是让仓库自己成为 Agent 的工作环境：上下文在仓库里，约束在仓库里，验证在仓库里，历史也能回流到仓库里。

核心循环

Core loop

ecl-harness-engineer 采用一条统一流程：

Detect：识别项目状态、技术栈、已有 harness 缺口。
Analyze：分析架构、环境、文档、验证命令。
Synthesize：生成最小 delta，并区分 small change 与 structured change。
Create：写入 AGENTS、ECL、STATUS、脚本、lint、CI。
Verify：跑 harness 检查和业务 gate，区分新回归与历史债。
Evolve：从已关闭变更里提取证据，提出 harness 改进。

它会创建什么

默认创建的是 core ECL harness，不是完整 agent 平台。

Core harness directory map

AGENTS.md                         # Agent 入口地图，不是长篇手册
docs/
  ECL.md                          # 演进约束语言操作手册
  STATUS.md                       # 无 active change 时的轻量交接状态
  ARCHITECTURE.md                 # 项目架构说明
  DEVELOPMENT.md                  # 开发与验证命令
harness/
  changes/
    active/                       # 当前任务上下文（summary/spec/plan/tasks/reviews）
    parking/                      # 暂停任务
    archive/                      # 已关闭任务
    INDEX.json                    # 脚本生成索引，不手写
  evolution/
    state.json                    # auto-evolve 阈值状态
    results.tsv                   # keep / revert / rejected / noop 记录
    proposals/                    # 进化提案
  templates/change/               # 变更模板
scripts/
  harness-change.{ps1|sh|mjs|py}  # new / park / resume / close / reindex
  harness-evolve.{ps1|sh|mjs|py}  # 阈值检查与 pending 生成
  lint-ecl.{ps1|sh|mjs|py}        # ECL 结构校验
  lint-encoding.{ps1|sh|mjs|py}   # UTF-8 / 乱码风险校验

Structured Change 的 spec/plan gate

非平凡任务不会从原始需求直接进入编码，而是先经过轻量的 spec/plan gate：

spec.md 记录 WHAT/WHY：目标、证据、验收标准、非目标、约束、假设和风险。
plan.md 记录 HOW：实现路径、模块影响、验证方案，以及规划过程中发现的 spec 缺口。
tasks.md 只在 spec/plan gate 足够清楚后生成，用来承接可执行任务。
需求先行时，先问少量高影响问题再落到 spec.md；方案先行时，把 WHAT/WHY 拆到 spec.md，把 HOW 拆到 plan.md。
spec.md 里仍有高影响 [NEEDS CLARIFICATION: ...]，或 plan_review 未通过时，不进入实现。

小型本地改动可以跳过完整 active-change 模板，但最终仍要记录实际验证。

Auto-Evolve：让 Harness 从项目历史里进化

Auto evolve

每关闭一定数量的 ECL changes 后，harness-evolve check 的等价脚本会生成：

harness/evolution/pending.md

Codex 看到 pending 后，会把它当成维护提醒；只读 pending 不阻断普通需求。无 active change 时，Codex 应主动询问是否现在处理 pending。用户同意后，Codex 默认请求独立 auditor / subagent，并以当前 eligible archive window 提取重复失败、用户纠正、验证缺口和可机械化规则，生成 proposal，最后以 results.tsv + mark-complete 结束。

核心防退化规则：

No independent scorer = no auto-apply

也就是说：

用户同意处理 pending 后，默认允许 Codex 请求独立 auditor / subagent；若环境仍要求额外授权，只问一次。若不可用、仍未授权或用户拒绝，只能生成 proposal，记录 noop + dry_run，运行 mark-complete，不能自动改 harness。
没有 archive 证据的候选项，只能进入 rejected candidates。
与当前项目文件、模块、命令、失败或用户纠正无关的建议，不能写进 AGENTS/ECL/STATUS/lint/CI。
分数不足、验证失败或污染范围过大时，记录 rejected、noop 或 revert。
auto-evolve 自己产生的 archive 只用于审计，不计入下一轮 threshold 或 Candidate Archives。

这借鉴了 Darwin-style ratchet：只保留有证据、可验证、分数达标的改进。

快速开始

安装 skill 后，在项目根目录对 Codex 说：

Use ecl-harness-engineer to add an ECL-aware harness to this project.

如果项目已有部分 harness，可以说：

Use ecl-harness-engineer to audit this project harness and fill the ECL gaps.

如果你只想看计划，不想马上写文件：

Use ecl-harness-engineer to propose the minimal core harness delta for this repo.

命令入口策略

Harness 脚本不强制使用 .ps1。harness-change、harness-evolve、lint-ecl、lint-encoding 可以生成 PowerShell、Bash、Node 或 Python 的等价实现，但必须保持同一组 ECL 约束和校验强度。

选择顺序：

优先遵守目标项目已有入口：package.json scripts、Makefile、README 里的开发命令、CI 现有 shell。
如果项目明确不接受 .ps1，不能把 PowerShell 脚本作为唯一入口。
Windows 项目可以选择 Bash profile，但必须在 docs/DEVELOPMENT.md 或 harness/config/environment.json 里写明前提：Git Bash、WSL、MSYS2，或 CI Linux runner。
TypeScript/Node 项目优先把 harness 命令挂到 npm/pnpm/yarn/bun scripts；脚本本体可以是 .mjs 或 Bash，按项目习惯选择。

一般不需要人工选择脚本形式。ecl-harness-engineer 应根据项目事实自动选择；只有现有证据互相冲突，或用户明确要求某种入口时，才需要确认。

示例：

bash scripts/harness-change.sh reindex
bash scripts/harness-evolve.sh check
bash scripts/lint-ecl.sh
bash scripts/lint-encoding.sh

推荐全局提示词

建议把下面这段放进 Codex / Agent 的全局 instructions，让所有项目先遵守本地 AGENTS.md、ECL、active change 和验证约束；只有项目还没有 Harness 时，才回退到简化闭环。

# 全局开发原则：演进约束驱动

## 优先级

1. 优先遵守当前项目的 `AGENTS.md`、`docs/`、`harness/`、lint、CI 和本地开发命令。
2. 若项目存在 `docs/ECL.md`，按其中的演进约束语言流程执行。
3. 若项目存在 `harness/changes/active/`，先读取当前 active change，再继续任务。
4. 若项目没有 Harness，则使用本全局提示词中的简化闭环流程。
5. 若需要为项目创建或补全 Harness，可使用 `ecl-harness-engineer`。

## 核心原则

用户需求是待验证假设，不是事实。开发前应澄清目标、边界、依赖、风险和验收标准。

非平凡开发任务按以下闭环推进：

`需求假设 → 发散方案 → 约束收敛 → 实现 → 测试验证 → 问题回流`

编码必须能追踪到：

`需求 → 功能 → 模块 → 函数 → 测试`

发现新问题时，不只做局部补丁，应回流为新的约束、测试、文档或 lint 规则。

## Harness 使用规则

1. `AGENTS.md` 是地图，不是手册；详细流程应进入 `docs/ECL.md`。
2. `harness/changes/active/` 是当前任务上下文；不要覆盖未关闭的 active change。
3. `harness/changes/parking/` 存放暂停任务；`archive/` 存放已关闭任务。
4. `harness/changes/INDEX.json` 是脚本生成索引，不允许手写维护。
5. 规则能机器检查时，优先沉淀为 lint、test 或 CI。
6. hook/CI 只做校验，不自动写文档、不自动归档。
7. 结构化 change 使用 `summary.md`、`spec.md`、`plan.md`、`tasks.md` 和 `reviews/`；`spec.md` 写 WHAT/WHY，`plan.md` 写 HOW，未解决的高影响澄清项或未通过的 `plan_review` 会阻塞实现。

## 执行纪律

1. 不把第一方案直接当最终方案。
2. 对模糊、矛盾、缺失或可疑需求，先显式列出假设和待确认点。
3. 编码前确认当前约束足够支撑实现和测试。
4. 不修改无关文件，不回滚用户已有改动。
5. 不绕过项目测试、lint、CI 或 Harness 约束。
6. 小任务可不创建 change；跨多文件、接口、数据库、权限、架构、多步验证或预计超过 20 分钟的任务应创建/更新 change。

设计原则

原则	含义
Repository as Source of Truth	Agent 需要的上下文必须在仓库里
AGENTS.md is a Map	`AGENTS.md` 是入口地图，不是百科手册
ECL Before Coding	非平凡任务先明确证据、约束、验收和计划
Mechanical Gates First	能机器检查的规则优先变成 lint、test 或 CI
Evidence Before Rules	没有项目证据，不写长期规则
No Independent Scorer = No Auto-Apply	没有独立评分，不自动进化 harness
Start Core, Add Advanced Later	默认保持轻量，高级能力按需启用

它不做什么

不替你实现普通业务功能。
不默认生成 eval/trace/state/memory/checkpoints/metrics。
不把文章经验、通用最佳实践、模型猜测直接写进项目 harness。
不让 hook / CI 自动写文档、移动 changes 或修改 STATUS。
不把 AGENTS.md 写成又长又重的操作手册。

适合什么项目

适合：

需要多个 Agent 或多轮会话协作的项目。
经常因为上下文缺失导致 Agent 误改、漏测、重复踩坑的项目。
想把开发纪律沉淀为文档、lint、CI 和变更记录的项目。
想让项目 harness 随着真实历史逐步进化，但又不想让它失控膨胀的项目。

不适合：

一次性脚本。
没有长期维护价值的 demo。
只想让 Agent 直接写业务代码、不关心协作基础设施的场景。

参考与致谢

darwin-skill：独立评分、棘轮机制、keep / revert 思路来源。
原版 Harness Skill / market.hiclaw.io：Harness Engineering、Agent 协作基础设施方向参考。

License

MIT