AI 时代,一个项目到底需要哪些文档?

最近我一直在想一个问题：

在 AI Coding Tools 已经越来越成熟的今天，一个项目到底还需要哪些文档？

以前我们聊项目文档，通常会想到 README、需求文档、架构文档、接口文档、部署文档、测试文档等等。

这些当然都有价值，但在真实项目里，文档一多，很容易变成另一种负担：没人维护、没人看、和代码脱节，最后变成“历史资料”。

但 AI 时代又不一样。

因为现在的文档不只是给人看的，也是给 AI 看的。

Claude Code、Codex 这类 AI Coding Tools 进入项目之后，最需要的不是一堆散乱的说明，而是稳定、清晰、可引用的上下文。它需要知道：

• 这个项目为什么存在
• 当前最重要的方向是什么
• 代码应该怎么组织
• 哪些地方不能乱改
• 遇到不确定需求时该怎么处理
• 修改完之后应该怎么验证

所以我现在越来越觉得，AI 时代的项目文档不一定要多，但一定要有清晰分工。

如果压缩到最小集合，我认为一个项目至少需要三个核心文档：

README 当索引，PRODUCT 当北极星，CLAUDE 当工程圣经。

这三个文档的职责不能重叠。

1. README：项目索引

README 不应该承担所有事情。

很多项目的问题是，README 一开始很清爽，后来什么都往里面塞：项目介绍、启动方式、产品规划、架构说明、接口说明、部署步骤、历史决策……最后 README 变得越来越长，真正重要的信息反而找不到。

在 AI 时代，README 更适合做“索引”。

它只需要回答几个最基本的问题：

• 这个项目是什么
• 适合谁使用
• 如何快速启动
• 常用命令是什么
• 关键文档在哪里
• 新人或 AI Agent 应该先读什么

也就是说，README 是入口，不是全部。

它的价值不是解释所有细节，而是让人和 AI 都能快速找到正确的上下文。

一个好的 README.md 应该像项目地图的首页：

# Project Name## What is this?一句话说明项目。## Quick start如何安装、启动、运行测试。## Key documents- PRODUCT.md: 产品目标、用户、范围- CLAUDE.md: 工程约定、代码规范、AI Coding Agent 工作规则- docs/architecture.md: 架构说明- docs/adr/: 重要技术决策记录

README 越清楚，AI 越不容易一进项目就迷路。

2. PRODUCT：北极星

如果 README 是入口，那么 PRODUCT 就是方向。

AI Coding Tools 很擅长执行，但它们不天然理解“为什么要做”。如果没有产品层面的约束，AI 很容易把事情做“完整”，但不一定做“正确”。

比如你让 AI 加一个功能，它可能会顺手加很多扩展能力、配置项、抽象层，看起来很勤奋，但其实已经偏离了产品当前阶段真正需要的东西。

所以项目需要一个 PRODUCT 文档，作为北极星。

它应该说明：

• 项目为什么存在
• 目标用户是谁
• 用户的核心问题是什么
• 当前阶段最重要的目标是什么
• 什么是明确不做的
• 什么算做完
• 产品体验上有哪些原则

PRODUCT 不需要写成很重的 PRD。它更像一个持续维护的产品判断基准。

比如：

# PRODUCT.md## Why this project exists这个项目解决什么问题。## Target users主要用户是谁，不是谁。## Core use cases最核心的 3-5 个使用场景。## Current focus当前阶段最重要的方向。## Non-goals明确不做什么。## Product principles体验和取舍原则。

这个文档最大的价值，是避免项目在快速迭代中发散。

尤其是有 AI 参与之后，开发速度会变快，代码生成成本会降低，但也更容易产生“功能膨胀”和“方向漂移”。

PRODUCT 的作用就是提醒团队和 AI：

我们不是为了写更多代码，而是为了持续逼近正确的问题。

3. CLAUDE：工程圣经

第三个文档，是给 AI Coding Agent 和开发者共同使用的工程约定。

这里我用 CLAUDE 来代表这类文档。它可以叫CLAUDE.md，也可以叫 AGENTS.md、CODEX.md，名字不重要，关键是它承担的职责。

它不是产品文档，也不是项目介绍。它是工程层面的“行为协议”。

它应该告诉 AI Coding Tools：

• 项目目录结构怎么理解
• 核心模块分别负责什么
• 常用开发命令是什么
• 测试怎么跑
• 代码风格是什么
• 哪些文件不要随便改
• 修改 API 时需要同步更新什么
• 遇到不确定需求时要先问，不要猜
• 每次改动应该尽量小而聚焦
• 完成后如何验证

比如：

# CLAUDE.md## Project structure- `src/`: core application code- `tests/`: test cases- `docs/`: documentation- `scripts/`: development scripts## Commands- Run tests: `pytest`- Start dev server: `python -m app`## Engineering rules- Prefer small, focused changes.- Do not change public APIs without updating related docs.- Add or update tests for behavior changes.- Do not edit migration files unless explicitly asked.- If requirements are ambiguous, ask before implementing.## ValidationBefore finishing:1. Run relevant tests.2. Check formatting.3. Summarize changed files and reasoning.

这个文档在 AI 时代非常关键。

因为 AI Coding Tools 的问题往往不是“不会写代码”，而是：

• 不知道项目边界
• 不知道历史约定
• 不知道哪些地方不能动
• 不知道改完怎么验证
• 不知道什么时候应该停下来问人

CLAUDE 的价值，就是把这些隐性工程经验显性化。

它像一本工程圣经，让 AI 在项目里工作时有规矩可循。

三者职责不能重叠

我觉得这里最重要的不是具体文件名，而是职责分离。

这三个文档最好不要互相混。

README 不应该越来越胖。 它只做索引和入口，不要把所有细节都塞进去。

PRODUCT 不应该混入工程细节。   它负责方向、用户、边界和取舍，不负责告诉你某个函数怎么写。

CLAUDE 不应该替产品做决定。   它负责工程约定和执行规则，不应该决定产品目标和功能优先级。

可以简单理解成：

• README 回答：我该从哪里开始？
• PRODUCT 回答：我们为什么做、往哪里走？
• CLAUDE 回答：代码应该怎么改、怎么验证？

三者合在一起，才构成一个适合人和 AI 协作的最小文档系统。

文档的目标不是“完整”，而是“可协作”

很多团队一提到文档，就会陷入两个极端： 一种是完全不写，觉得代码就是最好的文档。另一种是写很多，试图把所有细节都记录下来。

但在 AI 时代，我觉得文档的目标不是追求完整，而是提高协作效率。

尤其是 AI Coding Tools 出现后，文档的价值会更偏向这几个方向：

• 帮 AI 快速恢复上下文
• 减少 AI 猜错方向
• 限制不必要的发散
• 让人类判断和 AI 执行更好衔接
• 让项目在快速迭代中保持收敛

换句话说，文档不是为了证明项目很规范，而是为了让项目在混乱中持续收敛。

这也是我最近很喜欢的一个表达：

好文档不是让项目看起来更正式，而是让人和 AI 在同一个上下文里工作。

最后

AI 时代，代码生成会越来越快。但项目真正的难点，可能会从“怎么写代码”，转移到“如何保持方向、边界和一致性”。

所以我认为，一个项目最少需要三个核心文档：

README 当索引，PRODUCT 当北极星，CLAUDE 当工程圣经。

README 让人和 AI 找到入口。

PRODUCT 保证项目不偏航。

CLAUDE 约束工程执行，让 AI Coding Tools 更可靠地工作。

文档不需要很多，但要各司其职。

越是 AI 能快速写代码的时代，越需要少量高质量的文档来帮助项目持续收敛。