# coding-harness

**Repository Path**: cxman/coding-harness

## Basic Information

- **Project Name**: coding-harness
- **Description**: 四版通用 AI 编程工程化 Harness：Claude Code / Cursor / ChatGPT Codex / WorkBuddy。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# coding-harness

> 一套把 **AI 编码流程工程化** 的方法论，落地成四个主流 AI 编码工具的原生形态。

**核心思想只有一句话：模型负责聪明，harness 负责让它守纪律。**

AI 编码最大的痛不是"写不出代码"，而是：改到一半忘了上下文、跳过测试直接推、危险操作无人拦截、质量无法量化。Harness 用四根支柱解决：

1. **上下文当预算（Context as Budget）**——入口文件极小（≤8K），其余规则/角色/上下文/技能全部"按需加载"，不进常驻上下文。
2. **dispatcher 状态机 + 文件交接**——主会话退化为纯执行器，流程进度写进 `state.json` + `phases/*`，跨天可续跑、可审计。
3. **确定性门禁（G1–G8）外置到基础设施**——门禁用 Python 真跑构建/测试/接口校验，FAIL 即阻断（fail-closed），不信任模型自报"我改好了"。
4. **评测平台自进化闭环**——7 维确定性评分（零 LLM、可复现），每个 case 产出 `evidence.json`，复盘后回流到 rules/。

---

## 四版横向对比

| 维度 | Claude Code | Cursor | ChatGPT Codex (OpenAI) | WorkBuddy |
|------|-------------|--------|------------------------|-----------|
| 目录 | `claude/` | `cursor/` | `codex/` | `workbuddy/` |
| 入口指令文件 | `CLAUDE.md` | `.cursorrules` | 仓库根 `AGENTS.md` | `SKILL.md`（frontmatter 触发） |
| 原子规则 | `rules/*.md` | `.cursor/rules/*.mdc` | `rules/*.md` | `references/rules/*.md` |
| 角色 Agent | `agents/*.md` | `.cursor/agents/*.md` | `agents/*.md` | `references/agents/*.md` |
| 命令 | `/cmd`（`commands/*.md`） | `/cmd`（`.cursor/commands/*.md`） | `codex exec`（流水线） | Skill 加载即生效 |
| 配置 | `settings.json`（PreToolUse/PostToolUse hook） | 无 hook | `.codex/config.toml` + `.codex/requirements.toml` | WorkBuddy 权限模式 + `assets/` |
| 硬围栏机制 | hook 实时拦截 | `06-safety.mdc`(alwaysApply) + CI 跑 gates.py | `sandbox_mode`+`approval_policy` + CI 跑 gates.py | Craft/Plan/Ask 权限模式 + CI 跑 gates.py |
| 状态持久化 | `state.json` | `state.json` | `state.json` | `state.json` + `.workbuddy/memory/` 双写 |
| 适用 surface | Claude Code CLI | Cursor IDE | Codex CLI / ChatGPT Cloud | WorkBuddy 平台 |

四版**方法论完全一致**，差异只在"如何贴合各工具的加载约定与硬围栏机制"。挑一个你主力用的工具即可，不需要四个都装。

---

## 目录结构

```
coding-harness/
├── README.md          # 本文件（四版汇总对比）
├── .gitignore
├── claude/            # Claude Code 版（CLAUDE.md 约定）
├── cursor/            # Cursor 版（.cursorrules + .cursor/rules）
├── codex/             # ChatGPT Codex 版（AGENTS.md + .codex/）
└── workbuddy/         # WorkBuddy Skill 版（SKILL.md）
```

每个子目录内部都是同一套分层：

```
<version>/
├── README.md              # 该版本详细流程文档
├── <入口文件>             # CLAUDE.md / .cursorrules / AGENTS.md / SKILL.md
├── rules/                 # 7 条原子规则（踩坑墓志铭）
├── agents/                # 11 个角色 Agent
├── context/               # 按需上下文（含 tech-stack.md 模板）
├── skills/                # 能力封装
├── commands/              # 斜杠命令 / 流水线入口
├── state.json             # 外部化流程状态（控制平面）
├── workflow.yaml          # 19 节点链 + intent×risk 裁剪表
└── evals/                 # gates.py(G1-G8) + scoring.py(7维评分)
```

---

## 通用使用方式（四版都一样）

四版都不绑定任何技术栈。**唯一需要你填的地方**是各版本里的 `tech-stack.md`（Claude/Cursor/Codex 在 `context/`，WorkBuddy 在 `references/context/`）：把本仓库的语言、构建命令、分层约定、部署方式填进去即可，其余方法论开箱即用。

评测统一接口（四版相同）：

```bash
python evals/gates.py      # G1–G8 确定性门禁，FAIL 即非零退出（可接 CI）
python evals/scoring.py    # 7 维确定性评分，输出 json + 可复现 hash
```

门禁在无产物时会 **全部 FAIL 且退出码 1**（fail-closed 已验证）；评分在空 case 下返回 `F/0.0` 且多次运行 hash 一致（确定性已验证）。

### 各版本接入一句话

- **Claude Code**：`cp -r claude/. 你的项目/.claude/` → 说 `/init-harness` 接入
- **Cursor**：`cp -r cursor/.cursor 你的项目/` → Cursor 自动识别；把 `evals/gates.py` 接进 CI
- **ChatGPT Codex**：`cp -r codex/. 你的项目/`（复制 `AGENTS.md` + `.codex/`）→ `codex "按 harness 实现 xxx"`；CI 接 `gates.py`
- **WorkBuddy**：把 `workbuddy/` 作为 Skill 目录（项目级 `.workbuddy/skills/coding-harness/` 或用户级 `~/.workbuddy/skills/`）；加载后说"按 harness 流程实现 xxx"即触发

---

## 流程速览（19 节点链 × G1–G8 × intent×risk 动态裁剪）

不是每个需求都走全 19 步——按 `intent×risk` 动态裁剪：

- `QUERY/NA`：不启动流程，直接回答
- `BUG_FIX/LOW`：走 FAST_PATH（定位→修→G2+G3 门禁）
- `FEATURE/MEDIUM`：常规路径 + G1–G6 门禁
- `FEATURE/HIGH`：拉满 + ADR + G1–G8 全门禁 + 架构评审

`workflow.yaml` 里含完整 19 节点定义、G1–G8 门禁阈值、intent×risk 裁剪矩阵。

门禁语义（G1–G8，确定性，fail-closed）：

- **G1** 需求与计划文件齐备（phases/ 存在且非空）
- **G2** 真跑构建通过（`mvn`/`gradle`/`npm` 自动探测，取真实退出码）
- **G3** 真跑单测通过
- **G4** 无 TODO/FIXME/占位实现
- **G5** ATDD / 接口测试通过（无则不罚）
- **G6** 危险操作经确认且无 `rm -rf`/强制推送/密钥提交
- **G7** evidence.json 齐全（每个门禁产物可核验）
- **G8** 验收用例通过 / 输出对齐需求

---

## 选型建议

| 你的主力环境 | 推荐 |
|--------------|------|
| 终端里用 Claude Code CLI | `claude/` |
| 在 Cursor IDE 里写代码 | `cursor/` |
| 用 OpenAI Codex / ChatGPT Cloud | `codex/` |
| 在 WorkBuddy 平台做开发 | `workbuddy/` |

四版可并存于同一个仓库的不同目录（分别放 `.claude/`、`.cursor/`、根 `AGENTS.md`、`.workbuddy/skills/`），互不冲突——方便团队里不同人用不同工具但共享同一套方法论。

---

## 许可

方法论来自公开文章实践总结，本仓库按 MIT 许可开放，可自由用于你的项目。