和 AI 一起开发产品，repo 里到底该留下什么？
Building with AI: what belongs in the repo?最近做产品时，我逐渐发现：
使用 coding agent 后，repo 里的文档不再只是“留给以后看的记录”。
这里说的不是传统意义上的工程脚手架。
工程脚手架解决的是：项目使用什么框架、目录结构、数据库、认证、测试和部署方式。
这篇更关心的是另一层：当项目开始持续迭代、多个 Agent 参与开发后，产品事实、当前需求、技术结构和历史决策应该分别放在哪里。
前者让项目快速跑起来；后者让人和 Agent 不会越做越乱。
它们会直接影响 Agent 如何理解产品、怎样修改代码，以及遇到模糊问题时会往哪个方向猜。
文档太少，Agent 每次都要重新猜。
文档太多，同一个问题散落在几份文件里，Agent 也不知道该信哪一份。
所以真正的问题不是：
一个专业项目应该有多少份文档？
而是：
哪些信息需要长期保留？哪些只对当前阶段有效？每一种信息的 source of truth 在哪里？
1. 产品定义：我们在做什么
可以使用：
PRODUCT.md PRODUCT_DEFINITION.md
它应该回答相对稳定的问题：
- 产品服务谁
- 解决什么问题
- 核心流程是什么
- 主要产品原则是什么
- 当前明确不做什么
产品定义不是需求仓库。
不要把每次迭代的页面细节、临时方案和当前任务都塞进去。否则文件会越来越长，真正稳定的产品事实反而被埋掉。
创建时机： 产品方向开始形成时。更新时机： 目标用户、核心价值、主要流程或产品边界发生变化时。
2. 阶段或功能 Spec：这一次具体做什么
可以放在：
specs/ stage-05-fit-report.md application-pipeline.md
它负责当前阶段的执行范围，例如：
- 这次要解决什么问题
- 包含哪些场景
- 不包含哪些场景
- 页面和流程如何工作
- 验收标准是什么
- 哪些问题仍未决定
Product Definition 说的是：
产品现在是什么。
Spec 说的是：
这一轮具体准备实现什么。
不要把当前功能需求长期堆积在 PRODUCT.md 里，也不要让 Agent 只凭聊天记录理解正在做的功能。
创建时机： 一个任务已经大到不能只靠几句聊天说明时。更新时机： scope、流程或验收标准发生变化时。完成后冻结或归档，不必无限维护。
3. 系统文档：产品如何被实现
这一类通常包括：
ARCHITECTURE.md TECHNICAL_DESIGN.md DATA_MODEL.md DESIGN.md EVALS.md
不一定全部都需要。
ARCHITECTURE.md
记录当前系统结构、模块关系、主要数据流和外部依赖。
重点是系统现在如何运行，不是逐个解释代码文件。
TECHNICAL_DESIGN.md
更适合较大的功能或技术改动：
- 准备如何实现
- 涉及哪些模块
- 数据怎样变化
- 有什么风险
- 如何迁移和验证
它通常是阶段性的，实施完成后，应让 ARCHITECTURE.md 反映最终状态。
DESIGN.md
记录产品体验、信息结构、视觉和组件规则，以及 Agent 在设计上的发挥边界。
它不应该只是颜色、字体和圆角清单。
EVALS.md
当 AI 输出是产品核心能力时，需要明确：
- 什么算好结果
- 哪些错误不可接受
- 使用什么样例测试
- 如何区分模型问题、Prompt 问题和产品逻辑问题
创建时机： 当相关系统开始复杂，单靠代码已经无法解释重要约束时。更新时机： 真实实现发生变化时，而不是只在方案讨论时修改文档。
4. Decision Log：为什么这样决定
可以使用：
DECISIONS.md docs/adr/
它不负责记录“现在是什么”，而是记录：
- 当时遇到了什么问题
- 考虑过哪些方案
- 最后选择了什么
- 为什么
- 在什么条件下需要重新评估
这类信息很重要，因为几个月后，人和 Agent 都可能看到一个方案“不够完美”，却不知道它当时解决了什么问题。
但不是每个小决定都要写。
只记录那些：
- 会长期影响系统
- 修改成本较高
- 容易被后来的人重新质疑
- 有明确取舍的决定
创建时机： 第一次出现真正需要保留依据的重要选择时。更新机制： 以追加为主。决策被推翻时，新建一条，不要悄悄改写历史。
5. Agent Instructions：Agent 应该怎样工作
通常会看到：
CLAUDE.md AGENTS.md
它们应该告诉 Agent：
- 哪些文件是 canonical source
- 开始任务前需要读什么
- 代码和目录有哪些约定
- 修改后必须运行什么检查
- 哪些内容不能擅自改变
- 哪些重复错误需要避免
它不应该重新复制产品定义、完整架构和每个功能需求。
更好的做法是路由：
Product definition → PRODUCT.md
Current feature → specs/
Architecture → ARCHITECTURE.md
Design rules → DESIGN.md
Decision history → docs/adr/
Agent working rules → AGENTS.md / CLAUDE.md
Agent instructions 负责告诉 Agent 去哪里获取正确上下文，而不是吞掉所有上下文。
Iteration Log 是否必要？
不一定。
代码变化已经可以通过 commits、PR 和 changelog 追踪。
只有这些内容值得额外记录：
- 用户反馈改变了什么判断
- 做过哪些没有进入代码的实验
- 某个方案为什么失败
- Agent 反复出现了什么问题
- 哪些发现以后可能用于复盘或作品集
否则，手工维护 iteration log 很容易变成另一份重复记录。
一个实用判断
不要在项目第一天一次性创建十几份空文档。
先问：
这个问题是否会反复影响未来的判断？
如果会，就给它一个明确的 source of truth。
如果只影响当前任务，放进当前 spec。
如果代码本身已经足够说明，就不要再复制一遍。
好的文档体系不是文件很多，而是：
- 每份文档职责明确
- 同一个事实只维护一次
- 知道什么时候创建
- 知道什么时候更新
- 过期内容能被归档或删除
Agent 需要的也不是更多文字。
它需要的是一套清楚、不冲突、能找到正确答案的上下文。