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
五步流程
实现细节
这是检查清单，不是每个任务的固定仪式：只有
governed 且命中 matching escalation signal 时才运行 harness_recover.py、harness_env_probe.py 或 harness_checkpoint.py；light 不要求这些 lifecycle helpers。1. Recover（条件化）只有当任务风险较高、系统明确要求加强检查时，才核对当前运行状态、代码改动和本地记录；普通任务只查看完成工作所必需的信息。
2. Clarify确认目标、范围、受众、约束、领域词汇和验收标准；不清楚就进入 requirements。
3. Route按生命周期阶段选择 planner、TDD、QA、安全、发布、文档或 runtime helper；多步工作拆成垂直切片。
4. Verify运行测试、静态检查、浏览器 smoke 或脚本验证，记录四个证据字段。
5. Handoff（条件化）仅在 matching governed escalation 要求时写入 checkpoint：变更面、验证、阻塞项、下一步安全任务。
01
如果任务不明确，不要开始实现
先把模糊请求转成可验证目标。当前仓库的 CONTEXT.md 是统一术语表，定义 DHF、任务阶段、风险路径、验证记录、交接点、修改范围和协作角色等词，并列出应避免的近义词。当前没有 CONTEXT-MAP.md：只有项目以后拆成多个业务领域时，才需要用它指向各领域自己的术语表。相关 ADR 则记录已经确定的架构取舍，避免重复争论。
02
如果要并行 agent，先验证写入边界
多人协作只有在分工清楚、不会互相覆盖时才启动。每个 agent 负责哪些文件、如何证明完成、哪些内容不能改，都要事先写清楚；否则由一个 agent 完成，通常更快也更安全。复杂或跨会话任务还会使用 durable brief 保存这份任务说明。
03
如果要说完成，必须给 fresh evidence
完成不是感觉，而是最近一次命令输出。缺少 command、exit_code、key_output、timestamp 就还没完成。
04
如果在 debug，先建立反馈回路
不要先猜修复。先用失败测试、命令行样例、浏览器检查或运行轨迹稳定复现问题。若现有系统不便重复验证，就搭一个 throwaway harness：在隔离环境中用假数据反复执行最小故障场景，修复后立即用同一路径确认结果。它不接触客户或生产数据；问题解决后删除，或把关键场景转成长期自动化测试。
一个例子
同一个请求，在没有 harness 和有 harness 时，工作质量差异很明显。
“帮我把这个功能做好，然后发出去。”
A
没有 Harness
agent 可能直接改代码、猜测范围、跳过需求、最后用“看起来可以”作为完成依据。
B
使用 DHF
先选择治理 profile；只有 governed escalation 才恢复完整 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 的任务说明书，包含任务类型、现状与目标、必须保持或改变的接口、可验证的验收标准、验证命令、任务强度和明确不做的事项。这些内容刚好回答“要改什么、不能影响什么、怎样证明完成”；文件位置只用于导航，具体实现方法由 worker 决定，避免任务说明过长或过早锁死方案。 | 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 输出 |