现在能比较清楚地看到，这类“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 写出的代码更像人类高手吗？

我仔细读完了这份 CLADA 方案。整体架构思路清晰，三权分立模型、文档即共享内存、斜杠命令触发状态机这几个核心思路都很扎实。但从"设计能否真正落地成产品"的角度看，有几处关键环节语焉不详，甚至存在内在矛盾。以下是我的问题，大致按"越早需要回答越靠前"排列：

---

1. Gateway 的宿主身份是什么？

方案说 Gateway 是"拦截 Agent 输出特定字符串来触发模型切换"的 Python 脚本。但 Executor 和 Verifier 的具体接入方式没有说明——它们是通过 API 调用（stateless）、还是有状态的长连接进程？如果是 API 调用，"挂起 Executor 进程"这个说法在技术上是什么意思？挂起的是什么？

---

2. /ask_verifier 触发的判定逻辑是什么？

方案说 Executor"遇到歧义时自动触发"，但"歧义"的判定标准完全缺失。是 Executor 自己在输出中写 /ask_verifier？还是 Gateway 通过某种规则检测？如果是前者，如何防止 Executor 为了规避责任而滥用？如果是后者，这个规则是什么？

---

3. Verifier 的"独立环境"如何保证物理隔离？

/audit 阶段说 Verifier"独立拉起一个新的环境运行测试"。这个环境是 Docker 容器、沙盒虚拟机、还是仅仅是另一个进程？隔离的边界在哪里——是文件系统、网络、还是两者都有？如果测试需要数据库或外部服务，怎么处理？

---

4. contract.json 的权威性与 current_spec.md 的冲突如何仲裁？

方案定义了两个规格层——自然语言的 current_spec.md 和机器可读的 contract.json。实际开发中两者必然出现语义偏差（自然语言描述的边界总比 schema 宽）。当 Executor 按 contract.json 实现、Verifier 却按 current_spec.md 审计，产生分歧时，谁说了算？有没有明确的优先级规则？

---

5. L3 向量库的"过期记录剔除"由谁、按什么标准执行？

方案说 Verifier 对检索结果进行二次筛选，"剔除被 Superseded 的记录"。但 Superseded 的判定依据是什么？是 DR-xxx 文件里的某个字段？还是 Verifier 自己推断？如果是后者，Verifier 本身是无状态的 LLM，它凭什么知道哪条记录已经过时？这个"过期判定"逻辑如果缺失，RAG 检索反而会把 Executor 引向历史错误。

---

6. Verifier 的审计结论写入 audit_report.json 之后，Owner 不介入的情况下流程如何继续？

方案在 /audit 通过后说"向你申请 git merge"，但如果 Owner 不在线或没有响应呢？是阻塞等待、超时自动合并、还是回滚？整个方案对"Owner 离线"这个最常见的真实场景没有任何描述，而这恰恰是自动化框架存在价值最大的场景。

---

7. Executor 的 [TRACE] 输出是给谁看的，谁来消费它？

方案说 Executor"每修改 3 个文件必须输出一个 [TRACE] 摘要"。但没有说明这个 TRACE 的消费者是谁——是 Owner 实时看、是 Gateway 解析后存入 L2、还是仅作为日志归档？如果只是打印到终端，它在整个架构中的实质作用是什么？

---

8. 两个 Agent 的费用与延迟如何控制？

方案提到"花费超过 $1 时强制暂停"，但双 Agent 并行运行（Executor 写代码、Verifier 影子审计同步进行）的 token 消耗模型完全没有估算。对于一个 100 天长周期项目，L3 的全量对话 Log 灌入向量库的成本是多少？Verifier 每次读取完整 ADR + DR-xxx 的上下文窗口够用吗？这些是方案可行性的前置条件。

---

9. "Executor 严禁读取 .agent.md 之外的 Prompt 指令"这个约束如何强制执行？

方案把这条规则写在 .cursorrules 里，但 .cursorrules 本身也是文本文件，也在 Executor 的可读范围内。这是一个"用规则约束规则执行者"的循环——Executor 如果要违反，它同样可以读到这条规定然后选择忽视。真正的强制执行必须在 Gateway 层实现文件访问过滤，方案对此没有任何描述。

---

10. 整套方案的启动引导（Bootstrap）过程是什么？

方案描述的是一个稳态运行的系统，但第一次启动时：current_spec.md 从哪里来？contract.json 谁来生成？L3 向量库是空的怎么办？DR-xxx 编号从哪里开始？这个"冷启动"过程如果没有专门设计，实际上每个新项目都需要人工搭建一遍脚手架，和"自动化"的目标相悖。

回复质量很高，10个盲点基本都给出了可实施的技术路径。但读完之后，有几处新的回复本身又引出了更深层的问题，同时有2-3处回答我认为"答了但没真正解决"。继续追问：

---

1. STDIN阻塞挂起的前提假设存在裂缝

回复说Gateway通过"停止向Executor发送输入"来挂起。但Claude Code、Cursor这类主流Agent宿主，它们的交互模型并非简单的stdin/stdout管道——它们有自己的事件循环和工具调用机制。请问：CLADA是假设Executor是一个完全由Gateway自己启动的纯CLI进程？还是兼容现有Agent IDE（如Cursor/Claude Code）？如果是后者，pty劫持在这些IDE上的可行性验证做了吗？

---

2. "询问点数Quota"的设计细节缺失

防滥用机制提到给Executor设置Quota，但没有说明：Quota的计量单位是什么（每个iteration？每个文件？每个session）？耗尽后的行为是什么——强制让Executor自己做决定，还是直接报错终止？后者在复杂任务中会导致大量中途失败的iteration，这个代价有没有估算？

---

3. Contract.json > ADR > Spec 的优先级链在Bootstrap阶段自我矛盾

回复第4条确立了"Contract是第一真理"，但第10条Bootstrap流程是：先输入Goal → 再生成DR-001 → 最后由Verifier生成contract.json。也就是说，contract.json是从自然语言Goal和ADR里派生出来的。这意味着在项目生命周期的起点，优先级链是反的（Spec > ADR > Contract）。这个"创世时刻"的逻辑与稳态运行的优先级链如何自洽？谁来保证Bootstrap生成的contract.json忠实反映了Goal而没有引入偏差？

---

4. Docker隔离与Gateway文件代理之间存在架构层级冲突

第3条说Verifier在Docker容器里运行测试；第9条说Gateway在操作系统层级做文件访问代理。问题是：如果Verifier的测试环境在容器内，容器内的文件系统访问如何被宿主机的Gateway代理拦截？这两个机制是针对不同对象的（容器隔离针对Verifier，文件代理针对Executor），但方案没有明确说这一点，读起来像是同一套机制。请把这两条的适用对象和边界分开说清楚。

---

5. GPT-4o-mini作为TRACE摘要器引入了第三个模型

第7条说[TRACE]由"轻量级模型如GPT-4o-mini"实时生成current_progress.md。这意味着CLADA实际上是一个三模型架构（Executor + Verifier + Summarizer），但方案全程只提两个Agent。这个第三个模型的：定位是否固定（还是可替换）？它的输出current_progress.md是否会反哺给Executor或Verifier作为上下文？如果会，它就不是旁观者，而是第三个决策参与者，需要单独设计约束。

---

6. clada init的"5分钟完成宪法配置"与Verifier冷启动之间的鸡生蛋问题

Bootstrap流程第3步是"调用Verifier生成基础contract.json"，但Verifier依赖L2索引和DR文件才能做出有约束力的判断。在L3为空、只有一份用户输入的Goal文本的情况下，此时的Verifier实际上是一个没有历史记忆的裸模型。它生成的contract.json的质量和可靠性由什么来保证？还是说Bootstrap阶段的Verifier本质上只是一个"格式化工具"，并不真正行使审计职能？如果是后者，需要在文档里明确说明，否则会给使用者造成"第一份contract已经经过严格审计"的错误印象。

读完这轮回复，整体质量很高。状态机定义是整份文档迄今为止最扎实的部分，Mermaid图把之前散落在各处的逻辑收拢得很干净。[B_PLAN]闭环和双检锁的工程化定义也都达到了可实施的精度。

但距离95%还差几个具体的缺口，我逐一说：

---

已经可以关闭的问题

TCP长连接风险、[B_PLAN]强制Owner介入、双检锁Hard/Soft字段分类、状态机全图——这四项我认为已经达到设计完整度，可以进入实现阶段。

---

还差这几处，每一处都是实现时会踩的坑：

1. EXECUTING → IDLE 的异常终止路径过于粗糙

状态图里写了"Quota耗尽且未完成 → 异常终止 → IDLE"，但这条路径没有善后逻辑。Executor在中途终止时，它已经修改的文件处于什么状态？是回滚、是保留在脏工作区、还是自动stash？如果不定义，每次异常终止都会给下一个iteration留下一个不确定的起点，这是熵增的主要来源之一。建议补充：异常终止前Gateway强制执行git stash并写入interrupted_state.json，下次PROPOSING时作为恢复选项提示Owner。

2. Pattern Monitor的"同时写入冲突"防护依赖single-writer假设，但AUDITING阶段会破坏它

current_state.json记录当前哪个Agent掌控文件夹，这个设计在EXECUTING和ARBITRATING阶段有效。但AUDITING阶段Verifier在Docker容器内通过Volume挂载读取代码，同时如果Executor因某种原因（比如Gateway的SIGSTOP失效）还在运行，就会出现容器内读、宿主机写的竞态。建议明确：进入AUDITING状态时，Gateway对宿主机代码目录执行chmod -R 444（只读锁），AUDITING结束后恢复，这才是真正的物理互斥。

3. ARBITRATING → EXECUTING的上下文恢复没有定义

Verifier回答完问题后，Executor从SUSPENDED恢复。但Verifier的回答如何注入给Executor？是追加到Executor的stdin、还是写入一个临时文件让Executor读取、还是更新current_spec.md？这三种方式对Executor后续行为的影响完全不同。目前方案对这个"信息交接"环节是空白的，而它恰恰是Ralph Loop能否真正闭合的关键。

4. Heartbeat你自己提出来了但没有回答

你在回复末尾问"是否需要定期Heartbeat把TRACE喂给Summarizer"——这个问题我反问回来：如果不做Heartbeat，Summarizer只能在TRACE输出时被动触发，那在Executor长时间沉默执行（比如跑一个复杂算法）的区间里，Owner侧的进度感知是完全盲区。 建议的答案是：设置30秒定时器，如果无TRACE输出，Gateway主动向Executor的PTY发送一个无害的状态查询指令（类似心跳包），强制它输出当前进度，而不是被动等待。

---

当前完整度评估：88%

从75%到88%，这轮进步是实质性的。剩余12%集中在：

• 上述4个实现级细节（约8%）
• 一份完整的contract.json + DR-xxx规范化字段定义还没有出现（约4%）——这是你上一轮末尾承诺要给的，也是Executor和Verifier能够真正"对话"的语言基础

字段定义给出来之后，我认为可以到95%。

读完这轮。结论先说：

当前完整度：95%。达标。

---

各项逐一确认：

Clean Shutdown协议——git commit --no-verify的快照 + interrupted_state.json + Owner二选一的恢复界面，逻辑闭合，可实施。

只读锁——chmod -R 555 + fswatch异常熔断，物理互斥有了真正的执行层。这个组合在macOS和Linux上都能跑，是实用的选择。

ARBITRATING→EXECUTING的信息交接——Append Injection写入STDIN伪装成Owner指令，这个方案干净，不引入第三方文件依赖，符合Agent的会话心智模型。

Heartbeat——30秒计时器 + 空注释探针 + 兜底的show current status强制指令，三层降级设计合理。

contract.json字段结构——hard_assertions挂check_script这个设计是点睛之笔，把自然语言约束直接绑定到可执行验证脚本，Verifier审计时不需要主观判断，直接跑脚本看结果。

DR-xxx.md的front-matter——status/superseded_by字段出现了，这正是L3 RAG过滤的元数据基础，和之前第5轮讨论的过期剔除逻辑完全对接上了。

---

剩余5%是什么：

不是设计缺陷，是三处"实现时必须做决定但设计文档可以不写"的工程细节：

第一，fswatch在容器化环境里的行为需要实测——它监控的是宿主机inode，容器内的写操作通过Volume映射是否能被宿主机的fswatch捕获，取决于挂载方式，建议在技术风险清单里标注。

第二，Heartbeat的#: heartbeat空注释对不同的Agent Shell解释器行为不一致——Claude Code如果把它当成一条用户消息处理，可能会触发不必要的响应，实现时需要找到真正的"无副作用探针"指令。

第三，contract_id的版本演进规则没有定义——当Contract从1.0.0升级到1.1.0时，历史DR中引用旧版contract_id的记录如何处理？是向前兼容还是强制迁移？这在100天长周期里必然发生。

---

总体判断：

骨架完整，关键路径全部闭合，防破坏机制有物理层保障，文档格式可以直接作为实现规范使用。这三处剩余问题是实现阶段的工程决策，不是设计阶段的逻辑漏洞。

可以进入实现阶段了。建议下一步的优先级是：orchestrator.py的状态机骨架 → contract.json的Meta-Schema验证器 → PTY封装的兼容性测试（优先验证Claude Code的SIGSTOP行为）。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>CLADA — 完整技术方案 v1.0</title> <style> @import url('https://fonts.googleapis.com/css2?family=Syne:wght@400;600;700;800&family=JetBrains+Mono:wght@300;400;500&family=Noto+Sans+SC:wght@300;400;500&display=swap');

:root { --bg: #0a0c0f; --bg2: #0f1217; --bg3: #141920; --surface: #1a2030; --border: #252d3d; --border2: #2e3a50; --accent: #4af0a0; --accent2: #0ef; --accent3: #f0a04a; --warn: #f05a4a; --text: #d4dde8; --text2: #8899aa; --text3: #556677; --heading: #eef3f8; }

• { margin: 0; padding: 0; box-sizing: border-box; }

html { scroll-behavior: smooth; }

body { background: var(--bg); color: var(--text); font-family: 'Noto Sans SC', sans-serif; font-weight: 300; line-height: 1.8; font-size: 15px; }

/* SIDEBAR NAV */ .sidebar { position: fixed; left: 0; top: 0; width: 240px; height: 100vh; background: var(--bg2); border-right: 1px solid var(--border); overflow-y: auto; z-index: 100; padding: 32px 0; }

.sidebar-logo { font-family: 'Syne', sans-serif; font-weight: 800; font-size: 18px; color: var(--accent); padding: 0 24px 24px; border-bottom: 1px solid var(--border); letter-spacing: 0.05em; }

.sidebar-logo span { color: var(--text3); font-size: 11px; display: block; font-weight: 400; margin-top: 4px; letter-spacing: 0.1em; text-transform: uppercase; }

.nav-section { padding: 20px 24px 8px; font-size: 10px; text-transform: uppercase; letter-spacing: 0.15em; color: var(--text3); font-family: 'JetBrains Mono', monospace; }

.nav-item { display: block; padding: 7px 24px; color: var(--text2); text-decoration: none; font-size: 13px; transition: all 0.2s; border-left: 2px solid transparent; }

.nav-item:hover { color: var(--accent); border-left-color: var(--accent); background: rgba(74,240,160,0.04); }

/* MAIN */ .main { margin-left: 240px; min-height: 100vh; }

/* HERO */ .hero { padding: 80px 64px 64px; border-bottom: 1px solid var(--border); position: relative; overflow: hidden; }

.hero::before { content: ''; position: absolute; top: -100px; right: -100px; width: 500px; height: 500px; background: radial-gradient(circle, rgba(74,240,160,0.06) 0%, transparent 70%); pointer-events: none; }

.hero-tag { font-family: 'JetBrains Mono', monospace; font-size: 11px; color: var(--accent); letter-spacing: 0.2em; text-transform: uppercase; margin-bottom: 20px; }

.hero h1 { font-family: 'Syne', sans-serif; font-weight: 800; font-size: 52px; color: var(--heading); line-height: 1.1; margin-bottom: 16px; }

.hero h1 em { color: var(--accent); font-style: normal; }

.hero-sub { font-size: 16px; color: var(--text2); max-width: 640px; margin-bottom: 40px; line-height: 1.7; }

.hero-meta { display: flex; gap: 32px; flex-wrap: wrap; }

.meta-item { font-family: 'JetBrains Mono', monospace; font-size: 12px; color: var(--text3); } .meta-item strong { color: var(--text2); display: block; font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em; margin-bottom: 4px; }

/* CONTENT */ .content { padding: 0 64px 80px; }

.section { padding: 64px 0 0; border-top: 1px solid var(--border); margin-top: 64px; }

.section:first-child { border-top: none; margin-top: 0; padding-top: 64px; }

.section-label { font-family: 'JetBrains Mono', monospace; font-size: 10px; color: var(--accent); text-transform: uppercase; letter-spacing: 0.2em; margin-bottom: 12px; }

h2 { font-family: 'Syne', sans-serif; font-weight: 700; font-size: 28px; color: var(--heading); margin-bottom: 24px; line-height: 1.3; }

h3 { font-family: 'Syne', sans-serif; font-weight: 600; font-size: 17px; color: var(--heading); margin: 32px 0 12px; }

h4 { font-size: 13px; font-weight: 500; color: var(--accent2); font-family: 'JetBrains Mono', monospace; text-transform: uppercase; letter-spacing: 0.1em; margin: 24px 0 8px; }

p { color: var(--text); margin-bottom: 14px; }

/* CARDS */ .card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 16px; margin: 24px 0; }

.card { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 24px; position: relative; overflow: hidden; }

.card::before { content: ''; position: absolute; top: 0; left: 0; right: 0; height: 2px; }

.card.green::before { background: var(--accent); } .card.blue::before { background: var(--accent2); } .card.orange::before { background: var(--accent3); } .card.red::before { background: var(--warn); }

.card-icon { font-size: 22px; margin-bottom: 12px; } .card-title { font-family: 'Syne', sans-serif; font-weight: 700; font-size: 15px; color: var(--heading); margin-bottom: 8px; } .card-body { font-size: 13px; color: var(--text2); line-height: 1.7; } .card-tag { display: inline-block; margin-top: 12px; font-family: 'JetBrains Mono', monospace; font-size: 10px; padding: 3px 8px; border-radius: 3px; } .card.green .card-tag { background: rgba(74,240,160,0.1); color: var(--accent); } .card.blue .card-tag { background: rgba(0,238,255,0.1); color: var(--accent2); } .card.orange .card-tag { background: rgba(240,160,74,0.1); color: var(--accent3); } .card.red .card-tag { background: rgba(240,90,74,0.1); color: var(--warn); }

/* CODE BLOCKS */ pre { background: var(--bg3); border: 1px solid var(--border); border-radius: 6px; padding: 20px 24px; overflow-x: auto; margin: 16px 0 24px; position: relative; }

pre code { font-family: 'JetBrains Mono', monospace; font-size: 12.5px; line-height: 1.7; color: var(--text); }

.code-label { font-family: 'JetBrains Mono', monospace; font-size: 10px; color: var(--text3); text-transform: uppercase; letter-spacing: 0.1em; margin-bottom: 6px; }

.hl-green { color: var(--accent); } .hl-blue { color: var(--accent2); } .hl-orange { color: var(--accent3); } .hl-red { color: var(--warn); } .hl-dim { color: var(--text3); }

/* INLINE CODE */ code { font-family: 'JetBrains Mono', monospace; font-size: 12px; background: var(--surface); border: 1px solid var(--border); border-radius: 3px; padding: 1px 6px; color: var(--accent2); }

/* STATE MACHINE */ .state-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 12px; margin: 20px 0; }

.state-box { background: var(--surface); border: 1px solid var(--border2); border-radius: 6px; padding: 16px; }

.state-name { font-family: 'JetBrains Mono', monospace; font-size: 11px; font-weight: 500; text-transform: uppercase; letter-spacing: 0.1em; margin-bottom: 6px; }

.state-desc { font-size: 12px; color: var(--text2); line-height: 1.6; }

.state-box.active .state-name { color: var(--accent); } .state-box.verify .state-name { color: var(--accent2); } .state-box.warn .state-name { color: var(--accent3); } .state-box.danger .state-name { color: var(--warn); }

/* FLOW DIAGRAM */ .flow { background: var(--bg3); border: 1px solid var(--border); border-radius: 8px; padding: 32px; margin: 24px 0; font-family: 'JetBrains Mono', monospace; font-size: 12px; line-height: 2; overflow-x: auto; }

.flow-arrow { color: var(--text3); } .flow-state { color: var(--accent); font-weight: 500; } .flow-trigger { color: var(--accent3); font-style: italic; } .flow-agent { color: var(--accent2); }

/* TABLE */ table { width: 100%; border-collapse: collapse; margin: 16px 0 24px; font-size: 13px; }

th { background: var(--surface); color: var(--text2); font-family: 'JetBrains Mono', monospace; font-size: 10px; text-transform: uppercase; letter-spacing: 0.1em; padding: 10px 16px; text-align: left; border-bottom: 1px solid var(--border2); }

td { padding: 10px 16px; border-bottom: 1px solid var(--border); color: var(--text); vertical-align: top; }

tr:last-child td { border-bottom: none; } tr:hover td { background: rgba(255,255,255,0.015); }

/* RISK BOX */ .risk-box { background: rgba(240,90,74,0.07); border: 1px solid rgba(240,90,74,0.25); border-left: 3px solid var(--warn); border-radius: 0 6px 6px 0; padding: 16px 20px; margin: 16px 0; font-size: 13px; }

.risk-box strong { color: var(--warn); font-family: 'JetBrains Mono', monospace; font-size: 11px; display: block; margin-bottom: 6px; text-transform: uppercase; letter-spacing: 0.1em; }

.note-box { background: rgba(74,240,160,0.05); border: 1px solid rgba(74,240,160,0.2); border-left: 3px solid var(--accent); border-radius: 0 6px 6px 0; padding: 16px 20px; margin: 16px 0; font-size: 13px; }

.note-box strong { color: var(--accent); font-family: 'JetBrains Mono', monospace; font-size: 11px; display: block; margin-bottom: 6px; text-transform: uppercase; letter-spacing: 0.1em; }

/* FIELD SPEC */ .field-row { display: grid; grid-template-columns: 180px 80px 1fr; gap: 16px; padding: 10px 0; border-bottom: 1px solid var(--border); font-size: 13px; align-items: start; }

.field-row:last-child { border-bottom: none; } .field-name { font-family: 'JetBrains Mono', monospace; color: var(--accent2); font-size: 12px; } .field-type { font-family: 'JetBrains Mono', monospace; color: var(--accent3); font-size: 11px; } .field-desc { color: var(--text2); }

.badge { display: inline-block; font-family: 'JetBrains Mono', monospace; font-size: 9px; padding: 2px 6px; border-radius: 2px; text-transform: uppercase; letter-spacing: 0.08em; vertical-align: middle; margin-left: 6px; }

.badge-hard { background: rgba(240,90,74,0.15); color: var(--warn); } .badge-soft { background: rgba(74,240,160,0.1); color: var(--accent); }

/* DIVIDER */ .divider { border: none; border-top: 1px solid var(--border); margin: 32px 0; }

ul { padding-left: 20px; margin-bottom: 14px; } li { margin-bottom: 6px; color: var(--text); font-size: 14px; } li::marker { color: var(--accent); }

/* PROGRESS BAR */ .completeness { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 24px; margin: 24px 0; }

.completeness-title { font-family: 'Syne', sans-serif; font-weight: 600; color: var(--heading); margin-bottom: 16px; }

.progress-item { margin-bottom: 12px; } .progress-label { display: flex; justify-content: space-between; font-size: 12px; margin-bottom: 4px; } .progress-label span:first-child { color: var(--text2); } .progress-label span:last-child { font-family: 'JetBrains Mono', monospace; color: var(--accent); } .progress-bar { height: 4px; background: var(--border); border-radius: 2px; overflow: hidden; } .progress-fill { height: 100%; background: linear-gradient(90deg, var(--accent), var(--accent2)); border-radius: 2px; }

/* SCROLLBAR */ ::-webkit-scrollbar { width: 6px; height: 6px; } ::-webkit-scrollbar-track { background: var(--bg); } ::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 3px; } </style>

</head> <body> <nav class="sidebar"> <div class="sidebar-logo"> CLADA <span>Technical Specification v1.0</span> </div> <div class="nav-section">Overview</div> <a class="nav-item" href="#overview">设计哲学</a> <a class="nav-item" href="#architecture">三权分立架构</a> <div class="nav-section">Core Design</div> <a class="nav-item" href="#gateway">Gateway 控制器</a> <a class="nav-item" href="#statemachine">状态机</a> <a class="nav-item" href="#protocols">通讯协议</a> <div class="nav-section">Documents</div> <a class="nav-item" href="#contract">contract.json 规范</a> <a class="nav-item" href="#dr">DR-xxx 规范</a> <a class="nav-item" href="#memory">三级记忆系统</a> <div class="nav-section">Implementation</div> <a class="nav-item" href="#bootstrap">Bootstrap 引导</a> <a class="nav-item" href="#isolation">隔离机制</a> <a class="nav-item" href="#risks">技术风险清单</a> <a class="nav-item" href="#roadmap">实现路线图</a> </nav> <div class="main"> <div class="hero"> <div class="hero-tag">// CLADA · Closed-Loop Autonomous Development Architecture</div> <h1>让 AI 在<em>宪法约束</em>下<br>自主完成软件工程</h1> <p class="hero-sub"> CLADA 不是聊天框的延伸，而是一套将 AI Agent 嵌入工业流水线的完整架构。 它通过物理隔离、层级记忆和双 Agent 互审，将 AI 编程的熵增问题系统性地解决。 </p> <div class="hero-meta"> <div class="meta-item"><strong>Architecture</strong>三权分立 · 双 Agent</div> <div class="meta-item"><strong>Executor</strong>DeepSeek V4（低成本执行）</div> <div class="meta-item"><strong>Verifier</strong>Claude Sonnet（精准审计）</div> <div class="meta-item"><strong>Gateway</strong>Python · PTY · fswatch</div> <div class="meta-item"><strong>Isolation</strong>Docker · chmod 555</div> <div class="meta-item"><strong>完整度</strong>95%（可进入实现阶段）</div> </div> </div> <div class="content">

<!-- SECTION 1: 设计哲学 -->
<div class="section" id="overview">
  <div class="section-label">§ 01 · Design Philosophy</div>
  <h2>设计哲学：为什么需要 CLADA</h2>
  <p>
    传统 AI 编程的失败模式有三个根源：<strong>上下文熵增</strong>（长期迭代后 AI 忘记早期决策）、<strong>单点权威缺失</strong>（没有任何机制阻止 AI 改变自己的规则）、以及<strong>验证与执行混同</strong>（同一个 Agent 既写代码又判断代码好坏）。
  </p>
  <p>
    CLADA 的核心思想是将这三个问题分别用三个机制解决：<strong>三级记忆</strong>解决熵增、<strong>宪法文件（Contract + ADR）</strong>解决权威缺失、<strong>双 Agent 分权</strong>解决验证混同。
  </p>

  <div class="card-grid">
    <div class="card green">
      <div class="card-icon">⚖️</div>
      <div class="card-title">三权分立</div>
      <div class="card-body">Owner（最高裁决）、Executor（执行权）、Verifier（审计权）三者权责边界由物理机制强制执行，而非依赖 Prompt 约定。</div>
      <div class="card-tag">Constitutional</div>
    </div>
    <div class="card blue">
      <div class="card-icon">🧠</div>
      <div class="card-title">文档即共享内存</div>
      <div class="card-body">Agent 之间没有直接对话。所有信息交换通过结构化文件进行，每个文件格式都经过严格定义，防止语义漂移。</div>
      <div class="card-tag">Memory-First</div>
    </div>
    <div class="card orange">
      <div class="card-icon">🔄</div>
      <div class="card-title">状态机驱动</div>
      <div class="card-body">系统在八个明确定义的状态之间跳转。每次状态转移都有物理触发条件，Gateway 是唯一的状态时钟。</div>
      <div class="card-tag">Deterministic</div>
    </div>
    <div class="card red">
      <div class="card-icon">🔒</div>
      <div class="card-title">物理隔离</div>
      <div class="card-body">Executor 的文件访问权限由 Gateway 在操作系统层级代理拦截。Verifier 的测试运行在 Docker 容器内，测试代码无法影响宿主机。</div>
      <div class="card-tag">Hardware-Enforced</div>
    </div>
  </div>
</div>

<!-- SECTION 2: 三权分立架构 -->
<div class="section" id="architecture">
  <div class="section-label">§ 02 · Architecture</div>
  <h2>三权分立架构总览</h2>

  <div class="flow">

<span class="hl-dim">┌─────────────────────────────────────────────────────────────────┐</span> <span class="hl-dim">│</span> <span class="hl-orange">OWNER（最高裁决权）</span> <span class="hl-dim">│</span> <span class="hl-dim">│</span> Gateway 控制台 · 实时监控 · 强制断点 <span class="hl-dim">│</span> <span class="hl-dim">└───────────────────────────┬─────────────────────────────────────┘</span> <span class="hl-dim">│ 监控 / 指令</span> <span class="hl-dim">┌───────────────────────────▼─────────────────────────────────────┐</span> <span class="hl-dim">│</span> <span class="hl-green">GATEWAY（状态机时钟）</span> <span class="hl-dim">│</span> <span class="hl-dim">│</span> PTY 包装 · Pattern Monitor · 文件访问代理 · 状态路由 <span class="hl-dim">│</span> <span class="hl-dim">└──────────────┬────────────────────────────┬────────────────────┘</span> <span class="hl-dim">│ PTY/SIGSTOP</span> <span class="hl-dim">│ Docker + Volume</span> <span class="hl-dim">┌──────────────▼──────────┐</span> <span class="hl-dim">┌──────────▼─────────────────┐</span> <span class="hl-dim">│</span> <span class="hl-green">EXECUTOR（执行权）</span> <span class="hl-dim">│</span> <span class="hl-blue">│ VERIFIER（审计权） │</span> <span class="hl-dim">│</span> DeepSeek V4 <span class="hl-dim">│</span> <span class="hl-blue">│ Claude Sonnet │</span> <span class="hl-dim">│</span> · 只写代码 <span class="hl-dim">│</span> <span class="hl-blue">│ · 只写文档 + 审计报告 │</span> <span class="hl-dim">│</span> · 只读 spec/ <span class="hl-dim">│</span> <span class="hl-blue">│ · 运行测试（容器内） │</span> <span class="hl-dim">│</span> · 遇歧义必须上报 <span class="hl-dim">│</span> <span class="hl-blue">│ · 引用 ADR 做裁决 │</span> <span class="hl-dim">└──────────────┬──────────┘</span> <span class="hl-blue">└─────────────┬──────────────┘</span> <span class="hl-dim">│ 写入</span> <span class="hl-dim">│ 写入</span> <span class="hl-dim">┌──────────────▼──────────────────────────▼────────────────────────┐</span> <span class="hl-dim">│</span> <span class="hl-orange">共享文档层（唯一共享内存）</span> <span class="hl-dim">│</span> <span class="hl-dim">│</span> contract.json · DR-xxx.md · current_spec.md · audit_report.json <span class="hl-dim">│</span> <span class="hl-dim">└──────────────────────────────────────────────────────────────────┘</span> </div>

  <h3>角色权限边界（硬性规定）</h3>
  <table>
    <tr>
      <th>能力</th>
      <th>Owner</th>
      <th>Executor</th>
      <th>Verifier</th>
    </tr>
    <tr>
      <td>写入源代码 <code>src/</code></td>
      <td>✅</td><td>✅</td><td>❌</td>
    </tr>
    <tr>
      <td>写入文档 <code>docs/</code></td>
      <td>✅</td><td>❌（Gateway 拦截）</td><td>✅</td>
    </tr>
    <tr>
      <td>读取 <code>docs/decisions/</code></td>
      <td>✅</td><td>✅（只读）</td><td>✅</td>
    </tr>
    <tr>
      <td>读取 <code>.env</code> / secrets</td>
      <td>✅</td><td>❌（Gateway 拦截）</td><td>❌</td>
    </tr>
    <tr>
      <td>执行 <code>git merge main</code></td>
      <td>✅</td><td>❌</td><td>❌</td>
    </tr>
    <tr>
      <td>触发状态转移</td>
      <td>✅（斜杠命令）</td><td>部分（输出触发词）</td><td>部分（审计结论）</td>
    </tr>
  </table>
</div>

<!-- SECTION 3: Gateway -->
<div class="section" id="gateway">
  <div class="section-label">§ 03 · Gateway</div>
  <h2>Gateway 控制器详细设计</h2>
  <p>Gateway 是整个系统的神经中枢，以 <code>orchestrator.py</code> 形式运行。它不是简单的脚本，而是一个多线程进程管理器。</p>

  <h3>核心组件</h3>
  <div class="card-grid">
    <div class="card green">
      <div class="card-title">PTY Wrapper</div>
      <div class="card-body">通过 <code>pty.openpty()</code> 启动 Agent 进程。Agent 认为自己在与标准终端对话，Gateway 截获所有 I/O 流。支持 SIGSTOP / SIGCONT 物理挂起。</div>
    </div>
    <div class="card blue">
      <div class="card-title">Pattern Monitor 线程</div>
      <div class="card-body">持续嗅探 Executor 的 stdout。正则匹配触发词（<code>[REQ_REVIEW]</code>、<code>[DONE]</code>、<code>[B_PLAN]</code>）后立即发出状态切换指令。</div>
    </div>
    <div class="card orange">
      <div class="card-title">文件访问代理</div>
      <div class="card-body">通过 LD_PRELOAD 或 ptrace 拦截 Executor 进程的文件系统调用。禁止读取 <code>.env</code>、<code>secrets/</code>、<code>docs/decisions/</code>（写操作）。</div>
    </div>
    <div class="card red">
      <div class="card-title">Heartbeat 守护线程</div>
      <div class="card-body">30 秒计时器。stdout 静默超时后向 PTY 发送 <code>#: heartbeat\n</code> 探针。若无响应，发送 <code>show current status</code> 强制 Executor 输出 TRACE。</div>
    </div>
  </div>

  <h3>current_state.json — 全局状态文件</h3>
  <div class="code-label">runtime / current_state.json</div>
  <pre><code>{

<span class="hl-green">"state"</span>: <span class="hl-orange">"EXECUTING"</span>, <span class="hl-dim">// 当前状态机状态</span> <span class="hl-green">"active_agent"</span>: <span class="hl-orange">"executor"</span>, <span class="hl-dim">// 当前持有文件写权限的 Agent</span> <span class="hl-green">"src_lock"</span>: <span class="hl-blue">false</span>, <span class="hl-dim">// AUDITING 阶段置 true，触发 chmod 555</span> <span class="hl-green">"executor_pid"</span>: <span class="hl-blue">31245</span>, <span class="hl-green">"verifier_pid"</span>: <span class="hl-blue">31289</span>, <span class="hl-green">"quota_remaining"</span>: <span class="hl-blue">7</span>, <span class="hl-dim">// Executor 剩余询问次数</span> <span class="hl-green">"iteration_id"</span>: <span class="hl-orange">"IT-042"</span>, <span class="hl-green">"last_trace_ts"</span>: <span class="hl-blue">1716880200</span>, <span class="hl-dim">// 上次 TRACE 输出时间戳</span> <span class="hl-green">"b_plan_detected"</span>: <span class="hl-blue">false</span>, <span class="hl-dim">// 是否出现过 [B_PLAN] 标签</span> <span class="hl-green">"autopilot"</span>: <span class="hl-blue">false</span> <span class="hl-dim">// Owner 离线模式开关</span> }</code></pre>

  <h3>斜杠命令（Owner 控制接口）</h3>
  <table>
    <tr><th>命令</th><th>触发状态</th><th>动作</th></tr>
    <tr><td><code>/init</code></td><td>IDLE → BOOTSTRAP</td><td>引导用户输入 Goal，启动创世流程</td></tr>
    <tr><td><code>/propose</code></td><td>IDLE → PROPOSING</td><td>唤醒 Verifier，加载 L2 架构文档，生成新 Spec</td></tr>
    <tr><td><code>/execute</code></td><td>PROPOSING → EXECUTING</td><td>切换至 Executor，注入 current_spec.md</td></tr>
    <tr><td><code>/merge</code></td><td>PENDING_COMMIT → IDLE</td><td>执行 git merge，归档 IT-xxx.md，重置状态</td></tr>
    <tr><td><code>/reject</code></td><td>PENDING_COMMIT → EXECUTING</td><td>将拒绝理由注入 Executor STDIN，继续修改</td></tr>
    <tr><td><code>/abort</code></td><td>任意 → IDLE</td><td>触发 Clean Shutdown 协议，stash 现场</td></tr>
  </table>
</div>

<!-- SECTION 4: 状态机 -->
<div class="section" id="statemachine">
  <div class="section-label">§ 04 · State Machine</div>
  <h2>完整状态机定义</h2>

  <h3>八个状态</h3>
  <div class="state-grid">
    <div class="state-box">
      <div class="state-name">IDLE</div>
      <div class="state-desc">系统等待 Owner 指令。无 Agent 持有文件写权限。</div>
    </div>
    <div class="state-box warn">
      <div class="state-name">BOOTSTRAP</div>
      <div class="state-desc">创世阶段。Verifier 以"格式化工具模式"生成初始 Contract 和 DR-001。Owner 必须高强度介入确认。</div>
    </div>
    <div class="state-box verify">
      <div class="state-name">PROPOSING</div>
      <div class="state-desc">Verifier 接管。读取 L2 文档，与 Owner 协商，输出 current_spec.md。</div>
    </div>
    <div class="state-box active">
      <div class="state-name">EXECUTING</div>
      <div class="state-desc">Executor 持有代码写权限。每修改 3 个文件输出一次 [TRACE]。Heartbeat 守护激活。</div>
    </div>
    <div class="state-box warn">
      <div class="state-name">SUSPENDED</div>
      <div class="state-desc">Executor 发出 [REQ_REVIEW]。Gateway 发送 SIGSTOP，检查 TCP 连接状态，准备切换至 Verifier。</div>
    </div>
    <div class="state-box verify">
      <div class="state-name">ARBITRATING</div>
      <div class="state-desc">Verifier 接管。必须引用 DR-xxx 做裁决，将决策追加注入 Executor STDIN。</div>
    </div>
    <div class="state-box verify">
      <div class="state-name">AUDITING</div>
      <div class="state-desc">src/ 目录 chmod 555 锁定。Verifier 在 Docker 容器内运行测试，生成 audit_report.json。</div>
    </div>
    <div class="state-box warn">
      <div class="state-name">PENDING_COMMIT</div>
      <div class="state-desc">审计通过，等待 Owner 执行 /merge 或 /reject。若含 [B_PLAN] 则不可进入 autopilot。</div>
    </div>
  </div>

  <h3>完整状态转移表</h3>
  <table>
    <tr><th>From</th><th>To</th><th>触发条件</th><th>Gateway 动作</th></tr>
    <tr>
      <td>IDLE</td><td>BOOTSTRAP</td>
      <td>Owner 执行 <code>/init</code></td>
      <td>启动 Verifier 进程，加载 Meta-Schema，提示双检锁警告</td>
    </tr>
    <tr>
      <td>BOOTSTRAP</td><td>IDLE</td>
      <td>Owner 点击 Confirm（双检锁通过）</td>
      <td>写入 DR-001.md，生成 L2 index.json，标注"未经历史 ADR 审计"警告</td>
    </tr>
    <tr>
      <td>IDLE</td><td>PROPOSING</td>
      <td>Owner 执行 <code>/propose</code></td>
      <td>注入 L2 架构文档 + 相关 DR 摘要到 Verifier 上下文</td>
    </tr>
    <tr>
      <td>PROPOSING</td><td>EXECUTING</td>
      <td>Verifier 输出确认的 current_spec.md</td>
      <td>切换至 Executor PTY，写入 Spec，重置 Quota 计数器</td>
    </tr>
    <tr>
      <td>EXECUTING</td><td>SUSPENDED</td>
      <td>stdout 出现 <code>[REQ_REVIEW]</code> 或 ACCESS_DENIED</td>
      <td>发送 SIGSTOP，检查 TCP 连接，读取 q_waiting.json</td>
    </tr>
    <tr>
      <td>SUSPENDED</td><td>ARBITRATING</td>
      <td>Verifier 进程就绪</td>
      <td>将 q_waiting.json + 相关 DR 注入 Verifier 上下文</td>
    </tr>
    <tr>
      <td>ARBITRATING</td><td>EXECUTING</td>
      <td>Verifier 输出裁决</td>
      <td>将裁决以 SYSTEM_NOTIFICATION 格式写入 Executor STDIN，发送 SIGCONT，Quota -1</td>
    </tr>
    <tr>
      <td>EXECUTING</td><td>AUDITING</td>
      <td>stdout 出现 <code>[DONE]</code></td>
      <td>chmod -R 555 src/，拉起 Docker 容器，Volume 只读挂载</td>
    </tr>
    <tr>
      <td>AUDITING</td><td>EXECUTING</td>
      <td>audit_report.json 中 failure_count &gt; 0</td>
      <td>chmod -R 755 src/，将失败摘要写入 Executor STDIN</td>
    </tr>
    <tr>
      <td>AUDITING</td><td>PENDING_COMMIT</td>
      <td>所有测试通过 且 无 [B_PLAN]</td>
      <td>chmod -R 755 src/，git checkout -b feature-xxx，通知 Owner</td>
    </tr>
    <tr>
      <td>AUDITING</td><td>WAITING_FOR_OWNER</td>
      <td>所有测试通过 但 含 [B_PLAN]</td>
      <td>强制阻塞，禁止 autopilot，Owner 必须手动审阅 B_PLAN 决策</td>
    </tr>
    <tr>
      <td>EXECUTING</td><td>IDLE</td>
      <td>Quota 耗尽（异常终止）</td>
      <td>触发 Clean Shutdown 协议（见下文）</td>
    </tr>
  </table>

  <h3>Clean Shutdown 协议（异常终止善后）</h3>
  <div class="code-label">Gateway 原子操作序列</div>
  <pre><code><span class="hl-dim"># 1. 强制快照（不触发 pre-commit hooks）</span>

git add -A git commit -m <span class="hl-orange">"[CLADA_INTERRUPTED]: Quota exhausted at IT-042"</span> --no-verify git checkout -b clada/interrupted/IT-042

<span class="hl-dim"># 2. 保存中断现场</span> { <span class="hl-green">"iteration_id"</span>: <span class="hl-orange">"IT-042"</span>, <span class="hl-green">"last_trace"</span>: <span class="hl-orange">"[TRACE] Modified: auth.ts, db.ts, session.ts"</span>, <span class="hl-green">"pending_question"</span>: <span class="hl-orange">"..."</span>, <span class="hl-dim">// 来自 q_waiting.json（如有）</span> <span class="hl-green">"modified_files"</span>: [<span class="hl-orange">"src/auth.ts"</span>, <span class="hl-orange">"src/db.ts"</span>], <span class="hl-green">"stack_summary"</span>: <span class="hl-orange">"..."</span> <span class="hl-dim">// Summarizer 生成的摘要</span> } <span class="hl-dim">→ interrupted_state.json</span>

<span class="hl-dim"># 3. 提示 Owner 选择</span> <span class="hl-orange">"任务在 IT-042 中断。代码已保存至 clada/interrupted/IT-042 分支。"</span> <span class="hl-orange">"[A] 补充 Quota 继续 [B] 回滚至 main [C] 保留分支稍后处理"</span></code></pre> </div>

<!-- SECTION 5: 通讯协议 -->
<div class="section" id="protocols">
  <div class="section-label">§ 05 · Communication Protocols</div>
  <h2>Agent 间通讯协议</h2>

  <h3>ARBITRATING → EXECUTING：Append Injection</h3>
  <p>Verifier 的裁决通过 Gateway 以 <strong>SYSTEM_NOTIFICATION</strong> 格式直接写入 Executor 的 PTY STDIN，伪装成 Owner 指令。Executor 不需要读取第三方文件，在会话流中直接获取最新指令。</p>
  <div class="code-label">注入格式（写入 Executor PTY STDIN）</div>
  <pre><code>[SYSTEM_NOTIFICATION]: Verifier has resolved your query.

Decision: <span class="hl-green">{裁决内容}</span> Referenced ADR: <span class="hl-orange">DR-024</span> Constraint: This decision is binding. Do not deviate. Please integrate this decision and continue your current task.</code></pre>

  <h3>EXECUTING → SUSPENDED：q_waiting.json</h3>
  <div class="code-label">.comm/q_waiting.json</div>
  <pre><code>{

<span class="hl-green">"iteration_id"</span>: <span class="hl-orange">"IT-042"</span>, <span class="hl-green">"question_id"</span>: <span class="hl-orange">"Q-007"</span>, <span class="hl-green">"type"</span>: <span class="hl-orange">"interface_ambiguity"</span>, <span class="hl-dim">// 歧义类型</span> <span class="hl-green">"context"</span>: <span class="hl-orange">"Spec 未定义跨模块接口的错误传递方式"</span>, <span class="hl-green">"affected_files"</span>: [<span class="hl-orange">"src/auth.ts"</span>, <span class="hl-orange">"src/session.ts"</span>], <span class="hl-green">"quota_used"</span>: <span class="hl-blue">3</span>, <span class="hl-green">"timestamp"</span>: <span class="hl-blue">1716880200</span> }</code></pre>

  <h3>[TRACE] 输出规范</h3>
  <div class="code-label">Executor 每修改 3 个文件输出一次</div>
  <pre><code>[TRACE] IT-042 | Modified: src/auth.ts, src/db.ts, src/session.ts

[TRACE] Status: Implementing login endpoint per ASSERT-01 [TRACE] Next: Write unit test for Argon2id hash verification</code></pre> <p><strong>消费路径</strong>：Gateway 实时将 TRACE 发送给 Summarizer（轻量级模型），生成 <code>current_progress.md</code>，供 Owner 实时查看。Summarizer 输出<strong>严禁</strong>进入 Executor 或 Verifier 的上下文。</p>

  <h3>[B_PLAN] 标签协议</h3>
  <div class="note-box">
    <strong>触发条件</strong>
    Executor Quota 耗尽但任务未完成时，必须在下一次代码提交中附加 [B_PLAN] 标签，表明此次决策为"无Spec依据的主观判断"。
  </div>
  <pre><code><span class="hl-dim">// 代码注释中标注</span>

<span class="hl-orange">// [B_PLAN]: Session expiry set to 24h — no spec guidance, owner must confirm</span>

<span class="hl-dim">// TRACE 中也必须出现</span> [TRACE] [B_PLAN] IT-042 | Decision without spec: session TTL = 86400s</code></pre> <p><strong>审计后果</strong>：Verifier 发现 [B_PLAN] 后，即便测试全部通过，审计结论为 <code>PASS_WITH_RISK</code>，强制进入 WAITING_FOR_OWNER，<strong>禁止 autopilot 合并</strong>。</p> </div>

<!-- SECTION 6: contract.json -->
<div class="section" id="contract">
  <div class="section-label">§ 06 · Contract Specification</div>
  <h2>contract.json 完整规范</h2>
  <p>Contract 是系统的"机器可读宪法"，优先级高于一切自然语言文档。Verifier 以此为审计标准，Executor 以此为实现边界。</p>

  <h3>字段分类</h3>
  <div class="field-row">
    <div class="field-name">contract_id <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">string</div>
    <div class="field-desc">格式 CNT-xxx，唯一标识。版本升级时创建新 CNT，旧 CNT 标记 superseded_by。</div>
  </div>
  <div class="field-row">
    <div class="field-name">version <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">semver</div>
    <div class="field-desc">语义化版本。Hard Fields 变更必须升 major，Soft Fields 变更升 minor。</div>
  </div>
  <div class="field-row">
    <div class="field-name">scope.modules <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">string[]</div>
    <div class="field-desc">本 Contract 覆盖的模块列表。Executor 不得修改范围外的模块而不创建新 Contract。</div>
  </div>
  <div class="field-row">
    <div class="field-name">scope.interfaces <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">string[]</div>
    <div class="field-desc">涉及的 API 端点或函数签名。格式：<code>METHOD /path</code> 或 <code>FunctionName(args): ReturnType</code>。</div>
  </div>
  <div class="field-row">
    <div class="field-name">constraints.strict_types <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">boolean</div>
    <div class="field-desc">是否强制严格类型。影响 Verifier 的类型检查策略。</div>
  </div>
  <div class="field-row">
    <div class="field-name">constraints.max_latency_ms <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">number</div>
    <div class="field-desc">性能硬指标。Verifier 的测试脚本中必须包含延迟断言。</div>
  </div>
  <div class="field-row">
    <div class="field-name">constraints.allowed_dependencies <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">string[]</div>
    <div class="field-desc">白名单依赖库。Executor 引入白名单外依赖时 Gateway 拦截并报错。</div>
  </div>
  <div class="field-row">
    <div class="field-name">hard_assertions <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">Assertion[]</div>
    <div class="field-desc">每条断言包含 id、description、check_script（可执行验证脚本路径）。Verifier 直接运行脚本，不做主观判断。</div>
  </div>
  <div class="field-row">
    <div class="field-name">soft_recommendations <span class="badge badge-soft">Soft</span></div>
    <div class="field-type">Rec[]</div>
    <div class="field-desc">编码风格建议，不影响审计结论。Owner 在双检锁阶段自行选择。</div>
  </div>
  <div class="field-row">
    <div class="field-name">superseded_by <span class="badge badge-soft">Soft</span></div>
    <div class="field-type">string?</div>
    <div class="field-desc">废弃时填写继任 CNT 编号。RAG 系统据此过滤过期 Contract。</div>
  </div>

  <h3>完整示例</h3>
  <div class="code-label">docs/spec/contract.json</div>
  <pre><code>{

<span class="hl-green">"contract_id"</span>: <span class="hl-orange">"CNT-001"</span>, <span class="hl-green">"version"</span>: <span class="hl-orange">"1.0.0"</span>, <span class="hl-green">"created_by"</span>: <span class="hl-orange">"bootstrap-dual-lock"</span>, <span class="hl-green">"bootstrap_warning"</span>: <span class="hl-orange">"未经历史 ADR 审计，由 Owner 手动确认"</span>, <span class="hl-green">"scope"</span>: { <span class="hl-green">"modules"</span>: [<span class="hl-orange">"auth"</span>, <span class="hl-orange">"database"</span>], <span class="hl-green">"interfaces"</span>: [<span class="hl-orange">"POST /v1/login"</span>, <span class="hl-orange">"POST /v1/logout"</span>] }, <span class="hl-green">"constraints"</span>: { <span class="hl-green">"strict_types"</span>: <span class="hl-blue">true</span>, <span class="hl-green">"max_latency_ms"</span>: <span class="hl-blue">200</span>, <span class="hl-green">"allowed_dependencies"</span>: [<span class="hl-orange">"zod"</span>, <span class="hl-orange">"argon2"</span>, <span class="hl-orange">"jsonwebtoken"</span>] }, <span class="hl-green">"hard_assertions"</span>: [ { <span class="hl-green">"id"</span>: <span class="hl-orange">"ASSERT-01"</span>, <span class="hl-green">"description"</span>: <span class="hl-orange">"密码必须在存储前用 Argon2id 哈希处理"</span>, <span class="hl-green">"check_script"</span>: <span class="hl-orange">"npm run test:security"</span> }, { <span class="hl-green">"id"</span>: <span class="hl-orange">"ASSERT-02"</span>, <span class="hl-green">"description"</span>: <span class="hl-orange">"登录接口 P95 延迟必须低于 200ms"</span>, <span class="hl-green">"check_script"</span>: <span class="hl-orange">"npm run test:perf -- --assert-p95=200"</span> } ], <span class="hl-green">"soft_recommendations"</span>: [ { <span class="hl-green">"id"</span>: <span class="hl-orange">"REC-01"</span>, <span class="hl-green">"description"</span>: <span class="hl-orange">"优先使用 async/await 而非裸 Promise"</span> } ], <span class="hl-green">"superseded_by"</span>: <span class="hl-blue">null</span> }</code></pre>

  <h3>Contract 版本演进规则</h3>
  <p>当 Contract 从 1.0.0 升级时，旧 CNT 不删除，标记 <code>superseded_by: "CNT-002"</code>。历史 DR 中引用旧 CNT 编号的记录保持原样（历史真实性），但 RAG 检索时通过 L2 index.json 的 superseded 字段自动过滤，不向 Agent 提供过期 Contract 内容。</p>
</div>

<!-- SECTION 7: DR-xxx -->
<div class="section" id="dr">
  <div class="section-label">§ 07 · Decision Records</div>
  <h2>DR-xxx.md 决策记录规范</h2>
  <p>DR（Decision Record）是系统的"判例法库"。所有重大决策必须记录，Verifier 在仲裁时必须引用 DR 而非凭空判断。</p>

  <h3>Front-matter 字段（机器可读，RAG 过滤依据）</h3>
  <div class="field-row">
    <div class="field-name">id <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">DR-xxx</div>
    <div class="field-desc">三位数字编号，唯一，递增。</div>
  </div>
  <div class="field-row">
    <div class="field-name">title <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">string</div>
    <div class="field-desc">一句话描述决策内容。</div>
  </div>
  <div class="field-row">
    <div class="field-name">status <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">enum</div>
    <div class="field-desc"><code>proposed</code> | <code>accepted</code> | <code>superseded</code>。RAG 过滤器据此剔除 superseded 记录。</div>
  </div>
  <div class="field-row">
    <div class="field-name">superseded_by <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">DR-xxx?</div>
    <div class="field-desc">若 status 为 superseded，必须填写继任 DR 编号。</div>
  </div>
  <div class="field-row">
    <div class="field-name">date <span class="badge badge-hard">Hard</span></div>
    <div class="field-type">YYYY-MM-DD</div>
    <div class="field-desc">决策日期，用于 RAG 按时间排序。</div>
  </div>
  <div class="field-row">
    <div class="field-name">tags <span class="badge badge-soft">Soft</span></div>
    <div class="field-type">string[]</div>
    <div class="field-desc">分类标签，用于 RAG 关键词检索。</div>
  </div>
  <div class="field-row">
    <div class="field-name">related_contract <span class="badge badge-soft">Soft</span></div>
    <div class="field-type">CNT-xxx?</div>
    <div class="field-desc">与本决策关联的 Contract 版本。</div>
  </div>

  <h3>完整示例</h3>
  <div class="code-label">docs/decisions/DR-024.md</div>
  <pre><code><span class="hl-dim">---</span>

<span class="hl-green">id</span>: DR-024 <span class="hl-green">title</span>: 使用 DeepSeek V4 作为 Executor 模型 <span class="hl-green">status</span>: accepted <span class="hl-green">superseded_by</span>: null <span class="hl-green">date</span>: 2026-05-04 <span class="hl-green">tags</span>: [model-selection, cost-control] <span class="hl-green">related_contract</span>: CNT-001 <span class="hl-dim">---</span>

Context

初始方案使用 Claude Opus，但长期运行的 Token 成本过高，在 100 天迭代周期内不可持续。

Decision

切换至 DeepSeek V4-Pro 通过 CLI Bridge 接入作为 Executor 模型。

Rationale

V4-Pro 在编码基准测试中达到可比分数，成本降低约 90%，对长周期 Ralph Loop 至关重要。

Trade-offs

• 放弃：Claude Opus 在复杂推理任务中的优势
• 获得：每月约 $500 的成本节省，可持续运行能力

Consequences

• ✅ 总 Token 成本下降 90%
• ⚠️ 复杂推理任务延迟轻微上升
• ❌ 部分多语言任务质量略有下降

Verification

• Gateway 仪表盘监控 Token 用量

• 每次 Audit 运行 <span class="hl-orange">npm run test:audit</span> 验证编码准确性</code></pre>

  </div> <!-- SECTION 8: 三级记忆 --> <div class="section" id="memory"> <div class="section-label">§ 08 · Memory System</div> <h2>三级记忆系统</h2> <p>三级记忆是对抗"100天后幻觉"的核心机制。每一级有明确的写入者、读取时机和过期机制。</p>

  <div class="card-grid">
    <div class="card green">
      <div class="card-title">L1 · Active（工作记忆）</div>
      <div class="card-body">
        <strong style="color:var(--accent)">内容：</strong>当前修改文件 + current_spec.md + .cursorrules<br><br>
        <strong style="color:var(--accent)">机制：</strong>Gateway 在每次唤醒 Agent 时动态注入 System Prompt。Agent 的上下文窗口只包含当前任务相关内容。<br><br>
        <strong style="color:var(--accent)">生命周期：</strong>单次 Iteration
      </div>
      <div class="card-tag">In-Context</div>
    </div>
    <div class="card blue">
      <div class="card-title">L2 · Structural（架构记忆）</div>
      <div class="card-body">
        <strong style="color:var(--accent2)">内容：</strong>DR-xxx.md 集合 + architecture.md + L2 index.json<br><br>
        <strong style="color:var(--accent2)">写入者：</strong>Verifier（每次 ARBITRATING 后更新）<br><br>
        <strong style="color:var(--accent2)">读取时机：</strong>/propose 和 /ask_verifier 时强制读取<br><br>
        <strong style="color:var(--accent2)">过期机制：</strong>index.json 维护 superseded 字段，Gateway 在注入前预过滤
      </div>
      <div class="card-tag">File-Based</div>
    </div>
    <div class="card orange">
      <div class="card-title">L3 · Historical（向量记忆）</div>
      <div class="card-body">
        <strong style="color:var(--accent3)">内容：</strong>IT-xxx.md（迭代快照）+ 对话全量 Log<br><br>
        <strong style="color:var(--accent3)">写入者：</strong>后台异步脚本，每次 Iteration 结束后压缩写入<br><br>
        <strong style="color:var(--accent3)">检索策略：</strong>双重检索（关键词 + AST 代码片段），Verifier 对结果二次过滤<br><br>
        <strong style="color:var(--accent3)">过期机制：</strong>Gateway 在喂给 Agent 前检查 DR front-matter，剔除 superseded 记录
      </div>
      <div class="card-tag">Vector RAG</div>
    </div>
  </div>
  
  <h3>L2 index.json 结构</h3>
  <div class="code-label">docs/decisions/index.json（Gateway 过滤依据）</div>
  <pre><code>{
  

  <span class="hl-green">"decisions"</span>: [ { <span class="hl-green">"id"</span>: <span class="hl-orange">"DR-024"</span>, <span class="hl-green">"status"</span>: <span class="hl-orange">"accepted"</span>, <span class="hl-green">"superseded_by"</span>: <span class="hl-blue">null</span>, <span class="hl-green">"tags"</span>: [<span class="hl-orange">"model-selection"</span>], <span class="hl-green">"summary"</span>: <span class="hl-orange">"使用 DeepSeek V4 作为 Executor，节省 90% 成本"</span> }, { <span class="hl-green">"id"</span>: <span class="hl-orange">"DR-005"</span>, <span class="hl-green">"status"</span>: <span class="hl-orange">"superseded"</span>, <span class="hl-green">"superseded_by"</span>: <span class="hl-orange">"DR-024"</span>, <span class="hl-green">"tags"</span>: [<span class="hl-orange">"model-selection"</span>], <span class="hl-green">"summary"</span>: <span class="hl-orange">"[DEPRECATED] 使用 Claude Opus 作为 Executor"</span> } ], <span class="hl-green">"contracts"</span>: [ { <span class="hl-green">"id"</span>: <span class="hl-orange">"CNT-001"</span>, <span class="hl-green">"status"</span>: <span class="hl-orange">"active"</span>, <span class="hl-green">"version"</span>: <span class="hl-orange">"1.0.0"</span> } ] }</code></pre>

  </div> <!-- SECTION 9: Bootstrap --> <div class="section" id="bootstrap"> <div class="section-label">§ 09 · Bootstrap</div> <h2>Bootstrap 引导流程（clada init）</h2> <p>Bootstrap 是 CLADA 唯一要求 Owner 高强度介入的阶段。此阶段生成的 Contract 和 ADR 是整个项目的"宪法创世"，必须经过双检锁确认后才能进入稳态。</p>

  <div class="risk-box">
    <strong>⚠ Bootstrap 警告</strong>
    此阶段 Verifier 处于"格式化工具模式"，没有历史 ADR 可参考。生成的 contract.json 必须由 Owner 像审计法律合同一样仔细审阅。系统会在 Contract 上自动标注 bootstrap_warning 字段，直到经过至少一次完整 Iteration 验证后才移除。
  </div>
  
  <h3>双检锁机制</h3>
  <p>Bootstrap 阶段由两个不同模型分别生成 Contract，Gateway 进行字段级比对，Owner 只仲裁差异点。</p>
  
  <div class="flow">
  

<span class="hl-dim">Step 1</span> Owner 输入 Goal 文本 <span class="flow-arrow">↓</span> <span class="hl-dim">Step 2</span> <span class="flow-agent">Model A (Claude)</span> 生成 contract_a.json <span class="flow-agent">Model B (GPT-4o)</span> 生成 contract_b.json <span class="flow-arrow">↓ 并行</span> <span class="hl-dim">Step 3</span> Gateway 执行 Hard Fields 字段级 Key-Value 比对 <span class="flow-arrow">↓</span> <span class="hl-dim">Step 4a</span> Hard Fields 不一致 → <span class="hl-red">标红，Owner 必须手动选择</span> <span class="hl-dim">Step 4b</span> Soft Fields 不一致 → <span class="hl-orange">标黄，Owner 可选择或忽略</span> <span class="hl-dim">Step 4c</span> 所有字段一致 → <span class="hl-green">自动通过</span> <span class="flow-arrow">↓</span> <span class="hl-dim">Step 5</span> Owner 点击 Confirm → contract.json 状态从"流体"变为"晶体" <span class="flow-arrow">↓</span> <span class="hl-dim">Step 6</span> 系统写入 DR-001.md（技术选型决策） 生成初始 L2 index.json 标注 bootstrap_warning，进入 IDLE </div>

  <h3>冷启动 RAG 处理</h3>
  <p>若 L3 为空（新项目），Gateway 扫描现有代码库生成 Repo Map，作为第一份 <code>architecture.md</code> 写入 L2。若代码库也为空，则 architecture.md 仅包含 Goal 和技术栈选型，后续每次 Iteration 增量追加。</p>
</div>

<!-- SECTION 10: 隔离机制 -->
<div class="section" id="isolation">
  <div class="section-label">§ 10 · Isolation</div>
  <h2>物理隔离机制详解</h2>
  <p>CLADA 的隔离分两个独立防御层，针对不同的安全目标，适用对象不同。</p>

  <table>
    <tr><th>防御层</th><th>适用对象</th><th>防御目标</th><th>实现方式</th></tr>
    <tr>
      <td><strong>宿主机文件代理</strong></td>
      <td>Executor</td>
      <td>逻辑泄密（读取 secrets、修改 docs）</td>
      <td>Gateway 通过 LD_PRELOAD 或 ptrace 拦截文件系统调用，返回 EACCES</td>
    </tr>
    <tr>
      <td><strong>Docker 容器隔离</strong></td>
      <td>Verifier（测试运行时）</td>
      <td>执行风险（破坏性测试代码）</td>
      <td>Docker DIND + iptables 白名单网络 + 只读 Volume 挂载</td>
    </tr>
  </table>

  <h3>AUDITING 阶段完整隔离流程</h3>
  <div class="code-label">Gateway 执行序列</div>
  <pre><code><span class="hl-dim"># 1. 进入 AUDITING 前锁定宿主机源码目录</span>

chmod -R 555 ./src <span class="hl-dim"># Read & Execute only，剥夺写权限</span>

<span class="hl-dim"># 2. 启动 fswatch 守护（宿主机层面监控）</span> fswatch -r ./src | while read f; do echo "[SECURITY] Unauthorized write attempt: $f" kill -9 $EXECUTOR_PID <span class="hl-dim"># 立即杀死违规进程</span> done &

<span class="hl-dim"># 3. 拉起 Docker 容器（只读挂载源码）</span> docker run --rm
-v $(pwd)/src:/app/src:ro \ <span class="hl-dim"># 只读挂载</span> -v $(pwd)/test_results:/results \ <span class="hl-dim"># 可写输出目录</span> --network=clada-test-net \ <span class="hl-dim"># 隔离网络（仅 LocalStack）</span> clada-verifier:latest
npm run test:all

<span class="hl-dim"># 4. 测试完成后恢复权限</span> chmod -R 755 ./src docker rm -f clada-verifier-$(ITERATION_ID)</code></pre>

  <div class="risk-box">
    <strong>⚠ 技术风险：fswatch 与 Docker Volume</strong>
    fswatch 监控宿主机 inode。容器内通过 Volume 映射的写操作是否能被宿主机 fswatch 捕获，取决于 Volume 挂载方式（bind mount vs overlay）。在 bind mount 模式下 inode 共享，fswatch 可捕获；在某些 overlay 配置下可能无法捕获。<strong>必须在目标环境实测验证</strong>。
  </div>
</div>

<!-- SECTION 11: 技术风险 -->
<div class="section" id="risks">
  <div class="section-label">§ 11 · Technical Risks</div>
  <h2>技术风险清单</h2>

  <table>
    <tr><th>风险编号</th><th>风险描述</th><th>严重性</th><th>缓解策略</th><th>状态</th></tr>
    <tr>
      <td><code>RISK-01</code></td>
      <td>SIGSTOP 挂起期间 Claude Code 与 Anthropic 服务器的 TCP 长连接超时（通常 60-120s）</td>
      <td><span style="color:var(--warn)">高</span></td>
      <td>Gateway 恢复前检查连接状态；断线则重新注入 current_spec.md 上下文片段；建议部署 Ollama 本地备选模型</td>
      <td>⚠️ 待实测</td>
    </tr>
    <tr>
      <td><code>RISK-02</code></td>
      <td>fswatch 在特定 Docker Volume 挂载方式下无法捕获容器内写操作</td>
      <td><span style="color:var(--accent3)">中</span></td>
      <td>使用 bind mount 模式；或改用 inotifywait（Linux）替代；AUDITING 开始前的 chmod 555 作为主防线</td>
      <td>⚠️ 待实测</td>
    </tr>
    <tr>
      <td><code>RISK-03</code></td>
      <td>Heartbeat 的 <code>#: heartbeat</code> 空注释被 Agent 当成用户消息触发不必要响应</td>
      <td><span style="color:var(--accent3)">中</span></td>
      <td>在 PTY 层拦截 Agent 回应该注释的输出，不转发给 Owner；或改用纯 PTY 控制序列（不经 Agent 解析）</td>
      <td>⚠️ 待实测</td>
    </tr>
    <tr>
      <td><code>RISK-04</code></td>
      <td>LD_PRELOAD 文件访问代理在不同 OS / Agent 运行时（如容器化 Claude Code）下可能失效</td>
      <td><span style="color:var(--accent3)">中</span></td>
      <td>备选方案：使用 Linux namespace（mount ns）创建受限文件系统视图；macOS 上使用 sandbox-exec</td>
      <td>⚠️ 设计备选</td>
    </tr>
    <tr>
      <td><code>RISK-05</code></td>
      <td>Bootstrap 双检锁生成的 contract.json 语义差异无法通过字段级 Key-Value 比对发现</td>
      <td><span style="color:var(--accent)">低</span></td>
      <td>Hard Fields 严格字符串比对已足够；Soft Fields 差异由 Owner 人工仲裁；Meta-Schema 强制字段存在性</td>
      <td>✅ 已设计</td>
    </tr>
  </table>
</div>

<!-- SECTION 12: 实现路线图 -->
<div class="section" id="roadmap">
  <div class="section-label">§ 12 · Implementation Roadmap</div>
  <h2>实现路线图</h2>

  <h3>Phase 1 · 核心骨架（优先级最高）</h3>
  <table>
    <tr><th>任务</th><th>交付物</th><th>关键验证点</th></tr>
    <tr>
      <td>PTY 封装与 SIGSTOP 兼容性测试</td>
      <td><code>orchestrator.py</code> 基础版</td>
      <td>Claude Code 在 SIGSTOP 60s 后恢复的上下文完整性</td>
    </tr>
    <tr>
      <td>Pattern Monitor 线程</td>
      <td>触发词正则引擎</td>
      <td>[REQ_REVIEW] / [DONE] / [B_PLAN] 可靠识别</td>
    </tr>
    <tr>
      <td>状态机骨架</td>
      <td><code>current_state.json</code> 读写逻辑</td>
      <td>八个状态的转移不出现死锁或漏转</td>
    </tr>
    <tr>
      <td>contract.json Meta-Schema 验证器</td>
      <td><code>contract_validator.py</code></td>
      <td>Hard Fields 缺失时 Bootstrap 报错拒绝通过</td>
    </tr>
  </table>

  <h3>Phase 2 · 隔离与记忆</h3>
  <table>
    <tr><th>任务</th><th>交付物</th><th>关键验证点</th></tr>
    <tr>
      <td>Docker 测试环境</td>
      <td><code>Dockerfile.verifier</code> + <code>docker-compose.test.yml</code></td>
      <td>LocalStack 模拟外部服务；破坏性测试不影响宿主机</td>
    </tr>
    <tr>
      <td>chmod 互斥锁 + fswatch</td>
      <td>AUDITING 阶段物理锁定逻辑</td>
      <td>bind mount 场景下 fswatch 捕获率 100%</td>
    </tr>
    <tr>
      <td>L2 index.json 维护</td>
      <td><code>memory_manager.py</code></td>
      <td>superseded DR 不出现在 Agent 上下文</td>
    </tr>
    <tr>
      <td>Heartbeat 守护</td>
      <td>30s 计时器 + 探针逻辑</td>
      <td>探针不触发 Agent 业务逻辑响应</td>
    </tr>
  </table>

  <h3>Phase 3 · 完整流水线</h3>
  <table>
    <tr><th>任务</th><th>交付物</th><th>关键验证点</th></tr>
    <tr>
      <td>Bootstrap 双检锁 UI</td>
      <td><code>clada init</code> 命令</td>
      <td>Hard Fields 差异必须 Owner 手动仲裁，无法跳过</td>
    </tr>
    <tr>
      <td>L3 向量库集成</td>
      <td>RAG 管道 + Summarizer 接入</td>
      <td>双重检索 + superseded 过滤正确工作</td>
    </tr>
    <tr>
      <td>Clean Shutdown 协议</td>
      <td>异常终止善后逻辑</td>
      <td>中断后 git stash 完整，下次可选择恢复</td>
    </tr>
    <tr>
      <td>Owner 控制台 UI</td>
      <td>实时 TRACE 面板 + 断点设置</td>
      <td>$1 费用限制 / 5文件修改限制 可靠触发</td>
    </tr>
  </table>

  <div class="completeness">
    <div class="completeness-title">方案完整度评估</div>
    <div class="progress-item">
      <div class="progress-label"><span>三权分立架构设计</span><span>100%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:100%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>状态机定义</span><span>100%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:100%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>文档规范（Contract + DR）</span><span>100%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:100%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>通讯协议（Injection / TRACE / B_PLAN）</span><span>100%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:100%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>隔离机制设计</span><span>95%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:95%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>技术风险覆盖</span><span>95%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:95%"></div></div>
    </div>
    <div class="progress-item">
      <div class="progress-label"><span>PTY 兼容性（待实测）</span><span>70%</span></div>
      <div class="progress-bar"><div class="progress-fill" style="width:70%"></div></div>
    </div>
    <div class="progress-item" style="margin-top:16px;padding-top:16px;border-top:1px solid var(--border)">
      <div class="progress-label"><span style="color:var(--heading);font-weight:500">总体完整度</span><span>95%</span></div>
      <div class="progress-bar" style="height:6px"><div class="progress-fill" style="width:95%"></div></div>
    </div>
  </div>

  <div class="note-box">
    <strong>✅ 结论</strong>
    CLADA 方案已达到可进入实现阶段的完整度。剩余 5% 集中在三个需要实测验证的技术前提（RISK-01/02/03），建议在 Phase 1 结束时专门安排一个"兼容性验证 Sprint"，以实测结果修正对应的设计细节，再进入 Phase 2。
  </div>
</div>

</div> </div> </body> </html>

这两个思路都触到了真实的东西，但方向不同，我分开说。

---

ohmyopenagent 的 LISP/AST 思路

它真正有价值的洞察不是 LISP 本身，而是：把任务描述变成可被机器操作的树结构，而不是自然语言。

自然语言 Spec 的问题是歧义在传递过程中会放大。但 AST 形式的任务描述是可以被程序验证的——你能判断"这个节点有没有被执行"、"这个分支有没有覆盖"。这和 CLADA 的 contract.json 思路是同一个方向，只是表达层不同。

你说"如果只面向一种形态，规则重合度很高"——这个判断是对的，而且 LISP/AST 的价值正好在这里：当你把目标领域限定了，任务树的节点类型就是有限的。一个 2C app 的任务树，节点无非是：数据模型、页面、交互、网络调用、状态管理——就这几类。这个有限集合是可以被穷举和形式化的，Executor 不需要从自然语言里猜你要什么。

但我要泼一盆冷水：领域限定本身是个硬问题。"2C app 不考虑后端"听起来简单，但 UI 框架、状态管理方案、设计规范、目标平台，每一个维度都会分叉。你限定的不是"2C app"，你限定的是一个具体的技术栈 + 设计语言的组合。一旦限定够窄，规则确实清晰，但这时候你建的已经不是通用框架，而是一个垂直领域的代码生成器。这不是贬义，有时候这恰恰是更有价值的东西。

---

建筑行业的类比

这个思路比 ohmyopenagent 更有系统性，而且你说到了一个 CLADA 目前完全缺失的东西：流程的强制顺序性。

建筑里监理不是在最后验收，而是每一步完工才能开始下一步，而且监理和施工方用的是不同的标准文件——施工方看施工图，监理看验收规范，两者都对，但不是同一个文件。这个结构非常精确地描述了一个 CLADA 现在没有的机制。

让我把建筑角色映射到软件，然后指出真正有价值的地方是哪里：

V

visualize

V

visualize show_widget

映射里大部分 CLADA 已经有对应机制了。真正有价值的启发，是图里标红的三个缺口：

---

缺口一：双标准文件

这是建筑里最精妙的设计，也是 CLADA 目前最大的漏洞。

施工方拿的是施工图，监理拿的是验收规范，这两份文件由不同的人在不同时间写成，有意保持独立。施工方不参与写验收规范，监理不参与画施工图。

CLADA 现在的问题是：contract.json 同时充当了这两个角色。Executor 拿它作为实现依据，Verifier 也拿它作为审计依据。这意味着如果 contract 本身有歧义，两边都会用同一种方式理解错误。

建筑行业的解法是：分成两份文件，写法不同，角度不同。对应到 CLADA 就是：

• spec.md — 给 Executor 看的，描述"要做什么"，以功能为中心
• acceptance_criteria.json — 给 Verifier 看的，描述"怎么判断做没做到"，以可验证断言为中心

这两个文件在 PROPOSING 阶段由同一个 Verifier 生成，但刻意用不同视角写，然后在四方交底时对齐。

---

缺口二：工序签字（分阶段解锁）

建筑监理的核心权力不是最后验收，而是不签字就不能浇下一层混凝土。这是一种物理级别的强制顺序。

CLADA 现在的状态机已经有顺序，但没有阶段内部的检查点。Executor 在 EXECUTING 状态里可以一直跑，中间没有任何强制的"完成 30% 检查一次"的机制。

建筑里对应的是：地基完成监理签字 → 主体结构 → 监理签字 → 装修。每一层都是独立的合同和验收动作。

映射到 CLADA：在 Spec 里把任务分成若干里程碑（Milestone），Executor 完成每个里程碑输出 [MILESTONE: auth-layer]，Verifier 做一次轻量审计签字，才解锁下一个里程碑。这样 100 天的项目就变成了 20 个 5 天的项目，每个都有独立的 ADR 和验收记录。

---

缺口三：四方交底本身

建筑里交底是一个仪式性的强制同步时刻。所有人站在同一张图纸面前，任何歧义必须当场解决，解决记录签字存档。

CLADA 的 PROPOSING 阶段现在是 Owner 和 Verifier 的两方对话，产出 Spec。但 Executor 在这个阶段是沉默的——它不参与 Spec 的形成，直接收到成品 Spec 开始干活。

建筑行业明确反对这种做法，因为施工方最了解"这个设计能不能建"。所以交底时施工方必须在场，有权提出施工疑问，这些疑问会修改图纸。

对应到 CLADA：在 PROPOSING 结束后、EXECUTING 开始前，加一个"Executor 预审"步骤。Gateway 把 Spec 发给 Executor，让它只读不写，输出它预见的所有歧义点。Verifier 处理这些歧义点修订 Spec。这一步可以消灭 80% 的 [REQ_REVIEW] 中断，因为问题在施工前就暴露了。

---

两个思路合起来看

ohmyopenagent 的贡献是：限定领域，让任务树有限。建筑行业的贡献是：流程顺序有物理强制力，标准文件有意分离。

把这两个合在一起，你会得到一个比 CLADA 更强的架构：领域限定的分阶段交付系统，每个领域有自己的任务节点类型，每个阶段有独立的验收标准文件，Executor 在施工前必须参与交底。这比现在的 CLADA 要具体得多，也要可靠得多——代价是它不再是通用的，而是某个特定领域的专用流水线。

你觉得这个方向值得深入吗？