harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The repository is the system of record. Chat is not. State that must survive a session lives in files; a fresh session recovers it by reading them, not by guessing. Based on Learn Harness Engineering.

代码仓库是唯一事实来源，Chat 不是。必须跨会话保留的状态存放在文件中；新会话通过读取这些文件来恢复状态，而不是依靠猜测。基于 Learn Harness Engineering。

Init (once per repo, skip files that already exist)

初始化（每个仓库执行一次，跳过已存在的文件）

Copy from

templates/

next to this file, then adapt — never leave placeholders:

```
.agents/progress.md
```
— session log + current verified state.
```
.agents/features.json
```
— every user-visible feature with
```
id
```
,
```
priority
```
,
```
status
```
,
```
verification
```
steps and
```
evidence
```
. Write real features from the repo's README/issues/code; all start
```
not_started
```
.

Optional for large sessions:

templates/session-handoff.md

→

.agents/handoff.md

Dependencies are installed by the devcontainer features, not here; the baseline is the CI status on the repo's dev forge (GitHub, GitLab, Azure DevOps), which the hook prints. Put each feature's real verification steps in

.agents/features.json

. Commit the files as one change. Once

.agents/progress.md

.agents/features.json

exists, the

SessionStart

hook prints the state and the

Stop

hook checks the handoff.

从此文件旁的

templates/

中复制，然后进行调整——绝不能保留占位符：

```
.agents/progress.md
```
——会话日志和当前已验证状态。
```
.agents/features.json
```
——每个用户可见功能及其
```
id
```
、
```
priority
```
、
```
status
```
、验证步骤和
```
evidence
```
。根据仓库的 README/issues/code 填写真实功能；所有功能初始状态均为
```
not_started
```
。

大型会话可选：将

templates/session-handoff.md

复制为

.agents/handoff.md

。

依赖项由 devcontainer features 安装，而不是在此处安装；基线是仓库开发平台（GitHub、GitLab、Azure DevOps）上的 CI 状态，hook 会打印该状态。将每个功能真实的验证步骤写入

.agents/features.json

。将这些文件作为一次变更提交。一旦

.agents/progress.md

或

.agents/features.json

存在，

SessionStart

hook 就会打印状态，

Stop

hook 就会检查交接情况。

Session start

会话开始

```
pwd
```
— confirm the repo root.
Read the repo's own rules:
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
.agents/instructions/*.instructions.md
```
(the
```
SessionStart
```
hook lists which exist). They stay authoritative for commit format, PR base/title, scope limits and tooling; the harness adds the loop around them, it never overrides them.

Read

.agents/progress.md

, then

.agents/features.json

```
git log --oneline -5
```
. The
```
SessionStart
```
hook already printed the state and the forge CI status of the branch.
CI red on the branch? That is the baseline: fix it first. No new work on a broken start.
Pick the highest-priority unfinished feature. Set it
```
in_progress
```
. One at a time.

执行
```
pwd
```
——确认仓库根目录。
阅读仓库自身的规则：
```
CLAUDE.md
```
、
```
AGENTS.md
```
、
```
.agents/instructions/*.instructions.md
```
（
```
SessionStart
```
hook 会列出哪些文件存在）。这些规则始终是提交格式、PR base/title、范围限制和工具使用方面的权威依据；harness 只是为它们添加工作循环，绝不会覆盖它们。

读取

.agents/progress.md

，然后读取

.agents/features.json

。

执行
```
git log --oneline -5
```
。
```
SessionStart
```
hook 已经打印了状态和当前分支在开发平台上的 CI 状态。
分支上的 CI 是否失败？那就是当前基线：先修复它。不能在损坏的状态下开始新工作。
选择优先级最高的未完成功能，将其状态设为
```
in_progress
```
。每次只处理一个。

While working

工作过程中

Follow the repo's rules while working (minimal-change discipline, commit/PR format, CI naming). A rule conflict with the harness: the repo rule wins; record it in the progress log.
Stay inside the selected feature. A blocker may justify one narrow supporting fix.
```
passing
```
needs the feature's
```
verification
```
steps actually run, with evidence recorded (command + result, not "looks fine").
Never reword, delete or weaken a feature or test to make it pass. Never loosen verification mid-feature.
Declared done? Run the
```
harness-evaluator
```
agent: fresh context, tries to refute the claim.

工作时遵循仓库规则（最小变更原则、commit/PR 格式、CI 命名）。如果规则与 harness 冲突，以仓库规则为准；在进度日志中记录该冲突。
始终将工作范围限定在选定的功能内。遇到阻塞问题时，可以进行一次范围 narrowly 集中的辅助修复。
标记为
```
passing
```
前，必须实际运行该功能的
```
verification
```
步骤，并记录证据（命令和结果），不能只写“看起来没问题”。
绝不能通过改写、删除或弱化功能或测试来使其通过。功能开发期间绝不能放宽验证标准。
声明完成？运行
```
harness-evaluator
```
agent：使用全新的上下文，尝试反驳该完成声明。

Session end

会话结束

Update
```
.agents/progress.md
```
: verified state, what ran, evidence, known risk, next best step.
Update
```
.agents/features.json
```
statuses and evidence.
Walk
```
templates/clean-state-checklist.md
```
.
Commit once the repo is safe to resume, using the repo's commit and PR conventions from its rules. CI on the branch must be green or explained in the progress log; the next session must start without manual repair.

更新
```
.agents/progress.md
```
：已验证状态、执行内容、证据、已知风险和下一步最佳操作。
更新
```
.agents/features.json
```
中的状态和证据。
按照
```
templates/clean-state-checklist.md
```
逐项检查。
当仓库处于可安全恢复的状态时，按照仓库规则中的 commit 和 PR 约定提交一次。分支上的 CI 必须为绿色，或者在进度日志中说明原因；下一次会话必须无需手动修复即可开始。

Boundaries

边界

Do not invent features, evidence or verification results. Do not mark

passing

without a run. Do not hide unfinished work by editing the list.

不要虚构功能、证据或验证结果。没有实际运行验证，就不能标记为

passing

。不要通过编辑功能列表来隐藏未完成的工作。