establish-engineering-harness

name	establish-engineering-harness
description	为新建、进行中或已经建立过 Harness 的代码库配置并刷新可执行的工程护栏。
disable-model-invocation	true

建立 Engineering Harness

Engineering Harness 的目标，是把原本依赖人脑和聊天上下文的工程约束，转化为代码库中的唯一事实来源、明确 owner、正式 contract、可信验证和固定工作流。它不替代产品设计、模块设计或功能实现；它为后续 Agent 工作建立可检查的运行轨道。

本 Skill 只处理项目级治理。默认不大规模修改生产代码，不以理想架构覆盖现状，也不把模糊原则堆进 AGENTS.md 或 CLAUDE.md。

固定产物

优先创建或更新：

• docs/agents/engineering-harness.md——Harness 的主入口和执行地图。
• 仓库已采用的 AGENTS.md 或 CLAUDE.md——只加入指向主入口的短区块。
• 当前技术栈能够可靠执行的验证脚本、依赖规则、架构测试或 contract tests。
• 无法安全就地完成的治理工作——写成 spec、tickets 或明确的待办，不隐藏在总结中。

主入口格式见 HARNESS-FORMAT.md。

硬性边界

• 以仓库实际代码、配置、测试和已有文档为证据，不推测不存在的架构。
• 始终区分 Current State 与 Target State。
• 先保护稳定行为，再讨论重构。
• 只建立当前真实需要的 module、interface、owner 和 contract；推测性扩展不得进入 Harness。
• 生产代码重构、技术栈替换、公共 contract 迁移和大规模状态搬迁必须转为独立工作，不在本 Skill 中顺手完成。
• 新增的任何检查都必须实际运行；无法运行的命令不能登记为 canonical command。
• 已有 AGENTS.md 时不得另建 CLAUDE.md；已有 CLAUDE.md 时不得另建 AGENTS.md。两者都不存在时，先让用户选择。
• 写入前展示完整草稿和计划修改的文件；取得用户确认后再编辑。

流程

1. 探索仓库

检查并记录：

• Git 状态、默认分支、最近提交和当前工作区是否干净。
• 源代码、测试、构建、脚本、CI 和部署配置。
• README.md、AGENTS.md、CLAUDE.md、CONTEXT.md、CONTEXT-MAP.md、docs/adr/、架构文档、协议文档和规格文件。
• package manager、语言、框架、类型检查、lint、测试、构建和 E2E 命令。
• 公开入口、跨进程或跨网络接口、持久化 schema、事件协议和关键共享状态。
• 已存在的 Harness 文档及其中引用的路径和命令。

不得只根据目录名判断职责。至少沿一条真实用户行为或请求链路，从入口追踪到输出、状态变化和持久化。

完成标准： 已形成带文件路径证据的仓库事实清单，并且至少一条关键链路已被完整追踪。

2. 判定运行模式

根据证据选择一个模式：

• Greenfield——生产代码很少，尚无稳定用户行为，架构仍可围绕第一条纵向切片（vertical slice）建立。
• Existing Codebase——已有稳定功能、协议、数据或用户依赖，任何治理都必须先保护当前行为。
• Reconcile——已经存在 Engineering Harness，需要对照当前代码修复文档、命令、owner、contract 或检查规则的漂移。

向用户展示模式判断及证据。判断明显时继续；证据互相冲突时，让用户在候选模式中选择。

随后只读取对应分支：

• Greenfield：读取 GREENFIELD.md。
• Existing Codebase 或 Reconcile：读取 EXISTING-CODEBASE.md。

完成标准： 模式已经确定，且选择理由可由仓库事实复核。

3. 建立 Harness 草稿

按照 HARNESS-FORMAT.md 生成草稿。每一项声明都必须满足以下至少一项：

• 能引用实际代码、配置、测试或文档路径；
• 是用户明确确认的目标决策；
• 被清楚标记为尚未解决的 gap。

重点建立：

1. System map——关键运行链路和外部依赖。
2. Module responsibilities——每个 module 能用一句话说明职责。
3. Dependency rules——允许和禁止的依赖方向。
4. State ownership——关键状态由谁创建、修改和读取。
5. Canonical contracts——跨 module、进程、网络或持久化边界的唯一事实来源。
6. Protected invariants——后续修改不得破坏的稳定行为。
7. Verification——可信、可运行的 canonical commands。
8. Change workflow——后续 Agent 如何分析、实现、测试、审查和提交。
9. Known gaps——当前违规、缺失保护和目标改造，不伪装成已完成状态。

优先链接已有权威文档，不复制第二份定义。Harness 是执行入口和地图，不是新的文档堆积层。

完成标准： 草稿覆盖所有已识别的关键 module、状态、contract 和验证入口；每项内容都有证据、用户决策或 gap 标记。

4. 选择可执行护栏

把高价值规则尽可能转化为机器可检查的护栏。仅选择当前技术栈已有可靠实现路径的检查，例如：

• import 或 dependency direction checks；
• typecheck 和 schema validation；
• public contract tests；
• architecture tests；
• stream/event ordering tests；
• state owner 访问限制；
• lint rules；
• canonical verification script；
• CI 中的必需检查。

优先复用现有工具和测试框架。不要为了一个简单规则引入大型依赖，也不要以只断言 mock、非空值或 HTTP 200 的测试制造假绿。

需要设计 module interface 或 seam 时，转入 /codebase-design。需要保护已有行为时，在用户确认的 seam 上转入 /tdd。需要系统寻找存量架构摩擦时，转入 /improve-codebase-architecture。超出本次安全范围的工作使用 /to-spec 和 /to-tickets。

完成标准： 每条计划新增的机器护栏都能说明它保护的具体 invariant、运行位置和失败信号。

5. 展示写入计划并确认

一次性展示：

• docs/agents/engineering-harness.md 的完整草稿；
• 准备加入 AGENTS.md 或 CLAUDE.md 的短区块；
• 准备新增或修改的验证文件；
• 不会在本次处理、将转为后续工作的 gaps；
• 所有准备执行的验证命令。

用户可以修改草稿。未取得确认，不写入仓库。

完成标准： 用户明确确认写入范围，或给出需要应用的修改意见。

6. 写入并验证

按确认后的计划写入。AGENTS.md 或 CLAUDE.md 中只保留短入口：

## Engineering harness

修改代码前先阅读 `docs/agents/engineering-harness.md`。
所有变更必须遵守其中记录的 module responsibilities、dependency rules、
state ownership、canonical contracts、protected invariants 和 verification commands。

随后：

1. 检查 Harness 中所有相对路径均存在。
2. 逐条运行 canonical commands。
3. 运行新增的机器护栏，并确认它们能够失败于所保护的违规。
4. 检查 Current State 与 Target State 没有混写。
5. 检查未解决问题已进入 Known gaps 或真实 tracker。
6. 检查本 Skill 没有顺手修改未获授权的生产行为。
7. 审查最终 diff，删除重复、沉积和无效规则。

验证失败时，修复本次新增的 Harness 或准确记录既有失败；不得把失败命令登记为通过状态，也不得删除真实失败来获得绿色结果。

完成标准： 所有新增文件可读、引用有效、可执行命令已实际运行，结果与 Harness 记录一致。

7. 完成报告

最终只报告：

• 判定的模式；
• 创建或更新的文件；
• 已建立的 owner、contract、invariants 和机器护栏；
• 实际运行的验证及结果；
• 仍然存在的 gaps，以及它们对应的 spec、ticket 或下一条工作流。

不得用“已建立完整工程体系”之类无法验证的措辞代替具体结果。

整体完成标准

仅当以下条件全部满足时，Skill 才算完成：

• 仓库存在唯一且可发现的 Engineering Harness 入口。
• 所有核心 module 都有一句话职责，或被明确列为待梳理 gap。
• 所有关键状态都有 owner，或当前多 owner 违规已被准确记录。
• 关键跨边界 contract 有唯一事实来源，或缺口已进入后续工作。
• Protected invariants 来自真实行为、规格或用户确认。
• Canonical commands 已实际执行，结果没有被伪造为绿色。
• 至少一项高价值架构规则已机器化；确实无法机器化时，原因被记录。
• Current State 与 Target State 明确分离。
• 未解决工作已经进入可追踪的后续流程。
• 未执行未经授权的大规模生产代码重构。