Claude Code 用了一段时间后我最大的感受是真正拉开效率差距的不是你命令行敲得多溜而是你手头有没有一套经过沉淀的模板和配置体系。claude-code-templates说白了就是这套东西的集合——把常用的角色设定、工作流程、命令技能、代码规范全部固化到项目里让 Claude Code 从“一个能聊天的终端助手”变成“一个懂你团队规范、上来就能干活的结对程序员”。这篇文章是我把这套模板体系从零搭起来、在几个真实项目里跑完几轮迭代后的完整复盘。内容包括目录设计、CLAUDE.md 的写法、自定义命令和技能的落地、以及和 DeepSeek 模型对接时模板里那些容易踩的坑。无论你刚装好 Claude Code 想玩明白还是已经用了一段时间想从“零散调用”升级到“体系化管理”这篇都值得你认真看完。1. 模板体系的核心思路为什么需要一套自己的模板先说个实际对比。没有模板的时候每次用 Claude Code 干一个新任务我都得在终端里重新描述一遍项目背景、技术栈、代码风格、要遵守的规则。遇到稍微复杂点的任务光把上下文交代清楚就得打几百个字还经常说得不完整——比如忘了强调某个目录不能动、某个测试命令必须先跑结果它上来就改乱了一堆东西。有模板之后完全不是一回事。Claude Code 在启动时会自动加载项目里的 CLAUDE.md 文件把它当作“项目说明书”来读。模板的职责就是提前把这份说明书写好、写全、写得能落地。我把整个模板体系拆成三个层次第一层是全局配置。放在用户主目录里的~/.claude/管的是所有项目通用的偏好和行为。比如我统一了语言风格、默认的工具使用偏好、PID 相关的设置这些不随项目变化。第二层是项目级规则。就是项目根目录下的CLAUDE.md管的是这个项目特有的背景知识、命令习惯、架构约束。每个项目一份跟着项目走进仓库即生效。第三层是命令和技能。~/.claude/commands/和~/.claude/skills/这两块把高频操作固化成语义化指令。比如我以前每次写测试用例都要打一大段 prompt 描述“按什么风格、覆盖几条路径、用什么断言方式”现在一个/write-tests命令就全搞定了。这套分层的价值在于通用的事只写一遍特殊的事按项目隔离高频的事命令化。三层各自独立又能配合比模棱两可地“把所有规则都塞进 CLAUDE.md”要容易维护得多。我用下来的体会是模板体系不是“配置洁癖”的产物它解决的是三个特别实在的痛点第一降低每次对话的沟通成本省掉重复交代背景第二稳定输出质量不让同一个项目里的代码风格忽左忽右第三缩短新人上手时间新同学 clone 仓库后Claude Code 已经自动懂了这个项目的规矩。2. 初始化与基础配置从装好到能跑的最小闭环2.1 全局配置目录和环境检查一套模板体系落地的第一步是把全局目录建好。我建议直接按下面的结构准备~/.claude/ ├── CLAUDE.md # 全局的通用偏好 ├── commands/ # 自定义斜杠命令 │ ├── write-tests.md │ ├── review.md │ └── commit.md ├── skills/ # 技能定义 │ └── code-review/ │ └── SKILL.md └── settings.json # 全局设置可选有朋友会问全局 CLAUDE.md 和项目里那两份会不会冲突我实际测试下来它们遵循的是“就近覆盖”的优先级——项目内的规则覆盖全局规则子目录里的规则覆盖项目根目录的规则。所以全局文件里我只放那些“所有项目都该遵守”的底线条款比如默认语言用中文、改动前先列举影响文件、遇到模糊需求先提问题而不是瞎猜。项目文件里才放技术栈约束和目录结构描述。环境检查也要提前做。模板里依赖的 Claude Code 版本建议不低于 2.x因为早期的版本对 CLAUDE.md 的加载和 skills 支持都不完整。Windows 用户注意路径问题~/.claude在 Windows 下实际是C:\Users\你的用户名\.claudeLinux 和 macOS 下就是常规的 home 目录。如果你和我一样用 VSCode装了 Claude Code 扩展后命令面板里可以直接看到 Claude Code 相关操作终端里的claude命令也会在项目根目录自动找到上下文。2.2 模型接入与模板适配模板体系里要提前想清楚的一件事你到底用哪个模型。我一开始用的是 Anthropic 官方 API 默认模型后来为了控制成本主力接入了 DeepSeek。这里不是要比较谁好谁坏而是提醒你模板内容会受模型行为影响。DeepSeek 对中文指令的理解能力很强处理长上下文的表现也不错但在某些遵循性细节上和官方模型的“性格”不完全一样。比如官方模型会更自觉地遵守“先读后写”这种流程性规则而另一个模型在上下文比较长的时候偶尔会丢中间的某一条约束。所以我在模板里专门加了“重读规则”约定当一个任务步骤超过三步时模型必须停下来重读 CLAUDE.md 中的约束清单再继续执行。这个提醒别觉得多余实测下来能明显减少丢规则的情况。实际接入 DeepSeek 时配置用的是 API Base 和 Key 的切换方式。具体做法是在终端里临时指定环境变量启动export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 claude如果你经常要在不同模型间切换社区里通常的做法是装一个名为ccswitch的小工具早期版本有人叫它cc-switch能帮你把不同模型的配置存成预设一键切换。这件事和模板体系有关联因为模板里那些针对模型行为的约定本质上是在给“不同的模型性格”打补丁。切换模型后如果发现输出质量下降优先检查模板里的规则是否需要按新模型调一遍。2.3 从最小模板开始不要一上来就写完美模板我的建议是全局配置够用就行项目级 CLAUDE.md 刚开始也别写太长。一个四五行的最小可用模板长这样# 项目说明 这是一个基于 Python 的 Web 服务项目使用 FastAPI 框架。 # 约束 - 修改代码前先说明影响范围 - 所有新增依赖先征求确认再安装 - 使用中文回复别看内容少它已经能让 Claude Code 的行为从“通用聊天模式”切到“项目合作模式”。后面随着你对项目的理解加深一步步往里面加内容就行了。模板和代码一样适合增量演化一上来憋个几千字的“完美文档”反而容易过时模型还会被大量无效信息干扰判断。3. CLAUDE.md整个模板体系的“心脏”3.1 角色与目标给模型一个稳定的“人设”在一份有效的 CLAUDE.md 里我认为最重要的部分是给 Claude Code 定义清楚“它这个项目里是谁”。没有这个定义的时候它更像一个“什么都会一点的通用助手”有了定义之后它会稳定地带入角色做判断。我用一个实际例子说明。我的某个项目里角色定义是这样写的# 角色 你是这个项目的资深后端工程师熟悉项目现有架构和代码风格。 你的职责是实现功能、修复缺陷、编写测试、参与代码评审。 在给出建议时你优先考虑项目的可维护性和长期演进而不是临时方案。这里有个关键点角色定义不要只写“你是资深工程师”还要写“所以你会怎么表现”。后面那句“优先考虑可维护性而不是临时方案”才是真正影响它输出的那部分。只有头衔没有行为准则模型只会点头说“好的我是资深工程师”然后该咋样还咋样。3.2 命令与流程把项目专属操作写进规范项目里的高频命令、测试流程、代码提交规范都该沉淀进 CLAUDE.md。我建了一个“常用命令”小节格式很简单# 常用命令 - 构建: npm run build - 测试(全部): npm test - 测试(单文件): npm test -- src/utils/parser.test.js - 类型检查: npx tsc --noEmit - 代码格式化: npm run format为什么这在模板体系里这么重要因为模型默认并不知道你这个项目跑测试要用什么工具、有没有 lint 步骤。你如果不告诉它它可能在“验证代码是否可用”时想当然地直接运行不存在的命令或者完全跳过验证就宣布“完成了”。把命令写进去之后每次它需要时就直接查不需要你反复说明。还有一个细节不同项目的测试命令差异很大有的项目要跑 migration 再测有的项目测单文件比全量快十倍。这些细节都写进 CLAUDE.md模型才能做出符合项目习惯的选择而不是套用通用经验。3.3 架构与目录防止随手乱改的前提模型在长对话里确实会“迷路”——项目越大它越容易改错地方。比如事件总线模块同时在多个业务里被引用模型没看全依赖关系就动了一刀结果引发连锁故障。所以我对模板的要求是必须提供一份“安全地图”。安全地图要解释这三点目录结构、领域边界、危险区域。# 架构与目录 ## 目录职责 - src/core/ 核心业务逻辑改动需要谨慎评估 - src/adapters/ 外部系统适配层新增适配器时保持接口一致 - src/utils/ 通用工具函数禁止引入领域逻辑 - tests/unit/ 单元测试遵循 AAA 结构Arrange-Act-Assert ## 谨慎修改改动前必须向用户确认 - src/core/event-bus.ts: 全系统事件流转中枢上下游依赖极多 - migrations/: 数据库迁移脚本只追加不修改所谓“危险区域”是你结合实际经验标记出来的那些“一动就出事”的文件。比如数据表结构变更、公共类型定义、支付逻辑相关的文件。标记的作用是默认情况下模型不会主动改它们而是要向你确认后才会动手。如果你的项目里也有这种“雷区”强烈建议在模板里单独列出来。这一个动作能省掉很多次返工。3.4 协议与约束把项目规矩变成默认行为代码风格、命名惯例、提交格式、Pull Request 描述模板……这些都算“项目规矩”。在 CLAUDE.md 里我推荐用“黑名单 白名单”的方式写。黑名单是“绝对不能做的”比如“不要修改 package-lock.json”“不要用any类型”白名单是“希望默认遵守的”比如“新模块一律默认导出命名函数”“错误处理必须返回统一的 Result 结构”。这里有个容易犯的毛病写得像法律条款一样面面俱到。用户让模型做的事本来就不需要事无巨细地规范。我的经验是一个项目 CLAUDE.md 里“协议与约束”部分控制在 10 条以内只写那些“违反了会出明显问题”的规则。写太多模型反而容易漏掉关键的一条。4. 把模板升级为能力自定义命令与 Skills4.1 斜杠命令把常用 Prompt 固化成一件“趁手工具”CLAUDE.md 解决的是“背景知识”问题而斜杠命令解决的是“高频操作”问题。打个比方CLAUDE.md 像工作手册你随时翻阅斜杠命令像快捷键你一键触发一段程序化流程。在~/.claude/commands/下每个.md文件就是一个命令。文件名不带扩展名就是触发词。我最常用的三个命令文件结构如下--- description: 按项目规范编写单元测试 argument-hint: [测试目标文件] --- 针对 $ARGUMENTS 文件编写单元测试。 要求 1. 使用项目已有的测试框架和目录约定 2. 遵循 AAAArrange-Act-Assert结构 3. 覆盖正常路径、边界条件和主要异常分支 4. 单元测试不得访问外部网络或真实数据库 5. 完成后运行相关测试命令确认全部通过这里有几个值得注意的细节。description字段会在 Cluade Code 的命令列表里显示为提示文字方便你以后在交互界面里快速看到这个命令是干嘛的。argument-hint用来提示参数比如上面这个命令你输入/write-tests src/utils/parser.ts$ARGUMENTS就会被替换成src/utils/parser.ts。写命令模板的时候不要只写要求的清单还要把“验收标准”写进去也就是“完成后运行测试并确认通过”这一句——否则模型可能写完就停不做验证。斜杠命令其实也是模板的一种。它的价值是把你脑子里的“经验”外置成了一个文件这次写得不好改一版即可下次换个项目直接复制过去再用组里的同事拿去也能快速获得同样的工作方式。4.2 Skills让模板拥有“可插拔的能力”如果说斜杠命令是“指令快捷方式”那 Skills 就是“能力模块”。后者是一个带结构的目录里面除了指令描述还包括示例、资源文件和参考文档。实现上Skill 是一个包含SKILL.md的文件夹放在~/.claude/skills/或项目级的.claude/skills/下。我拿“代码评审”这个 Skill 举例它的目录结构长这样~/.claude/skills/code-review/ ├── SKILL.md └── examples/ ├── good-review.md └── bad-review.mdSKILL.md 里写的是--- name: code-review description: 对变更的代码进行结构化评审输出明确的发现列表 --- # Code Review Skill ## 流程 1. 先读取 diff理解改动范围 2. 检查是否符合项目 CLAUDE.md 中的约定 3. 按下面的维度逐项评审 - 正确性是否存在逻辑错误、边界遗漏 - 安全性是否存在注入、越权、泄密风险 - 可维护性命名、结构、注释是否清晰 - 性能是否有明显低效的查询或循环 4. 输出格式每个问题按 [严重 | 建议 | 疑问] 三档分类 ## 注意 - 对不确认的问题标注“存疑”不要强行下结论 - 只说问题不说场面话Skills 和模板的关系是模板提供上下文和约束Skills 提供专业领域的知识和方法。CLAUDE.md 里我只需要写“代码变更后先做 review 再提交”具体的 review 方法论和示例则由 Skill 在模型需要时自行加载。关于手动安装第三方 SkillsGitHub 上很多仓库提供现成的 Skills。操作方式不复杂把仓库 clone 到你本地的 skills 目录里就能用。比如git clone https://github.com/example/some-skill.git ~/.claude/skills/some-skill但要提醒一句不要无脑装一堆 Skill。每个 Skill 在特定场景下才会被触发加载装多了表面看不出来但模型不是每次都会精准判断调用哪个反而可能出现“该用的时候没用、不该用的时候硬套”的情况。我目前的习惯是每个 Skill 满足三条件才装自己用得上、内容质量过硬、示例真实具体。4.3 模板和命令的迭代节奏记录、触发、固化这一小节更像是我自己沉淀下来的方法论分享给大家参考。我的工作流是“记录、触发、固化”三步循环。刚开始用一个新项目时我会在项目根目录旁边放一个notes.md不在 CLAUDE.md 里记录自己在对话里重复说的那些话“说了三遍让它先读 docs 再动手”“提醒了两次它才记得要用事务”。当某个点重复触发超过两三次我就把它提炼成一条规则写进 CLAUDE.md 或命令模板。比如为了某个项目之前每次做需求我都得当场强调“先写集成测试再实现”后来屡试不爽就干脆建了一个/implement命令把这个流程固化成标准--- description: 按 TDD 节奏实现一个需求 argument-hint: [需求描述] --- 请按以下流程实现需求$ARGUMENTS 1. 阅读相关代码明确改动范围 2. 先写会失败的集成测试 3. 再实现最小逻辑使测试通过 4. 运行全量相关测试确认没有破坏已有功能 5. 列出所有改动的文件清单和测试结果这样迭代的好处是模板体系不是静态的它会跟着你对项目的理解一起成长。每一条新增的规则都来自真实的摩擦而不是从网上抄来的漂亮话。5. 实战从零到一构建一套可用的模板体系5.1 目录结构与三份核心文件下面用一套我在实际项目中用过的模板给你一个可以直接抄的骨架。假设是一个 TypeScript Express 项目。项目根目录下先创建.claude/目录用来放项目级的模板内容。完整的推荐目录长这样项目根目录/ ├── .claude/ │ ├── CLAUDE.md # 项目规则 │ ├── commands/ │ │ ├── implement.md │ │ ├── review.md │ │ └── test.md │ └── skills/ │ └── (可选项目专用技能) ├── package.json └── src/个人全局目录放那些跨项目的通用规则~/.claude/ ├── CLAUDE.md # 全局偏好 ├── commands/ │ ├── write-tests.md │ └── commit.md └── skills/ ├── code-review/ └── db-migration/5.2 一套可直接参考的 CLAUDE.md 模板下面这份文件不是示例是我从实际项目里精简出来的。你直接复制然后项目背景替换成自己的即可。# 角色定义 你是本项目的中级以上全栈工程师。你的目标是让功能按需求落地代码符合项目约定。做技术选型时偏向成熟稳定而不是花哨。 # 项目概述 一个面向中小团队的任务管理 API 服务基于 Express TypeScript PostgreSQL使用 Prisma 作为 ORM。代码仓库采用 monorepo 结构应用在 apps/api/共享类型在 packages/shared/。 # 常用命令 - 安装依赖: pnpm install - 启动开发服务: pnpm dev - 运行全部测试: pnpm test - 单一测试文件: pnpm vitest run src/modules/tasks/task.service.test.ts - 代码检查: pnpm lint - 数据库迁移: pnpm prisma migrate dev # 架构约束 - apps/api/src/modules/tasks: 任务领域所有业务逻辑集中在 service 层 - packages/shared/contracts: 前后端共享的 DTO 和类型定义改动会直接影响前端 - 禁止在 controller 层写复杂业务逻辑 - 所有数据访问必须走 Prisma API # 业务规则 - 任务状态流转: todo - in_progress - review - done - 删除任务是软删除通过 deletedAt 字段标记 - 涉及金额或权限变更时必须输出审计日志 # 协议 - 回复使用中文代码注释和标识符使用英文 - 对接口签名或数据库 schema 的修改先列出影响范围征求确认后再动手 - 新功能默认补齐单元测试和集成测试这份模板看起来不长但它已经把“角色、背景、命令、架构、业务、协议”六个维度都覆盖了。模型能靠它完成很大一部分“新人入职培训”。5.3 实操过程从写到跑的一个完整闭环我拿一次真实任务来展示这个模板怎么产生作用。任务需求是“为任务模块增加截止时间字段”。如果没有模板模型面对这个需求只能靠猜指不定会在哪一层加字段、怎么加校验、需不需要迁移。有了上面的模板它的推理链就完全不一样了。模型会先查常用命令里的 Prisma 迁移命令然后按架构约束找到 tasks service 层。因为模板里写了“对 schema 的修改先征求确认”所以它会先输出影响清单Prisma schema 中增加dueDate字段、迁移文件生成、DTO 和类型定义更新、service 校验逻辑补充、相关测试新增。等我确认后它才动手。这就是模板的作用——不是限制模型的发挥是让它的每一步都走在项目轨道上。5.4 调优与迭代每次对话后留 10 分钟整理模型生成完后我会检查一遍然后把交互里值得沉淀的细节补进模板。这轮任务结束我在 CLAUDE.md 的“业务规则”部分加了一条“所有日期字段统一用 ISO 8601 字符串存储”。这是模型跟我在对话中确认过的时间格式如果不固化下个任务它可能又用别的格式。把这个习惯保持下来你的模板就会从“通用能力”逐步进化成“项目专属大脑”。每次沉淀的内容不需要多一两条就够关键是坚持。6. 常见问题与排查手册6.1 我遇到过的典型问题汇总这里梳理一些问题列表附上排查方向和处理方式问题表现可能原因处理方式模型完全不理会 CLAUDE.md 里的规则文件命名不对或路径放错确认根目录下名字是CLAUDE.md全大写系统提示和目录大小写都要精确模型“知道”规则但执行时遗漏规则条目过多或相互矛盾精简到 10 条以内消除互相冲突的表述斜杠命令找不到命令目录不在预期路径确认放在~/.claude/commands/或.claude/commands/下文件名与触发词一致换模型后规则失效模型对指令遵循度不同调整模板表述增加“必须”“禁止”这类强约束词必要时拆分步骤子目录里规则覆盖了项目根目录内容命名规则冲突在子目录放就近的补充规则避免重复定义大而全的内容6.2 排查技巧实录一次“模板失效”的完整追踪分享一次真实的排查经验。有个项目在某天开始模型的表现突然“变笨”——完全不像读到了项目背景的样子。经验丰富的朋友可能会直接怀疑模板加载出了问题。我的排查顺序是这样先确认工作目录是不是项目根目录发现没问题再确认最近改没改过 CLAUDE.md 的格式发现前一天刚从网上复制了一段带特殊符号的规则进去最后打开文件检查才发现那段内容里包含了一个被误触发的 Markdown 表格分隔符把后面的规则全部解析成了表格内容模型读取时只看到了表格框架没看到规则实质。这件事给我两个教训第一所有从外部复制进模板的内容都要检查 Markdown 语法是否完整第二每次修改 CLAUDE.md 后新开一个会话验证加载效果别在长对话里测试模板。6.3 存储位置与卸载清理如果要在多台设备间同步模板建议直接打包~/.claude目录。这个目录里全是文本配置没有运行时生成的大文件非常适合放到 Git 仓库里管理。项目级的.claude目录最好直接提交到项目仓库让所有协作者共享同一套规则。想彻底卸载 Claude Code CLI 时除了移除命令行工具本身还要把配置目录一起清掉。全局目录删掉~/.claude项目目录删掉.claude/注意别把真正的源代码目录误删了就行。提到存储位置时还有一个细节Claude Code 的全局存储路径~/.claude在不同系统上有差异Windows 上在用户主目录下macOS 和 Linux 常规如果你的机器上配置了自定义XDG_CONFIG_HOME那路径会跟着这个环境变量走排查找不到配置时先确认它。7. 模板的扩展方向让体系更接近“团队基础设施”模板体系再往上走一步就变成团队基础设施了。我自己实验下来有几个值得探索的方向分享给你。第一个方向是接 more robust 的 code review 流程。不只是让模型“看一下有没有问题”而是把评审标准细化成可检查项比如安全、性能、可维护性、测试覆盖分别给分。把评审结果输出成固定格式配合斜杠命令/review每次代码合并前跑一遍能得到稳定的反馈。第二个方向是把模型能力和自建文档体系打通。在模板里把docs/目录结构和关键文档路径写清楚模型在需要了解某个领域时就知道去读哪份文档。这样模板就不仅是给模型看的它更像是“项目里所有智能体的共同抓手”。第三个方向是配合 Claude Agent SDK 做一些自动化任务。模板里的规则可以被 SDK 应用的程序直接调用比如“根据 CLAUDE.md 的规则自动分析新 issue 的标签和负责人”。不过这需要一点编程能力不是纯配置能搞定的。我个人在实践中最大的体会是模板体系的核心价值不在于收藏了多少花哨配置而在于每条规则是否来自真实项目摩擦。能解决问题的模板才是好模板其他人写得再漂亮不如自己踩一个坑填进去来得实在。另外还有个小技巧算是压箱底的经验写完模板后故意把上下文搞得模糊一点然后丢给 Claude Code 一个小任务观察它能不能自己从 CLAUDE.md 里补充上下文。这个实验能很快测出你的模板是否真的写得清楚。如果它在模糊输入下还能表现稳定那恭喜你这套体系已经能扛事了。
