# harness

**Repository Path**: liudechang/harness

## Basic Information

- **Project Name**: harness
- **Description**: AI 驱动的开发工作流引擎 — Claude Code 编排层
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harness Engine

> AI 驱动的开发工作流引擎 — Claude Code 编排层
>
> 自动化 **需求 → 设计 → 实现 → 测试 → 部署** 全流程，支持断点恢复，可配置人工审批关卡，持续运行数小时无中断。

## 快速开始

```bash
# 在你现有的项目根目录执行（npm 发布后可用）
npx harness-engine init

# 发布前直接从 Gitee 运行
npx git+https://gitee.com/liudechang/harness.git init
```

自动完成：检测项目配置 → 安装 Skill + Workflow → 配置免审批权限。然后：

```text
# 先构建项目知识库（LLM agent 深度理解项目架构）
/harness map

# 再启动开发
/harness start <feature>
```

```text
# 仅功能名（使用 harness.yaml 中的 prompt）
/harness start my-feature

# 功能名 + 内联需求描述（推荐，描述优先于 prompt）
/harness start user-login 实现用户名密码登录，支持记住密码，失败3次锁定

# 查看进度
/harness status

# 审批通过 / 驳回修改
/harness approve design
/harness reject design 模块划分不合理，请重新调整
```

---

## 安装方式

### npm（推荐）

```bash
# npm 发布后可用：
npx harness-engine init          # 当前目录

# 发布前直接用 git URL：
npx git+https://gitee.com/liudechang/harness.git init

# 或全局安装：
npm install -g git+https://gitee.com/liudechang/harness.git
harness-engine init /path        # 指定目录
```

`init` 自动完成：
1. 检测项目配置（语言/框架/测试/部署目标）
2. 安装 `.claude/skills/harness/SKILL.md`（Skill 入口）
3. 安装 `.claude/workflows/harness-pipeline.js`（Workflow 脚本）
4. 生成 `.harness/harness.yaml`（项目配置）
5. 配置 `.claude/settings.local.json`（免审批权限 — 避免 `npx vitest` 等命令弹窗中断）

### Git Submodule

```bash
git submodule add git@gitee.com:liudechang/harness.git .harness-engine
node .harness-engine/bin/init.js
```

### 手动复制

将 `.claude/skills/harness/SKILL.md` 和 `.claude/workflows/harness-pipeline.js` 复制到项目对应目录。

---

## 指令参考

| 指令 | 功能 | 示例 |
|------|------|------|
| `/harness start <f> [desc]` | 新功能全流程开发 | `/harness start payment 集成微信支付` |
| `/harness fix <f> <bug>` | Bug 修复（跳过需求设计，直接定位修复） | `/harness fix login 密码错误返回200` |
| `/harness iterate <f> [desc]` | 增量迭代（MVP→v2→v3） | `/harness iterate payment 增加退款` |
| `/harness resume <f>` | 跨会话断点恢复 | `/harness resume payment` |
| `/harness map` | LLM agent 深度学习项目，生成架构地图 | `/harness map` |
| `/harness status [f]` | 查看进度 | `/harness status` |
| `/harness approve <stage> [f]` | 通过 Quality Gate（多feature时须指定） | `/harness approve design login` |
| `/harness reject <stage> <原因> [f]` | 驳回修改（最多3次） | `/harness reject design 架构不合理 login` |
| `/harness abort <f>` | 终止并归档 | `/harness abort payment` |

---

## Workflow Pipeline

```
/harness start "实现用户登录"
    │
    ▼
Stage 1: requirements    需求分析 → spec.md
    │  ⏸ 等待审批
    ▼
Stage 2: design          方案设计 → design.md + tasks.md（模块列表）
    │  ⏸ 等待审批
    ▼
Stage 3: develop  TDD 编码 → impl-summary.md（并行 agent，模块级恢复）
    │  ⏸ 等待审批
    ▼
Stage 4: review          Agent 自查 → review.md（正确性/安全/可维护/测试/风格）
    │  ⏸ 审查（未通过→自动回退 develop）
    ▼
Stage 5: testing         并行测试 + 修复循环 → test-report.md + test-case.md
    │  ⚡ auto_approve（可配置，失败→自动回退 develop）
    ▼
Stage 6: deployment      部署发布 → deploy-result.md
       ⏸ 强制人工确认
```

---

## 配置

`npx harness-engine init` 自动生成 `.harness/harness.yaml`，根据检测结果配置：

```yaml
meta:
  name: my-app
  language: typescript       # 自动检测
  framework: next.js         # 自动检测

stages:
  requirements:
    auto_approve: false      # true=自动流转, false=等待人工审批
    artifact: {feature}/spec.md
    prompt: |                # 后备方案：/harness start 无描述时使用
      需求分析的 prompt...

  design:
    auto_approve: false
    artifact: {feature}/design.md

  develop:
    auto_approve: false
    strategy: tdd            # tdd | direct | incremental
    max_parallel: 5          # 最大并行模块数

  review:
    auto_approve: false      # agent 自查，未通过→自动回退 develop

  testing:
    auto_approve: true       # 存量项目建议 true，逐步改为 false
    coverage_threshold: 80
    adversarial_verify: false

  deployment:
    auto_approve: false      # 部署永远人工确认
    target: vercel           # 自动检测：vercel | docker | manual
    pre_deploy_check: "npm run build && npm run test"
```

---

## Artifacts 产物

每个 feature 独立目录，7 个产物文件覆盖全流程：

```
.harness/artifacts/{feature}/
  spec.md              ← 需求规格 (requirements)
  design.md            ← 技术方案 (design)
  tasks.md             ← 模块列表+任务 (design)
  impl-summary.md      ← 实现摘要 (develop)
  review.md            ← 审查报告 (review)
  test-report.md       ← 测试结果 (testing)
  test-case.md         ← 测试用例 (testing)
  deploy-result.md     ← 部署结果 (deployment)
```

---

## 免审批权限

`init` 自动配置 `.claude/settings.local.json`，使 Workflow agent 执行开发命令时无需人工审批，确保长时间持续运行不中断：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Bash(git *)",
      "Bash(mkdir *)",
      "Bash(rm *)"
    ]
  }
}
```

---

## 架构

```
Skill 入口层 (.claude/skills/harness/SKILL.md)
  → 解析配置、路由指令、Quality Gate 交互、Checkpoint 管理
  ↓
Workflow 执行引擎层 (.claude/workflows/harness-pipeline.js)
  → 5 阶段 Pipeline、pipeline() 顺序流转、parallel() 并行分发
  ↓
Memory 持久化层 (.harness/)
  → checkpoints/ = 状态机  artifacts/ = 产物  memory/ = 决策记录
```

---

## 存量项目使用建议

1. **先从简单 feature 开始** — `/harness start add-health-check` 跑通全流程
2. **testing.auto_approve 先设为 true** — 等测试覆盖完善后再关闭
3. **prompt 中写入项目约束** — 框架、目录结构、编码规范
4. **渐进提升自动化** — 第一周人工审批每个阶段，信任建立后逐步开启 auto_approve

---

## 许可证

MIT