Vibe Coding 工程化进阶（一）：用 CLAUDE.md / AGENTS.md 给 AI 装上"项目记忆"

上一个系列讲的是个人怎么把 Vibe Coding 用好。这个系列升级到团队工程化：怎么把"全靠人随手提示"的玄学，变成"整个团队、每次对话都稳定可复现"的体系。四块拼图——记忆（CLAUDE.md/AGENTS.md）、规范（Rules）、感官（MCP）、护栏（Hooks）。这是第一块：记忆。

一、先理解一个残酷设定：AI 每次都是"失忆"开局

不管模型多强，每开一个新对话，它对你的项目几乎一无所知：不知道用的什么技术栈、命令怎么跑、目录怎么分、哪些是历史包袱不能动。

于是大多数人的日常是这样的：

"我们用 pnpm 不是 npm……组件放 app/components……状态用 Pinia 不是 Vuex……别动 legacy/ 目录……"

每次都要重复一遍。 这就是没有"项目记忆"的代价。CLAUDE.md / AGENTS.md 要解决的就是这件事：把这些每次都要说的话，写一次，让 AI 每次自动读到。

二、CLAUDE.md 和 AGENTS.md 到底是什么、什么关系

它们是放在项目里的 Markdown 指令文件，会被 AI 编程工具在每次对话时自动加载进上下文，作为"项目说明书"。

CLAUDE.md：Claude Code 的项目记忆文件。
AGENTS.md：一个跨工具的开放约定，Cursor 等主流工具都已支持。

两者作用完全一样，区别只是生态。实务建议：

用 AGENTS.md 作为主文件（通用、跨工具）；如果团队同时重度使用 Claude Code，可以让 CLAUDE.md 指向它（一行 See @AGENTS.md），避免维护两份。

下文统一以 AGENTS.md 为例，规则对 CLAUDE.md 同样成立。

三、加载机制：它是"分层"的

这是用好它的关键认知。记忆文件不是只有一个，而是按层叠加：

层级	位置	作用范围	放什么
全局	`~/.claude/CLAUDE.md` / 用户级配置	你的所有项目	个人偏好（语言、commit 风格）
项目根	仓库根目录 `AGENTS.md`	整个项目	技术栈、命令、约定、架构、雷区
子目录	子目录下的 `AGENTS.md`	该目录及其子级	该模块的特殊规则

当 AI 在某个子目录工作时，根目录 + 该子目录的记忆会一起生效。所以 monorepo 里可以根目录放通用约定，packages/admin/ 再放后台专属约定，互不污染。

Claude Code 里还支持 @相对路径 引用：@docs/architecture.md，把大文档拆出去、按需引入，避免主文件臃肿。

四、该写什么：高信噪比是唯一标准

记住一个铁律：

AGENTS.md 的每一行都常驻上下文，是要花 token、也会稀释注意力的。写得越多越啰嗦，关键信息越被淹没。 目标是「高信噪比」，不是「全」。

值得写进去的，是那些**"不写 AI 就会做错、且每次都要纠正"**的东西：

项目一句话定位：是什么、给谁用。
技术栈：框架、语言、包管理器、关键库（写清楚版本心智，比如"Vue 3 + <script setup>，不要 Options API"）。
常用命令：装依赖 / 起开发 / 构建 / 测试 / lint，一字不差能直接跑。这是性价比最高的一块——AI 最容易在这里瞎猜。
目录地图：核心目录各自放什么。
代码约定：命名、组件写法、样式方案、状态管理、API 层怎么调。
雷区（最值钱）：哪些目录/文件不能动、哪些历史坑、哪些"看起来能改其实会炸"的地方。
协作约定：分支、commit 规范、PR 要求。

五、不该写什么

❌ 长篇大论的风格指南：链接过去（详见 @docs/style.md），别全文塞进来。
❌ 密钥、token、内网地址：它会进上下文、可能被打印，安全风险。
❌ 易变的临时信息：本周排期、某个临时 bug——过期的记忆比没有记忆更糟。
❌ AI 本来就会的通识："React 是个前端框架"这种不用写。

六、一份可直接抄的前端 `AGENTS.md` 模板

# 项目：Andy Blog 前台（Nuxt SSR）

面向访客的博客前台，内容由后端 API 提供。

## 技术栈
- Nuxt 4 + Vue 3（一律 `<script setup>`，不要 Options API）
- TypeScript 严格模式；包管理器用 pnpm（禁止 npm/yarn）
- 样式用 Tailwind + shadcn-nuxt；不要手写全局 CSS
- 国际化用 @nuxtjs/i18n（no_prefix 策略）

## 常用命令
- 装依赖：`pnpm i`
- 起开发：`pnpm dev`
- 构建：`pnpm build`
- 类型检查：`pnpm typecheck`
- Lint 修复：`pnpm lint --fix`

## 目录地图
- `app/pages/`   路由页面
- `app/components/` 通用组件（UI 原子组件在 `components/ui/`）
- `app/composables/` 数据请求与逻辑复用（用 useAsyncData）
- `server/`       Nitro 服务端（SSR 走内网 API）

## 约定
- 数据获取统一用 composables（如 `useBlogApi`），不在组件里裸调 fetch
- 提交信息遵循 Conventional Commits（中文描述）
- 新组件优先复用 `components/ui/`，不够再自建

## 雷区
- 不要改 `routeRules` 里列表页的缓存策略，缓存有专门设计（见 @docs/cache.md）
- `app/components/ui/` 是 shadcn 生成的，不要手改，要改用 CLI 重新生成
- 不要把静态资源写死域名，用 `staticPath` 运行时拼接