AI 文档系统

为什么需要这套系统

AI 编码工具最怕两件事：一是每次都从零猜项目结构，二是规则太多又互相冲突。

01MVP 的做法不是把所有约定塞进一份超长说明，而是把规则按作用拆开。离代码越近的文件，越负责本目录的边界；跨目录复用的规则，放到主题规范；一次性需求和产品判断，不混进工程规则里。

四类文档

类型	位置	负责什么
目录守门规则	`AGENTS.md`、`products/01mvp/apps/web/AGENTS.md`、`packages/*/AGENTS.md`	进入这个目录改代码时能做什么、不能做什么
主题规范	`.agents/*.md`	oRPC、UI、认证、日志、i18n、测试、工作流等跨目录规则
专项工作流	`.agents/skills/*`	部署、模板初始化、文档收录、云服务排障等可复用任务
产品与变更文档	`products/01mvp/apps/web/content/docs`、`docs/`、必要时的 specs/OpenSpec	给人看的产品意图、使用说明、架构判断和较大变更方案

一句话说：

AGENTS 管代码行为，.agents 管工程规范，Skills 管可复用工作流，产品文档管人要理解的意图。

AGENTS 怎么分层

根目录的 AGENTS.md 是全局入口，只放项目边界、通用命令和分层原则。

子目录的 AGENTS.md 是本地规则。例如：

products/01mvp/apps/web/AGENTS.md
products/01mvp/apps/web/content/AGENTS.md
products/01mvp/apps/web/content/docs/AGENTS.md
packages/AGENTS.md
products/01mvp/packages/api/AGENTS.md
products/01mvp/packages/db/AGENTS.md
packages/ui/AGENTS.md

这些文件不应该变成阅读清单。它们应该直接告诉 AI：这个目录的职责是什么、禁止什么、文件应该放哪里、改完怎么验证。

如果确实需要更长的主题规则，用 Related Guidance 指向 .agents/*.md。不要写一长串 Load First，否则每个小任务都会被迫加载无关上下文。

`.agents/*.md` 放什么

.agents/*.md 是主题规范库，适合放跨目录长期复用的规则：

.agents/orpc.md
.agents/ui.md
.agents/auth.md
.agents/i18n.md
.agents/logging.md
.agents/workflow.md
.agents/testing.md
.agents/environment-variables.md
.agents/ai.md

这些文件比目录 AGENTS.md 更详细，但不是每次都要读。只有任务触碰对应主题时才需要引用。

比如修改 products/01mvp/packages/api 时，本地 AGENTS.md 已经说明 API 包的边界；只有当你要新增 procedure、改 typed errors 或调整日志时，再看 .agents/orpc.md 和 .agents/logging.md。

产品需求放哪里

不要把产品需求、临时任务、活动页计划和一次性讨论塞进 AGENTS.md。

更合适的分法是：

内容	放哪里
目录边界、代码放置、禁止事项	最近的 `AGENTS.md`
长期工程方法论	`.agents/*.md`
模板使用者需要理解的能力	`products/01mvp/apps/web/content/docs/template`
产品意图、页面流转、用户故事	`docs/` 或后续的 `specs/`
支付、权限、数据迁移等大型变更	先写明确 proposal/spec，再实现

小修小改不需要完整规格流程。涉及多个 package、数据库、权限、安全或支付时，再把需求写成更正式的变更文档。

维护规则

能写进最近目录 AGENTS.md 的边界规则，不留在旁路文件里。
目录 AGENTS.md 保持短，只写本目录不可违反的规则。
主题细则只保留一份 canonical source，避免同一条规则在多个地方重复。
旧框架、旧路径、旧 package 名称和不存在的命令，发现就删或改成当前结构。
影响读者理解的规则变化，要同步更新 docs/template 里的说明。

这套系统的目标不是让规则越多越好，而是让 AI 每次进入一个目录时，都能读到最接近当前文件、最不容易误用的规则。