CLAUDE.md 模板库 — Claude Code Arsenal

$ cat CLAUDE.md · TEMPLATES

四层记忆模板 · 复制即用

四层各司其职:全局管行为,项目管事实,目录管局部,local 管隐私。以下模板依据官方文档与社区最佳实践编写并刻意保持精简——请以它为骨架填入你的真实信息,而不是原样照贴。

memory-hierarchy — 记忆加载层级

~/.claude/├── CLAUDE.md ← 全局启动加载└── skills/← 个人 Skills · 全项目可用~/work/my-app/← 你在这里运行claude├── CLAUDE.md ← 项目 · 随 git 共享启动加载├── CLAUDE.local.md ← 个人偏好gitignore├── .claude/skills/← 项目 Skills└── src/ └── CLAUDE.md ← 目录级规则懒加载# 启动时自 cwd 向上收集所有 CLAUDE.md;# 子目录的等 Claude 读到该目录文件才注入;# 兄弟目录互不打扰。

SCOPE·全部项目行为准则层

保存路径

~/.claude/CLAUDE.md

加载时机

每个会话启动即加载,对本机所有项目生效

放什么

跨项目稳定不变的行为规则:沟通语言、破坏性操作确认、工程纪律、环境事实(时区/默认包管理器)

别放什么

任何具体项目的信息——那是项目层的事;也别写人格设定,写不改变行为的话等于浪费注意力

~/.claude/CLAUDE.md

# 全局工作准则(适用于本机所有项目)

## 沟通
- 用中文与我交流;代码、命令、报错信息保持英文原样
- 先给结论再给理由;不确定就直说,不要编造 API 或配置项

## 行为边界
- 删除文件、git push --force、数据库迁移、改 CI 配置等
  破坏性/高影响操作:先说明影响范围,征得我确认再执行
- 永远不要把密钥、token、密码写进代码或提交历史;
  发现 .env / 凭据有泄露风险时主动提醒我
- 不要擅自升级依赖的大版本

## 工程纪律
- 改动最小化:只做被要求的事,不顺手重构、不加多余抽象
- 修完 bug 先运行相关测试再收工
- commit message 用 Conventional Commits(feat/fix/chore/docs…)
- 同一任务连续失败两次时,停下来复述你对问题的理解再继续

## 我的环境
- 时区 Asia/Shanghai;macOS + zsh;Node ≥ 20;包管理器默认 pnpm

SCOPE·本仓库项目事实层

保存路径

仓库根目录 ./CLAUDE.md,提交进 git 与团队共享

加载时机

在仓库内(含子目录)启动即加载

放什么

五件事:命令、结构、约定、雷区、工作流。全是 Claude 读代码猜不出、猜错代价又高的东西;其中「照抄执行的命令」是单条价值最高的信息

别放什么

架构长篇复述(用 @ 引用 docs 即可)、Claude 一个会话就能自学的内容、多步骤流程(该做成 Skill)

./CLAUDE.md

# MyApp — 项目上下文

> 电商后台管理系统 · Next.js 15 + TypeScript + Prisma + PostgreSQL
> 详细架构见 @docs/architecture.md,不在此复述

## 常用命令(照抄执行,不要自行猜测)
- 开发:   pnpm dev
- 全部测试: pnpm test
- 单个测试: pnpm test -- --grep "关键词"
- 质量门:  pnpm lint && pnpm typecheck
- 迁移:   pnpm db:migrate(仅本地库;线上迁移走 CI)

## 目录速览
- app/        路由与页面(App Router)
- app/api/    API 路由,鉴权中间件在 app/api/_lib/
- lib/        领域逻辑与数据访问封装
- prisma/     schema 与迁移
- tests/      e2e;单测与源码同目录 *.test.ts

## 代码约定
- TypeScript strict,禁止 any;组件一律具名导出
- 数据访问只走 lib/db.ts 封装,不要直接 new PrismaClient
- 样式仅用 Tailwind,不写内联 style、不引入新 UI 库
- 新功能必须带 Vitest 用例,放在被测文件同目录

## 雷区(违反会出事故)
- prisma/migrations/ 里已存在的迁移文件一律只读
- app/api/webhooks/* 的签名校验逻辑不许改动
- CI 运行在 Node 20,不要使用更高版本才有的 API

## 工作流
- 涉及 >3 个文件的改动:先给出计划,确认后再动手
- 收工前必须通过:pnpm lint && pnpm typecheck && pnpm test

SCOPE·单个目录局部规则层

保存路径

任意子目录,如 src/components/CLAUDE.md

加载时机

懒加载——Claude 读到该目录下文件时才注入,兄弟目录互不可见,天然节省上下文

放什么

只对这一块代码成立的规则:组件规范、该模块专属的测试方式、monorepo 中各包差异化的构建命令

别放什么

全仓库通用的约定——放上层会被重复加载稀释;若规则被无视,先跑 /memory 确认它是否尚未加载

src/components/CLAUDE.md

# components/ 目录规则(仅在本目录内工作时生效)

- 每个组件独立文件夹:index.tsx + types.ts + *.test.tsx
- 基础控件只从 @/components/ui 取用,禁止引入新组件库
- 状态优先局部 useState;跨组件共享走 zustand(见 @/stores)
- 服务端数据一律经由 hooks/ 内的 query hook,组件内不 fetch
- 新组件必须补同目录 *.stories.tsx(Storybook)
- 可访问性:交互元素必须有可见焦点态与 aria 标签

SCOPE·只有你个人偏好层

保存路径

仓库根目录 ./CLAUDE.local.md,并加入 .gitignore

加载时机

启动即加载,但不随仓库共享——团队规则与个人口味互不污染

放什么

个人环境与偏好:本地服务地址、测试账号指引、你个人的沟通习惯

别放什么

真实密钥与密码——写「去哪取」而不是写值本身;gitignore 不等于安全

./CLAUDE.local.md(记得 gitignore)

# 个人偏好(已 gitignore,不与团队共享)

- 本地数据库:postgresql://localhost:5433/myapp_dev
- 本地服务:web 3000 / api 4000 / mail 预览 8025
- 演示账号:demo@local(密码在团队 1Password「MyApp Dev」)
- 向我解释用中文,commit message 保持英文
- 我用 macOS + zsh,不要给我 Windows 路径或 PowerShell 命令