当 AI 成为主程序员：如何设计一套不让 Agent “失忆”与“瞎猜”的项目文档体系？
这篇文章主要告诉你，当 Agent 已经从辅助写代码变成主要开发执行者后，项目文档应该怎样组织，才能让 Agent 在多轮、多任务、多会话开发中快速建立正确上下文，不反复猜、不读一堆废文档、不发生规范漂移。
很多人让 AI 写代码，经常会遇到两个痛点：AI记不住事情、AI喜欢瞎搞。
早上你花了一个小时，在聊天框里跟它反复叮嘱“别用某个库”、“按钮样式必须用现成组件”、“千万别碰老接口”。它答应得好好的。下午对话窗口变长变卡了，你新开一个会话，它立马把早上的叮嘱忘得一干二净，又开始按自己的默认习惯随心所欲乱写。
更要命的是，它在代码库里翻到一段为了绕过平台 Bug 特意写的特殊逻辑，自以为很聪明地觉得“这代码写得太蠢了”，顺手帮你重构优化了一遍，一跑直接报错。
很多人遇到这种情况，只会一遍遍复制粘贴提示词，或者怪模型太笨。其实根本原因很现实：AI 进你的项目，两眼一抹黑，只能靠翻文件。你给它翻的文件如果是个混乱的垃圾堆，它敲出来的代码肯定也是乱七八糟的。
人类写代码看不懂旧文档，还能跑去问身边的同事；AI 没有这个条件，它必须把文件里的规矩当成唯一依据。
要解决这个问题，必须把项目的文档结构重新理一遍。下面这张图里的目录规范，就是专门给 AI 当主程序员准备的：
├── AGENTS.md # 给 AI 看的总规则：优先级、工作流程、死穴禁区、验收标准
├── README.md # 给人类看的一页纸：这项目干嘛的、本地怎么两行命令跑起来
├── CHANGELOG.md # 每次发版更新了啥
├── docs/ # 核心业务和技术规范（按事情拆开，别堆在一起）
│ ├── PRODUCT.md # 业务底线：目标用户是谁、解决啥问题、哪些功能坚决不做
│ ├── ARCHITECTURE.md # 系统骨架：模块怎么拆的、数据流向、选了啥技术
│ ├── DESIGN-SYSTEM.md # 界面规范：颜色、间距、现有组件怎么调，别自己乱写样式
│ ├── DEVELOPMENT.md # 开发命令：环境配置、启动命令、格式化命令、代码规矩
│ ├── TESTING.md # 测试要求：怎么跑单测、跑什么命令、怎样就算测试通过
│ ├── DEPLOYMENT.md # 部署回滚：构建步骤、环境变量配置、出事怎么回滚
│ ├── decisions/ # 历史决策记录（最关键）：记录“为什么当时故意这么写”
│ │ ├── 001-use-cloudflare-pages.md
│ │ ├── 002-state-management.md
│ │ └── ...
│ └── plans/ # 跨会话接力棒：把任务进度存盘，换会话不失忆
│ ├── active/ # 正在干的任务计划
│ │ ├── add-city-comparison.md
│ │ └── refactor-data-layer.md
│ └── completed/ # 干完归档的任务记录
│ └── 2026-09-01-initial-setup.md
├── references/ # 资料库
│ ├── ai-prompts/ # 好用的提示词
│ ├── external/ # 外部引用和数据源
│ └── assets/ # 图片素材与设计图
├── src/ # 业务源码
└── tests/ # 测试用例一、 把规矩和介绍分开：AGENTS.md 与README.md
以前很多项目喜欢把什么东西都塞进一个 README.md，最后搞得上万行。人类懒得看，AI 读了占满上下文，还抓不住重点。
这两个文件必须分工明确：
README.md只留给人类看：说明项目是干嘛的，写三两行启动命令，人类扫一眼能跑起来就行。AGENTS.md是给 AI 进门先看的红头文件：这是整个项目的控制中心。
AGENTS.md 里面不要说废话，只列三块内容：
- 去哪看什么：要查业务看
PRODUCT.md，要查代码规矩看DEVELOPMENT.md，别瞎猜。 - 绝对不能碰的红线：比如“绝对不要手改数据库迁移文件”、“绝对不能引入额外的 CSS 库”。
- 合格交付标准：改完代码必须自己跑通哪条测试命令、必须更新哪个文件，否则不算完工。
二、 规范拆开装：别让 AI 读大杂烩
AI 处理短而精准的信息很靠谱，面对又臭又长的大合集容易眼花漏看。docs/ 下面的几份文件，各自管好一件事：
PRODUCT.md划好圈子，防它乱加戏： 明确写上“我们做什么，坚决不做什么”。比如你做一个极简打卡工具，里面白纸黑字写上“本项目不做社交分享和好友系统”，它写代码时就不会自作多情搞个好友列表出来。ARCHITECTURE.md讲清骨架，防它乱插代码： 告诉它接口在哪一层、数据怎么流转。防止它偷懒把本该写在后端的数据库查询直接塞进前端组件里。DESIGN-SYSTEM.md管住手脚，防前端样式发疯： 明确列出项目现有的主色调、间距大小，以及弹窗、按钮组件的路径。明确规定“只要写弹窗，必须用现成的 Modal 组件，严禁用原生 div 自己手搓浮层”。DEVELOPMENT.md与TESTING.md给出具体命令： 直接写明单测跑哪条命令、打包跑哪条命令。省得它改完代码连怎么验证都不知道，全凭感觉交差。
三、 防手欠神器：decisions 目录（决策记录）
很多老代码写得奇奇怪怪，甚至看起来有点冗余，背后多半有踩坑原因——可能为了兼容某个浏览器的奇葩 Bug，也可能是因为某个云平台的环境限制。
如果不把原因写下来，AI 看到就会觉得“这代码写得不够优雅，我顺手改了吧”，一改就引爆隐藏 Bug。
在 docs/decisions/ 目录下，用类似 001-use-cloudflare-pages.md 这样的小文件记下来：
- 当时遇到了什么问题？
- 为什么选了现在的方案？
- 为什么另一个看起来很美好的方案行不通？
AI 动手改模块之前先扫一眼相关的决策，立刻明白“这里长得怪是故意留着的”，自然不敢胡乱重构。
四、 跨会话接力棒：plans 目录（治好断点失忆）
聊天记录会变长，会话窗口会卡顿，电脑也会关机。指望把上下文留在对话历史里，根本靠不住。
要想换一个会话、换一个模型还能继续干，必须把任务进度写在文件里。这就是 docs/plans/ 目录的作用：
1. plans/active/（正在干的）
要做一个新功能，先让 AI 在这里新建一个文件，比如 add-city-comparison.md，里面写清楚：
- 目标是什么
- 拆解成哪几步（列好勾选清单）
- 涉及改哪几个文件
- 验收条件是什么
如果聊天窗口卡死了，或者今天下班了，明天重新开一个对话，你只要把一句话甩给它：
“去看
docs/plans/active/add-city-comparison.md，接着完成第三步。”
新 AI 读完文件，马上就能无缝接手，用不着你把前因后果从头解释一遍。
2. plans/completed/（干完归档）
功能测完上线后，把这个文件移到 completed/ 里。以后再做类似功能，或者后人想知道这个模块当初是怎么建起来的，这就是最真实的过程记录。
五、 订死干活步骤：五步交付法
有了这套目录，还要把 AI 干活的动作固定下来，写进 AGENTS.md 里，强制它执行这五步：
A["1. 理解任务"] --> B["2. 制定计划"] --> C["3. 开发实现"] --> D["4. 验证测试"] --> E["5. 更新文档"]- 第一步：看懂要求：读相关文档，看有没有相关的
decisions限制，不明白的停下来问人类，严禁自己脑补。 - 第二步：写下计划：在
plans/active/创建或者更新任务文档，把步骤和验收标准列出来，让人类确认一眼。 - 第三步：动手写代码：按照规范改文件，自己做基本检查；中间做了关键选型，顺手在
decisions/加一篇记录。 - 第四步：跑通测试：亲自执行测试命令，对照当初定下的验收标准一个个对，自己把报错修干净。
- 第五步：收拾现场：把改动同步到相关文档，把写完的计划移动到
plans/completed/，记下一两条避坑心得。
六、 怎么给手头的老项目改造？
不需要一天时间把所有文档全憋出来。照着下面这三步走，项目立刻就能顺手很多：
- 第一步：今天花十分钟建个
AGENTS.md写在项目根目录下，写上你的技术栈名字、跑测试的命令，以及两三条平时最烦它犯错的禁令（比如不要改哪些核心文件）。 - 第二步：以后做功能，先逼它写 plan
别直接在聊天框里给大需求。让它先在
docs/plans/active/给你列个计划清单，你觉得没毛病了，再让它敲代码。 - 第三步：它改错一次，记一篇 decision
只要它搞乱了你原有的特殊设计，别光顾着在对话里骂它。直接让它在
docs/decisions/补一个短文件，说明“为什么这里不能这么改”。以后换任何会话，它都不会再犯同一个错。
把文档当成约束 AI 行为的规则手册，它才能真正从一个动不动就闯祸的实习生，变成一个稳定省心的主力干将。