# Harness 场景使用详解（中文）

> 本文档覆盖官方主页 https://revfactory.github.io/harness/#en "Try These Prompts" 区块列出的全部 8 个场景。
> 每个场景包含：推荐架构模式、原文 prompt、中文释义、预期生成的 agent/skill、完整操作步骤、后续使用指令。
>
> **前置条件**：已按 `README_ZH.md` 完成安装（`/plugin install harness@harness` 或将 `skills/harness` 拷到 `~/.claude/skills/`）。

---

## 触发机制澄清：要不要调 `/xxx` 指令？

**不需要。Harness 是纯 Skill 插件，没有业务 slash command，直接粘贴 prompt 就会触发。**

查 `.claude-plugin/` 可见：插件只包含 `skills/harness-zh/SKILL.md`，没有 `commands/` 目录。Claude Code 通过匹配 SKILL.md 的 `description` 字段（触发短语：`给这个项目搭一个 harness`、`构建 harness`、`harness 设计`、`多 agent 协作` 等）**自动 Skill 调用**。

### 三种触发方式

| 方式 | 怎么做 | 何时用 |
|---|---|---|
| ① 自然语言（官方演示） | 直接粘贴场景 prompt | 默认首选，所有 8 个场景都这样用 |
| ② 显式 Skill 调用（兜底） | 在开头加 `请使用 harness skill …` | 当自然语言没命中、走到别的 skill 时 |
| ③ 插件市场命令 | `/plugin marketplace add …` + `/plugin install …` | **这是安装命令**，一次性，不是运行命令 |

> `/plugin …` 是 Claude Code 内置的**插件管理命令**，harness 自己没有 `/harness` 这种业务命令。

### 两个阶段的调用都不需要 `/`

1. **造团队阶段**：粘贴 `Build a harness for …` → Harness 生成 `.claude/agents/*` 与 `.claude/skills/*`。
2. **用团队阶段**：再粘贴真实任务（如 `开始构建博客网站：首页、文章列表 …`）→ Claude Code 依据 `CLAUDE.md` 里登记的 trigger 指针自动激活刚造好的团队。

两步**都不用 slash command**。

---

## 通用操作流程（所有场景共用）

不论哪个场景，交互节奏都一样：

1. **启动 Claude Code**，进入目标项目目录（若是内容/研究类，可新建一个空目录作为工作区）。
2. **粘贴场景 prompt** 触发 Harness。触发短语包括 `Build a harness …` / `给这个项目搭一个 harness` / `构建 harness` / `多 agent 协作` 等。
3. **Phase 0 审计**：Harness 先读 `.claude/agents/`、`.claude/skills/`、`CLAUDE.md`，汇报现状并向你确认是"新建 / 扩展 / 运维"。
4. **Phase 1–2 方案确认**：Harness 输出领域分析、执行模式（Team / Subagent / Hybrid）与架构模式建议。**此时审阅并可以修改**，避免生成后再返工。
5. **Phase 3–4 产物生成**：自动写入 `.claude/agents/*.md` 与 `.claude/skills/*/SKILL.md`。所有 agent 统一 `model: "opus"`。
6. **Phase 5–6 编排与验证**：注册编排器、更新 `CLAUDE.md` 的 trigger 指针、跑 dry-run 与 A/B 对比。
7. **进入使用阶段**：下一次用自然语言描述你的真实任务，Claude Code 会根据 `CLAUDE.md` 指针自动触发相应 team。
8. **反馈迭代**：每次任务结束后告诉 Harness "这里不够 / 那里过度"，它会更新 agents / skills，harness 会持续进化。

> 提示：Agent Team 一个 session 只能激活一支。Pipeline 类场景（如网站开发）中，Harness 会在 Phase 切换处解散旧团队、以文件交接产物，再组建下一支团队——这是预期行为。

---

## 1. 🔎 Deep Research（深度研究）

- **架构模式**：Fan-out / Fan-in（并行调查 → 汇总交叉验证）
- **原文 prompt**：
  > Build a harness for deep research. I need an agent team that can investigate any topic from multiple angles — web search, academic sources, community sentiment — then cross-validate findings and produce a comprehensive report.
- **中文释义**：为"深度研究"搭一个 harness，需要从网页搜索、学术文献、社区舆情三个角度并行调查某话题，互相交叉验证后产出综合报告。

### 预期生成

| Agent | 职责 |
|---|---|
| `web-researcher` | 调用 WebSearch / WebFetch，抓一手网页信息 |
| `academic-researcher` | 检索论文、技术白皮书，标注引用 |
| `community-analyst` | 收集 Reddit/HN/X 等社区情绪与反面观点 |
| `cross-validator` | 对三路结果做来源对齐、冲突标记 |
| `report-writer` | 合成最终报告（含引用、分歧说明） |

Skills（示例）：`web-search/`、`paper-search/`、`sentiment-extract/`、`cross-validate/`、`report-compose/`。

### 操作步骤

1. 新建研究工作区：`mkdir ~/research && cd ~/research && claude`
2. 粘贴上方原文 prompt。
3. 审阅 Phase 2 方案：确认是 Fan-out/Fan-in，fan-in 阶段应含"冲突检测与证据引用"。
4. 等待生成完成后，**用真实课题调用**：
   ```
   用刚才的深度研究 harness 调查：
   "2026 年小语言模型（SLM）在端侧部署的工业落地现状"
   输出：中文报告，≥3 个相互独立来源，冲突观点必须单列章节。
   ```
5. 阅读中间产物：报告草稿会落在 `research/report.md`，原始证据在 `research/evidence/`。
6. 追加指令示例：`帮我把社区观点单独抽成一份 5 分钟播客脚本`。

---

## 2. 🌐 Website Development（全栈网站开发）

- **架构模式**：Pipeline（设计 → 前端 → 后端 → QA）
- **原文 prompt**：
  > Build a harness for full-stack website development. The team should handle design, frontend (React/Next.js), backend (API), and QA testing in a coordinated pipeline from wireframe to deployment.
- **中文释义**：搭一个用于全栈网站开发的 harness，团队要能从线框图一路协调到上线：设计 → 前端（React/Next.js）→ 后端（API）→ QA 测试。

### 预期生成

| Agent | 职责 |
|---|---|
| `designer` | 线框 / 设计 token / 组件规范 |
| `frontend-dev` | Next.js 页面与组件 |
| `backend-dev` | API 路由、数据模型、鉴权 |
| `qa` | **必须是 `general-purpose`**，负责跨边界 shape 比对（前端 hook vs API 响应）、增量回归 |

### 操作步骤

1. 初始化前端工程：`npx create-next-app@latest my-site && cd my-site`
2. 运行 `claude`，粘贴原文 prompt。
3. **重点审阅 Phase 3**：
   - QA agent 类型必须是 `general-purpose`（非 `Explore`，后者无法跑脚本）。
   - `qa.md` 是否声明"每模块完成后立刻跑增量 QA"。
4. 生成完成后，给出真实需求触发 pipeline：
   ```
   开始构建博客网站：
   - 首页、文章列表、文章详情、Admin 登录后台
   - 后端用 Next.js API Routes + Prisma + SQLite
   - 鉴权用 NextAuth
   每完成一个模块让 qa agent 立刻增量校验。
   ```
5. 观察团队交接：`designer` 产物存 `docs/design/`，`frontend-dev` 与 `backend-dev` 并行推进但**在 contract 上对齐**（API schema 文件）。
6. 联调与部署：`qa` 跑 Playwright/Jest 后，再让团队生成部署说明（Vercel / 自托管 Dockerfile）。

---

## 3. 🎨 Webtoon Production（网漫/条漫制作）

- **架构模式**：Producer–Reviewer（互评保证风格一致）
- **原文 prompt**：
  > Build a harness for webtoon episode production. I need agents for story writing, character design prompts, panel layout planning, and dialogue editing. They should review each other's work for style consistency.
- **中文释义**：搭一个用于单集条漫制作的 harness，需要剧本、人物设定 prompt、分镜排版、对白润色四类 agent，彼此互审保证风格一致。

### 预期生成

| Agent | 职责 |
|---|---|
| `story-writer` | 分场剧本、情感曲线 |
| `character-designer` | 输出可喂给图像模型（MJ/SDXL）的人物描写 prompt |
| `panel-planner` | 页数、每页分镜、镜头语言 |
| `dialogue-editor` | 对白节奏、台词长度、声调 |
| `style-reviewer`（可选） | 统一美术与叙事风格 |

### 操作步骤

1. 新建项目：`mkdir webtoon-ep01 && cd webtoon-ep01 && claude`
2. 粘贴 prompt 触发 Harness。
3. 审阅 Phase 2：确认是 Producer–Reviewer，每个 producer 产出后都要经过至少一轮同侪 review。
4. 调用示例：
   ```
   用这个 harness 产出第 1 集（20 页）：
   - 世界观：赛博朋克 + 东亚都市
   - 主角：退役 AI 调试师；搭档：家用机器人
   - 目标情绪：悬疑开头 → 幽默中段 → 温情收尾
   ```
5. 收 4 份产物：`script.md`、`characters.md`（含图像 prompt）、`panels.md`、`dialogue.md`。
6. 让 `style-reviewer` 出一张风格一致性报告；不合格处自动回炉。

---

## 4. 🎥 YouTube Content（YouTube 内容策划）

- **架构模式**：Supervisor（中心 agent 动态调度）
- **原文 prompt**：
  > Build a harness for YouTube content creation. The team should research trending topics, write scripts, optimize titles/tags for SEO, and plan thumbnail concepts — all coordinated by a supervisor agent.
- **中文释义**：搭一个用于 YouTube 内容生产的 harness，团队包含趋势研究、脚本、SEO 标题/标签、封面创意，由一个 supervisor agent 统一调度。

### 预期生成

| Agent | 职责 |
|---|---|
| `supervisor` | 拆任务、分派、汇总、决定迭代轮次 |
| `trend-researcher` | 通过 Search 抓热度词与竞品 |
| `scriptwriter` | 撰写 hook + 段落脚本 |
| `seo-optimizer` | 标题、tag、描述（含 CTR 预估） |
| `thumbnail-designer` | 封面构图、文案、色彩方案（输出图像 prompt） |

### 操作步骤

1. 频道工作目录：`mkdir yt-channel && cd yt-channel && claude`
2. 粘贴 prompt。
3. 审阅 Phase 2：supervisor 必须**显式拥有路由与重试权**——检查 `supervisor.md` 里是否写了 "当 seo-optimizer CTR<X 时回炉 scriptwriter"。
4. 使用：
   ```
   用 YouTube harness 产出下周视频：
   - 主题：本地运行 DeepSeek-V3 完整指南
   - 目标观众：中文独立开发者
   - 期望长度：12 分钟
   输出：脚本、标题 5 选 1、标签 15 个、封面 3 版本
   ```
5. supervisor 会串行 / 并行编排并把最终包交付到 `episode-01/`。

---

## 5. 🔍 Code Review（代码审查与重构）

- **架构模式**：Fan-out / Fan-in（并行多维审计 → 汇总）
- **原文 prompt**：
  > Build a harness for comprehensive code review. I want parallel agents checking architecture, security vulnerabilities, performance bottlenecks, and code style — then merging all findings into a single report.
- **中文释义**：搭一个综合代码审查 harness，多个 agent 并行检查架构、安全漏洞、性能瓶颈、代码风格，最后合并成一份报告。

### 预期生成

| Agent | 职责 |
|---|---|
| `architect-reviewer` | 分层、依赖方向、耦合度 |
| `security-reviewer` | OWASP Top 10、密钥泄露、注入 |
| `perf-reviewer` | N+1、热点路径、分配/GC |
| `style-reviewer` | 命名、死代码、注释冗余 |
| `merger` | 冲突消解、严重度分级、生成报告 |

### 操作步骤

1. 在既有代码仓库根目录运行 `claude`。
2. 粘贴 prompt；确认 Phase 0 能发现既有项目类型（语言/框架）。
3. 使用：
   ```
   对本仓库 src/ 目录做完整 code review。
   输出格式：按"阻塞 / 重要 / 建议"三级分级的 Markdown 报告，附文件:行号。
   ```
4. 典型产物：`reports/review-YYYYMMDD.md`，还会在 PR 描述里留 `Fixes #issue`。
5. 想只审差异：`只审最近 5 个 commit 的增量`，Harness 会把 `git diff` 作为输入范围限定。

---

## 6. 📚 Technical Docs（技术文档 / API 文档）

- **架构模式**：Pipeline（分析 → 描述 → 示例 → 复核）
- **原文 prompt**：
  > Build a harness that generates API documentation from this codebase. Agents should analyze endpoints, write descriptions, generate usage examples, and review for completeness.
- **中文释义**：搭一个从代码库生成 API 文档的 harness，依次执行：端点分析 → 写描述 → 生成用法示例 → 完整性复核。

### 预期生成

| Agent | 职责 |
|---|---|
| `endpoint-analyzer` | 扫路由/handler，抽方法、参数、返回 schema |
| `description-writer` | 中/英文段落说明 + 使用约束 |
| `example-generator` | curl / SDK 代码片段、边界值用例 |
| `completeness-reviewer` | 缺参数、缺错误码、缺示例则打回 |

### 操作步骤

1. 在后端仓库根目录运行 `claude` 并粘贴 prompt。
2. 指定输出目标：
   ```
   用文档 harness 为 src/api/ 下全部路由生成 docs/api/。
   每个端点输出：签名表 + 描述 + 3 个 curl 示例（成功/失败/边界）。
   ```
3. 建议让 `completeness-reviewer` 的通过阈值设为"所有 public 路由 100% 覆盖"，不过则自动回 `description-writer`。
4. 追加国际化：`再出一份 docs/api/en/ 英文版`。

---

## 7. 📊 Data Pipelines（数据管道设计）

- **架构模式**：Hierarchical Delegation（分层委派）
- **原文 prompt**：
  > Build a harness for designing data pipelines. I need agents for schema design, ETL logic, data validation rules, and monitoring setup that delegate sub-tasks hierarchically.
- **中文释义**：搭一个数据管道设计 harness，包含 schema 设计、ETL 逻辑、校验规则、监控配置等 agent，以分层委派方式组织。

### 预期生成

| 层级 | Agent | 职责 |
|---|---|---|
| 上层 | `pipeline-architect` | 整体拓扑、数据契约、分层决策 |
| 中层 | `schema-designer` | 原始/中间/集市层 schema |
| 中层 | `etl-designer` | 任务 DAG、批/流选择、幂等策略 |
| 底层 | `validation-engineer` | 空值、枚举、分布漂移规则 |
| 底层 | `monitoring-engineer` | SLI/SLO、告警、血缘 |

### 操作步骤

1. 在数据项目目录运行 `claude`，粘贴 prompt。
2. 审阅 Phase 2：上层 agent 是否真的具备"向下拆分 + 收敛子任务"的协议（查看 `pipeline-architect.md` 的团队通信段落）。
3. 真实任务：
   ```
   用数据管道 harness 设计：
   - 源：Stripe Webhook + 自研 Postgres
   - 目的：BigQuery 数仓 + Looker 报表
   - SLA：T+1 小时可见，0 重复计费
   输出：Mermaid 拓扑图、dbt 模型骨架、Great Expectations 规则、监控 YAML
   ```
4. 产物位置：`pipelines/{topology.md, dbt/, validations/, monitoring/}`。

---

## 8. 🚀 Marketing Campaign（营销活动）

- **架构模式**：Producer–Reviewer（迭代质量审查）
- **原文 prompt**：
  > Build a harness for marketing campaign creation. The team should research the target market, write ad copy, design visual concepts, and set up A/B test plans with iterative quality review.
- **中文释义**：搭一个营销活动 harness，团队要研究目标市场、写广告文案、设计视觉概念、制定 A/B 测试计划，每轮都走质量审查。

### 预期生成

| Agent | 职责 |
|---|---|
| `market-researcher` | 人群画像、痛点、竞品定位 |
| `copywriter` | 广告文案（长/中/短三版） |
| `visual-conceptor` | 主视觉概念 + 图像 prompt |
| `ab-planner` | 变量、样本量、成功指标 |
| `campaign-reviewer` | 对齐 brand voice、合规、ROI 假设 |

### 操作步骤

1. 新工作区 `mkdir campaign-q2 && cd campaign-q2 && claude`。
2. 粘贴 prompt。
3. 审阅 `campaign-reviewer` 是否拥有"打回重做"权限——P-R 模式的关键。
4. 启动：
   ```
   用营销 harness 产出：
   - 产品：面向开发者的 AI IDE 插件，付费订阅
   - 地区：中国大陆 + 日本
   - 预算：$30k，2 周
   输出：受众文档 / 3 组文案 / 2 个视觉概念 / 完整 A/B 计划（含指标与停检条件）
   ```
5. 每轮产物落 `campaign-q2/round-N/`，`reviewer` 打回后会在 `round-N/review.md` 写理由。

---

## 跨场景通用小技巧

- **切换语言**：harness 生成物默认含韩文原语；可在 Phase 1 追加 `请将所有 agents/skills 以中文撰写`。
- **只要 Subagent 模式**：如果你的任务里 agent 间几乎不需要通信，追加 `请使用 Subagents 模式而非 Agent Teams`。
- **查看现状**：随时说 `harness 点检` / `帮我审计一下现有 harness` / `audit my harness`，触发 Phase 0 审计。
- **扩展而非重建**：新增一个 agent 就说 `给现有 harness 增加一个 translator agent`，Harness 会走"扩展矩阵"而非从零开始。
- **强制 opus**：若某个 agent 被降级成其他模型，提醒 Harness "所有 agent 必须 `model: opus`"——这是 SKILL.md 的硬性规定。
- **A/B 验证**：Phase 6 会跑 with-skill vs without-skill 对比。若对比缺失，直接说 `补一次 A/B 验证并给出质量增量`。

---

## 附录：对应的架构模式速查

| 场景 | 架构模式 | 核心机制 |
|---|---|---|
| Deep Research | Fan-out/Fan-in | 并行调查 + 交叉验证合并 |
| Website Development | Pipeline | 顺序流水线，强 contract 交接 |
| Webtoon Production | Producer-Reviewer | 生成后互审保证风格一致 |
| YouTube Content | Supervisor | 中心调度，动态回炉 |
| Code Review | Fan-out/Fan-in | 多维并行审计 + 合并报告 |
| Technical Docs | Pipeline | 顺序产出 + 完整性门禁 |
| Data Pipelines | Hierarchical Delegation | 上层拆分、下层执行 |
| Marketing Campaign | Producer-Reviewer | 迭代审查直到达标 |