刚开始用 Claude Code 的时候我跟绝大多数人一样直接在终端里敲一句话让它帮我写代码、改 bug。用着用着就发现不对劲每次开新会话它都不认识我项目的结构不知道我的代码规范连测试命令都要我重新说一遍。直到我认真折腾了claude-code-templates这套模板体系才算是真正把 Claude Code 用顺了。这篇东西就是我自己在项目里沉淀下来的模板设计思路、可直接抄的配置文件和踩坑记录希望能让你少走点弯路。1. 为什么需要一套 Claude Code 模板体系1.1 没有模板时的真实痛点先说一个很常见的场景。你的项目可能是一个 Spring Boot 后端或者一个 Next.js 前端里面几十个目录、几百个文件。你让 Claude Code 帮你加一个接口它默认会怎么做它会先扫描整个项目结构猜测哪些文件是 controller、哪些是 service然后按照它“觉得对”的方式去改。如果项目结构和它预设的模式不一样它就会把代码写进错误的地方或者生成一堆和你现有风格完全不搭的代码。这还不是最烦的。更烦的是每个新会话都要重新交代背景这个项目的构建命令是npm run build测试要跑pytest代码里日期格式必须用yyyy-MM-dd数据库迁移文件放在哪个目录……你交代过一次第二次开新会话它又忘了因为对话上下文根本不共享。这个问题在团队协作里更明显——不同成员用同一个 AI 工具出来的代码风格五花八门review 的时候能气死人。1.2 模板体系到底解决了什么claude-code-templates本质上是一套“规则注入”的方案。它把项目的背景信息、编码规范、常用工作流、命令封装成固定的模板文件放在项目目录里。每次 Claude Code 启动时会自动加载这些规则于是它从第一句话开始就“知道”自己在一个什么样的项目里、应该按什么方式干活。这套东西能带来几个非常直接的好处。第一是会话间的“记忆力”你不必每次重复描述项目背景第二是输出的一致性同一套模板让 AI 在不同时间、不同人手里产出的代码风格趋同第三是可复用性新项目克隆过来把模板目录复制进去立刻就有了一套标准化的 AI 助手行为准则。我个人的体会是配好模板之后Claude Code 的可用性提升至少两个档它从一个“偶尔聪明偶尔犯浑的对话机器人”变成了一个真正懂你项目的协作者。1.3 适用场景和读者画像如果你符合下面任一情况这套模板体系值得你花半小时配置一下每天要开好几个 Claude Code 会话处理同一个项目的人在团队里推行 AI 辅助编码、希望统一规范的技术负责人维护多个项目、不想每个项目都重新调教 AI 的独立开发者。当然如果你只是拿 Claude Code 写几个一次性脚本那确实没必要折腾直接对话就完了。下面说的所有内容都是针对“把它当长期工具使”的场景。2. 模板体系的整体设计目录结构与分层思路2.1 先看懂官方加载机制动手写模板之前得先理解 Claude Code 是怎么读取规则的。它有几个主要的配置层级CLAUDE.md放在项目根目录是项目级指令文件只要在这个项目里启动 Claude Code它就会自动加载~/.claude/CLAUDE.md放在用户主目录是全局级文件所有项目都会加载项目根目录下的.claude/commands/和.claude/agents/则用来存放自定义命令和子代理的定义。这些文件彼此之间是叠加关系不是替换关系。也就是说全局规则会加载项目规则也会加载两者并行生效。这就给了我们一个很好的分层设计空间全局文件放那些“不管什么项目都适用的通用偏好”项目文件放“只有这个项目才需要的特定规则”。另外官方也支持在CLAUDE.md里用相对路径引用其他文件比如docs/architecture.md这个机制可以用来拆大文件避免一个文件塞得满满当当。2.2 我的模板目录结构长这样下面是我自己项目里实际在用的目录结构你可以直接参考project-root/ ├── CLAUDE.md ├── CLAUDE.local.md ├── .claude/ │ ├── commands/ │ │ ├── code-review.md │ │ ├── test.md │ │ ├── commit.md │ │ ├── changelog.md │ │ └── api.md │ ├── agents/ │ │ └── backend-architect.md │ └── settings.json └── docs/ ├── architecture.md └── coding-standards.mdCLAUDE.md是核心入口内容以“简短、高频、稳定”的信息为主比如项目简介、常用命令、目录职责。CLAUDE.local.md是个人层面的本地规则通常不进版本库放一些只属于你自己的偏好比如“回答时多用中文”“不要主动提议重构”。docs/下的两个文件是被CLAUDE.md通过引用的大文档放架构说明、编码规范这类低频但重要的内容需要时再让 AI 去读避免每次会话都消耗太多上下文窗口。2.3 为什么这样分层这么设计的核心逻辑是“渐进式上下文加载”。我见过很多人的CLAUDE.md写得跟百科全书一样五千字的规范全塞进去结果 Claude Code 每次会话的开销巨大而且重点信息被淹没。正确的思路是高频且短小的指令直接写在CLAUDE.md里让 AI 每轮都看得到低频但重要的资料放在被引用的文档里AI 在需要的时候自己去读用不上就不读。这就像一个团队的 onboarding 手册新人第一天只需要知道打卡时间和工作地点没必要把公司全套规章制度背下来。另外要提醒一句.claude/settings.json这个文件可以用来配置权限比如哪些工具需要用户确认哪些目录允许 AI 读写。我建议在多人协作项目里把需要确认的操作列进去避免 AI 自动改了一堆不该改的文件。这个文件本身也是模板体系的一部分别忽略它。3. CLAUDE.md 项目指令模板可直接抄的版本3.1 完整模板示例这是我从多个项目里提炼出来的一套还算通用的CLAUDE.md你可以根据自己项目的情况增删。注意这不是让你照抄是为了让你看到结构# 项目订单管理系统Order Service ## 项目简介 这是一个基于 Spring Boot 3 MyBatis Plus 的微服务负责订单的创建、支付回调、状态流转。前端仓库另见 order-web本仓库只处理后端逻辑。 ## 常用命令 - 本地启动./mvnw spring-boot:run -Dspring-boot.run.profilesdev - 运行全部测试./mvnw test - 运行单个测试./mvnw test -DtestOrderServiceTest - 代码检查./mvnw spotless:check - 打包./mvnw clean package ## 目录职责 - controller/HTTP 接口层只做参数校验和响应封装 - service/业务逻辑层事务在这里控制 - mapper/MyBatis 接口SQL 写在对应 XML 中 - domain/实体类与领域模型 - common/通用工具、异常、常量 ## 编码规范 - 类名、方法名使用驼峰常量使用大写加下划线 - controller 层统一返回 ResultT 结构错误码见 ErrorCode 枚举 - Service 层接口必须有实现类禁止直接写类内实现 - 金额相关字段一律用 BigDecimal禁止使用 double - 所有时间字段使用 LocalDateTime禁止使用 java.util.Date - 新增数据库字段必须同步修改对应的 XML 映射文件 ## 事务与测试要求 - 涉及钱的状态流转必须在 service 方法上加 Transactional - 每次改动必须补充或更新单元测试覆盖率不得低于新增代码的 80% - 测试禁止连接真实数据库使用 H2 内存库 ## 重要约定 - 修改订单状态时必须走 OrderStateMachine禁止直接改 state 字段 - 支付回调接口是异步通知幂等处理依赖 order_no event_type 去重 - 日志打印统一使用 Slf4j上下文信息放入 MDC3.2 逐段拆解每部分为什么这么写开头那段“项目简介”作用是给 AI 一个最基本的定位锚点。别小看这一句话它能让 AI 在回答问题时自动往“这是一个订单系统”的方向靠而不是泛泛地给一个通用方案。我见过有人在这里写了一大段业务背景什么“本系统旨在提升……赋能……”之类全是废话。简介控制在三到五行说清楚“是什么、用什么技术栈、主要做什么”就够了。“常用命令”这部分价值极高。Claude Code 经常需要自己执行命令来验证代码如果你不告诉它构建和测试命令它就会猜猜错的概率相当高尤其是 Maven 项目它总爱用mvn而很多项目实际用的是./mvnwwrapper。把这些命令写进模板等于是把你平时的肌肉记忆直接复制给了 AI。注意命令要写得具体连 profile 参数、单测过滤条件都要写清楚AI 会严格按字符串去执行。“目录职责”那段是我的私货。很多项目的包名、目录层级并不符合主流约定AI 默认的 Classifier 机制根据类名猜测功能经常会猜错。比如你的项目里有个domain包里面全是贫血模型AI 看到Order类可能以为它是实体结果它其实是 DO。把目录职责写清楚之后AI 找文件的准确率会显著提升。如果你发现 AI 总是把文件放错地方十有八九是缺了这段。“编码规范”和“重要约定”是保命条款。这里面写的东西都是你实打实踩过坑、不希望 AI 再犯的错。比如 BigDecimal 替代 double比如状态流转必须走状态机这些规则一旦被违反代码 review 时必然出问题。我强烈建议你每被 AI 坑一次就往这个文件里补一条规则。一个月下来这个文件会变成你的“AI 调教经验集”。3.3 几个容易忽略的细节写CLAUDE.md的时候有几个细节值得注意。第一个是不要用否定句写规则比如“不要使用 double”经验是 AI 对否定句的遵从度明显低于肯定句改成“金额相关字段一律使用 BigDecimal”效果更好。第二个是规则编号的问题如果你的规则超过十条建议给每条加个编号方便后面跟 AI 说“按规则 7 处理”不然你指代不明它又要犯迷糊。第三个是别把CLAUDE.md当成普通文档来写它是给 AI 看的 Few-shot 上下文示例不是给人看的说明书所以最好用短句、祈使句、结构化列表避免大段散文。4. 自定义 Slash Command 实战把高频操作做成命令4.1 命令模板的基本格式CLAUDE.md解决的是“每轮对话都生效的常驻规则”但有些操作你只会在特定时刻用比如“帮我 review 一下当前改动”“按规范生成 commit message”。这种低频高价值操作适合做成自定义 Slash Command。Claude Code 会在启动时读取.claude/commands/目录下的所有.md文件把它们注册成斜杠命令。格式非常简单--- description: 代码审查检查当前分支的改动 argument-hint: [可选参数比如指定文件路径] --- 你是一名资深代码审查专家。请审查当前分支相对于 main 分支的所有改动。 审查时重点检查以下方面 1. 是否存在潜在的并发问题或事务边界错误 2. 是否有违反项目编码规范的地方见 CLAUDE.md 3. 是否有安全漏洞特别是注入、越权、敏感信息泄露 4. 单元测试是否覆盖了主要逻辑分支 输出格式先列出“必须修改”的问题再列出“建议优化”的问题最后给一个总体评价。这个文件本身就是一个 prompt 模板。当你输入/code-review的时候Claude Code 会把这段 prompt 作为执行指令并且会把当前上下文里的文件信息自动带上。argument-hint是给用户看的参数提示比如你可以写“指定文件或目录不填则默认全部改动”。4.2 我的几个常用命令模板除了上面那个 review 命令我再分享几个我用得最频繁的。一个是测试执行命令。直接对话里跟 AI 说“跑一下测试”它常常会跑全量测试慢得要死。我写了一个/test命令让它先读取package.json里的 scripts 配置再根据用户传入的参数只跑指定模块的测试跑完之后还要汇总失败用例和堆栈信息。如果没传参数就只跑和当前 git diff 相关的文件对应的测试。这个命令帮我省了大量等待时间。另一个是/commit命令。我把它绑定到项目自己的 commit 规范上模板里写明 commit message 的结构type(scope): descriptiontype 必须是 feat/fix/docs/refactor/test/chore 之一description 用祈使句、不超过 50 个字符。AI 会先git diff和git status查看改动再按规范生成 3 个候选 message 让我选。这样既保证了信息完整又省去我手写提交信息的功夫。还有/changelog命令用来生成两个版本之间的变更记录。模板里给 AI 一个清晰的输出格式新增、修复、变更、移除四个分组每个分组下列出对应的 commit 标题并标注影响范围。因为 Claude Code 能读 git log这个命令的准确性其实相当高。最后提一下/api命令让 AI 根据docs/api-design.md里的约定生成一个新接口的 controller、service 和测试文件省去重复的 CRUD 劳动。4.3 进阶用 Bash 脚本做命令不是所有命令都适合用纯 Markdown prompt 实现有些需要真正执行本地逻辑。Claude Code 的命令文件支持在 Markdown 里嵌入可执行代码块也支持直接写带 shebang 的脚本文件。我举个例子我的/init-project命令是一个 bash 脚本做的事情是从模板仓库拷贝CLAUDE.md、创建.claude/commands目录、根据用户输入的项目类型生成对应的settings.json。这种“配置生成器”类型的命令用脚本写比用 prompt 写要稳定得多。这里要提醒一个坑脚本文件需要可执行权限。我一开始把脚本放进去之后怎么调用都报“command not found”检查了一圈才发现是chmod x没做。另一个坑是路径问题脚本里如果用相对路径它的基准目录是命令文件所在目录不是项目根目录最好在脚本开头用cd $(dirname $0)/../..之类的方式固定工作目录不然在不同项目里行为不一致排查起来很痛苦。5. 工作流模板让项目启动、团队协作都有章法5.1 新项目初始化工作流模板体系不只能服务单个项目内的小操作它还能帮你标准化“从零开始一个新项目”的流程。我给自己建了一个“项目脚手架”模板集里面包含一个初始化命令和一套目录模板。新建项目的时候我会先执行mainframe init风格的一串命令具体看你的工具链然后把项目类型、技术栈、包名等参数填进去剩下的目录结构和配置文件由 AI 按模板生成。这背后的思路是把你自己过去两三年建项目时积累的最佳实践固化成一堆可复用的模板文件。比如对于 Node.js 项目我的模板里固定包含src/、src/modules/、test/、docs/这些目录并且CLAUDE.md里写清楚了每个目录的职责边界。这样新项目的 AI 助手从一开始就有一个好骨架不会一上来就把代码堆在根目录。5.2 团队标准化把模板放进 Git 仓库如果你在一个团队里工作模板体系的收益会被放大很多倍。我建议把.claude/目录和CLAUDE.md提交到 Git 仓库里让每个成员 clone 之后自动拥有同一套 AI 行为准则。这比在 wiki 里写十页“AI 使用规范”有效得多——因为规则不是给人看的是直接注入到 AI 上下文里生效的。成员自己也可以往.claude/commands/里加命令通过 MR 合入团队里的命令库会越用越丰富。但在团队环境里要特别注意隐私和保密问题。.claude/目录里如果写入了敏感信息比如内部服务地址、密钥占位符、未公开的业务规则一旦仓库权限管控不严就会泄露。我的建议是敏感信息不要写进模板必要的话用环境变量引用并在.gitignore里排除CLAUDE.local.md这类个人配置文件。5.3 子代理模板术业有专攻Claude Code 的.claude/agents/目录允许你定义专用子代理每个子代理有自己的系统提示词、可用工具列表和模型配置。我个人的实践是定义了一个backend-architect子代理它的职责是“在动手写代码之前先输出一份模块设计文档”包括数据模型、接口定义、依赖关系。主对话收到复杂需求时可以让它先派子代理去思考设计再回来写实现。这种“先设计后编码”的工作流在改动核心模块时特别有用能避免 AI 一上来就闷头写代码写到一半发现方向错了。5.4 会话启动模板一个固定起手式最后一个建议是给自己设计一个“会话开场模板”。我每次开始一个大需求时会在所有对话的最前面粘贴一段固定的话先用一句说明需求背景再告诉 AI “在动手前先阅读 CLAUDE.md 和 docs/architecture.md然后列出你的实施计划和需要我确认的问题确认后再开始写代码”。这相当于给 AI 一个“元指令”防止它一上来就自作主张。你完全可以把这段话做成一个plan命令让它固定执行这个流程。6. 常见问题与排查技巧实录6.1 模板不生效AI 还是瞎搞很多人配置完模板之后发现 AI 的行为没什么变化于是以为模板没用。根据我的排查经验最常见的原因有三个文件名写错了Claude Code 只认CLAUDE.md这个名字多一个字母少一个字母都不行路径放错了全局配置应该放在~/.claude/CLAUDE.md项目配置放在项目根目录如果放进了.claude/子目录可能有不一样的行为还有一个是大小写问题在 Linux 系统上Claude.md和CLAUDE.md是两个不同文件务必保持一致。6.2 命令文件不显示或报 Not Found自定义命令不显示先检查两件事一是命令文件是否在.claude/commands/目录下且后缀是.md或可执行文件二是重启会话没有。Claude Code 通常在会话启动时扫描命令启动之后新放进去的文件可能要重开会话才能识别。如果命令能显示但执行报错大概率是 frontmatter 写错了比如description或argument-hint的格式不对或者脚本没有执行权限。遇到这种情况我的排查套路是先用claude --help或官方日志看执行时的详细报错。6.3 上下文窗口被占满AI 越聊越蠢模板文件太多或者CLAUDE.md里塞了大量内容会占用上下文窗口导致 AI 在长对话中段开始“忘事”。我在实际使用中的感受是CLAUDE.md的推荐量级在几十行以内超过 200 行的项目规则建议拆到外部文档用引用。另外如果一轮对话实在太长直接开新会话反而更清醒——因为模板是自动加载的新会话并不会丢失项目背景知识你只需要把当前任务的中间产物用文件或者git commit固化下来新会话可以接得上。6.4 模板和实际代码不一致的问题这个问题在项目演进过程中几乎一定会出现模板里写的规范还停留在三个月前代码已经换了新风格。比如你从 MyBatis 换成了 JPA但CLAUDE.md里还写着“SQL 写在 XML 中”AI 就会照着旧规范给你写已经不存在的 XML 映射。解决方案没有捷径就是定期维护模板。我现在每完成一个迭代都会扫一遍.claude/目录把过时的规则更新掉。也可以让 AI 帮忙做这件事专门开一个会话让它对比当前代码风格和模板规则输出需要同步修改的清单。6.5 安全边界哪些不该写进模板最后说个安全上的经验。模板是给 AI 看的但它也可能被输出到对话里或者通过错误日志泄露。不要在里面写真实密码、token、内部 IP不要写“忽略安全检查”这类僭越性指令企业项目里的未公开业务策略尽量用泛化描述代替具体数据。设定权限边界也很重要比如.claude/settings.json里可以配置哪些文件目录只读哪些工具需要二次确认避免 AI 在无人监督时改动基础设施文件。模板体系对我来说最大的意义是让我从“反复给 AI 解释项目背景”的琐碎劳动中解放出来了。现在新开一个会话我只需要说一句“帮我实现这个功能”它就自动进入状态。这套东西没什么高深的理论就是把该沉淀的沉淀下来该分工的分工出去。如果你之前没用过模板我建议从最小的CLAUDE.md开始不要一上来就想搭一套完美体系先把最常被 AI 搞错的三条规则写进去用起来之后再逐步添加命令和工作流。模板是活的它应该随着你项目和经验的成长一起迭代。
