我自己早就在折腾 Claude Code 的模板体系一开始纯粹是因为重复性劳动太多了——每个新项目都要写一遍环境说明、编码规范、常用命令模型每次都得重新理解一遍我的工作上下文。后来我把这些沉淀成claude-code-templates一套带自定义命令、钩子和项目约定的模板库才算真正把 Claude Code 从聊天窗口变成了能融入团队流程的终端搭档。这篇文章就聊聊这套模板怎么设计、怎么写、怎么落地以及我在实际使用中踩过的一些坑。如果你还不知道 Claude Code 模板能做什么简单说它就是把你和 Claude 协作时的上下文、规则、常用操作固化下来让模型在每次对话里自动加载项目背景、遵守你的代码规范并通过斜杠命令一键执行写测试提交代码做代码审查这类高频操作。适合正在用或打算用 Claude Code 做日常开发的人也适合想统一团队 AI 编程规范的技术负责人。1. 模板这件事为什么值得专门讲1.1 Claude Code 模板到底是什么先把概念理顺。Claude Code 本身是一个运行在终端里的 AI 编程助手它能在你的代码仓库里读文件、改代码、跑命令。而claude-code-templates指的是围绕 Claude Code 建的一套可复用的配置与命令集合它通常包含这几类东西CLAUDE.md文件项目级或用户级的上下文说明书告诉 Claude 这个项目是什么、目录怎么组织、代码风格如何、有哪些约定。自定义斜杠命令比如/review、/test、/build每个命令是一个 Markdown 或其他格式的指令模板能触发一段精心设计的提示词。Hooks 钩子配置在特定事件如编辑文件后、对话开始前自动执行脚本比如自动跑格式化、自动查错。权限与输出控制限定 Claude 可以操作哪些命令、哪些目录避免它乱来。我刚接触时最大的误解是模板不就是把提示词存一下吗实际上远不止。它的核心价值在于把人与模型之间的隐性协作契约转成显性、可版本控制的文件。你不需要每次对话都跟 Claude 解释我们项目用 pnpm不用 npm测试文件放在tests里对外暴露的 API 必须加 JSDoc这些规则写进模板后每次启动它都会自动读取并且在改代码时自动遵守。1.2 模板解决的核心痛点用裸的 Claude Code 工作用久了会有几个明显的痛点几乎每个深耕的人都逃不掉第一上下文反复丢失。对话一开模型不知道你的项目背景你得重新粘贴说明。万一你忘了说某个约定它可能按默认习惯生成不符合项目要求的代码。第二操作不统一。不同人用同一个模型写测试的习惯、提交信息的格式、分支命名规范都可能各写各的。代码仓库会变得越来越乱。第三高危操作缺乏约束。Claude Code 有能力执行 Shell 命令、修改文件如果没有权限控制它完全可能执行一个rm -rf或者把生产环境配置覆盖掉。这不是危言耸听是现实中发生过的事故。第四重复劳动。每次都要口头说帮我跑一下 lint、帮我生成一下接口文档效率很低。如果有一个/lint命令一键搞定整个流程会顺畅很多。模板体系就是冲着这几个问题去的。我实际体会是一套设计良好的模板能让 Claude Code 从一个偶尔可用的玩具变成几乎不会出错的协作者。这也解释了为什么社区里claude-code-templates相关仓库会火——它解决的正是规模化使用 AI 编程助手时的组织问题。2. 模板体系设计与核心文件拆解2.1 CLAUDE.md项目的操作手册CLAUDE.md是整个模板体系的地基。它是 Claude Code 启动时会自动读取的文件作用相当于一份给 AI 看的 README但比 README 更务实——它不写这个项目是做什么的这种空话而是写**在这个仓库里你应该怎么工作**。我建议文件里至少要有这几个段落项目概览与命令入口项目是做什么的安装依赖用哪个命令启动开发环境用哪个命令。目录结构说明哪块代码放哪、新增模块该放哪里、路由或状态管理遵循什么模式。代码风格与约定命名规范、组件写法、错误处理风格、HTTP 接口定义方式。测试约定测试框架是什么、测试文件命名规则、模拟数据的放置位置。变更流程branch 命名、commit message 格式、PR 模板要求。举个例子我的一个前端项目里写的是# Project Context - Tech stack: Next.js 14, TypeScript, TailwindCSS, pnpm - Install dependencies: pnpm install - Run dev server: pnpm dev # Directory Layout - app/ → App Router pages and routes - components/ → Reusable React components - lib/ → Utility functions, API clients, constants - tests/ → Integration tests (Playwright) # Code Style - Use function components, not class components - All exported functions must be typed with explicit return types - Error handling: use a Result pattern, never throw raw exceptions这些规则不需要写得多漂亮但一定要具体、可执行。写得越含糊模型判断的余地就越大最后出来的代码比如不符合预期写得越细Claude 的表现越接近团队资深工程师。另外要注意CLAUDE.md有层级关系。~/.claude/CLAUDE.md是全局的所有会话都会加载项目根目录下的CLAUDE.md是仓库级的项目越多、结构越复杂这样的层级拆分越重要。全局的主要放个人偏好比如默认使用中文回复、代码块里不要用 emoji项目级的放与具体仓库相关的约定。2.2 斜杠命令操作入口的设计CLAUDE.md管上下文斜杠命令则管动作。Claude Code 的自定义命令放在.claude/commands/目录下也有用户级的~/.claude/commands/每个命令是一个 Markdown 文件命令名就是文件名比如.claude/commands/review.md对应/review。斜杠命令的作用是触发一段固定的提示词。关键点在于提示词不是在命令文件里单纯写帮我审查代码这种话而是要给出可执行的、有边界的指令甚至可以在指令里引用项目文件、要求执行特定工具。我写的/review命令长这样--- description: Run a comprehensive code review on the current changes --- You are an expert code reviewer. 1. Run git diff --stat and git diff HEAD to understand the current changes. 2. Focus on logic errors, potential race conditions, memory leaks, and security issues. 3. For each issue found, respond: - [High] description: include file path, line number, and a concrete fix - [Medium] description: include suggested improvement - [Low] style/nitpick: keep to a minimum 4. Do NOT fix the code. Just report the issues. 5. End with a summary table listing all issues sorted by severity.这个命令文件里我明确要求了只报告、不修改避免模型自作主张改动代码。命令文件里还加了 YAML frontmatter用description字段定义这个命令的说明。这样在终端输入/时Claude Code 能列出可用命令和对应描述。命令文件除了放提示词还可以写一些辅助逻辑比如要求模型先读取某个配置文件再开始操作。我最常用的几个命令/test生成或修复测试、/commit生成符合规范的提交信息、/explain解释当前文件或目录的结构、/doc生成文档、/docker生成或检查 Docker 配置。2.3 Hooks让自动化真正自动起来如果说斜杠命令是手动挡hooks 就是自动挡。Claude Code 的 hooks 允许你在特定事件发生时自动执行本地脚本。这对于模板体系来说是画龙点睛的一笔它能确保任何一次 AI 操作都不会跳出你的质量防线。比较实用的 hooks 场景PreToolUse在 Claude 调用某个工具之前拦截检查。比如执行 Shell 命令前过滤掉git push、rm -rf这类危险操作。PostToolUse在工具调用完成后触发。比如每次文件编辑后自动跑 eslint 或自动格式化。Stop在 Claude 完成一轮回复后触发可以用来跑冒烟测试或将变更通知发送到 IM。UserPromptSubmit在用户提交新的提示词之前注入额外的信息。hooks 的作用不能小看。比如我在一个客户项目里配置了PostToolUse钩子每次模型编辑文件后自动跑 prettier结果格式化风格前后一致代码 review 时再也不用纠结空格和分号问题。配置 hooks 用的是 JSON 格式放在.claude/settings.json里。下面是一个简单的示例{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: scripts/guard-dangerous-commands.sh } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: scripts/auto-format.sh } ] } ] } }matcher字段用来匹配工具名Edit|Write表示匹配多个工具名称。hooks 配置好之后Claude 的每次文件编辑都会触发格式化脚本整个过程是无感的。2.4 权限与安全配置模板的安全带权限控制是我在模板体系里最强调的部分。Claude Code 默认能访问文件系统、能执行终端命令如果不设置边界它可能在你没注意的情况下做了破坏性操作。settings.json里有几个关键字段permissions.allow允许 Claude 直接执行的命令列表比如[pnpm test, pnpm lint]。permissions.deny绝对禁止的命令列表比如[rm -rf *, git push --force]。additionalDirectories允许模型访问的额外目录不配置时它只能访问当前项目目录。我的建议是测试类、构建类、格式化类命令尽量放入 allow因为它们相对安全git 写操作、包发布、生产环境相关的命令一律不加白名单。每次 Claude 需要执行一个不在 allow 列表里的命令时它会在终端里停下并向你确认这个确认的过程你可以慢慢习惯它相当于一道安全带帮你拦截了不少低级失误。遇到确实不常用但又有正当需求的命令怎么办我一般不会直接放行而是让 Claude 在执行前说明理由我再决定是否批准。这样做虽然多了几个确认步骤但远比事后收拾一个失控的 AI 操作成本低。3. 从零构建一套可用模板实操全流程3.1 初始化模板目录结构我们直接开始搭建。先创建一个模板项目目录结构参考这样claude-code-templates/ ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── commit.md │ │ ├── explain.md │ │ └── doc.md │ ├── settings.json │ └── CLAUDE.md ├── scripts/ │ ├── auto-format.sh │ └── guard-dangerous-commands.sh ├── README.md └── .gitignore先创建目录mkdir -p .claude/commands mkdir -p scripts这套目录结构里有几个地方需要注意.claude/commands/是斜杠命令的存放目录命令文件扩展名必须是.md文件名就是命令名。scripts/里放 hooks 要执行的脚本我坚持把脚本和配置分开这样 hooks 的command字段可以简洁地指向脚本路径。.gitignore里要把CLAUDE.md的本地变体和一些用户级配置文件排除掉避免团队历史的个人偏好被提交到公共分支。3.2 编写项目级 CLAUDE.md在项目根目录创建CLAUDE.md这是模板的灵魂文件。前面提到过内容框架这里我直接给一份我实际在 TypeScript 服务端项目里使用的模板你可以按需调整# CLAUDE.md ## Project Overview TypeScript API server built with Fastify. Uses PostgreSQL via Prisma ORM. ## Commands - pnpm install — install dependencies - pnpm dev — start dev server with hot reload - pnpm build — compile TypeScript - pnpm test — run unit tests (Vitest) - pnpm lint — run ESLint ## Directory Structure - src/ — source code - routes/ — Fastify route definitions - services/ — business logic layer - repositories/ — data access layer (Prisma) - schemas/ — Zod validation schemas - test/ — test files, mirror src structure - prisma/ — Prisma schema and migrations ## Code Conventions - Use async/await over .then() chains - Validate input at the route layer using Zod schemas - Error handling: throw typed ServiceError; route layer maps to HTTP responses - Naming: files kebab-case, exports PascalCase for classes, camelCase for functions - Database access through repositories, not in routes or services ## Testing - Test files named *.test.ts - Use Vitest, no Jest - Mock external services at the network boundary (use MSW) - Each service should have at least one success and one failure test case ## Git Workflow - Branch naming: feature/, fix/, chore/ - Commit message format: type(scope): description - Example: feat(orders): add status endpoint - Create PR with reference to issue number写完后你可以直接开一个新会话验证输入这个项目的测试命令是什么Claude 应该能从CLAUDE.md里找到答案而不是瞎猜。这里有个原则CLAUDE.md 只写事实和规则不写主观论述。你不需要写这个项目很重要这类话AI 不需要情感激励它只需要明确的指令和约束。3.3 自定义斜杠命令的编写方法斜杠命令要设计得有明确输入、有执行边界、有输出格式。我的经验是一个命令文件控制在 30 行左右太长模型反而容易丢重点。我拿/test命令举个例子它做的是生成或补全测试。命令内容--- description: Generate or update unit tests for the current file --- You are a senior software engineer specialized in writing tests. Task: Write unit tests for the file I will specify. Rules: 1. Use the test framework configured in CLAUDE.md. Check CLAUDE.md first. 2. Cover these scenarios: - Normal case / happy path - Error case / edge case - Boundary values 3. Follow existing test patterns in the test/ directory. 4. Mock external dependencies (DB, network) — never connect to real services. 5. Do not modify any source file. Only create/modify test files. Before writing the tests, show a short plan: - Framework and test runner - Files to be created/modified - Test cases list If the file is not specified, ask the user first.实际调用时我会输入/test src/services/order.service.ts模型会先查看CLAUDE.md里的测试框架约定再查看现有测试文件的风格然后生成符合项目的测试代码。命令文件还有几个进阶玩法组合多个步骤在/deploy-check命令里让模型依次执行 lint、build、test最后输出汇总报告。引用其他文件比如/component命令可以引用templates/component.md作为生成 React 组件的骨架。使用环境变量在命令文件中可以用$VAR形式引用环境变量适合把 token、项目名等动态信息注入提示词。3.4 hooks 接入与验证前面提过 hooks 的配置这里我把脚本也写一下让大家有个完整的参考。scripts/auto-format.sh的内容#!/usr/bin/env bash set -euo pipefail # Auto-format JavaScript/TypeScript files with Prettier # Only run on files that are staged or modified FILES$(git diff --name-only --diff-filterACM | grep -E \.(ts|tsx|js|jsx)$ || true) if [ -n $FILES ]; then echo [hook] Formatting changed files... npx prettier --write $FILES fiscripts/guard-dangerous-commands.sh的内容#!/usr/bin/env bash set -euo pipefail # Block dangerous commands from being executed by Claude Code case $1 in rm -rf*|git push --force*|sudo *|curl *|kill *) echo [hook] BLOCKED dangerous command: $1 2 exit 1 ;; *) exit 0 ;; esac注意钩子脚本需要有执行权限chmod x scripts/auto-format.sh chmod x scripts/guard-dangerous-commands.sh配置好之后可以做个验证让 Claude 修改一个文件观察它是否会触发 prettier再让它执行一个危险命令观察它是否会被拦截。这两个验证通过说明 hooks 链路是通的。settings.json的权限配置也可以加上{ permissions: { allow: [ pnpm test, pnpm lint, pnpm build, git status, git diff, git log --oneline ], deny: [ rm -rf *, git push --force, sudo * ] } }这里我必须提醒一句allow 列表里的命令Claude 执行时不再询问你。所以不要图省事把git push加进 allow宁可让它多问一次也不要让它无感推送。4. 模板复用与团队协作4.1 个人模板库的版本化管理模板这东西写一次容易维护起来难。我见过不少人的.claude/目录乱成一团命令文件改了几版连自己都记不清哪个是最新逻辑。所以建议把模板项目纳入 Git 管理并且打上版本标签。我个人的做法是不同项目的模板会有公共部分和特色部分。公共部分存放在~/.claude/commands/下比如/explain、/commit这类通用命令项目特化内容放在项目自身的.claude/里。这样既不污染全局环境又能随项目分发给团队。再推荐一个小技巧CLAUDE.md里可以写一条引用指令让它自动加载docs/architecture.md等文档。这样不需要把所有内容都塞进CLAUDE.md见下面这个写法## Reference Documents When discussing architecture, first read docs/architecture.md for the current system design. When modifying API routes, read src/routes/README.md to understand routing conventions.这能让CLAUDE.md保持精简又不丢失深度信息。文档越全模型对复杂项目的理解就越准。4.2 团队共享模板的规范团队用模板最大的问题是**谁来维护、怎么同步**。我的建议是每个仓库自带.claude/目录进代码评审。新增或修改命令必须提 PRreviewer 要检查命令里有没有危险指令、权限配置是否合理。还需要制定几条团队约定CLAUDE.md里的命令必须以真实项目命令为准不允许出现臆想的脚本。斜杠命令文件不得含有个人偏好比如总是用 XXX 命名这类除非是全团队共识。危险操作一律不放allow列表。模板更新后必须写CHANGELOG并在 README 里同步使用说明。如果团队规模不大还有个轻量做法用 Git 子模块或者 monorepo 的公共包方式把通用的命令和 hooks 做成一个共享包各项目通过符号链接引用。这样修一个 bug 只需在一处改动所有项目都能受益。5. 常见问题与排查技巧实录5.1 模板不生效查路径更查命名最常遇到的是CLAUDE.md 明明写了规则Claude 却不遵守。我排查下来原因多半是以下三类文件放错了位置项目级的CLAUDE.md必须在项目根目录子目录里的CLAUDE.md只对该子目录生效。用户级的要放在用户主目录.claude/下。命名拼写错误大小写不对或文件名多了空格模型就读不到了。规则太模糊比如只写代码要清晰模型不理解什么叫清晰要写成不要超过 200 行的函数这样的具体约束。一个实用排查技巧是终端里输入/context或查看会话上下文看系统提示里有没有加载CLAUDE.md里的内容。如果没加载问题基本就出在前两类原因。5.2 斜杠命令无法解析输入/review没有反应或者提示找不到命令。大概率是文件路径不对或文件名格式不对。斜杠命令的文件名必须与命令名完全一致。比如命令名是/review文件就得是review.md。如果是嵌套目录比如.claude/commands/backend/review.md命令名就变成/backend/review。我一般不用嵌套保持所有命令平铺放在一级目录下简单直观。另外确认文件有没有 YAML frontmatter 格式问题。frontmatter 必须在文件最顶部结尾有---解析失败时命令可能不会被索引到。5.3 上下文过长与成本控制模板配置得越细模型每次读取的 token 也越多。CLAUDE.md如果写得像百科全书每次对话都会消耗大量 token而且过长的上下文可能让模型忽略重点。我的对策是分级加载根CLAUDE.md只写最核心的信息项目类型、命令、目录、风格具体的技术方案放到独立文档里用引用指令按需加载。斜杠命令文件也不要太长能一句话说清楚的任务不用三段式描述。模板质量不在于字多而在于指令密度高、可执行。5.4 权限误拦截导致流程中断deny列表写得过狠也会出问题。我曾经把grep命令误加入了 deny 列表结果 Claude 每次想搜代码都得问我一遍协作效率大打折扣。排查下来才发现是权限配置把太基础的命令拦截了。处理原则很简单不要把只读、无副作用的命令加进 deny。deny主要防的是有破坏性副作用的写操作比如删除文件、强制推送、生产环境变更。遇到误拦截把对应的安全命令从 deny 里移除或者直接用更精确的模式匹配比如rm -rf /tmp/*而不是rm -rf *。5.5 常见问题速查表症状可能原因排查办法模型不遵守仓库规范CLAUDE.md 位置不对或写得太模糊检查根目录文件细化规则/review 命令找不到文件名与命令名不一致检查.claude/commands/下文件名每次改文件都要格式化冲突hooks 里格式化脚本未执行检查脚本权限手动跑一次验证危险命令没被拦截deny 规则不匹配用同样的命令文本测试匹配正则模型回答时缺少项目背景全局/项目级上下文加载不全终端查看 context 信息确认加载项6. 模板的进阶玩法与扩展思路6.1 面向特定场景的专家型模板通用模板只是起步。我最近在做的事是让模板具备角色化能力——针对不同任务场景设定不同专家角色并配置专门的命令。比如在项目里做性能优化时我会加载一个性能专家模板它包含专门的CLAUDE.md片段说明这个仓库可能的性能瓶颈分布数据库索引缺失、N1 查询、大列表渲染等。/perf-audit命令自动统计接口响应时间找出慢查询。/perf-fix命令针对瓶颈项生成优化方案并附上基准测试。再比如处理线上故障时加载一个 SRE 模板它会要求 Claude 说话更简洁、优先给止损方案、不在没有确认时直接改生产代码。这种场景化模板的价值在于把模型的行为习惯和任务目标强绑定。6.2 与模型行为参数的配合Claude Code 提供了一些模型行为参数模板可以配合这些参数使用。例如调整生成长度需要大段文档生成时调高日常对话保持中等长度。开启思考模式复杂算法设计时强制 Claude 先输出思路再动手能明显减少瞎改代码的情况。控制工具调用频率某些模板里设置尽量不调用 Bash除非必要能降低无谓指令带来的风险。个人经验是模板和这些参数结合效果是乘法级而非加法级。单靠提示词很难完全约束模型的行为习惯参数配合会更稳。6.3 模板仓库的开源与持续迭代如果你写的模板足够通用完全可以整理成开源项目。我参考过社区一些做得很好的仓库它们的共同特点是有清晰的 README、示例目录和不断迭代的 changelog。开源的额外好处是用的人多了会有人帮你发现边界场景比如这个命令在 Windows PowerShell 下跑不通、这个正则匹配不到含空格的路径。持续迭代的方法也不复杂每次遇到一个要是当时有现成命令就好了的场景就记下来周末花时间补一条命令每次发现模型在某个上下文里产生了一次糟糕的回复就回溯是缺了哪条规则补进CLAUDE.md。模板是活的不是一次写完就能放那里的。模板不必追求大而全。对我来说最有价值的模板永远是那些能解决具体问题的、精简的小集合。与其堆 30 个命令不如把最常用的 5 个命令打磨到极致让每一次调用都稳定、高效、可预期。