Claude Code 通关手册（三）：99%的人不知道的效率秘诀，CLAUDE.md 深度实战

┌──────────────────────────────────────────────────────────┐
│           Claude Code 记忆系统全景图                       │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌────────────────────────────────────┐                  │
│  │  第 1 层：全局 CLAUDE.md            │                  │
│  │  ~/.claude/CLAUDE.md               │                  │
│  │  → 所有项目通用的个人偏好           │                  │
│  │  → "我喜欢 2 空格缩进"             │                  │
│  └──────────┬─────────────────────────┘                  │
│             ↓ 叠加                                        │
│  ┌────────────────────────────────────┐                  │
│  │  第 2 层：项目 CLAUDE.md            │                  │
│  │  项目根目录/CLAUDE.md              │                  │
│  │  → 项目专属信息，提交到 Git         │                  │
│  │  → "本项目用 Next.js 14 + TS"      │                  │
│  └──────────┬─────────────────────────┘                  │
│             ↓ 叠加                                        │
│  ┌────────────────────────────────────┐                  │
│  │  第 3 层：个人本地 CLAUDE.local.md  │                  │
│  │  项目根目录/CLAUDE.local.md        │                  │
│  │  → 个人偏好，不提交到 Git           │                  │
│  │  → "用中文回答我"                  │                  │
│  └──────────┬─────────────────────────┘                  │
│             ↓ 叠加                                        │
│  ┌────────────────────────────────────┐                  │
│  │  第 4 层：子目录 CLAUDE.md          │                  │
│  │  src/components/CLAUDE.md          │                  │
│  │  → 按需加载，操作该目录时才读取     │                  │
│  │  → "组件必须用函数式声明"          │                  │
│  └──────────┬─────────────────────────┘                  │
│             ↓ 叠加                                        │
│  ┌────────────────────────────────────┐                  │
│  │  第 5 层：Auto Memory（自动记忆）   │                  │
│  │  ~/.claude/projects/<项目>/memory/ │                  │
│  │  → Claude 自己记的笔记             │                  │
│  │  → 自动记录，无需你维护             │                  │
│  └────────────────────────────────────┘                  │
│                                                          │
│  叠加规则：所有层级同时生效，不是覆盖关系                   │
│  冲突时：越具体的层级优先级越高                             │
│                                                          │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│            CLAUDE.md 内容取舍原则                          │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ✅ 该写的（每次会话都需要知道的信息）                      │
│  ├── 项目是什么、用了什么技术栈                            │
│  ├── 项目目录结构的关键说明                                │
│  ├── 编码规范和命名约定                                   │
│  ├── 日常开发要跑的命令（dev/build/test/lint）             │
│  ├── 重要的架构决策和约束                                  │
│  └── 常踩的坑和特殊注意事项                                │
│                                                          │
│  ❌ 不该写的                                              │
│  ├── "写出高质量代码" — 太模糊，等于没说                   │
│  ├── "遵循最佳实践" — Claude 自己知道，不用你教             │
│  ├── 完整的 API 文档 — 太长，用 @docs/ 引用               │
│  ├── 频繁变动的信息 — 放到对话里说就行                     │
│  ├── 所有可能用到的命令 — 只写高频的                       │
│  └── SOLID 原则的定义 — Claude 比你还熟                   │
│                                                          │
│  核心思路：                                                │
│  想象你给一个高级工程师写交接文档                           │
│  他什么都会，只是不了解"你这个项目的特殊情况"               │
│  你只需要写特殊情况，不需要教他基础知识                     │
│                                                          │
└──────────────────────────────────────────────────────────┘

分析这个项目的完整结构，帮我生成一份 CLAUDE.md 初稿，
包括项目概述、技术栈、目录结构、编码规范和常用命令

/init

# DevPulse 项目说明

## 项目概述
DevPulse 是一个基于 Next.js 14 的技术博客平台，支持 Markdown 文章发布、
用户认证、评论互动和全文搜索。面向技术社区，部署在 Vercel 上。

## 技术栈
- 框架：Next.js 14.x（App Router，不使用 Pages Router）
- 语言：TypeScript 5.x（strict 模式，tsconfig 中 strict: true）
- 样式：Tailwind CSS 3.x（不使用 CSS Modules）
- ORM：Prisma 5.x + PostgreSQL 16
- 认证：NextAuth.js v5
- 部署：Vercel（自动部署 main 分支）

## 项目结构
src/
├── app/              # App Router 页面和布局
│   ├── (auth)/       # 认证路由组（登录、注册）
│   ├── (blog)/       # 博客路由组（文章列表、详情）
│   ├── api/          # API Routes
│   └── layout.tsx    # 根布局
├── components/       # 可复用组件
│   ├── ui/           # 基础 UI（Button、Input、Modal 等）
│   └── features/     # 业务组件（ArticleCard、CommentBox 等）
├── lib/              # 工具函数、配置、第三方封装
├── types/            # TypeScript 类型定义（全局共享类型）
└── prisma/           # 数据库 schema 和迁移文件

## 编码规范
- 组件声明：使用 function 关键字，不用箭头函数导出
  正确：export function ArticleCard() {}
  错误：export const ArticleCard = () => {}
- Props 类型命名：ComponentNameProps（如 ArticleCardProps）
- 服务端组件是默认值，只在需要交互时添加 'use client'
- 禁止使用 any 类型，所有变量和参数必须有明确类型
- import 使用命名导入，避免 default export（组件除外）
- 提交信息格式：type(scope): description（英文）
  示例：feat(blog): add article search functionality

## 常用命令
- 开发服务器：npm run dev
- 生产构建：npm run build
- 类型检查：npx tsc --noEmit
- 代码检查：npm run lint
- 运行测试：npm run test
- 测试覆盖率：npm run test -- --coverage
- 数据库迁移：npx prisma migrate dev
- 数据库客户端：npx prisma studio
- 生成 Prisma 类型：npx prisma generate

## 重要约束
- 所有页面组件默认是 Server Component，数据获取在服务端完成
- 客户端交互组件必须显式标注 'use client'
- 图片必须使用 next/image，链接必须使用 next/link
- API Routes 统一放在 src/app/api/，使用 Route Handlers（不是旧版 API Routes）
- 环境变量在 .env.local 中，不要提交到 Git
- Prisma schema 修改后必须运行 migrate dev 和 generate

# 退出当前会话
Ctrl+D

# 重新启动（不要用 -c 继续，要全新启动）
claude

帮我重构 ArticleCard 组件，拆分成更小的子组件

# My Project

This is a web project. Use React.
Write clean code and follow best practices.

┌────────────┬──────────────────────┬──────────────────────┐
│ 维度        │ ❌ 差的               │ ✅ 好的               │
├────────────┼──────────────────────┼──────────────────────┤
│ 项目描述    │ "一个网站"            │ "基于 Next.js 14 的   │
│            │                      │  技术博客平台"         │
├────────────┼──────────────────────┼──────────────────────┤
│ 技术栈     │ "用了 React"          │ "Next.js 14 + TS     │
│            │                      │  strict + Tailwind"   │
├────────────┼──────────────────────┼──────────────────────┤
│ 编码规范    │ "写干净的代码"        │ "function 声明组件，   │
│            │                      │  Props 命名 XxxProps"  │
├────────────┼──────────────────────┼──────────────────────┤
│ 常用命令    │ 没有                  │ 完整的 dev/build/     │
│            │                      │  test/lint/migrate     │
├────────────┼──────────────────────┼──────────────────────┤
│ 信息密度    │ 3 行                  │ 80-100 行             │
├────────────┼──────────────────────┼──────────────────────┤
│ 效果       │ Claude 不断追问       │ Claude 上手就能干活    │
└────────────┴──────────────────────┴──────────────────────┘

DevPulse/
├── CLAUDE.md                     ← 项目全局上下文
├── src/
│   ├── components/
│   │   └── CLAUDE.md             ← 组件开发规范
│   ├── app/api/
│   │   └── CLAUDE.md             ← API 开发规范
│   └── lib/
│       └── CLAUDE.md             ← 工具函数规范
└── tests/
    └── CLAUDE.md                 ← 测试编写规范

# 组件开发规范

## 文件组织
- 每个组件一个文件，文件名与组件名一致（PascalCase）
- 复杂组件可以建子目录：ComponentName/index.tsx + 子组件
- 基础 UI 组件放 ui/，业务组件放 features/

## 组件结构顺序
1. 'use client'（如果需要）
2. import 语句
3. Props 接口定义
4. 组件函数
5. 辅助函数（组件外部）

## 样式规范
- 优先使用 Tailwind 工具类
- 超过 5 个类名时用 clsx/cn 函数合并
- 响应式断点：sm:640 md:768 lg:1024 xl:1280
- 暗色模式使用 dark: 前缀

## 性能注意事项
- 列表渲染必须有稳定的 key（不用 index）
- 大列表考虑虚拟滚动
- 图片使用 next/image 的 sizes 属性优化加载

# API Routes 开发规范

## 文件结构
- 每个路由放在对应目录下：api/posts/route.ts
- 使用 Route Handler 语法（export async function GET/POST/PUT/DELETE）

## 错误处理
- 所有路由必须有 try-catch 包裹
- 统一错误格式：{ error: string, code: string }
- 使用 NextResponse.json() 返回响应
- 4xx 错误返回用户友好的提示，5xx 记录日志但返回通用提示

## 数据校验
- 请求体用 zod schema 校验
- 校验失败返回 400 + 具体的字段错误信息

## 认证
- 需要认证的路由使用 getServerSession() 检查
- 未认证返回 401，无权限返回 403

~/.claude/projects/devpulse/memory/
├── MEMORY.md           ← 索引文件，启动时加载前 200 行
├── debugging.md        ← Claude 记录的调试经验
├── patterns.md         ← Claude 发现的代码模式
└── api-conventions.md  ← Claude 总结的 API 约定

记住：这个项目的数据库连接偶尔会超时，
如果 Prisma 报连接错误，先检查 DATABASE_URL 是否正确，
再检查 PostgreSQL 服务是否在运行

/memory

┌──────────────────────────────────────────────────────────┐
│         CLAUDE.md vs Auto Memory 分工                     │
├────────────────┬─────────────────────────────────────────┤
│ CLAUDE.md      │ Auto Memory                             │
├────────────────┼─────────────────────────────────────────┤
│ 你写的         │ Claude 自己写的                          │
│ 指令和规范      │ 经验和发现                               │
│ 提交到 Git     │ 本地保存                                 │
│ 团队共享       │ 个人专属                                  │
│ 启动时全量加载  │ 启动时加载前 200 行                       │
│ 你负责维护      │ Claude 自动维护                          │
├────────────────┼─────────────────────────────────────────┤
│ 该写什么：      │ 该记什么：                               │
│ 技术栈、规范、  │ 调试经验、踩过的坑、                     │
│ 命令、架构约束  │ 发现的项目特殊模式                       │
└────────────────┴─────────────────────────────────────────┘

.claude/rules/
├── typescript.md       ← TypeScript 规范
├── testing.md          ← 测试规范
├── api-design.md       ← API 设计规范
└── git-workflow.md     ← Git 工作流规范

---
globs: ["src/**/*.tsx", "src/**/*.ts"]
---

# TypeScript 代码规范

- 禁止使用 any，使用 unknown 替代
- 函数返回值必须有显式类型标注
- ...

# 全局偏好

## 语言和沟通
- 用中文回答问题和写注释
- 代码中的变量名、函数名、commit message 用英文
- 解释技术概念时优先用类比和例子

## 代码风格
- 缩进：2 个空格
- 引号：单引号（字符串）
- 分号：不使用（除非 ASI 有歧义）
- 命名导入优先于默认导入

## Git 习惯
- commit message 格式：type(scope): description
- 每次提交前先跑 lint 和类型检查
- 不要自动 push，commit 后等我确认

## 回答偏好
- 直接给解决方案，减少铺垫
- 代码修改时说明"为什么"改，不只是"改成什么"
- 有多种方案时列出优劣对比，让我选择

┌──────────────────────────────────────────────────────────┐
│         CLAUDE.md 维护策略                                 │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  个人项目 / Side Project                                  │
│  ├── 启动时让 Claude 分析并更新：                          │
│  │   "检查 CLAUDE.md 是否与当前项目一致，有过时内容就更新" │
│  └── 频率：感觉不准的时候随时更新                          │
│                                                          │
│  团队项目                                                 │
│  ├── 纳入 Code Review 流程                                │
│  │   → 修改 CLAUDE.md 必须有人 review                    │
│  ├── 指定一个 owner 定期维护                              │
│  └── 频率：每两周或每个 Sprint 检查一次                    │
│                                                          │
│  维护信号（出现以下情况就该更新了）：                       │
│  ├── Claude 生成的代码经常不符合规范                       │
│  ├── 你发现自己在会话中反复纠正同一件事                    │
│  ├── 项目新增了重要的依赖或架构变更                        │
│  └── Code Review 中发现 Claude 遗漏了某个约定              │
│                                                          │
│  大小控制：                                                │
│  ├── 理想：80-120 行                                     │
│  ├── 上限：150 行                                        │
│  ├── 超了怎么办 → 拆分到子目录 CLAUDE.md 或 rules/        │
│  └── 用 @docs/xxx.md 引用详细文档，不要全塞进来            │
│                                                          │
└──────────────────────────────────────────────────────────┘

读一下 @CLAUDE.md，对比当前项目实际的 package.json 和 tsconfig.json，
看看有没有过时或者不一致的信息，如果有就帮我更新

# [项目名] 项目说明

## 项目概述
[一句话描述项目用途]

## 技术栈
- 框架：Nuxt 3.x（使用 Composition API，不使用 Options API）
- 语言：TypeScript（strict 模式）
- 样式：UnoCSS / Tailwind CSS
- 状态管理：Pinia
- 请求：useFetch / useAsyncData（Nuxt 内置）
- 部署：[Vercel / 阿里云 / 腾讯云]

## 编码规范
- 组件使用 <script setup lang="ts"> 语法
- Props 使用 defineProps<PropsType>() 声明
- Emits 使用 defineEmits<EmitsType>() 声明
- 组合式函数放在 composables/ 目录下，以 use 开头命名
- 页面组件放在 pages/，布局放在 layouts/
- 服务端 API 放在 server/api/

## 常用命令
- 开发：npm run dev / pnpm dev
- 构建：npm run build
- 类型检查：npx nuxi typecheck
- 代码检查：npm run lint