1. 为什么我把 Claude Code 用成了一次调教、处处复用1.1 从一次手忙脚乱的重构说起我接手一个内部项目第一次跑claude进到仓库里自认为已经会玩了把需求一股脑贴进去让它改一个服务接口的重构。结果它先问我项目是不是 Java 后端明明是 Go再问我有没有测试框架明明有折腾了十几轮最后交上来的改动把无关模块一起碰了。问题不在于模型笨而在于我什么上下文都没给它它只能在对话里一点点猜。后来我学乖了每次开新会话之前先手动贴一段项目说明——技术栈、目录结构、常用命令、编码规范。效果立竿见影但很快又出现新问题这段说明我每周要重复贴五六遍而且每次贴的版本还不一样心情好的时候写详细点赶工的时候写潦草点。AI 的表现也跟着我的临场发挥波动。于是我开始研究社区里那些claude-code-templates类仓库发现核心思路特别朴素把人和模型之间重复说的话从每次打一遍变成沉淀成文件、自动加载、按需调用。我把这套思维落地到自己工作流里之后Claude Code 才真正从一个偶尔靠谱的对话窗口变成了一个稳定可预期的项目成员。1.2 模板到底解决了什么三个不可见的成本先说我感受到的三个最大的隐性成本这也是模板体系真正要解决的问题。第一个是上下文口粮。每一次开新会话Claude 对项目的了解基本为零。你告诉它的每一句话都会占用上下文窗口。如果每天重复交代这个项目前端是 React 18 TypeScript后端是 Go数据库是 MySQL测试用 go test这十几行字很快就压缩了你真正用来做事的空间。更可怕的是如果 AI 在对话中途才想起来问你们用什么构建工具那它之前基于错误假设做的判断可能全部要推倒重来。模板的本质是把这些喂给模型的背景知识在会话开始前就放进它脑子里一次到位。第二个是人格漂移。同一个模型你让它用严谨的工程口吻做事和让它随意放飞产出的代码风格、注释习惯、commit message 质量完全是两个水平。没有固定工作守则的时候AI 会随着对话情绪和措辞逐渐跑偏一开始还老老实实跑测试聊到后面就开始跳过验证直接出结论。模板里的 CLAUDE.md 相当于给模型写了一本《员工手册》让它的行为基线稳定在某个水准上。第三个是流程不可控。没有 hooks 和命令约束AI 是否在改动前先读相关文件、是否在提交前跑格式化、是否对危险操作做过确认全靠它自觉。你盯着它的时候还好你一走神它可能直接执行了一个git push --force。我见过太多人抱怨AI 又乱改我代码本质上不是因为模型笨而是你没有把规则固化成强制流程。1.3 claude-code-templates 是什么一个人人可复制的模板仓库claude-code-templates不是一个官方工具也不是某个特定软件的插件而是社区里一类可复用的 Claude Code 配置与提示词模板集合的统称。你可以把这类仓库理解成一套开箱即用的调教手册里面有全局指令文件、高频任务的斜杠命令、自动化钩子、子代理定义、MCP 工具接入方式以及把它们串起来安装脚本。我自己的做法是把这类仓库当作参考再结合自己团队的实际情况重建出一份专属版本。这套东西的价值不在于代码量多少而在于你把跟 AI 协作的隐性知识显式化、版本化、可移植。下面我会拆开讲讲模板体系的每个构件到底管什么然后给出一套可以直接抄作业的搭建流程。2. 模板体系的六个构件一次讲清楚各自管什么2.1 CLAUDE.md智能体的世界观和工作守则CLAUDE.md 是 Claude Code 的指令文件也是整个模板体系的地基。它分两级全局的放在~/.claude/CLAUDE.md会加载进你机器上所有的 Claude Code 会话项目级的放在项目根目录只对这个仓库生效。两者会合并项目级的内容相当于覆盖/追加全局配置所以适合写项目专属的东西。我的经验是全局这份要写你这个人的通用工作方式比如先读后写、小步提交、遇到歧义先问、不擅自升级依赖。项目级那份要写这个项目的具体身世技术栈、目录结构、构建命令、测试命令、代码风格、常见的坑。一句话概括全局份是你的世界观项目份是你的岗位说明书。需要特别注意的是CLAUDE.md 不是 README不是越详细越好。它是要被模型内化的行为准则和背景知识而不是给人看的手册。写太多低密度信息比如贴一整篇项目历史反而会把真正关键的行为约束挤到模型注意力边缘。我自己控制的标准是全局 100 行以内项目 200 到 300 行再长就该考虑拆到 slash command 里了。2.2 Slash Commands把高频任务变成肌肉记忆如果说 CLAUDE.md 定义了你是谁slash command 就定义了你能熟练做什么。它存放在~/.claude/commands/全局或.claude/commands/项目目录下一个 Markdown 文件就是一个命令文件名就是命令名。比如我放一个review.md在会话里输入/review就会触发对应的指令模板。slash command 的高度价值在于压缩操作流程。没有/review的时候你想让 AI 做代码审查得当场描述请审查 src/controllers 下的改动按严重程度列出问题给出修改建议……有了/review之后只需要敲四个字符加上参数剩下的事情模板会替你描述。它本质上是你自己定义的高频工作流而且支持参数插值用{arg}占位调用时把具体内容填进去。我见过不少人的模板库里塞了几十个命令实际上真正高频的根本没几个。我的建议是从三个开始代码审查、补测试、生成 commit message。这三个几乎是每个项目每天都用得上的先把这三条沉淀好再慢慢扩充。2.3 Hooks不靠自觉的质量门禁CLAUDE.md 和 slash command 都是在引导模型但模型偶尔还是会在执行层面犯浑。hooks 就是用来兜底的那道闸门它在特定事件发生时触发你写的脚本执行检查、拦截或自动修复。常见的接入点有PreToolUse模型调用工具前比如执行 bash 命令时、PostToolUse工具调用完成后、Stop模型完成一轮回复后、UserPromptSubmit用户提交消息时。基于这些事件你能实现很多自动化纪律比如在git push前弹确认、在每次编辑完文件后自动跑格式化、在生成了超长日志时压缩输出。hooks 的定位是纪律兜底不是思维替代。它管的是命令级的行为边界而不是帮模型判断代码设计好不好。别指望用 hook 来替你做代码审查那是 slash command 和 subagent 的活儿。用 hook 管好不动不该动的文件、不跳过硬性检查、不静默执行危险操作就已经值回票价了。2.4 Subagents把复杂任务拆给虚拟资深员工单个 Claude 会话里的上下文和注意力是有限的。如果你让它同时承担架构设计、写代码、看测试、审代码四件事它往往会顾此失彼。subagent 就是为了解决这个问题你可以定义多个分工明确的子代理每个子代理有自己独立的系统提示词和工具权限主代理负责调度把任务派给合适的虚拟员工。比如我会定义一个架构师agent职责是分析需求和设计模块边界只读代码不写代码再定义一个审阅者agent专门挑毛病它的指令里甚至可以故意写得苛刻一点。定义方式也很简单在.claude/agents/目录下放一个 Markdown 文件写清楚这个 agent 的角色、职责边界、可用工具和工作流程即可。主力工作的任务分配原则是职责越单一产出越稳定。subagent 的价值不止在于分工还在于隔离上下文。主对话不必一直背着架构师读过的那一堆文件只有在拿到架构师结论时才需要把结论加载回来。这对长任务的上下文管理帮助非常大。2.5 MCP 与输出风格能力底座和语气旋钮MCPModel Context Protocol解决的是工具接入问题。默认情况下Claude Code 能读写文件、执行命令但如果你想让 AI 直接访问数据库、调用浏览器、操作 Figma就需要通过 MCP 服务器把工具暴露给模型。模板库的 MCP 部分通常会预置一批常用接入比如数据库查询、本地文件检索、HTTP 请求调试等跟着跑一遍claude mcp add就能搭建完成。输出风格则是一个经常被忽略的小配置。Claude Code 支持设定回答语气和详略程度比如concise简明、detailed详细、plan计划式、bullet-points要点式。这个配置适合放进模板里因为不同项目的协作风格差异很大做运维脚本时希望输出简短可执行做方案设计时希望输出结构化文档。把风格设置在模板层固定下来能让产出形态稳定而不是每次看模型心情。2.6 一张表看懂六者的分工协同构件存放位置管什么适合沉淀的内容全局 CLAUDE.md~/.claude/CLAUDE.md行为基线与通用工作原则先读后写、小步提交、提问方式项目 CLAUDE.mdproject/CLAUDE.md项目专属上下文技术栈、构建命令、架构说明、常见坑Slash Commands~/.claude/commands/或project/.claude/commands/高频任务的标准化操作代码审查、补测试、提交信息生成Hooksproject/.claude/settings.json或全局 settings命令级纪律兜底危险命令拦截、自动格式化、环境变量注入Subagents~/.claude/agents/或project/.claude/agents/分工协作的虚拟角色架构师、审阅者、测试专员、重构专员MCP 与输出风格claude mcp add及/style外部能力接入与表达形态数据库工具、浏览器工具、格式化风格这六者并不全是并列关系CLAUDE.md 是地基slash command 是操作入口hooks 是执行闸门subagent 是任务分发MCP 是工具箱输出风格是语气旋钮。理解了各自职责后搭建整套模板库就变成了一个按需组合的过程。3. 实操从零搭建你自己的 claude-code-templates3.1 目录结构全局层、项目层、仓库层怎么分我建议把你的模板库本身做成一个 git 仓库这样所有配置都有版本号、有变更记录、能一键同步到新机器。目录结构大致长这样claude-code-templates/ ├── README.md ├── install.sh ├── global/ │ ├── CLAUDE.md │ └── commands/ │ ├── commit.md │ ├── review.md │ └── test.md └── project/ ├── CLAUDE.md ├── commands/ │ └── db-migrate.md ├── agents/ │ └── architect.md └── hooks/ └── check-dirty-files.sh分层的思路很简单global/目录放不依赖具体项目的通用配置安装时软链到~/.claude/project/目录放项目模板你新建仓库时直接把它拷进项目根目录再按需修改。这样既保证了一套基线又保留了项目之间的差异化空间。3.2 全局 CLAUDE.md 怎么写原则优先规矩后置这是我的全局 CLAUDE.md 的核心骨架你可以直接复制改改# Claude Code 全局工作守则 你是一名资深全栈工程师行为基线如下 1. 先读后写任何修改前先读取相关文件确认改动影响范围再动手。 2. 小步提交一次只处理一个逻辑单元。改完代码必须给出验证该改动的具体命令。 3. 遇歧义先问需求不清时基于项目现有代码提出一个倾向方案并让用户确认。 4. 保持现有风格优先延续项目当前代码风格和目录结构除非用户明确要求重构。 5. 不擅自升级依赖不要修改 package.json / go.mod 等文件除非任务明确涉及。 6. 结论前置回复时先给结论再给理由最后给操作步骤。 ## 通用代码规范 - 所有公共函数/接口必须有简短注释说明职责和调用方式。 - 错误信息必须包含上下文哪个操作、哪个文件、失败原因。 - 不允许把 API 密钥、连接串等敏感信息写进代码或日志。 - 文件末尾保留一个换行符遵循各语言常见风格。 ## 通用测试要求 - 修改了核心逻辑时必须补或改对应测试。 - 运行测试前先确认测试命令不清楚时先问。为什么原则优先、规矩后置因为模型对长篇文档的注意力不是均匀分布的靠前的指令更容易被严格执行。项目级 CLAUDE.md 同理最上面放这个项目最不能错的几条硬约束比如数据库迁移必须用 Alembic不得直接改线上配置。3.3 三条高性价比的 Slash Command/review /test /commit先说/review这是我最常用的命令。它的文件内容--- description: 对指定范围的代码做走查式审查 argument-hint: 文件路径或路径范围如 src/controllers --- 请对 {arg} 范围内的代码进行一次走查式审查输出格式如下 1. 概览审查范围、涉及文件、主要职责。 2. 问题清单按严重程度排序 - 每个问题给出位置、问题类型逻辑/性能/可维护性/安全隐患、修复建议。 3. 重复与坏味道指出重复代码、命名问题、过度设计。 4. 低风险优化建议不改变行为的小改进。 审查要求 - 先读取范围内所有相关文件再下结论禁止凭印象判断。 - 不要提出大规模重构建议除非你同时给出收益和风险分析。 - 只输出审查结论不直接修改文件。/commit也很实用它的核心是让模型把杂乱改动整理成规范 commit message--- description: 生成规范化 commit message --- 请先执行 git diff --cached 和 git status阅读暂存区的改动内容然后 1. 按 Conventional Commits 格式生成一条 commit message。 2. 按改动类型归类feat/fix/refactor/docs/test/chore。 3. 每条 commit message 不超过 80 字符正文列出关键变更点。 4. 如果暂存区为空提示用户先执行 git add不要自行暂存文件。/test命令我把它设计成一个测试缺口补齐器--- description: 为指定模块或文件补齐测试 argument-hint: 文件路径或模块名 --- 请为 {arg} 补齐单元测试 1. 先读取被测文件列出可测的行为和边界条件。 2. 参考项目已有测试文件的风格和断言方式。 3. 覆盖主流程、错误路径、边界输入三类场景。 4. 输出建议运行测试的具体命令并说明本次新增用例覆盖了哪些分支。命令设计有一条原则参数尽量少职责尽量纯。/review只审不改/commit只写不推/test只测不修。混合职贵的命令容易让模型在一件事里分心质量反而下来。3.4 Hooks 落地危险命令拦截与自动格式化hooks 在较新的 Claude Code 版本里可以配置在项目的.claude/settings.json或全局配置中。下面是我实际用过的配置核心做了两件事拦截危险 bash 命令编辑文件后自动检查是否有遗留的调试语句。{ hooks: { PreToolUse: [ { matcher: Bash(git push --force|rm -rf|git reset --hard|DROP TABLE), hooks: [ { type: command, command: python3 ~/.claude/hooks/confirm_dangerous.py \$CLAUDE_TOOL_INPUT\ } ] } ], PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: python3 ~/.claude/hooks/check_debug_statement.py \$CLAUDE_FILE_PATHS\ } ] } ] } }confirm_dangerous.py里做的事情很简单读取环境变量CLAUDE_TOOL_INPUT如果检测到危险命令就输出一段明确的中断提示否则输出PASS。之所以用脚本而不是直接写在 JSON 里是因为脚本可以写复杂判断而且好测试。注意一点hook 的 matcher 是正则表达式匹配的是工具调用描述。如果匹配太宽比如matcher: Bash.*每个 bash 命令都会触发一次脚本调用对话体验会明显变卡。我的建议是把匹配范围收窄到确实需要确认的那几条命令。3.5 Subagents 示例一个只读不写的架构师subagent 定义放在.claude/agents/architect.md内容风格是角色 职责边界 工作流程--- name: architect description: 需求分析与系统设计。当用户需要设计方案、模块拆分、接口定义时使用。 tools: Read, Grep, Glob --- 你是一名资深系统架构师。工作方式如下 1. 需求澄清先列出你理解的需求标注不确定的约束条件向用户确认。 2. 现状分析读取项目关键配置文件如 go.mod、package.json、Makefile和相关模块代码理解现有架构。 3. 方案对比给出至少两个可行方案从实现成本、维护成本、风险三个维度对比给出明确推荐。 4. 输出设计模块划分、接口签名、数据模型、迁移路径。只给出关键伪代码不写完整实现。 5. 边界约束你没有修改文件的权限只做分析和设计。所有结论输出在回复中。关键技巧在 frontmatter 的tools字段我给 architecture 只开了Read, Grep, Glob三个只读工具它物理上就不可能改文件。这和人类团队里架构师只画图纸不进工地是一个道理。权限边界本身也是对角色行为最硬的约束。3.6 用 install.sh 一键安装并纳入版本管理把模板库变成 git 仓库之后新机器上只需要跑一次安装脚本就能全部就位#!/usr/bin/env bash set -euo pipefail CLAUDE_HOME${CLAUDE_CONFIG_DIR:-$HOME/.claude} SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) mkdir -p $CLAUDE_HOME/commands $CLAUDE_HOME/agents # 全局指令 ln -sf $SCRIPT_DIR/global/CLAUDE.md $CLAUDE_HOME/CLAUDE.md # 全局斜杠命令 for f in $SCRIPT_DIR/global/commands/*.md; do ln -sf $(pwd)/$f $CLAUDE_HOME/commands/$(basename $f) done # 全局子代理 for f in $SCRIPT_DIR/global/agents/*.md; do ln -sf $(pwd)/$f $CLAUDE_HOME/agents/$(basename $f) done echo 安装完成。运行 claude用 /help 或 /context 验证配置生效。用软链而不是拷贝是因为软链能让改模板仓库和让 Claude Code 生效这两个动作保持同步。你改了模板提交到 git下次在任何已安装的机器上 pull 一下配置就自动更新。版本控制和配置管理由此打通。4. 模板设计里最容易翻车的四个地方4.1 负面指令的白熊效应别写不要用 X我在第一版 CLAUDE.md 里写过一句本项目不要使用 numpy结果模型在每次涉及数组处理时都频繁提到 numpy甚至写代码时会故意绕开之后跟一句这里改用 list 避免引入 numpy。这就是典型的负面指令问题你越强调一件事模型越容易在上下文里高频检索到它。正面的写法是给替代方案比如数组处理统一使用 polars 库以兼容项目现行的数据处理标准。把不要做什么翻译成要做什么模型就不需要在检索时不断撞见那个被你禁止的词。这个原则适用于所有指令文件给行为一个正面的出口而不是给一个禁令清单。4.2 上下文口粮分配CLAUDE.md 不是越长越好我见过有人把 CLAUDE.md 写成了一万字的长文包含公司制度、社会规则、各种提示词技巧。结果模型越到后面越缺氧关键约束反而没执行。上下文窗口是有限的模板塞得越多留给实际任务和对话历史的空间就越少。我自己踩过几次坑后的经验是CLAUDE.md 里只保留三类东西——必须遵守的行为底线、项目最核心的现状信息、绝对不能被搞错的硬约束。其余内容比如某个命令的详细用法、某种模式的完整代码示例放进 slash command 按需加载。就像你不会把整个流程手册贴在一页纸上随身带而是用到哪章查哪章。4.3 Hook 脚本变成事故源头先 dry-run 再上线这是我翻车最惨的一次。我写了一个PreToolUse钩子用来在模型执行git push前弹确认。脚本本身没有 bug但我在 matcher 里写得太宽把*git*都拦了下来结果模型每次想执行任何含 git 的命令都被卡住对话直接陷入弹确认-执行-再弹确认的死循环。那时候我才意识到hook 脚本不是写了就行它本身也是代码至少要有基本的防御性。现在我的流程是任何 hook 脚本先单独在终端里跑一遍用模拟的环境变量输入测过行为确认输出符合预期后再挂到配置里。上线之后开一个新会话故意触发一次对应事件确认不会卡住。hooks 毕竟是拦在模型和工具之间的闸门闸门失灵和没有闸门一样危险甚至更隐蔽。4.4 命令与参数的边界把命令当接口来设计slash command 的参数插值{arg}看着简单实际用起来有个不小的坑参数内容里的空格和特殊字符可能导致整个命令语义偏掉。比如/review src/controllers|user.ts这种参数如果模板里没有处理好分隔符模型解析时就会把多出来的部分当成额外内容。我的处理方式是两件事第一所有命令模板里对{arg}的使用都保持单一且置于句末第二在模板中明确声明参数格式比如参数必须是文件路径或 glob 表达式。更进一步我会在命令文件里加一行如果参数看起来不像路径请先和用户确认再继续这条简单规则让很多解析混乱的问题被挡在源头。本质上是把命令当作一个函数来设计入参格式、边界行为、异常分支都要提前声明清楚。5. 跑了一段时间后的真实反馈与迭代心得5.1 项目前后对比审查通过率、返工率、上下文消耗用了模板体系大概两个月后我简单做了个差不多的对比。重构类任务的一次性通过率指的是AI 给出的第一版改动被直接采纳的比例从大概三成提到了七成上下代码审查的结果从经常泛泛而谈变成了能定位到具体文件的具体行并给出可执行的建议上下文消耗的直观感受是同一类任务的对话轮次明显变少因为不再需要前十五轮都在给 AI 普及项目常识。当然这不是一个严格控制的实验变量很多。但方向是一致的当模型的基线行为稳定在被明确定义的工作方式上时输出方差会显著缩小。AI 的下限被模板抬起来了而上限某种程度上取决于你写进去的领域知识和约束质量。5.2 版本化模板库的几个实战建议把模板库当代码库管理这件事值得多说几句。我一开始只是随意地在~/.claude/里改文件改来改去自己都忘了哪条规则是哪一版加的。后来把模板库变成 git 仓库以后每个命令的新增、每条工作守则的调整都有了 commit 记录。有问题可以直接回滚旧版团队协作时可以 code review 模板变更新机器装环境也不再依赖模糊的记忆。另外我强烈建议给模板库写一个精简的 README记录几件事这个库包含哪些命令、每个命令的适用范围、已知的边界问题。别小看这份文档你三个月后回来改模板时会发现它比任何注释都有用。维护模板库的成本大约每周 15 分钟换来的是每工作日省下的反复沟通时间这笔账很划算。5.3 最后分享一个我最近加进去的小技巧最近我加了一个特别简单但效果很好的命令/todo。它不做任何高深的事只是让模型在开始一个多步骤任务前先输出一份带验收标准的 TODO 清单并且每完成一步就标记一次进度。听起来平平无奇但这个小命令把AI 一次脑暴完所有东西然后开始埋头写代码的坏习惯给改了任务被拆成可检查的步骤中途你可以随时插话调整方向不再需要等它全部做完才发现方向错了。还有一个近乎零成本的改动我也很推荐在全局 CLAUDE.md 加一条每个操作完成后用一句话说明下一步建议。这句话让 AI 从被动执行变成了主动引导在很多场景下都能帮我们提前发现遗漏的测试和没考虑到的影响范围。模板这种东西最忌讳一步到位。先搭一个能用的最小闭环然后在日常使用中持续往里加你真正高频需要的东西——它才会越用越顺手。