文档组织策略 — Agentic Software Factory

本文是一个通用框架：在 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 上下文型

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

判断标准

你会把这个文档发给设计师 / 新工程师看吗？ - 会 → 发布型：进 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 解决设计师的核心痛点：

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

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

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

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

## 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 执行）

覆盖 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 里明确写：

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

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

working-memory（记忆层）

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

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

# 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/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 完整模板：

# [Repo 名]

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

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

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

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

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

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

@.claude/rules/execution-policy.md

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

# 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/agentic-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（复制模板后重命名）

# 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:

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

---

Task 2: [任务名称]

...

---

Final Verification

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

Expected: All checks pass, no resource replacement. ```

---

参考

• Stripe Minions（Agentic Factory 最详细的工程实践）
• StrongDM Software Factory（最激进的无人工 review 实践）
• Kiro — feature spec 放代码 repo 的模式
• Claude Code CLAUDE.md 官方建议
• Agentic Software Factory — 完整参考
• Agentic Software Factory — 操作手册