AI 协作维护
01MVP 当前仓库如何用 AI 维护代码、文档、规则和提交。
这个仓库本身就是样板
01MVP 不只是给产品接入 AI 功能，也把 AI 当成日常维护仓库的协作者。这里的 AI 协作不是靠每次重新解释上下文，而是把稳定规则、目录边界和专项工作流沉淀进仓库。
这样做的目标很直接：
- AI 接手任务前能知道项目边界，不需要从零猜目录结构。
- 文档、UI、数据库、API、包结构各有自己的规则来源。
- 代码和文档修改可以带着验证一起完成。
- 新规则能进入仓库，而不是停留在某一次对话里。
维护结构
| 层级 | 位置 | 作用 |
|---|---|---|
| 全局入口 | AGENTS.md | 项目级硬边界、通用命令、规则分层原则 |
| 目录守门规则 | products/01mvp/apps/web/AGENTS.md、packages/*/AGENTS.md | 某个目录的职责、禁止事项和本地验证 |
| 文档站规则 | products/01mvp/apps/web/content/docs/AGENTS.md | 文档写作、栏目定位、sidebar 和 changelog 规则 |
| 主题规范 | .agents/*.md | oRPC、UI、认证、日志、i18n、测试、工作流等跨目录细则 |
| 专项能力 | .agents/skills | TanStack、Better Auth、Zeabur、Wrangler、模板初始化等可复用工作流 |
| 人类文档 | products/01mvp/apps/web/content/docs | 给模板使用者看的背景、路径和判断方式 |
根说明文件故意保持短。AI 进入具体目录后，应该优先读取最近的 AGENTS.md，再按任务需要查看 .agents/*.md。
一次任务怎么推进
先确认位置：AI 先看当前任务改的是 app、content、docs、api、db、ui 还是配置。
读取最近规则：从根 AGENTS.md 到目标目录最近的 AGENTS.md，确认本地边界。
按需看主题规范：例如新增 procedure 看 .agents/orpc.md，改 UI 看 .agents/ui.md，改 env 看 .agents/environment-variables.md。
检查仓库状态：动手前看 git status，区分用户已有改动和本次任务需要修改的文件。
改真实文件：按当前仓库结构修改代码或 MDX，不把开发备注写进对外页面，也不做无关清理。
做针对性验证：文档任务不跑全量构建；跨 package 代码改动再扩大到 root lint、type-check 或 build。
为什么清掉 references
旧结构里有 .agents/references，里面放了文档、UI、数据库、API、包架构和命令表等规则。
这个做法跑久了会有两个问题：
- 规则离代码远，AI 不一定会主动读取。
- 旧路径、旧框架和旧命令容易残留，和当前项目打架。
现在改成更直接的结构：目录规则就近放在 AGENTS.md，跨目录规则放在 .agents/*.md，专项流程放在 .agents/skills。.agents/references 不再作为规则入口保留。
Skills 负责更具体的工作流
主题规范解决的是项目规则，Skill 解决的是专项任务。
例如：
- 初始化一个真实产品站时，用
01mvp-template-initializer。 - 做 Zeabur 部署时，用
zeabur-deploy、zeabur-variables和zeabur-domain-url。 - 写 Cloudflare Workers 或 Wrangler 配置时，用
workers-best-practices和wrangler。 - 收录资料进文档时，用
shoulu。
这样 AI 不需要把所有领域知识都塞进根说明。常见任务有稳定入口，复杂任务再读取更专业的 Skill。
文档和代码一起维护
这个仓库的原则是：规则影响谁，就写给谁看。
- 只影响 AI 执行方式的规则，放进
AGENTS.md或.agents/*.md。 - 会影响模板使用者判断和操作的内容，写进
content/docs。 - 只属于当前实现细节的内容，优先留在代码和类型里，不额外写一份容易过期的文档。
AI 维护文档时，不是把代码翻译成文章，而是补充人类需要知道的背景、路径、约束和下一步。
这篇文档有问题？