Problem 01
记忆不可靠
聊天历史可能过期，agent 必须回到 repo 文件、状态日志、git diff 和测试结果里找事实。
Delivery Harness Framework / DHF Beginner Guide
Delivery Harness Framework (DHF)
把模糊请求变成可验证交付。
它不是一个更聪明的 prompt，也不是单个 agent。它是一套工作框架，让 AI 工程任务先恢复事实，再用领域语言和 ADR 锁定范围，按阶段路由执行，最后用新鲜证据证明完成。
一句话：DHF 把“帮我做这个”变成“已读哪些事实、当前处于哪个阶段、谁负责执行、怎样验证、下一次如何接手”。
为什么 beginner 需要它
Agentic engineering 最大的问题通常不是模型不会写代码，而是工作缺少边界、证据和交接。
Problem 02
请求太模糊
如果目标、范围、验收标准或领域词汇不清楚，直接开发会把便宜的澄清问题变成昂贵返工。
Problem 03
工具太多
planner、TDD、QA、安全、发布、文档技能各自有用，但需要一个 router 决定什么时候用谁。
Problem 04
“完成”不可审计
DHF 要求每个完成声明带上 command、exit_code、key_output、timestamp。
Problem 05
下一次无法接手
交接不是总结文学，而是把阶段、变更面、验证证据、阻塞项和下一个安全任务写入状态。
Beginner Rule
先问“现在在哪一步”
不要先问“该写什么代码”。先确认 lifecycle stage，再决定读、规划、写、测、评审还是发布。
三层架构
这是理解 DHF 的最短路径：runtime 给边界，router 选路线，specialists 做具体工作。
Layer 01
Runtime layer
包括 AGENTS.md、hooks、tool policy、evidence schema、checkpoint helper 和测试入口。它回答：什么能做，什么需要证据，什么必须阻断。
rulesstateevidence
Layer 02
Router layer
delivery-harness-framework 读取 durable state，恢复当前阶段，选择下一条 workflow。它回答：现在应该进入 research、requirements、planning、development、validation、review、ship 还是 handoff。
phaseroutingnext safe task
Layer 03
Specialist layer
包括 repo-specific harness、gstack skills、planner、TDD、QA、安全、发布和 doc-updater。它回答：具体由哪个专家流程完成任务。
plannerTDDQAship
五步流程
Beginner 可以把每个任务都压进这五步，而不是直接跳到写代码。
1. Recover读取 AGENTS、README、repo-index、harness state、git 状态和本地 evidence。
2. Clarify确认目标、范围、受众、约束、领域词汇和验收标准；不清楚就进入 requirements。
3. Route按生命周期阶段选择 planner、TDD、QA、安全、发布、文档或 runtime helper；多步工作拆成垂直切片。
4. Verify运行测试、静态检查、浏览器 smoke 或脚本验证，记录四个证据字段。
5. Handoff写入 checkpoint：变更面、验证、阻塞项、下一步安全任务。
01
如果任务不明确，不要开始实现
先把模糊请求转成可验证目标。DHF 会读取 CONTEXT.md、CONTEXT-MAP.md 和相关 ADR，避免用错领域词。
02
如果要并行 agent，先验证写入边界
多 agent 不是越多越好。只有当 write set 不重叠、验证命令明确，必要时还有 durable agent brief，才允许 scoped workers。
03
如果要说完成，必须给 fresh evidence
完成不是感觉，而是最近一次命令输出。缺少 command、exit_code、key_output、timestamp 就还没完成。
04
如果在 debug，先建立反馈回路
不要先猜修复。先拿到 failing test、CLI fixture、browser check、trace replay 或 throwaway harness，再进入假设和修复。
一个例子
同一个请求，在没有 harness 和有 harness 时，工作质量差异很明显。
“帮我把这个功能做好，然后发出去。”
A
没有 Harness
agent 可能直接改代码、猜测范围、跳过需求、最后用“看起来可以”作为完成依据。
B
使用 DHF
先恢复 repo 状态，判断需求和领域语言是否清晰；若不清晰，进入 requirements；若清晰，把多步工作拆成可验证的 vertical slices。
C
交付结果
输出包含阶段判断、已读来源、执行路径、验证命令、退出码、关键输出、时间戳和下一步安全任务。
input request
把一次模糊请求变成 DHF 输出
“请修一下 public docs，让新读者知道应该先看哪一页，并确认改完是通过测试的。”
DHF output
最小可交付证据
command:python3 test_runner.pyexit_code:0key_output:[PASS] lifecycle skill routing doc discoverabletimestamp:2026-05-14T00:00:00-04:00
术语表
| 术语 | 新手解释 | 在本仓库中的对应物 |
|---|---|---|
| Harness | 把 agent 工作固定在安全流程里的“安全带”和“交付轨道”。 | delivery-harness-framework、runtime docs、helpers |
| Runtime | 围绕模型运行的规则、权限、证据、状态和 hooks。 | docs/HARNESS_RUNTIME.md、codex/runtime/* |
| Router | 决定当前任务处于哪个阶段、该交给哪个技能或脚本。 | delivery-harness-framework |
| Skill | 认知工作流：规划、TDD、QA、安全、发布、文档等。 | codex/skills/*、gstack-* |
| Helper | 确定性脚本：恢复、探测、验证、报告、checkpoint。 | scripts/harness_*.py |
| Vertical slice | 一个能单独验证的端到端小切片，而不是只改某一层。 | AFK / HITL planning |
| Durable brief | 给 worker agent 的耐久任务合同，记录 current/desired behavior、key interfaces、acceptance criteria 和 out of scope。 | docs/templates/harness-agent-brief.md |
| Evidence | 证明任务完成的新鲜命令结果。 | command、exit_code、key_output、timestamp |
| Checkpoint | 给下一次会话恢复用的状态记录。 | docs/harness-state.md |
| Next safe task | 下一位 agent 不需要猜就能继续做的安全动作。 | scripts/harness_recover.py 输出 |