AI 辅助开发
用 AI 编码工具高效参与项目开发
这是什么
本页讲的是你写代码时让 AI 帮你的工作方式，不是项目里的 AI 功能（如聊天、生成文本）。项目为 AI 编码助手准备了专用指导文件，让 AI 理解项目规范后写出更符合项目风格的代码。
CLAUDE.md：给 AI 的项目说明书
项目根目录的 CLAUDE.md（AGENTS.md 是其软链接）是整个项目的"AI 说明书"，包含：
- 项目结构和技术栈概览
- 常用命令（dev、build、test、database）
- 代码规范和开发流程
- Git 提交规范和分支策略
- 常见问题排查提示
AI 编码工具在读取后能准确理解项目约定，生成符合规范的代码。
让 AI 新增 UI 时
涉及页面、组件、弹窗、表单、dashboard、docs 可视区域时，要先让 AI 读取：
AGENTS.md/CLAUDE.md的 Design System 部分apps/01mvp-web/content/docs/user-guide/guides/ui-and-theme.zh.mdxapps/01mvp-web/content/docs/user-guide/concepts/ui-style.zh.mdxapps/01mvp-web/src/styles/theme.cssapps/01mvp-web/src/lib/theme-presets.ts
新增 UI 的验收标准不是“当前截图好看”，而是切换 01mvp、vercel、linear、claude 后都能正常阅读和操作。AI 不能用固定色值绕过 preset；如果需要新的视觉角色，应该先补 theme.css 的变量和语义类，再写组件。
什么时候更新 CLAUDE.md
确定规范：当你确定了一条新的代码规范或工作流程
同步更新三处：
CLAUDE.md— 更新 AI 的指导内容apps/01mvp-web/content/docs/— 更新对应的开发文档- 相关 package 的
README.md— 如果影响包的能力或 API
CLAUDE.md 和 AGENTS.md 是同一个文件的软链接，修改其中一个另一个会自动同步。不要删除软链接，否则 AI 工具可能找不到项目说明。
文档分层：AI 读什么 vs 你读什么
项目采用两层文档策略：
Package README.md（给 AI + 开发者）
每个 packages/xxx/README.md 包含技术细节：API 签名、类型定义、使用示例、配置选项。AI 开发时会自动读取对应包的 README，不需要你手动指定。
网站文档（给你看）
content/docs/ 里的页面按任务组织：guides/ 告诉你"怎么改"，reference/ 补充技术细节。
维护原则：README.md 是技术细节的唯一来源；网站文档解决任务路径，不重复抄 API 签名。
OpenSpec：大功能的规划流程
对于涉及多个模块的大功能或架构变更，使用 OpenSpec 工作流：
创建提案 — 在 openspec/changes/ 下写 .md 文件，描述目标和技术方案
实施 — 使用 /openspec:apply 按提案开发
归档 — 完成后用 /openspec:archive 归档
对于 Bug 修复、小功能添加、文档更新等小任务，直接用 AI 工具的 Plan Mode 即可，不需要走完整的 OpenSpec 流程。