最近我在整理自己一套长期在用的 Claude Code 启动配置时顺手把它开源成了claude-code-templates这个项目。起因很简单每次在新机器上初始化一个项目我都得重新回忆那些零零散散的规则、命令和习惯设置既费时间又容易遗漏。后来我把这些沉淀成一套模板体系用CLAUDE.md文件、目录约定和一小组脚本把环境固化下来新机器上复制过去就能直接进入工作状态。这个项目适合两类人一类是刚接触 Claude Code、想少走弯路的新手另一类是已经用了一段时间、但觉得每次配置都很烦的老手。文章里我会把模板的设计思路、目录结构、关键参数和坑都摊开讲你可以直接抄走用也可以按自己的习惯改造。所有内容都是我实测跑过、踩过坑之后整理出来的不是网上那种“看起来很美”的包装教程。1. 模板体系整体设计与拆解1.1 为什么不是“一份配置走天下”很多人第一次看到claude-code-templates时第一反应是“配置放一个文件里不就行了搞这么复杂干嘛”。说实话我也试过把所有内容塞进一个超长的CLAUDE.md结果用了两周就放弃了。原因很简单不同的项目对 Claude Code 的行为要求差太远了。举几个真实场景一个 Go 后端服务我希望它在提交前自动跑go vet和go test ./...并且严格遵守项目已有的目录划分。一个前端 React 项目我希望它优先使用已有的组件库不要动不动就建议引入新的依赖CSS 方案也要保持一致。一个写文档的仓库我希望它把语气调成技术文档风格不要用“我们”、“大家”这类口语化表达。这三个需求如果写在同一份全局配置文件里要么互相打架要么又臭又长。所以模板的核心思路是分三层全局层适合所有项目的基础习惯比如“禁止破坏性操作前不询问”“生成代码时要附带简要说明”。项目层针对特定技术栈的规则比如 Go 项目的测试命令、前端项目的 lint 规则。会话层临时指定的指令比如“这次只改接口定义不动业务逻辑”。这套分层和claude-code-templates里的目录结构是对应的。全局规则放在~/.claude/下项目规则放在仓库根的CLAUDE.md里临时指令则通过!命令或对话直接给。模板本身只是把前两层固化成了可复制的文件让你不需要每次从零开始写。1.2 模板要解决的核心问题是什么如果你只用 Claude Code 做简单的问答和代码生成那模板确实可有可无。但只要你把它当生产力工具用——每天跑几十次命令、让它操作文件、执行测试、跨模块重构——就会发现没有约束的对话式操作有多不可控。我遇到过几个典型问题这也是做这套模板的动机第一个问题是上下文漂移。对话长了以后模型会慢慢忽略你开局说的“不要修改测试文件”这类约束开始自作主张。模板通过把关键约束写进启动时的CLAUDE.md相当于每次会话开始就“重新强调”一遍边界漂移概率明显下降。第二个问题是重复劳动。每个项目都要解释“我们用的是 pnpm 不是 npm”“跑测试用make test不要用go test”“代码风格遵循现有文件不要用 prettier 重排”。这些话说一次两次还行长期重复就是纯浪费时间。写成规则后Claude Code 启动时自动读取不用重复教。第三个问题是危险操作缺乏刹车。默认情况下Claude Code 执行文件修改类操作时会弹确认但你可以通过配置调整这个行为。模板里我默认保留// #!危险命令的确认机制并写明了哪些操作不允许自动执行相当于给它装了一套护栏。模板的目录设计就是围绕这三个问题展开的用规则文件对抗漂移用预设命令对抗重复用权限配置对抗风险。2. 模板的目录结构与核心文件解析2.1 看看一个真实模板长什么样这里是我当前仓库里的目录结构简化掉无关文件后大概是这个样子claude-code-templates/ ├── README.md ├── project/ │ ├── CLAUDE.md │ └── .claude/ │ ├── commands/ │ │ ├── code-review.md │ │ ├── test.md │ │ └── release.md │ ├── agents/ │ │ ├── reviewer.md │ │ └── debugger.md │ └── hooks/ │ └── pre-commit.sh ├── global/ │ ├── CLAUDE.md │ └── settings.example.json └── install.sh逐层说。project/CLAUDE.md是给具体项目用的通常放在仓库根目录内容主要是技术栈相关规则。global/CLAUDE.md是给~/.claude/CLAUDE.md准备的放通用习惯。.claude/commands/里是预设的斜杠命令.claude/agents/里是子代理定义hooks/里是和 git 钩子配合的脚本。这个结构不是拍脑袋定的它和 Claude Code 实际的读取规则是匹配的。项目根目录的CLAUDE.md会在启动时自动加载~/.claude/CLAUDE.md则是全局自动加载子目录里的命令和代理文件用于动态扩展。模板的价值就是把“该放哪、怎么写、每类文件能干什么”替你踩过一遍。2.2 CLAUDE.md 文件里到底写什么CLAUDE.md是这套体系的核心格式其实就是 Markdown但内容组织有讲究。我见过不少人把文档里所有要求一口气写完结果就是又乱又没人看。我的做法是把内容分成固定几个目录段落身份与职责一段话说明这个项目或者这套规则面向什么场景。比如“你是本项目的代码协作者负责实现功能、修复问题、编写测试所有改动必须符合现有代码风格”。关键约束禁止做的事优先级最高。比如“不要修改vendor/目录下的任何文件”“不要使用any类型”“不要在没有测试的情况下提交重构”。工作流正常执行任务的流程。比如“完成代码修改后必须运行make lint和make test”“提交信息使用 Conventional Commits 格式”。常用命令把项目里高频使用的命令写成列表让 Claude Code 优先使用。这样做的好处是即使 Claude Code 在长对话中忘了某个细节它也可以在需要时回看CLAUDE.md的对应段落。前提是段落标题足够清晰能让它在“翻文档”的时候快速定位。2.3 全局规则和项目规则怎么划分全局CLAUDE.md里我放的是不太会变的东西比如回答问题时先看现有代码不要凭空创造修改文件前先展示 diff重要改动必须等确认不确定需求时先提问不要猜涉及删除操作时必须显式确认项目级CLAUDE.md里放的是会随项目变化的东西比如后端用哪个框架路由怎么组织数据库迁移用什么工具命名规范前端组件库是哪个样式方案是什么划分标准很简单如果换一个项目你还需要这句话就放全局如果这句话只对这个仓库有意义就放项目级。新手容易犯的错是全都堆在全局换项目后 Claude Code 反而被旧规则束缚做出不合适的行为。3. 实战搭建从零开始做一个自己的模板3.1 安装和初始化克隆模板仓库后第一步是运行install.sh它会做三件事#!/usr/bin/env bash set -euo pipefail CONFIG_DIR${HOME}/.claude mkdir -p ${CONFIG_DIR}/commands mkdir -p ${CONFIG_DIR}/agents mkdir -p ${CONFIG_DIR}/hooks if [ -f ${CONFIG_DIR}/CLAUDE.md ]; then cp ${CONFIG_DIR}/CLAUDE.md ${CONFIG_DIR}/CLAUDE.md.bak fi cp global/CLAUDE.md ${CONFIG_DIR}/CLAUDE.md cp -r global/commands/. ${CONFIG_DIR}/commands/ 2/dev/null || true cp -r global/agents/. ${CONFIG_DIR}/agents/ 2/dev/null || true echo done这里有几个细节要注意。首先是set -euo pipefail因为安装脚本里任何一步失败都不应该继续否则容易出现半配置状态。其次是备份逻辑直接覆盖~/.claude/CLAUDE.md风险太高先备份是最基本的安全习惯。最后是mkdir -p避免因目录不存在而报错。如果你更想手动配置也可以只复制文件到对应位置。全局规则放在用户目录项目规则就放进仓库根目录然后自己在 Claude Code 里验证是否生效。3.2 设置核心参数模型、权限与危险命令settings.json是 Claude Code 的行为开关里面有几个参数值得一提。模板示例里我放了基础配置{ model: claude-sonnet-4-20250514, permissions: { defaultMode: claudeSonnet }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash ~/.claude/hooks/check-dangerous.sh } ] } ] } }model是指定默认模型如果你在不同项目里用了不同档位的模型可以在项目级settings.json覆盖。permissions.defaultMode影响交互模式保守一点就保留确认机制。hooks 部分我是用一个脚本拦截 Bash 类工具调用检查命令是否匹配危险操作列表。这个检查脚本的写法也简单核心逻辑是正则匹配#!/usr/bin/env bash input$1 dangerous_patterns( rm -rf git reset --hard git clean -f :(){:|:};: ) for pattern in ${dangerous_patterns[]}; do if echo $input | grep -qE $pattern; then echo blocked: ${pattern} exit 2 fi done exit 0这里注意hook 的退出码是2时表示阻断工具调用0表示放行。别搞反了否则危险命令会被直接放过去那就失去保护意义了。3.3 写一个实用的斜杠命令斜杠命令是 Claude Code 里最能提升效率的功能之一。它本质上就是一条写好的指令模板你在对话框里输入/testClaude Code 会读取对应的 Markdown 文件把里面的内容作为指令发给模型。我项目里最常用的是这个--- description: 运行完整测试集并汇报结果 --- 请按以下步骤操作 1. 检查当前分支确认是否在功能分支上main/master 上不要直接跑全部测试 2. 运行 make test 命令 3. 如果测试失败先看错误日志定位原因再修改代码 4. 重新运行失败用例确认修复后再跑全量测试 5. 汇报最终结果附上关键日志片段这个文件的 frontmatter 里的description字段非常关键。Claude Code 会根据描述字段来判断什么时候推荐这个命令给你。写清楚它做的事比你随便写“跑测试”要有用得多因为模型会结合上下文判断是否适合调起。在模板里我放了几个不同用途的命令文件核心思路都是一样的把高频操作从“一段上下文的对话”变成“一条可复用的命令”把流程固定下来避免每次随机发挥。4. 常见问题与排查技巧实录4.1 CLAUDE.md 太长导致上下文膨胀这是我被问得最多的一个问题规则写多了以后发现每次启动会话都要消耗很多 token上下文窗口被规则占掉一大截。我的建议分两步。第一步精简全局规则。全局规则只保留那些“违反一次都受不了”的内容例如“修改文件前必须先展示 diff”其他建议性的内容一律砍掉。项目规则同理但可以比全局多写一点因为它只在这个仓库里生效。第二步把细节挪到命令或代理文件里。比如“code review 时关注哪些点”这种内容平时用不到每次启动都加载纯属浪费。把它写成/code-review命令只在需要的时候调用。这样CLAUDE.md保持精炼token 消耗也降下来了。如果你发现CLAUDE.md非要超过一千行才能覆盖需求那大概率是你试图让模型记住太多琐碎事实。换个思路让模型在需要时去读文档而不是把所有文档内容塞进上下文。4.2 斜杠命令不生效或者找不到文件我自己也踩过这个坑。某个版本的 Claude Code 更新后斜杠命令的搜索路径发生了变化导致我放在项目.claude/commands/下的命令突然全失效了。排查时先确认几件事文件是不是放在正确的目录下。全局命令路径是~/.claude/commands/项目命令路径是project/.claude/commands/。文件名是不是符合规范。斜杠命令要求用.md后缀文件名就是命令名。确认当前目录是不是已经在项目里。如果你在子目录下启动 Claude Code它可能不会往上找父目录的.claude。最后一个坑是权限问题。如果你用的是公司电脑或者受限环境~/.claude目录的写权限可能导致命令文件读到了旧版本。我一般直接重启会话并重新加载配置大部分情况都能解决。4.3 hooks 不触发或者误杀正常操作hooks 的设计初衷是给你一个干预工具调用的机会但实际用起来比文档描述的更容易出错。我遇到过两个典型情况第一种是 hook 脚本没有执行权限。复制脚本文件时忘了chmod x结果就是 hook 静默失败危险命令照样执行。这个问题特别隐蔽排查方法是在脚本开头加一行echo hook triggered /tmp/claude-hook.log先确认它到底有没有被调用。第二种是误杀。比如我的“危险命令”正则里写了rm -rf但实际项目里有个合法场景需要清理临时目录。解决办法是把白名单机制也加上allow_patterns( rm -rf ./build rm -rf ./tmp ) for pattern in ${allow_patterns[]}; do if echo $input | grep -qE $pattern; then exit 0 fi done先查白名单再查黑名单这样既保护安全又不影响正常操作。模板里的check-dangerous.sh也是这么设计的我在注释里写清楚了这个顺序避免以后自己忘了。4.4 多模板混用时的冲突处理当你同时维护多个项目每个项目都有自己的CLAUDE.md和settings.json时冲突就难免了。比如我在模板里全局规定“测试用 make”但某个项目实际用的是 pnpm如果项目级规则没有覆盖全局模型就会傻乎乎地执行make test直接报错。解决方式是在项目级CLAUDE.md的“关键约束”一栏里显式写“本项目所有测试命令使用 pnpm不要使用 make”并且把它放在靠前的位置。Claude Code 在合并规则时项目级的优先级高于全局级所以只要写清楚它基本不会用错。更极端的场景是同一个仓库里同时有前端和后端代码前后端的 lint 规则完全不同。我的做法是拆成两个子代理一个负责前端、一个负责后端并且在每个子代理文件里写死对应的命令和风格。这样比在CLAUDE.md里写一堆“如果……那么……”要有效得多。5. 模板的维护、迭代与扩展方向5.1 如何让模板跟着大模型版本走Claude Code 本身的规则文件格式和 hooks 机制会随着版本迭代而变化所以claude-code-templates不是一个写完就不动的死项目。我每隔一段时间都会做一次检查新版本是否引入了新的settings.json字段斜杠命令的 frontmatter 格式是否有变化hooks 的退出码约定有没有改有没有新增的权限模式这个检查流程本身也可以“模板化”。比如我在全局CLAUDE.md里写了一条规则当 Claude Code 版本更新后先跑一遍项目的核心流程确认模板里的关键命令还能正常使用再继续日常开发。虽然说起来简单但坚持做的人不多也正是这种更新节奏让模板始终保持可用。5.2 模板的个性化扩展把自己常用的东西加进去模板真正发挥价值是在你把它改造成“自己的形状”之后。我给你几个扩展方向都是我自己验证过的把企业内部命令包进去。比如你所在团队用kubectl、docker compose、terraform之类的工具可以把常用命令封装成斜杠命令。重点是把团队默认参数写进命令比如kubectl -n production get pods而不是让模型猜参数。加上项目特定的知识库入口。很多项目有内部文档但 Claude Code 不知道去哪找。你可以在项目级规则里写“当用户提到部署流程时先读取docs/deployment.md再回答”相当于给它一个导航入口。给代码审查定制专门的子代理。默认情况下Claude Code 扮演的是全能助手但如果你希望它在 code review 时特别较真地检查并发问题或者特别关注安全漏洞就可以在.claude/agents/里定义一个security-reviewer并在里面写清楚关注点。这些扩展不会让模板本身变得更复杂因为它只是往已有的框架里塞内容。框架的好处在于你知道该往哪个目录放规则写出来能生效而不是变成了装饰文件。6. 更深一层模板与 Agent 模式的结合6.1 Agents 与模板的区别和联系很多人在看到.claude/agents/目录时会把它当作“模板的子集”来看。其实不完全是这样Agent 是比CLAUDE.md更细粒度的行为封装。一个CLAUDE.md可能定义了整个项目的行为底线而一个 Agent 文件则定义了一个“角色”在特定任务里的响应方式。举个例子。我的模板里有一个reviewer.md它可以让 Claude Code 在收到/review命令时用代码审查专家的身份去检查代码而不是普通助手的身份。这意味着它会更关注变更的行、函数签名、边界条件和测试覆盖而不是泛泛地说“代码写得不错”。Agent 文件的写法其实不复杂本质上就是一个CLAUDE.md的缩小版区别在于它需要显式描述“你是一个具备某方面专长的人”。模板里我放了一些常用角色比如 debugger、reviewer、release-manager每个文件都忠实地写了各自的工作流和禁忌。6.2 用模板固化团队工作流如果你在团队里用 Claude Code模板的价值会被放大。每次新同事加入不需要靠口头解释“这个项目是怎么跑测试的”直接把模板仓库克隆下来装好一切默认行为就已经对齐了。这比任何新人培训文档都要直观因为它直接作用于日常工作。我见过做得比较好的团队实践是把claude-code-templates作为内部共享仓库每次项目配置升级时先提 PR合并后再同步到各组成员。这样规则演进有记录不是某个人默默改了本地的CLAUDE.md然后别人全都不知道。当然这样做的前提是模板本身要足够稳定不能三天两头大改。所以我把频繁变动的部分都塞进 commands 目录而不动CLAUDE.md的基础框架。这样日常改的都是增量基础规则很少动团队同步成本也低。7. 几条个人实战总结与建议最后分享几条从我自己的使用经历里沉淀下来的心得挑重要的说。第一条CLAUDE.md 不是文档是行为规范。写它的时候不要像写 README 一样去介绍项目背景而是直接写“看到这段代码时你应该怎么做”。每一条都要能落到具体行为上否则就是无效内容。我早期写的规则里有“代码要高质量”这种话后来发现毫无用处删掉反而清爽。第二条配置文件出问题时先用二分法排查。比如某次更新后 Claude Code 表现异常直接怀疑所有规则会让人崩溃。我的做法是先注释掉项目级CLAUDE.md看问题还在不在再注释掉全局CLAUDE.md一层层排除。真正出问题的往往就是最近改动的那几行。第三条模板是为下一次会话准备的。很多人觉得当前会话里已经把所有需求讲清楚了模板可有可无。但实际上模板最大的价值在于“下一个会话不用重新讲”。你中断三天后再回来模型不会记得之前的上下文却能通过CLAUDE.md快速恢复到原来的状态。这种“状态恢复”能力才是模板体系真正的杀手锏。第四条花时间维护模板其实就是降低长期成本。每次遇到重复的坑就把它写进规则每次发现模型老犯同类错误就用命令或 hook 卡住。模板不是一次性工程它是你使用 Claude Code 过程中的“活的知识库”。维护越勤后面的每次操作越轻松。