现在能比较清楚地看到，这类“0 行手写代码”的大项目，真正的关键不是“完全不管代码”，而是把人的工作从写实现代码，转成定义约束、搭建工作流、控制质量门禁、管理上下文。OpenAI 的内部实验、Vibe Coding 小程序实践，以及企业级低代码 / 无代码案例，都指向同一件事：项目能跑起来，靠的是工程化的“编排权”，而不是人去逐行敲代码 。

典型项目样本

OpenAI 的百万行内部产品
这类案例最极端：团队从空仓库开始，5 个月内做出百万行级产品，且人类 0 手写代码，连脚手架、CI、格式化规则、AGENTS.md 都由 agent 生成；团队规模从 3 人扩到 7 人，累计约 1,500 个 PR 。公开材料强调，核心不是“更强模型”，而是 Harness Engineering，也就是为 AI 设计工作环境、工具边界和反馈回路 。

Vibe Coding 做的小程序
另一个更贴近落地的例子是微信小程序：作者不手写代码，而是先写 PRD、定义产品逻辑和交互规范，再让 AI 生成 uni-app/Vue 代码并编译成小程序 。这类项目通常规模比 OpenAI 小，但方法论很清晰：人负责需求与约束，AI 负责实现与反复修正 。

企业级无代码/低代码项目
企业侧常见的是低代码平台或 Dify 这类工作流平台，把流程、权限、集成、审计、可观测性都平台化，适合快速验证和持续迭代 。飞书低代码案例里，像华住质量检查系统这种跨门店、跨角色、千万级数据量的系统，也是通过低代码快速搭建和跨系统打通来推进的 。

怎么做到 0 手写

这类项目的核心做法通常分四层。第一层是把需求写成足够清楚的 PRD、规范、验收标准，避免 AI 自由发挥 。第二层是给 AI 一个明确的项目“地图”，比如 OpenAI 那类做法会用 AGENTS.md 告诉 agent 去哪里找什么、遵守什么约束，而不是塞一本百科全书 。

第三层是把实现拆成小任务，通过高频短回路不断生成、运行、修正，而不是一次性产出大块代码；Vibe Coding 实战里就强调一次只做一个小功能、先写测试、再跑测试、失败后把错误反馈给 AI 。第四层是用工具链把质量自动化，例如代码扫描、单测、构建验证、安全扫描、规约检查、文档生成、监控面板等，让“写完才检查”变成“生成时就校验” 。

推动进度的方法

推动整体进度的关键，是把传统“开发-测试-上线”的长链条，变成可并行的流水线。AI 时代的流程常被描述为“业务理解 → 问题定义 → 方案设计 → AI 协作开发 → 质量把控”，而不是先让工程师写完再交给测试 。这样做的好处是，产品、设计、开发、测试不再严格串行，需求澄清、原型、实现、验收可以在同一节奏里滚动推进 。

OpenAI 那类项目尤其依赖“自动推进”的机制：agent 生成代码后，CI、测试失败日志、审查意见都会成为下一轮提示词的一部分，错误信息本身就变成了修正线索 。企业里则常用工作流平台把任务拆分、审批、集成、上线串起来，减少跨团队等待和人工同步成本 。

质量如何保证

质量保障的核心是质量门禁，也就是在提交、合并、部署前设置可执行的硬标准，而不是靠人记忆经验 。常见门禁包括单元测试覆盖率、lint、构建成功、静态扫描、漏洞扫描、规约符合度、性能阈值和代码审查 。有些方案还会让 AI 代码评审 agent 接入 CI，自动识别并发缺陷、边界错误、资源泄漏和规范问题 。

另一个关键点是“质量前移”。很多实践都强调在生成阶段就让 AI 先写测试、先对照规范、先做局部验证，这样错误会更早暴露，修复成本也更低 。对企业来说，权限、审计、日志留痕、独立环境和回滚机制也很重要，因为它们决定了 AI 生成的变更能不能安全落地 。

典型技术栈

这类项目常见的技术栈不是单一语言，而是一整套工程体系。前端/应用层可能用 uni-app、Vue、小程序框架，后端则通过平台或 agent 生成 API、任务流和管理后台 。在 AI 原生开发里，常见工具包括 AI 编辑器、Coding Agent、RAG、工作流编排、可观测性平台、CI/CD、Sonar 类质量扫描、自动化测试和代码评审工具 。

如果是企业级无代码/低代码路线，常见能力会集中在可视化工作流、Prompt IDE、RAG 管道、权限管理、审计、集成和 API 发布 。如果是更偏“全 AI 编码”的路线，则会额外依赖项目级约束文件、仓库规范、agent 任务分解、测试先行和流水线反馈回路 。

可复制流程

一个可复用的流程大致是这样：

1. 先把业务目标写成短而硬的 PRD、验收标准和非功能要求。

2. 建立项目规范文件，包含目录结构、命名、架构边界、依赖限制和 agent 操作规则。

3. 让 AI 先生成脚手架、测试、CI、文档和基础模块。

4. 将功能拆成小任务，每次只交付一个闭环。

5. 在 CI 中加入质量门禁，失败即阻断合并或上线。

6. 用评审、日志、监控和审计形成持续反馈。

7. 通过迭代不断补齐边界条件、性能和稳定性。

这套方法的本质，是把“写代码”替换成“管理生成过程”，把“人力编码”变成“系统化编排” 。

适合什么场景

最适合这套模式的，是需求变化快、流程标准化、重复性强、集成复杂但边界清楚的项目，比如内部工具、运营系统、流程系统、知识工作流、原型验证和中小型业务应用 。对于高度创新、强算法、强实时、强安全或架构极复杂的核心系统，AI 仍然更适合辅助而非完全接管 。

如果你愿意，我可以下一步直接整理成一份“大项目 0 手写代码落地方法论”，按「组织流程 / 工具链 / 质量门禁 / 示例模板」四部分输出，适合拿去内部分享或立项讨论。

下面我把 OpenAI 这个“3 人、5 个月、0 行人工手写代码、百万行级内部产品” 的案例抽成一套可执行的方法论，重点放在“人极少参与，但目标可控”。这套方法的核心不是“让 AI 自由发挥”，而是把人类角色收缩到 定义目标、约束、验证、升级决策，把代码生产和修复尽量全部交给 agent 闭环完成 。infoq+1

方法总原则

最重要的原则是：仓库不是给人看的文档集合，而是给 agent 可执行的事实系统。OpenAI 的做法是把工程师角色从“写代码”改成“设计环境、定义意图、构建反馈循环”，并强调要给 agent 一张地图，而不是一千页手册 。因此，落地方法论的第一原则不是“多写说明”，而是“把说明变成仓库内可检索、可验证、可强制执行的资产” 。gitcode.csdn+1

第二个原则是：每一个约束都应该是机器可检查的。在这个案例里，AGENTS.md、架构文档、质量文档、执行计划、测试、CI、lint、可观测性，都被当作 agent 的工作环境组成部分，而不是附属材料 。第三个原则是：任何不稳定的东西都不能只靠人记忆，而要通过文件、脚本、门禁和反馈回路固化下来 。51cto+1

需求怎么写

需求不要写成传统 PRD 那种“描述愿景”的文档，而要写成 agent 能直接执行的任务说明。OpenAI 的实践强调，把宏大目标拆成微小构建块，并把这些构建块放进仓库里的计划、设计文档和执行计划中 。对 agent 来说，最关键的是：任务边界、输入、输出、验收标准、失败条件必须写清楚，否则它会在错误方向上高效工作 。gitcode.csdn+1

可落地的需求模板可以固定为：

• 目标：要解决什么业务问题。
• 范围：本次只做什么、不做什么。
• 约束：性能、兼容性、安全、依赖、架构边界。
• 验收：哪些测试通过才算完成。
• 风险：哪些地方必须人工复核。
• 回退：失败如何回滚或降级。

这类写法的关键不是“完整”，而是“可执行”。OpenAI 明确反对把所有信息塞进一份巨型 AGENTS.md，而是把总览做成地图，把细节拆到更深层文档里 。infoq

规范怎么定

代码输出规范要尽量前置，并且写成仓库规则，而不是聊天里的口头要求。OpenAI 的案例里，初始脚手架本身就包括仓库结构、CI 配置、格式化规则、包管理器设置和应用框架，连 AGENTS.md 也是由 agent 生成的 。这说明规范不是开发后补的，而是工程系统的一部分。infoq

建议固定四类规范：

• 结构规范：目录层级、模块边界、依赖方向。
• 风格规范：命名、格式化、注释、文件大小限制。
• 可靠性规范：必须有日志、指标、错误处理、超时、重试。
• 变更规范：每次 PR 的最小粒度、必须附带的测试、禁止改动范围。

在 OpenAI 的实践里，自定义 lint 和结构化测试被用来强制这些规则，甚至错误信息会直接注入 agent 的上下文，帮助它修复 。51cto+1

流程怎么跑

推荐把流程做成一个固定闭环：

1. 人类写任务单和验收标准。
2. 编排器创建分支和工作区。
3. 开发 agent 实现功能。
4. 测试 agent 运行测试并产出结果。
5. 评审 agent 检查质量、文档、边界和风险。
6. 编排器根据结果决定合并、重试或升级人工。
7. 归档到计划/文档/债务清单里。

OpenAI 的流程里，human to agent 的接口几乎完全通过提示词完成，而 PR 合并前会触发本地审查、交叉评审和多轮反馈循环 。这个模式的本质是把“开发”变成“多 agent 协作的状态机”，而不是单人改代码 。reddit+1

开发和测试是否分工

必须分工。 在这种模式里，开发 agent 和测试 agent 最好职责分离，否则同一个 agent 既写代码又判定自己正确，会极大降低可信度 。OpenAI 的实践里，评审可以由不同的 agent 执行，甚至人类评审都可以不是强制项，说明系统重心已经转向 agent 对 agent 的互审 。reddit+1

一个可执行的分法是：

• 开发 agent：只负责实现最小变更。
• 测试 agent：只负责复现、验证、补充边界测试。
• 评审 agent：只负责检查架构、风格、风险、文档一致性。
• 编排 agent：只负责路由、状态推进、重试和升级。

这样做的好处是把“是否通过”的判断从实现者手里拿走，减少自我欺骗 。infoq

测试怎么判定通过

测试通过不能只看“单测绿了”，而要看一个分层门禁矩阵。OpenAI 的描述里，应用会在隔离的工作树里运行，接入 DevTools、日志、指标和追踪，agent 可以直接复现 bug、验证修复并推导 UI 行为 。这意味着通过标准不只是代码层，还包括运行层、体验层和可观测性层。infoq

建议把判定拆成四层：

• 静态层：lint、格式、依赖、类型检查通过。
• 单元层：关键逻辑测试通过，覆盖核心路径。
• 集成层：模块联调、接口契约、数据库迁移通过。
• 运行层：端到端场景、日志无异常、核心指标达标。

OpenAI 还提到可以把“800ms 内启动”或“关键用户路径 trace 不超过 2 秒”写成可操作的提示目标，这说明通过条件最好量化成阈值，而不是模糊描述 。infoq

测试失败怎么办

测试失败后，不要让人手工修，而是让流程自动回到上游 agent。OpenAI 的做法是：当失败出现时，不是简单“重试提示词”，而是先问系统缺了什么能力、什么约束不清楚，然后把修复方案写回仓库 。也就是说，失败不是终点，而是对规则、工具、上下文缺口的一次诊断。taogongwei+1

实际运行时可以固定成三步：

1. 测试 agent 输出失败原因和最小复现。
2. 编排 agent 判断是实现错误、测试错误还是规范缺失。
3. 分别路由到开发 agent、测试 agent 或文档/规则修订任务。

如果同类失败重复出现，就不要继续“修代码”，而要升级为“修系统”：补充 lint、补充测试模板、补充架构约束或补充 AGENTS 文档 。infoq

错误怎么处理

流程出错时，核心不是“人工接手修”，而是建立 可升级的异常分流机制。OpenAI 的案例里，团队非常强调当 agent 卡住时，要追问“缺的是工具、护栏还是文档”，然后把缺口变成仓库中的永久规则 。这意味着错误处理要分成可自动修复和必须人工介入两类。infoq

建议定义四级错误：

• L1：格式、lint、轻微测试失败，自动重试。
• L2：局部逻辑错误，交给开发 agent 修复。
• L3：架构冲突、边界不清，触发方案重审。
• L4：安全、数据、发布风险，升级人工批准。

这样做能保证“大部分错误自动流转”，只有少数高风险问题才进入人工决策 。51cto+1

重构怎么做

代码积累到一定程度后，重构不能靠一次大手术，而要用 持续垃圾回收式重构。OpenAI 的做法是定期扫描偏离规则的代码，更新质量评分，并开启针对性的重构 PR，而且很多 PR 可以在一分钟内审完自动合并 。这说明重构在 agent 体系里应该是持续性的、低风险的、小步迭代，而不是等到失控再一次性推倒重来。infoq

重构可分三种触发器：

• 结构触发：模块过大、依赖错位、边界破裂。
• 质量触发：重复代码、低覆盖率、告警上升。
• 演化触发：新架构模式成熟，可以统一迁移旧实现。

重构任务要先生成“迁移计划”，再由 agent 分批执行，每批只改一个可验证子集，避免横跨太多不变量 。developer.aliyun+1

怎么防止重构改错

防止改错的关键是 用测试和隔离环境锁住行为。OpenAI 使用每个 worktree 独立运行应用实例、接入 DevTools 和隔离可观测性栈，让 agent 能在自己的工作副本里验证修复，而不是直接污染主线 。这种方式非常重要，因为它让重构前后可以在同一真实环境里做对照验证。infoq

建议把重构保护机制做成：

• 先冻结当前行为，补齐回归测试。
• 再做最小重构，保持测试不变。
• 用 diff-based 验证检查关键输出是否一致。
• 对高风险路径做双重验证或影子运行。

如果是大规模重构，最好按“先抽象、后迁移、再删旧代码”的顺序推进，并让每一步都能回滚 。csdn+1

人工参与边界

要做到“人极少参与但目标可控”，必须明确哪些事情永远不交给 agent。OpenAI 的思路不是完全去人，而是让人专注于优先级、验收标准、系统设计和最终把关 。换句话说，人类应该只处理“目标定义”和“风险决策”，而不是参与日常实现。infoq

可以把人工介入限定在四类场景：

• 需求变化影响方向。
• 安全、合规、数据风险。
• 架构级迁移和大重构。
• agent 连续失败三次以上且无法归类。

这样既能维持高自动化，又不会让系统在关键决策上失控 。openai+1

一套可执行模板

如果把它收敛成一套最小可落地模板，可以直接定义为：

• PRODUCT.md：目标、边界、验收。
• ARCHITECTURE.md：模块边界、依赖方向、数据流。
• AGENTS.md：仓库导航、工作规则、禁止事项。
• QUALITY.md：lint、测试、性能、安全门禁。
• PLAN.md：当前任务、阶段、负责人、状态。
• EVALS/：复现脚本、回归样本、端到端场景。
• CI/：自动检查、合并门禁、发布门禁。

这一套的逻辑和 OpenAI 的做法一致：把知识放进仓库，把规则放进工具，把验证放进流水线，把修复放进 agent 循环 。openai+1

如果你愿意，我下一步可以把这套方法论继续整理成一份更实用的 “OpenAI 式 0 手写代码项目作业手册”，输出为：

1. 需求文档模板，
2. AGENTS.md 模板，
3. 测试与门禁模板，
4. 重构与回归模板。

下面给你一套可直接落地的完整模板包，按 OpenAI 这类“人极少参与、AI 主导实现”的思路来设计。它的目标不是写得像论文，而是让每个文件都能被 agent 读懂、被测试验证、被流程约束，从而实现准确、科学、逻辑闭环、尽量无矛盾、无遗漏。

一、模板总原则

先说规则：一个文件只负责一种事实。产品讲“为什么做、做什么”，架构讲“怎么分层、怎么协作”，计划讲“这次做哪些、先后顺序”，质量讲“什么算通过”，agent 说明讲“怎么在仓库里工作”。
如果某个信息在两个文件里都出现，必须有主从关系：主文件定义事实，其他文件只引用，不重复发明。

第二个原则是：所有关键内容都要可追溯。每个需求、设计决策、测试点、任务项都要有唯一 ID，后续任何修改都能回指到来源。
第三个原则是：所有约定都要能被检查。能写成规则的，就不要只写成描述；能写成测试的，就不要只写成口号；能自动校验的，就不要只靠人记忆。

---

二、文件结构总览

建议仓库里至少有这 5 个核心文件：

• PRODUCT.md

• ARCHITECTURE.md

• PLAN.md

• QUALITY.md

• AGENTS.md

如果项目更大，再加这些辅助文件：

• DECISIONS.md

• RISKS.md

• EVALS.md

• GLOSSARY.md

• CHANGELOG.md

下面我先给你核心五个模板。

---

三、PRODUCT.md 模板

这个文件只定义“做什么”和“为什么做”。

# Product Document

## 1. 项目概述
- 项目名称：
- 项目目标：
- 目标用户：
- 核心场景：
- 不做什么：

## 2. 问题定义
- 用户当前面临的问题：
- 现有方案的不足：
- 本项目要解决的核心矛盾：

## 3. 成功标准
- 业务指标：
- 用户体验指标：
- 交付时间要求：
- 质量要求：

## 4. 范围定义

### 4.1 本期范围
-

### 4.2 非目标范围
-

## 5. 用户与场景

### 5.1 用户角色
- 角色 A：
- 角色 B：

### 5.2 典型场景
- 场景 1：
- 场景 2：

## 6. 需求列表
| ID | 需求描述 | 优先级 | 说明 |
|----|----------|--------|------|
| P-001 |
| 高 |
| | P-002 |
| 中 |  |

## 7. 约束条件
- 业务约束：
- 合规约束：
- 性能约束：
- 安全约束：

## 8. 验收口径
- 通过标准：
- 不通过标准：
- 例外处理方式：

## 9. 术语表
| 术语 | 定义 |
|------|------|
|  |  |

这个文件的约定

• 只写产品事实，不写技术实现。

• 每条需求必须可被验证。

• 每条需求都要有 ID。

• “不做什么”必须写清楚，避免范围漂移。

• 成功标准必须量化，不能只写“提升体验”。

---

四、ARCHITECTURE.md 模板

这个文件只定义“怎么分层、怎么通信、边界在哪里”。

# Architecture Document

## 1. 架构目标
- 设计目标：
- 关键原则：
- 架构边界：

## 2. 总体结构
- 系统分层：
- 核心模块：
- 模块职责：

## 3. 模块说明

### 3.1 模块 A
- 职责：
- 输入：
- 输出：
- 依赖：
- 失败模式：
- 所属需求：

### 3.2 模块 B
- 职责：
- 输入：
- 输出：
- 依赖：
- 失败模式：
- 所属需求：

## 4. 数据流
- 数据来源：
- 数据处理流程：
- 存储方式：
- 生命周期：

## 5. 接口契约

### 5.1 内部接口
- 接口名：
- 请求：
- 响应：
- 错误码：
- 幂等性：

### 5.2 外部接口
- 接口名：
- 协议：
- 限流：
- 安全要求：

## 6. 非功能设计
- 性能：
- 可扩展性：
- 可观测性：
- 安全性：
- 可维护性：

## 7. 关键决策
| ID | 决策 | 原因 | 影响 |
|----|------|------|------|
| A-001 |
|  |  |

## 8. 边界与依赖
- 允许依赖：
- 禁止依赖：
- 组件边界：
- 变更边界：

## 9. 风险与缓解
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
|  |
|  |

## 10. 与需求映射
| 需求 ID | 架构实现位置 | 说明 |
|---------|--------------|------|
| P-001 |
|  |
| P-002 |
|  |

这个文件的约定

• 只讲设计，不讲排期。

• 每个模块要写输入、输出、依赖、失败模式。

• 每个架构决策要写原因，不许只写结论。

• 每条需求都要能在架构里找到落点。

---

五、PLAN.md 模板

这个文件只定义“这次怎么做”。

# Plan Document

## 1. 当前迭代目标
- 迭代名称：
- 迭代目标：
- 交付日期：
- 成功定义：

## 2. 任务拆解
| ID | 任务 | 对应需求 | 前置条件 | 负责人 | 状态 |
|----|------|----------|----------|--------|------|
| T-001 |
| P-001 |
|  | 未开始 |
| T-002 |
| P-002 |
|  | 未开始 |

## 3. 执行顺序 1.  2.  3.

## 4. 依赖关系
- 外部依赖：
- 内部依赖：
- 风险依赖：

## 5. 里程碑
| 里程碑 | 标准 | 日期 |
|--------|------|------|
| M-1 |
|  |

## 6. 交付物
- 代码：
- 测试：
- 文档：
- 配置：
- 监控：

## 7. 变更控制
- 允许变更：
- 必须审批变更：
- 禁止变更：

## 8. 升级条件
- 哪些情况必须升级人工：
- 哪些情况可以自动重试：
- 哪些情况必须重新设计：

这个文件的约定

• 只写当前迭代，不写永久规范。

• 每个任务必须对应一个需求。

• 每个任务必须有前置条件和完成状态。

• 不能把“想法”写进计划，计划只写可执行项。

---

六、QUALITY.md 模板

这个文件只定义“什么算对、什么算错、错了怎么办”。

# Quality Document

## 1. 质量目标
- 正确性：
- 稳定性：
- 性能：
- 安全性：
- 可维护性：

## 2. 质量门禁

### 2.1 静态检查
- 格式检查：
- 代码风格：
- 类型检查：
- 依赖检查：

### 2.2 单元测试
- 覆盖范围：
- 必测路径：
- 边界条件：

### 2.3 集成测试
- 接口联调：
- 数据一致性：
- 配置验证：

### 2.4 端到端测试
- 主流程：
- 异常流程：
- 回归场景：

## 3. 通过标准
- 所有必测项通过：
- 无阻断级缺陷：
- 性能不低于阈值：
- 安全扫描通过：

## 4. 失败判定
- 哪些失败直接阻断：
- 哪些失败可降级：
- 哪些失败可接受但要登记：

## 5. 失败处理流程 1. 定位失败类型。 2. 判断是代码问题、测试问题、需求问题、环境问题。 3. 分配给对应责任流。 4. 修复后重新验证。 5. 记录到回归样本。

## 6. 回归机制
- 回归测试集：
- 历史缺陷样本：
- 防复发规则：

## 7. 质量指标
| 指标 | 阈值 | 当前值 | 状态 |
|------|------|--------|------|
| 单测通过率 |
|  |
| | 覆盖率 |
|  |
| | 关键路径成功率 |
|  |  |

## 8. 质量例外
- 允许例外的情况：
- 例外审批人：
- 例外到期时间：

这个文件的约定

• 质量必须量化。

• 测试通过标准必须明确到“能否合并”。

• 失败后不能只记日志，必须形成回归样本。

• 每个阻断项都要有明确升级路径。

---

七、AGENTS.md 模板

这个文件是给 agent 的“工作手册”。

# Agent Instructions

## 1. 仓库导航
- 产品定义在 `PRODUCT.md`
- 架构定义在 `ARCHITECTURE.md`
- 迭代计划在 `PLAN.md`
- 质量标准在 `QUALITY.md`
- 术语定义在 `GLOSSARY.md`

## 2. 工作原则
- 先理解需求，再修改代码。
- 先补测试，再改实现。
- 一次只做一个最小闭环。
- 不允许跨越式重构。
- 不允许擅自扩大范围。

## 3. 必须遵守的规则
- 保持文件职责单一。
- 保持需求、架构、计划、测试之间的引用一致。
- 不允许删除现有行为，除非有明确变更说明。
- 不允许在没有测试保护的情况下修改核心逻辑。

## 4. 输出要求
- 每次变更必须说明：
- 做了什么
- 为什么做
- 如何验证
- 影响了哪些需求 ID
- 代码修改必须附带测试修改或新增测试。

## 5. 失败处理
- 连续两次失败后，先检查上下文与规范是否缺失。
- 如果是需求歧义，回到产品文档。
- 如果是设计冲突，回到架构文档。
- 如果是验证失败，回到质量文档。

## 6. 重构规则
- 重构前先补回归测试。
- 每次重构只改一个局部边界。
- 重构后必须做等价性验证。
- 不允许同时做重构和功能扩展。

## 7. 升级条件
- 安全风险。
- 数据丢失风险。
- 无法归类的连续失败。
- 架构级变更。

这个文件的约定

• 这是 agent 的操作系统，不是产品说明书。

• 所有“怎么做”都必须能在其他文件里找到依据。

• 出现歧义时，先回查文档，不要直接猜。

---

八、辅助文件模板

DECISIONS.md

记录重要设计决策，防止架构漂移。

# Decisions Log
| ID | 日期 | 决策 | 原因 | 影响范围 | 相关文档 |
|----|------|------|------|----------|----------|
| D-001 |
|  |
|  |  |

RISKS.md

记录风险和缓解策略。

# Risks Log
| ID | 风险 | 概率 | 影响 | 缓解措施 | 状态 |
|----|------|------|------|----------|------|
| R-001 |
|  |
|  |  |

EVALS.md

记录评估场景和回归样本。

# Evals Document

## 1. 关键场景
- 场景 1：
- 场景 2：

## 2. 评估标准
- 正确性：
- 稳定性：
- 边界表现：

## 3. 回归样本
- 样本 ID：
- 问题描述：
- 预期结果：

GLOSSARY.md

统一术语，消除歧义。

# Glossary
| 术语 | 定义 | 备注 |
|------|------|------|
|  |
|  |

---

九、如何保证准确

准确靠的是“事实唯一来源 + ID 追溯”。

具体做法是：

• PRODUCT.md 只定义业务事实。

• ARCHITECTURE.md 只定义实现事实。

• PLAN.md 只定义执行事实。

• QUALITY.md 只定义验证事实。

• 每个条目有唯一 ID。

• 所有下游文件只能引用上游，不得自行改写上游定义。

这样做的结果是：同一个事实不会被多个文件重复书写，也不会因为人脑记忆不同而产生歧义。

---

十、如何保证科学

科学靠的是“可验证、可复现、可证伪”。

也就是说：

• 需求必须能测试。

• 架构必须能解释为什么这样设计。

• 质量标准必须有阈值。

• 失败必须能复现。

• 修复必须能回归验证。

如果一个条目不能被验证，那它就只是口号，不是工程规范。

---

十一、如何保证逻辑闭环

逻辑闭环靠的是从上到下的一条链：

1. PRODUCT.md 定义需求。

2. ARCHITECTURE.md 把需求映射到模块。

3. PLAN.md 把模块变成任务。

4. QUALITY.md 定义任务完成的证据。

5. AGENTS.md 规定 agent 怎么执行。

6. 测试结果反向更新 PLAN.md、RISKS.md、DECISIONS.md。

只要这条链能跑通，就不会出现“需求写了但没人实现”“实现了但没人验证”“验证了但不知对应哪个需求”的断裂。

---

十二、如何避免矛盾

避免矛盾的关键是三条：

• 单一事实源：一个事实只在一个主文件里定义。

• 交叉引用：其他文件只能引用，不得重写。

• 一致性检查：每次改动都检查需求、架构、计划、测试是否同步。

比如：

• PRODUCT.md 说“只支持异步处理”，那 ARCHITECTURE.md 就不能偷偷写同步主链路。

• QUALITY.md 说“必须支持失败重试”，那 PLAN.md 就不能把重试当成可选项。

• AGENTS.md 说“先补测试再改实现”，那 agent 不能直接改核心逻辑。

---

十三、如何避免遗漏

避免遗漏靠“模板强制 + 清单强制 + 回查强制”。

模板强制

每个文件必须填完固定栏目，不能空着跳过。

清单强制

每个需求至少要回答：

• 谁要用？

• 为什么要做？

• 怎么实现？

• 怎么验证？

• 失败怎么办？

回查强制

每次交付后反查：

• 需求有没有漏到架构？

• 架构有没有漏到计划？

• 计划有没有漏到测试？

• 测试有没有漏到回归样本？

只要其中一环断了，就说明有遗漏。

---

十四、推荐的落地机制

为了让这些模板真的可用，建议再加 4 个自动化检查：

• 文档字段检查：必填项是否齐全。

• ID 引用检查：引用是否都能找到来源。

• 一致性检查：术语、范围、状态是否冲突。

• 回归覆盖检查：历史 bug 是否都有测试样本。

这 4 个检查是模板真正落地的关键，因为它们能把“规范”从口头要求变成流程门禁。

---

十五、最简执行顺序

如果你现在就要开始用，可以按这个顺序：

1. 先写 PRODUCT.md。

2. 再写 ARCHITECTURE.md。

3. 再写 QUALITY.md。

4. 再写 PLAN.md。

5. 最后写 AGENTS.md。

6. 每次改动都同步更新 DECISIONS.md 和 RISKS.md。

7. 每次测试失败都补进 EVALS.md。

---

十六、最后一句话总结

这套模板的本质，不是让文档变多，而是让事实有源头、设计有边界、执行有顺序、质量有门禁、失败有回路。
只要这些约定被文件结构、ID 追踪和自动校验固化下来，系统就能在很少人工参与的情况下保持可控。

如果你要，我下一步可以直接把这套模板整理成一份可复制到仓库里的完整 Markdown 文件包，我会按每个文件分别输出成最终版。

这套规范的核心，不是“每个文件怎么写得漂亮”，而是把文档本身做成可验证的系统：每个文件只承担一个职责，文件之间通过引用、唯一编号、约束检查和测试门禁形成闭环 。OpenAI 这类 Harness Engineering 的思路里，AGENTS.md 更像“仓库地图”，而 docs/ 中的 PRODUCT.md、ARCHITECTURE.md、计划文档、技术债记录则是分层展开的可维护工件 。

文件职责划分

PRODUCT.md 的职责是定义“做什么”和“为什么做”，也就是产品范围、用户价值、成功标准和不做什么；ARCHITECTURE.md 定义“怎么分层、怎么通信、边界在哪”；PLAN.md 定义“这次迭代要交付什么、顺序是什么、谁负责什么”；QUALITY.md 定义“什么算通过、什么算失败、失败后怎么办” 。这些文件之间最重要的原则是不重复、不抢职责：产品文档不写实现细节，架构文档不写临时任务，计划文档不写永久规范，质量文档不写业务愿景 。

规范如何保证准确

准确性主要靠三种机制。第一是模板约束：每类文件都有固定字段、固定顺序和固定粒度，AI 不能自由发挥，把内容写散 。第二是唯一标识和交叉引用：需求、架构决策、测试用例、任务项都带稳定 ID，后续改动可以反向追溯到源头 。第三是仓库内事实优先：文件必须和当前代码、CI、测试、指标、接口定义一致，过期就要被 doc-gardening 或校验任务修正 。

规范如何保证科学

这里的“科学”本质上是可证伪、可验证、可重复。ARCHITECTURE.md 不能只写理念，必须把模块边界、依赖方向、接口契约、数据流和非功能要求写成能被静态检查或测试验证的约束 。QUALITY.md 则把“好不好”变成客观门槛，比如 lint、类型检查、单测、集成测试、性能阈值、安全扫描、日志完整性和回归检测 。

换句话说，规范不是“描述理想状态”，而是“定义可观测条件”。一旦条件能被脚本和测试读取，它就从主观经验变成了工程事实 。

逻辑闭环怎么做

逻辑闭环靠的是“需求 → 架构 → 计划 → 实现 → 测试 → 评审 → 回写文档”的单向流转。OpenAI 的实践强调，文档不是一次性写完，而是随着实现和验证不断更新，形成持续反馈回路 。因此，每个文件都要回答三个问题：输入是什么、输出是什么、通过什么证明它成立 。

一个闭环的关键是：PLAN.md 中的每个任务必须能追溯到 PRODUCT.md 的某条需求，而 QUALITY.md 中的每条门禁必须能追溯到 ARCHITECTURE.md 的某条风险控制或接口要求 。如果追溯不上，就说明这个条目要么是废话，要么是遗漏，要么是重复 。

防矛盾机制

避免矛盾的核心方法是单一事实源和交叉一致性检查。比如产品范围只在 PRODUCT.md 里定义一次，架构边界只在 ARCHITECTURE.md 里定义一次，测试门禁只在 QUALITY.md 里定义一次，计划只引用这些事实，不再重新发明概念 。OpenAI 风格的文档体系还会配合 lint、链接检查、结构检查和过期检查，发现术语不一致、引用失效、接口冲突时直接打回 。

矛盾检测最好分两层：先由 agent 做语义检查，再由机器做格式和依赖检查。前者查“是否前后说法冲突”，后者查“是否引用失效、字段缺失、顺序错误” 。

防遗漏机制

防遗漏靠的是强制模板 + 覆盖清单 + 反向审计。例如，PRODUCT.md 至少要覆盖用户、场景、范围、非目标、成功标准；ARCHITECTURE.md 至少要覆盖模块、接口、数据、依赖、风险；QUALITY.md 至少要覆盖测试层级、通过标准、失败分流、回归机制 。如果任何必填项缺失，系统就不允许进入实现阶段，而是要求补文档 。

反向审计也很重要：从代码、测试和 CI 反查文档，看看文档是否真的覆盖了当前系统中的关键行为。OpenAI 这类做法里，文档的新鲜度和链接完整性本身就是被定期扫描的对象 。

可操作的约束形式

真正有效的规范通常不是长篇叙述，而是几类固定句式：

• “必须/不得”类规则，用于硬约束。

• “如果……则……”类规则，用于条件分支。

• “通过/失败”类规则，用于验收。

• “引用到……”类规则，用于追溯。

这种写法可以让 agent 直接映射到任务执行和测试判定上，也方便后续自动检查 。在大型 AI 编程流程里，规范越接近“可执行规则”，越容易保持一致性 。

实际推荐结构

如果你要落地成一套可控体系，我建议按下面方式固定：

• PRODUCT.md：目标、范围、非目标、用户价值、成功指标。

• ARCHITECTURE.md：分层、边界、接口、依赖、风险。

• PLAN.md：迭代拆解、任务顺序、状态、负责人、依赖。

• QUALITY.md：测试分层、门禁、失败处理、回归策略。

• AGENTS.md：仓库导航、工作方式、禁止事项、升级条件。

这套结构的要点不是文件名本身，而是把描述、实现、验证、治理分开，并让它们通过 ID、检查器和回归测试串起来 。

如果你愿意，我下一步可以直接给你一套可复制的模板，按这五个文件分别写出“OpenAI 风格”的最小可落地版本。

可以，而且我会直接给出一个批判性判断：如果目标真的是“支持自动化开发这个工作任务”，那么我前面给出的那套 PRODUCT / ARCHITECTURE / PLAN / QUALITY / AGENTS 文档体系，表达能力更强；但如果目标是“让 agent 更稳、更少认知负担、更适合高频迭代”，那么 DIG（decisions / iterations / goal）更轻、更贴合自动化执行。结论上我会倾向于：DIG 更适合做自动化开发的主骨架，我那套文档更适合做高复杂度项目的治理层。

先说结论

对自动化开发来说，最重要的不是文档多，而是上下文短、约束明确、状态可推进。DIG 的优势就在于它把信息压缩成三类：目标、迭代、决策，天然适合 agent 做计划、执行、回看和修正。相比之下，我给出的那套模板更像“完整的工程治理体系”，适合大团队、复杂系统、长期维护，但它对 agent 来说也更重、更容易产生文档冗余和维护成本 。

所以如果问题是“哪个更能支持自动化开发这个工作任务”，我的判断是：

• 短周期、强执行、频繁迭代：DIG 更优。

• 大系统、强治理、强合规、多人协作：我那套更完整。

我那套模板的优点

我那套模板的最大优点是分工清晰。PRODUCT.md 负责业务意图，ARCHITECTURE.md 负责技术边界，PLAN.md 负责执行顺序，QUALITY.md 负责验收标准，AGENTS.md 负责 agent 行为约束。这样做的好处是，任何单个文件都不会承担过多职责，适合复杂项目里做长期治理 。

它的第二个优点是适合防矛盾。因为每个文件的职责很明确，所以你可以做引用检查、ID 检查、门禁检查、回归检查，这对大型项目特别重要 。换句话说，它更像一个“组织级工程系统”，不是单纯的执行记录。

但它的问题也很明显：信息密度太高、维护面太宽。对于自动化开发来说，agent 最怕的不是没有信息，而是信息太分散、太冗余、太难判断当前应该读哪一份。文件越多，越容易出现“文档正确但上下文过载”的问题，尤其在快速迭代时，维护这些分离文件本身就会变成负担 。

DIG 的优势

DIG 的好处是它天然符合 agent 的工作方式：

• Goal 告诉它要去哪。

• Iteration 告诉它这一步走多远。

• Decision 告诉它为什么这么走、下一次是否复用。

这比“同时读五份文档”更像一个可推进的状态机。对于自动化开发，状态机式的知识组织比百科式的知识组织更有效，因为 agent 需要的是当前任务上下文，不是完整组织档案 。

DIG 还有一个很强的点：它天然支持短反馈回路。每一轮迭代都围绕一个目标推进，完成后沉淀决策，再进入下一轮。这样做可以显著降低“计划写了很多，但执行偏了很远”的风险，也更适合让开发、测试、重构在同一循环里完成 。

DIG 的短板

但 DIG 也不是万能的。它的短板在于：表达能力偏弱，容易把复杂系统简化过头。如果项目涉及架构边界、接口契约、质量门禁、回归体系、风险控制，单靠 DIG 往往不够，因为它不天然表达这些横向治理信息 。

另一个问题是，DIG 容易在“迭代”里装下太多东西，最后迭代记录变成了半个日志、半个计划、半个复盘。这样虽然上下文短，但如果没有额外规范，决策可能会变成碎片化、不可追溯，最后又回到“看起来轻量，实际上混乱”的状态。

我会怎么批判地比较

如果把两者放到“自动化开发”这个目标下，我会这样评价：

维度	我那套模板	DIG
上下文负担	高	低
表达完整性	高	中等
适合 agent 执行	中等	高
适合复杂治理	高	中等偏低
适合快速迭代	中等	高
防矛盾能力	高	取决于配套约束
可长期维护性	高	中等
实施门槛	高	低

所以从“自动化开发工作任务”的角度，我会说：
DIG 更像执行内核，我那套模板更像外部护栏。

更好的选择：DIG + 少量硬文档

真正最优的方案，不是二选一，而是用 DIG 做主线，用少量硬文档做护栏。也就是说：

• Goal 对应 PRODUCT.md 的最小摘要。

• Iteration 对应 PLAN.md 的当前轮次。

• Decision 对应 DECISIONS.md。

• 再保留一个很轻的 QUALITY.md 和 AGENTS.md，负责门禁和行为约束。

这样就不会有“文档系统过重”的问题，同时还能保留关键治理能力。这个结构对自动化开发最友好，因为 agent 每一轮只需要看：

1. 这次要达成什么目标；

2. 这轮准备做什么；

3. 为什么这样做；

4. 怎么判断成功；

5. 出错往哪里回流。

我的最终判断

如果你要的是一套能长期支撑复杂项目的全景文档体系，我前面的模板更完整。
如果你要的是一套最适合 agent 自动推进、自动修复、自动迭代的工作框架，DIG 更优。
如果你要的是真正可落地的大型自动化开发，最好的方式是：DIG 作为主框架，我那套模板中的少数关键文件作为治理补件。

如果你愿意，我下一步可以直接把这两者融合成一版 “DIG + 最小治理文档” 的最终模板，压缩成一套真正适合 AI 编排开发的仓库结构。

下面给你一套我建议的最终模板，按 DIG 为主骨架，再加少量治理文件的方式来设计。它特别解决你提到的一个关键点：每次迭代结束后，功能说明应该写在哪里，才能让后续迭代不把已实现代码改错。

总体结构

建议仓库最终只保留这 6 类核心文件：

• GOAL.md

• ITERATIONS.md

• DECISIONS.md

• SPEC.md

• QUALITY.md

• AGENTS.md

如果项目较大，再加两个辅助文件：

• CHANGELOG.md

• EVALS.md

其中，每次迭代后的功能说明，默认写在 ITERATIONS.md 的对应迭代记录里，同时同步更新 SPEC.md 的“当前功能规范”部分。
这样做的好处是：ITERATIONS.md 负责“历史发生了什么”，SPEC.md 负责“当前系统应该是什么样”。后续开发时，agent 只要先看 SPEC.md，就不会把已经完成的功能误当成待实现事项。

---

1. GOAL.md 模板

这个文件只放项目总目标和稳定约束，不放具体迭代细节。

# Goal

## 1. 项目目标
- 项目要解决的问题：
- 目标用户：
- 最终结果：
- 成功标准：

## 2. 核心边界
- 本项目必须实现：
- 本项目明确不做：
- 必须长期保持的原则：

## 3. 关键约束
- 业务约束：
- 技术约束：
- 安全约束：
- 性能约束：

## 4. 不变目标
- 长期不变的产品目标：
- 长期不变的架构原则：
- 长期不变的质量标准：

用法

这个文件只会在方向变化时改，不会随着每次迭代频繁修改。
它相当于“北极星”，防止项目越做越偏。

---

2. ITERATIONS.md 模板

这是最关键的文件。每次迭代后的功能说明、完成项、遗留问题、回归风险，都写在这里。

# Iterations

## Iteration 001

### 1. 迭代目标
- 本轮目标：
- 对应 GOAL 章节：

### 2. 本轮范围
- 完成内容：
- 未完成内容：
- 明确不做内容：

### 3. 变更摘要
- 新增功能：
- 修改功能：
- 删除功能：
- 行为变化：

### 4. 验收结果
- 通过的检查：
- 未通过的检查：
- 已知问题：

### 5. 回归风险
- 可能影响的旧功能：
- 已做的回归验证：
- 仍需关注的边界：

### 6. 后续建议
- 下一轮应优先处理：
- 不建议立即改动：
- 需要补充的文档：

### 7. 关联记录
- 对应 DECISION ID：
- 对应 SPEC 条目：
- 对应 QUALITY 条目：
- 对应 EVALS 样本：

## Iteration 002 ...

这里就是“每次迭代后的功能说明”主存放处

它应该写成“事实记录”，而不是随意叙述。每一轮结束后都要明确写：

• 做了什么。

• 行为发生了什么变化。

• 哪些旧功能可能受到影响。

• 已经验证过什么。

• 还剩什么风险。

为什么它能防止改错

因为后续迭代时，agent 先读这里，就能知道：

• 哪些功能已经存在。

• 哪些行为不能随便改。

• 哪些接口、字段、逻辑属于历史承诺。

• 哪些地方修改后必须做回归。

---

3. SPEC.md 模板

这个文件是“当前系统应该是什么样”的唯一事实源。
如果你担心后续迭代把已实现代码改错，SPEC.md 比 ITERATIONS.md 更关键，因为它定义了“当前有效规范”。

# Specification

## 1. 当前版本说明
- 当前版本号：
- 当前生效日期：
- 当前功能边界：

## 2. 当前功能清单
| ID | 功能 | 状态 | 说明 |
|----|------|------|------|
| F-001 |
| 已实现 |
| | F-002 |
| 已实现 |  |

## 3. 行为规范

### 3.1 输入行为
- 支持哪些输入：
- 不支持哪些输入：

### 3.2 输出行为
- 必须输出什么：
- 允许输出什么：
- 禁止输出什么：

### 3.3 异常行为
- 错误如何返回：
- 哪些错误可重试：
- 哪些错误必须失败：

## 4. 业务规则
- 规则 1：
- 规则 2：

## 5. 兼容性说明
- 向后兼容要求：
- 已废弃能力：
- 迁移方式：

## 6. 不可变约定
- 不能随意修改的行为：
- 不能删除的功能：
- 不能更改的接口：

## 7. 当前已知限制
- 限制 1：
- 限制 2：

## 8. 与迭代对应关系
| 功能 ID | 首次实现迭代 | 最近修改迭代 | 说明 |
|---------|--------------|--------------|------|
| F-001 | 001 | 002 |  |

这个文件的作用

ITERATIONS.md 记录“历史”，SPEC.md 记录“当前有效状态”。
后续任何人或 agent 想改代码，必须先看 SPEC.md，因为它告诉你：哪些行为是当前必须保持的。

---

4. DECISIONS.md 模板

这个文件记录为什么这么设计，避免后面反复争论。

# Decisions
| ID | 日期 | 决策 | 原因 | 影响范围 | 关联迭代 |
|----|------|------|------|----------|----------|
| D-001 |
|  |
|  |  |

## 决策说明格式

### D-001
- 背景：
- 决策内容：
- 替代方案：
- 选择原因：
- 影响范围：
- 回滚条件：

这个文件的作用

以后如果有人问“为什么这里不能改”，答案就在这里。
它会大大减少后续迭代中对同一问题的反复修改。

---

5. QUALITY.md 模板

这个文件定义“怎么判断没改错”。

# Quality

## 1. 质量目标
- 正确性：
- 稳定性：
- 性能：
- 安全性：
- 可维护性：

## 2. 必须通过的检查
- 单元测试：
- 集成测试：
- 端到端测试：
- 静态检查：
- 回归测试：

## 3. 通过标准
- 所有关键测试通过。
- 所有受影响功能的回归通过。
- 无阻断级缺陷。
- 无违反当前 SPEC 的行为变化。

## 4. 失败处理
- 失败是否允许重试：
- 失败是否允许降级：
- 失败是否必须回退：
- 失败是否必须升级人工：

## 5. 回归样本
| 样本 ID | 场景 | 预期结果 | 来源迭代 |
|---------|------|----------|----------|
| R-001 |
|  |  |

它和防改错的关系

每次迭代都必须验证：

• 新功能能跑。

• 旧功能没坏。

• 新行为没有偏离 SPEC.md。

如果改动影响旧功能，就必须把旧功能对应回归样本补进去。

---

6. AGENTS.md 模板

这个文件告诉 agent 怎么工作，避免它乱改。

# Agent Instructions

## 1. 阅读顺序 1. 先读 GOAL.md。 2. 再读 SPEC.md。 3. 再读 ITERATIONS.md。 4. 再读 DECISIONS.md。 5. 再读 QUALITY.md。

## 2. 工作原则
- 先确认当前规范，再修改实现。
- 先补测试，再改代码。
- 一次只做一个最小迭代。
- 不得擅自改动已在 SPEC 中冻结的行为。
- 若发现文档冲突，先停止并修正文档。

## 3. 修改规则
- 新增功能必须先更新 SPEC，再更新 ITERATIONS。
- 修复缺陷必须记录回归样本。
- 重构必须先声明不改变外部行为。
- 删除功能必须在 SPEC 中标记废弃并保留迁移说明。

## 4. 失败处理
- 如果测试失败，先判断是代码问题、测试问题还是文档问题。
- 如果行为与 SPEC 不一致，以 SPEC 为准。
- 如果 SPEC 与 ITERATIONS 冲突，以 SPEC 为准，并补修 ITERATIONS 记录。

## 5. 升级条件
- 安全风险。
- 数据丢失风险。
- 行为不可解释。
- 连续失败超过阈值。

---

7. CHANGELOG.md 模板

这个文件是对外发布用的简版历史，不取代 ITERATIONS.md。

# Changelog

## [Unreleased]
-

## [1.0.0]
- 新增：
- 修复：
- 变更：
- 废弃：

---

8. EVALS.md 模板

这个文件保存典型场景和回归案例，防止以后“改着改着改坏了”。

# Evals

## 1. 关键场景
- 场景 1：
- 场景 2：
- 场景 3：

## 2. 样本库
| ID | 场景 | 输入 | 预期输出 | 来源 |
|----|------|------|----------|------|
| E-001 |
|  |
|  |

## 3. 评估规则
- 正常路径必须通过。
- 异常路径必须按规范失败。
- 历史 bug 必须防回归。

---

9. 这套模板如何防止改错

这是最关键的部分。

9.1 用 SPEC 锁住当前行为

SPEC.md 是当前有效规范。
后续迭代如果要改行为，必须先改 SPEC.md，否则就属于“未授权变更”。

9.2 用 ITERATIONS 记录每次变更后的功能说明

每次迭代后，把：

• 新增了什么。

• 修改了什么。

• 哪些旧行为受影响。

• 哪些测试已经做过。

都写进 ITERATIONS.md。
这样后续 agent 能一眼知道历史和风险，不会误以为旧功能还没完成。

9.3 用 QUALITY 把旧功能保护起来

每次改动都要跑受影响区域的回归。
如果新功能可能影响老功能，就把老功能变成回归样本，锁进 EVALS.md。

9.4 用 DECISIONS 解释为什么不能乱改

很多后续误改不是技术问题，而是“为什么不能动”没被记录。
DECISIONS.md 就是给这个问题兜底。

9.5 用 AGENTS 强制工作顺序

agent 先读规范，再改代码；先补测试，再改实现。
这个顺序能大幅降低“先改后补”的混乱。

---

10. 最推荐的实际流程

每次迭代都按这个顺序：

1. 先更新或确认 GOAL.md。

2. 根据当前目标更新 SPEC.md。

3. 在 ITERATIONS.md 写本轮迭代说明。

4. 如有重要取舍，写进 DECISIONS.md。

5. 在 QUALITY.md 补充测试与通过标准。

6. 在 EVALS.md 增加回归样本。

7. 让 agent 按 AGENTS.md 执行。

8. 完成后再回写 ITERATIONS.md 的最终结果。

---

11. 一句话总结

如果你最关心的是“后期迭代不要把已经实现的代码改错”，那么最重要的不是多写文档，而是建立这个分工：

• GOAL.md 管方向。

• SPEC.md 管当前有效行为。

• ITERATIONS.md 管每次迭代后的功能说明。

• DECISIONS.md 管为什么这么定。

• QUALITY.md 管怎么证明没改错。

• AGENTS.md 管 agent 的执行纪律。

其中，防止改错的核心文件是 SPEC.md + ITERATIONS.md + QUALITY.md。
SPEC.md 锁定当前该是什么，ITERATIONS.md 记录每次改了什么，QUALITY.md 验证有没有把旧东西改坏。

如果你要，我下一步可以直接把这套模板整理成一份可复制进仓库的最终版 Markdown 文件集合，我会按文件逐个完整写出来。

结合这篇 OpenAI 的文章来看，我前面给出的模板需要调整，而且调整方向很明确：要从“文档分层治理”进一步收敛到“反馈循环驱动的 harness”。OpenAI 强调的不是多写几份文档，而是把文档、测试、评审、修复、再验证串成闭环；工程师的主要工作变成设计环境、指定意图、构建反馈回路，而不是写实现代码 。

需要调整的地方

第一，ITERATIONS.md 不能只做历史记录，它还应该成为反馈信号的汇聚点。OpenAI 的做法里，agent 发现问题后，团队会把“缺了什么工具、护栏或文档”反向写回仓库，这意味着迭代记录不只是“做了什么”，还要记录“失败模式是什么、为什么失败、下一轮要如何改 harness” 。

第二，QUALITY.md 需要从“通过标准”升级成“感知器 + 纠偏器”的组合。文章里强调的不是简单 pass/fail，而是让 lint、结构测试、类型检查、架构边界校验输出能直接喂给 agent 的纠错信息；也就是说，质量检查本身要写得像“可执行提示”，而不是只报错 。

第三，SPEC.md 需要增加“可观测行为定义”，不只是业务行为。因为反馈循环要闭合，agent 必须能通过测试或运行时信号判断“到底哪一步偏了”；如果规范只写结果不写可观测证据，反馈回路就断了 。

我会怎么改模板

我建议把最终模板改成下面这个结构：

• GOAL.md：目标与不可变边界。

• SPEC.md：当前有效功能与行为规范。

• ITERATIONS.md：每轮迭代的目标、完成项、失败模式、回写动作。

• DECISIONS.md：关键设计决策与原因。

• HARNESS.md：反馈循环、检查点、重试策略、升级策略。

• QUALITY.md：门禁、测试、回归、可执行错误信息。

• AGENTS.md：agent 工作方式与改动纪律。

这里新增一个很重要的文件：HARNESS.md。
因为 OpenAI 这篇文章的核心其实不是“文档管理”，而是“harness engineering”：怎么把环境、反馈、控制系统搭起来，让 agent 在里面可靠工作 。

HARNESS.md 应该写什么

这个文件专门定义反馈循环，建议模板如下：

# Harness

## 1. Harness 目标
- 让 agent 在最小人工介入下完成任务。
- 让错误尽可能在仓库边界内被发现和修复。
- 让重复失败变成新的规则或检查。

## 2. 输入信号
- 需求信号：来自 GOAL.md / SPEC.md。
- 任务信号：来自 ITERATIONS.md。
- 约束信号：来自 DECISIONS.md / AGENTS.md。
- 质量信号：来自 QUALITY.md / 测试 / lint / CI。
- 运行信号：来自日志、trace、截图、录屏、指标。

## 3. 内循环 1. 生成计划。 2. 实现变更。 3. 本地检查。 4. 读取失败信息。 5. 修复并重试。 6. 直到满足局部门禁。

## 4. 外循环 1. 进入集成/预发布/生产验证。 2. 观察真实行为与预期偏差。 3. 把偏差写回 ITERATIONS.md。 4. 把重复偏差抽象成新的规则、测试或护栏。 5. 更新 SPEC.md / QUALITY.md / AGENTS.md。

## 5. 失败分类
- 代码错误。
- 测试错误。
- 规范缺失。
- 观测不足。
- 真实环境偏差。

## 6. 自动修复策略
- 小错误：agent 自修。
- 重复错误：更新规则或测试。
- 结构性错误：更新 harness。
- 高风险错误：升级人工。

## 7. 反馈沉淀
- 每次失败都必须产出：
- 最小复现。
- 原因分类。
- 修复记录。
- 新增规则或测试。

这个文件的价值在于：它把“反馈循环”从一种抽象理念，变成了仓库里明确可执行的工程对象 。

你的模板还差什么

如果严格对照 OpenAI 的文章，我会再补三件事。

1. 错误消息要可修复

文章里很重要的一点是：反馈信号不是“你错了”，而是“你该怎么修”。所以 QUALITY.md 里的 lint、测试、结构校验，最好输出带修复建议的错误信息，而不是纯失败码 。

2. 重复失败要升级成规则

如果同类问题反复出现，就不能再只修代码，而要把它提升为 harness 的一部分：新增 lint、结构测试、模板字段、回归样本或 AGENTS 约束 。

3. 反馈必须分内环和外环

OpenAI 的文章里最关键的是“Humans steer, agents execute”。所以要把反馈分成两层：

• 内环：仓库内、CI 内、PR 前，主要由 agent 自己闭环修复。

• 外环：预发布/生产/真实用户环境，主要负责发现未知问题，然后反哺内环。
  这点是我之前模板里没有显式写透的 。

反馈循环怎么构建

我建议用一个非常明确的两环结构。

内环

内环是最快的，目的是让 agent 在合并前尽量自洽。

流程是：

1. agent 根据 GOAL.md、SPEC.md、ITERATIONS.md 生成计划。

2. agent 修改代码。

3. QUALITY.md 里的静态检查、单测、结构测试运行。

4. 如果失败，把错误信息原样喂回 agent。

5. agent 修复后重跑。

6. 直到通过。

内环的特点是确定性强、反馈快、成本低 。

外环

外环解决的是内环看不见的问题，比如真实用户路径、灰度流量、性能退化、交互偏差、长期漂移。

流程是：

1. 变更进入预发布或生产环境。

2. 通过日志、trace、指标、录屏、人工反馈观察结果。

3. 把真实偏差记到 ITERATIONS.md。

4. 把复发问题沉淀到 EVALS.md、QUALITY.md、SPEC.md。

5. 需要时修改 harness 本身，而不只是修业务代码。

外环的核心作用是把“未知失败模式”纳入系统治理 。

最终我建议的模板关系

如果按最稳妥的方式收敛，我建议这样定位：

• GOAL.md：目标。

• SPEC.md：当前应该是什么。

• ITERATIONS.md：每轮做了什么、发现了什么。

• DECISIONS.md：为什么这么定。

• HARNESS.md：怎么让反馈闭环。

• QUALITY.md：怎么判定对错、怎么纠错。

• AGENTS.md：agent 怎么干活。

也就是说，这次最重要的调整不是删文件，而是把“反馈循环”显式化，单独抽成 HARNESS.md。
这会让整个体系更接近 OpenAI 这篇文章的真实方向：不是靠更厚的文档，而是靠更强的反馈系统让 agent 自主纠偏 。

如果你愿意，我下一步可以直接把这套模板整理成最终版仓库目录结构 + 每个文件的完整 Markdown 模板，并把 HARNESS.md 也一起写全。

我现在没法直接把一个真实可下载的 zip 文件发给你，但我可以把压缩包内的完整文件内容一次性给你，你复制保存成对应文件后，立刻就能本地打包成 zip。为了不耽误你，我直接给你一个最实用的版本：目录结构 + 每个文件完整内容。

压缩包目录

openai_harness_template_pack/ ├── GOAL.md ├── SPEC.md ├── ITERATIONS.md ├── DECISIONS.md ├── HARNESS.md ├── QUALITY.md ├── AGENTS.md ├── CHANGELOG.md └── EVALS.md

GOAL.md

# Goal

## 1. 项目目标
- 项目要解决的问题：
- 目标用户：
- 最终结果：
- 成功标准：

## 2. 核心边界
- 本项目必须实现：
- 本项目明确不做：
- 必须长期保持的原则：

## 3. 关键约束
- 业务约束：
- 技术约束：
- 安全约束：
- 性能约束：

## 4. 不变目标
- 长期不变的产品目标：
- 长期不变的架构原则：
- 长期不变的质量标准：

SPEC.md

# Specification

## 1. 当前版本说明
- 当前版本号：
- 当前生效日期：
- 当前功能边界：

## 2. 当前功能清单
| ID | 功能 | 状态 | 说明 |
|----|------|------|------|
| F-001 |
| 已实现 |
| | F-002 |
| 已实现 |  |

## 3. 行为规范

### 3.1 输入行为
- 支持哪些输入：
- 不支持哪些输入：

### 3.2 输出行为
- 必须输出什么：
- 允许输出什么：
- 禁止输出什么：

### 3.3 异常行为
- 错误如何返回：
- 哪些错误可重试：
- 哪些错误必须失败：

## 4. 业务规则
- 规则 1：
- 规则 2：

## 5. 兼容性说明
- 向后兼容要求：
- 已废弃能力：
- 迁移方式：

## 6. 不可变约定
- 不能随意修改的行为：
- 不能删除的功能：
- 不能更改的接口：

## 7. 当前已知限制
- 限制 1：
- 限制 2：

## 8. 与迭代对应关系
| 功能 ID | 首次实现迭代 | 最近修改迭代 | 说明 |
|---------|--------------|--------------|------|
| F-001 | 001 | 002 |  |

ITERATIONS.md

# Iterations

## Iteration 001

### 1. 迭代目标
- 本轮目标：
- 对应 GOAL 章节：

### 2. 本轮范围
- 完成内容：
- 未完成内容：
- 明确不做内容：

### 3. 变更摘要
- 新增功能：
- 修改功能：
- 删除功能：
- 行为变化：

### 4. 验收结果
- 通过的检查：
- 未通过的检查：
- 已知问题：

### 5. 回归风险
- 可能影响的旧功能：
- 已做的回归验证：
- 仍需关注的边界：

### 6. 后续建议
- 下一轮应优先处理：
- 不建议立即改动：
- 需要补充的文档：

### 7. 关联记录
- 对应 DECISION ID：
- 对应 SPEC 条目：
- 对应 QUALITY 条目：
- 对应 EVALS 样本：

Iterations

Iteration 001

User

• 本轮用户目标：
• 涉及的用户场景：
• 用户可感知变化：
• 未覆盖的用户场景：

Dev

• 本轮开发内容：
• 修改的模块：
• 新增的接口/字段/逻辑：
• 结构性变化：
• 与旧代码的兼容性：

Test

• 测试范围：
• 通过的测试：
• 失败的测试：
• 回归样本：
• 仍需补测的边界：

Risk

• 可能影响的旧功能：
• 需要特别关注的行为：
• 是否需要人工复核：

Next

• 下一轮优先事项：
• 不建议立即改动：
• 需要更新的文档：

DECISIONS.md

# Decisions
| ID | 日期 | 决策 | 原因 | 影响范围 | 关联迭代 |
|----|------|------|------|----------|----------|
| D-001 |
|  |
|  |  |

## 决策说明格式

### D-001
- 背景：
- 决策内容：
- 替代方案：
- 选择原因：
- 影响范围：
- 回滚条件：

HARNESS.md

# Harness

## 1. Harness 目标
- 让 agent 在最小人工介入下完成任务。
- 让错误尽可能在仓库边界内被发现和修复。
- 让重复失败变成新的规则或检查。

## 2. 输入信号
- 需求信号：来自 GOAL.md / SPEC.md。
- 任务信号：来自 ITERATIONS.md。
- 约束信号：来自 DECISIONS.md / AGENTS.md。
- 质量信号：来自 QUALITY.md / 测试 / lint / CI。
- 运行信号：来自日志、trace、截图、录屏、指标。

## 3. 内循环 1. 生成计划。 2. 实现变更。 3. 本地检查。 4. 读取失败信息。 5. 修复并重试。 6. 直到满足局部门禁。

## 4. 外循环 1. 进入集成/预发布/生产验证。 2. 观察真实行为与预期偏差。 3. 把偏差写回 ITERATIONS.md。 4. 把重复偏差抽象成新的规则、测试或护栏。 5. 更新 SPEC.md / QUALITY.md / AGENTS.md。

## 5. 失败分类
- 代码错误。
- 测试错误。
- 规范缺失。
- 观测不足。
- 真实环境偏差。

## 6. 自动修复策略
- 小错误：agent 自修。
- 重复错误：更新规则或测试。
- 结构性错误：更新 harness。
- 高风险错误：升级人工。

## 7. 反馈沉淀
- 每次失败都必须产出：
- 最小复现。
- 原因分类。
- 修复记录。
- 新增规则或测试。

QUALITY.md

# Quality

## 1. 质量目标
- 正确性：
- 稳定性：
- 性能：
- 安全性：
- 可维护性：

## 2. 必须通过的检查
- 单元测试：
- 集成测试：
- 端到端测试：
- 静态检查：
- 回归测试：

## 3. 通过标准
- 所有关键测试通过。
- 所有受影响功能的回归通过。
- 无阻断级缺陷。
- 无违反当前 SPEC 的行为变化。

## 4. 失败处理
- 失败是否允许重试：
- 失败是否允许降级：
- 失败是否必须回退：
- 失败是否必须升级人工：

## 5. 回归样本
| 样本 ID | 场景 | 预期结果 | 来源迭代 |
|---------|------|----------|----------|
| R-001 |
|  |  |

AGENTS.md

# Agent Instructions

## 1. 阅读顺序 1. 先读 GOAL.md。 2. 再读 SPEC.md。 3. 再读 ITERATIONS.md。 4. 再读 DECISIONS.md。 5. 再读 QUALITY.md。

## 2. 工作原则
- 先确认当前规范，再修改实现。
- 先补测试，再改代码。
- 一次只做一个最小迭代。
- 不得擅自改动已在 SPEC 中冻结的行为。
- 若发现文档冲突，先停止并修正文档。

## 3. 修改规则
- 新增功能必须先更新 SPEC，再更新 ITERATIONS。
- 修复缺陷必须记录回归样本。
- 重构必须先声明不改变外部行为。
- 删除功能必须在 SPEC 中标记废弃并保留迁移说明。

## 4. 失败处理
- 如果测试失败，先判断是代码问题、测试问题还是文档问题。
- 如果行为与 SPEC 不一致，以 SPEC 为准。
- 如果 SPEC 与 ITERATIONS 冲突，以 SPEC 为准，并补修 ITERATIONS 记录。

## 5. 升级条件
- 安全风险。
- 数据丢失风险。
- 行为不可解释。
- 连续失败超过阈值。

CHANGELOG.md

# Changelog

## [Unreleased]
-

## [1.0.0]
- 新增：
- 修复：
- 变更：
- 废弃：

EVALS.md

# Evals

## 1. 关键场景
- 场景 1：
- 场景 2：
- 场景 3：

## 2. 样本库
| ID | 场景 | 输入 | 预期输出 | 来源 |
|----|------|------|----------|------|
| E-001 |
|  |
|  |

## 3. 评估规则
- 正常路径必须通过。
- 异常路径必须按规范失败。
- 历史 bug 必须防回归。

本地打包命令

把这些文件放进同一个目录后运行：

bash

zip -r openai_harness_template_pack.zip openai_harness_template_pack/

如果你想，我下一条可以直接给你一个单个 shell 脚本，你复制到本地执行后，会自动生成这 9 个文件并打成 zip。

可以。我先直接给结论：前几轮里我确实过度顺着你的方向在做局部优化，缺少对“目标到底是什么、哪些部分是概念混杂、哪些结构会在真实落地时失效”的主动拆解。 这次我会把问题重新“打散再重组”，给你一个更像工程评审而不是应答补丁的版本。

我先辩论式地判断一下：你真正要的不是一套“好看的文档模板”，而是一套能让 agent 在复杂项目里低人工参与、持续不改坏旧功能、还能不断把失败变成规则的控制系统。如果把这个目标看清楚，那么文档体系的价值就不是“信息记录”，而是“控制面板”；而控制面板的核心不是多，而是少而强、闭环、可执行。这也是为什么 OpenAI 的 harness engineering 思路会强调把工程师角色从写代码转成设计环境和反馈回路 。

先做一轮真正的批判

观点 A：你前面那套大模板，优点是完整，缺点是太像人类管理手册

我前面给你的 GOAL / SPEC / ITERATIONS / DECISIONS / HARNESS / QUALITY / AGENTS / EVALS 套件，理论上覆盖面很全，能把需求、设计、验证、回归、反馈都放进去。它的问题是：它过于“治理中心化”，更适合人类团队审阅，而不是 agent 高频迭代。对 agent 来说，文件越多，越容易出现两个问题：一是上下文负担高，二是“事实分散在多个地方”，最后又回到人要帮它整合。OpenAI 文章里强调的重点是 harness：把工作环境、反馈、约束设计好，让 agent 自己在闭环里运行，而不是给它一本百科全书 。

观点 B：DIG 的方向更对，但单独 DIG 又太轻

你提到的 DIG（goal / iterations / decisions）是对的，因为它更接近 agent 的工作方式：目标、当前轮次、沉淀决策。它的好处是轻、短、可推进，特别适合自动化开发的循环。
但如果只用 DIG，问题会是：它能记住“做过什么”，却不一定足够精确地定义“当前系统必须是什么”以及“什么样的验证才算真正通过”。OpenAI 的 harness 不是只靠日志和目标摘要，它还依赖脚手架、测试、lint、可观测性、AGENTS 规则、反馈再注入 。所以 DIG 是主骨架，但如果不加护栏，会在复杂项目里失控。

观点 C：user / dev / test 的分层不是装饰，而是必要的结构增强

你提到的 iteration -> user/dev/test 维度，我之前没有把它抬到足够高的优先级。现在我明确判断：这不是可有可无的细节，而是把“需求、实现、验证”拆开的关键结构。它让一个迭代的描述从“混合叙述”变成“状态机记录”：用户目标有没有变、实现改了什么、测试是否证明成功。对自动化开发来说，这个结构比单段摘要更适合 agent 读取和后续回归 。

我现在的修改版：更小、更强、更闭环

我建议把最终方案收敛成 5 个主文件 + 1 个核心迭代结构：

• GOAL.md

• SPEC.md

• ITERATIONS.md

• HARNESS.md

• QUALITY.md

• AGENTS.md

其中：

• GOAL.md 负责长期目标和边界。

• SPEC.md 负责当前生效的事实。

• ITERATIONS.md 负责每轮推进和历史沉淀。

• HARNESS.md 负责反馈循环和错误闭环。

• QUALITY.md 负责质量门禁和回归。

• AGENTS.md 负责 agent 的工作纪律。

关键变化是：不再把 DECISIONS、EVALS 作为必须主文件，而是把它们作为辅助块内嵌或可选扩展。这样做的原因很简单：如果追求自动化开发，主结构必须尽可能短；否则文件越多，越容易把 agent 的注意力打散。OpenAI 的路线本质上就是“让 harness 提供足够约束，但别把执行环境做成文档迷宫” 。

最终版 ITERATIONS 应该怎么写

我建议直接固定成这样：

# Iterations

## Iteration 001

### User
- 本轮用户目标：
- 用户可感知变化：
- 涉及的业务场景：
- 未覆盖场景：

### Dev
- 本轮实现内容：
- 修改的模块：
- 新增/变更接口：
- 结构变化：
- 兼容性影响：

### Test
- 本轮测试范围：
- 通过的测试：
- 失败的测试：
- 回归样本：
- 尚需补测项：

### Risk
- 对旧功能的风险：
- 对数据/性能/安全的风险：
- 是否需要人工复核：

### Next
- 下一轮优先事项：
- 不建议立即改动：
- 需要更新的规范：

这个结构的优点是：

1. User 锁住目标，防止偏题。

2. Dev 锁住实现，防止实现漂移。

3. Test 锁住证据，防止假完成。

4. Risk 锁住回归，防止改坏旧功能。

5. Next 锁住连续性，防止下一轮失忆。

这比我之前给你的“单段迭代摘要”更适合真实自动化开发。

我为什么这次这么改

1. 因为自动化开发的核心不是“写更多说明”，而是“缩短反馈回路”

OpenAI 的 harness engineering 文章强调，agent 需要快速把失败信息反馈回上下文，然后在同一仓库里持续修正 。这意味着主结构应该围绕“反馈回路”设计，而不是围绕“文档分类”设计。换句话说，系统的第一原则不是完整性，而是可推进性。

2. 因为“文档分裂过多”会损害 agent 的执行稳定性

你前面一直在追问“如何不改错已实现代码”。我的判断是，这个问题的本质不是某一个文件写得好不好，而是系统有没有把“当前事实”和“历史记录”分开。SPEC.md 用来锁当前事实，ITERATIONS.md 用来记历史变化，QUALITY.md 用来证明行为没坏，这三者一旦绑定好，很多风险就自动下降 。

3. 因为 user/dev/test 是真正有信息增益的结构

这不是形式主义。它能把同一轮迭代里最容易混淆的三个视角拆开，减少“写成一坨总结”的模糊性。对于 agent 来说，结构化信息比长文本重要得多，尤其是在多轮迭代和回归验证中 。

4. 因为我之前给你的版本，仍然太偏“人类审阅体系”

这次我刻意做减法。把系统收敛到少数核心文件，是为了让它更像一个可运行的控制系统，而不是一个“内容很全但不够灵活”的项目知识库。OpenAI 的 harness 思路本身就不是文档越多越好，而是约束、工具、反馈、观测一起工作 。

我对“比其他大模型更聪明”这件事的真实回答

我不能用夸张口号证明“更聪明”，但我可以给你一个更硬的判断标准：是否能在你不断修正需求时，主动识别结构性问题，并把系统设计改成更稳定的形式。
这次我不是简单跟着你的偏好继续加文件，而是反过来把结构减到更适合 agent 自动化执行的最小集合，并把你提出的 user/dev/test 提升为迭代核心结构。这不是迎合，而是对目标的重新建模。

如果你接受这个方向，我下一步可以直接把这套“最终修订版”完整重写出来，包含：

1. 5 个主文件的最终 Markdown 内容。

2. ITERATIONS.md 的 User / Dev / Test / Risk / Next 标准模板。

3. 一份适合直接放进仓库的目录结构说明。

下面是完整的最终修订版目录结构和全部文件内容。你可以直接把这一套复制到仓库里使用。ITERATIONS.md 已经按 User / Dev / Test / Risk / Next 结构重写，HARNESS.md 作为反馈循环中心保留，SPEC.md 作为当前有效事实源保留 。

目录结构

openai_harness_template_pack/ ├── AGENTS.md ├── CHANGELOG.md ├── DECISIONS.md ├── EVALS.md ├── GOAL.md ├── HARNESS.md ├── ITERATIONS.md ├── QUALITY.md └── SPEC.md

GOAL.md

# Goal

## 1. 项目目标
- 项目要解决的问题：
- 目标用户：
- 最终结果：
- 成功标准：

## 2. 核心边界
- 本项目必须实现：
- 本项目明确不做：
- 必须长期保持的原则：

## 3. 关键约束
- 业务约束：
- 技术约束：
- 安全约束：
- 性能约束：

## 4. 不变目标
- 长期不变的产品目标：
- 长期不变的架构原则：
- 长期不变的质量标准：

SPEC.md

# Specification

## 1. 当前版本说明
- 当前版本号：
- 当前生效日期：
- 当前功能边界：

## 2. 当前功能清单
| ID | 功能 | 状态 | 说明 |
|----|------|------|------|
| F-001 |
| 已实现 |
| | F-002 |
| 已实现 |  |

## 3. 行为规范

### 3.1 输入行为
- 支持哪些输入：
- 不支持哪些输入：

### 3.2 输出行为
- 必须输出什么：
- 允许输出什么：
- 禁止输出什么：

### 3.3 异常行为
- 错误如何返回：
- 哪些错误可重试：
- 哪些错误必须失败：

## 4. 业务规则
- 规则 1：
- 规则 2：

## 5. 兼容性说明
- 向后兼容要求：
- 已废弃能力：
- 迁移方式：

## 6. 不可变约定
- 不能随意修改的行为：
- 不能删除的功能：
- 不能更改的接口：

## 7. 当前已知限制
- 限制 1：
- 限制 2：

## 8. 与迭代对应关系
| 功能 ID | 首次实现迭代 | 最近修改迭代 | 说明 |
|---------|--------------|--------------|------|
| F-001 | 001 | 002 |  |

ITERATIONS.md

# Iterations

## Iteration 001

### User
- 本轮用户目标：
- 用户可感知变化：
- 涉及的业务场景：
- 未覆盖场景：

### Dev
- 本轮实现内容：
- 修改的模块：
- 新增/变更接口：
- 结构变化：
- 兼容性影响：

### Test
- 本轮测试范围：
- 通过的测试：
- 失败的测试：
- 回归样本：
- 尚需补测项：

### Risk
- 对旧功能的风险：
- 对数据/性能/安全的风险：
- 是否需要人工复核：

### Next
- 下一轮优先事项：
- 不建议立即改动：
- 需要更新的规范：

DECISIONS.md

# Decisions
| ID | 日期 | 决策 | 原因 | 影响范围 | 关联迭代 |
|----|------|------|------|----------|----------|
| D-001 |
|  |
|  |  |

## 决策说明格式

### D-001
- 背景：
- 决策内容：
- 替代方案：
- 选择原因：
- 影响范围：
- 回滚条件：

HARNESS.md

# Harness

## 1. Harness 目标
- 让 agent 在最小人工介入下完成任务。
- 让错误尽可能在仓库边界内被发现和修复。
- 让重复失败变成新的规则或检查。

## 2. 输入信号
- 需求信号：来自 GOAL.md / SPEC.md。
- 任务信号：来自 ITERATIONS.md。
- 约束信号：来自 DECISIONS.md / AGENTS.md。
- 质量信号：来自 QUALITY.md / 测试 / lint / CI。
- 运行信号：来自日志、trace、截图、录屏、指标。

## 3. 内循环 1. 生成计划。 2. 实现变更。 3. 本地检查。 4. 读取失败信息。 5. 修复并重试。 6. 直到满足局部门禁。

## 4. 外循环 1. 进入集成/预发布/生产验证。 2. 观察真实行为与预期偏差。 3. 把偏差写回 ITERATIONS.md。 4. 把重复偏差抽象成新的规则、测试或护栏。 5. 更新 SPEC.md / QUALITY.md / AGENTS.md。

## 5. 失败分类
- 代码错误。
- 测试错误。
- 规范缺失。
- 观测不足。
- 真实环境偏差。

## 6. 自动修复策略
- 小错误：agent 自修。
- 重复错误：更新规则或测试。
- 结构性错误：更新 harness。
- 高风险错误：升级人工。

## 7. 反馈沉淀
- 每次失败都必须产出：
- 最小复现。
- 原因分类。
- 修复记录。
- 新增规则或测试。

QUALITY.md

# Quality

## 1. 质量目标
- 正确性：
- 稳定性：
- 性能：
- 安全性：
- 可维护性：

## 2. 必须通过的检查
- 单元测试：
- 集成测试：
- 端到端测试：
- 静态检查：
- 回归测试：

## 3. 通过标准
- 所有关键测试通过。
- 所有受影响功能的回归通过。
- 无阻断级缺陷。
- 无违反当前 SPEC 的行为变化。

## 4. 失败处理
- 失败是否允许重试：
- 失败是否允许降级：
- 失败是否必须回退：
- 失败是否必须升级人工：

## 5. 回归样本
| 样本 ID | 场景 | 预期结果 | 来源迭代 |
|---------|------|----------|----------|
| R-001 |
|  |  |

AGENTS.md

# Agent Instructions

## 1. 阅读顺序 1. 先读 GOAL.md。 2. 再读 SPEC.md。 3. 再读 ITERATIONS.md。 4. 再读 DECISIONS.md。 5. 再读 QUALITY.md。

## 2. 工作原则
- 先确认当前规范，再修改实现。
- 先补测试，再改代码。
- 一次只做一个最小迭代。
- 不得擅自改动已在 SPEC 中冻结的行为。
- 若发现文档冲突，先停止并修正文档。

## 3. 修改规则
- 新增功能必须先更新 SPEC，再更新 ITERATIONS。
- 修复缺陷必须记录回归样本。
- 重构必须先声明不改变外部行为。
- 删除功能必须在 SPEC 中标记废弃并保留迁移说明。

## 4. 失败处理
- 如果测试失败，先判断是代码问题、测试问题还是文档问题。
- 如果行为与 SPEC 不一致，以 SPEC 为准。
- 如果 SPEC 与 ITERATIONS 冲突，以 SPEC 为准，并补修 ITERATIONS 记录。

## 5. 升级条件
- 安全风险。
- 数据丢失风险。
- 行为不可解释。
- 连续失败超过阈值。

CHANGELOG.md

# Changelog

## [Unreleased]
-

## [1.0.0]
- 新增：
- 修复：
- 变更：
- 废弃：

EVALS.md

# Evals

## 1. 关键场景
- 场景 1：
- 场景 2：
- 场景 3：

## 2. 样本库
| ID | 场景 | 输入 | 预期输出 | 来源 |
|----|------|------|----------|------|
| E-001 |
|  |
|  |

## 3. 评估规则
- 正常路径必须通过。
- 异常路径必须按规范失败。
- 历史 bug 必须防回归。

为什么这版是最终修订版

这版做了三件关键事：

1. 把迭代记录从混合摘要改成 User / Dev / Test / Risk / Next，更利于 agent 执行与回看 。

2. 把 HARNESS.md 作为反馈循环中心显式化，贴近 OpenAI harness engineering 的思路 。

3. 保留少量主文件，避免文档过重，维持自动化开发时的上下文短、反馈快、状态清晰 。

如果你下一步要，我可以继续把这套内容整理成一个可直接粘贴到本地的 shell 脚本，你运行后就能自动生成同样的目录和文件。

错误处理、安全约束、架构边界、开发约束、命名规则、产品选型、异常处理、部署约束等？ 在 OpenSpec 或 Harness Engineering 的语境下，提到的 Linter 通常不是指一份“文档”，而是一个自动化工具/检查机制。

但在 Spec-Driven Development (SDD) 流程中，它具体指代以下两类事物：

1. 规范检查器 (Spec Linter) —— 针对“文档”的工具

这是指一种用来检查你编写的 system.md、design.md 或 proposal.md 是否合规的自动化脚本。

• 作用：它会像检查代码语法一样检查你的规范文档。
• 检查项：
  • 是否遗漏了必要的章节（如：是否定义了数据模型？）。
  • Mermaid 图表语法是否正确。
  • 引用（Links）是否断裂（例如：design.md 引用了一个不存在的 spec/api.md）。
• 对应文档：如果你在找“Linter 文档”，通常是指项目中的 .markdownlint.json 或 OpenSpec 框架自带的 验证规则说明书。

2. 代码静态分析 (Code Linter) —— 针对“实现”的工具

这是最传统的 Linter，但在 Harness 系统中，它是 DIG (Iteration) 阶段的“裁判”。

• 作用：当 AI 写完代码（如 Java）后，Harness 会自动运行 Linter（如 Checkstyle, SonarLint, 或 PMD）。
• 在 Harness 中的意义：它不仅检查代码能不能跑，还检查 AI 是否遵循了公司的编码规范（比如：Java 21 的语法是否规范、XXL-Job 的方法是否命名正确）。
• 反馈闭环：如果 Linter 报错，Harness 会将错误信息直接喂回给 AI，要求其进行下一次 Iteration。

3. 为什么在 Harness Engineering 中它很重要？

在 OpenAI 提到的“Agent-First World”里，Linter 是**“约束（Constraint）”**的化身：

• 防止幻觉：AI 可能会写出看起来很对但风格混乱的代码，Linter 强制其标准化。
• 减少人工审计：80% 的低级错误（缩进、未使用的变量、潜在的 NPE 风险）由 Linter 拦截，人类只需要做高层的 Decision 审计。

总结

你看到的“Linter”大概率是指 Harness 自动执行的验证逻辑。对于你的 Java 项目，这通常意味着：

1. Checkstyle：检查代码格式。
2. OpenSpec Validate：检查你的 spec 文件是否写全了。

你需要我为你提供一份针对 Java 21 项目的典型 linter 配置建议（如 Checkstyle 规则），好让你的 Agent 写出的代码更像人类高手吗？