# opencode-harness

**Repository Path**: cuigray/opencode-harness

## Basic Information

- **Project Name**: opencode-harness
- **Description**: OpenCode 适配的 Harness Engineering 项目模板
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode Harness Engineering 模板

把 AI Coding Agent 的"错误→修复→不再犯"闭环，固化到项目里的模板。

> 参考自 [新安《Harness Engineering：耗时一周，我是如何将应用的AI Coding率提升至90%的》](https://mp.weixin.qq.com/s/rlIyIIZOXFObNIXbPI7gDg)

---

## 这是什么（30 秒看懂）

三个 AI Agent + 一套流程 + 一些命令，帮你把开发需求从分析到部署走完，且每步留痕。

**三个 Agent 各司其职，你通过 Tab 键切换：**

| Agent | 什么时候切过去 | 它帮你做什么 |
|---|---|---|
| **Owner** | 拿到新需求时 | 理解需求 → 写 spec → 拆任务 → 维护变更记录 |
| **Coder** | 确定要写代码了 | 按分层规范编码 → 写单元测试 → 部署验证 |
| **Reviewer** | 需要查漏补缺时 | 评审方案 → 评审代码 → 评审测试，它改不了代码 |

**Pipeline 命令：** 在 OpenCode 里敲 `/` 就能看到可用命令，告诉 AI 当前该做什么。

---

## 首次使用（5 分钟）

### Step 1：复制到项目

```bash
cp -r ~/code/opencode-harness/{.,}* /path/to/your/project/
cp -r ~/code/opencode-harness/.opencode /path/to/your/project/
```

### Step 2：告诉 AI 你的项目是什么

改这几个文件，把占位符换成真实的：

| 改哪个 | 改什么 | 参考示例 |
|---|---|---|
| `AGENTS.md` 第 3 行 | `{项目名称}` 和技术栈 | `Python 3.12 / FastAPI / SQLAlchemy / Celery / Redis` |
| `.opencode/rules/` 下三个文件 | 工程结构、编码规范、开发流程 | 文件里的注释就是示例，照着改 |
| `wiki/` 下三个文件 | 你的业务链路、数据模型、业务流程 | 不急着填完，遇到需求时再补 |

### Step 3：启动，跑一个需求试试

```bash
# 在项目根目录启动 OpenCode
opencode

# 默认进入 Owner Agent。输入：
/analyze-request
```

AI 会问你这个需求是什么，然后产出 `spec.md` + `tasks.md`。按 Tab 切到 Reviewer 评审，再切到 Coder 编码……就这样一站一站走下去。

---

## 一个需求怎么跑完（实战场景）

假设你接了个需求："给订单列表加一个按日期筛选的功能"。

| 步骤 | 你做什么 | AI 做什么 | 产出物 |
|---|---|---|---|
| 1 | 切到 **Owner**，敲 `/analyze-request`，描述需求 | 分析需求 → 产出 spec + tasks | `spec.md`、`tasks.md` |
| 2 | 你读一遍 spec，确认没问题 | — | — |
| 3 | 按 Tab 切到 **Reviewer**，敲 `/review-plan` | 评审 spec + tasks，提意见 | `review_v1.md` |
| 4 | 如果评审通过，切到 **Coder**，敲 `/implement` | 按分层规范写代码 | 代码变更、`coding_report.md` |
| 5 | 切到 **Reviewer**，敲 `/review-code` | 代码审查 | `code_review_v1.md` |
| 6 | 如果有 MUST FIX，切回 Coder 修，重复 4-5 | — | — |
| 7 | 切到 **Coder**，敲 `/verify-deploy` | CI 验证 → 更新 summary | `ci_report.md`、更新后的 `summary.md` |
| 8 | 你最终确认交付 | — | — |

**回退规则：** 如果 CI 发现测试为 0 → 自动回退到写测试；编译错误 → 回退到改代码；需求理解错了 → 回退到重做分析。

**评审上限：** 需求评审最多 3 轮，代码/测试评审最多 2 轮，过了就找你拍板。

---

## 每阶段 AI 产出的文件在哪

```
.opencode/changes/{YYYYMMDD}-{类型}-{描述}/
├── summary.md                    ← 整个变更的"档案封面"，每步完成后自动更新
├── request_analysis/
│   ├── spec.md                   ← 需求规格（写什么）
│   ├── tasks.md                  ← 任务拆解（怎么拆）
│   └── review/review_v1.md       ← 需求评审意见（v1, v2...版本递增）
├── coding/
│   ├── coding_report_v1.md       ← 编码报告（改了哪些文件）
│   └── review/code_review_v1.md  ← 代码评审意见
├── unit_test/                    ← 单元测试代码 + 报告
├── ci_result/                    ← CI 构建结果
└── deployment/                   ← 部署确认
```

关键文件：**`summary.md`**。整个变更的唯一真相源，任何 Agent 接手时先读它，就知道干到哪了。

---

## 常见问题

### 和不用模板有啥区别？

不用模板 = 每次跟 AI 说一遍项目背景，每轮改完没有记录，改了什么全靠记忆。用模板 = AI 自己读 rules + wiki，每步有产出物，随时可回溯。

### 需要把所有 wiki 和 rules 填完才用吗？

不用。rules 给三个示例就行（工程结构、编码规范、开发流程），wiki 遇到需求时再补。模板的精髓是**渐进式填充**，有坑再补规则。

### 怎么切 Agent？

**Tab 键**。OpenCode 默认进入 Owner，按 Tab 循环切换 Owner → Coder → Reviewer。

### 3 个 Agent 有什么区别？

Owner 能做所有事（分析 + 驱动流程），Coder 聚焦编码，Reviewer **改不了文件**（write/edit 禁用），只管审查挑毛病。

### 模板文件结构一览

```
├── opencode.json                 # OpenCode 配置
├── AGENTS.md                     # 项目规则 + Wiki 加载指令
├── .opencode/
│   ├── agents/                   # 3 个 Agent 的定义（≈ 岗位说明书）
│   ├── rules/                    # 项目规范（待你填充）
│   ├── skills/                   # 4 个技能包（Agent 的工作 SOP）
│   ├── commands/                 # 7 个 pipeline 命令
│   └── changes/_template/        # 变更目录模板
└── wiki/                         # 业务知识库（待你填充）
```