establish-engineering-harness

Files (5)

• EXISTING-CODEBASE.md
• GREENFIELD.md
• HARNESS-FORMAT.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 建立 Engineering Harness

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

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

## 固定产物

优先创建或更新：

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

主入口格式见 [HARNESS-FORMAT.md](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](GREENFIELD.md)。
- Existing Codebase 或 Reconcile：读取 [EXISTING-CODEBASE.md](EXISTING-CODEBASE.md)。

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

### 3. 建立 Harness 草稿

按照 [HARNESS-FORMAT.md](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`。需要保护已有行为时，自行选择可信测试边界，测试优先任务可使用已安装的 `/tdd`。需要系统寻找存量架构摩擦时，转入 `/codebase-design`。超出本次安全范围的工作登记为 Known gaps，跨会话时用 `/handoff` 接力。

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

### 5. 展示写入计划并确认

一次性展示：

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

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

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

From iZiTTMarvin/agent-skills-zh, MIT.

More from iZiTTMarvin/agent-skills-zh