Nexus Harness

Agent = Model + Harness — 给 Claude Code / Cursor 装上稳定、可验证、可恢复的 Go 后端研发执行环境。 A Harness Engineering toolkit for Go-backend teams that turns one-off AI conversations into a repeatable, verifiable, resumable engineering workflow.

开源地址 · Repository: https://github.com/xurb-nexus/nexus-harness

模型决定「能不能生成」，Harness 决定「能不能交付」。Nexus Harness 不替代任何 AI 编码工具，而是在它们外面包一层研发 Harness：把 PRD → TRD → Plan → TDD 开发 → Review → 归档 → 问题定位 → AIWeave docs 同步 串成一条状态可恢复、质量有证据的工程流水线。纯 skill 化、克隆即用、不依赖任何 MCP。

定位：当前面向 Go 后端研发（AIWeave docs 契约是核心能力，非 Go 项目自动降级跳过）。宿主主推 Claude Code / Cursor；Codex / Gemini 为实验性，兑现度见 宿主支持现状。

为什么需要它

七大特色能力

这些是 Nexus Harness 与「让 AI 直接写代码」的根本区别——不只追求生成速度，更追求过程可控、质量可查、状态可恢复。

1. 双 Agent 独立评审 — 生成与评审分离，reviewer 子 Agent 不继承主会话上下文，杜绝「自己说服自己、自己给自己放行」。
2. TDD 红绿灯驱动 — RED → GREEN → REFACTOR，先定义可验证行为再实现；硬 gate 拦截 mock 假绿灯与「删码跑红」式作弊。
3. 跨会话状态续跑 — 不依赖对话记忆，从 workspace/ context.json TRD Plan STATUS.md 恢复现场继续推进。
4. AIWeave docs 双向契约 — Go 项目写代码前读 docs/，写完反向 sync-feature-to-docs 回写，归档时 doc-sync-check 校验漂移。
5. 工作流钩子 + 会话隔离 — stop hook 把擅自停下的 Agent 自动拉回循环；per-conversation 隔离让多个窗口并行各跑各的项目，互不干扰。
6. 数据围栏 — 测试默认只读真实库，写操作只能碰本轮自建数据；缺配置即停，绝不静默降级。
7. ContextPack 三层诊断 — L1 实况 eager-load → L2 TRD 索引 → L3 docs/INDEX.md，已知坑优先命中，排障只读、根因确认后可 Hotfix。

设计理念详见 Harness Engineering。

宿主支持现状

Nexus Harness 是「宿主无关协议 + 各端适配」。开源前如实标注各端兑现度，避免「clone 即用」落空：

Roadmap：补齐 Claude Code 的 .claude/agents/* 注册文件与 hooks，让「双 Agent 独立评审 / stop hook 拉回循环」在 Claude Code 端也 clone 即用。

六个入口

进入业务仓库运行 nexus，回复编号或直接描述目标即可；任意时刻单独输入 nexus 回到入口菜单。

AIWeave 集成

vendor 了 AIWeave，作为 Go 项目「代码 ↔ docs 双向契约」的规范源（非 Go 项目自动跳过）。

• 规范量：28 篇 docs-spec + 18 个 .claude/skills/ 操作手册（new-model / sync-feature-to-docs / doc-sync-check / io-review 等）。
• 三档成熟度：T0 冷启动建骨架 → T1 补缺口 → T2 检查并按需同步。
• 正向 / 反向：写前读 docs/ + BUILD_STATUS.md 按契约实现；写后 sync-feature-to-docs 回写、doc-sync-check 校验。
• 归属与边界：产物写入业务仓库随代码提交；skills/aiweave-bridge/vendor/aiweave/** 为只读上游镜像。

快速开始

前提：已安装 Claude Code（claude 命令可用，见 claude.ai/code）；终端可执行 python3。

# 1. 安装一次（幂等：建目录、加 nexus 软链、提示 PATH）
git clone https://github.com/xurb-nexus/nexus-harness.git
cd nexus-harness && bash install.sh   # 完成后开一个新终端

# 2. 在业务仓库启动
cd /path/to/your-project
nexus                                  # 出现 1–6 菜单；Cursor 用户在 Agent 聊天框输入 nexus

命令速查与路径模型

nexus                  # auto-init + 启动 Claude Code
nexus init             # 在当前项目写/更新适配文件
nexus doctor           # 检查本机安装与环境
nexus cheatsheet       # CLI 速查
nexus uninstall        # 卸载（--dry-run 预览）

文档

open site/public/index.html     # 本地静态文档站（file://，零运行时）

也可在业务项目运行 nexus 后选择 6. 查看使用说明。

参与共建

欢迎通过 issue / PR 参与共建。

许可证

本项目以 Apache License 2.0 开源。