{"_id":"@bojunchai/harness-kit","name":"@bojunchai/harness-kit","dist-tags":{"latest":"0.3.3"},"versions":{"0.3.3":{"name":"@bojunchai/harness-kit","version":"0.3.3","description":"A stack-agnostic scaffolding kit for AI-coding-agent harnesses. Drops a complete 5-subsystem harness (instructions / state / feedback / observability / governance) into any new or existing repo. Based on walkinglabs/learn-harness-engineering.","keywords":["ai-agents","agents-md","harness-engineering","claude-code","codex","opencode","scaffolding","developer-tools","coding-agent"],"homepage":"https://github.com/Bojun-Vvibe/harness-kit#readme","bugs":{"url":"https://github.com/Bojun-Vvibe/harness-kit/issues"},"repository":{"type":"git","url":"git+https://github.com/Bojun-Vvibe/harness-kit.git"},"license":"MIT","author":{"name":"Bojun Chai","url":"https://github.com/Bojun-Vvibe"},"type":"module","main":"dist/cli.cjs","bin":{"harness":"dist/cli.cjs","harness-kit":"dist/cli.cjs"},"engines":{"node":">=18.0.0"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"biome check .","lint:fix":"biome check --write .","format":"biome format --write .","typecheck":"tsc --noEmit","check":"npm run lint && npm run typecheck && npm run test && npm run build","prepublishOnly":"npm run check"},"dependencies":{"@clack/prompts":"^0.7.0","cac":"^6.7.14","fast-glob":"^3.3.2","kleur":"^4.1.5"},"devDependencies":{"@biomejs/biome":"^1.9.4","@types/node":"^22.10.5","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^2.1.8"},"_id":"@bojunchai/harness-kit@0.3.3","gitHead":"cb7879d14289c22cce9756adf3aee17f21a94c91","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-N7YhSAh/6vwKC5VT+0q5XQpERr7FNKx/+k/O2PMBgMyOr657p0QOXG8uDmnnkhT3O+cb8Iv61FPN8eqnr1TVWA==","shasum":"f312b3d30b15f8d0b16e486dcacdab90e875a875","tarball":"https://registry.npmjs.org/@bojunchai/harness-kit/-/harness-kit-0.3.3.tgz","fileCount":38,"unpackedSize":252187,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBjswOdvPyYDCDcIIxt6bh0ciDKDFdd423k9xLIjTsbDAiEAgf6d7YvqsdlK71iJ8zjDHmk9g2u0jFBcCSa8+U9nJBQ="}]},"_npmUser":{"name":"bojunchai","email":"bmayday.chai@gmail.com"},"directories":{},"maintainers":[{"name":"bojunchai","email":"bmayday.chai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/harness-kit_0.3.3_1778728222801_0.461431663490399"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T03:10:22.648Z","0.3.3":"2026-05-14T03:10:22.957Z","modified":"2026-05-14T03:10:23.202Z"},"maintainers":[{"name":"bojunchai","email":"bmayday.chai@gmail.com"}],"description":"A stack-agnostic scaffolding kit for AI-coding-agent harnesses. Drops a complete 5-subsystem harness (instructions / state / feedback / observability / governance) into any new or existing repo. Based on walkinglabs/learn-harness-engineering.","homepage":"https://github.com/Bojun-Vvibe/harness-kit#readme","keywords":["ai-agents","agents-md","harness-engineering","claude-code","codex","opencode","scaffolding","developer-tools","coding-agent"],"repository":{"type":"git","url":"git+https://github.com/Bojun-Vvibe/harness-kit.git"},"author":{"name":"Bojun Chai","url":"https://github.com/Bojun-Vvibe"},"bugs":{"url":"https://github.com/Bojun-Vvibe/harness-kit/issues"},"license":"MIT","readme":"# harness-kit\n\n> 一个面向 AI 编码 agent 的工程脚手架。一条命令，给任何新老项目装上完整的「指令 / 状态 / 反馈 / 可观测 / 治理」五子系统 harness。技术栈无关。\n\n[![npm version](https://img.shields.io/npm/v/harness-kit.svg)](https://www.npmjs.com/package/harness-kit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> [English](./README.md) · **简体中文** · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Português](./README.pt.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md)\n\n---\n\n## 这是什么\n\n`harness-kit` 是 [**walkinglabs/learn-harness-engineering**](https://github.com/walkinglabs/learn-harness-engineering)（[课程站点](https://walkinglabs.github.io/learn-harness-engineering/)）这门课讲的那套 harness 思想的工具化实现。课程提炼自 OpenAI 和 Anthropic 公开的工程实践。\n\n课程（以及这个工具）建立在三篇原始文章之上：\n\n- [OpenAI — *Harness Engineering: Leveraging Codex in an Agent-First World*](https://openai.com/index/harness-engineering/)\n- [Anthropic — *Effective Harnesses for Long-Running Agents*](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)\n- [Anthropic — *Harness Design for Long-Running Application Development*](https://www.anthropic.com/engineering/harness-design-long-running-apps)\n\n核心论点：**换更贵的模型是最贵的修法，修 harness 是最便宜的。** 这个工具直接把 harness 给你装上。\n\n一条 `harness init`，你的项目里就会出现：\n\n- `AGENTS.md` — 路由式入口（≤ 200 行，不是百科全书）\n- `CONSTRAINTS.md` — 不可违反的硬约束\n- `docs/` — 架构、决策日志、测试标准（按主题拆分）\n- `PROGRESS.md` — 跨会话日记本，agent 不再\"断片\"\n- `features.json` — 项目脊梁骨，每个功能项必须带 `verification` 命令\n- `QUALITY.md` — 模块质量评分，告诉下个 agent 该先修哪\n- `Makefile` — `setup / test / lint / check` 等标准 target（命令体由你填）\n- `scripts/exit-clean.sh` — L12 五维度退场检查\n- `scripts/session-init.sh` — 入场简报\n- `scripts/e2e-check.sh` — 三层（静态 / 行为 / 系统）校验\n- `docs/templates/sprint-contract.md` + `rubric.md` — 多步骤工作模板\n- `.github/workflows/harness.yml` — 把 exit-clean 跑进 CI\n- 各家 agent 配置文件（`CLAUDE.md`、`.codex/AGENTS.md` 等），全部指回 `AGENTS.md`\n\n全部纯文本。没有后台进程。没有锁定。**技术栈无关**——Node、Python、Rust、Go、移动端、混合栈都行。删掉脚手架文件还能用。\n\n---\n\n## 安装 / 使用\n\n工具自带一个 `harness` CLI。生成出来的 `Makefile` 和 `scripts/` 都直接调 `harness ...`，所以基本都要把它装到 PATH 里。\n\n```bash\n# 推荐：全局装一次 ────────────────────────────────────────────────\nnpm install -g harness-kit\nharness init                 # 新项目（交互式）\nharness inject               # 老项目（默认 dry-run）\n\n# 或者零安装用 npx ───────────────────────────────────────────────\n# 注意：npx 只在那一次调用里暴露 `harness` 命令。\n# 生成的 Makefile / scripts 都引用 `harness doctor`，\n# 所以你最终还是会想全局装一次。\nnpx harness-kit init\nnpx harness-kit inject --apply\n```\n\n如果你用了 `npx`，然后跑 `harness doctor` 报 \"command not found: harness\"，全局装一次就好：\n\n```bash\nnpm install -g harness-kit\n```\n\n---\n\n## init 完之后：把这段 prompt 丢给你的 agent\n\n脚手架里到处是 TODO 占位。**别手动填**。\n\n**`harness init` 跑完会自动把这段 prompt 直接打印到终端**，并存一份到 `.harness/bootstrap-prompt.txt`。随时再看：\n\n```bash\ncat .harness/bootstrap-prompt.txt   # init 时打印的那份原文\n```\n\n想 init 时直接出指定语言的 prompt，传 `--lang`：\n\n```bash\nharness init --lang zh   # en | zh | ja | ko | es | pt | fr | de\n```\n\n下面是中文版 prompt，方便参考——在你的 coding agent（Claude Code / Codex / OpenCode / Cursor / Aider）里打开项目，把它整段粘进去：\n\n```\n你现在在一个刚被 harness-kit 初始化过的仓库里工作。\n你的任务是：把这套 harness 在 THIS 项目里落实成真。\n\n1. 通读所有生成出来的脚手架文件：AGENTS.md、CONSTRAINTS.md、PROGRESS.md、\n   QUALITY.md、docs/architecture.md、docs/decisions.md、\n   docs/testing-standards.md、Makefile、.harnessrc.json。先理解结构。\n\n2. 检查项目本身：读 package.json / pyproject.toml / Cargo.toml / go.mod /\n   src 目录树 / 现有 README / CI 配置 / lockfile。搞清楚这个项目到底是什么、\n   用的什么栈、入口在哪、已经在遵守什么约定。\n\n3. 把所有生成文档里的 `> **TODO**:` 占位替换成对 THIS 项目为真的内容。\n   要具体——引用真实的文件名和行号。如果某条信息你不能高置信度回答，\n   就留 `> **TODO(@me, YYYY-MM-DD): need answer for X**`，不要瞎编。\n\n4. 把 Makefile 里的占位 target body（setup / dev / test / lint / typecheck /\n   build / clean）替换成项目真实的命令。每条都验证：先 `make -n <target>`，\n   再 `make <target>` 跑一次。如果某个 target 在这个项目不适用，留成 `@true`\n   并加一行注释说明为什么不适用。\n\n5. 在 CONSTRAINTS.md 里，把示例的 \"Code constraints\" 和 \"Forbidden\" 两节\n   换成 5–15 条对 THIS 项目为真的硬约束。从已有测试、lint 配置、CI、错误\n   处理代码、ADR 里推导出来。不适用的示例直接删。\n\n6. features.json 暂时不要自己加 feature。等用户告诉你要做什么。要加的时候，\n   严格按 FEATURES.md 里的规则来——那是编辑 features.json 的契约（状态机、\n   WIP=1、verification 门控、反模式）。先读一遍，再动手。\n\n7. 全部完成后验证并盖章：\n   - 跑 `make check` —— 必须 exit 0\n   - 跑 `harness doctor` —— 分数必须 ≥ 24/30\n   - 在 PROGRESS.md 末尾追加一段 `## Session <ISO 时间戳>`，写清楚做了什么\n     （bootstrap：为 <项目名> 填好脚手架）\n   - 跑 `bash scripts/exit-clean.sh` —— 必须 exit 0\n\nbootstrap 期间的硬规则：\n- WIP = 1。不要开始写新功能。\n- 除了第 1 步列出的脚手架文件之外，不要修改任何文件。\n- 在 `harness doctor` 和 `make check` 都通过之前，不能宣布完成。\n- 仓库里实在推导不出来的事情，问用户——不要瞎编。\n```\n\n把它存成 snippet，每次新搭项目就用它。\n\n---\n\n## 命令\n\nCLI 故意做得极小：2 个脚手架命令 + 2 个诊断命令 + 1 个 viewer。其余日常工作都在生成出来的仓库里——markdown + 脚本，可读、可 grep、可改。\n\n| 命令 | 干什么 |\n|---|---|\n| `harness init [dir]` | 全新项目装 harness（交互式），写入约 18 个文件。结束时自动打印 bootstrap prompt |\n| `harness inject [dir]` | 给老项目注入。默认 dry-run；`--apply` 真正写入。已有 `AGENTS.md` / `Makefile` 安全合并 |\n| `harness doctor [dir]` | 给五子系统每项打分（满分 5），加冷启动测试（5 个问题）。和 `view` 用同一套标签 |\n| `harness view [dir]` | 启一个 localhost dashboard（默认端口 3737），按 **指令 / 工具 / 环境 / 状态 / 反馈** 5 个子系统可视化当前项目的 harness |\n| `harness clean [dir]` | 跑 L12 五维度 exit-clean（构建/测试/进度/工件/启动路径）|\n\ninit 之后基本不再需要 `harness` CLI。日常工作流都在：\n\n| 操作 | 在哪做 |\n|---|---|\n| 管理 feature（add / start / done / block）| 直接编辑 `features.json`，按 `FEATURES.md` 里的规则 |\n| 验证 feature 真的做完了 | `bash scripts/validate-feature.sh <id>` |\n| Session 开始的简报 | `bash scripts/session-init.sh` |\n| Session 结束的检查 | 在 `PROGRESS.md` 加一段，再 `bash scripts/exit-clean.sh` |\n| 再看一遍 bootstrap prompt | `cat .harness/bootstrap-prompt.txt` |\n\n---\n\n## 五子系统对应表（每条对应一讲）\n\n| 子系统 | 生成文件 | 讲义 |\n|---|---|---|\n| **指令** | `AGENTS.md`, `CONSTRAINTS.md`, `docs/architecture.md`, `docs/decisions.md`, `docs/testing-standards.md` + 各 agent 路由文件 | L02 / L04 |\n| **状态** | `PROGRESS.md`, `features.json`, `FEATURES.md`, `QUALITY.md` | L05 / L08 / L12 |\n| **反馈** | `Makefile`, `scripts/exit-clean.sh`, `scripts/session-init.sh`, `scripts/validate-feature.sh`, `scripts/e2e-check.sh` | L02 / L09 / L10 |\n| **可观测** | `docs/templates/sprint-contract.md`, `docs/templates/rubric.md` | L11 |\n| **治理** | `CONSTRAINTS.md`, `.github/workflows/harness.yml`, `.harnessrc.json` | L03 / L12 |\n\n---\n\n## 三个不容讨价还价的强约束\n\n1. **WIP = 1**：`features.json` 同时只能有一个 feature 处于 `active`。这条规则写在 `FEATURES.md` 里，靠 agent 自律 + git diff review 执行。彻底干掉「同时启动六件事，零件做完」的失败模式（L07）。\n\n2. **完成的唯一路径是 verification**：每个 feature 必须有 verification 命令。只有 `bash scripts/validate-feature.sh <id>` 退出码 0 才能标 passing。「我看着没问题」≠ done（L09）。\n\n3. **干净退场是「完成」的一部分**：`scripts/exit-clean.sh` 五维度检查（构建/测试/PROGRESS 是否最近更新/无残留临时文件/启动路径可调）。CI 里跑同一个脚本（L12）。\n\n---\n\n## 支持的 agent\n\n`claude-code` / `codex` / `opencode` / `cursor` / `aider`。每家在它期望的位置写一个文件，全部指回 `AGENTS.md` 作为唯一真相源。\n\n---\n\n## 跟 spec-kitty 的区别\n\n[spec-kitty](https://github.com/spec-kitty/spec-kitty) 是更重的、mission 驱动的 harness。`harness-kit` 是最小化、覆盖 80% 场景的精简版。两个可以并存——`harness-kit` 跑在 spec-kitty 下面没问题。\n\n| | harness-kit | spec-kitty |\n|---|---|---|\n| 概念数量 | 少（5 个子系统）| 多（mission / WP / charter / doctrine）|\n| 出第一个有用产出 | 几分钟 | 一小时上下 |\n| 工作流意见 | 无——你自己定 | 强——必须 specify→plan→tasks→implement→review |\n| 老项目注入 | 一等公民（`inject` 命令） | 可以但不是重点 |\n| 依赖 | 仅 Node ≥ 18 | Python + 几个 |\n\n---\n\n## License\n\nMIT © Bojun Chai。详见 [LICENSE](./LICENSE)。\n\n## 致谢与出处\n\n这个项目只是别人想法的工程化封装。生成文件里的 `L01`–`L12` 讲义编号都对应：\n\n- [**walkinglabs/learn-harness-engineering**](https://github.com/walkinglabs/learn-harness-engineering)\n  —— 课程 GitHub 仓库 / [可读站点](https://walkinglabs.github.io/learn-harness-engineering/)\n\n课程本身则是对以下三篇工程文章的提炼：\n\n- OpenAI —— [Harness Engineering: Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)\n- Anthropic —— [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)\n- Anthropic —— [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps)\n\n如果这个工具帮到你，也请去给 walkinglabs 的课程仓库点个 star——它是这套框架的源头。\n","readmeFilename":"README.zh.md","_rev":"1-ea446741e26517e07b1aa603905b127b"}