junhong_cmp_fiber/docs/engineering/从零构建Agent友好项目最佳实践.md

# 从零构建 Agent 友好项目：Harness 工程实践与文档标准

> 用途：用于新项目初始化和长期治理。它定义“哪些知识需要存在、放在哪里、按什么格式写、如何验证”。
>
> 核心结论：OpenSpec 只负责当前行为与行为变更；完整 Harness 还必须让 Agent 能找到事实、运行系统、观察结果、遵守边界、独立验证并持续清理熵。

## 1. 先澄清：ADR 不是 OpenSpec

- OpenSpec 的标准 Artifact 是 `proposal`、增量 `specs`、`design` 和 `tasks`。
- `design.md` 记录**一次 Change** 的实现设计、取舍、迁移和回滚。
- ADR 是业界通用但独立的“长期架构决策记录”，不属于 OpenSpec，也不是新项目必需品。
- 默认不建 `adr/`。只有一个跨 Change、长期生效、存在真实竞争方案且无法从代码理解原因的决策，才考虑单独记录；否则留在对应 Change 的 `design.md`。

## 2. Harness 的完整范围

OpenAI 的 Harness Engineering 不只是“短 AGENTS.md + docs”。一个完整闭环包含：

1. **仓库可读**：事实进入仓库，并有清晰索引和单一权威位置。
2. **环境可运行**：每个工作区能独立启动、测试和复现。
3. **结果可观察**：Agent 能读取日志、指标、追踪、页面和 DOM，而不是靠猜。
4. **架构可约束**：依赖方向、边界数据解析和关键不变量可机械检查。
5. **任务可判定**：需求被写成可观察、可验证的行为契约。
6. **执行可闭环**：Agent 能复现、修改、验证、比较前后结果并处理反馈。
7. **知识可维护**：链接、Owner、新鲜度和生成来源可检查，过期内容持续清除。
8. **人类掌舵**：人负责目标、优先级和判断点；Agent 负责读取、执行、验证和维护。

因此，Context 收敛不是“少写文档”，而是让默认 Context 很小、按需 Context 有标准、运行反馈足够强。

## 3. 从最小集合开始

### 3.1 所有项目 Day 0 必需

```text
AGENTS.md             # 短导航与真正的全局硬约束
README.md             # 人和 Agent 都可执行的启动入口
ARCHITECTURE.md       # 一页系统地图和依赖边界
openspec/             # 当前行为与行为变更
CI / scripts          # 格式化、检查、测试、构建命令
```

### 3.2 有真实内容时才创建

```text
docs/integrations/    # 存在第三方契约
docs/engineering/     # 存在跨模块、长期工程约束
docs/generated/       # 能由命令稳定再生的参考资料
RELIABILITY.md        # 存在队列、重试、容灾、SLO 等系统性要求
SECURITY.md           # 存在统一信任边界、敏感数据或威胁模型
FRONTEND.md           # 前端规模足以需要统一交互/状态/设计规则
PRODUCT_SENSE.md      # 多团队或 Agent 经常误判产品取舍
QUALITY_SCORE.md      # 已有明确评分维度和维护机制
```

不要预建空目录、空模板或“以后也许有用”的文档。

### 3.3 如何理解 OpenAI 文章中的示例目录

文章展示的是一套成熟仓库的实际结构，不是要求每个项目照抄。与本指南的映射如下：

| 文章中的示例 | 解决的问题 | 本指南的默认选择 |
|---|---|---|
| `ARCHITECTURE.md` | 系统地图与边界 | Day 0 创建一页版本 |
| `docs/design-docs/`、`DESIGN.md` | 跨范围设计知识 | 单次变更放 OpenSpec `design.md`；只有长期跨 Change 设计才另建 |
| `docs/exec-plans/{active,completed}`、`PLANS.md` | 长任务持续执行 | 默认用 OpenSpec `tasks.md`；非行为型长期治理才建唯一执行计划 |
| `docs/product-specs/` | 当前产品行为 | 使用 `openspec/specs/`，不再复制一套 |
| `docs/generated/db-schema.md` | Agent 可检索的生成事实 | 有稳定生成命令时放 `docs/generated/` |
| `docs/references/*-llms.txt` | 将仓库外依赖资料变成 Agent 可读输入 | 仅保存任务高频需要且无法稳定在线获取的官方资料；第三方协议归 `docs/integrations/` |
| `FRONTEND.md` | 前端统一边界 | 前端复杂度触发后创建 |
| `PRODUCT_SENSE.md` | 产品判断原则 | 重复误判触发后创建 |
| `QUALITY_SCORE.md` | 领域/架构质量评分 | 有固定评分和治理动作后创建 |
| `RELIABILITY.md`、`SECURITY.md` | 跨系统可靠性和安全约束 | 对应风险出现后创建 |

关键不是目录名一致，而是：每类知识有唯一权威位置、Agent 可发现、能被验证、不会和 OpenSpec 重复。

### 3.4 不重复的事实分工

| 知识 | 权威位置 | 不应放入 |
|---|---|---|
| 当前可观察业务行为 | `openspec/specs/` | AGENTS、工程规范 |
| 拟议行为变化 | `openspec/changes/<change>/` | 主 Specs、路线图副本 |
| 系统地图和依赖方向 | `ARCHITECTURE.md` | 每个 Change 重复描述 |
| 第三方提供的契约 | `docs/integrations/` | 业务 Spec 原文复制 |
| 长期工程约束 | `docs/engineering/` + 检查器 | 任务型 Skill |
| 实现事实 | 代码、配置、迁移 | 叙述文档副本 |
| 可再生参考资料 | `docs/generated/` | 手工维护文档 |
| 任务过程 | OpenSpec Change 或唯一执行计划 | 第二套 TODO/状态台账 |
| 完成证据 | 测试、CI、运行输出 | 长期“完成总结” |

## 4. 每类文档的统一质量契约

除生成文档外，长期文档至少要让读者回答：

```yaml
purpose: 这份文档解决什么问题
scope: 适用与不适用范围
source_of_truth: 哪些事实由本文权威维护，哪些只引用
owner: 负责判断内容是否仍成立的角色或团队
last_verified: 最后通过代码、运行结果或官方来源核验的日期
update_triggers: 哪些变更发生时必须同步检查本文
verification: 用什么命令或证据判断内容仍有效
```

这不要求所有文件都使用 YAML；要求这些信息明确可找到。

### 合格标准

- 写具体规则和可判定结果，不写“注意质量”“合理处理”等口号。
- 关键声明有代码路径、命令、测试、Schema 或官方来源支撑。
- 复制外部内容时标明来源版本和核验时间。
- 一项事实只有一个权威正文，其他位置只链接。
- 每个“必须/禁止”都对应机械检查，或明确说明当前为何只能人工审查。
- 示例只用于消除歧义；示例不得成为第二份规则。

### 不合格信号

- 没有适用范围、Owner 或更新触发条件。
- 只有目录介绍，没有依赖方向、入口或验证方式。
- 把当前 Bug 写成理想行为，或把未来设计冒充当前事实。
- 从代码能直接搜索得到的列表被手工复制并长期维护。
- 同一个状态、错误码或字段定义在多份文档中各写一遍。

## 5. AGENTS.md 标准

### 必填内容

1. 项目一句话目标。
2. Agent 从代码无法自然发现、且几乎所有任务都适用的硬约束。
3. build、test、lint、spec 验证的真实命令。
4. 事实源优先级和按需文档入口。
5. 禁止直接修改的生成物、敏感路径或外部生产边界。

### 禁止内容

- 完整 DTO、Model、路由或迁移操作步骤。
- 领域状态机、接口字段表和第三方协议正文。
- 已完成任务、历史方案、长 Review 清单。
- Agent 能从代码、包管理器或 `--help` 获取的通用知识。

### 尺寸与验证

- 80～120 行是目标，150 行是软预算。
- 每一行应对大多数任务有价值。
- CI 检查链接有效；验证命令必须在干净环境可运行。

```md
# 项目 Agent 指南

## 项目目标
<一句话>

## 全局硬约束
- <规则；对应检查命令或规则文档链接>

## 验证
- Build: `<command>`
- Test: `<command>`
- Lint: `<command>`
- Spec: `openspec validate --all`

## 事实源
- 当前行为：`openspec/specs/`
- 系统边界：`ARCHITECTURE.md`
- 外部契约：`docs/integrations/`
- 工程约束：`docs/engineering/`
```

## 6. ARCHITECTURE.md 标准

它是系统地图，不是完整设计书。目标是让新 Agent 在几分钟内知道从哪里进入、允许依赖谁、数据如何流动。

### 必填章节

1. **系统职责与非职责**：系统解决什么，不解决什么。
2. **运行单元**：API、Worker、定时任务、前端、数据库、缓存、外部系统。
3. **领域/模块地图**：模块职责、Owner（如有）和主要入口路径。
4. **依赖方向**：允许和禁止的跨层、跨模块依赖。
5. **关键数据流**：请求、异步事件、回调、读写路径。
6. **信任与事务边界**：外部输入在哪里解析，事务在哪里开始/结束。
7. **验证方法**：结构测试、依赖检查、启动或 smoke 命令。
8. **详细资料索引**：链接 Specs、工程约束和外部契约，不复制正文。

### 写法标准

```md
## 模块：订单
- 职责：创建订单并管理支付前后的状态流转
- 入口：`internal/...`
- 可依赖：共享错误、支付 Port
- 禁止依赖：HTTP Handler、具体支付 SDK
- 行为契约：`openspec/specs/orders/spec.md`
- 结构验证：`<command>`
```

### 机械检查

- 用 import/dependency 测试验证禁止依赖。
- 用 smoke 命令验证列出的运行单元确实可启动。
- 用链接检查验证每个引用存在。
- 模块增删、入口迁移或依赖方向改变时触发更新。

## 7. 外部契约文档标准

外部契约记录“第三方实际要求我们怎样交互”。它不是本系统的产品需求，也不是 SDK 使用教程。

### 7.1 目录规则

```text
docs/integrations/<provider>/
├── README.md            # 当前接入契约与导航
├── examples/            # 经脱敏、可复现的请求响应样例（需要时）
└── source/              # 无稳定链接的官方原文快照（需要时）
```

官方内容有稳定 URL 时只保存链接和项目所需摘要；不要复制整站文档。

### 7.2 README 必填字段

```md
# <Provider> 接入契约

## 元数据
- Owner: <角色/团队>
- 官方来源: <URL 或 source/ 文件>
- 官方版本/发布日期: <值或 unknown>
- 项目适用环境: <sandbox/production/region>
- 最后核验: YYYY-MM-DD
- 更新触发: SDK升级、官方版本变化、字段/签名/错误码变化

## 接入范围
- 使用能力：<项目实际使用的 API/事件>
- 不使用能力：<容易误用但明确不接入的能力>

## 端点与认证
| 场景 | Method | URL/Topic | 认证 | 超时 |

## 请求契约
| 字段 | 类型 | 必填 | 约束 | 来源章节 | 项目映射 |

## 响应与错误
| 外部状态/错误码 | 含义 | 可重试 | 项目处理 | 告警 |

## 签名与回调
- 签名原文构造：<精确定义>
- 验签步骤：<精确定义>
- 时间窗/重放保护：<规则>
- 回调确认语义：<响应内容和重试条件>

## 可靠性
- 幂等键：<字段与作用域>
- 超时：<连接/请求>
- 重试：<次数、退避、仅哪些错误>
- 限流：<规则>
- 对账/补偿：<触发与入口>

## 安全与数据
- 凭证名称及托管位置：<只写名称，不写密钥>
- 敏感字段：<日志脱敏规则>
- 来源校验：<证书/IP/签名等>

## 验证
- 本地/沙箱命令：`<command>`
- 固定输入：`<fixture>`
- 预期结果：`<literal outcome>`
- 生产人工验收：<只有真实环境才能完成的最小步骤>
```

### 7.3 质量门禁

- 所有项目使用的字段都能追溯到官方来源或经确认的真实样例。
- 签名、金额单位、时间格式、编码、回调确认内容必须写成精确规则。
- 每种外部错误明确：重试、失败、忽略、人工处理中的一种。
- 重试必须同时定义上限、退避和幂等保护。
- 示例必须脱敏，并可被测试或脚本读取；真实密钥不得进入仓库。
- 至少有一个沙箱/契约测试，或明确记录为何只能人工验收。

### 7.4 不合格示例

```md
调用失败时适当重试。
```

问题：没有错误范围、次数、退避、幂等和最终失败动作，无法实现或验证。

合格写法：

```md
仅对连接超时和外部错误 E_TEMP 重试；最多 3 次，间隔 1s/2s/4s；
每次复用同一幂等键。三次失败后记录 integration failure 并进入人工对账队列。
```

## 8. 工程约束文档标准

工程约束描述“所有相关代码长期必须保持的性质”。DTO、Model、路由、迁移、注释、依赖边界属于此类，而不是 Skill。

### 8.1 一条约束的标准格式

```md
### ENG-<AREA>-NNN：<可判定标题>

- 状态：active | deprecated
- 适用范围：<路径、语言、组件或操作>
- 规则：MUST/MUST NOT <单一可判定约束>
- 理由：<错误成本或架构原因；不复述规则>
- 正例：`<最小示例或现有代码链接>`
- 反例：`<最小示例>`
- 机械检查：`<测试/Lint/脚本命令>` 或 `暂为人工：<原因>`
- 例外：<允许条件、批准者、记录位置；无则写“无”>
- Owner：<角色/团队>
- 最后验证：YYYY-MM-DD
- 更新触发：<框架升级、目录调整、事故等>
```

### 8.2 规则拆分标准

- 一个 ID 只表达一个义务，避免“正确、安全、高性能地处理”。
- 适用范围必须能映射到路径或组件。
- 正例优先链接仓库内稳定实现，不复制大段代码。
- 反例只展示最容易犯且有实际代价的错误。
- 规则能由机器判断时，文档必须链接检查器；检查器才是执行门禁。
- 例外必须有边界和到期/复审条件，不能写“特殊情况除外”。

### 8.3 分类

| 分类 | 应记录 | 首选验证 |
|---|---|---|
| 架构 | 依赖方向、分层、边界解析 | 结构测试、import Lint |
| 数据 | 迁移、主键、金额单位、事务 | Schema/Lint/集成测试 |
| API | 路由注册、错误形状、兼容性 | OpenAPI diff、契约测试 |
| 可靠性 | 幂等、重试、锁、Outbox | 故障注入、集成测试 |
| 安全 | 权限、敏感字段、信任边界 | 安全测试、静态检查 |
| 代码品味 | 禁止无价值抽象、复杂度上限 | Lint + Review |

### 8.4 合格与不合格示例

不合格：

```md
数据库迁移要谨慎，注意兼容旧数据。
```

合格：

```md
### ENG-DB-003：新增非空列必须可在线回填
- 适用范围：`migrations/`
- 规则：已有数据表新增非空列时，MUST 先增加可空列或带兼容默认值，完成回填后再收紧约束。
- 理由：直接增加无默认值的非空列会使现有数据迁移失败。
- 机械检查：`<migration smoke command>`
- 例外：仅空表；必须在 Change design 中提供查询证据。
```

## 9. OpenSpec 生成提案的标准

用户不需要手工填写长表。AI 生成 Change，但生成器和 Reviewer 必须遵守质量门禁。

### 9.1 Explore 后才能确定的内容

- 当前行为和证据路径。
- 目标、原因、范围和非目标。
- 角色、资源、前置状态和数据范围。
- 状态、金额、权限、事务、并发、幂等和外部失败边界。
- 已知事实、推断和真正需要人决策的问题。

### 9.2 Proposal

只回答为什么、做什么、不做什么、影响哪些 Capability。不得塞入实现步骤和通用工程规范。

### 9.3 Requirement / Scenario

```md
### Requirement: <一个可观察义务>
系统 SHALL <测试者无需阅读实现即可判定的结果>。

#### Scenario: <场景>
- **GIVEN** <角色、数据、前置状态>
- **WHEN** <一个动作>
- **THEN** <可观察结果>
- **AND** <副作用或必须保持的不变量>
```

门禁：

- 一个 Requirement 一个主要义务。
- Scenario 有具体前置条件、触发和结果。
- 覆盖主流程以及代价最高的权限、失败、边界或重复场景。
- 不使用“体验良好”“正确处理”“高性能”等不可判定词。
- 不写函数名、表名、ORM、缓存或队列选型。
- Brownfield 的错误现状也按 As-Is 写入；Spec 描述事实不等于认可设计。

### 9.4 Design

记录本 Change 的架构通道、数据与事务、并发、外部失败、兼容、迁移、发布、回滚和真实取舍。简单且实现显然时保持简短。

### 9.5 Tasks

- 按可独立验证的纵向切片拆分，不按 Model/Service/Handler 水平拆分。
- 每项映射 Requirement/Scenario，并包含最小验证命令和预期结果。
- 适用时同时验证响应、持久化、副作用和失败不变量。
- 实施发现 Artifact 与事实冲突时同步修订，不静默跳过或扩大任务。

## 10. Generated docs 标准

仅当内容能稳定再生且 Agent 经常需要查询时创建，例如数据库 Schema、OpenAPI 摘要或配置清单。

每份生成文件顶部必须包含：

```md
<!-- GENERATED FILE: DO NOT EDIT -->
- Source: <代码/Schema 路径>
- Command: `<生成命令>`
- Generator version: <版本>
- Generated at: <时间或来源 commit>
```

CI 重新生成并检查 diff。生成结果没有稳定命令时，它就不是 generated doc，而是会腐烂的手工副本。

## 11. 唯一执行计划标准

一般功能直接使用 OpenSpec `tasks.md`，不要再建 `docs/exec-plans/`。只有不改变产品行为、跨多天且 OpenSpec 不适配的迁移/治理任务，才使用单独执行计划。

必填内容：

- 目标和完成定义。
- 范围、非目标和受保护路径。
- 前置依赖和顺序。
- 可恢复的任务清单，每项含验证。
- 当前进度，只在这一处更新。
- 关键决策与新发现。
- 回滚条件和命令。
- 最终验收命令及预期结果。

Manager、Executor、Auditor 可以分工，但只能共享这一份任务契约；Harness state 和报告只是可丢弃证据。

## 12. Agent 可操作环境标准

### 12.1 独立运行

- 每个 worktree/工作区可使用不同端口和隔离的临时数据启动。
- README 提供一条启动命令、一条测试命令和一条重置命令。
- 依赖、种子数据和环境变量有可复制的本地默认值；真实凭证不入库。

### 12.2 浏览器与 UI

有 UI 时，Agent 应能：

- 启动应用并通过浏览器/CDP 操作关键流程。
- 保存失败前后的截图或视频。
- 读取 DOM、Console error 和失败网络请求。
- 用稳定测试定位器，而非脆弱坐标。

### 12.3 可观测性

本地至少能按 request/correlation ID 串起：

- 结构化日志。
- 关键指标。
- 跨进程或异步链路追踪（系统存在此类链路时）。

提供最小查询命令。临时本地可观测栈应可一键启动和销毁，运行数据不作为长期事实源。

### 12.4 自主验证闭环

```text
复现问题 → 捕获基线 → 修改 → 运行最小测试 → 启动系统
→ 检查日志/指标/页面 → 对比前后 → 完整门禁 → 提交审查
```

只有产品取舍、不可逆操作、真实生产权限或相互冲突的事实需要升级给人。

## 13. Reliability、Security、Product Sense、Quality Score

这些不是所有项目的固定作业。

### RELIABILITY.md：何时创建

当系统出现 SLO、重试、队列、定时任务、降级、容灾或数据修复策略时创建。最低结构：关键用户旅程、SLO/错误预算、故障模式、超时重试、幂等与补偿、观测和告警、恢复/演练、Owner。

### SECURITY.md：何时创建

当存在统一信任边界、敏感数据、权限模型或外部暴露面时创建。最低结构：资产和角色、信任边界、认证授权、数据分类、密钥、审计、主要威胁与控制、验证命令、事件入口、Owner。

### PRODUCT_SENSE.md：何时创建

当多个功能反复需要相同产品判断、Agent 经常做出局部正确但产品错误的选择时创建。最低结构：目标用户、核心任务、优先级原则、明确非目标、取舍示例、正反例。具体行为仍归 OpenSpec。

### QUALITY_SCORE.md：何时创建

只有团队真的按固定维度定期评分并采取行动时创建。每项必须有定义、证据来源、当前分数、阈值、Owner、改进动作和复评日期；没有维护机制就不要创建。

## 14. 文档检查与持续清熵

### 每次变更

- 检查内部链接和引用路径。
- OpenSpec 校验全部通过。
- 生成文档可无差异再生。
- 架构边界检查通过。
- Change 完成后同步/归档 Specs，删除被替代的同义说明。

### 周期性 doc-gardening

Agent 定期生成候选清单，人只处理真正的判断点：

- 失效链接、孤儿文件和长期 TBD。
- `last_verified` 过期且影响仍高的文档。
- 与代码、测试或 Specs 冲突的声明。
- 重复规则、重复事实和已被检查器取代的提醒。
- 已完成的临时计划、报告和可丢弃运行证据。

清理优先级：删除 > 合并到权威位置 > 更新 > 新建索引。

### 黄金原则

把反复出现的 Review 意见和事故教训变成最靠近问题的自动化约束：测试、类型、Lint、Schema、结构检查或运行时保护。不要持续加长 AGENTS.md。

## 15. Day 0 到稳定期的落地顺序

1. Agent 生成最小可运行仓库、格式化、包管理、CI 和测试骨架。
2. 建立短 `AGENTS.md`、可执行 `README.md` 和一页 `ARCHITECTURE.md`。
3. 初始化 OpenSpec；第一个真实功能走 Explore → Propose → Review → Apply → Verify → Archive。
4. 打通独立工作区启动、日志读取和最小 smoke 测试。
5. 出现真实第三方时按外部契约模板创建资料。
6. 出现重复工程失误时先加检查器，再补对应约束 ID。
7. 只有触发条件成立时增加 Reliability、Security 等专项文档。
8. 持续删除完成报告、重复事实和过期 Context，避免周期性大扫除。

## 16. 最低验收清单

- [ ] 新 Agent 只读 AGENTS.md 就能找到行为、架构、外部契约和验证入口。
- [ ] README 的启动、测试、重置命令在干净工作区可执行。
- [ ] ARCHITECTURE.md 的依赖方向有检查或明确人工门禁。
- [ ] OpenSpec Requirement/Scenario 可观察、可判定。
- [ ] 外部契约的版本、字段、签名、重试、幂等和验证证据齐全。
- [ ] 每条工程约束有范围、规则、理由、检查、例外和 Owner。
- [ ] Agent 能自行读取错误日志；有 UI 时能读取页面和网络失败。
- [ ] 同一事实没有多个权威正文。
- [ ] 文档链接、生成检查、Spec 校验和测试进入 CI。
- [ ] 临时计划、状态和运行证据不会成为第二事实源。

## 17. 参考资料

### 第一方

- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/)
- [OpenSpec Overview](https://openspec.dev/docs/overview)
- [OpenSpec Writing Specs](https://openspec.dev/docs/writing-specs)
- [OpenSpec Getting Started](https://openspec.dev/docs/getting-started)
- [LongHorizon-Harness](https://github.com/AMAP-ML/LongHorizon-Harness)

### 补充实践

- [Augment：How to write good AGENTS.md files](https://www.augmentcode.com/blog/how-to-write-good-agents-dot-md-files)
- [BetterClaw：AGENTS.md best practices](https://www.betterclaw.io/blog/agents-md-best-practices)
- [What goes in AGENTS.md?](https://ro14nd.de/what-goes-in-agents-md/)
- [Domain Expertise Is the New Agentic Coding Moat](https://www.developersdigest.tech/blog/domain-expertise-agentic-coding-moat)
- [O’Reilly：How to write a good spec for AI agents](https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/)