# 从 DigestDesk 复盘：不同规模的 AI 项目，文档应该怎么设计？

发表于

从 DigestDesk 复盘：不同规模的 AI 项目，文档应该怎么设计？

副标题

从 AGENTS.md、OpenAI Codex、Amp、Claude Code、GitBook 和 Mastra 的 AI-native 文档建议出发，解释为什么 DigestDesk 没有继续保留 600 行的大型架构文档，而是选择了 AGENTS.md + context.md + history.md 的轻量协作模型。

正文

AI coding agent 参与开发之后，项目文档的目标变了。

过去，文档主要是给人看的：README 介绍项目，architecture 解释系统设计，operations 说明部署，history 记录背景。但 AI agent 需要的不是完整叙事，而是能够立刻指导行动的上下文：

  • 这个项目怎么运行？
  • 哪些命令可以用？
  • 哪些链路不能破坏？
  • 最近改了什么？
  • 今天要验证什么？
  • 如果我正在改某个子系统，需要读哪份更具体的规则？

这次 DigestDesk 的复盘，就是围绕这个问题展开的。

我们最初有一份 631 行的 docs/architecture.md。它内容完整，但对 Agent 来说并不高效。它更像“给人读的系统说明书”，而不是“给 AI 执行任务用的操作上下文”。最终，我们把它压缩成 150 行的 docs/context.md，并保留 AGENTS.md 和 docs/history.md 作为 AI 协作的核心入口。

这个决定不是简单删文档，而是把文档从“解释型”改成“可执行型”。

AI-native 官方建议：不同规模项目应该怎么做？

1. 小项目：一个 AGENTS.md 就够了

AGENTS.md 官方站点把它定义为：

README for agents.

也就是说，README.md 给人看，AGENTS.md 给 AI agent 看。

对于小项目，最简单的结构通常是：

1
2
README.md
AGENTS.md

AGENTS.md 里放：

  • 项目概览；
  • 安装命令；
  • build/test/lint 命令；
  • 代码风格；
  • 安全注意事项；
  • 常见坑。

这种模式适合单服务、单语言、规则较少、没有复杂调度或多租户边界的项目。小项目不需要很多 rules，也不需要长篇 context.md，因为 Agent 读一个短 AGENTS.md 就能安全工作。

2. 中型项目：AGENTS.md 做路由，docs 存上下文

OpenAI Codex 和 Amp 都把 AGENTS.md 作为项目级指导文件。Codex 支持从项目根目录向下读取多层 AGENTS 文件；Amp 也把 AGENTS.md 用于项目结构、build/test 命令、约定和常见坑。

这类工具的共同方向不是“一个巨型文档”，而是：

1
2
AGENTS.md
docs/*.md

其中：

1
2
3
4
5
6
7
8
9
10
11
AGENTS.md
= 每次都要读的规则

docs/context.md
= 需要理解系统边界时读

docs/operations.md
= 部署/运行问题时读

docs/history.md
= 最近修改和决策记忆

这种模式适合有前后端、数据库、后台任务、非显性业务规则，以及多次迭代后积累了历史决策的项目。

对这类项目，AGENTS.md 不应该写得很长。它应该负责指路：如果你改 digest 链路，读 context；如果你排查部署，读 operations；如果你做非 trivial 修改，读 history 最新部分。

3. 大型项目：多层 AGENTS.md / rules / skills

当项目变大，Claude Code、Amp、OpenAI Codex 这类工具都会引导你把上下文拆开。

大型项目可能长这样：

1
2
3
4
5
6
7
8
9
AGENTS.md
services/api/AGENTS.md
services/web/AGENTS.md
packages/ui/AGENTS.md
docs/context.md
docs/operations.md
docs/adr/
.agents/skills/
.claude/rules/

这种模式适合 monorepo、多语言、多团队、多服务，或者不同目录有不同测试命令、安全要求和发布流程的项目。

Claude Code 的 memory 文档尤其强调：常驻上下文应该保持简洁，太长会消耗上下文窗口并降低遵循率。更具体的规则应当放到 path-scoped rules 或 skills 中，按需加载。

Amp 的设计也类似：

  • AGENTS.md 放持久、通用的项目规则；
  • skills 放任务型指导；
  • MCP 提供外部工具能力；
  • 插件处理事件驱动扩展。

也就是说，大型项目不是把一个文件越写越长，而是把规则拆成“常读”和“按需读”。

4. AI-native 产品 / 企业级项目：docs + skill + MCP + memory

GitBook 和 Mastra 的博客更接近 AI-native 产品文档设计。

GitBook 对 skill.md 的建议是：不要只描述功能，而要描述能力、流程、约束和执行顺序。也就是说，给 Agent 的文档应该写 workflow，而不是 feature。

Mastra 的建议也类似：文档要结构清晰、可被 LLM 访问、内容自包含、减少歧义；然后用 skills 告诉 Agent 推荐路径、常见坑和应该优先使用的 API。

企业级或 AI-native 产品最终可能变成：

1
2
3
4
5
6
7
AGENTS.md / CLAUDE.md
docs/context.md
docs/workflows/*.md
skills/*
MCP docs server
agent memory
hooks

这时文档已经不只是 Markdown 文件，而是完整的 Agent 操作系统。

但 DigestDesk 还没有到这个阶段。

为什么 DigestDesk 不用大型项目那套？

DigestDesk 不是小项目，但也不是大型 monorepo。

它的实际复杂度在中间：

1
2
3
4
5
6
7
8
React/Vite frontend
Express API
Postgres
Scheduler worker
Digest job
AI summarization
多用户订阅关系
历史调试和成本优化记录

1. 服务数量不多，但核心链路不能破坏

DigestDesk 主要是：

1
Web + Scheduler + Postgres

没有几十个服务，也没有多语言 monorepo。所以现在不需要：

1
2
3
4
5
server/AGENTS.md
client/AGENTS.md
scheduler/AGENTS.md
.claude/rules/*.md
.agents/skills/*

但它有一个很重要的系统不变量：

用户手动、系统触发、定时触发的 digest 生成，都必须走 executeDailyDigestJob。

如果 Agent 绕过这个入口，直接在 route 里调用 generateDaily，就会破坏 feed sync、pre-summary、digest assembly、AI 成本控制，以及 scheduled/manual 的一致性。

所以它需要 context.md，但不需要很多 path-specific rules。

2. 文档主要是给 Agent 接力用的

这个项目的文档不是为了写给人慢慢读，而是为了让 Agent 接手时快速恢复上下文。

所以我们没有保留传统大而全的 architecture.md。传统架构文档会写产品规则、数据库字段、API 细节、ER 图、流程图和后续演进方向。这些对人类理解有帮助，但 Agent 每次进入项目时不一定需要完整读完。

对 DigestDesk 来说，更有效的是：

1
2
3
4
5
docs/context.md
= 150 行系统不变量

docs/history.md
= 最近修改、待验证事项、关键决策

也就是说，我们把“完整叙事”替换成了“执行上下文”。

3. history 对这个项目比 operations 更重要

DigestDesk 刚经历过成本和重复触发问题，例如：

  • 42 篇文章却出现 520 次模型请求；
  • RSS 优先，Jina fallback；
  • 日报前预摘要；
  • 去全局串行锁；
  • digest_jobs 并发执行；
  • summary cache miss 验证；
  • scheduled/manual 触发统一。

这些不是普通文档信息，而是项目记忆。

如果 Agent 不知道这些历史，它很可能会重复排查已经排查过的问题，推翻刚做过的决策，或者重新引入重复 AI 调用。

所以 DigestDesk 必须保留 docs/history.md。

4. operations 有用，但不是核心入口

DigestDesk 确实有 docs/operations.md，但它不应该每次都读。因为部署信息只有在这些场景下重要：

  • Zeabur 部署；
  • scheduler 没启动；
  • env 缺失；
  • digest_jobs 没被消费；
  • 生产日志异常。

所以我们把它保留为按需文档，而不是塞进 AGENTS.md。

这也是和传统文档体系的区别：不是所有重要文档都应该每次加载。重要但低频的信息应该按需加载。

最终选择：DigestDesk 采用中型 AI 项目模型

DigestDesk 最适合的不是小项目模型，也不是大型 monorepo 模型，而是中型 AI 项目模型：

1
2
3
4
5
AGENTS.md
README.md
docs/context.md
docs/history.md
docs/operations.md

它们的职责是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
AGENTS.md
= Agent 必读协议。短、稳定、硬规则、命令、文档路由。

docs/context.md
= AI 系统上下文。系统不变量、数据边界、服务边界、核心链路。

docs/history.md
= Agent 接力记忆。最近改了什么、今天验证什么、哪些决策不要忘。

docs/operations.md
= 部署运行排障。只有 scheduler/env/deploy 问题时读。

README.md
= 人类入口。保持短。

可以画成这样：

1
2
3
4
AGENTS.md
  ├── docs/context.md     系统不变量
  ├── docs/history.md     最近修改 / 待验证
  └── docs/operations.md  部署排障

为什么不继续拆更多文件？

因为现在拆更多会过度设计。

当前不需要：

1
2
3
4
5
server/AGENTS.md
client/AGENTS.md
scheduler/AGENTS.md
.claude/rules/*.md
.agents/skills/*

原因是：

  1. 项目规模还没到 monorepo 级别；
  2. 不同目录的开发规则差异不大；
  3. 当前最重要的问题是 digest 链路一致性，不是多团队并行规范；
  4. 太多规则文件会增加维护成本；
  5. Agent 反而可能不知道该读哪个。

等到未来出现这些情况，再拆：

  • frontend 和 backend 有明显不同规范；
  • scheduler 变成独立复杂子系统；
  • 测试命令按目录不同；
  • 多人/多 Agent 同时开发；
  • 重复任务稳定下来，可以封装成 skill；
  • 部署排障频繁发生，需要专门 deploy skill。

我们学到的核心原则

这次复盘学到的不是“要有多少文档”，而是：

文档结构要跟项目规模匹配。

小项目：

1
2
README.md
AGENTS.md

中型 AI 项目：

1
2
3
4
5
README.md
AGENTS.md
docs/context.md
docs/history.md
docs/operations.md

大型 monorepo：

1
2
3
4
5
AGENTS.md
*/AGENTS.md
docs/*
rules/*
skills/*

AI-native / 企业级：

1
2
3
4
5
6
7
组织级规则
项目级规则
路径级规则
skills
MCP
hooks
memory

DigestDesk 当前属于中型 AI 项目，所以选择中型模型。

结论

DigestDesk 没有采用大型项目常见的多层 rules、多个 AGENTS.md、专用 agents 或 skills，不是因为那些方案不好，而是因为当前项目还不需要。

我们采用的是一个更符合当前规模的模型：

1
AGENTS.md + context.md + history.md + operations.md + README.md

这个设计的重点是：

  • AGENTS.md 保持短，作为 Agent 必读协议；
  • context.md 保留系统不变量，替代长篇 architecture；
  • history.md 记录最近修改和待验证事项，解决 AI 接力问题；
  • operations.md 按需处理部署排障；
  • README 保持人类入口。

最终目标不是“文档完整”，而是让 AI 每次接手项目时能更快、更稳、更少犯重复错误。

参考链接