auto-harness

Harness 工程脚手架 — 一键初始化「Harness Engineering」多 Agent 协作工程。

npm 包名 @laoliang/auto-harness。

简介

Harness Engineering 是一套把「人 + 多 Agent 协作做软件工程」固化到工程里的方法论：由 PM Agent 统一调度（BA / SA / RR / Dev / CR / TE 分角色流水线），每个阶段强制产出带结论（PASS / BLOCK / REJECT）的文档后才能流转，配合 git 门禁、业务规格（specs）与踩坑记忆（memory）沉淀，让 AI 交付过程可审查、可回滚、可复用。

auto-harness 是这个方法论的脚手架 CLI：

适配状态：目前只适配 Claude Code，后续会提供对其他 AI 编程工具的支持。

• 交互式创建 harness 工程：自动检测 OS + Python 环境（缺失时引导安装）、接入后端 / 前端 / APP 端 git submodule（APP 端可选，部分工程没有）
• 生成完整框架层：CLAUDE.md / .claude 角色与命令 / .harness 流程与脚本（全部 Python、无 .sh，macOS / Windows 双系统兼容）
• 可升级：脚手架发版后 update 一键刷新已生成工程的框架层，保留项目状态；工程后续想补接新的端（如 APP 端），也在 update 里填地址即接入

项目结构

初始化完成后，工程目录结构如下：

<工程目录>/
├── CLAUDE.md                 # Harness 主入口（快速开始 / 完整流程 / 关键约束）
├── .claude/                  # Claude Code 侧配置
│   ├── agents/               # 多 Agent 角色定义（PM / BA / SA / RR / Dev / CR / TE）
│   ├── commands/             # 斜杠命令（/harness-bootstrap、/harness-propose 等）
│   ├── rules/                # 全局纪律（工作流 / OS 兼容 / 代码标准）
│   ├── hooks/                # Claude Code 钩子
│   └── skills/               # 领域技能
├── .harness/                 # 工程核心（随项目版本管理，沉淀项目资产）
│   ├── scripts/              # Python 流程脚本（init_task / spec_merge / archive / verify ...）
│   ├── workflow/             # 流程定义（flow-definition / transitions / contract）
│   ├── specs/                # 业务域规格（spec.md + spec-template.md）
│   ├── deliverables/         # 各任务交付物（proposal / requirements / design / dev-log ...）
│   ├── tasks/                # 任务看板 board.md（PM 调度依据）
│   ├── memory/               # 踩坑记忆（跨任务沉淀）
│   ├── codebase-guide/       # 代码库引导索引
│   ├── templates/            # 语言/技术栈骨架模板（java / dotnet / javascript）
│   ├── git-hooks/            # pre-commit 等门禁
│   └── config.json           # 根配置（主线分支等）
└── services/                 # 按你的 git 地址接入的子模块（backend / frontend）

生成物

• 完整 harness 框架层：角色、命令、规则、流程脚本、门禁钩子、文档模板
• services/ 下按你的 git 地址接入的子模块（.gitmodules + git submodule）
• 工程专属文件（首次 /harness-init 生成）：codebase-guide、specs 索引、看板、memory 骨架

代码地图

harness 使用 Codegraph 作为代码地图——一款面向 AI 编码代理的预索引代码知识图谱工具（官网）。它预先为代码建立符号与调用关系索引，让 AI 检索代码时先命中索引、更快更准。

为提高 AI 编程质量，/harness-init 会给每个子工程安装并初始化三类「AI 上下文」文件：

| 文件 | 作用 | |------|------| | .codegraph/ | Codegraph 代码索引（codegraph init 自动生成） | | CLAUDE.md | 子工程入口说明（技术栈 / 构建命令 / 关键约定） | | docs/CODE_STANDARDS.md | 编码规范 |

这些文件由使用者自行维护——维护得越准确、越贴近工程实际，AI 编码质量越高；子工程已存在的同名文件不会被覆盖（初始化时自动跳过）。

变量占位

| 阶段 | 占位符 | 填充时机 | |------|--------|---------| | 脚手架创建期 | {{PROJECT_NAME}} {{BACKEND_DIR}} {{FRONTEND_DIR}} {{APP_DIR}} {{BACKEND_URL}} {{FRONTEND_URL}} {{APP_URL}} | CLI 生成 README/CLAUDE 等根文件时 | | 生成工程 init 期 | {{SUB_PROJECT}} {{PROJECT_NAME}} {{PROJECT_PATH}} {{MODULE_NAME}} {{MODULE_PATH}} {{APP_NAME}} {{APP_PATH}} | 生成工程运行 /harness-init 渲染 .tmpl 模板时 |

快速开始

环境要求

• Node >= 18（脚手架本身）
• Python >= 3.8（初始化出的 harness 工程脚本运行时需要；脚手架会自动检测并引导安装）
• Claude Code（运行 harness 多 Agent 流程的宿主：/harness-* 斜杠命令、角色 Agent 与门禁钩子均运行在 Claude Code 中）

安装

安装前准备：

1. 准备好子工程 git 地址：后端 / 前端 / APP 端（APP 端可选，留空即不接入；至少一端必填）
2. 进入你希望生成 harness 工程的目录，再执行下面的安装命令

# 直接运行（无需本地安装，从公共 npm 拉取）
npx @laoliang/auto-harness

# 指定工程名/目录名
npx @laoliang/auto-harness my-project

工程生成在当前运行目录的子目录下：带参数时以参数为工程名（如 my-project → ./my-project/），不带参数时交互询问工程名后同样创建在 ./<工程名>/。当前目录下同名目录已存在且非空时，会询问「继续使用（不覆盖已有文件）/ 退出」。

harness 采用外包式接入：它不会把现有代码工程原地改造成 harness 工程，而是新建一个标准的 harness 工程，再把你提供 git 地址的源仓库作为 services/ 子工程以 submodule 形式引入。原有代码仓库本身不被改动，只在 harness 工程内接入管理。

交互流程：

1. 输入工程名/目录名（或作为位置参数传入）
2. 输入后端 / 前端 / APP 端 git 地址（APP 端可留空；至少一端必填）
3. 输入子工程主线分支（集成/归档合并目标，默认 dev，写入 .harness/config.json）
4. 检测 OS + Python 环境，缺失时引导安装（自动/手动/跳过）
5. 复制通用骨架 → 写入 .gitmodules → git submodule add → 生成工程 README
6. cd <目录> 后在 Claude Code 里执行 /harness-init 生成项目专属文件

升级-刷新安装工程（update）

脚手架版本升级后，已生成工程的框架层（.harness/scripts、.claude 等）需要刷新；工程后续想补接新的端（例如先只有前后端，后来要加 APP 端），也走同一条命令：

# 公共 npm 包（0.1.7+）
npx @laoliang/auto-harness update <工程目录>

# 不传目录 = 当前目录
cd <工程目录> && npx @laoliang/auto-harness update

端接入（固定三端：后端 / 前端 / APP 端）

• 已接入的端自动跳过，不提问。端是否已接入按 services/ 下目录的结构判定，不看目录名：pom.xml 或 .sln/.csproj → 后端；package.json + apps/ → 前端（微前端多 App）；package.json 无 apps/ → APP 端（单应用 SPA）
• 缺失的端才提示「<端>仓库 git 地址（留空表示暂不接入）」：
  • 填地址 → 问目录名（默认 backend/frontend/app）→ git submodule add，并把该端补进 .harness/codebase-guide/index.md 的「子工程文件清单」表与根 README.md 的端列表
  • 留空 → 完全跳过：不写 .gitmodules、不建目录、表格不出行
• 新接入的端还没有子工程文档（CLAUDE.md / docs/CODE_STANDARDS.md / .harness/build.json），需再在 Claude Code 里跑一次 /harness-init 生成（幂等，已接入的端会跳过）

框架层刷新

• 只刷框架层（脚本/钩子/规则/模板），保留项目状态：tasks/（看板）、deliverables/（活任务）、memory/、specs/（除 spec-template.md）、codebase-guide/、config.json、.claude/settings.local.json、services/
• 占位符自动实例化为工程实际目录名（services/backend 等）
• 被覆盖文件先备份到 .harness/.logs/update-backup-<时间戳>/，可回滚
• 根 README.md 仅在本次真的接入了新端时才重写（纯刷新不动它，避免覆盖你的手改）
• 全程无安装副作用，也不会改动任何子工程源码

脚本化（三端都留空 = 只刷框架层，不接入任何端）：

printf '\n\n\n' | npx @laoliang/auto-harness update <工程目录>

完成后建议跑 python3 .harness/scripts/harness.py check-harness --preflight 验证。

Harness 用法与设计

初始化完成后，所有任务从「向 AI 说一句话需求」开始，其余由 harness 的流程与角色接管。

核心流程

Bootstrap 阶段                           PM 调度阶段
──────────────                           ──────────
.harness/scripts/init_task.py            读取 .claude/agents/project-manager.md
    ↓                                    ↓
人机协作打磨 proposal.md                 切换 PM 身份
（消歧义、定 scope、选 profile）          ↓
    ↓                                    /harness-propose
人工确认 proposal 定稿                   BA → SA → RR → 审批 1
    ↓                                    ↓
交接 PM                                  /harness-apply
                                         Dev → CR → TE → 审批 2
                                         ↓
                                         /harness-archive → DONE

角色

| 角色 | 职责 | |------|------| | PM（project-manager） | 唯一调度者：拆解任务、分派 Worker、裁决阶段流转 | | BA（business-analyst） | 需求分析：产出 requirements（含可验证场景） | | SA（solution-architect） | 方案设计：impact-analysis + design | | RR（readiness-reviewer） | 就绪评审：确认 proposal 具备进入开发的条件 | | Dev（developer） | 实现：按 design 开发、自测、本地提交 | | CR（code-reviewer） | 代码审查：对照 requirements/design 审查 diff | | TE（test-engineer） | 测试：build-test + verify 验收 |

命令

| 命令 | 用途 | |------|------| | /harness-init | 首次初始化：生成项目专属文件（codebase-guide / specs / 看板 / memory） | | /harness-bootstrap <任务> <需求> | 新任务入口：打磨 proposal、消歧义、定 profile | | /harness-propose <任务> | 切 PM：BA → SA → RR → 审批 1 提案流水线 | | /harness-apply <任务> | 切 PM：Dev → CR → TE → 审批 2 实现流水线 | | /harness-archive | 归档：spec merge、memory merge、轮次收档、子模块合入 | | /harness-fix <任务> <描述> | 轻量直通：修非 harness 开发的简单 bug（跳过 propose 审批） |

设计要点

• 制品边界：下游角色不修改上游制品，发现上游问题只能提阻塞项，由 PM 正式打回
• PM 澄清义务：范围/口径/验收模糊时 PM 必须反问人，禁止 AI 自行「合理补全」
• 文档即流转：每个阶段必须产出对应文档且带明确结论（PASS / BLOCK / REJECT）后才能流转
• 轮次契约：reopen 新轮次以 ## R<N> 增量归档；契约反转须显式声明 superseded，spec 只落最终态
• 双系统兼容：框架层全 Python 无 .sh，macOS / Windows 行为一致
• 门禁：pre-commit 拦截集成分支直接提交交付物/子模块指针；check_harness 校验工程完整性；spec-lint 校验规格编码