在AI开发的年代，文档工程是越来越重要了。
过去的项目代码主要由人编写，项目目标到实现细节都在人脑子里，只要记性好，你几乎不需要写文档。
现在很多代码都是由AI来完成，程序员的角色逐渐往产品经理走，文档成了另一种编程语言，而实现代码成了某种“汇编”，文档如何组织就越来越重要了。
这篇文档是我跟AI讨论出来的，也参考了最近的deepseek-harness项目，算是一个“如何写文档的文档”。

AI 协作项目的文档管理模式

本文定义一套适用于人与 AI 协作开发的软件文档管理方法。

目标不是“写更多文档”，而是：

• 把不同层级的项目约束放在正确的位置；
• 明确哪些内容属于产品决策，哪些属于实现自由；
• 避免同一规则散落在多个文件；
• 让 AI 能快速找到与当前任务相关的上下文；
• 让关键约束尽可能能够通过测试、Lint 或 CI 验证；
• 随着项目增大，仍然能维持稳定的架构和产品意图。

示例项目假设为一个简单的 Linux 管理系统：

Linux Manager

- 管理配置文件
- 查看系统服务
- 启停和重载服务
- 查看日志
- 执行备份与恢复

---

1. 核心原则

项目文档不是一个“大说明书”，而是多个不同层级的契约。

推荐按以下层级组织：

Product
    ↓
User Contracts
    ↓
System Contracts
    ↓
Architecture
    ↓
Features
    ↓
Workflows
    ↓
Patterns
    ↓
Decisions
    ↓
Implementation
    ↓
Verification

越靠上：

越稳定
越接近产品意图
越应该由人决定
越不应该由 AI 随意修改

越靠下：

越接近实现
越容易变化
越可以交给 AI 自由设计

基本原则：

先约束“系统应该是什么”和“必须怎样表现”，最后才约束“代码具体怎么写”。

---

2. 推荐目录结构

一个中等规模项目可以采用：

docs/
├── README.md
├── design.md
├── architecture.md
├── development.md
│
├── contracts/
│   ├── cli.md
│   ├── config.md
│   ├── api/
│   └── ui.md
│
├── features/
│   ├── files.md
│   ├── services.md
│   ├── logs.md
│   └── backup.md
│
├── workflows/
│   ├── edit-validate-reload.md
│   └── backup-and-restore.md
│
├── patterns/
│   ├── atomic-file-write.md
│   ├── process-execution.md
│   ├── error-handling.md
│   └── path-resolution.md
│
├── decisions/
│   └── ...
│
└── generated/
    ├── module-graph.md
    ├── routes.md
    └── config-schema.md

项目根目录另外保留：

AGENTS.md

它不是详细文档，而是 AI 的入口和导航。

---

3. design.md：产品概设

回答：

这个系统是什么？

这里写整个项目最稳定的定义。

例如：

Linux Manager 是一个轻量 Linux 管理工具。

它允许用户：

- 管理指定配置文件；
- 查看和控制系统服务；
- 查看服务日志；
- 创建和恢复备份。

它不是：

- 完整服务器控制面板；
- 通用 Shell；
- IDE；
- 自动运维平台。

同时定义核心概念：

Host
├── Config
├── Service
├── Log
└── Backup

这一层不应该出现：

Go interface
HTTP handler
Vue component
数据库表
具体 package

design.md 应该稳定。

如果实现重构一次就要改 design.md，通常说明它写得太底层了。

---

4. contracts/：外部契约

Contract 描述的是：

系统对外承诺什么？

它们属于项目最重要的稳定边界。

---

4.1 CLI Contract

例如：

linuxmgr service status nginx
linuxmgr service restart nginx

linuxmgr config check
linuxmgr backup create

应定义：

命令
参数
flag
输出
错误
exit code

例如：

linuxmgr service restart nginx

Success:
  exit code = 0

Service does not exist:
  exit code = 2

Restart failure:
  exit code = 1

不规定内部调用 systemctl 还是其他实现。

---

4.2 Config Contract

例如：

services:
  - name: nginx
    type: systemd
    target: nginx

configs:
  - name: nginx
    path: /etc/nginx

Config 文档定义：

字段
类型
默认值
必填项
合法性
兼容性

配置格式最好进一步拥有机器可读 Schema。

---

4.3 API Contract

如果系统有 Web UI：

Frontend
    ↓ HTTP
Backend

API 文档定义：

endpoint
request
response
error
status code
serialization

例如：

POST /api/services/{id}/restart

Response:

{
  "status": "running"
}

能使用 OpenAPI 时，优先让 API contract 可验证。

---

4.4 UI Contract

UI 不需要完全靠文字表达。

推荐组合：

Prototype / Screenshot
+
Interaction Rules
+
State Definitions

例如：

Service row:

name
status
restart
stop
logs

再规定：

running:
    显示 Stop / Restart

stopped:
    显示 Start

operation pending:
    action disabled

operation failed:
    显示错误

视觉需求优先使用原型和截图。

---

5. architecture.md：系统结构

回答：

代码允许怎么组织？

Architecture 不描述每个功能怎么实现，而描述：

模块
层级
依赖方向
系统边界
禁止依赖

例如：

                   workflows
                /      |       \
               ▼       ▼        ▼
            files   services   backup
               \       |        /
                \      |       /
                   platform

规则：

Feature → Platform
    allowed

Workflow → Feature
    allowed

Feature → unrelated Feature
    default forbidden

Platform → Feature
    forbidden

Architecture 最重要的不是：

谁依赖谁。

而是：

谁绝对不能依赖谁。

这些禁止规则应尽可能进入自动检查。

---

6. features/：纵向功能契约

Feature 回答：

一个功能模块负责什么？

例如：

features/services.md

可以采用统一模板。

Responsibility

负责系统服务的查询和控制。

Owns

service state
start
stop
restart
reload

Does Not Own

配置文件修改
日志存储
备份
HTTP transport
UI layout

Capabilities

GetStatus
Start
Stop
Restart
Reload

Dependencies

Process execution
Service manager adapter

Invariants

不存在的服务不能执行操作。

Restart 不修改配置。

查询状态不得产生系统副作用。

Feature 文档是 AI 开发时非常关键的上下文。

它主要防止：

模块职责扩散
重复实现
跨模块偷调用
业务规则散落

---

7. workflows/：跨 Feature 动作链

Workflow 回答：

一个用户行为跨多个 Feature 时，具体按什么顺序执行？

例如：

workflows/edit-validate-reload.md

可能涉及：

Files
Services

流程：

Write config
    │
    ├── failed → WriteError
    │
    ▼
Validate config
    │
    ├── failed → ValidationError
    │
    ▼
Reload service
    │
    ├── failed → ReloadError
    │
    ▼
Success

同时定义关键语义：

文件写入失败：
    不执行 validate。

Validate 失败：
    不执行 reload。

Reload 失败：
    已写入的文件保持写入状态。

因此：

Workflow 定义的是“这件具体事情怎么走”。

它通常对应一个明确用户场景。

---

8. patterns/：跨 Feature 的通用实现规则

Pattern 回答：

这一类问题在整个项目中统一怎么处理？

Pattern 与 Workflow 完全不同。

例如：

patterns/atomic-file-write.md

定义所有模块保存重要文件时统一使用：

write temporary file
        ↓
flush
        ↓
rename
        ↓
cleanup

再例如：

patterns/process-execution.md

规定：

所有子进程：

- 必须设置 timeout；
- stdout/stderr 必须捕获；
- 不允许 shell 拼接未经验证的参数；
- exit code 必须转换为统一错误模型；
- cancellation 必须终止子进程。

Pattern 通常会被多个 Feature 使用：

Files
Backup
Services

都可能依赖同一个 Pattern。

因此：

Workflow = 某一件具体业务怎么走。
Pattern = 一类实现问题统一怎么处理。

---

9. decisions/：保存“为什么”

代码通常只能告诉后来者：

现在是什么样。

但很难告诉：

为什么当初这样设计？

这就是 Decision 文档的用途。

例如：

decisions/
2026-08-use-systemd-and-docker-only.md

内容可以很短：

Decision

第一版只支持：

- systemd
- Docker

不提供任意 shell service backend。


Reason

这两种系统都提供统一：

- status
- start
- stop
- restart
- logs

任意 shell backend 会扩大能力边界，并导致状态语义不统一。


Rejected

generic command adapter


Reconsider when

出现第三种真实 service backend。

Decision 特别适合 AI 项目。

否则未来 AI 很容易看到现有设计后说：

“这里可以抽象得更通用。”

然后重新引入一个已经被明确拒绝的方案。

---

10. Behavior：复杂功能继续向下描述

不是每个 Feature 都需要独立 Behavior 文档。

通常直接写在 Feature 或 Workflow 内即可。

只有复杂时再拆。

常见表达有：

Concepts
Operations
Invariants
Decision Tables
State Machines
Errors
Examples

---

10.1 Concepts

使用语言无关的类型表达：

type Service = {
    id: string
    name: string
    manager: ServiceManager
}

enum ServiceManager {
    systemd
    docker
}

不要过早加入：

pointer
receiver
async
context.Context

这些属于实现语言。

---

10.2 Operations

例如：

RestartService(
    serviceId: string
) -> ServiceStatus | ServiceError

并补：

Preconditions:

- service exists

Effects:

- service process may change

Does not:

- modify configuration

---

10.3 Invariants

例如：

A service query must never mutate system state.

A managed file path must stay inside its configured root.

A backup must never silently overwrite an existing backup.

这些是非常强的 AI 约束。

---

10.4 Decision Table

多条件规则优先用表格。

例如：

exists	running	action	result
false	-	restart	NotFound
true	true	restart	restart
true	false	restart	start or restart according to manager contract

它比复杂自然语言更容易检查遗漏。

---

10.5 State Machine

有明显生命周期时使用。

例如：

Idle
 │ start
 ▼
Starting
 ├── success → Running
 └── failure → Failed

Running
 │ stop
 ▼
Stopping
 ├── success → Stopped
 └── failure → Failed

状态机非常适合：

UI
异步任务
连接
后台进程
编辑器
部署流程

---

10.6 Examples

当一个规则很难解释时，优先增加实例。

例如：

Configured root:

/etc/nginx

合法：

nginx.conf
→ /etc/nginx/nginx.conf

合法：

sites/a.conf
→ /etc/nginx/sites/a.conf

非法：

../../etc/passwd
→ OutsideRoot

Examples 是成本最低、效果最好的规格之一。

---

11. Implementation Contract：什么时候才写 Interface

只有在真正需要时才规定：

interface
package
class
function
component

例如存在：

Systemd
Docker

两种实现时，可以定义：

ServiceManager

Status
Start
Stop
Restart
Reload
Logs

然后再映射到某种语言：

type ServiceManager interface {
    Status(...)
    Start(...)
    Stop(...)
    Restart(...)
}

但不要为了“控制 AI”而提前规定所有 interface。

否则很容易出现：

Repository
RepositoryImpl

Service
ServiceImpl

Manager
ManagerImpl

Factory
Adapter

这种没有实际价值的抽象。

判断标准：

需要稳定模块边界、多实现替换或测试隔离时，再规定 interface。

---

12. development.md：项目如何工作

回答：

如何开发这个仓库？

通常包含：

运行环境
依赖版本
安装
开发启动
build
lint
test
codegen
目录说明

例如：

Backend:
    Go 1.x

Frontend:
    Node
    pnpm

Commands:

make dev
make build
make test
make check

不要让每个 Agent 每次重新猜：

怎么启动
怎么测试
什么命令是权威

---

13. generated/：机器事实

某些信息不要人工维护。

例如：

module dependency graph
HTTP route list
config schema
database schema
event map

它们应该尽可能由代码生成。

例如：

generated/module-graph.md

回答：

实际代码现在是怎么依赖的？

而：

architecture.md

回答：

它应该怎么依赖？

两者结合才能发现架构漂移。

---

14. AGENTS.md：AI 的入口，而不是百科全书

AGENTS.md 应该尽量短。

它主要负责：

项目原则
禁止事项
必须执行的检查
文档导航
AI 工作方式

例如：

Before changing service behavior:
    read docs/features/services.md

Before changing file handling:
    read docs/features/files.md
    read docs/patterns/atomic-file-write.md

Before cross-feature changes:
    read relevant workflow.

Before architectural changes:
    read docs/architecture.md
    create/update a decision record.

以及：

Task is not complete until:

make check

passes.

不要把所有 Feature 内容复制进 AGENTS.md。

否则：

AGENTS.md

会越来越长，并且产生多个事实来源。

---

15. 文档所有权

每种信息应该只有一个权威位置。

例如：

产品定义
    → design.md

CLI 行为
    → contracts/cli.md

配置格式
    → contracts/config.md

模块边界
    → architecture.md

服务模块行为
    → features/services.md

跨模块动作
    → workflows/

通用实现原则
    → patterns/

为什么做某项设计
    → decisions/

不要：

design.md
architecture.md
AGENTS.md
README.md

四个地方都重复描述同一条规则。

正确做法：

一个地方定义
其他地方引用

---

16. 文档应该写到什么程度

一个重要原则：

只有当 AI 存在现实概率产生“代码可以运行，但不是我们想要的东西”时，才增加规格。

因此按照需要逐层深入。

---

Level 1：Product

只需要知道系统是什么：

design

够了。

---

Level 2：External Contract

用户或其他系统会依赖：

CLI
Config
API
UI

写成稳定契约。

---

Level 3：Architecture / Feature

当项目开始模块化：

Architecture
Feature ownership
Dependencies
Invariants

写清楚。

---

Level 4：Behavior

如果 AI 经常猜错：

状态
条件
错误
流程
边界

增加：

state machine
decision table
workflow
examples

---

Level 5：Implementation

只有确有必要时规定：

interface
function signature
package structure

否则允许实现自由。

---

17. 文档与测试的关系

最强的文档不是 Markdown，而是能够被验证的规则。

因此逐渐把文档映射到：

Design
    → 人类 review

API
    → OpenAPI contract tests

Config
    → Schema validator

Architecture
    → dependency checks

Feature invariants
    → unit / integration tests

Workflow
    → acceptance tests

UI state
    → Playwright / component tests

Patterns
    → lint / shared implementation / tests

理想状态：

Documentation
      ↓
Machine-checkable rule
      ↓
CI

而不是：

Documentation
      ↓
希望 AI 记得

---

18. 文档变更规则

代码修改时，不应该默认修改所有文档。

可以采用：

实现细节变化
    → 通常只改代码

公开行为变化
    → 修改 Contract

Feature 语义变化
    → 修改 Feature

跨模块流程变化
    → 修改 Workflow

通用实现原则变化
    → 修改 Pattern

架构边界变化
    → 修改 Architecture

设计理由发生重要变化
    → 新增 Decision

不要为了保持“文档同步”而把实现细节大量写进高级文档。

---

19. Decision 的生命周期

Decision 可以具有简单状态：

proposed
accepted
rejected
superseded

例如：

DEC-003 Generic Service Backend

Status:
Rejected

未来如果重新讨论：

不要删除旧记录。

创建：

DEC-011 Introduce OpenRC Backend

然后写：

Supersedes:
DEC-003

这可以保留项目演化过程，尤其能防止 AI 重复走已经走过的弯路。

---

20. 不要过度文档化

以下情况通常不值得写独立文档：

简单 helper
普通 CRUD
显而易见的代码
只被一个函数使用的内部算法
语言本身已经清楚表达的内容

不要为每个 package 建：

README.md
architecture.md
interface.md
design.md

文档规模应该跟项目复杂度增长，而不是提前铺满空壳。

---

21. 判断某项内容放哪里的简单问题

遇到一条新规则时，可以依次问：

它解释“为什么做这个产品”吗？

放：

design.md

用户或外部系统会依赖吗？

放：

contracts/

它定义代码的模块边界吗？

放：

architecture.md

它只属于一个功能吗？

放：

features/

它描述多个 Feature 完成一个具体动作吗？

放：

workflows/

它是多个 Feature 都应该遵循的通用做法吗？

放：

patterns/

它主要解释“为什么这样决定”吗？

放：

decisions/

它只是事实，而且可以从代码推导吗？

放：

generated/

它已经到了 Go / Rust / TypeScript 具体结构吗？

优先考虑：

直接让代码表达

除非这是必须长期稳定的 Implementation Contract。

---

22. 一套推荐的 AI 工作流程

Agent 接到任务：

“增加服务日志功能”

首先读取：

AGENTS.md

docs/design.md             # 必要时
docs/architecture.md
docs/features/logs.md
docs/features/services.md  # 如果相关
docs/contracts/api/...     # 如果修改 API

如果涉及：

日志进程读取

再读取：

docs/patterns/process-execution.md

如果是跨模块：

Service → Logs → UI

检查：

docs/workflows/

如果需要改变模块边界：

先修改 architecture
+
创建 decision

完成代码后：

make check

然后确认：

Contract 是否变化？
Feature 是否变化？
Workflow 是否变化？
Pattern 是否变化？
Decision 是否需要记录？

最后才完成任务。

---

23. 最终模型

可以把整个体系看成：

                    Human Intent
                         │
                         ▼
                    design.md
                         │
                         ▼
                External Contracts
               CLI / Config / API / UI
                         │
                         ▼
                  architecture.md
                         │
                         ▼
                     Features
                  /      |      \
                 ▼       ▼       ▼
              Files   Services  Backup
                  \      |       /
                   ▼     ▼      ▼
                     Workflows
                         │
                         ▼
                      Patterns
                         │
                         ▼
                    Implementation
                         │
                         ▼
                      Tests / CI

旁边还有：

Decisions
    记录为什么

Generated Docs
    记录代码事实

AGENTS.md
    告诉 AI 去哪里找

---

24. 最重要的几个规则

如果只记住几条，可以记：

1. Design 定义产品，不定义代码。
2. Contract 定义外部承诺。
3. Architecture 定义模块边界和禁止依赖。
4. Feature 定义纵向职责和不变量。
5. Workflow 定义具体跨 Feature 动作链。
6. Pattern 定义跨 Feature 的通用实现方法。
7. Decision 保存“为什么”，防止未来重复推翻。
8. 可以从代码生成的事实不要人工维护。
9. 复杂行为优先用状态机、决策表、实例，而不是长篇自然语言。
10. Interface 是最后一级约束，不要太早设计。
11. 能被机器验证的规则最终进入测试、Lint 或 CI。
12. AGENTS.md 是导航和规则入口，不是项目百科。

最终目标不是让 AI 阅读更多文字。

而是让它面对一个这样的代码库：

产品意图有明确来源
外部接口有稳定契约
模块之间有边界
每个功能有所有权
跨模块行为有明确流程
重复问题有统一模式
重要决定有历史
实现拥有适当自由
错误能够被自动检查

到了这个程度，人与 AI 的合作方式就不再是：

人不停解释
AI 不停猜
人不停纠正

而逐渐变成：

人维护意图和边界
        ↓
AI 根据规格实现
        ↓
机器验证硬规则
        ↓
人只处理真正需要判断的问题