第 3 章 · 02 三个记忆模板精读

第 3 章 · 02 三个记忆模板精读

本节摘要:原书提供三个可直接照抄改造的模板。项目级(虚构电商项目:Node.js+PostgreSQL+React 18+Docker):项目概览 → 架构(用 @docs/architecture.md 引用)→ 开发规范(代码风格/命名/Git 工作流/测试/API/数据库/部署)→ 常用命令 → 联系人 → 已知问题。个人级(虚构"8 年全栈开发者"):关于我 → 代码偏好 → 调试偏好 → 沟通方式 → 项目组织 → 工具链。目录级(API 模块):请求校验 → 认证 → 响应格式 → 分页 → 限流 → 缓存。三个模板共同揭示 CLAUDE.md 的内容原则:只写规则与事实,不写实现细节。

学习目标

阅读完本节,你应当能够:

1. 复述项目级模板的章节结构与"已知问题"的价值。
2. 说出个人级模板的六个板块,理解"沟通方式"为什么值得写进记忆。
3. 背出目录级模板(API 模块)的六类约定要点。
4. 总结三个模板共有的内容原则。

一、项目级模板(project-CLAUDE.md)

虚构电商项目,章节结构:

• 项目概览:名称、技术栈(Node.js+PostgreSQL+React 18+Docker)、团队 5 人、截止时间;
• 架构:用 @docs/architecture.md 等文件引用代替复制粘贴;
• 开发规范:
  • 代码风格:Prettier+ESLint airbnb、100 字符行宽、2 空格缩进;
  • 命名:kebab-case 文件、PascalCase 类、camelCase 函数、UPPER_SNAKE_CASE 常量、snake_case 表;
  • Git 工作流:分支 feature/、fix/,conventional commits,至少 1 个 approval;
  • 测试:80% 覆盖率、Jest+Cypress、*.test.ts;
  • API:RESTful、/api/v1/;
  • 数据库:migrations、不硬编码凭据、连接池;
  • 部署:Docker+K8s、蓝绿发布、自动回滚;
• 常用命令表(构建/测试/启动);
• 团队联系人:Sarah Chen 技术负责人 / Mike Johnson 产品 / Alex Kim 运维;
• 已知问题与解决:PG 连接池峰值 20→查询排队;Safari 14 async generator 兼容→Babel——这是最容易被忽略但最值钱的板块:把踩过的坑写下来,AI 就不会再踩;
• 关联项目。

二、个人级模板(personal-CLAUDE.md)

虚构"8 年全栈开发者",六个板块:

• 关于我:偏好 TypeScript/Python,沟通直接、带例子;
• 代码偏好:显式 try-catch、注释写"为什么"、TDD、模块化低耦合+依赖注入;
• 调试偏好:[DEBUG] 前缀、时间戳;
• 沟通方式:用图示、先例后理、修改前后对照、结尾总结——AI 的输出风格可以由记忆塑造;
• 项目组织:src/api|services|models|utils + tests/docs/docker;
• 工具链:VS Code+vim、Zsh+Oh-My-Zsh、Prettier 100 列、Jest+RTL。

三、目录级模板(directory-api-CLAUDE.md)

API 模块专用,六类约定:

• 请求校验:Zod,失败返回 400+字段级错误;
• 认证:JWT 24h+refresh;
• 响应格式:统一 {success, data, timestamp, version} 与错误 JSON 结构;
• 分页:cursor 而非 offset、hasMore、上限 100、默认 20;
• 限流:认证用户 1000/h、公开 100/h、429+retry-after;
• 缓存:Redis 5 分钟、写时失效。

四、共同原则

三个模板共同揭示的内容原则:只写规则与事实,不写实现细节——风格规则、接口契约、目录约定、踩坑记录,都是"AI 无法从代码里轻易推断"的知识;而具体实现细节会随代码变化,写进去只会制造噪音。

小结

模板的价值是"起步即规范":项目级定团队契约,个人级定输出风格,目录级定模块边界。下一节把写作标准上升到原则层面:CLAUDE.md 的黄金法则。