Harness Engineering 13：最小可用的 Agent 可读工作区
前面 12 篇讲的是原则。这一篇落到工程目录：如果要把一个普通仓库改造成适合 Agent 长期工作的仓库，最小要放哪些文件？
答案不是先做复杂调度系统，而是先让仓库变得“可读、可跑、可验证、可恢复”。这四个能力到位后，再谈更复杂的多角色和自动循环。
最小目录结构
可以从这一组文件开始：
.
├── AGENTS.md
├── ARCHITECTURE.md
├── PROGRESS.md
├── DECISIONS.md
├── feature_list.json
├── evaluator-rubric.md
├── session-handoff.md
├── clean-state-checklist.md
└── init.sh
这不是文档工程，而是 Agent 的工作接口。每个文件都要服务一个动作。
| 文件 | 目的 | 不应该写成 |
|---|---|---|
AGENTS.md | 入口、硬约束、导航 | 百科全书 |
ARCHITECTURE.md | 系统地图和边界 | 过期架构论文 |
PROGRESS.md | 当前真实状态 | 情绪化流水账 |
DECISIONS.md | 关键取舍 | 会议纪要堆 |
feature_list.json | 任务状态机 | 普通待办 |
evaluator-rubric.md | 验收评分 | 主观好坏判断 |
session-handoff.md | 会话恢复点 | 漂亮总结 |
clean-state-checklist.md | 结束条件 | 可选提醒 |
init.sh | 标准开工路径 | 一次性脚本 |
第一步：写一个短入口
AGENTS.md 的任务是让新会话启动，而不是把项目全部讲完。
# AGENTS.md
## Startup
1. Confirm working directory.
2. Read PROGRESS.md.
3. Read feature_list.json.
4. Run ./init.sh.
5. Select one active feature only.
## Working Rules
- Work on one feature at a time.
- Do not mark passing without evidence.
- Do not expand scope silently.
- If baseline verification fails, stop feature work.
## Definition of Done
- Required verification ran.
- Evidence is recorded.
- Clean-state checklist passes.
入口文件越短，越容易被稳定遵守。复杂规则用链接跳到专题文件。
第二步：让功能清单成为调度器
feature_list.json 是最关键的状态文件。它决定 Agent 该做什么，以及什么时候可以停。
| 必需字段 | 说明 |
|---|---|
id | 稳定任务标识 |
priority | 调度顺序 |
area | 影响范围 |
user_visible_behavior | 用户可见行为 |
status | 当前状态 |
verification | 验证步骤 |
evidence | 实际证据 |
第一版不要塞太多任务。先写 3 到 5 个能明确验证的 feature，让 Agent 学会按状态推进。
第三步：初始化脚本先做小
init.sh 不需要一开始覆盖所有环境。它只要能回答三个问题：依赖是否可用、项目能否启动、最小验证能否跑。
init.sh 应该做：
- 打印当前目录和版本信息。
- 检查必要依赖。
- 检查必要配置。
- 运行一个快速 smoke check。
- 输出下一步建议。
不要让初始化脚本偷偷修改大量状态。它的主要任务是检查和报告。
第四步：进度日志只写可恢复事实
PROGRESS.md 应该帮助下个会话继续，而不是证明上一轮很努力。
推荐格式：
| 区块 | 写什么 |
|---|---|
| Verified now | 当前确实可用 |
| Active feature | 当前唯一任务 |
| Last verification | 跑过的命令和结果 |
| Known risks | 未验证路径 |
| Next step | 下一步和通过标准 |
示例：
## 2026-06-08
Verified now:
- 应用可启动。
- 文档上传 API smoke check 通过。
Active feature:
- import-003：显示导入进度。
Known risks:
- 20MB 以上文件未验证。
Next step:
- 加入大文件夹具，跑完整上传流程。
第五步：评价表要能拒绝
evaluator-rubric.md 的价值是让检查者敢于说“不通过”。如果评价表只鼓励总结优点，就没有意义。
| 维度 | 通过问题 |
|---|---|
| 正确性 | 是否实现了目标行为 |
| 验证 | 是否有实际运行证据 |
| 范围 | 是否只改了允许范围 |
| 可靠性 | 重启或重跑后是否仍可用 |
| 可维护性 | 下个会话是否能理解 |
| 交接 | 是否能直接继续 |
每个维度最好有 0 到 2 分。任何关键维度为 0，都应该要求修订。
最小工作流
这个工作流足够小，但已经覆盖了 Harness 的核心：入口、环境、状态、验证、反馈、交接。
常见落地错误
| 错误 | 调整 |
|---|---|
| 一次写 50 个 feature | 先写 3 到 5 个 |
AGENTS.md 写太长 | 拆成入口和专题 |
| 只写文档不写命令 | 加 init.sh 和验证命令 |
| 证据停在终端 | 写回 feature 和 progress |
| 评价表太主观 | 改成证据驱动 |
| 结束不清理 | 增加 clean-state gate |
最小工作区的目标不是自动化一切，而是让每一次 Agent 会话都能从明确状态开始，并在明确状态结束。
参考材料
- Walking Labs：Learn Harness Engineering
https://walkinglabs.github.io/learn-harness-engineering/en/ - Walking Labs 教程源码
https://github.com/walkinglabs/learn-harness-engineering