> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 文档组织策略

> 本文是一个通用框架：在 AI agent 深度参与开发的团队里，文档应该怎么组织。
> 适用于任何多 repo 项目。新建 repo 或重组文档体系时，以本文作为参考基线。
>
> **读者**：工程师，以及执行 `factory-audit` 的 AI agent。
>
> **两个用途**：
>
> - 工程师参考：了解如何组织文档对 agent 友好，评估现有 repo 是否合规
> - `factory-audit` 标准规范：执行 factory-audit 时，agent 主动读取本文，以此判断 repo 是否符合 Agentic Software Factory 的基础设施要求
>
> 注意：本文不是每次 session 自动加载的文件。`factory-audit` skill 被调用时，会通过 `execution-policy.md` 里的指针主动读取本文。

***

## 一、核心问题

多 repo 项目里，文档通常散乱在三个地方：README、各 repo 的 wiki、一个独立的文档站。这在纯人类开发时勉强够用，但引入 AI agent 之后会暴露三个痛点：

| 角色              | 痛点                                               |
| --------------- | ------------------------------------------------ |
| **设计师**         | 不知道"最新代码实现了什么" — code → design 的信息流断了            |
| **工程师 / Agent** | 不知道去哪里找 tech spec 来执行任务                          |
| **AI Agent**    | 跨 repo 的 feature 设计没有自然落脚点，CLAUDE.md 塞太多内容反而降低质量 |

这三个痛点驱动了完全不同的信息结构需求。

***

## 二、两类文档：发布型 vs 上下文型

这是整个框架的基础前提。**每建一个新文档，先判断它是哪类。**

::: tip 判断标准
**你会把这个文档发给设计师 / 新工程师看吗？**

- 会 → **发布型**：进 nav / 放在 docs repo 的主结构里
- 不会 → **上下文型**：放在 git 里，不发布，给 agent 读

:::

|          | 发布型              | 上下文型                                    |
| -------- | ---------------- | --------------------------------------- |
| **目的**   | 给人类团队成员读         | 给 Claude / AI agent 读                   |
| **内容状态** | 稳定、经过 review     | 可以是草稿、WIP                               |
| **维护成本** | 高，更新需要 PR        | 低，随时修改                                  |
| **典型例子** | 产品功能设计、系统架构、行业知识 | execution-policy、working memory、spec 草稿 |

***

## 三、行业现状

不同规模的团队选择不同方案：

| 规模          | 常见做法                                       | 代表                    |
| ----------- | ------------------------------------------ | --------------------- |
| 小团队（1-5 人）  | docs 和 code 分开，docs 用 GitHub Pages 展示      | Stripe 早期             |
| 中等（10-50 人） | Backstage / Docusaurus 把各 repo 的 docs 聚合展示 | Spotify               |
| 大团队（50+）    | 专属文档平台 + MCP 工具按需注入 context                | Stripe Minions、Notion |

**AI agent 方向的新兴共识（2025-2026）：**

- Feature spec 放代码 repo（Kiro、GitHub spec-kit、StrongDM 的做法）
- CLAUDE.md 保持精简，用 `@import` 或显式链接按需展开（Claude Code 官方推荐）
- 跨 repo 文档集中存放，但必须有从代码 repo 指向它的显式链接

***

## 四、三种方案

### 方案 A：代码驱动（Docs with Code）

每个代码 repo 自带 `docs/plans/`（feature plan）和 `docs/adr/`（本服务决策）。集中文档库缩小为 org 级 ADR + onboarding。

**适合**：服务间独立性强，跨 repo 交互少。
**不适合**：高度跨 repo 的系统（跨服务 feature 没有自然落脚点）。

### 方案 B：集中文档（Centralized Docs）

所有设计文档放集中 docs repo，代码 repo 的 CLAUDE.md 只存本地操作说明 + 指向 docs repo 的链接。

**适合**：有专职文档维护者，或已有 RAG 基础设施。
**不适合**：小团队，文档和代码在不同 repo，容易不同步。

### 方案 C：分层混合（推荐）✅

```
docs repo（战略层）              = 跨 repo 设计 + 产品知识 + org 级决策
代码 repo（战术层）              = feature spec + 本服务 ADR
CLAUDE.md（指针层）              = 精简，只存命令 + 指向文档的链接
execution-policy.md（决策层）    = agent 遇到分叉时的判断规则（全局级）
.claude/working-memory/（记忆层）= 任务中的决策记录，对抗 context 丢失
git-ai（实现历史层）             = 每行代码的 AI session 归因，`/ask` 可查询原始 intent
```

**核心洞察**：问题不是"文档放哪里"，而是"agent 执行任务时能不能发现正确的文档"。解法不是往 CLAUDE.md 里塞内容，而是建立**发现机制**（指针 + 索引）。

***

## 五、分层混合方案详解

### docs repo（战略层）

承载跨 repo 的知识，适合人类和 agent 都读：

```
docs/                                      # MkDocs 发布（human-facing，出现在网站）
├── architecture/
│   ├── system-overview.md                 # 全系统架构：所有 repo 如何协作
│   └── cross-repo-features/               # 已完成的跨 repo 架构文档（稳定后才放这里）
│       └── [feature-name].md              # 不存 in-flight spec，只存已发布的架构决策
├── adr/                                   # Org 级技术决策记录
│   └── 001-xxx.md
├── product/
│   └── changelog.md                       # 产品 changelog（给设计师看）
└── onboarding/
    └── new-engineer.md

.claude/                                   # Agent-facing（不发布，不出现在网站）
├── rules/
│   └── execution-policy.md
├── working-memory/
├── templates/plans/
└── specs/                                 # ★ 进行中的跨 repo feature spec（新增）
    ├── YYYY-MM-DD-[feature]-design.md     # Phase 1 产出（设计决策，你拍板）
    └── YYYY-MM-DD-[feature]-impl.md       # Phase 2 产出（执行计划，agent 消费）
```

**`product/changelog.md` 解决设计师的核心痛点**：

```markdown
## 2026-03
- ✅ [功能名] — 一句人话描述，相关 repo: xxx，PR: #123
- 🚧 [功能名] — 进行中
```

产品视角，不用 `feat/fix` 前缀，用人话。让设计师在 GitHub web UI 就能看到"最新实现了什么"。

**`system-overview.md` 对 Orchestrator Agent 友好的格式要求**：

Orchestrator Agent 会读这个文件来决定把任务分发给哪个 repo。格式必须包含：

```markdown
## Repo 清单

| Repo | 职责 | 技术栈 | 主要入口文件 |
|------|------|--------|-------------|
| callytics-infrastructure | 电话分析 Lambda + CDK | TypeScript/CDK | lambda/*/handler.ts |
| studio-website-monorepo | 前端 Vue + 后端 API | Vue3/Hono | apps/web/src/ |
| ... | ... | ... | ... |

## 服务边界

[哪些事情跨多个 repo，哪些事情只在一个 repo 内完成]

## 跨 repo 数据流

[简要描述主要数据流向，如：RC webhook → callytics-infrastructure → DDB → studio-website]
```

没有这个格式，Orchestrator 就无法自动拆分任务。它不知道把"实现 X feature"分给哪几个 repo。

### 代码 repo（战术层）

存本服务相关的执行文档：

```
[repo-name]/
├── CLAUDE.md                       # 精简：命令 + 指针（不存内容）
│
├── .claude/
│   ├── rules/
│   │   └── execution-policy.md    # 决策规则（agent 自主工作的基础）
│   ├── templates/
│   │   └── plans/                  # ★ 模板统一放这里（所有 repo 一致）
│   │       ├── design.md           # 背景、方案对比、决定、影响范围
│   │       └── impl.md             # 逐步执行计划（含代码、commit 命令）
│   └── working-memory/            # 任务执行中的临时记录（任务完成后删除）
│       └── [task-name].md
│
└── docs/
    └── plans/                      # 实际 plan 文件（日期命名，agent 直接消费）
        ├── YYYY-MM-DD-[feature]-design.md
        └── YYYY-MM-DD-[feature]-impl.md
```

**Spec 放哪里**：

```
所有 repo 统一：spec 文件放 .claude/specs/，不管任务涉及几个 repo
进行中不发布；完成后架构结论可提取到 docs/architecture/cross-repo-features/ 发布

需要写 spec 吗？
├── ≤ 3 个文件 且 ≤ 50 行改动 → 直接 PR，不写 spec
├── hotfix → 直接 PR，事后在 working-memory 补记录
└── 其他场景 → 写 design.md（你 review）→ 写 impl.md（agent 执行）
```

::: warning 覆盖 superpowers `writing-plans` 默认路径
superpowers 的 `writing-plans` skill 默认输出到 `docs/plans/`。**所有 repo 都要在 `execution-policy.md` 里覆盖这个默认值**，改用 `.claude/specs/`。

:::

### CLAUDE.md（指针层）

CLAUDE.md 是 agent 每次 session 自动加载的文件，是**最稀缺的 context 资源**。

规则：

- ✅ 存：构建命令、测试命令、本 repo 的约束规则
- ✅ 存：指向 docs repo 的链接（Cross-Repo Context 段落）
- ❌ 不存：大段设计文档内容（用 `@import` 或链接代替）
- ❌ 不存：其他 repo 的实现细节

### execution-policy.md（决策层）

**这是让 agent 真正自主的关键文件，和 CLAUDE.md 同等重要。**

放在 `.claude/rules/execution-policy.md`，在 CLAUDE.md 里用 `@.claude/rules/execution-policy.md` 引入。

作用：把你的判断预先写成机器可读的规则 — agent 遇到决策分叉时查这个文件，而不是来问你。

**execution-policy.md 和 spec 的区别**：

- spec 是"这个 feature 做什么"（任务级）
- execution-policy 是"遇到任何情况如何决策"（全局级）

### Plan Checkpoint（执行前确认）

**来自 Devin 2.0 的核心设计。防止 agent 花 3 小时跑偏的关键机制。**

不要让 agent 直接从 spec 跳到执行。正确流程：

```
你发任务（提供 requirements.md）
    ↓
Agent 先研究 codebase（不写代码）
    ↓
生成 Plan 给你看（5-10 分钟）：
  "我准备这样做：Step 1... Step 2...
   ⚠️ 我发现：[潜在问题或需要你确认的决策点]
   你想要：A) [方案A]  B) [方案B]  C) 你决定"
    ↓
你 review Plan（5 分钟）→ 确认或修改
    ↓
执行（方向已锁定，不会跑偏）
```

在 requirements.md 里明确写：

```markdown
## Plan Checkpoint
- [ ] Agent 必须在开始写代码前生成执行计划，等待确认
- 例外：任务范围极小（改一个函数），可以跳过
```

> 早期 Devin 的最大问题：会花好几个小时追一个不可能的方案而不升级给人类。解决方案不是更好的 AI，而是加 Plan Checkpoint。

### working-memory（记忆层）

**LLM 每次 session 开始都是空白。30 分钟后 context 被自动压缩，具体细节会丢失。**

working-memory 文件让 agent 把"这次任务发现了什么"写到磁盘，下次 session 或其他 agent 读这个文件就能接着干，不需要从头来。

```markdown
# Working Memory: [任务名]

## 当前进度
- [x] Step 1: 读相关代码
- [x] Step 2: 确定修改点
- [ ] Step 3: 实现
- [ ] Step 4: 写测试

## 已发现的重要信息
- contacts 表的 phone 字段是 VARCHAR(20)，不是 E.164 格式 ← 下次 session 从这里继续
- [其他在代码里发现的关键细节]

## 已做的决定
- 选择了方案 A（加索引），原因：全表扫描在 1M+ 行时会超时

## 遇到的问题 / 待确认
- [ ] contacts 表里同一个 phone 有多条记录，用哪条？→ 需要 Park & Notify 用户
```

***

## 六、与 Meegle + MCP Orchestrator 的结合

当团队成熟后，这套文档结构可以直接对接自动化 orchestration：

```
Meegle（飞书项目）
    ↓ MCP Server（project.larksuite.com/mcp_server/v1）
    ↓ create_workitem / get_node_detail
    ↓
[Orchestrator Agent]
    1. 读 architecture/0-system-overview.md
       → 知道有哪些 repo，每个 repo 的职责边界
    2. 读 .claude/specs/ 里的 feature spec
       → 知道这个 feature 涉及哪些 repo、改什么
    3. 为每个受影响的 repo 生成独立 Plan（design.md + impl.md）
       → 写入各 repo 的 .claude/specs/
    ↓
并行 Worker Agents（git worktree × N，每个 repo 一个）
    每个 Worker：读 Task Spec → Plan Checkpoint → 执行 → CI → PR
    ↓
各自开 PR → Meegle finish_node 自动关闭 work item
```

**这套流程能跑通的三个前提**：

| 前提                                            | 为什么重要                            |
| --------------------------------------------- | -------------------------------- |
| `system-overview.md` 存在且格式正确                  | Orchestrator 靠它理解 repo 边界，才能拆分任务 |
| 每个 repo 的 `CLAUDE.md` 有 Cross-Repo Context 链接 | Worker Agent 才能发现跨服务的设计文档        |
| Feature spec 包含可验证的验收标准                       | Worker Agent 才能自我验证，不需要人工检查每一行   |

**瓶颈不在工具，在文档完整性。**

***

## 七、新 repo 完整配置模板

新建一个 repo，**所有目录和文件应该一次性建好**，内容可以是 placeholder，但结构必须齐全。不要等到"需要的时候再建" — 缺失的结构会让 agent 在不该思考的地方浪费 context。

**所有 repo（worker 和 orchestrator 结构相同）：**

```
[any-repo]/
├── CLAUDE.md                          # agent 每次 session 自动加载
├── README.md                          # 给人类读的入门说明
│
├── .claude/
│   ├── rules/
│   │   └── execution-policy.md        # agent 的决策规则（含 spec 路径规则）
│   ├── working-memory/                # 任务中的决策记录（对抗 context 丢失）
│   │   └── _template.md
│   ├── templates/plans/               # design.md + impl.md 模板（复制用）
│   │   ├── design.md
│   │   └── impl.md
│   └── specs/                         # ★ 所有 spec 文件（进行中，不发布）
│       ├── YYYY-MM-DD-[feature]-design.md
│       └── YYYY-MM-DD-[feature]-impl.md
│
└── docs/                              # 发布内容（docs repo 用 MkDocs，代码 repo 自定义）
    └── adr/                           # 本服务架构决策记录（已完成，稳定后发布）
        └── 000-template.md
```

**`CLAUDE.md` 完整模板：**

```markdown
# [Repo 名]

## 这个 repo 是什么
[一句话说清楚这个服务的职责和边界]

## 构建命令
[安装依赖的命令]
[构建命令]
[测试命令]
[lint / typecheck 命令]

## 部署 / diff 命令（如适用）
[例：cdk diff / wrangler deploy --dry-run]

## 关键文件
- `[入口文件路径]` — [一句话说明]
- `[配置文件路径]` — [一句话说明]

## 绝对不能碰
- `[路径]` — [原因]

## Cross-Repo Context
- 系统全景：[docs repo URL]/architecture/0-system-overview.md
- 跨 repo feature 设计：[docs repo URL]/architecture/cross-repo-features/
- Agentic Factory 操作手册：[docs repo URL]/ai/factory/agentic-software-factory-playbook/
- 相关 feature（按需填）：[具体链接]

@.claude/rules/execution-policy.md
```

**`.claude/rules/execution-policy.md` 完整模板：**

```markdown
# Autonomous Execution Policy — [Repo 名]

## 遇到不确定时的决策顺序
1. 先看本文件有没有覆盖这个场景
2. 参考 conversation history（`~/.claude/projects/[project]/` JSONL）了解负责人的决策偏好
3. 看现有代码里同类问题怎么解决（以现有代码为范本）
4. 有设计含义的决策（影响多文件、架构选择）→ 考虑 long-term 影响与可维护性，在 PR 里说明理由
5. 绝不因为不确定就停下来问用户

## Factory 标准规范
- 如果你是在执行 factory-audit：读 https://github.com/retaintive/docs/blob/main/docs/ai/factory/doc-structure-for-agents.md 了解合规标准

## 技术选型（已决定，直接按这个做）
- 数据持久化：[你的选择]
- 跨服务通信：[你的选择]
- 测试框架：[你的选择]

## Spec 文件位置
所有 spec 文件统一放 `.claude/specs/`，不管任务涉及几个 repo。superpowers `writing-plans` 默认路径是 `docs/plans/`，覆盖它改用 `.claude/specs/`。

## 遇到这些情况直接决定，不用问我
- [常见分叉 1，例如："字段类型不确定 → 用 string"]
- [常见分叉 2]

## 遇到这些情况 Park & Notify 我
- 需要改 prod 环境配置
- 发现设计文档有矛盾
- 影响超过 2 个 repo 的架构变更
- [其他你想被告知的情况]

## 验证步骤（必须全部通过才能开 PR）
1. [unit test 命令]
2. [lint/typecheck 命令]
3. [integration test 命令（如有）]

## 重试策略
- 测试失败 → 自己修，最多 3 次
- 第 4 次失败 → 开 Draft PR，标注卡点，通知用户

## Circuit Breaker
- 单任务超过 20 个 AI turns → 停止，Park & Notify
- 同一个错误连续出现 3 次 → 停止，Park & Notify
```

**`.claude/templates/plans/design.md` 模板：**

文件命名规范：`YYYY-MM-DD-[feature]-design.md`（复制模板后重命名）

````markdown
# Design: [Feature 名称]

**Date**: YYYY-MM-DD
**Status**: Draft — Pending Review
**Issue/Ticket**: [link]
**Scope**: [受影响的主要文件，逗号分隔]

---

## 背景

[2-3 段，说明为什么要做这个。必须链接到相关设计文档的具体章节，不能只写 docs repo 根目录]

- 相关文档：[docs repo URL]/[具体路径]#[具体章节锚点]

### 核心问题

[具体描述要解决的问题，可以用 bullet list]

---

## 方案对比（如有多个选项）

### 方案 A：[名称]

[一段描述]

```typescript
// 关键代码片段（可选，帮助理解方案）
````

**优点**：...
**缺点**：...

### 方案 B：\[名称]

\[一段描述]

**优点**：...
**缺点**：...

### 评估

| 维度      | 方案 A | 方案 B |
| ------- | ---- | ---- |
| \[复杂度]  |      |      |
| \[影响范围] |      |      |
| \[可维护性] |      |      |

***

## 决定

选择方案 X，原因：\[...]

***

## 影响范围

| 文件     | 改动性质         |
| ------ | ------------ |
| `[路径]` | 新增 / 修改 / 删除 |

**不改的文件（及原因）**：

- `[路径]` — \[原因]

````

**`.claude/templates/plans/impl.md` 模板：**

文件命名规范：`YYYY-MM-DD-[feature]-impl.md`（复制模板后重命名）

```markdown
# Implementation: [Feature 名称]

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** [一句话描述目标]

**Architecture:** [实现架构说明，说清楚数据流和关键设计决策]

**Tech Stack:** [框架、SDK、测试工具]

---

## Context & Invariants

- `[组件/文件/环境变量]` — **[不变 / 被删除 / 被替换，说明原因]**
- `[组件/文件]` — **[unchanged, already works]**

## Files Changed

| File | Change |
|------|--------|
| `[路径]` | [改什么] |

---

## Task 1: [任务名称]

**Files:**
- Modify: `[路径]`

**Step 1: [步骤描述]**

In `[文件]`, [位置说明]:

```typescript
// 完整代码片段
````

Expected: \[预期结果，例如：`package.json` 有新依赖，tests pass]

**Step 2: ...**

**Commit:**

```bash
git add [files]
git commit -m "[type]([scope]): [description]"
```

***

## Task 2: \[任务名称]

...

***

## Final Verification

```bash
[测试命令]
[lint/typecheck 命令]
[diff 命令（如适用）]
```

Expected: All checks pass, no resource replacement.

```

---

## 参考

- [Stripe Minions（Agentic Factory 最详细的工程实践）](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)
- [StrongDM Software Factory（最激进的无人工 review 实践）](https://factory.strongdm.ai/)
- [Kiro — feature spec 放代码 repo 的模式](https://kiro.dev)
- [Claude Code CLAUDE.md 官方建议](https://docs.anthropic.com/en/docs/claude-code/claude-md)
- [Agentic Software Factory — 完整参考](agentic-software-factory.md)
- [Agentic Software Factory — 操作手册](agentic-software-factory-playbook.md)
```