1. 为什么我最终整理了一套自己的 claude-code-templates先交代一下背景。我大概从第一版 CLI 发布就开始用 Claude Code 写代码最开始的体验确实是惊艳但用了一周之后问题就逐渐暴露了同一个仓库里今天让它改个函数明天让它写个测试后天又让它做代码审查每次都要在对话里反复解释项目结构、技术栈、代码风格、命令怎么跑。稍微复杂一点的仓库上下文一长前面说过的约束它转头就忘。你可能也有这种感觉——Claude Code 本身很强但默认状态下的它更像一个什么都会一点、但对你项目一无所知的通用助手。你指望它写出符合团队风格的代码它给你的却是看起来对但细节总差一点的东西。网上其实已经有不少 claude-code-templates 相关的项目和讨论但很多要么只给一份写满规则的 CLAUDE.md要么就是把提示词堆得极其臃肿。我后来干脆放弃直接照搬自己整理了一套模板配合 CLAUDE.md、自定义斜杠命令、Hook 脚本三个维度使用跑了一段时间之后效率提升非常明显。这篇文章不打算只给你一份模板文件而是想把我的整理思路、每一个配置背后的原因、实际用起来的感受、还有踩过的坑完整地讲一遍。你如果也在用 Claude Code或者正准备系统化地用它干活这篇文章应该对你有用。2. 模板库的整体设计与目录分层逻辑在动手写内容之前我先想清楚了一件事模板不是写给 Claude 看的说明书而是给项目和编码助手之间建立的一套协作协议。协议太复杂没人执行协议太简单覆盖不了场景。所以我的目录结构围绕项目级信息、命令层、钩子层三块来设计。2.1 我从目录设计开始而不是从提示词开始很多人整理模板有个误区一上来就写你是一个资深工程师这种角色设定。实际上 Claude Code 本身就是工程师水平缺的不是角色感而是对你项目的具体认知。所以我把重点放在结构上目录长这样claude-code-templates/ ├── README.md ├── project/ │ ├── CLAUDE.md # 项目级规则放到仓库根目录 │ ├── frontend.CLAUDE.md # 前端专项规则 │ └── backend.CLAUDE.md # 后端专项规则 ├── user/ │ └── CLAUDE.md # 用户级规则放到 ~/.claude/ ├── commands/ │ ├── review.md # 自定义命令代码审查 │ ├── refactor.md # 自定义命令重构 │ ├── test.md # 自定义命令写测试 │ └── explain.md # 自定义命令解释代码 ├── hooks/ │ ├── pre-tool-use.ts # 工具调用前拦截 │ ├── stop.ts # 回答结束后处理 │ └── settings.json # 钩子开关配置 └── contexts/ ├── api-design.md # 接口设计上下文 ├── db-migration.md # 数据库迁移上下文 └── frontend-style.md # 前端样式上下文这套结构解决的核心问题是把放之四海而皆准的规则和某个项目特有的规则分离开。通用规则放在用户级目录项目特性放进项目级文件临时任务由斜杠命令临时加载。这样Claude 在启动时加载的内容量是可控的不会因为规则太多导致真正重要的指令被稀释。2.2 目录每一层到底放什么内容项目级的 CLAUDE.md 是核心我的写作顺序固定如下这个顺序很重要后面我会解释为什么项目一句话描述让 Claude 立刻知道自己在哪个项目里。常用命令构建、测试、Lint、格式化命令必须写全。Claude Code 有工具可以直接读 package.json但如果类目很多显式给出更可靠。代码组织结构只用一两句话描述核心目录划分比如src/components 放 UI 组件src/lib 放无业务逻辑的工具函数。代码风格约束不用泛泛的写干净代码而是写硬性规则比如错误处理必须走 AppError 类禁止裸抛 Error。测试要求比如新功能必须补单测覆盖率不低于 80%。用户级~/.claude/CLAUDE.md我放的是跨项目统一的偏好比如代码里中文注释的规范、提交信息格式、遇到不确定的 API 时先去翻文档而不是猜。这部分内容不依赖任何特定项目一次配置全局生效。commands 目录里每个文件都是一个独立的斜杠命令定义hooks 目录则用 TypeScript 脚本在特定时机拦截或修改 Claude 的行为。这三个层级各自独立组合起来才是一个完整的模板体系。3. 核心文件实战拆解CLAUDE.md、commands、hooks 分别怎么写这一节是全文最实操的部分。我不只给文件内容更重要的是讲清楚每个字段为什么这么写、实际运行时的效果如何。3.1 CLAUDE.md 的写法规则具体到能被检查而不是被感受先看一段我当时给一个 Node.js 后端项目写的 CLAUDE.md 精简版你可以直接抄# 项目OrderService ## 一句话描述 订单服务的后端处理下单、支付回调、库存扣减使用 Node.js TypeScript Fastify。 ## 常用命令 - 安装依赖: pnpm install - 启动开发: pnpm dev - 运行测试: pnpm test - 测试监听: pnpm test:watch - 代码检查: pnpm lint - 格式化: pnpm format ## 目录结构 - src/domain: 纯业务逻辑不依赖框架 - src/infra: 数据库、Redis、外部 API 客户端 - src/api: 路由和请求参数校验 - src/app: 组装应用的地方 ## 编码约束 1. 禁止使用 any必须显式定义类型。 2. 所有错误必须包装成 AppErrormessage 字段为面向用户的中文描述。 3. 数据库查询必须走 repository 层禁止在路由里直接写 SQL。 4. 新逻辑必须配套单元测试涉及外部 API 的用 mock。 5. 函数名用动词开头布尔返回值用 is/can/should 开头。 ## 安全边界 - 不要修改数据库迁移文件。 - 不要修改已经发布的 API 契约。 - 支付相关代码改动前先检查是否有幂等处理。你注意看我没有写请写出优雅的代码这种句子因为这种指令 Claude 无法量化。我写的是禁止使用 any必须走 repository 层这种可以直接检查的规则Claude 在执行的时候才真正有章可循。这里有个关键的心得CLAUDE.md 不是越长越好。Claude 的上下文窗口虽然大但超过一定长度后后面的内容对行为的约束力会显著下降。我实测下来把核心规则压缩在 40 行以内、把冷门规则放进子文件按需加载效果远好于一份 200 行的大而全规则。3.2 commands 的写法让你的高频操作变成一条命令自定义斜杠命令是 claude-code-templates 里最有价值也最容易被忽略的部分。Claude Code 内置了/review、/test等命令但很多时候内置命令的提示词是通用型的不贴合你的项目。比如我想让代码审查更贴合团队规范就在 commands/ 目录下新建 review.md# 执行代码审查 你正在对一个 Pull Request 做代码审查。请严格遵循以下流程 1. 阅读本次改动的全部 diff不要只看摘要。 2. 依次检查以下维度 - 类型安全有没有 any、类型断言、未处理的 null/undefined。 - 错误处理有没有裸 throw、吞掉异常、缺少错误上下文。 - 性能隐患循环内有没有发请求/查数据库。 - 业务正确性有没有破坏幂等、并发安全问题。 3. 最终输出格式 - 高风险问题必须修复给出具体文件行号和修复建议。 - 中风险问题建议修复说明理由。 - 低风险问题风格类仅供讨论。 如果本次改动少于 50 行可以更快完成但结论必须完整。这个命令是在项目里输入/review后触发的。它和内置 review 最大的区别是我明确告诉它必须看 diff 全文并且给了它幂等、并发安全这种贴合我们业务的关键词。实际用下来审查质量提高了一个档次。再比如写测试命令我可以指定测试框架习惯和 mock 规则# 编写单元测试 根据用户选中的函数或模块生成单元测试。 要求 1. 使用 vitest 和 testing-library/react如果是 React 组件。 2. 测试文件命名test.js/tsx 与源文件同目录。 3. 覆盖核心逻辑分支包括异常分支不追求覆盖率数字。 4. mock 外部依赖时mock 的返回值必须符合真实类型。 5. 每个测试用例用中文描述意图注释不用写。 先列出测试计划再写代码写完跑一遍测试如果失败回去修复。运行的时候只要在对话中输入/test选中目标文件Claude 就会按照这套流程来执行。它的意义是把你希望 AI 怎么做沉淀成可复用的模板而不是每次重新描述一遍。3.3 hooks 的设置什么时候才真正用得上Hook 是 claude-code-templates 里最容易被忽略、也最容易出问题的模块。我用hooks/settings.json配置了两个比较轻量的钩子{ hooks: [ { matcher: PreToolUse, hooks: [ { type: command, command: node .claude/hooks/check-sensitive-files.mjs, tools: [ Write, Edit ] } ] } ] }这个 hook 的作用是在 Claude 写文件之前先跑一个 Node 脚本检查目标路径是不是敏感文件比如生产环境配置文件、密钥文件如果是就直接拦截并返回警告。这种防护型 hook 的价值在于可以防止 Claude 在修改代码时不小心覆盖掉不该动的东西。我用的另一个 hook 是 Stop 钩子在每次回答结束前做个轻量清理。说实话复杂 hook 我并不推荐新手一上来就尝试因为调试成本不算低。我自己刚开始用 hook 时还踩了一个挺深的坑后面会专门讲。3.4 一键引入模板的脚本省去手工复制最后我还在整个项目根目录放了一个install.sh作用是自动把模板安装到目标项目的.claude目录和用户目录#!/usr/bin/env bash set -euo pipefail TARGET${1:-.} CLAUDE_USER_DIR$HOME/.claude if [ ! -d $CLAUDE_USER_DIR ]; then mkdir -p $CLAUDE_USER_DIR fi if [ -f $CLAUDE_USER_DIR/CLAUDE.md ]; then echo 检测到已存在的用户级 CLAUDE.md跳过如需更新请手动替换 else cp user/CLAUDE.md $CLAUDE_USER_DIR/CLAUDE.md fi if [ -d $TARGET/.claude ]; then echo 检测到已有 .claude 目录先备份到 .claude.bak cp -r $TARGET/.claude $TARGET/.claude.bak fi mkdir -p $TARGET/.claude/commands mkdir -p $TARGET/.claude/hooks cp project/CLAUDE.md $TARGET/CLAUDE.md cp commands/*.md $TARGET/.claude/commands/ cp hooks/settings.json $TARGET/.claude/hooks/settings.json echo 模板安装完成。这个脚本把手工复制变成了一个命令看起来简单但实际用起来非常省事。我经常同时维护多个项目跑一遍脚本几秒钟就能把一套共识同步到新项目。4. 从零到一落地真实项目的模板化改造过程说了这么多理论我拿一个真实经历过的小项目来走一遍完整流程。这个项目是一个内部的数据看板前端技术栈是 React TypeScript Vite不算复杂但问题很典型。4.1 改造前默认状态的翻车现场在模板化之前我试着让 Claude Code 给这个项目加一个按日期范围筛选数据的功能。它打开相关组件开始改我给的需求是过滤条件变化时重新请求接口结果它写了一版筛选组件把请求逻辑直接塞进了组件内部没走项目里统一的 useApi hook样式也用的是内联 style跟项目里的 tailwind 体系完全不搭。问题出在哪不是 Claude Code 能力不行而是它根本不知道这个项目有 useApi 这个封装也不知道样式必须用 tailwind。默认状态下它只能按通用最佳实践写而通用最佳实践不等于你项目的最佳实践。4.2 改造过程一步步把项目共识喂给它我先写好该项目的 CLAUDE.md内容覆盖几个关键点项目里所有接口请求必须走src/api/index.ts里导出的 useApi 方法不允许直接用 axios。样式优先使用 Tailwind classes不允许内联 style。新组件放src/components/下首次创建时同步写一个 Storybook story。然后把常用检查命令做成了斜杠命令/check让它能一次性执行 lint typecheck test# 运行项目检查 执行以下命令并报告结果 1. pnpm lint 2. pnpm typecheck 3. pnpm test -- --run 如果 lint 或 typecheck 有错逐条解释错误原因给出修改建议不要擅自修改代码。最后在 CLAUDE.md 里加入了一条硬规则动手前先看现有代码的模式比如查一个现有组件怎么调用 useApi再照着那个模式写。这条规则对前端项目特别有效因为保持一致是最重要的工程要求。4.3 改造后的效果同样任务反馈质量完全不同改造后的效果是立竿见影的。同样做日期筛选功能Claude Code 这次的做法是先调了一下现有组件库的结构和 useApi 的用法然后用了项目里的 DatePicker 组件样式用 Tailwind class 补齐请求逻辑也走了统一封装。更有意思的是当我让它加一个导出 CSV按钮时它主动在评论里指出项目里好像还没有过 CSV 导出的先例它建议我考虑放一个新工具函数到src/lib/目录并询问是否要补测试。这种有意识的、符合项目语境的主动思考正是我期待的状态。我不是要把这个结果吹得神乎其神——这个项目本身不大规则也相对好梳理。但这件事充分说明了一个观点用 Claude Code 的效率下限由模型决定上限由你的模板质量决定。5. 模板化之后踩过的坑和排查思路模板不是装完就万事大吉的下面这几个问题都是我实际遇到过、并且花了一些时间才定位到根因的写出来帮你省掉排查的时间。5.1 命令不生效自定义命令和内置命令的优先级问题有阵子我发现/review明明写好了但执行出来的效果却跟内置 review 几乎一样。我检查了半天把配置文件翻了个遍最后才意识到我把自定义命令文件放到了项目根的.claude/commands/review.md但项目里同时存在一个同样名字的内置命令。Claude Code 对命令的解析方式跟我预期的不一样——它优先识别内置命令或者自定义命令文件格式有问题导致被跳过。具体来说自定义斜杠命令文件要求第一行是# 命令名且扩展名必须是.md。我之前用的是review.txtClaude Code 根本不认。排查链路先执行/看看命令列表里有没有你定义的命令。没有的话检查命令文件名是.md还是.txt。检查第一行是不是# 命令名称。检查文件是否放在了正确的目录项目级是.claude/commands/用户级是~/.claude/commands/。5.2 上下文被塞爆模板写太多的反噬另一个常见问题是模板里的规则越来越多最终导致每条命令执行时都要携带超长上下文。这个问题的表现很隐蔽Claude 不会报错但行为会变笨。它开始忽略你写在后面的规则或者答非所问。根本原因在于Claude Code 每次对话开始时会把 CLAUDE.md、命令内容、系统提示词一起算进上下文。当这些内容超过一定比例后模型对具体指令的注意力会被稀释。我的解决办法是分层用户级 CLAUDE.md 只保留绝对必要的通用偏好控制在 20 行内。项目级 CLAUDE.md 控制在 40-60 行只写违反就会出问题的硬规则。场景化的规则比如数据库迁移规范放进 contexts/ 目录用时通过附加指令加载。我曾经有个模板项目级 CLAUDE.md 写到了 150 行里面甚至包含了写代码时注意驼峰命名这种废话执行效率反而更低了。删掉一半之后效果立刻回来。5.3 Hook 回调风暴一个不小心触发无限循环这个坑比较深。当时我在 hook 里写了一个PostToolUse 自动跑 lint的逻辑想着每次 Claude 改完代码就自动检查一下。听起来挺合理但实际跑起来claude 写一次文件触发 lintlint 发现错误后我又在 hook 返回的内容里让它继续修改代码改完又触发 PostToolUse又跑 lint……就出现了类似回调风暴的循环。这种问题从日志上很难一眼看出来你会看到明明只要求改一处代码它却反反复复改了好多轮而且每轮都伴随着 lint 脚本的执行。排查链路查看 Claude Code 的事件日志在~/.claude下可以开启 debug 模式。确认是哪个 hook 触发了循环PostToolUse 和 PreToolUse 最常见。检查 hook 脚本的返回值如果返回了含decision: block或者要求继续修改的提示它会重新进入工具调用流程形成循环。修复方案hook 里只做拦截敏感行为这类纯判断操作不要做自动修复这类闭环操作。把 lint 结果作为建议写在返回内容里让模型在下一轮正常对话中消化而不是用 hook 强制驱动。Hook 是好东西但在 claude-code-templates 里它应该做守门员而不是做教练。守门员只要挡危险动作教练的职责应该交给 CLAUDE.md 里的规则。5.4 模板和项目的时效性忘了更新导致误导最后一个坑算是我给自己的提醒模板是有生命周期的项目在演进模板里的规则如果跟不上反而会产生误导。这个项目的典型表现是两个多月前写的 CLAUDE.md 里写着数据库访问走 TypeORM结果项目中间迁移到了 Prisma但 CLAUDE.md 没同步更新。后续所有对话里 Claude 都在 TypeORM 的假设下工作写的代码跟现状完全脱节。我现在的做法是在模板的 README.md 里标注了最后审查日期每次项目有架构级变更换了 ORM、改了请求库、调整了目录结构就顺手把 CLAUDE.md 相关的行更新掉。这个习惯比任何技术技巧都重要。6. 从模板库到个人工作台后续还能怎么扩展说到扩展我不建议你把 claude-code-templates 当成静态仓库一次性用完就扔。它本质上是你和 Claude Code 协作的一层自定义壳值得长期维护。我目前正在做的一个扩展方向是代码库生长图谱。具体做法是在用户级 CLAUDE.md 里写一条规则——每当 Claude 新写了一个模块它要同步在项目的.claude/knowledge.md里追加一条记录包含模块名、位置、依赖关系、设计要点。这样几周下来知识文件会自动生长成一个轻量的代码地图。后续对话里如果新任务涉及这个模块可以先让 Claude 读一下 knowledge.md 的相关条目再开始动手。这比每次从零理解代码库要高效得多。另一个方向是把模板和团队的代码审查规范打通。比如 review.md 命令里嵌入了团队规范文档的路径让 Claude Code 在进行 PR 审查时直接读取团队规范输出违反第几条规范的结论。团队规范本身也会更新但模板只是引用路径不会耦合具体内容。你可能会问这些扩展是不是越搞越复杂我的观点是模板复杂度要和你的使用频率成正比。如果你只是偶尔用 Claude Code 写个脚本用户级 CLAUDE.md 就足够了不需要上 commands 和 hooks。但如果你像我一样每天都靠它写代码、做审查、跑重构那花一两天时间把模板体系搭好长期回报是非常可观的。我在实际维护这套模板时最大的感受是不要追求一劳永逸的完美模板把它当做一个随项目成长而持续打磨的配置文件。今天添一条规则明天删一条过时的约束慢慢地你会发现Claude Code 在你手里表现得越来越像一个真正融入团队的结对编程伙伴而不是一个每次都需重新磨合的临时工。