diff --git a/README.md b/README.md
index b64e786..a56e63c 100644
--- a/README.md
+++ b/README.md
@@ -14,12 +14,12 @@
# Harness — The Team-Architecture Factory for Claude Code
-**English** | [한국어](README_KO.md) | [日本語](README_JA.md)
+**English** | [한국어](README_KO.md) | [日本語](README_JA.md) | [中文](README_ZH.md)
> **Harness is a team-architecture factory for Claude Code.** Say **"build a harness for this project"** (English) or **"하네스 구성해줘"** (한국어) or **"ハーネスを構成して"** (日本語), and the plugin turns your domain description into an agent team and the skills they use — picked from six pre-defined team-architecture patterns.
diff --git a/README_JA.md b/README_JA.md
index 542ce3e..befaeff 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -14,12 +14,12 @@
# Harness — Claude Code のためのチームアーキテクチャファクトリー
-[English](README.md) | [한국어](README_KO.md) | **日本語**
+[English](README.md) | [한국어](README_KO.md) | **日本語** | [中文](README_ZH.md)
> **Harness は Claude Code 向けのチームアーキテクチャファクトリーです。** **「ハーネスを構成して」** (日本語) · **"build a harness for this project"** (English) · **"하네스 구성해줘"** (한국어) と伝えるだけで、プラグインがドメイン記述をエージェントチームとそのチームが使うスキルへと変換します — あらかじめ定義された 6 種類のチームアーキテクチャパターンから 1 つを選んで。
diff --git a/README_KO.md b/README_KO.md
index 891994d..7295b8b 100644
--- a/README_KO.md
+++ b/README_KO.md
@@ -14,12 +14,12 @@
# Harness — Claude Code를 위한 팀 아키텍처 팩토리
-[English](README.md) | **한국어** | [日本語](README_JA.md)
+[English](README.md) | **한국어** | [日本語](README_JA.md) | [中文](README_ZH.md)
> **Harness는 Claude Code용 팀 아키텍처 팩토리입니다.** **"하네스 구성해줘"** (한국어) · **"build a harness for this project"** (English) · **"ハーネスを構成して"** (日本語) 한 문장으로, 플러그인이 도메인 설명을 에이전트 팀과 그들이 쓸 스킬로 변환합니다 — 사전 정의된 6가지 팀 아키텍처 패턴 중 하나를 골라서요.
diff --git a/README_ZH.md b/README_ZH.md
new file mode 100644
index 0000000..dccd5c5
--- /dev/null
+++ b/README_ZH.md
@@ -0,0 +1,303 @@
+
+
+
+
+
+
+
+
+
+# Harness — Claude Code 的团队架构工厂
+
+[English](README.md) | [한국어](README_KO.md) | [日本語](README_JA.md) | **中文**
+
+> **Harness 是面向 Claude Code 的团队架构工厂。** 只需说一句 **"build a harness for this project"**（English）、**"하네스 구성해줘"**（한국어）、**"ハーネスを構成して"**（日本語）或 **"帮我配置 harness"**（中文），插件就会把你的领域描述转化为一支 agent team 以及它们所用的 skill —— 从六种预定义的团队架构模式中挑选其一。
+
+## 概述
+
+Harness 借助 Claude Code 的 agent team 系统，把复杂任务分解为协同工作的专家 agent 团队。说一句 "build a harness for this project"，它就会自动生成贴合你领域的 agent 定义（`.claude/agents/`）与 skill（`.claude/skills/`）。
+
+## 类别 — Harness 所处的位置
+
+Harness 位于 Claude Code 生态的 **L3 Meta-Factory** 层 —— 这一层生成其他 harness，而非自身作为一个 harness。在 L3 内部，我们选择了一个具体的子层：**Team-Architecture Factory**。
+
+| 层级 | 它做什么 | 共存的邻居 |
+|-------|--------------|---------------------------|
+| **L3 — Meta-Factory / Team-Architecture Factory**（我们） | 一句领域描述 → agent team + skill，经由 6 种预定义团队模式 | — |
+| L3 — Meta-Factory / Runtime-Configuration Factory | 确定性、可复现的运行时配置 | [coleam00/Archon](https://github.com/coleam00/Archon) |
+| L3 — Meta-Factory / Codex Runtime Port | 相同理念，Codex 运行时 | [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) |
+| L2 — Cross-Harness Workflow | 在多个 harness 之间统一 skill/规则/hook | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) |
+
+> Archon 生成确定性的运行时配置。Harness 生成团队架构（pipeline、fan-out/fan-in、expert pool、producer-reviewer、supervisor、hierarchical delegation）以及 agent 所用的 skill。二者是同属 L3 的不同子层。需要运行时确定性就选 Archon，需要团队架构就选 Harness，也可以组合使用。
+
+## Star History
+
+
+
+
+
+
+
+## 核心特性
+
+- **Agent Team 设计** —— 6 种架构模式：Pipeline、Fan-out/Fan-in、Expert Pool、Producer-Reviewer、Supervisor、Hierarchical Delegation
+- **Skill 生成** —— 自动生成带 Progressive Disclosure 的 skill，实现高效的上下文管理
+- **编排（Orchestration）** —— agent 间数据传递、错误处理与团队协调协议
+- **校验（Validation）** —— 触发验证、dry-run 测试，以及「带 skill / 不带 skill」对比测试
+
+
+## 工作流
+
+```
+Phase 1: 领域分析
+ ↓
+Phase 2: 团队架构设计（Agent Team vs Subagent）
+ ↓
+Phase 3: 生成 Agent 定义（.claude/agents/）
+ ↓
+Phase 4: 生成 Skill（.claude/skills/）
+ ↓
+Phase 5: 集成与编排
+ ↓
+Phase 6: 校验与测试
+```
+
+## 安装
+
+### 通过 Marketplace 安装
+
+#### 添加 marketplace
+```shell
+/plugin marketplace add revfactory/harness
+```
+
+#### 安装插件
+```shell
+/plugin install harness@harness-marketplace
+```
+
+### 作为全局 Skill 直接安装
+
+```shell
+# 将 skills 目录复制到 ~/.claude/skills/harness/
+cp -r skills/harness ~/.claude/skills/harness
+```
+
+## 插件结构
+
+```
+harness/
+├── .claude-plugin/
+│ └── plugin.json # 插件清单
+├── skills/
+│ └── harness/
+│ ├── SKILL.md # 主 skill 定义（6-Phase 工作流）
+│ └── references/
+│ ├── agent-design-patterns.md # 6 种架构模式
+│ ├── orchestrator-template.md # 团队/subagent 编排模板
+│ ├── team-examples.md # 5 个真实团队配置
+│ ├── skill-writing-guide.md # Skill 编写指南
+│ ├── skill-testing-guide.md # 测试与评估方法论
+│ └── qa-agent-guide.md # QA agent 集成指南
+└── README.md
+```
+
+## 用法
+
+在 Claude Code 中用类似下面的提示触发：
+
+```
+Build a harness for this project
+Design an agent team for this domain
+Set up a harness
+帮我配置 harness
+```
+
+### 执行模式
+
+| 模式 | 说明 | 推荐场景 |
+|------|-------------|-----------------|
+| **Agent Team**（默认） | TeamCreate + SendMessage + TaskCreate | 需要 2 个以上 agent 协作 |
+| **Subagent** | 直接调用 Agent 工具 | 一次性任务，无需 agent 间通信 |
+
+
+
+
+### 架构模式
+
+| 模式 | 说明 |
+|---------|-------------|
+| Pipeline | 顺序、相互依赖的任务 |
+| Fan-out/Fan-in | 并行、相互独立的任务 |
+| Expert Pool | 依上下文选择性调用 |
+| Producer-Reviewer | 先生成，再做质量评审 |
+| Supervisor | 中心 agent 动态分配任务 |
+| Hierarchical Delegation | 自顶向下递归委派 |
+
+## 产出
+
+Harness 生成的文件：
+
+```
+your-project/
+├── .claude/
+│ ├── agents/ # Agent 定义文件
+│ │ ├── analyst.md
+│ │ ├── builder.md
+│ │ └── qa.md
+│ └── skills/ # Skill 文件
+│ ├── analyze/
+│ │ └── SKILL.md
+│ └── build/
+│ ├── SKILL.md
+│ └── references/
+```
+
+## 应用场景 —— 试试这些提示
+
+安装 Harness 后，把下面任意提示复制到 Claude Code 中：
+
+**深度调研（Deep Research）**
+```
+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.
+```
+
+**网站开发**
+```
+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.
+```
+
+**Webtoon / 漫画制作**
+```
+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.
+```
+
+**YouTube 内容策划**
+```
+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.
+```
+
+**代码评审与重构**
+```
+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.
+```
+
+**技术文档**
+```
+Build a harness that generates API documentation from this codebase.
+Agents should analyze endpoints, write descriptions, generate usage
+examples, and review for completeness.
+```
+
+**数据管线设计**
+```
+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.
+```
+
+**营销活动**
+```
+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 与它的邻居
+
+在 Claude Code / agent 框架生态里，Harness 并不孤单。以下仓库分布在相邻层级；每一项都以并列的「X 是……，Harness 是……」形式描述，方便你挑选合适的一个，或组合多个使用。
+
+| 仓库 | 它的定位 | 与 Harness 的关系 |
+|------|----------------|-------------------------|
+| [coleam00/Archon](https://github.com/coleam00/Archon) | "harness builder" —— 确定性、可复现的运行时配置 | **同属 L3，邻接子层。** Archon 是 Runtime-Configuration Factory，Harness 是 Team-Architecture Factory。需要运行时确定性选 Archon，需要团队架构选 Harness，或组合使用。 |
+| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 相同理念的 Codex 移植版 | **同属 L3，不同运行时。** 在 Claude Code 上用 Harness，在 Codex 上用 meta-harness。 |
+| [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | "Agent harness 性能与工作流层"（位于现有 harness 之上） | **不同层级。** ECC 是跨 harness 的标准化层；Harness 是生成 harness 的工厂。可串联组合。 |
+| [wshobson/agents](https://github.com/wshobson/agents) | Subagent / skill 目录（182 个 agent，149 个 skill） | **工厂 ↔ 零件供应。** wshobson 是可选购的目录；Harness 设计团队。把 wshobson 的条目作为零件吸收进 Harness 生成的团队中。 |
+| [LangGraph](https://langchain-ai.github.io/langgraph/) | 状态图编排，与 LLM 无关 | **不同赛道。** LangGraph 面向长时运行、状态可恢复的编排；Harness 面向快速、Claude-Code 原生的团队设计。 |
+
+## 用 Harness 构建的成果
+
+### Harness 100
+
+**[revfactory/harness-100](https://github.com/revfactory/harness-100)** —— 覆盖 10 个领域的 100 个生产级 agent team harness，提供英文与韩文两版（共 200 个包）。每个 harness 配有 4-5 个专家 agent、一个 orchestrator skill 以及领域专属 skill —— 全部由本插件生成。1808 个 markdown 文件，涵盖内容创作、软件开发、数据/AI、商业战略、教育、法律、健康等领域。
+
+### 研究：Harness 有效性的 A/B 测试
+
+**[revfactory/claude-code-harness](https://github.com/revfactory/claude-code-harness)** —— 一项覆盖 15 个软件工程任务的对照实验，衡量结构化预配置对 LLM 代码 agent 产出质量的影响。
+
+| 指标 | 不用 Harness | 用 Harness | 提升 |
+|--------|:-:|:-:|:-:|
+| 平均质量分 | 49.5 | 79.3 | **+60%** |
+| 胜率 | — | — | **100%**（15/15） |
+| 产出方差 | — | — | **-32%** |
+
+关键发现：有效性随任务复杂度递增 —— 任务越难，提升越大（Basic +23.8，Advanced +29.6，Expert +36.2）。
+
+**各处统一使用的表述：** +60% 平均质量（49.5 → 79.3）、15/15 胜率、−32% 方差（n=15，作者自测 A/B，第三方复现待补）。
+
+> 完整论文：*Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality.*
+
+## 依赖要求
+
+- [启用 Agent Teams](https://code.claude.com/docs/en/agent-teams)：`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+
+## 常见问题（FAQ）
+
+
+Q1. "+60%" 是不是夸大了？
+
+
+Q2. 为什么是 "harness factory" 而不是 "harness builder"？这不是在和 Archon 竞争吗？
+
+
+Q3. "仅支持 Claude Code" 是不是太窄了？Gemini/Codex 怎么办？
+
+## 许可证
+
+Apache 2.0
diff --git a/docs/experimental-dependency_ZH.md b/docs/experimental-dependency_ZH.md
new file mode 100644
index 0000000..653de61
--- /dev/null
+++ b/docs/experimental-dependency_ZH.md
@@ -0,0 +1,153 @@
+# 实验性开关依赖
+
+> **状态：** Active · **负责人：** revfactory · **最后更新：** 2026-04-18 · **SLA：** 见 [监控承诺](#监控承诺)
+
+本文档解释 `harness` 为何需要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`、该开关三种可能的未来，以及本仓库在每种情况下会做什么 —— 并给出限时承诺，便于企业采纳者据此规划。
+
+---
+
+## 当前状态
+
+### 为何需要这个开关
+
+`harness` 是一个构建于 Claude Code **Agent Teams API** 之上的元 skill 工厂。每当用户运行 `claude "build a harness for "` 时，内部会调用三个 Claude Code 原语：
+
+| 原语 | 用途 | 是否受开关限制 |
+|-----------|---------|-------------|
+| `TeamCreate` | 实例化一支共享上下文的多 agent 团队 | **是** |
+| `SendMessage` | 在团队成员间路由消息（supervisor ↔ worker） | **是** |
+| `TaskCreate` | 在团队内派生长时运行的子任务 | **是** |
+| `Agent` 工具（invoke） | 单 agent 派发 | 否（GA） |
+
+这三个受开关限制的原语都要求：
+
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+```
+
+如果启动 `claude` 的 shell 中未设置该变量，harness 生成的团队会回退为单 agent 执行，从而悄然破坏 Pipeline / Fan-out-in / Supervisor / Hierarchical Delegation 模式。
+
+### Anthropic 参考资料（提交 issue 前必读）
+
+该开关的设计理由与路线图见三篇 Anthropic Engineering 博文。评估 harness 的采纳者至少应阅读第一篇：
+
+1. [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) —— 定义了 Anthropic 认可的 "harness" 类别与长时运行 agent 契约。
+2. [Harness design for long-running apps](https://www.anthropic.com/engineering/harness-design-long-running-apps) —— `harness` 所固化的模式（Pipeline、Producer-Reviewer、Supervisor 等）。
+3. [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) —— 可能取代实验性开关的前进路径（见场景 B）。
+
+---
+
+## 依赖图
+
+```
+harness (v1.2.0)
+ └── Agent Teams API (Claude Code)
+ ├── TeamCreate ← EXPERIMENTAL_AGENT_TEAMS=1
+ ├── SendMessage ← EXPERIMENTAL_AGENT_TEAMS=1
+ ├── TaskCreate ← EXPERIMENTAL_AGENT_TEAMS=1
+ └── Agent (invoke) ← GA (与开关无关)
+ └── Anthropic Roadmap
+ ├── Scenario A: Flag removed (GA promotion)
+ ├── Scenario B: Managed Agents GA (parallel path)
+ └── Scenario C: Breaking signature change
+```
+
+**自顶向下阅读此图：** harness 依赖 Agent Teams API，后者依赖单个实验性开关，而该开关又依赖 Anthropic 自己的路线图。任一上游节点变化时，本仓库都有义务在下文 SLA 内适配。
+
+---
+
+## 3 种场景
+
+每种场景都列出**检测触发条件**（我们如何得知它发生）、本仓库承诺的 **T+24h / T+48h / T+72h 行动**，以及每个检查点的**用户可见产物**。
+
+### 场景 A —— 开关移除（Agent Teams 晋升 GA）
+
+**触发检测：** Anthropic Claude Code Changelog 发布 "Agent Teams is now GA"，**或** `claude-code` 二进制不再需要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`（由 [P-13](#) 的 nightly CI 检测）。
+
+**概率（主观）：** 高 —— 这是上述三篇博文所预示的路径。
+
+| 检查点 | 行动 | 产物 |
+|------------|--------|----------|
+| **T+24h** | 开 `feat/drop-experimental-flag` 分支。从每个 README / docs / Quickstart 移除 `export` 行。在 `plugin.json` 中加入 `claude-code >= X.Y.Z` 下界。 | 分支 + PR（草稿） |
+| **T+48h** | 发布 `docs/migrating-from-experimental.md`。把 `docs/experimental-dependency.md`（本文件）标题更新为 "no flag required as of vX.Y"。置顶 GitHub issue："Action required: drop the export line"。 | 迁移指南 + 置顶 issue |
+| **T+72h** | 发布 **v1.3.0**，包含：(a) CHANGELOG 条目，(b) 带迁移说明的 `gh release create`，(c) HN 跟进帖："We dropped the experimental flag"。 | `v1.3.0` git tag + GH Release |
+
+**采纳者影响：** 正面。企业审批阻力下降 —— "无实验性开关" 这一勾选项变得可满足。对 harness 用户代码无破坏性变更。
+
+---
+
+### 场景 B —— Managed Agents 进入 GA（并行路径）
+
+**触发检测：** Anthropic 发布 "[Managed Agents](https://www.anthropic.com/engineering/managed-agents) is generally available"，并提供稳定的 `claude-agents` CLI 或 SDK 接口。
+
+**概率（主观）：** 90 天内中-高。Managed Agents 是服务端执行模型；harness 的客户端团队编排**不会**自动迁移过去。
+
+| 检查点 | 行动 | 产物 |
+|------------|--------|----------|
+| **T+24h** | 开 `feat/managed-agents-compat` PR。加入 `adapters/managed-agents/` 脚手架，把 harness 的 6 种团队模式映射到 Managed Agents 调用。识别不兼容的模式（很可能是 Hierarchical Delegation）。 | 兼容 PR（草稿） |
+| **T+48h** | 发布博文：**"Harness + Managed Agents: one layer up, not replaced"**，发于 Dev.to 与本仓库。把 harness 重新定位为输出 Managed Agents 配置的**设计期**层，而非运行时竞品。 | 共存定位博文 |
+| **T+72h** | 发布 `docs/managed-agents-migration.md`，附逐模式矩阵（6 种模式中哪些 1:1 映射、哪些需重写）。更新 README 姊妹仓库一节。 | 迁移指南 |
+
+**战略说明：** harness 重新定位为 Managed Agents **之上的层** —— "Managed Agents 运行团队，harness 设计团队"。这是 GTM 计划 §4.2 中的共存框架。
+
+**采纳者影响：** 中性偏正面。现有 harness 用户继续在实验性开关路径上工作；新用户可选择 Managed Agents 输出。
+
+---
+
+### 场景 C —— 破坏性变更（API 签名突变）
+
+**触发检测：** Nightly CI（`.github/workflows/nightly-compat.yml`，路线图编号 P-13）对 Claude Code 最新 nightly 构建运行失败，**或** Changelog 宣布重命名的环境变量 / 变更的 `TeamCreate` 签名。
+
+**概率（主观）：** 中。实验性 API 可能在无弃用窗口的情况下被重命名。
+
+| 检查点 | 行动 | 产物 |
+|------------|--------|----------|
+| **T+0 至 T+24h** | Nightly CI 在 Slack/Discord 告警。作者开 `hotfix/compat-` 分支，修补受影响的调用点。在新旧签名上单测通过（尽力而为）。 | Hotfix 分支 |
+| **T+24h** | 合并 hotfix。推 `v1.2.x` 补丁 tag。更新 `docs/compatibility-matrix.md` 中受影响 Claude Code 版本的行。 | `v1.2.x` 补丁发布 |
+| **T+72h** | 若变更非平凡（影响 harness 的公共契约），在仓库 Discussions 标签页 + X 发布简短通告。否则一条 CHANGELOG 条目即可。 | Discussions 帖（视情况） |
+
+**采纳者影响：** 固定在旧版 Claude Code 的现有用户不受影响。使用最新版的用户会在同一周内获得补丁。
+
+---
+
+## 监控承诺
+
+我们承诺以下**可观测 SLA**。未达成即构成提交带 `sla-breach` 标签 issue 的理由。
+
+| 事件 | SLA | 度量方式 |
+|-------|-----|-------------|
+| Anthropic 在官方 Changelog 发布 Agent Teams / Managed Agents 变更 | 本文档在 **72 小时**内更新 | 对比 Changelog 帖时间戳与本文件 `最后更新` 行 |
+| Nightly CI 检测到兼容性破坏 | **24 小时**内开 hotfix 分支 | GitHub Actions 运行时间戳 vs. 分支创建时间戳 |
+| 新的 Claude Code 稳定版（minor 或 major） | **7 天**内为 `docs/compatibility-matrix.md` 添加对应行 | 兼容性矩阵 diff |
+
+**我们主动监控的来源：**
+
+- Claude Code 发布说明 —— 通过 [Anthropic Engineering 博客](https://www.anthropic.com/engineering) RSS 关注
+- `anthropics/claude-code` GitHub Releases（nightly tag）
+- Anthropic Discord `#claude-code` 频道（社区信号）
+
+---
+
+## 企业采纳者 FAQ
+
+### Q1. 我们处于受监管行业（金融、医疗、公共部门），无法在生产中启用 `EXPERIMENTAL` 开关。如何采纳 harness？
+
+**原因：** 许多合规框架（SOC 2 Type II、ISO 27001、K-ISMS）禁止在生产中使用不稳定 / 预览特性。
+**行动：** **仅在设计期**使用 harness：在沙箱工作站上运行它来生成 `.claude/agents/` 与 `.claude/skills/` 文件，然后把生成的产物提交进你的生产仓库。生产环境的 Claude Code 永远不需要这个开关 —— 只有受开关限制的 `TeamCreate` 运行时才需要。生成的单 agent skill 与 GA 路径兼容。
+
+### Q2. 如果 Agent Teams 进入 GA（场景 A），我现有的 harness 生成代码会坏吗？
+
+**原因：** 在 Anthropic 的 Claude Code 中，GA 晋升对生成产物历来是非破坏性的；只是该开关不再被要求而已。
+**行动：** 终端用户无需任何操作。你的 `.claude/agents/*.md` 与 `.claude/skills/*` 文件是纯 Markdown，仍然有效。GA 当天你即可 `unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`。我们会在 48 小时内发布迁移说明（见场景 A）。
+
+### Q3. 你们有书面 SLA 保证吗？如果没达成会怎样？
+
+**原因：** 企业在审批前需要一份合同级、或至少可观测的承诺。
+**行动：** 上方 SLA 表即为**公开承诺**，由以下机制保障：(a) 一个 GitHub Action，在检测到 Changelog 事件 72 小时后若本文件 `最后更新` 行仍未更新则在本文件下评论，(b) 采纳者可施加的 `sla-breach` issue 标签，(c) `CONTRIBUTING.md` 中对任何违约的事后复盘义务。这不是付费 SLA —— 而是社区承诺。如需付费 SLA，请联系维护者（见仓库 README）。
+
+---
+
+**相关文档：**
+- [`docs/quickstart.md`](./quickstart.md) —— 5 分钟安装演练
+- [`docs/show-hn-launch-kit.md`](./show-hn-launch-kit.md) —— 公开发布套件
+- `docs/compatibility-matrix.md` *（待补，P-13）* —— Claude Code × harness 版本对照表
diff --git a/docs/quickstart_ZH.md b/docs/quickstart_ZH.md
new file mode 100644
index 0000000..b091044
--- /dev/null
+++ b/docs/quickstart_ZH.md
@@ -0,0 +1,118 @@
+# 快速上手 —— 5 分钟构建你的第一个 Harness
+
+> **时间预算：5 分钟（严格）。** 如果 5 分钟内你还没走到 Step 5，请停下并提交 issue —— 那是本文档的 bug，不是你的问题。
+
+
+
+**结束时你将拥有：** 一个可用的 `.claude/agents/` 目录，里面有 3-5 个领域专精的 agent —— 由一句话提示生成，可直接在示例任务上运行。
+
+**前置条件（开始前请确认）：**
+- Claude Code **v2.x 或更高版本**（`claude --version` 应返回 `2.x` 或更高）
+- 一个能跨命令保留 `export` 的 shell（bash、zsh 或 fish）
+- 可访问 `github.com` 与 `api.anthropic.com` 的网络
+
+---
+
+## Step 1 —— 添加 marketplace（60 秒）
+
+```bash
+claude plugin marketplace add revfactory/harness
+```
+
+**作用：** 注册 `harness` marketplace，使 Claude Code 能发现 `revfactory` 发布的插件。
+
+**预期输出：** `Added marketplace: revfactory/harness`
+
+---
+
+## Step 2 —— 安装插件并启用实验性开关（40 秒）
+
+```bash
+claude plugin install harness@harness
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+```
+
+*（要让该开关在多个 shell 会话间持久生效，把 `export` 这一行追加到 `~/.zshrc` 或 `~/.bashrc`。）*
+
+**作用：** 从 `harness` marketplace 安装 `harness` 插件，然后启用 Agent Teams —— harness 用来编排多 agent 工作流的 Claude Code API。开关为何必需，见 [`docs/experimental-dependency.md`](./experimental-dependency.md)。
+
+**失败 FAQ #1 —— `AGENT_TEAMS not found` / team 无法实例化**
+**原因：** Claude Code 版本低于 v2.x（Agent Teams 在 v2.0 引入）。
+**修复：** 运行 `claude --version`。若低于 2.0，通过 `npm i -g @anthropic-ai/claude-code`（或你所用发行版的安装器）升级，然后重复 Step 2。
+
+---
+
+## Step 3 —— 用一句话生成一个 harness（2 分钟）
+
+```bash
+claude "build a harness for a fintech risk-assessment team"
+```
+
+**作用：** 调用 `/harness:harness` 元 skill，它会分析你的领域描述，并把一支专精 agent 团队 + 它们的 skill 脚手架写入当前目录的 `.claude/agents/` 与 `.claude/skills/`。
+
+**试试这些替代提示** —— 任意一条都有效：
+- `claude "帮我配置 harness —— 金融科技风险评估团队"`（中文同样有效）
+- `claude "하네스 구성해줘 — 핀테크 리스크 평가 팀"`（韩文同样有效）
+- `claude "build a harness for an e-commerce fraud-detection workflow"`
+- `claude "design an agent team for technical due diligence on open-source repos"`
+
+**预期输出：** 一段流式计划，随后确认已写出 3-5 个 agent `.md` 文件及其 skill。
+
+**失败 FAQ #2 —— 中文/韩文提示无响应，而英文提示成功**
+**原因：** 区域设置或分词器误路由；harness 的 orchestrator 基于触发词匹配（如韩文「하네스 구성」），这些触发词内建于 skill 定义中。
+**修复：** 若非英文提示失败，用上面的英文提示重试 —— 底层 skill 完全相同。若都失败，跳到失败 FAQ #3。
+
+---
+
+## Step 4 —— 校验生成的文件（30 秒）
+
+```bash
+ls -la .claude/agents/
+ls -la .claude/skills/
+```
+
+**作用：** 确认元 skill 已把文件写入预期位置。
+
+**预期输出：** 每个目录 3-5 个文件，文件名反映你的领域（如金融科技示例中的 `risk-analyst.md`、`compliance-reviewer.md`、`portfolio-monitor.md`）。
+
+**失败 FAQ #3 —— "什么都没生成" / 目录为空**
+**原因：** 插件实际未安装，或在当前项目中未激活。
+**修复：** 运行 `claude plugin list`。若没有 `harness@harness`，重复 Step 2。若存在但未激活，运行 `claude plugin enable harness@harness`，然后重复 Step 3。
+
+---
+
+## Step 5 —— 让新团队跑一个示例任务（90 秒）
+
+复制一条贴近真实的 Jira-工单式提示，交给你刚生成的团队：
+
+```bash
+claude "Ticket FIN-427: A new corporate customer (mid-cap manufacturer, \$80M revenue, South Korea) has applied for a \$5M working-capital line. Produce a risk assessment covering (1) credit-history red flags, (2) sector concentration vs. our existing book, (3) regulatory exposure (KFTC, FSC). Output: a 1-page memo with a go/no-go recommendation."
+```
+
+**作用：** Claude Code 检测到 `.claude/agents/` 中的新 agent，按 harness 生成的团队模式（风险类工作通常是 Producer-Reviewer 或 Expert-Pool）路由任务，并返回一份结构化备忘录。
+
+**失败 FAQ #4 —— "团队不执行 / 只有一个 agent 响应"**
+**原因：** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 在运行 Step 3 的 shell 中设置了，但运行 Step 5 的 shell 中没有（新开终端时常见）。
+**修复：** 在当前 shell 重新 export：`export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`，然后重跑 Step 5。要永久生效，把该行加入你的 shell rc 文件。
+
+**失败 FAQ #5 —— "API 调用太多 / 成本焦虑"**
+**原因：** 多 agent 团队每个任务可能扇出 5 个以上并行 Claude 调用。单个复杂工单可消耗 50K-200K token。
+**修复：** 每次运行限制为单个任务（不要用 `&&` 串联多次 harness 调用），若你的 Claude Code 版本支持，使用 `--max-turns` 标志。生产环境中，把 harness 调用置于成本感知的包装层之后 —— 见 `docs/cost-controls.md` *（待补）*。
+
+---
+
+## 完成
+
+到这一步，你应该已经拥有：
+
+- [x] 一个含领域专精 agent 的 `.claude/agents/` 目录
+- [x] 一个含其支撑 skill 的 `.claude/skills/` 目录
+- [x] 一次成功的示例任务执行
+- [x] 一个可用的 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境
+
+**下一步阅读：**
+- [`docs/experimental-dependency.md`](./experimental-dependency.md) —— 为何需要这个开关，以及它变化时我们会怎么做
+- [`revfactory/harness-100`](https://github.com/revfactory/harness-100) —— 100+ 预构建领域 harness 的目录，若你更想克隆而非生成
+- [`revfactory/claude-code-harness`](https://github.com/revfactory/claude-code-harness) —— 我们用来在 15 个任务上测得 +60% 质量的 A/B 测试 harness
+
+**如果你遇到本指南未覆盖的问题：** 提交一个带 `quickstart-gap` 标签的 issue，并附上：(a) 哪一步失败，(b) `claude --version`，(c) 准确的错误信息。quickstart-gap issue 的首次响应 SLA 为 **48 小时**（见 `CONTRIBUTING.md`）。
- 
+ 
+
+ 
+ 
+ 
+ 
+ 
+