by-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

by-harness

by-harness

是一个独立 skill，用来给目标仓库安装并运行一套稳定的工程闭环：

text

read task -> plan -> build -> qa -> fix -> mark_pass -> session_close

核心目标不是“多放一些文档”，而是让模型每次开发都有明确的任务来源、规格、实现边界、验收方式和会话收口记录。

by-harness

is an independent skill used to install and run a stable engineering closed-loop for target repositories:

text

read task -> plan -> build -> qa -> fix -> mark_pass -> session_close

The core goal is not to "add more documents", but to ensure that every model development has clear task sources, specifications, implementation boundaries, acceptance methods, and session closure records.

1. 先判断用户意图

1. First determine user intent

收到请求后，先把用户意图归到下表之一，再执行对应动作。

用户意图	常见说法	主要动作
初始化 harness	“初始化”“用 by-harness 初始化这个仓库”	运行 `scripts/scaffold.py` ，再提示执行或执行 `.harness/scripts/init.sh`
持续拆任务	“持续拆任务”“拆 5 个任务”“把这个主题拆一下”	运行 `scripts/decompose_tasks.py` ，写入 active bucket
执行某个任务	“执行 feat-03”“继续当前任务”	读取任务，按 plan/build/qa/fix/mark_pass 闭环推进
会话收口	“收口”“保存进度”“session_close”	运行 `.harness/scripts/session_close.py`
自动续跑	“继续下个任务”“自动续跑”	运行 `.harness/scripts/task_switch.py continue --target-dir .`
老仓库升级	“升级 harness”“同步 runtime”“更新脚手架”	运行 `scripts/update_runtime.py` ，优先备份与版本化迁移
Java 规范约束	“Java 硬规则”“Service 接口实现”“MapStruct/金额/Redis/分页规则”	使用 `.harness/docs/java-dev-conventions.md` 第 7 章 Java Gate 约束 plan/build/qa
分布式 Java 约束	“分布式编码规范”“幂等/重试/锁/事务/消息/缓存一致性”	使用 `.harness/docs/java-dev-conventions.md` 第 14 章 Distributed Java Gate 约束 spec/contract/build/qa
前端规范约束	“前端规范”“UI 约束”“按设计稿/参考页”	使用已下发的前端三层规范和 BYAI HTML 参考约束实现

如果缺少项目名、目标目录或任务 ID，能从当前仓库和

.harness/task-harness/index.json

推断时直接推断；推断风险高时再问一个简短问题。

After receiving a request, first categorize the user's intent into one of the items in the table below, then perform the corresponding action.

User Intent	Common Phrases	Main Actions
Initialize harness	"Initialize", "Initialize this repository with by-harness"	Run `scripts/scaffold.py` , then prompt to execute or execute `.harness/scripts/init.sh`
Continuous task decomposition	"Decompose tasks continuously", "Split into 5 tasks", "Split this topic"	Run `scripts/decompose_tasks.py` and write to the active bucket
Execute a specific task	"Execute feat-03", "Continue the current task"	Read the task and advance through the plan/build/qa/fix/mark_pass closed-loop
Session closure	"Close the session", "Save progress", "session_close"	Run `.harness/scripts/session_close.py`
Automatic resumption	"Continue to the next task", "Automatic resumption"	Run `.harness/scripts/task_switch.py continue --target-dir .`
Legacy repository upgrade	"Upgrade harness", "Sync runtime", "Update scaffolding"	Run `scripts/update_runtime.py` , prioritizing backup and versioned migration
Java specification constraint	"Java hard rules", "Service interface implementation", "MapStruct/amount/Redis/pagination rules"	Use Chapter 7 Java Gate of `.harness/docs/java-dev-conventions.md` to constrain plan/build/qa
Distributed Java constraint	"Distributed coding specifications", "Idempotency/retry/lock/transaction/message/cache consistency"	Use Chapter 14 Distributed Java Gate of `.harness/docs/java-dev-conventions.md` to constrain spec/contract/build/qa
Frontend specification constraint	"Frontend specifications", "UI constraints", "Follow design draft/reference page"	Use the issued three-tier frontend specifications and BYAI HTML references to constrain implementation

If the project name, target directory, or task ID is missing, infer it directly from the current repository and

.harness/task-harness/index.json

when possible; ask a brief question only if the inference risk is high.

2. 初始化目标仓库

2. Initialize target repository

初始化使用 skill 内置脚本：

bash

python3 {{SKILL_PATH}}/scripts/scaffold.py \
  --project-name "<项目名称>" \
  --description "<项目目标>" \
  --tech-stack "<技术栈，可选>" \
  --project-type "<项目类型，可选>" \
  --design-guidance "<设计约束，可选>" \
  --target-dir "<项目目录>"

初始化后生成：

根目录入口：
```
AGENTS.md
```
、
```
CLAUDE.md
```
Codex / Claude 配置：
```
.codex/
```
、
```
.claude/
```

Harness 工作区：

.harness/config/

、

.harness/docs/

、

.harness/scripts/

、

.harness/task-harness/

任务索引：
```
.harness/task-harness/index.json
```

默认任务桶：

.harness/task-harness/features/backlog-core.json

运行时版本：
```
.harness/config/runtime-version.json
```
更新策略：
```
.harness/config/update-policy.json
```

初始化完成后，执行或提示：

bash

bash .harness/scripts/init.sh

不要在已有项目中默认使用

--force

。只有用户明确要求覆盖时才使用。

Initialization uses the skill's built-in script:

bash

python3 {{SKILL_PATH}}/scripts/scaffold.py \
  --project-name "<项目名称>" \
  --description "<项目目标>" \
  --tech-stack "<技术栈，可选>" \
  --project-type "<项目类型，可选>" \
  --design-guidance "<设计约束，可选>" \
  --target-dir "<项目目录>"

After initialization, the following are generated:

Root directory entries:
```
AGENTS.md
```
,
```
CLAUDE.md
```
Codex / Claude configurations:
```
.codex/
```
,
```
.claude/
```

Harness workspace:

.harness/config/

.harness/docs/

.harness/scripts/

.harness/task-harness/

Task index:
```
.harness/task-harness/index.json
```

Default task bucket:

.harness/task-harness/features/backlog-core.json

Runtime version:
```
.harness/config/runtime-version.json
```
Update policy:
```
.harness/config/update-policy.json
```

After initialization is complete, execute or prompt:

bash

bash .harness/scripts/init.sh

Do not use

--force

by default in existing projects. Only use it when the user explicitly requests overwriting.

3. 任务存储模型

3. Task storage model

默认使用分片任务存储：

```
.harness/task-harness/index.json
```
：路由索引，记录 active bucket。
```
.harness/task-harness/features/*.json
```
：任务分片。
```
.harness/task-harness/progress/latest.txt
```
：最新会话快照，给新会话快速接续。

.harness/task-harness/progress/YYYY-MM.md

：按月追加的会话历史。

.harness/feature_list.json

只用于 legacy 项目兼容：如果旧项目已经存在该文件，可以继续同步 active bucket 视图；新项目不要主动创建它。

Sharded task storage is used by default:

```
.harness/task-harness/index.json
```
: Routing index, records the active bucket.
```
.harness/task-harness/features/*.json
```
: Task shards.
```
.harness/task-harness/progress/latest.txt
```
: Latest session snapshot, for quick resumption in new sessions.

.harness/task-harness/progress/YYYY-MM.md

: Monthly appended session history.

.harness/feature_list.json

is only used for legacy project compatibility: If the file already exists in an old project, you can continue to sync the active bucket view; do not actively create it for new projects.

4. 持续拆任务

4. Continuous task decomposition

当用户要求拆解需求、追加任务或扩展 backlog 时，运行：

bash

python3 {{SKILL_PATH}}/scripts/decompose_tasks.py \
  --target-dir "<项目目录>" \
  --item "<任务描述1>" \
  --item "<任务描述2>" \
  --category "feature"

执行原则：

用户指定数量时尽量满足；未指定时通常拆 4-8 个可执行任务。

每个任务要能进入

read task -> plan -> build -> qa -> fix -> mark_pass

闭环。

新任务默认写入 active bucket；只有用户指定时才切换 bucket。
回报新增任务 ID、优先级、建议执行顺序和下一步命令。

任务过多或旧

feature_list.json

过大时，可运行：

bash

python3 {{SKILL_PATH}}/scripts/rebalance_tasks.py --target-dir "<项目目录>"

When users request to decompose requirements, append tasks, or expand the backlog, run:

bash

python3 {{SKILL_PATH}}/scripts/decompose_tasks.py \
  --target-dir "<项目目录>" \
  --item "<任务描述1>" \
  --item "<任务描述2>" \
  --category "feature"

Execution principles:

Try to meet the quantity specified by the user; if not specified, usually split into 4-8 executable tasks.

Each task must be able to enter the

read task -> plan -> build -> qa -> fix -> mark_pass

closed-loop.

New tasks are written to the active bucket by default; switch buckets only when specified by the user.
Report the new task IDs, priorities, recommended execution order, and next command.

When there are too many tasks or the old

feature_list.json

is too large, you can run:

bash

python3 {{SKILL_PATH}}/scripts/rebalance_tasks.py --target-dir "<项目目录>"

5. 执行任务闭环

5. Execute task closed-loop

当用户要求执行某个 feature，按以下顺序推进：

定位任务：优先用用户给出的
```
feat-id
```
；没有时用
```
.harness/scripts/ensure_task_branch.py
```
选择当前任务。

读取任务：看

description

、

steps

、

spec_path

、

contract_path

、

qa_report_path

。

Plan：生成或更新
```
.harness/docs/specs/<feature>.md
```
。
Build：只实现 contract 范围内的内容。
QA：运行可用测试；QA 默认非阻塞，但失败要记录问题。
Fix：单元测试失败时最多修 3 轮。
Mark pass：单元测试通过，且
```
spec_path
```
/
```
contract_path
```
文件真实存在后，才可把
```
passes=false
```
改为
```
true
```
。
Session close：调用会话收口脚本，刷新最新进度。

如果 3 轮后单元测试仍失败，保持

passes=false

，记录原因、已尝试修复和下一步建议。

When users request to execute a feature, proceed in the following order:

Locate the task: Prioritize using the
```
feat-id
```
provided by the user; if not available, use
```
.harness/scripts/ensure_task_branch.py
```
to select the current task.

Read the task: Check

description

steps

spec_path

contract_path

qa_report_path

Plan: Generate or update
```
.harness/docs/specs/<feature>.md
```
.
Build: Only implement content within the contract scope.
QA: Run available tests; QA is non-blocking by default, but failures must be recorded.
Fix: Fix up to 3 rounds if unit tests fail.
Mark pass: Only change
```
passes=false
```
to
```
true
```
after unit tests pass and the
```
spec_path
```
/
```
contract_path
```
files actually exist.
Session close: Call the session closure script to refresh the latest progress.

If unit tests still fail after 3 rounds, keep

passes=false

, record the reason, attempted fixes, and next-step suggestions.

6. 会话收口与续跑

6. Session closure and resumption

每次会话结束或用户要求保存进度时，运行：

bash

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --feature-id "<feat-id>" \
  --outcome "in-progress|completed|blocked" \
  --qa-score "<0-100，可选>" \
  --note "<本轮摘要>"

收口脚本会：

追加进度日志。

刷新

.harness/task-harness/progress/latest.txt

。

输出下一任务建议。

继续下个任务时运行：

bash

python3 .harness/scripts/task_switch.py continue --target-dir .

Run the following each time a session ends or the user requests to save progress:

bash

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --feature-id "<feat-id>" \
  --outcome "in-progress|completed|blocked" \
  --qa-score "<0-100，可选>" \
  --note "<本轮摘要>"

The closure script will:

Append progress logs.

Refresh

.harness/task-harness/progress/latest.txt

Output suggestions for the next task.

Run the following to continue to the next task:

bash

python3 .harness/scripts/task_switch.py continue --target-dir .

7. 老仓库升级

7. Legacy repository upgrade

老仓库优先使用版本化升级，不要重新全量覆盖：

bash

python3 {{SKILL_PATH}}/scripts/update_runtime.py --target-dir "<项目目录>"

升级行为：

先备份关键配置、脚本和运行时文档。
读取
```
.harness/config/runtime-version.json
```
。
有
```
manifest_url
```
时从远程 manifest 拉取并校验 checksum。
没有
```
manifest_url
```
时只执行本地兼容迁移。
当前版本高于内置或远程版本时，只告警，不降级覆盖。

远程定时检查使用：

bash

python3 .harness/scripts/update_runtime.py --target-dir . --check-remote

默认

update-policy.json

是

enabled=false

；只有用户配置

manifest_url

并开启后才自动检查。

Prioritize versioned upgrades for legacy repositories, do not re-overwrite entirely:

bash

python3 {{SKILL_PATH}}/scripts/update_runtime.py --target-dir "<项目目录>"

Upgrade behavior:

First back up key configurations, scripts, and runtime documents.
Read
```
.harness/config/runtime-version.json
```
.
Pull from the remote manifest and verify the checksum if
```
manifest_url
```
exists.
Only perform local compatibility migration if there is no
```
manifest_url
```
.
Only issue an alert and do not downgrade/overwrite if the current version is higher than the built-in or remote version.

Use the following for remote scheduled checks:

bash

python3 .harness/scripts/update_runtime.py --target-dir . --check-remote

The default

update-policy.json

enabled=false

; automatic checks are only performed after the user configures

manifest_url

and enables it.

8. 工程规范下发

8. Engineering specification distribution

初始化会下发两类工程规范：

后端：
```
.harness/docs/java-dev-conventions.md
```

前端入口：

.harness/docs/frontend-dev-conventions.md

Java 后端采用 Java Gate：

Plan 阶段声明触发项：Service、入口依赖、MapStruct、中文注释、金额、分页、Redis、日志、配置密钥。
所有 Java 改动必须声明 Distributed Java Gate：未触发需说明理由；触发外部调用、Dubbo/HTTP/RPC、MQ、异步、线程池、锁、Redis、事务、补偿或发布停机时，必须逐条对照第 14 章。
Contract 阶段必须把 Java Gate 和 Distributed Java Gate 转成可验收清单，不能只写“已阅读规范”。
Build 阶段复述适用清单并按正反例实现。
QA 阶段对照 contract 和 convention-check 结果验收。
Stop hook 阶段自动拦截可机器识别的 fail/warn。

前端采用三层结构：

约束层：
```
.harness/docs/frontend/rules.md
```
示范层：
```
.harness/docs/frontend/code-design.md
```
视觉层：
```
.harness/docs/frontend/ui-design.md
```

视觉参考：

.harness/docs/frontend/references/byai-ds-v/index.html

当前任务涉及 React、Vue、Next.js、TypeScript 组件、UI、样式、表格、表单、图表、Agent 界面或交互状态时，模型必须先阅读

.harness/docs/frontend-dev-conventions.md

，再按任务类型阅读三层规范。

新增页面、重构页面或明显视觉变更时，还必须打开 BYAI HTML 参考页。参考页用于理解布局、密度、状态、token 和视觉气质，不要把 demo HTML 直接复制成业务实现。

Two types of engineering specifications are distributed during initialization:

Backend:
```
.harness/docs/java-dev-conventions.md
```

Frontend entry:

.harness/docs/frontend-dev-conventions.md

Java backend adopts Java Gate:

Declare trigger items in the Plan phase: Service, entry dependencies, MapStruct, Chinese comments, amount, pagination, Redis, logs, configuration keys.
All Java changes must declare Distributed Java Gate: Explain the reason if not triggered; when triggering external calls, Dubbo/HTTP/RPC, MQ, asynchronous operations, thread pools, locks, Redis, transactions, compensation, or release downtime, must check against Chapter 14 item by item.
In the Contract phase, Java Gate and Distributed Java Gate must be converted into an acceptable checklist, not just write "have read the specifications".
In the Build phase, repeat the applicable checklist and implement according to positive and negative examples.
In the QA phase, accept according to the contract and convention-check results.
In the Stop hook phase, automatically intercept machine-identifiable fail/warn.

Frontend adopts a three-tier structure:

Constraint layer:
```
.harness/docs/frontend/rules.md
```
Demonstration layer:
```
.harness/docs/frontend/code-design.md
```
Visual layer:
```
.harness/docs/frontend/ui-design.md
```

Visual reference:

.harness/docs/frontend/references/byai-ds-v/index.html

When the current task involves React, Vue, Next.js, TypeScript components, UI, styles, tables, forms, charts, Agent interfaces, or interaction states, the model must first read

.harness/docs/frontend-dev-conventions.md

, then read the three-tier specifications according to the task type.

When adding a new page, refactoring a page, or making obvious visual changes, you must also open the BYAI HTML reference page. The reference page is used to understand layout, density, status, tokens, and visual temperament; do not directly copy the demo HTML into business implementations.

9. 运行约束

9. Runtime constraints

```
AGENTS.md
```
是主契约，定义 Plan / Build / Verify / Fix。
```
.harness/docs/TASK-HARNESS.md
```
是任务层契约，不得覆盖主契约。
常规任务只更新任务状态、进度和闭环工件，不随意改任务结构。
单元测试通过且 spec/contract 已落盘后才可
```
passes=true
```
；QA 报告默认非阻塞，但必须记录结果。
任何已标记
```
passes=true
```
的 feature，如果缺少
```
spec_path
```
或
```
contract_path
```
对应文件，pre-completion hook 必须阻断完成。
所有新增或修改的函数、方法必须补齐中文注释，说明用途、关键参数、返回值和副作用。
涉及 Java 时，完成前自检 Java Gate：Service 接口/实现、入口依赖接口、MapStruct ERROR、金额、分页、Redis、日志、配置密钥；同时自检 Distributed Java Gate，并运行 convention-check。
涉及前端时，完成前自检 token、状态覆盖、响应式、可访问性、BYAI 参考页对齐和反例规避。
不使用破坏性 git 命令，不覆盖用户已有修改，不在已有项目中默认
```
--force
```
。

```
AGENTS.md
```
is the main contract, defining Plan / Build / Verify / Fix.
```
.harness/docs/TASK-HARNESS.md
```
is the task-level contract and must not overwrite the main contract.
Regular tasks only update task status, progress, and closed-loop artifacts; do not arbitrarily modify the task structure.
```
passes=true
```
can only be set after unit tests pass and the spec/contract has been saved to disk; QA reports are non-blocking by default, but results must be recorded.
For any feature marked
```
passes=true
```
, if the corresponding
```
spec_path
```
or
```
contract_path
```
file is missing, the pre-completion hook must block completion.
All newly added or modified functions and methods must be supplemented with Chinese comments explaining their purpose, key parameters, return values, and side effects.
When involving Java, self-check Java Gate before completion: Service interface/implementation, entry dependency interface, MapStruct ERROR, amount, pagination, Redis, logs, configuration keys; also self-check Distributed Java Gate and run convention-check.
When involving frontend, self-check tokens, status coverage, responsiveness, accessibility, alignment with BYAI reference pages, and avoidance of negative examples before completion.
Do not use destructive git commands, do not overwrite existing user modifications, and do not use
```
--force
```
by default in existing projects.

10. 回报格式

10. Reporting format

执行完成后，用简短结构回报：

做了什么：初始化、拆任务、执行任务、收口或升级。
改了哪里：列出关键文件或目录。
验证结果：脚本输出、测试、dry-run 或未验证原因。
下一步：给出一个最合适的命令或任务 ID。

After execution is complete, report using a concise structure:

What was done: Initialization, task decomposition, task execution, session closure, or upgrade.
Where changes were made: List key files or directories.
Verification results: Script output, tests, dry-run, or reason for no verification.
Next step: Provide the most appropriate command or task ID.

11. 典型提示词

11. Typical prompts

用 by-harness 初始化这个仓库，项目名 xxx，目标是 xxx

持续拆任务 主题：支付链路稳定性，拆 5 个

执行 feat-03，严格按 read task -> plan -> build -> qa -> fix -> mark_pass

把当前会话收口，记录 qa 分数和下一步

升级这个项目里的 harness runtime

这个 Java 功能按 Java Gate 检查 Service、金额、Redis、分页和配置

这个 Java 功能按分布式编码规范检查幂等、重试、锁、事务和消息

这个前端页面按 BYAI 参考和三层规范重做

Initialize this repository with by-harness, project name xxx, goal is xxx

Continuously decompose tasks, topic: Payment link stability, split into 5 tasks

Execute feat-03, strictly follow read task -> plan -> build -> qa -> fix -> mark_pass

Close the current session, record the qa score and next step

Upgrade the harness runtime in this project

Check this Java feature against Java Gate for Service, amount, Redis, pagination, and configuration

Check this Java feature against distributed coding specifications for idempotency, retry, lock, transaction, and message

Redo this frontend page according to BYAI references and three-tier specifications