coding-agent-harness 1.0.0

package/docs-release/architecture/overview.md

@@ -0,0 +1,52 @@
+# Architecture Overview
+
+Coding Agent Harness is a document-governed operating layer for long-running coding
+agent work. It uses repository-native files, state contracts, role boundaries, and
+checks to keep agent sessions auditable and recoverable.
+
+## Public Architecture
+
+```mermaid
+flowchart TB
+  Skill["Skill / Agent Entry"]
+  Docs["Public Standards<br/>references/"]
+  Templates["Install Templates<br/>templates/"]
+  Target["Target Project Docs<br/>AGENTS.md + docs/"]
+  Check["Checker / Status CLI"]
+
+  Skill --> Docs
+  Skill --> Templates
+  Templates --> Target
+  Docs --> Target
+  Check --> Target
+```
+
+## Operating Principle
+
+The harness separates three concerns:
+
+| Layer | Responsibility |
+| --- | --- |
+| Public package | Ships reusable standards, templates, and checker logic. |
+| Target project docs | Store the project's live plans, SSoTs, ledgers, and evidence. |
+| Private operations | Store repository-local review drafts, handoffs, and release decisions. |
+
+The public package should describe the system. It should not publish private
+operating ledgers from this repository or from any target project.
+
+## Worker / Coordinator Boundary
+
+```mermaid
+flowchart LR
+  Worker["Worker<br/>local module files"]
+  Handoff["Coordinator Handoff"]
+  Coordinator["Coordinator<br/>global facts"]
+  Check["Strict Check"]
+
+  Worker --> Handoff
+  Handoff --> Coordinator
+  Coordinator --> Check
+```
+
+Workers own local task and module facts. Coordinators own global projections such
+as registries, ledgers, closeout indexes, and regression state.

package/docs-release/guides/agent-installation.md

@@ -0,0 +1,139 @@
+# Agent 安装指南
+
+这份指南写给在目标项目里执行安装或升级的 coding agent。README 只保留给人看的定位、
+快速开始和最小命令；安装细则放在这里和 `SKILL.md`。
+
+## 操作合同
+
+这套 CLI 的主要操作者通常是目标项目里的 agent，不是最终用户。Agent 不应该要求用户
+研究命令参数、模板目录或 capability 选择；这些决策必须在 Diagnose / Decide 阶段完成，
+并在交付 summary 中说明依据。
+
+使用 v1.0 六阶段流程：
+
+1. Diagnose：扫描项目结构、语言、现有文档、CI、协作方式和风险面。
+2. Decide：确定 locale、delivery model 和 capability packs。
+3. Scaffold：运行 `harness init` 或 `harness add-capability`。
+4. Configure：把生成文档改成项目事实；不要把模板假装成已定制标准。
+5. Verify：运行 CLI 检查和项目原生证据。
+6. Deliver：输出 residual、owner 和下一步。
+
+## 语言规则
+
+- 用户在场时，先问 harness 文档使用中文还是英文。
+- 非交互安装必须显式传 `--locale zh-CN` 或 `--locale en-US`，不要依赖默认值。
+- 中文用户或中文优先项目使用 `zh-CN`。
+- 英文团队、英文优先仓库或用户明确要求英文时使用 `en-US`。
+- 同一个目标项目不要混用 `templates/` 和 `templates-zh-CN/`；只有 schema 字段、
+  文件名、状态枚举、命令和跨工具协议 token 可以保留英文。
+
+## 新项目初始化
+
+目标项目没有旧 harness 时使用这条路径：
+
+```bash
+node scripts/harness.mjs init \
+  --locale zh-CN \
+  --capabilities core,dashboard \
+  /path/to/project
+```
+
+Capability 要保守选择：
+
+| Capability | 默认 | 何时选择 |
+| --- | --- | --- |
+| `core` | 是 | 永远安装。这是 document kernel。 |
+| `dashboard` | 否 | 用户或 agent 需要本地只读状态页。 |
+| `safe-adoption` | 否 | 旧 harness 项目接入 v1.0，需要保留历史文档。 |
+| `adversarial-review` | 否 | 发布、架构、安全、数据或策略风险需要独立 review artifact。 |
+| `long-running-task` | 否 | Agent 需要连续多轮执行，不能每步都询问用户。 |
+| `module-parallel` | 否 | 两个以上独立模块需要 owner、registry 和同步规则。 |
+| `subagent-worker` | 否 | 会改代码的 subagent 需要独立 worktree 和 commit-backed handoff；依赖 `module-parallel`。 |
+
+`init` 的 JSON 输出会包含 `report`。交付 summary 必须包含：
+
+- locale
+- selected capabilities，以及每个可选 capability 的选择理由
+- created / skipped files
+- Configure 阶段做了哪些项目化改动
+- verification commands 和结果
+- residual owner / action / status
+- 是否提交；如果只是 dogfood 测试，是否已清理测试产物
+
+## 用户级注册
+
+如果用户已经通过 npm 或源码拿到了 `harness` CLI，可以把本 Skill 注册到用户级
+agent 目录，避免每个项目重复拷贝：
+
+```bash
+harness install-user --agent codex --global
+harness doctor-user --agent codex
+```
+
+支持的 agent target：
+
+| Agent | 用户级目录 |
+| --- | --- |
+| `codex` | `~/.codex/skills/coding-agent-harness` |
+| `claude` | `~/.claude/skills/coding-agent-harness` |
+| `gemini` | `~/.gemini/skills/coding-agent-harness` |
+| `openclaw` | `~/.openclaw/skills/coding-agent-harness` |
+| `agents` | `~/.agents/skills/coding-agent-harness` |
+| `all` | 安装到以上所有目录 |
+
+安全规则：
+
+- 默认交互确认；非交互场景必须传 `--yes` 或先用 `--dry-run`。
+- 默认不覆盖已有文件，只补缺失文件。
+- 需要强制更新时显式传 `--force`。
+- `doctor-user` 会检查 `SKILL.md`、模板、references、CLI scripts 和本指南是否存在。
+
+## 旧 Harness 迁移
+
+目标项目已经有旧版 harness 时使用这条路径。不要把旧文档重建一遍：
+
+```bash
+node scripts/harness.mjs add-capability safe-adoption \
+  --locale zh-CN \
+  /path/to/old-project
+```
+
+规则：
+
+- 不覆盖已有 `AGENTS.md`、`CLAUDE.md`、`docs/Harness-Ledger.md`、SSoT、
+  walkthrough、task progress 和历史 task plan。
+- 只补齐缺失的 v1.0 模板和 capability registry。
+- 已有项目事实只能 merge、append 或记录 residual；不能用泛化模板替换。
+- 历史合同缺口在普通模式下进入 `adoption-needed` warning。
+- `--strict` 必须仍然能因为旧 checker 失败或历史合同缺口而失败。
+
+## 验证命令
+
+安装或升级收口前，至少运行：
+
+```bash
+node scripts/harness.mjs check --profile target-project /path/to/project
+node scripts/harness.mjs status --json /path/to/project
+node scripts/harness.mjs dashboard --out /tmp/harness-dashboard.html /path/to/project
+```
+
+开发本仓 v1.0 kernel 时，release gate 是：
+
+```bash
+npm test
+npm run smoke:dashboard
+node scripts/harness.mjs check --profile source-package .
+node scripts/harness.mjs check --profile private-harness .harness-private
+node scripts/harness.mjs check --profile target-project examples/minimal-project
+```
+
+## 必跑回归路径
+
+任何 v1.0 kernel 改动都必须覆盖两条路径：
+
+| 路径 | 必须证明 |
+| --- | --- |
+| 新项目初始化 | 空项目 `init --locale zh-CN\|en-US --capabilities core,...` 后，模板语言一致、registry 正确、`status --json` 不误报 `safe-adoption`。 |
+| 旧 harness 迁移 | 旧项目 `add-capability safe-adoption --locale ...` 后，旧文件不被覆盖，缺失 v1.0 模板被补齐，普通模式 warning，strict 模式能阻塞历史缺口。 |
+
+真实项目 dogfood 默认清理测试产物，除非用户明确要求保留并提交。

package/examples/minimal-project/.harness-capabilities.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "capabilities": [
+    {"name": "core", "state": "configured"},
+    {"name": "review-contract", "state": "verified"},
+    {"name": "dashboard", "state": "verified"}
+  ]
+}

package/examples/minimal-project/AGENTS.md

@@ -0,0 +1,4 @@
+# Minimal Harness Example
+
+Use `docs/11-REFERENCE/` for project rules and `docs/09-PLANNING/TASKS/` for
+task execution records.

package/examples/minimal-project/CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Entry
+
+Read `AGENTS.md` first.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/execution_strategy.md

@@ -0,0 +1,10 @@
+# Execution Strategy
+
+| Decision | Choice | Notes |
+| --- | --- | --- |
+| Primary executor | coordinator | Example task only. |
+| Subagents | none | No parallel work needed. |
+| Review model | self-check | Demonstrates the contract shape. |
+| Worktree strategy | same checkout | Public example fixture. |
+| Conflict control | coordinator owns shared files | No shared-file contention. |
+| Evidence depth | L0 | Fixture-level evidence only. |

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/progress.md

@@ -0,0 +1,11 @@
+# Demo Task - Progress
+
+## Status
+
+in-progress
+
+## Updates
+
+| Date | Update | Evidence |
+| --- | --- | --- |
+| 2026-05-18 | Created example roadmap | report:TARGET:docs/09-PLANNING/TASKS/demo-task/visual_roadmap.md:example phase table |

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/review.md

@@ -0,0 +1,27 @@
+# Demo Task - Review
+
+## Reviewer Identity
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| coordinator | self-check | example |
+
+## Confidence Challenge
+
+No material finding for this example.
+
+## Evidence Checked
+
+| Evidence ID | Type | Path | Summary |
+| --- | --- | --- | --- |
+| E-001 | review | TARGET:docs/09-PLANNING/TASKS/demo-task/task_plan.md | Visual roadmap table exists |
+
+## Findings
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| R-001 | P3 | Example only | E-001 | none | no | closed | no | none |
+
+## Final Confidence Basis
+
+self-check only; example is not a release approval.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/task_plan.md

@@ -0,0 +1,14 @@
+# Demo Task
+
+## Goal
+
+Show the v1.0 visual roadmap contract.
+
+## Scope
+
+Public example only.
+
+## Execution & Visualization Files
+
+- `execution_strategy.md`
+- `visual_roadmap.md`

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/visual_roadmap.md

@@ -0,0 +1,11 @@
+# Visual Roadmap
+
+```mermaid
+flowchart LR
+  P1["Plan"] --> P2["Verify"]
+```
+
+| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| P1 | none | done | 100 | Example plan | review | present | none | coordinator |
+| P2 | P1 | planned | 0 | Example verification | command | missing | none | coordinator |

package/examples/minimal-project/docs/Harness-Ledger.md

@@ -0,0 +1,6 @@
+# Harness Ledger
+
+| ID | Task | Status | Review State | Next Action | Owner |
+| --- | --- | --- | --- | --- | --- |
+| LED-001 | demo-task | in_progress | review-ready | Verify rendered roadmap and evidence | coordinator |
+| LED-002 | escaped-pipe-demo | planned | pending | Confirm parser keeps alpha\|beta notes | coordinator |

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "coding-agent-harness",
+  "version": "1.0.0",
+  "description": "Document governance kernel for long-running coding agents.",
+  "type": "module",
+  "bin": {
+    "harness": "scripts/harness.mjs"
+  },
+  "scripts": {
+    "check": "node scripts/harness.mjs check --profile source-package .",
+    "check:private": "node scripts/harness.mjs check --profile private-harness .harness-private",
+    "status": "node scripts/harness.mjs status --json .",
+    "dashboard": "node scripts/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
+    "dashboard:folder": "node scripts/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
+    "smoke:dashboard": "node scripts/smoke-dashboard.mjs",
+    "test": "node scripts/test-harness.mjs"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "SKILL.md",
+    "LICENSE",
+    "references/",
+    "templates/",
+    "templates-zh-CN/",
+    "scripts/",
+    "docs-release/",
+    "examples/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/references/adversarial-review-standard.md

@@ -0,0 +1,173 @@
+# Adversarial Review Standard
+
+## 核心思路
+
+对抗性审查不是普通总结，也不是 walkthrough。它是任务完成前的独立挑战环节：
+主动寻找错误假设、边界遗漏、回归风险、证据缺口和过早收口。
+
+每个需要 reviewer agent、subagent、外部审查者或多轮 hardening 的任务，都必须写
+`review.md`。这是 reviewer 的一等交付物，不应只散落在 `progress.md` 或对话记录里。
+
+## 存放位置
+
+标准位置：
+
+```text
+docs/09-PLANNING/TASKS/<YYYY-MM-DD-任务名>/review.md
+```
+
+任务目录中的文件职责：
+
+- `task_plan.md`：目标、范围、步骤、验收标准
+- `findings.md`：研究发现和技术决策
+- `progress.md`：执行过程和验证记录
+- `review.md`：对抗性审查报告、findings、no-finding 结论和残余风险
+- `long-running-task-contract.md`：连续执行合同（仅长程任务需要）
+
+## 何时必须写
+
+以下情况必须写 `review.md`：
+
+- 使用 reviewer agent、subagent 或外部审查者
+- 长程任务合同中包含 review loop
+- 任务触及共享架构、数据、安全、权限、部署、迁移或跨模块契约
+- regression gate、live smoke、browser inspection 或 release 前验证暴露过问题
+- 用户明确要求“review”“审查”“对抗性审查”“再挑一遍问题”
+
+轻量单文件修复可以在 `progress.md` 写自审结论，但如果发现 material risk，应升级为
+`review.md`。
+
+## 审查姿态
+
+Reviewer 必须以找问题为目标，而不是证明实现正确。
+
+每轮对抗性审查必须先使用 Confidence Challenge：
+
+> 你对这个方案、实现和策略有 100% 的信心吗？如果没有，找出所有可能的漏洞，提出适当的修复建议，并运行这个循环，直到你对新策略事实上有 100% 的信心。
+
+这里的“100% 信心”不是主观自信，而是基于当前 scope、证据和已知风险的工程判断：
+
+- 不允许直接回答“有信心”来跳过审查。
+- 如果存在任何可验证的漏洞、证据缺口或未处理的 material risk，必须写入 findings。
+- 修复建议必须具体到代码、测试、文档、回归或后续任务路由。
+- 每轮修复后必须重新运行 Confidence Challenge，直到没有 open material finding。
+
+审查重点：
+
+1. **Goal / Scope Drift**：实现是否偏离任务目标，是否偷偷扩大或遗漏 scope
+2. **Behavioral Regression**：已有行为是否被破坏，尤其是调用方契约和状态流转
+3. **Boundary / Security Risk**：权限、输入、路径、网络、数据边界是否有漏洞
+4. **Evidence Gap**：测试、smoke、日志、截图或 trace 是否不足以支持结论
+5. **Operational Risk**：部署、回滚、配置、迁移、并发、定时任务是否有未验证风险
+6. **Maintainability Risk**：实现是否引入难以维护的耦合、重复或隐藏状态
+
+## 报告结构
+
+`review.md` 必须包含：
+
+```markdown
+# [任务名称] - Review
+
+## Review Scope
+- Reviewer:
+- Review type:
+- Reviewed refs:
+- Out of scope:
+
+## Confidence Challenge
+- Question: 你对这个方案、实现和策略有 100% 的信心吗？
+- Answer:
+- If not 100%, remaining vulnerabilities:
+- Fix loop count:
+- Final confidence basis:
+
+## Material Findings
+| ID | Severity | Area | Finding | Evidence | Required Action | Status |
+|----|----------|------|---------|----------|-----------------|--------|
+
+## Non-Material Notes
+- [不阻塞但值得记录的问题；如无写"无"]
+
+## Evidence Checked
+- [ ] [测试 / smoke / 日志 / 截图 / PR / diff / runtime evidence]
+
+## No-Finding Statement
+[如果没有 material finding，明确写：本轮未发现阻塞目标的 material finding。]
+
+## Residual Risk
+- [已知残余风险；如无写"无"]
+
+## Follow-Up Routing
+- Task Plan:
+- Progress:
+- Findings:
+- Regression SSoT:
+- Lessons SSoT:
+- Walkthrough:
+```
+
+## Severity 分级
+
+| 级别 | 含义 | 处理规则 |
+|------|------|----------|
+| P0 | 会导致数据损坏、安全事故、生产不可用或错误发布 | 必须停下，不能继续收口 |
+| P1 | 会破坏核心路径、关键契约或主要验收标准 | 必须修复并重跑证据 |
+| P2 | 有明确回归或维护风险，但不阻塞主目标 | 记录并判断是否本轮修复 |
+| P3 | 质量建议、命名、文档或轻微改进 | 可记录为 follow-up |
+
+Material finding 指 P0/P1，以及任何会改变 stop condition 的 P2。
+
+## 状态规则
+
+每条 finding 的 `Status` 使用以下值：
+
+- `open`
+- `fixed`
+- `accepted-residual`
+- `not-reproducible`
+- `out-of-scope`
+
+`accepted-residual` 必须说明为什么不阻塞本轮目标，并路由到后续任务或 SSoT。
+
+## Confidence Loop
+
+Review loop 的固定执行形态：
+
+1. 提出 Confidence Challenge。
+2. 如果不是 100% 有信心，列出所有可能漏洞和证据缺口。
+3. 将会影响 stop condition 的漏洞写入 Material Findings。
+4. 提出具体修复建议，并路由到本轮修复、accepted residual 或后续任务。
+5. 修复后重跑相关证据。
+6. 再次提出 Confidence Challenge。
+7. 直到没有 open material finding，才能写 no-finding statement 或 final confidence basis。
+
+不能把“accepted residual”当作 100% 信心。accepted residual 只表示该风险不阻塞本轮目标，
+仍然必须写明原因和后续路由。
+
+## 与其他文档的关系
+
+- `review-routing-standard.md` 决定 reviewer / subagent / external agent / human review 何时触发
+- `progress.md` 记录审查发生的时间和处理结果摘要
+- `findings.md` 记录审查中产生的技术决策或研究发现
+- `Regression-SSoT.md` 记录新增或调整的 regression surface
+- `Lessons-SSoT.md` 记录可复用的流程、架构或标准改进建议
+- `walkthrough` 收口时引用 `review.md` 的 material finding 状态和 no-finding 结论
+- `Harness Ledger` 记录本轮是否完成 review report
+
+## 停止与收口规则
+
+任务不能在以下状态收口：
+
+- 存在 `open` 的 P0/P1 finding
+- reviewer 没有写 `review.md`，但任务合同要求 review loop
+- Confidence Challenge 缺失，或没有记录 final confidence basis
+- no-finding statement 缺失
+- material finding 修复后没有重跑对应证据
+- accepted residual 没有后续路由
+
+任务可以收口的最低条件：
+
+- P0/P1 全部 `fixed`、`not-reproducible` 或有明确 `out-of-scope` 理由
+- P2 material risk 已修复或 `accepted-residual` 并路由
+- `Evidence Checked` 足以支撑 no-finding 或 residual 结论
+- walkthrough 和 Harness Ledger 已引用 review report

package/references/agents-md-pattern.md

@@ -0,0 +1,140 @@
+# AGENTS.md / CLAUDE.md 入口设计模式
+
+## 核心思路
+
+AGENTS.md 是跨 agent 的 canonical 入口；CLAUDE.md 是 Claude Code 的兼容入口。两者都应该是**目录和宪章**，不是百科全书。
+
+推荐默认生成：
+
+- `AGENTS.md`：唯一事实源，包含硬规则和 Task-Type Reading Matrix
+- `CLAUDE.md`：轻量 shim，只要求 Claude Code 先读 `AGENTS.md`，不复制完整规范
+
+## 反模式：百科全书式
+
+把所有规则塞进一个文件：架构原则、开发规范、测试标准、文档治理、协作纪律、环境配置……
+
+结果：文件越长，agent 表现越差。不相关的约束互相干扰，该关注的重点被淹没。
+
+## 正确模式：宪章 + 索引
+
+AGENTS.md 只包含两类内容：
+
+1. **硬规则（宪章）** — 核心架构原则、绝对不能违反的约束
+2. **导航矩阵（索引）** — 做什么类型的任务，先读哪个文件
+
+### Task-Type Reading Matrix 示例
+
+```markdown
+## Task-Type Reading Matrix
+
+- 架构 / adapter / runtime 相关任务：
+  先读 docs/11-REFERENCE/core-decoupling-standard.md
+
+- 测试 / scenario / 冒烟：
+  先读 docs/11-REFERENCE/testing-standard.md
+
+- 文档治理 / planning / walkthrough：
+  先读 docs/11-REFERENCE/docs-library-standard.md
+
+- Harness Ledger / 上下文回写：
+  先读 docs/11-REFERENCE/harness-ledger-standard.md
+
+- Walkthrough / Closeout / Lessons 收口：
+  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/01-GOVERNANCE/Lessons-SSoT.md 和 docs/10-WALKTHROUGH/Closeout-SSoT.md
+
+- 开发执行 / 回写流程：
+  先读 docs/11-REFERENCE/execution-workflow-standard.md
+
+- Repo governance / PR / branch protection:
+  先读 docs/11-REFERENCE/repo-governance-standard.md
+
+- CI/CD / required checks:
+  先读 docs/11-REFERENCE/ci-cd-standard.md
+
+- 长程任务 / 连续执行 / 子代理审查：
+  先读 docs/11-REFERENCE/long-running-task-standard.md
+
+- 对抗性 review / reviewer 报告：
+  先读 docs/11-REFERENCE/adversarial-review-standard.md
+
+- Reviewer / subagent / 外部审查路由：
+  先读 docs/11-REFERENCE/review-routing-standard.md
+
+- 前端 / UI 任务：
+  先读 docs/11-REFERENCE/frontend-standard.md
+```
+
+### 推荐结构
+
+```
+项目根目录/
+├── AGENTS.md        ← 231 行，canonical 宪章 + 索引
+├── CLAUDE.md        ← 轻量 shim，指向 AGENTS.md
+└── docs/
+    ├── Harness-Ledger.md
+    └── 11-REFERENCE/
+        ├── testing-standard.md
+        ├── execution-workflow-standard.md
+        ├── repo-governance-standard.md
+        ├── ci-cd-standard.md
+        ├── long-running-task-standard.md
+        ├── adversarial-review-standard.md
+        ├── review-routing-standard.md
+        ├── engineering-standard.md
+        ├── frontend-standard.md
+        ├── docs-library-standard.md
+        ├── harness-ledger-standard.md
+        ├── regression-ssot-governance.md
+        ├── walkthrough-standard.md
+        └── ...（按需扩展）
+```
+
+### 行数控制
+
+AGENTS.md 控制在 **100-300 行**。超过 300 行说明有内容应该下沉到 reference 文件。
+
+CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应复制 AGENTS.md 的完整规则，避免两份入口文件漂移。
+
+### 关键设计决策
+
+- agent 做后端重构时，不会被前端规范干扰
+- agent 做测试时，不会被文档治理规则分心
+- 每种任务类型只加载它需要的上下文
+- agent 写 walkthrough 时会被入口显式路由回 Lessons SSoT，但 Lessons 全文不会塞进 AGENTS.md
+
+这跟 OpenAI 在 Harness Engineering 实践中得出的结论一致：给 agent 一张地图，不给一本千页手册。
+
+## 生成 AGENTS.md + CLAUDE.md 的步骤
+
+1. 确认项目的技术栈和主要模块
+2. 确认 `docs/11-REFERENCE/` 下有哪些标准文件
+3. 用 `templates/AGENTS.md.template` 作为 AGENTS.md 起点
+4. 填写项目信息区（项目名、技术栈、仓库结构）
+5. 根据项目模块编写 Task-Type Reading Matrix
+6. 写入硬规则（核心架构约束、绝对不能违反的原则）
+7. 控制 AGENTS.md 总行数在 100-300 行
+8. 用 `templates/CLAUDE.md.template` 生成 CLAUDE.md shim，指向 AGENTS.md
+9. 不要在 CLAUDE.md 中复制完整规范
+
+## 不同项目类型的调整
+
+### 单仓小项目
+- Reading Matrix 可以简化为 3-5 条
+- 硬规则可以更精简
+- 不需要多 agent 协作规则
+
+### Monorepo
+- Reading Matrix 按包/模块分组
+- 每个包可以有自己的 reference 文件
+- 需要跨包依赖规则
+
+### 前后端分离
+- 前端和后端各有独立的 reference 文件
+- Reading Matrix 按前端/后端/共享分组
+- 需要 API 契约规则
+
+### 多人 + 多 Agent
+- 需要协作纪律规则
+- 需要 worktree 命名规范
+- 需要明确 subagent reviewer 与 worker 的区别：worker 必须使用独立 worktree / branch，提交自己的 commit，再由 coordinator 集成
+- 需要 merge 审批流程