By Harness

by-harness

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

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

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

1. 先判断用户意图

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

用户发起 by-harness 指令后，默认输入的技术方案、需求描述或任务背景已经经过用户确认。不要反复澄清需求；能从当前仓库、技术方案、.harness/task-harness/index.json 和既有 spec/contract 推断时，直接形成假设、取舍、风险和范围外事项并继续产出。只有目标目录/任务 ID 完全无法定位、或下一步会执行破坏性操作时，才问一个必要问题。

2. 初始化目标仓库

初始化使用 skill 内置脚本：

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/tasks/
• 运行时版本：.harness/config/runtime-version.json
• 更新策略：.harness/config/update-policy.json

如果目标仓库已经存在 AGENTS.md / AGENT.md / agents.md / agent.md 或 CLAUDE.md / claude.md，初始化与升级都必须保留原内容，只合并或替换 <!-- BEGIN BY-HARNESS MANAGED BLOCK --> 到 <!-- END BY-HARNESS MANAGED BLOCK --> 之间的 by-harness 托管区块。

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

bash .harness/scripts/init.sh

项目根 AGENTS.md / CLAUDE.md 会要求每个新会话开始、处理用户请求前先运行：

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

该检查仍受 .harness/config/update-policy.json 的 check_interval_minutes 限制，默认 12 小时内不会重复访问远程；失败只记录原因，不阻断开发。

不要在已有项目中默认使用 --force。只有用户明确要求覆盖时才使用。

3. 任务存储模型

默认使用 v3 单任务文件存储：

• .harness/task-harness/index.json：稳定路由索引，记录 task_globs，日常拆任务不修改它。
• .harness/task-harness/tasks/*.json 与 .harness/task-harness/tasks/**/*.json：权威任务源，每个任务一个独立 JSON 文件；新任务默认按批次目录归档。
• .harness/task-harness/progress/YYYY-MM/*.md：每次会话一个独立进度文件，避免多分支同时追加同一月度文件。
• .harness/task-harness/progress/latest.txt：legacy 兼容快照，不作为权威进度源。
• .harness/task-harness/features/*.json：只作为 v2/legacy bucket 读取兼容，不作为新任务默认写入目标。
• session-context.json / session-boundary.json 已禁用：收口和续跑只依赖会话日志、任务状态和模型提示，不再写会引发分支冲突的会话运行态 JSON。

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

任务 ID 不再使用 feat-01 这种全局递增序号。新任务内部仍保留由 UTC 时间戳、类型前缀、描述 slug 和短 hash 组成的机器 ID，例如：

20260508T153012Z-feat-login-rate-limit-a3f9c2

文件名和展示名使用批次号、任务号、中文标题和短 hash，例如：

.harness/task-harness/tasks/B001-20260508T153012Z-音频转写/
  T001-音频转写记录DDL和Mapper仓储-a3f9c2.json

任务 JSON 内会写入 batch_id、batch_name、display_id、local_display_id、task_no、title 和 display_name。日常定位优先使用 display_id（如 B001-T001），也兼容完整机器 ID。排序依赖 priority、created_at、id，不要把执行顺序编码进机器 ID。

4. 持续拆任务

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

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

执行原则：

• 任务粒度宁可少而完整，不要碎片化；未指定数量时通常拆 2-5 个可独立验收的功能任务。
• 每个任务必须是一个完整、可验证、可独立闭环的功能切片：包含业务目标、主要实现面、验收标准和验证方式，能进入 read task -> plan -> build -> qa -> fix -> mark_pass 闭环。
• 不按技术层、文件或步骤拆任务：不要把同一功能拆成 DDL、Mapper/DAO、Service、Controller/API、前端页面、测试、文档 等单独任务；这些应作为同一个功能任务的 steps。
• 只有当子项本身可被独立发布、独立验证、独立回滚，且有自己的验收标准时，才拆成单独任务。
• 新任务默认新增到 .harness/task-harness/tasks/<批次目录>/，不得为了追加任务而修改 backlog-core.json 或 index.json。
• 回报新增任务 ID、优先级、建议执行顺序和下一步命令。

旧 feature_list.json 或 v2 bucket 过大时，才考虑运行 legacy 重平衡工具：

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

5. 执行任务闭环

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

1. 定位任务：优先用用户给出的任务 ID；没有时用 .harness/scripts/ensure_task_branch.py 扫描单任务文件与 legacy bucket 后选择当前任务。
2. 读取任务：看 description、steps、spec_path、contract_path、qa_report_path。
3. Plan：生成或更新 .harness/docs/specs/<feature>.md。
4. Build：只实现 contract 范围内的内容。
5. QA Gate：运行可用测试、convention-check、required 集成测试门禁和 Agent Review Closeout（single-pass，只审查一次）；失败要记录问题。
6. Fix：根据 QA Gate 和 Agent Review 结果一次性修复所有问题；单元测试失败时最多修 3 轮。
7. Mark pass：单元测试通过、required QA Gate 通过，required Agent Review（如启用）无 accepted/actionable finding，且 spec_path / contract_path 文件真实存在后，才可把 passes=false 改为 true。
8. Session close：调用会话收口脚本，写入独立进度分片。

如果 3 轮后单元测试仍失败，保持 passes=false，记录原因、已尝试修复和下一步建议。

6. Quick / Fast Track 分流

当用户请求的是明确、局部、可验证改动时，先运行分类器，而不是直接进入完整 feature 闭环。即使用户没有显式说 quick-fix 或 fast-track，只要请求是修复、调整、优化、补测试、改校验、改提示或处理报错这类自然语言改动，且没有显式指定 plan/build/qa/sprint，也必须先分类：

python3 .harness/scripts/quick_fix_classifier.py \
  --target-dir . \
  --prompt "<用户原始改动描述>"

分类器输出 confidence、recommended_mode、risk_flags、changed_files 和 diff 统计：

• confidence=high 且 recommended_mode=quick_fix：可进入 quick-fix。
• recommended_mode=fast_track 且 confidence=high|medium：可进入 fast-track。
• confidence=low 或 recommended_mode=standard_feature：必须走标准 read task -> plan -> build -> qa -> fix -> mark_pass。

Quick/Fast Track 允许范围：

• quick-fix：明确报错、空值保护、typo、日志级别、错误提示、单测/编译小修复；预计不超过 5 个文件、post-diff 不超过 200 行。
• fast-track：局部业务逻辑调整、内部校验规则、Mapper/转换逻辑、非公共配置、小型前端交互、测试补齐、局部异常处理；预计不超过 8 个文件、post-diff 不超过 400 行。
• 不涉及 DB migration、权限/安全、计费、限流、缓存一致性、事务、幂等、外部 API、公共 DTO 或接口契约。

执行后必须复核：

python3 .harness/scripts/quick_fix_classifier.py \
  --target-dir . \
  --phase post-diff \
  --prompt "<用户原始 bug 描述>"

如果 post-diff 出现 risk_flags、超过文件/行数阈值，或验证失败原因不明确，立即补 spec/contract 并升级到标准闭环。quick-fix/fast-track 只写进度日志，不得修改任务定义或把 feature passes 置为 true。

Quick-fix 收口使用：

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --quick-fix \
  --title "<bug 标题>" \
  --outcome pass \
  --note "<修改文件、验证命令和结果>"

如 quick-fix 关联已有任务，可追加 --feature-id "<task-id>" 作为日志引用，但仍不能绕过该任务的 spec/contract/QA Gate 门禁。

Fast-track 收口使用：

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --fast-track \
  --title "<改动标题>" \
  --outcome pass \
  --note "<范围、风险判断、验证命令和结果>"

7. 会话收口与续跑

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

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

completed 作为旧命令兼容别名，会被脚本映射为 pass；新命令必须优先使用 pass。

收口脚本会：

• 写入 .harness/task-harness/progress/YYYY-MM/<timestamp>-<task-id>.md 独立进度日志。
• quick-fix/fast-track 写入 .harness/task-harness/progress/YYYY-MM/<timestamp>-quickfix|fasttrack-<slug>.md，并在日志中记录 work_mode=quick_fix|fast_track。
• legacy 项目兼容刷新 .harness/task-harness/progress/latest.txt。
• 输出下一任务建议。

继续下个任务时运行：

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

8. 老仓库升级

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

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

升级行为：

• 默认不创建备份文件；确需升级前快照时显式传 --backup。
• 读取 .harness/runtime-cache/runtime-version.json，没有 cache state 时再读 .harness/config/runtime-version.json。
• 有 manifest_url 时从远程 manifest 拉取并校验 checksum；Python runtime 与 hook 写入 .harness/runtime-cache/，项目 tracked 位置只保留稳定 wrapper，避免多分支重复产生 runtime diff。
• 没有 manifest_url 时只执行本地兼容迁移。
• 当前版本高于内置或远程版本时，只告警，不降级覆盖。

远程定时检查使用：

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

默认 update-policy.json 是 enabled=false；只有用户配置 manifest_url 并开启后才自动检查。

9. 工程规范下发

初始化会下发 Java 工程规范：

• Java 入口：.harness/docs/java-dev-conventions.md
• Java 分片：.harness/docs/java/rules/

Java 后端采用分片 Java 总门禁，并融合真实项目验证过的落地规则：

• Plan 阶段先读 Java 入口，再按触发维度读取分片规则：00-core.md、java-ddd.md、dubbo-api.md、logging-error.md、persistence-infra.md、testing-security.md、distributed-java-gate.md。
• Plan 阶段必须执行最小实体与成本评估：如无必要，勿增实体；历史项目小改动优先复用既有实体、表、DTO、Service、配置和扩展点。
• 所有 Java 改动都必须处理 Java 总门禁 5 条：先契约后实现、先本地后通用、边界不被突破、风险显式落地、验证可追溯。
• 业务状态、任务类型、动作类型、错误码、配置 key、阈值禁止散落魔法字符串/魔法数字；使用 enum、语义常量或配置项集中管理。
• 按触发维度追加 5 条左右核心门禁：通用工程、分层与 DDD、Dubbo 与公共 API、日志与异常、持久化与基础设施、测试安全运维、分布式 Java 门禁。
• 所有 Java 改动必须声明分布式 Java 门禁：未触发需说明理由；触发外部调用、Dubbo/HTTP/RPC、MQ、异步、线程池、锁、Redis、事务、补偿或发布停机时，必须逐条对照 distributed-java-gate.md。
• Contract 阶段必须把 Java 总门禁、触发维度核心门禁、分布式 Java 门禁转成可验收清单，不能只写“已阅读规范”。
• Build 阶段复述总门禁和触发维度门禁，并按正反例实现。
• QA 阶段对照 contract、触发分片、convention-check、Testcontainers 集成测试矩阵和 QA result JSON 验收。
• Stop hook 阶段自动拦截可机器识别的 fail/warn。

10. 运行约束

• AGENTS.md 是主契约，定义 Plan / Build / Verify / Fix。
• .harness/docs/TASK-HARNESS.md 是任务层契约，不得覆盖主契约。
• 常规任务只更新对应单任务 JSON 的状态、进度和闭环工件，不随意改任务结构。
• quick-fix/fast-track 只用于快速旁路日志，不得作为 feature 完成依据；需要完成 feature 时必须回到标准门禁。
• 规划方案必须遵守“如无必要，勿增实体”；历史项目小改动默认按最小成本实施，新增实体/表/DTO/Service/配置项必须写明必要性、替代方案、迁移成本和回滚影响。
• 单元测试通过、required QA Gate 通过、required Agent Review（如启用）通过且 spec/contract 已落盘后才可 passes=true；advisory/manual QA 与 Agent Review 结果必须记录。
• 任何已标记 passes=true 的 feature，如果缺少 spec_path 或 contract_path 对应文件，pre-completion hook 必须阻断完成。
• 所有新增或修改的函数、方法必须补齐中文注释，说明用途、关键参数、返回值和副作用。
• 涉及 Java 时，完成前自检 Java 总门禁、魔法值治理、触发维度核心门禁和分布式 Java 门禁，并运行 convention-check。读取规范时必须先读入口，再按触发维度读分片，不能默认整包加载所有规则。
• 不使用破坏性 git 命令，不覆盖用户已有修改，不在已有项目中默认 --force。

11. 回报格式

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

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

12. 典型提示词

• 用 by-harness 初始化这个仓库，项目名 xxx，目标是 xxx
• 持续拆任务 主题：支付链路稳定性，拆 5 个
• 执行 20260508T153012Z-feat-login-rate-limit-a3f9c2，严格按 read task -> plan -> build -> qa -> fix -> mark_pass
• quick-fix 修复一个明确小 bug，先分类，修完后 quick close
• fast-track 调整一个局部校验规则，先分类，修完后 fast close
• 把当前会话收口，记录 qa 分数和下一步
• 升级这个项目里的 harness runtime
• 这个 Java 功能按 Java 总门禁检查 Service、金额、Redis、分页和配置
• 这个 Java 功能按分布式编码规范检查幂等、重试、锁、事务和消息