Enterprise Harness

一个围绕 Claude Code 的企业后端交付骨架项目。

它的目标不是单纯证明“模型会写代码”，而是把一次需求从输入到落地，推进成一套更接近企业团队协作的工程过程：可探索、可落盘、可审查、可验证、可恢复、可跨机器接入。

当前状态：可运行的 repo contract + portable runtime MVP

它已经足够作为团队共享、跨会话可恢复、跨机器可接入的第一版骨架；但还不是完整企业级强门禁平台。

---

为什么会有这个项目

很多 AI coding workflow 停留在：

• 会话里说过的话，下轮就丢了
• 模型容易直接开写，跳过设计、TDD 和验证
• 项目规则写了很多，但没有真正接进运行时
• change、review、validation、evidence 分散在不同地方
• 换一台机器或换一个系统后，本地运行方式不一致

Enterprise Harness 想解决的不是“再写一套 prompt”，而是把 Claude Code 放进一套更像工程系统的结构里。

---

这个项目是什么

你可以把它理解成两层：

1. Repo Contract（仓库共享契约）

团队共享、提交进仓库：

• AGENTS.md
• CLAUDE.md
• .claude/rules/
• .claude/agents/
• .claude/skills/
• harness/specs/
• harness/templates/
• harness/changes/
• harness/config.yaml

这部分负责定义：

• 工作流
• 规则
• 资产结构
• reviewer 角色
• change 生命周期
• 文档与探索证据的落点

2. Portable Runtime（跨平台运行层）

每台机器本地适配：

• harness/plugin/runtime/cli.mjs
• bootstrap / doctor / sync / verify
• install / setup-local-adapter / upgrade / migrate
• local-adapter.schema.json
• local-adapter.example.json
• Node 版 hook adapters

这部分负责解决：

• OS / shell 差异
• 本地路径与命令
• 环境变量与 secrets
• 本机工具可用性
• 本地接入、自检、同步与迁移

---

一个请求进来后，会发生什么

这套 Harness 的重点不是“马上改代码”，而是先让流程站住。

当前主路径

1. 加载项目 contract
   • Claude Code 通过 .claude/settings.json 接入 SessionStart / PreToolUse / PostToolUse / Stop hooks
2. 主 agent 判断 request shape / tier
   • 先分流：是问答、文档、L0、L1、L2 还是更高风险变更
3. 先探索，再决定 route
   • 代码问题默认 codegraph-first
   • 外部库/框架问题默认 Context7-first
4. 必要时落 change 资产
   • 把 state.json、change.md、validation.md、evidence/tooling.md 放进 harness/changes/
5. 写入前过 gate
   • 对受治理路径（当前重点是 reference-service/）检查 active change、designApproved、redVerified
6. 写入后自动检查
   • 结构、轻语义、review/evidence 状态检查
   • 必要时把 validation 标为 stale
7. 完成前必须刷新验证证据
   • Stop gate 会阻止 stale validation 或缺失 validation 资产的“伪完成”状态

更详细的时序图见：

• docs/zh-cn/overview.md

---

当前已经真实可用的能力

代码探索与文档检索

• codegraph-first 已真实可用
• Context7 CLI wrapper 已真实可用
• 已有明确 fallback policy，而不是静默退回 grep / Read

change 生命周期与治理骨架

• harness/changes/ 资产模型已成形
• state.json / change.md / validation.md / evidence/tooling.md 已形成最小 change bundle
• active change 与受治理路径写入约束已接入 runtime gate

runtime CLI

当前统一入口：

node harness/plugin/runtime/cli.mjs <command>

当前已具备：

• bootstrap
• doctor
• sync
• verify
• install
• setup-local-adapter
• update
• upgrade
• migrate
• upstream-check
• lifecycle
• context7

hook adapters

.claude/settings.json 当前已接上：

• SessionStart
• PreToolUse
• PostToolUse
• Stop

平台 smoke matrix

GitHub Actions platform-smoke 当前已覆盖：

• Linux
• macOS
• Windows

当前可以准确表述为：

Linux 已长期实测；macOS / Windows 的当前 runtime smoke 路径已在 CI matrix 验证通过。

---

当前还不该夸大的地方

这个项目当前不是：

• 完整企业级强门禁平台
• 已 fully productized 的公开安装插件
• 所有路径都已接入同等强度 gate 的系统
• 所有本机环境都零差异支持的成品

以下能力仍在继续建设中：

• 更完整的 plan gate / task gate
• 更细粒度的 RED_VERIFIED 消费逻辑
• ArchUnit
• JaCoCo 85% 机械门禁
• 真实 HTTP API E2E
• 更强 OpenAPI 语义门禁
• 更完整 installer / upgrade / migration 体验
• 更广泛真机开发机场景验证

---

适合谁 / 不适合谁

适合谁

• 想把 Claude Code 用进 Java / Spring Boot 后端团队流程的人
• 想让 AI coding 从“会话技巧”进入“项目契约 + runtime + change 资产”的团队
• 想以 codegraph-first / Context7-first 方式组织探索和文档检索的人
• 想基于现有骨架继续做企业化扩展的人

不适合谁

• 想找一个已经发布完成、可一键安装的成品插件的人
• 想把它直接当成完整 CI/CD 与质量平台替代品的人
• 只关心前端 UI 点击测试的人

---

入口（先记这三个）

如果你只想先知道“从哪进”，记住这三条就够了：

• Claude Code 会话入口：/harness
• 新 change 命令入口：node harness/plugin/runtime/cli.mjs start-change <change-id> [owner] [tier] [topic]
• 自动兜底层：.claude/settings.json hooks 会自动做提醒、阻断和校验

也就是说：

• skill 负责流程编排
• command 负责确定性动作
• hooks 负责自动兜底

Quickstart

当前最推荐的接入方式仍是：clone 仓库后在仓库根目录执行 runtime CLI。

前置要求

• Node.js >= 20
• 推荐安装 codegraph
• 推荐可用 npx / ctx7

1. 获取仓库

git clone https://github.com/Emtemf/enterprise-harness.git
cd enterprise-harness

2. 首次接入

node harness/plugin/runtime/cli.mjs bootstrap
node harness/plugin/runtime/cli.mjs setup-local-adapter --write
node harness/plugin/runtime/cli.mjs doctor
node harness/plugin/runtime/cli.mjs sync
node harness/plugin/runtime/cli.mjs verify
node harness/plugin/runtime/cli.mjs upstream-check

3. 开始一个新 change

node harness/plugin/runtime/cli.mjs start-change <change-id> [owner] [tier] [topic]

4. 在 Claude Code 会话中进入工作流

• 优先从 /harness 开始
• 纯 intake 场景可继续走 harness-intake

5. 可选：使用 npm scripts

npm run bootstrap
npm run doctor
npm run sync
npm run verify
npm run upstream-check

完整安装说明见：

• docs/zh-cn/installation-guide.md
• harness/plugin/runtime/ONBOARDING.md

---

关键目录地图

.
├── README.md
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── rules/
│   ├── agents/
│   └── skills/
├── hooks/
├── harness/
│   ├── bin/
│   ├── changes/
│   ├── explorations/
│   ├── plugin/
│   ├── reviewers/
│   ├── specs/
│   ├── templates/
│   └── work/
├── docs/
│   └── zh-cn/
└── reference-service/

最重要的几个位置

• CLAUDE.md：项目高层操作合同
• .claude/rules/：自动加载规则源
• harness/specs/：长期稳定规范
• harness/templates/：change / design / tasks / validation 模板
• harness/changes/：活动 change 资产
• harness/plugin/runtime/：跨平台运行层
• reference-service/：Java 参考样板，不是插件本身的全部核心

---

文档地图

先看这些

• docs/zh-cn/overview.md
• docs/zh-cn/installation-guide.md
• docs/zh-cn/announcement.md
• docs/zh-cn/launch-post-kit.md
• docs/zh-cn/github-release-v0.1.0.md

核心 contract / spec

• CLAUDE.md
• harness/specs/plugin-runtime.md
• harness/specs/local-runtime-adapter.md
• harness/specs/containerization-sandboxing.md
• harness/specs/evidence-submission.md
• harness/specs/platform-validation-matrix.md
• harness/specs/release-readiness.md
• harness/specs/mvp-roadmap.md

对外协作

• CONTRIBUTING.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/ISSUE_TEMPLATE/
• .github/workflows/platform-smoke.yml

---

当前路线图（简版）

Iteration 1：门禁收紧

• design gate
• stale validation gate
• RED_VERIFIED 才允许生产源码写入
• reviewer verdict 消费逻辑更明确

Iteration 2：Java 黄金样板增强

• ArchUnit
• JaCoCo 85%
• 真实 HTTP API E2E
• 更强 OpenAPI 契约语义校验

Iteration 3：插件产品化

• machine-local adapter 正式 schema 继续收紧
• 更完整 installer
• upgrade / migration 机制完善
• 上游升级治理与版本盘点
• 更广泛平台 / 真机验证

---

语言约定

• 仓库文档、流程资产、评审说明默认使用中文
• 代码标识符、包名、公开 API 默认保持英文

---

一句话总结

Enterprise Harness 当前已经不是“几篇规则文档 + 一堆脚本”，而是：

一套围绕 Claude Code 的企业后端交付骨架：有共享契约、有变更生命周期、有本地运行层、有跨机器接入入口，并且关键路径已经真实跑通。