1. 先搞明白claude-code-templates 到底是什么最开始看到 claude-code-templates 这个名字很多人第一反应是“给 Claude Code 用的代码模板”。这个理解只说对了一半。它真正指的是面向 Claude Code 这一终端编码工具的一套可复用配置模板包括 CLAUDE.md 规则文件、技能skills的目录结构、常用提示词片段、角色定义和工作流约定。你可以把它理解成给 Claude Code 准备的“入职手册”和“操作 SOP”。Claude Code 本身是 Anthropic 推出的 CLI 编码工具你可以在终端里通过自然语言让它读代码、改代码、跑测试、提 PR。它厉害的地方是能感知你当前的项目结构但默认情况下它就像一个“聪明但对你项目一无所知的新人”——它不知道你们的代码规范、不知道哪些目录不能动、不知道测试命令是什么、不知道你希望它用什么语气提交代码。而 claude-code-templates 这类模板库就是把这些“项目常识”固化下来让工具一进入项目就能很快进入状态。适合谁看如果你刚接触 Claude Code一两周了还在反复解释项目背景或者你已经用了几个月但每次新项目都要复制一份旧的配置文件又或者你带团队、想让所有人都按同一套标准使用这个工具——这文章就是给你写的。下面所有内容都是我自己在真实项目里试出来的经验没有花架子。2. 核心设计思路模板到底在解决什么问题2.1 先理解 Claude Code 的记忆机制想写好模板得先搞清楚 Claude Code 是怎么“记住”上下文的。它的记忆主要来自几个层面系统提示词system prompt内置的通用能力、你在终端里输入的自然语言指令、以及它能自动读取的规则文件。规则文件里最核心的就是 CLAUDE.mdClaude Code 会在对话开始、文件变动、每个关键节点自动加载它。很多人忽略一个细节Claude Code 每次加载 CLAUDE.md 都要消耗上下文窗口。你不是写得越多越好而是写得越“精准”越好。一份 500 行的 CLAUDE.md 和一份 200 行的 CLAUDE.md看着前者信息多但因为上下文被无关内容挤占真正干活时它反而更容易“丢三落四”。模板库存在的意义就是帮你把“每次都要重复写在命令行里的话”变成“它自己翻开就能看到的东西”。我做 claude-code-templates 这类项目时第一原则就是所有规则必须能回答“为什么”而不是单纯“是什么”。比如“不要修改 node_modules”和“node_modules 是第三方依赖目录改动会导致安装锁文件失效不用管它”后者明显更容易让模型在复杂情况下做出正确判断。2.2 模板的分层结构全局、项目、技能一个健壮的 claude-code-templates 库通常包含三层层级存放位置作用范围典型内容全局层~/.claude/CLAUDE.md所有项目语言偏好、通用编码规范、常用命令习惯项目层项目根目录/CLAUDE.md当前仓库技术栈说明、构建命令、目录职责、代码风格技能层项目根目录/.claude/skills/按需激发特定任务的专用流程如代码审查、性能分析我强烈建议全局层只放通用习惯项目层聚焦仓库细节技能层解决“特定场景的高质量输出”。不要把项目特有的技术栈写进全局模板否则换一个项目它就开始张冠李戴。我见过有人把 Vue 的规范写进全局层结果用 React 的项目里它反复建议用 Vue 语法。技能层是 Claude Code 后来引入的能力相当于给工具预置了一套“专业技能包”。每个技能是一个目录里面放一个 SKILL.md描述这个技能何时触发、执行步骤是什么、有哪些注意事项。技能只有在用户提问或行为匹配到它的描述时才会被加载所以它不占每轮对话的上下文非常划算。2.3 模板库的两个核心收益一致性和可复制性团队里多人用同一个工具最怕的是同一个问题问出十个不同的答案。有人让它“修一下”有人让它“把报错处理了”结果它给出的改动风格完全不同。模板库能把这种差异降到很低大家都读同一份 CLAUDE.md、用同一组技能输出的代码风格、提交信息格式、注释习惯都会趋同。可复制性也很关键。终端的 AI 编码工具已经成了我很多项目的基础设施那基础设施的配置就不能“只可意会不可言传”。把配置沉淀成模板仓库新项目 clone 下来跑一条安装脚本五分钟内就拥有一套成熟配置。新同事入职教他跑一次安装脚本剩下的他自己探索都能少踩很多坑。3. 实操搭建从零构建你的 claude-code-templates 仓库3.1 仓库目录结构规划我通常按下面这个结构组织模板库claude-code-templates/ ├── global/ │ ├── CLAUDE.md # 全局规则 │ └── .claude/settings.json # 全局行为设置 ├── project/ │ ├── CLAUDE.md # 项目级规则示例 │ └── .claude/ │ └── skills/ # 技能目录示例 ├── skills/ │ ├── code-review/ # 代码审查技能 │ │ └── SKILL.md │ ├── performance-check/ # 性能检查技能 │ │ └── SKILL.md │ └── refactor-safe/ # 安全重构技能 │ └── SKILL.md ├── prompts/ │ ├── git-commit.md # 提交信息规范 │ ├── issue-report.md # 问题报告模板 │ └── onbording.md # 新项目引导 ├── scripts/ │ ├── install.sh # 一键安装脚本 │ └── update.sh # 更新模板脚本 └── README.md这个结构的好处是能区分“通用层”和“示例层”。global/是实际会被装到本机的文件project/是给具体项目用的样板skills/是技能库prompts/是可能需要手动粘贴的常用指令片段。3.2 编写 CLAUDE.md把“常识”翻译成规则写 CLAUDE.md 最忌讳的是把它写成一份“企业规章制度”。Claude Code 能理解的不是抽象的条文而是具体的指令。我举一个我真实项目里的例子# Demo API 项目规则 ## 项目简介 这是一个基于 FastAPI 的订单服务主要提供订单创建、查询、取消接口。 数据库使用 PostgreSQLORM 是 SQLAlchemy 2.0缓存用的是 Redis。 代码仓库根目录是 /demo-api所有命令都在此目录下运行。 ## 常用命令 - 启动开发服务器python -m uvicorn app.main:app --reload - 运行全部测试pytest tests/ -v - 运行单个测试文件pytest tests/test_orders.py -v - 代码格式化ruff check . --fix ## 目录职责 - app/main.py —— 应用入口与路由注册 - app/models/ —— 数据库模型禁止在 service 层直接写 SQL - app/services/ —— 业务逻辑一个 service 只负责一个业务域 - app/routers/ —— API 路由层只做参数校验与响应封装 - tests/ —— 单元测试与集成测试 ## 编码规范 - 新增接口必须附带 OpenAPI 文档注释 - 所有时间字段统一用 UTC 存储序列化时转东八区 - 数据库变更必须新增 migration禁止直接改表结构 - 日志用 app.utils.logger 模块打出结构化日志不要用 print - 不要修改 node_modules 或 vendor 目录下的任何文件 ## 常见任务工作流 ### 新增一个订单查询接口 1. 在 app/schemas 中定义 Pydantic 请求/响应模型 2. 在 app/services 中实现业务查询逻辑 3. 在 app/routers 中注册新路由 4. 在 tests 中补充至少两个用例正常返回和参数非法 5. 运行 pytest tests/ 确保全部通过 ### 修复一个 Bug 1. 先运行 pytest 复现问题 2. 判断是模型层还是服务层的问题 3. 修改代码后必须追加一个能覆盖该 Bug 的回归测试 4. 运行相关测试范围不要求跑全量但要保证无新失败我写这份文件时反复调整了好几次最后得到的经验是用编号步骤描述工作流比写一大段“请遵循良好的开发实践”有用得多。模型很擅长按编号步骤执行但很难把一个抽象原则落地成具体操作。还有一个小技巧CLAUDE.md 里用“禁止”这个词要谨慎。如果只是一些偏好用“优先”或“建议”。一旦写了“禁止”模型就会把这当成硬性红线宁可多问也不动手。这有时反而降低效率。3.3 定义技能Skills让模板具备按需触发的专业能力技能是模板库里最值得花时间打磨的部分。一个规范的技能目录长这样refactor-safe/ ├── SKILL.md └── examples/ └── after-refactor-example.tsSKILL.md 的 frontmatter 里必须有name和description。description 是这只技能能否被正确触发的关键。Claude Code 会根据用户当前的提问与 skill 描述做语义匹配所以描述里尽量包含触发场景、任务动词、语言或框架信息。下面是我写的“安全重构”技能的 SKILL.md 核心内容--- name: refactor-safe description: 当用户要求重构代码、提取函数、拆分模块、重命名变量时使用。适合 JS/TS/Python 项目。不要用于新增功能或修复 Bug。 --- # 安全重构 ## 执行目标 在不改变代码行为的前提下调整代码结构以提升可读性、可维护性。 ## 前置检查必须依次完成 1. 检查项目是否已有测试运行一次 npm test 或 pytest 记录基线通过数 2. 如果没有测试先向用户说明风险等用户确认后再继续 3. 确认重构范围只处理用户提到的模块不顺手改无关文件 ## 重构步骤 1. 建立“重构前后对照清单”列出涉及的文件和函数 2. 小步提交每完成一个函数的提取/重命名立即跑一次相关测试 3. 重构完成后再跑一次全量测试对比基线 4. 检查 git diff确认没有非预期的格式变更 ## 禁止事项 - 同一批次里既重构又改业务逻辑 - 重构时顺手“美化”整份文件 - 在重构过程中引入新依赖 ## 验收标准 - 前后测试结果一致或更好 - 核心函数调用关系变化不超过用户指定的范围 - 生成的提交信息里写明重构内容和测试结论写技能时最容易犯的错是“把技能写成大纲”。加上了前置检查、禁止事项、验收标准才是真正能指导一个 agent 完成任务的技能。我把技能文件当“带教训的教程”来写因为 SKILL.md 的作用就是在工具犯错时给它一个清晰的边界。3.4 提示词片段库留给手动场景的“弹药”不是所有场景都能靠自动匹配触发技能。有时候用户就是在终端里随口问了一句“这个函数怎么这么慢”我习惯准备一批 prompt 片段按需复制黏贴。比如性能分析提示词请作为资深性能工程师对以下代码段做耗时分析 1. 先用 cProfile 或 py-spy 采集现行数据没有环境就基于静态分析评估 2. 列出耗时最高的 3 个函数说明为什么慢 3. 给出两个优化方案一个是不改动架构的快速优化一个是架构层优化 4. 每种方案都要说明改动范围、预期收益、风险点 5. 在你动手前先把你打算改的代码路径图用文字描述给我确认这种片段有几个共同点有专业角色设定、有明确的步骤要求、有“先确认再动手”的护栏。我把它们放在prompts/目录都按场景命名需要时直接复制进终端。4. 实操要点让模板真正好用的几个关键参数4.1 description 写得越具体触发越精准Claude Code 的 skills 功能是基于语义匹配触发的。如果你把 code-review 技能的 description 写成“代码审查”它几乎什么都不会匹配到或者说换个方式到处乱触发。我踩过这个坑后来把 description 改成当用户要求检查代码质量、发现潜在 Bug、评估代码规范合规性时使用。 适用于提交 PR 前的自检、重构前后的质量验证。 不用于日常功能开发。改完之后触发准确率高了很多。这里的关键是要把技能触发的正向场景和负向排除都写清楚。就像你给同事派活不能只说“看一下代码”得说清楚什么时候该看、什么时候不用看。4.2 模板里的“上下文预算”意识每次对话都会把 CLAUDE.md 全文载入上下文因此你写的每行字都在消耗它的“注意力”。我给自己定了一个规则CLAUDE.md 控制在 100-200 行以内。如果内容多到超出这个范围就会把“技能”和“提示词片段”承接一部分。有一个真实示例我的一个 Spring Boot 项目里CLAUDE.md 曾经写了 320 行覆盖了从 Maven 构建到 SonarQube 检查的所有细节。结果这个工具经常在无关问题上“过度表现”——比如我只是问一个接口参数它把整个模块的配置都重述了一遍。精简到 150 行之后这种情况明显减少了。4.3 把“禁止做的事”写进模板比事后纠正便宜得多Claude Code 允许在过程中多次纠错但纠错也有代价每次纠正都要消耗来回轮次而且它改完一个错误可能引入另一个。与其事后不断纠正不如在模板里预先声明边界。我的模板库有一个通用规则区专门记录这类边界## 绝对不要做的事 - 不要在没有运行测试前声称“改动不会破坏现有功能” - 不要删除代码时只删了定义没删引用改动前先 grep 一遍引用 - 不要一次性生成超过 600 行的新文件超过要分步追加 - 不要把执行命令的输出贴回对话里当作结果要基于文件事实判断这些规则看着像“废话”但对模型来说特别有效。因为它的预训练经验里很多是“小步快跑式”的辅助操作如果你不明确给它设限它就容易搞出“删了定义忘了引用”这类事故。4.4 用 settings.json 控制行为模式除了 CLAUDE.mdClaude Code 还有各级.claude/settings.json配置文件。我常用它来做三件事设置权限模式比如禁止自动执行可能造成破坏的命令、忽略某些目录、配置自定义命令别名。{ permissions: { bash: { allow: [npm test, pytest, git status, git diff, ls], deny: [rm -rf, git push --force, psql] } }, ignore_patterns: [node_modules, .venv, dist, .next], aliases: { test: pytest tests/ -v --tbshort, lint: ruff check . } }有个容易忽略的点ignore_patterns写在 settings 里能有效减少工具的无效探索。比如项目里有个巨大的dist/目录如果不加忽略它可能在整理文件时把这个目录也扫进去白白浪费整整几千个 token 的上下文。5. 常见问题与排查技巧实录我自己用下来模板相关的问题主要集中在几个场景。下面直接给问题和对应解法。5.1 模板看起来没被加载现象你改了 CLAUDE.md但 Claude Code 似乎还在用旧规则。排查思路看文件名大小写必须严格叫CLAUDE.md写成claude.md或Claude.md都不行看是否放错了目录。项目级 CLAUDE.md 要放在仓库根目录不是src/也不是.claude/看有没有缓存。新版本 Claude Code 有会话缓存如果长期开着同一个会话可能需要/clear或重启新会话才能重新加载最新模板检查是不是同时存在全局和项目模板项目模板的内容优先级高于全局但不是合并有些关键指令可能被覆盖我遇到过最隐蔽的问题是团队里某位同事在全局模板里写了一条“所有代码评审都是浪费时间”之类的规则结果项目模板里的代码评审技能完全失效。全局和项目模板之间是“覆盖”关系不是你想象的“拼接和补充”所以排查模板问题时要两级文件一起看。5.2 技能匹配不到或老是被错误触发如果技能文件存在但从不被触发先检查技能目录命名是否正确。技能必须放在.claude/skills/技能名/SKILL.md这个路径下而且技能名目录不能有空格。如果技能老是乱触发多半是 description 写得过于宽泛。按我前面说的方法把负面场景和正面场景同时写清楚能解决绝大部分问题。还有一个容易踩的坑技能目录里的辅助文件比如 example 文件、参考报告确实会被一起打包进技能上下文但体积不能太大。我试过在技能目录里放了一份 3MB 的参考 PDF结果每次触发这个技能对话延迟明显变高。技能库里尽量只放文本和少量代码示例。5.3 模板内容太长拖慢响应这个已经在前面说过了但我再提供一组实操数字。我测试过不同体积的 CLAUDE.md 对首字响应速度的影响150 行以内基本无感300 行左右会有一点延迟但还能接受500 行以上不仅响应慢模型理解长文档的能力也会衰减。所以如果必要信息太多就把一部分挪到技能里而不是硬塞在 CLAUDE.md。5.4 团队协作模板更新后别人不生效多人共用一套 claude-code-templates最怕“我更新了模板队友还用的是旧规则”。我现在的做法是给仓库配一个update.sh脚本里面写清楚更新步骤先拉代码再执行./update.sh脚本会帮你比对文件变更并提示是否需要重启会话。另外在CHANGELOG.md里记录每次改动这样队友知道哪一次改动跟他们手头的工作有关。# !/bin/bash # update.sh 示例 echo 正在备份当前全局配置... cp -r ~/.claude ~/.claude.backup.$(date %Y%m%d) echo 将模板库的 global/ 复制到 ~/.claude/ cp -r ./global/* ~/.claude/ echo 可选更新项目级模板 if [ -f ./project/CLAUDE.md ]; then echo 检测到项目级模板请手动复制到具体项目根目录 fi echo 完成。请重启 Claude Code 会话让模板生效。这个脚本虽然很基础但能避免“手动复制粘贴漏项目”的问题。真正在团队里推广模板库时脚本化和自动化是必须的否则大家嫌麻烦就不会去更新。6. 进阶扩展把模板库变成你的工作流核心模板库不只是静态的文件集合它还可以承担不少“流程自动化”的活。我目前在做的几个扩展方向供你参考第一个是给模板库加“项目初始化”技能。新建项目时Claude Code 读取这个技能自动批量生成 CLAUDE.md、目录结构、初始配置文件和第一个 Hello World 测试。这样团队里开新服务的成本降得很低。第二个是“周报辅助”技能。每周五它读取我这周的 git log、提交信息按模板生成周报草稿我再手改一遍。这个技能不需要多复杂关键就是描述足够准确写“当用户提到周报、本周工作、git 提交记录时使用”。第三个是把模板库跟 CI 结合起来。模板里规定每个项目的 CLAUDE.md 都要包含## 常用命令和## 目录职责然后在 CI 里跑一条脚本检查这两段是否缺失缺失就报警。这看起来有点“小题大做”实际执行下来对保持模板质量很有帮助。我个人做模板维护时有个体会模板是活的不是写一次就完事。每次用 Claude Code 做任务如果遇到它反复出错、反复纠正的环节那就是模板需要补规则的信号。把那些“你纠正过三次以上的问题”沉淀成模板里的一条规则比你在终端里一次次重复解释高效得多。对于刚接触 claude-code-templates 的读者我建议不要一开始就搞一个覆盖所有场景的大仓库。先从一个项目的一个 CLAUDE.md 开始跑两周把发现的问题记录下来再慢慢演化成模板库。等你积累到三五个项目的规则时再把公共部分抽到全局层项目特有部分留在项目层。模板这东西规模不重要贴合自己的真实工作流才重要。