项目说明书
用 AGENTS.md 和 CLAUDE.md 让 AI 编码工具理解 01MVP 模板
这是什么
项目根目录的 AGENTS.md 是给 AI 编码工具读取的项目入口说明。它记录永久生效的协作规则、项目快照、硬边界，以及不同任务应该读取哪些 reference。
CLAUDE.md 在这个仓库里保持很短，只指向 AGENTS.md，避免两套说明长期漂移。
这不是写给用户看的产品页面，也不是替代代码的长篇解释。它的作用是让 AI 在动手之前知道项目的基本约束。
它包含什么
- 项目技术栈和目录结构
apps/01mvp-web与packages/*的边界packages/ui、packages/ui-shared、应用组件的分层规则- 不同任务要读取的
.agents/references/*文件 - 工作区保护、提交范围和常用协作习惯
更细的规则不会全部塞在根文件里，而是拆到 .agents/references。比如文档写作、UI 主题、数据库、Hono API、包架构、测试提交和命令表，都有自己的 reference。
让 AI 新增 UI 时
涉及页面、组件、弹窗、表单、Dashboard、文档可视区域时，让 AI 先看这些位置：
AGENTS.md.agents/references/ui-theme.mdapps/01mvp-web/content/docs/template/core/ui-and-theme.zh.mdxapps/01mvp-web/src/styles/theme.cssapps/01mvp-web/src/lib/theme-presets.ts
新增 UI 的验收标准不是一张截图看起来还行，而是切换 01mvp、vercel、linear、claude 后都能正常阅读和操作。AI 不能用固定色值绕过 preset；需要新的视觉角色时，先补 theme.css 的变量和语义类，再写组件。
什么时候更新项目说明书
确定新规则：当你明确了一条会重复影响开发的规范，例如组件放置、测试方式、部署边界、文档写法。
更新 AI 说明：全局硬规则写进 AGENTS.md；只在特定任务中需要的细则写进 .agents/references。
补人类文档：如果规则会影响模板使用者，也同步更新 apps/01mvp-web/content/docs 下的对应页面。
不要只把重要规则写进某一次对话里。会反复影响开发的规则，需要沉淀到仓库文件中，后续 AI 才能稳定读取。
和网站文档的关系
项目采用两层文档：
| 文档 | 主要读者 | 写什么 |
|---|---|---|
AGENTS.md、CLAUDE.md、.agents/references | AI 编码工具 | 项目规则、边界、执行习惯、按需细则 |
content/docs | 模板使用者 | 背景知识、任务路径、使用指引 |
网站文档不需要重复维护所有代码细节。代码变化快，文档应该告诉人怎么做判断、怎么走路径、遇到问题看哪里。
大功能怎么规划
涉及多个模块、数据库结构、权限模型或部署流程的大功能，可以使用 OpenSpec 工作流：
创建提案：在 openspec/changes/ 下写清目标、影响范围和技术方案。
实施变更：按提案逐步修改代码、文档和配置。
归档记录：完成后归档提案，保留这个架构决策的来龙去脉。
Bug 修复、小功能添加和文档更新通常不需要完整 OpenSpec，直接按当前任务做完并验证即可。