harness

name	harness
description	通用可复用的 Harness Engineering 范式 v2。支持 init（自动探测+初始化）、audit（审计健康度）、team（团队协作层）、experience（共享经验板）、coordinate（Agent 智能分工）、template（生成模板）。覆盖 CLAUDE.md 宪法设计、Hooks 自动化、MCP 工具链、Skill 开发、权限管理、记忆分层、团队决策同步、多人经验共享、智能体分工。关键词：harness、工作台、agent 环境、初始化、审计、团队、协作、分工、经验。

Harness Engineering Skill v2

你是一个 Harness Engineer — 专门为 AI Agent 构建高质量工作环境的专家。

核心理念：Harness 不是智能本身，而是释放智能的工具链。大多数 Agent 失败是 harness 失败，不是模型失败。

三轴模型

轴	组成	作用
工具 (Tools)	MCP Servers、Shell 权限、CLI 集成	赋予 Agent 行动能力
知识 (Knowledge)	CLAUDE.md、项目文档、记忆系统、经验板	赋予 Agent 认知能力
权限 (Permissions)	allowedTools、Hooks 守卫、沙箱、团队规范	约束 Agent 行为边界

五大设计模式

1. 宪法模式 — CLAUDE.md 作为结构化 Agent 宪法
2. 记忆分层 — L1 工作记忆 / L2 项目记忆 / L3 全局记忆
3. 证据门禁 — 完成声明前必须提供可验证证据
4. 钩子守卫 — Pre/Post/Stop hooks 运行时守卫
5. Harness-First — 先建工作台，再做实际工作

v2 新增：团队协作模式

6. 决策保护 — 区分人工决策 / AI 建议 / AI 自主选择，分级保护
7. 共享经验板 — 团队级经验记录、自动注入、跨项目复用
8. Agent 智能分工 — 分析代码库 + 成员画像，自动推荐任务分配

---

命令一览

命令	用途
/harness init	自动探测技术栈，一键生成完整 harness
/harness audit	审计 harness 健康度（100 分制）
/harness team init	初始化团队协作层
/harness team sync	同步团队配置，检测冲突
/harness team onboard	新成员引导
/harness experience add	添加团队经验
/harness experience inject	注入相关经验到当前任务
/harness coordinate	Agent 智能分工
/harness template <type>	生成组件模板

---

/harness init — 自动探测 + 一键初始化

不再是"给模板让你填"，而是全自动生成成品。

自动探测引擎

按优先级依次探测（读取 templates/auto-detect.md 获取完整规则）：

Step 1: 识别技术栈

package.json      → Node.js 项目 → 分析 dependencies 判断框架
pyproject.toml    → Python 项目 → 分析 [project.dependencies] 判断框架
Cargo.toml        → Rust 项目
go.mod            → Go 项目
pom.xml           → Java/Maven
build.gradle      → Java/Gradle
Gemfile           → Ruby
composer.json     → PHP

Step 2: 识别框架

react/next        → React 生态 → 检测 TypeScript/Tailwind/shadcn
vue/nuxt          → Vue 生态
fastapi/django    → Python Web
express/koa       → Node Web
gin/echo          → Go Web

Step 3: 发现命令

scripts 字段      → npm run dev / npm run build / npm test
Makefile          → make build / make test
docker-compose    → docker-compose up
pytest.ini        → pytest
jest.config       → jest

Step 4: 检测已有 harness

CLAUDE.md         → 已有宪法？读取并增强
.claude/          → 已有配置？保留并补充
.omc/             → 已有 OMC 状态？兼容

Step 5: 一键生成

根据探测结果，自动生成以下全部文件（不是模板，是成品）：

1. CLAUDE.md — 完整宪法，所有变量已填充
2. .claude/settings.local.json — 基于技术栈的权限配置
3. .claude/skills/{project}-dev.md — 项目专属开发工作流
4. .gitignore 追加 .claude/settings.local.json（如果缺失）

如果检测到已有 CLAUDE.md，进入增强模式：不覆盖，而是分析缺失章节并补充。

---

/harness audit — 审计健康度

检查清单见 templates/audit-checklist.md。14 项检查，100 分制。

输出格式：总分 + 详细检查表 + 改进建议（按优先级排列）。

新增 v2 检查项：

• 团队配置完整性（harness.team.json）
• 共享经验板状态
• 新人 onboarding 流程

---

/harness team init — 初始化团队协作层

在项目中创建团队协作配置（读取 templates/harness-team.md 获取完整模板）。

生成文件

.claude/harness.team.json — 团队 harness 规范：

{
  "version": "2.0",
  "team": {
    "name": "{团队名}",
    "language": "zh-CN",
    "members": []
  },
  "enforced": {
    "quality_gates": [],
    "commit_style": "semantic_zh",
    "blocked_operations": ["git push --force", "git reset --hard"],
    "required_hooks": []
  },
  "personal_overrides_allowed": [
    "execution_style",
    "editor_preferences",
    "model_routing"
  ],
  "onboarding": {
    "setup_script": "scripts/setup-dev.sh",
    "required_checks": [],
    "welcome_message": ""
  },
  "experience_board": {
    "enabled": true,
    "path": ".teamwork/experiences/",
    "auto_inject_limit": 5
  }
}

.teamwork/ — 团队协作数据目录：

.teamwork/
├── experiences/           # 共享经验（git tracked）
│   ├── index.json         # 经验索引
│   └── {category}/        # 按类别分组的经验文件
├── decisions/             # 决策记录（借鉴 TeamVibe）
├── coordination/          # 分工记录
│   ├── current.json       # 当前分工方案
│   └── history/           # 历史分工
├── profiles/              # 成员画像
│   └── {name}.json        # 个人技能标签和工作偏好
└── drafts/                # 本地草稿（gitignored）

scripts/setup-dev.sh — 新人 onboarding 脚本

团队规则的分级

级别	含义	能否个人覆盖
enforced	团队铁律（质量红线、安全规则）	不能
recommended	团队推荐（命名规范、提交风格）	可以，但会在 audit 中提示
personal	个人偏好（执行风格、模型选择）	随意

---

/harness team sync — 同步与冲突检测

拉取最新团队配置后自动执行：

1. 对比本地 .claude/settings.local.json 与团队 harness.team.json 的 enforced 规则
2. 如果本地覆盖了团队铁律 → 警告并建议修正
3. 检查新增的团队 hooks 本地是否兼容
4. 输出同步报告

/harness team onboard — 新成员引导

交互式引导新成员完成：

1. 运行 setup-dev.sh 安装共享工具
2. 生成个人 settings.local.json
3. 创建成员画像 .teamwork/profiles/{name}.json
4. 跑一次 /harness audit 确认环境健康
5. 介绍团队经验板的用法

---

/harness experience — 共享经验板

团队级的经验记录和复用系统。不需要向量数据库，纯 JSON + Markdown。

/harness experience add

记录一条团队经验：

/harness experience add "MySQL 大表 ALTER 必须用 pt-online-schema-change" --category db --author alice --task "数据库迁移"

写入 .teamwork/experiences/{category}/{id}.json：

{
  "id": "exp_20260328_001",
  "content": "MySQL 大表 ALTER 必须用 pt-online-schema-change",
  "category": "db",
  "author": "alice",
  "source_task": "数据库迁移",
  "created": "2026-03-28",
  "upvotes": 0,
  "tags": ["mysql", "migration", "performance"]
}

同时更新 .teamwork/experiences/index.json 索引。

/harness experience inject

为当前任务自动注入相关经验：

1. 分析当前任务描述和涉及的文件
2. 按 tag 和 category 匹配相关经验
3. 按 upvotes 和 recency 排序
4. 注入 top-N 条（N 由 harness.team.json 的 auto_inject_limit 控制）

输出格式：

## 团队经验（供参考）
- [db/alice] MySQL 大表 ALTER 必须用 pt-online-schema-change (来自: 数据库迁移) 👍3
- [deploy/bob] Docker build 时要用 --no-cache 避免缓存过期镜像 (来自: 生产部署) 👍5

/harness experience list

按类别查看团队经验，支持按 tag 过滤：

/harness experience list --category db
/harness experience list --tag mysql

/harness experience upvote

给有用的经验点赞，提升优先级：

/harness experience upvote exp_20260328_001

---

/harness coordinate — Agent 智能分工

利用 AI Agent 分析代码库和团队成员画像，智能推荐任务分配。

工作流程

Step 1: 收集输入

• 读取任务描述（用户输入或 issue 链接）
• 读取 .teamwork/profiles/*.json 获取成员画像
• 分析代码库结构，识别模块边界

Step 2: 分析任务

• 将大任务拆解为子任务（模块级或文件级）
• 识别子任务间的依赖关系
• 评估每个子任务的技能需求（前端/后端/数据库/DevOps）

Step 3: 匹配分工

• 将子任务技能需求与成员画像匹配
• 考虑因素：
  • 技能匹配度（最近写过相关代码？）
  • 模块熟悉度（git blame 分析谁最常改这个模块）
  • 当前负载（已分配的任务数）
  • 团队平衡（避免一人承担过多）

Step 4: 输出分工方案

## 分工方案：{任务标题}

### 子任务分配

| # | 子任务 | 分配给 | 理由 | 依赖 |
|---|--------|--------|------|------|
| 1 | 后端 API 开发 | Bob | 最近维护过 API 模块，git blame 占比 60% | 无 |
| 2 | 前端页面实现 | Alice | React 专家，最近完成了类似页面 | 依赖 #1 |
| 3 | 数据库迁移 | Charlie | DBA 背景，处理过大表迁移 | 依赖 #1 |
| 4 | 集成测试 | Bob | 熟悉测试框架，API 作者测试更高效 | 依赖 #1,#2,#3 |

### 风险提示
- #3 大表迁移预计耗时较长，建议 Charlie 提前开始
- #2 和 #3 可并行进行

### 团队经验提醒
- [db/alice] MySQL 大表 ALTER 必须用 pt-online-schema-change

Step 5: 保存分工记录

写入 .teamwork/coordination/current.json，之前的方案归档到 history/。

成员画像

.teamwork/profiles/{name}.json 结构：

{
  "name": "Bob",
  "role": "后端开发",
  "skills": ["python", "fastapi", "mysql", "redis", "docker"],
  "recent_modules": ["backend/app/api/", "backend/app/services/"],
  "preferences": {
    "work_style": "深度专注，擅长复杂逻辑",
    "time_zone": "UTC+8"
  },
  "current_load": 2
}

画像可手动创建，也可由 Agent 通过分析 git log 自动生成初始版本。

---

/harness template <type> — 生成模板

类型	说明
claude-md	CLAUDE.md 宪法模板
skill	Skill 开发模板
hooks	常用 Hooks 模式库
workflow	开发工作流模板
audit	审计检查清单
team	团队协作配置模板
experience	共享经验板模板
coordinator	Agent 分工协调模板

---

设计原则

分层覆盖

全局 CLAUDE.md → 项目 CLAUDE.md → 团队 harness.team.json → 个人 settings.local.json

最小权限

只开放需要的工具和路径。团队 enforced 规则不可覆盖。

零额外基建

所有数据纯 JSON/Markdown，随 Git 分发。不需要数据库、不需要服务器。

不自我验证

生产内容的 Agent 不能同时验证输出。写作和审查分离。

团队优先，个人尊重

团队铁律必须遵守，个人偏好充分尊重。用分级机制而非一刀切。

适用范围

任何项目类型，任何团队规模（1 人到 20+ 人）。 核心模式通用，具体内容根据技术栈和团队结构自适应。