# 全局安装（推荐：装一次到处用、IDE 接入零超时）
npm install -g harness-engineering-mcp

# 或在项目里直接调用，不全局安装（≥ 0.2.1 起 npx 包名直调也能用）
npx -y harness-engineering-mcp@latest init                  # CLI 简写
npx -y -p harness-engineering-mcp@latest harness init       # CLI 标准写法
npx -y -p harness-engineering-mcp@latest harness-mcp        # 起 MCP server

mkdir hello-harness && cd hello-harness
git init
npm init -y
npm pkg set scripts.test='node -e "process.exit(0)"'
mkdir test && echo "// placeholder" > test/sanity.test.js
echo "node_modules/" > .gitignore
echo ".env" >> .gitignore
echo "dist/" >> .gitignore

harness init --mode=solo --stack=node-typescript --type=library --name=hello-harness

harness_init: completed
- created .harness/config.json (1234 bytes)
- created .harness/baseline.json (412 bytes)
- created .harness/scripts/engineering-check.ps1 (123 bytes)
- created .harness/scripts/engineering-check.sh (98 bytes)
- created .harness/engineering-harness.md (567 bytes)
- created .harness/adr/0001-engineering-harness-baseline.md (...)
- created .harness/features/INDEX.md (...)
- created .harness/features/_template/01_REQUIREMENT_ANALYSIS.md (...)
  ... 7 个阶段模板 ...
- created .github/pull_request_template.md (...)
Next steps:
- 运行 harness_check 跑首次门禁
- 查看 .harness/engineering-harness.md 熟悉项目 SSOT
- 如团队规模发生变化可运行 harness_upgrade_mode 升档

hello-harness/
├── .harness/
│   ├── config.json
│   ├── baseline.json
│   ├── engineering-harness.md         ← 项目 SSOT
│   ├── adr/0001-engineering-harness-baseline.md
│   ├── features/INDEX.md + _template/
│   └── scripts/engineering-check.{ps1,sh}
├── .github/pull_request_template.md
├── .gitignore
├── package.json
└── test/sanity.test.js

harness check

Harness Check: PASS
PASS 13 · WARN 1 · FAIL 0 · 178ms

  ✓ config.exists          .harness/config.json 存在
  ✓ config.valid           mode=solo stack=node-typescript
  ✓ structure.ssot         SSOT .harness/engineering-harness.md 存在
  ⚠ structure.adr          .harness/adr/ 下 1 条 ADR（baseline）
  ✓ structure.features     features 任务看板存在
  ✓ secrets.envfile        未在仓库中发现 .env 文件
  ✓ secrets.gitignore      .gitignore 包含关键排除项
  ✓ tests.directory        测试目录 test 存在
  ✓ tests.command          npm test 已配置
  ✓ baseline.exists        .harness/baseline.json 存在
  ✓ baseline.valid         baseline version=1.0
  ✓ docs.readme            README.md 存在
  ✓ quality.coverage       未设置覆盖率基线，跳过
  ✓ quality.pr_size        变更 0 行 / 0 文件，在限制内

harness route "用户列表加一个按状态筛选的下拉框"

[route] task = "用户列表加一个按状态筛选的下拉框"
skill: dev-flow-oneliner-fe
skill_uri: harness://skills/dev-flow-oneliner-fe
weight: 一句话需求
modifiers: [M2]
forced_upgrade: null
suggested_next_tools: [harness_load_skill, harness_check]
efficiency_hints:
  - 「列表 / 筛选」识别为 UI 范畴，可直接用 dev-flow-oneliner-fe 切片实现
  - 提交前必跑 harness check --strict
  - skill / spec 走 harness:// URI 引用，不要复制粘贴到 prompt 里
  - 短回复 + 表格优于散文

harness route "后端加张订单表"

skill: dev-flow-oneliner-be
modifiers: [M4]
forced_upgrade:
  to: dev-flow-doc-be
  reason: 涉及数据库 schema 变更，须走完整 PRD + 迁移脚本 + 回滚 SQL 流程

harness check --strict --run-tests
git add -A && git commit -m "chore: harness baseline"

Harness Check: PASS
PASS 14 · WARN 0 · FAIL 0 · 1240ms
  ✓ tests.exec             npm test 成功 (exit=0)

[main (root-commit) abc1234] chore: harness baseline
 N files changed, ... insertions(+)

{
  "status": "completed",            // ready | needs_input | completed | dry_run
  "detected": { "stack": "...", "project_type": "...", "evidence": [...] },
  "ask_user": [],                    // status=needs_input 时告诉 AI 还要问什么
  "generated_files": [
    { "path": ".harness/config.json", "action": "created", "bytes": 1024 }
  ],
  "next_steps": ["运行 harness check 校验首次门禁"]
}

harness init --mode=small-team --stack=java-spring --type=backend-service --name=order-api

{
  "category": "config",
  "check_id": "config.exists",
  "status": "PASS",            // PASS | WARN | FAIL
  "message": ".harness/config.json 存在",
  "suggestion": "...",         // 可选
  "file": "...", "line": 12    // 可选
}

config.exists · config.valid
structure.ssot · structure.adr · structure.features
secrets.envfile
tests.directory · tests.command · tests.exec (run_tests=true 时才出现)
baseline.exists · baseline.valid
docs.readme

{
  "skill": "dev-flow-oneliner-fe",
  "skill_uri": "harness://skills/dev-flow-oneliner-fe",
  "weight": "一句话需求",
  "deliverables": ["MINI_PRD", "IMPACT_ANALYSIS", "API_CONTRACT(if needed)"],
  "forced_upgrade": { "to": "dev-flow-doc-fe", "reason": "涉及数据库 schema 变更" },
  "modifiers": ["M2", "M4"],
  "suggested_next_tools": ["harness_load_skill", "harness_check"]
}

harness route "后端新增订单表和查询接口"
# skill: dev-flow-oneliner-be
# forced_upgrade: dev-flow-doc-be · 涉及数据库 schema 变更
# modifiers: [M4]

harness list skills           # 看所有技能
node dist/cli.js mcp           # 启动 MCP 由 IDE 调用 harness_load_skill

{
  "status": "generated" | "passed" | "blocked",
  "file_path": ".harness/features/search-v2/03_GATE_REVIEW.md",
  "blockers": ["缺少回滚 SQL", "鉴权策略缺失"]
}

# 生成
harness route "为 search-v2 做闸门评审" 
# 然后 AI 调用 harness_gate_review action=generate feature_name=search-v2

# 检查
harness_gate_review cwd=$(pwd) feature_name=search-v2 action=check

{
  "status": "completed" | "dry_run" | "not_found",
  "removed": [".harness/config.json", ".harness/features/INDEX.md", ...],
  "kept": ["CHANGELOG.md", ".github/CODEOWNERS"],
  "next_steps": ["..."]
}

harness upgrade --to=mid-team
# from=solo to=mid-team
# 生成 5 个新文件，跳过 1 个已存在

harness uninstall --dry-run             # 先看要删什么
harness uninstall                       # 交互确认后删除
harness uninstall -y                    # 一键删除，不确认（脚本里用）
harness uninstall --keep-root-dir -y    # 清空内容、保留 .harness/ 占位

{
  "version": "0.1",
  "project": {
    "name": "my-project",
    "type": "backend-service",
    "stack": "java-spring",
    "mode": "solo"
  },
  "modules": {
    "people":   { "branch_strategy": "trunk", "pr_max_lines": 600 },
    "process":  { "gate_review_enabled": true },
    "quality":  { "coverage_baseline": 0.6 },
    "release":  { "semver": true, "changelog": true },
    "security": { "secret_scan": true },
    "knowledge":{ "feature_board": true }
  }
}

# 先在终端查出你当前 node / npx 的绝对路径
which node
which npx
# 例如可能输出：/Users/你/.nvm/versions/node/v22.13.0/bin/npx

{
  "mcpServers": {
    "harness-engineering": {
      "command": "/Users/你/.nvm/versions/node/v22.13.0/bin/npx",
      "args": ["-y", "-p", "harness-engineering-mcp@latest", "harness-mcp"]
    }
  }
}

sudo ln -sf $(which node) /usr/local/bin/node
sudo ln -sf $(which npx)  /usr/local/bin/npx

# 如果你不重度使用 nvm 切版本，可以直接卸了换 Homebrew
brew install node
# 然后从 .zshrc / .bashrc 删除 nvm 的 export 行
# 最后重启终端 + 重启 Cursor

# 模拟 GUI 应用的 launchd 启动环境，看 npx 在不在 PATH
launchctl getenv PATH | tr ':' '\n' | grep -E "(nvm|node|local/bin|homebrew)"
# 然后试试 launchd 能不能直接执行 npx：
osascript -e 'do shell script "which npx"'

// ~/.cursor/mcp.json
// 推荐：不依赖全局安装，npx 自动从 npm 拉取
{
  "mcpServers": {
    "harness-engineering": {
      "command": "npx",
      "args": ["-y", "-p", "harness-engineering-mcp@latest", "harness-mcp"]
    }
  }
}

{
  "mcpServers": {
    "harness-engineering": { "command": "harness-mcp" }
  }
}

// ~/.config/claude-code/mcp.json
{
  "mcpServers": {
    "harness-engineering": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "harness-engineering-mcp@latest", "harness-mcp"]
    }
  }
}

# ~/.codex/config.toml
[[mcp_servers]]
name = "harness-engineering"
command = "npx"
args = ["-y", "-p", "harness-engineering-mcp@latest", "harness-mcp"]

cd legacy-api
harness init                   # 走交互；扫描器会建议合理的 mode/stack
harness check                  # 看首次门禁结果
harness check --run-tests      # 加上真实测试看是否绿

1. harness_route_task task="..." → 拿到 skill + modifiers + forced_upgrade
2. harness_load_skill name=<skill> → 读 SKILL.md
3. 按 SKILL.md 流程产出 .harness/features/<name>/01_..06_*.md
4. harness_gate_review action=check feature_name=<name> → 出 blocker
5. harness_check --run-tests → 最终绿灯后再提交

# solo → small-team
harness upgrade --to=small-team

# small-team → mid-team
harness upgrade --to=mid-team

# .github/workflows/harness.yml
- name: Harness Engineering check
  run: |
    npx -y -p harness-engineering-mcp@latest harness check --strict --run-tests --json > harness-report.json
- name: Upload report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: harness-report
    path: harness-report.json

{
  "skill": "dev-flow-oneliner-be",
  "modifiers": ["M4"],
  "forced_upgrade": { "to": "dev-flow-doc-be", "reason": "涉及数据库 schema 变更" },
  "efficiency_hints": [
    "spec/rule 走 harness:// URI 引用，不要复制粘贴到 prompt 里（保持 prompt cache 命中）",
    "DB schema 变更：先出迁移脚本 + 回滚 SQL，再写代码，禁止跳过 ADR",
    "强制升级到 dev-flow-doc-be：保留完整 PRD + 阶段文档，禁止偷工省略",
    "回复 < 2000 字符，表格优于散文，独立工具调用一次性批发"
  ]
}

harness://spec/file/AI_EFFICIENCY.md
harness://skills/ai-efficiency
harness://rules/16-ai-efficiency.mdc

git clone https://github.com/movebrickschi/harness-engineering-mcp.git
cd harness-engineering-mcp
npm install
npm run typecheck && npm run lint && npm test && npm run build

src/
  cli/        CLI 命令（init/check/route/upgrade/list/mcp）
  core/       业务核心（scanner / renderer / checker / router / config）
  mcp/        MCP server + tools/ + resources/
  types/      共享 TS 类型
assets/
  spec/       Engineering Harness Spec（含 schema）
  skills/     内置 skills（dev-flow 全套 + 通用 18 个）
  rules/      .cursor/rules 模板
  templates/  init / features / pr / adr 模板
  stack-adapters/  Java Spring · Node TS · Python 适配指南
test/         12 个测试文件，57 用例
docs/         PROPOSAL / M2-M4 各阶段联调文档

npm run typecheck && npm run lint && npm test && npm run build
npm pack --dry-run                     # 检查包内容
npm publish --access public            # 需先 npm login
git tag v0.1.0 && git push origin v0.1.0