# harness/ — agent 长时开发的工作环境

这套东西解决的问题：**多轮会话开发时，状态不要存在于聊天记录或人的记忆里，
而是存在于仓库文件中。**

参考：[Learn Harness Engineering](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/)
（核心公式 `Agent = Model + Harness`；设计原则：**短入口，深链接**）

## 结构

```
harness/
├── README.md            本文件：结构导航
├── progress.md          ★ 进度日志：当前已验证状态 + 每轮会话记录
├── feature_list.json    ★ 功能清单：状态 / 验证步骤 / 证据
├── init.sh              安装依赖 + 基础验证 + 打印启动命令
│
├── tools/               脚本都写这里（验证脚本、调试脚本、结构校验）
│   ├── README.md
│   └── validate-harness.mjs  ★ 校验 harness 结构本身（见下「机械约束」）
│
├── docs/                项目文档
│   ├── architecture.md    架构、目录、核心系统、关键约束
│   ├── quality.md         质量评分：各领域现状与缺口
│   ├── exec-plans/        ★ 执行计划与技术债
│   │   ├── README.md          计划管理方式（含「计划只能放这里」的硬规则）
│   │   ├── active/            进行中的计划
│   │   ├── completed/         已完成的计划（决策追溯）
│   │   └── tech-debt-tracker.md  技术债清单
│   └── reference/         接口契约与参考资料
│       ├── README.md        索引：先读哪份
│       ├── api-chat.md            现行接口契约
│       ├── api-chat-fields-zh.md  字段中英对照
│       ├── DMS_*.md               DMS 契约与栏目现状（含实测结论）
│       └── legacy/API.md          交接时的代码快照（非规格，勿照抄）
│
└── sops/                标准流程
    ├── session-start.md   开工流程
    ├── session-end.md     收尾清单
    ├── handoff.md         会话交接
    ├── verification.md    验证流程（含本项目踩过的坑）
    └── evaluator-rubric.md 六维度评审表
```

★ = 每轮都会读写；其余按需查。

## 机械约束（不是口头约定）

文档写「计划要放 `exec-plans/`」「同一时间只能一个 `in_progress`」，
光写着没用 —— **违反的时候得有东西报错**：

```bash
node harness/tools/validate-harness.mjs    # 退出码非 0 = 有违规
```

它会检查：必备文件是否齐、有没有游离的计划文件、`feature_list.json` 是否有
假 passing / 重复 id / 多个 in_progress、`progress.md` 的会话编号是否重复。
**收尾时跑一次**（见 `sops/session-end.md`）。

## 怎么用

**开工**：按 [`sops/session-start.md`](sops/session-start.md) 走 ——
读 `progress.md` 与 `feature_list.json` → 看提交 → 跑 `init.sh` → 只选一个功能做。

**收尾**：按 [`sops/session-end.md`](sops/session-end.md) 过一遍清单，
**当场**更新 `progress.md` 与 `feature_list.json`，不要攒到会话结束。

**验证**：按 [`sops/verification.md`](sops/verification.md) ——
接口相关改动必须对真实后端端到端验证，脚本写到 `tools/`。

## 三条规则

1. **同一时间只做一个功能**（`feature_list.json` 里只有一个 `in_progress`）
2. **没有可运行证据不得声称完成**（构建通过只是底线，不是充分条件）
3. **每次改动完成就立刻更新记录**，不要攒 —— 攒到最后必然漏记、且已写下的描述会过期

## 深链接在哪

根 `CLAUDE.md` 只保留**很短的入口**（开工步骤 + 规则 + 指向本目录）。
架构细节、接口契约、流程细节都在 `harness/` 里 —— 这是刻意的：
入口短才有人读，细节深才不会污染入口。

## 与仓库其他部分的关系

| 位置 | 内容 | 入库 |
|---|---|---|
| `README.md` | **改动记录**（按日期），给团队看 | ✅ 入库 |
| `CLAUDE.md` / `agents.md` | 简短入口 + 工作规则 / 开发原则 | ✅ 入库（2026-09-17 起） |
| `harness/`（本目录） | 状态、流程、文档、脚本 | ✅ 入库（2026-09-17 起） |
| `.env.*.local`、`.claude/settings.local.json` | 带凭据的本机配置 | ❌ 不入库 |
| `harness/tools/_*.mjs` | esbuild 打包产物 | ❌ 不入库（会与源码漂移） |

> ⚠️ **不要在三处重复记同一件事。** 变更明细记在 `README.md`；
> `harness/` 里只记 **README 没有的东西** —— 哪些验证过、哪些还挂着、下一步做什么。