# FF AI Workspace 文档系统规则

> **版本**: v3.0
> **最后更新**: 2026-04-06

---

## 1. 写作原则（AI-first）

> **文档写决策和约束，不写操作步骤。操作交给 AI 和 skills。**

| 原则 | 说明 |
|------|------|
| **写决策，不写操作** | 写”为什么选 Temporal”，不写”怎么启动 Temporal”。操作步骤做成 skill |
| **写约束，不写代码能表达的** | 写”Controller 不放业务逻辑”，不写 `@Controller` 示例。版本看 `package.json`，结构看 schema 文件 |
| **写 AI 推断不出的** | 业务规则、架构决策的”为什么”、跨模块隐含约束 |
| **一个事实只存一处** | 代码能查到的不重复到文档；文档和代码冲突以文档为准 |
| **面向 AI 可消费** | 表格优于叙事、短文档优于长文档、明确”做/不做”优于模糊描述 |

### 判断标准

写文档前问两个问题：
1. **这个信息能从代码/配置/命令输出中获得吗？** — 能 → 不写
2. **AI 遇到这个场景时，能自己解决吗？** — 能 → 做成 skill，不写文档

---

## 2. 目录结构

```
docs/
├─ modules/          # 模块文档（业务契约）
├─ standards/        # 开发规范（架构决策、流程规则）
├─ ops/              # 运维文档（部署策略、服务器配置）
│   └─ archive/      # 已归档的临时记录
└─ README.md         # 文档中心
```

---

## 3. 模块文档结构（必须遵守）

### 必需（7）
- `README.md`
- `01-prd.md`
- `03-architecture.md`
- `05-ui-interaction-spec.md`
- `06-data-model.md`
- `07-api.md`
- `09-test-scenarios.md`

### 推荐（4）
- `02-user-journey.md`
- `04-state-machine.md`
- `08-error-codes.md`
- `10-e2e-test-spec.md`

### 可选（2）
- `11-roadmap.md`
- `99-changelog.md`

---

## 3.1 需求管理文档结构（必须遵守）

### 必需（1）
- `README.md`

### 需求明细（按需）
- `items/REQ-XXXX.md`

### 变更记录（按需）
- `changes/REQ-XXXX.md`

---

## 4. 依赖顺序（权威阅读顺序）

1. PRD → 2. User Journey → 3. Architecture → 4. State Machine → 5. UI Spec → 6. Data Model → 7. API → 8. Error Codes → 9. Test Scenarios → 10. E2E Spec

> 修改任一文档，必须先阅读其上游依赖。

---

## 5. 规则与约束

- **规则优先级**：全局规则（`AGENTS.md` / `CLAUDE.md`）> 模块 PRD 边界规则（`01-prd.md` Always/Ask/Never）> 技能执行细则（`SKILL.md`）。冲突时高优先级覆盖低优先级
- **单一事实来源**：同一规则只能在一个地方定义
- **模板参考**：文档模板在对应技能的 `references/` 目录中（模块文档 → `docs-main`，测试报告 → `test-backend`，E2E 规范 → `test-frontend`）。AI 根据 §6 的最小定义直接生成文档，不需要模板文件
- **命名固定**：文档文件名与编号不得随意改动
- **文档优先**：文档与代码冲突时，以文档为准并停止执行
- **统一可读性**：文档默认同时面向 AI 与人类阅读，不再使用”机器读取区 / 人类阅读区”二分结构；应使用自然、语义化的章节标题组织内容

---

## 6. 文档类型最小定义

| 文档 | 核心约束 |
|------|---------|
| README.md | 模块目标、文档导航（含"何时读取"路由）、当前状态 |
| 01-prd | 功能边界（In/Out）、核心业务约束、角色权限矩阵、边界规则（Always/Ask/Never） |
| 02-user-journey | 角色场景表（用户操作→系统响应），异常分支覆盖（校验+权限+并发） |
| 03-architecture | 架构摘要、分层边界、当前控制器/服务/页面结构表、实施阶段 |
| 04-state-machine | 状态列表、合法流转（守卫条件+错误码引用 08）、异常路径 |
| 05-ui-interaction-spec | 页面清单、页面状态规范（加载/空/无权限/错误态）、API 调用约束 |
| 06-data-model | 实体、字段、关系、约束 |
| 07-api | 端点、请求/响应类型、权限、错误码引用 |
| 08-error-codes | 按业务域分组的错误码表（码/HTTP 状态/触发条件/处理建议） |
| 09-test-scenarios | "测什么"——场景表（ID/类型/输入/期望输出），按正常/异常/权限/边界分类 |
| 10-e2e-test-spec | "怎么测"——流程编排剧本（角色/步骤/依赖/断言），L2 MCP 主驱动 |

> 每条信息只在一个文件中定义，其他文件通过引用指向权威位置。


### 6.1 最小填写原则

- 每类文档只要求最小必填项，避免模板化堆砌。
- 如果某类信息对当前阶段不重要，可省略”如需”章节，但必填项不能空。
- 如果文档尚未完整，应明确标注 Draft / Need Update，而不是留空字段。
- 必填项优先使用表格或短列表，降低 AI 和人类的阅读成本。

### 6.2 元数据头规范

每份模块文档（README 除外）应在标题下方包含以下元数据头，用于路由、检索和自动校验：

```markdown
> **module**: {模块名}
> **doc_type**: PRD / UserJourney / Architecture / StateMachine / UISpec / DataModel / API / ErrorCodes / TestScenarios / E2ESpec / Roadmap
> **status**: Draft / Review / Active / Deprecated
> **owner**: {负责人/团队}
> **upstream_docs**: {上游依赖文档列表，如 “01-prd.md, 04-state-machine.md”}
> **last_verified**: YYYY-MM-DD
```

- `upstream_docs` 按 §4 依赖顺序列出本文档的直接上游，便于 lint 校验引用链
- `last_verified` 记录最后一次人工确认文档与代码一致的日期
- README.md 不需要此头，它本身就是路由索引

---

## 7. 文档 lint 检查规则

以下检查项应在文档变更后执行（可手动或通过 CI 自动化）：

| 检查项 | 说明 |
|--------|------|
| 必填章节完整性 | 每个文档必须包含其模板中的必填章节（非"如需"章节） |
| 元数据头完整性 | `module`、`doc_type`、`status`、`owner`、`upstream_docs`、`last_verified` 六个字段不能为空 |
| 交叉引用存在性 | 文档中引用的其他文档路径必须实际存在 |
| 04 → 08 错误码一致 | `04-state-machine.md` "违反时错误"列引用的错误码必须在 `08-error-codes.md` 中定义 |
| 09 覆盖 01 验收标准 | `09-test-scenarios.md` 的场景应覆盖 `01-prd.md` 验收标准中的所有条目 |
| 10 引用 09 关键场景 | `10-e2e-test-spec.md` 的流程应覆盖 `09-test-scenarios.md` 中 P0 场景 |
| 禁用标记清理 | 不得包含"机器读取区"或"人类阅读区"旧分区标记 |
| upstream_docs 合法性 | 元数据头中的 `upstream_docs` 文件必须实际存在于同目录 |

> 以上规则定义检查逻辑，具体的 CI 脚本或手动检查流程按项目需要实现。

---

## 8. 与 Skills 的关系

- 标准文档作为权威来源，同时面向 AI 与人类阅读
- 机器可执行规则与流程入口应放在对应 Skills，但不得将事实源从 `docs/` 搬入 Skills
- Skills 必须引用本文件作为结构与命名的权威依据