AGENTS.md 项目说明书

这是什么

项目里的 AGENTS.md 是给 AI 编码工具读取的规则文件。它不面向普通用户，也不替代 README。

它的作用是让 AI 在改代码前知道三件事：

当前目录负责什么。
哪些做法不能越界。
需要时去哪里看更详细的主题规范。

01MVP 现在采用嵌套 AGENTS.md：根目录放全局规则，products/01mvp/apps/web、products/01mvp/apps/web/content/docs、products/01mvp/packages/api、products/01mvp/packages/db 等目录放本地规则。越靠近被修改文件的规则，越应该优先生效。

它包含什么

根 AGENTS.md 只放全局入口：

项目技术栈和 monorepo 分层。
通用命令和验证习惯。
规则分层原则。
不同任务的入口路径。

目录级 AGENTS.md 只放本目录守门规则：

这个目录能放什么。
不能依赖哪些模块。
文件应该放在哪里。
改完优先跑什么验证。

更长的主题细则放在 .agents/*.md，例如 .agents/orpc.md、.agents/ui.md、.agents/auth.md、.agents/workflow.md。

让 AI 新增 UI 时

涉及页面、组件、弹窗、表单、Dashboard、文档可视区域时，让 AI 先按目录读取规则：

根 AGENTS.md
products/01mvp/apps/web/AGENTS.md
如果改文档内容，再看 products/01mvp/apps/web/content/AGENTS.md 和 products/01mvp/apps/web/content/docs/AGENTS.md
需要更细 UI 规则时，再看 .agents/ui.md

新增 UI 的验收标准不是一张截图看起来还行，而是主题、移动端、可读性和状态都能正常工作。不要把开发备注、实现过程或任务记录写进读者可见的页面。

什么时候更新 AGENTS

确定规则是否会重复出现：一次性任务不要写进 AGENTS；会长期影响代码行为的规则才需要沉淀。

选择最近的位置：只影响一个目录的规则，写进这个目录的 AGENTS.md；跨目录复用的细则，写进 .agents/*.md。

避免重复：同一条规则只能有一个 canonical source。其他文件只用 Related Guidance 指过去。

同步读者文档：如果规则会影响模板使用者理解项目，也同步更新 products/01mvp/apps/web/content/docs/template。

不要只把重要规则留在某一次聊天里。会反复影响开发的规则，需要进入仓库文件，后续 AI 才能稳定读取。

和网站文档的关系

文档	主要读者	写什么
`AGENTS.md`	AI 编码工具	当前目录改代码时必须遵守的边界
`.agents/*.md`	AI 编码工具	跨目录复用的工程主题规范
`.agents/skills`	AI 编码工具	可复用专项工作流
`products/01mvp/apps/web/content/docs`	模板使用者	背景、路径、使用方式和判断建议
`docs/` 或后续 specs	项目维护者	产品意图、变更方案、阶段性决策

网站文档不需要重复所有代码细节。代码变化快，文档应该告诉人怎么做判断、怎么走路径、遇到问题看哪里。

大功能怎么规划

Bug 修复、小功能和文档更新，通常直接按任务实现并验证即可。

涉及多个 package、数据库结构、权限模型、安全策略或支付流程的大功能，先写一份明确的 proposal/spec，再让 AI 实现。这样可以把“要做什么”和“怎么写代码”分开，避免 AI 只凭聊天记录改核心模块。