harness-lab: Command for Claude Code

/harness-setup

目标

将 harness-lab 治理框架接入到当前 Git 项目，并让安装结果与当前仓库的真实治理契约一致。

前置检查

1. Git 仓库检测

   • 当前目录必须包含 .git/
   • 如果不是 Git 仓库，先提示用户运行 git init

2. 现有治理文件检测

   • 检查是否存在：AGENTS.md, CLAUDE.md, requirements/, .claude/progress.txt
   • 如果存在，记录冲突文件列表
   • 当前安装器的真实策略是默认跳过已有文件，避免覆盖目标项目内容

推荐执行方式

在目标项目中运行：

node /path/to/harness-lab/scripts/harness-install.mjs --defaults

如果目标项目的 package.json 在子目录（例如 app/package.json），仍在 Git 根目录运行安装器，并显式指定脚本绑定位置：

node /path/to/harness-lab/scripts/harness-install.mjs --defaults --package-dir app

包含治理 hooks：

node /path/to/harness-lab/scripts/harness-install.mjs --defaults --with-hook

如果 harness-lab 以 npm 包形式安装，package.json 暴露 harness-install bin 后，也可以使用：

npx --yes --package=harness-lab harness-install --defaults
npx --yes --package=harness-lab harness-install --defaults --dry-run
npx --yes --package=harness-lab harness-install --defaults --package-dir app
npx --yes --package=harness-lab harness-install --defaults --with-hook

模块

核心模块（必须安装）：

• AGENTS.md - 治理规则主入口
• CLAUDE.md - 会话入口协议
• requirements/ - REQ 生命周期管理
• .claude/progress.txt - 跨会话进度交接

默认模块：

模块	说明	默认
docs/	设计稿和规范目录	yes
context/	业务/技术/经验索引	yes
skills/ 与 .agents/skills/source-command-*	阶段导航技能、Claude Code source-command skills（含 worktree-req）	yes
CLI 脚本	REQ lifecycle/status/experience、reflect/align、audit/health、docs gate、doctor、invariant 与其运行依赖	yes
治理 hooks	.claude/settings.example.json, scripts/session-start.js, scripts/req-check.js, scripts/scope-guard.mjs, 本地 hook 配置	no，需 --with-hook

安装器真实行为

1. 源目录

   • 默认使用安装脚本所在仓库作为源目录
   • 可通过 --source /path/to/harness-lab 显式指定

2. 冲突处理

   • 检测已存在文件
   • 默认跳过已存在文件
   • 当前不实现覆盖/取消的交互式分支

3. 初始化配置

   • 创建或补齐 requirements/ 目录结构
   • 默认保留目标项目已有 REQ、报告和经验历史；仅在 --clean-template-history 下清理带模板标记的历史文件
   • 仅在不存在时初始化 .claude/progress.txt；重装逐字节保留现有进度
   • 合并合法的 .claude/settings.local.json，非法 JSON 原样保留并终止安装
   • 生成 requirements/reports/harness-setup-report.md