项目文档这样组织，AI才不会跑偏

用过 Claude Code、Cursor 或者 Windsurf 的朋友，大概率都经历过这种窒息时刻：你跟 AI 聊了四十分钟，它刚给你写出了一个漂亮的架构设计，你满意地点了点头，然后说"好，接下来把这个模块实现一下"。结果它回头看了一眼代码，回了一句：

"我来从头开始设计这个系统的架构……"

你一口老血喷在屏幕上。不是 AI 变笨了，是它的上下文窗口——清掉了。

聊了那么久，前面那些讨论、决策、约束条件，全没了。AI 不记得了，就好像你们从来没聊过一样。

这个问题背后的道理其实很简单：上下文窗口 = RAM，文件系统 = 硬盘。RAM 易失、有限、宝贵的很；硬盘持久、廉价、写多少都行。你让 AI 把所有东西都塞 RAM 里，那它肯定记不住。你得帮它把东西存硬盘里。

那问题来了：存什么？怎么存？

今天这篇文章，结合两个思路来聊——Matt Pocock 的 9 条项目文档铁律，和 Ahmed Othman（planning-with-files，灵感来自 Meta 花 20 亿美元收购的 Manus）的三文件模式。

第一部分：Matt Pocock 的 9 条项目文档铁律

Matt Pocock 是 aihero.dev 的作者，他的 GitHub 项目 mattpocock/skills 有 60K+ Stars。他总结了一套 AI 项目文档的组织方式，核心原则是：按类型分文件，按需要选择性加载，别一股脑塞进上下文。

下面逐条拆解。

1. 项目知识库 → 放项目外

架构讨论、技术选型调研、背景研究这些内容，放项目目录里。它们只在项目初期决策时需要用到，一旦定了，AI 日常编码就不需要反复读了。放在项目根目录的 knowledge/ 或者直接单独放一个外部仓库，需要的时候再手动引入。

原则：别拿灰尘数据污染上下文。

2. AGENTS.md — 项目操作指南

这份文件放在项目根目录，告诉 AI 这个项目怎么玩。包括：
- 项目技术栈和目录结构导航
- 代码规范和风格约定
- 常用的工作流（测试怎么跑、构建怎么执行）
- AI 需要遵守的规则

比如你可以在 AGENTS.md 里写："本项目所有 API 必须先写类型定义，再写实现"；"新增功能必须同步更新测试"。这就是 AI 的操作手册。

3. CONTEXT.md — 术语表

每个项目都有自己的黑话。agg 是聚合根还是聚合函数？biz 是业务层还是 Biztalk 的缩写？把这些术语整理到 CONTEXT.md 里，AI 翻一眼就不会搞混。

对 AI 来说，一个歧义术语可能就意味着后面几万行代码的逻辑方向全都跑偏。

4. ADR（架构决策记录）— 每个决策一个文件

ADR（Architecture Decision Record）不是什么新鲜概念，但对 AI 项目来说极其重要。每个重大架构决策写一个 .md 文件，格式包含：标题、状态、背景、决策、后果。

为什么要这么做？因为人是会变卦的。你今天决定用 PostgreSQL，做了很多适配工作。三个星期后换成了 MySQL，如果不写 ADR，AI 看到旧代码就会困惑——"这怎么还有 PG 的方言？是不是祖传屎山？"

ADR 是 AI 防止架构变坏的工具。

5. ARCHITECTURE.md — 架构文档

数据怎么流转，模块怎么分层，依赖关系是什么。这张"大地图"对 AI 来说比对人还重要。人读了或许能记住大概，AI 每次翻开都要看到完整的。

画几个 ASCII 架构图更好，AI 吃这套。

6. DESIGN.md — 设计文档

更详细的设计描述。为什么这么设计，权衡了什么，有什么取舍。跟 ARCHITECTURE.md 的区别是：架构是大局观，设计是局部细节说明。

7. spec/ 文件夹 — 阶段性实现方案

把一个大的需求拆成多个阶段，每个阶段写一个 spec 文件。比如 spec/phase-1-auth.md、spec/phase-2-payment.md。每个 spec 说清楚这阶段要实现什么、不做什么、验收条件是什么。

AI 读到这样一个 spec，就不会"自由发挥"了。

8. tickets/ 文件夹 — 垂直切片式任务

这里放的是真正可以执行的"任务切片"。每个 ticket 应该是一个垂直切片——跨越前端、后端、数据库，完整实现一个小功能。而不是按职能划分的"前端任务"、"后端任务"。

垂直切片的理念是：每个 ticket 做完，系统就多了一个可工作的端到端特性。AI 做起来目标清晰，你也好验收。

9. scratch/ 文件夹 — 语料暂存区

临时的 issue 记录、待讨论的问题、实验性的想法。算是 AI 项目的便签本。不优雅没关系，能帮 AI 记住就行。

到这里你已经发现了，Matt Pocock 这套体系的本质是：把工作记忆从 AI 的脑子（上下文）转移到文件系统（硬盘）里。 按类别分好，每次要做什么就加载对应的文件，别一股脑全塞进去。

第二部分：planning-with-files 的三文件模式

GitHub 上有个 18K+ Stars 的项目叫 planning-with-files，作者 Ahmed Othman。这个项目的灵感来自 Meta 花了 20 亿美元收购的 Manus 团队。Manus 团队在 AI 编程上有一个很厉害的技术：注意力操纵（Attention Manipulation）。

名字听起来玄乎，本质很简单：让 AI 不断地回读同一份文件，把全局目标推回到上下文里来。

planning-with-files 就是这套思路的极致简化版，只用了三个文件：

1. task_plan.md

任务拆解 + 进度追踪。把一个项目拆成若干个任务，每个任务标注状态（待办 / 进行中 / 已完成 / 阻塞）。AI 每完成一步，就去更新这个文件。

核心操作是：AI 在每个步骤之前先读这个文件，这样它就不会迷失。

2. findings.md

调研笔记。AI 做技术调查、读文档、看源码之后，把关键发现写在这里。下次同样的调查不需要再做一遍——AI 读到 findings.md 就能复用之前的调研结论。

3. progress.md

会话日志 + 错误历史。这是最有意思的部分。每次 AI 做了什么，遇到什么错误，尝试了什么方案，全都记下来。

这里有个"错误不要删"的原则： 失败的尝试记录留着。AI 下次再看到同样的场景，读到之前失败的历史，就不会再往同一个坑里跳了。人会说"吃一堑长一智"，对 AI 来说，"读一记长一智"。

这三文件的组合拳很简单：task_plan.md 告诉 AI 下一步要做什么，findings.md 告诉 AI 已知什么，progress.md 告诉 AI 踩过什么坑。

attention-manipulation 的效果体现在：AI 每次读 task_plan.md 的开头几行，都会看到项目的顶层目标。这就相当于你每次开会前先念一遍"我们要做什么"，谁都不会跑偏。

怎么选？怎么结合？

两种思路不冲突，互补的。

Matt Pocock 教你怎么组织——文件按什么分类，知识怎么分层。他解决的是"静态结构"问题：档案室里每个文件放哪个格子。

planning-with-files 教你怎么驱动——哪些文件要反复读，怎么通过文件做持久化工作记忆。它解决的是"动态过程"问题：工作的时候先看哪个文件、更新哪个文件。

我自己的做法是把两者结合起来：

my-project/
├── AGENTS.md              # AI 操作手册
├── CONTEXT.md              # 术语表
├── ARCHITECTURE.md         # 架构图
├── task_plan.md            # 任务拆解 + 进度（从 planning-with-files）
├── findings.md             # 调研笔记（从 planning-with-files）
├── progress.md             # 会话日志（从 planning-with-files）
├── spec/
│   └── phase-1-auth.md     # 阶段性实现方案
├── tickets/
│   └── T001-implement-login.md  # 垂直切片任务
├── adr/
│   ├── 001-use-postgres.md
│   └── 002-use-nextjs.md
├── scratch/                # 语料暂存区
└── knowledge/              # 项目知识库

核心思路就一句话：别让 AI 把所有东西都塞进上下文，该存硬盘的存硬盘。

上下文窗口是用来"执行"的，不是用来"记忆"的。文件系统才是 AI 真正的长期记忆。

每次你准备跟 AI 开始一个新会话，花 5 分钟整理一下文档结构，把关键信息写进文件里。高质量的文档是在"喂"AI，低质量的上下文是在"废"AI。

你的 AI 不会记得你说过什么——但它会读到你都写了什么。所以，写下来。