1. 为什么模板化是Claude Code使用的分水岭1.1 从每次都重新说一遍到结构即默认行为用Claude Code一段时间的人大概率都经历过这么个阶段每开一个新项目第一件事就是花十几二十分钟把上下文灌进去——咱们这个项目是Python写的用FastAPI数据库是PostgreSQL测试必须用pytest代码风格遵循Black不要随便改依赖版本提交信息要按Conventional Commits写……。说的时候是清楚了可第二天换个终端继续干活它又忘了。尤其是多项目并行的时候来回切换上下文语境AI一会儿把A项目的目录结构套到B项目上一会儿又用B项目的测试框架跑A项目的用例心累得很。后来我想明白一件事Claude Code这种东西本质是一个上下文驱动的执行引擎它缺的不是能力是稳定可靠的上下文来源。你把规则放在对话里规则就是一次性的你把规则放在文件里规则就成了项目的默认行为。这正是模板化能解决的核心问题——把那些反复口头强调的东西固化成结构、文件和约定让AI在没有你絮叨的情况下自己做出符合预期的行为。所以我开始系统地整理自己的Claude Code模板配置也就是现在的 claude-code-templates 这套方案。它不是某个单一文件而是由CLAUDE.md记忆文件、斜杠命令、Hook规则、目录脚手架共同组成的一套项目初始化资产。做完之后新项目从clone到进入理想工作流基本五分钟就能搞定而且团队里其他人拉下来同一套模板行为表现也是接近的。1.2 模板到底要包含哪几层东西要理解模板方案先得理解Claude Code的配置体系是分层的。我的理解是四个层次各有各的管辖区用户级配置~/.claude/包括用户级CLAUDE.md、全局斜杠命令、全局Hook作用于所有项目。工作区级配置.claude/ 在工作区根目录作用于整个多仓库工作区适合放跨仓库的通用约定。项目级配置项目根目录的CLAUDE.md和 .claude/作用于单个仓库放这个项目的专属规则。会话级指令你在对话里补充的临时要求优先级最高但最不稳定。一个常见的误区是把所有东西都塞进项目级CLAUDE.md结果就是一个文件几千行AI每次读上下文都要吃掉几千token反而影响了主要任务。模板化的核心其实是职责划分就近生效近的管近的远的管远的各层只放自己该管的内容。这一节先搭认知框架下面我用完整踩过的路径来讲每一层的具体设计和写法。2. 三层CLAUDE.md的职责划分工作区、项目、用户2.1 用户级个人偏好与全局纪律用户级CLAUDE.md放在~/.claude/CLAUDE.md它的特点是不管你在哪个项目里它都会生效。这个东西最适合放什么我个人的经验是放三样东西第一跨项目通用的编码习惯。比如变量命名要有意义不允许出现a、b、tmp这种无法理解的缩写所有修改变动必须同步更新相关测试字符串拼接用f-string而不是号。这些规则对Python、JavaScript、Shell都适用放在用户级就不用每个项目的CLAUDE.md里重复写。第二对你个人工作方式的约束。比如回答技术问题时先给结论再展开遇到不确定的需求先列出假设清单再动手只使用项目环境中已经安装的依赖不要擅自安装新包。这其实是在给AI立人设让它配合你的协作习惯。第三安全底线。这是我的血泪教训——有段时间AI动不动就给我执行git push --force或者在我没允许的情况下修改数据库连接配置。现在我会在用户级CLAUDE.md里明确写涉及git push、rm、DROP TABLE、生产环境操作之前必须停止并向我确认。有人可能担心用户级配置会污染不同项目的专属逻辑。这种担心合理解决办法是用户级只写纪律不写业务。纪律是通用的业务是专属的一混就容易出错。比如你用户级写了所有时间字段一律用UTC存储那没问题你要是写了本项目数据库密码是xxx那这个配置就彻底没法在不同项目间复用了。2.2 项目级仓库的红线与上下文压缩项目级CLAUDE.md放在仓库根目录这是大家最先接触也最容易用错的一层。它的正确打开方式有两个关键词红线、压缩。先说红线。每个项目都有一些天条比如这个模块是生成代码禁止手改数据库迁移只能由migration_runner脚本执行对外接口的返回格式必须符合v2协议。这些规则写进项目级CLAUDE.mdAI就不会越界。之前我们有个项目AI为了快速修复一个类型问题绕过了统一的数据访问层直接写原生SQL去查表差点把生产数据搞乱。原因就是你根本没告诉过它这个项目的红线在哪。AI没有道德直觉它只有规则意识——你不写它就按自己理解的最优解来而这个最优解往往不是你想要的。再说压缩。AI能携带的上下文总量有限CLAUDE.md不是越长越好。我的做法是项目级CLAUDE.md保持在200行以内只写目录结构摘要、技术栈清单、构建与测试命令、红线规则、代码风格要点这五类。像为什么这么设计某模块的历史包袱这类细节放到/docs或者代码注释里并告诉AI需要时自己去翻/docs/AI_CONTEXT.md。这叫上下文外置。我踩过的坑是一开始把项目背景、架构演进历史全部堆进CLAUDE.md结果每次对话光读记忆文件就消耗了差不多3000 tokenAI的半条命都没了。建议大家可以做一个实验把CLAUDE.md压到原来的一半观察一下回复质量很多时候不仅没变差反而因为上下文干净而变好了。想到这里我突然意识到AI其实跟人一样规则太多等于没有规则。2.3 工作区级多仓库协作的粘合剂工作区级CLAUDE.md是很多人忽略但实际非常有价值的一层。它的作用范围是整个工作区/多仓库根目录。什么时候需要用最典型的是微服务项目、前后端分离的多仓库项目。比如你工作区下有frontend、backend、shared-libs三个仓库经常需要AI跨仓库改代码。如果只在每个仓库放项目级CLAUDE.mdAI对整体架构是什么、三个仓库之间怎么通信、改动需要同步哪些仓库是缺乏全局认知的。工作区级CLAUDE.md正好补这一段可以写frontend调用backend的/api/v1接口改动接口必须同时更新OpenAPI文档和前端对应类型定义shared-libs是被两个业务仓库依赖的公共库任何对外API变更必须先提出变更说明。实际效果上工作区级配置相当于给AI一张地图让它清楚每个仓库的边界和关联。项目级配置负责地方法规用户级配置负责宪法三个层级的优先级和覆盖范围互不冲突。曾经处理过一个跨仓库问题后端把接口字段做了重命名但前端类型定义没跟着更新整个联调环境直接崩了。后来我在工作区级CLAUDE.md里强制加了接口变更必须同步前后端类型这一条这类问题才彻底绝迹。2.4 一个可以抄的CLAUDE.md骨架很多人看了一堆理论还是不知道怎么落笔我直接放一个经过几个项目验证的CLAUDE.md骨架项目级你们按需删改# 项目概览 该仓库是xxx服务的核心实现基于FastAPIPostgreSQL部署环境分为staging和production。 # 技术栈与关键路径 - 框架: FastAPI 0.1xx, 使用 app/main.py 作为入口 - ORM: SQLAlchemy 2.x, 所有查询必须经过 repository 层, 禁止直接使用 session.execute 写裸SQL - 测试: pytest, 测试文件与源码目录一一对应 - 格式化: Ruff, format与lint配置在 pyproject.toml # 常用命令 - 本地启动: uv run uvicorn app.main:app --reload - 运行测试: uv run pytest -x -q - lint检查: uv run ruff check . # 红线规则 - 禁止修改 migration/ 下的已发布迁移; 新变更必须新建迁移文件 - 外部API返回结构必须保持 {code, message, data} 三层结构 - 凡是涉及用户隐私字段的改动必须经过评审标注 [PRIVACY] # 代码风格与提交规范 - 提交信息使用 Conventional Commits, 例如 feat(api): add pagination - 新代码必须附带对应单测, 覆盖率不得低于新增代码的80%写到这里再补充一个经验CLAUDE.md写完之后别急着用先让它自我问答。最简单的验证方式就是你直接问AI根据你的记忆文件这个项目的技术栈是什么红线有哪些如果它答得上来说明文件结构是有效信息如果它答得含含糊糊说明你的文件写成了摆设需要重写。这种验证方式成本极低但能避免你带着一份根本不被AI理解的配置跑好几周。3. 斜杠命令模板把高频操作固化成固定动作3.1 命令模板的文件结构与格式CLAUDE.md管的是AI怎么想斜杠命令Slash Command管的是AI怎么干活。斜杠命令本质上是把一段完整的、可复用的指令做成一个固定入口你在对话里输入/commit、/review、/refactorAI就会执行对应的模板指令。命令文件的格式不复杂本质上是一个带YAML frontmatter的Markdown文件放在 .claude/commands/ 目录下。文件名就是命令名frontmatter里写描述和参数提示正文里写具体执行步骤和逻辑。最核心的机制是变量占位符$ARGUMENTS代表用户输入斜杠命令时附带的所有参数$1、$2代表第一个、第二个参数。我个人的项目里命令模板被放在 .claude/commands/ 下跟随仓库走和CLAUDE.md分开管理。为什么要分开因为斜杠命令往往带着复杂的执行逻辑和脚本操作单独管理能避免把记忆文件变得臃肿也方便单独做版本控制。想象一下如果你把五个命令模板全塞进CLAUDE.md那AI每次读上下文都要多出几千token而这些内容只在触发命令时才真正需要。一个最简单的命令模板长这样--- description: 按规范生成 commit message argument-hint: [type] 简要描述 --- 请根据当前 git diff 内容生成一个符合 Conventional Commits 规范的提交信息。 要求 - type 从 feat/fix/docs/refactor/test/chore 中选择若用户提供了 $1 则优先使用 $1 - 提交信息不超过80个字符 - 根据 diff 的关键改动点生成描述 - 不得包含任何 AI 相关字样或多余解释3.2 我日常必配的六个命令模板用好斜杠命令的关键在于什么样的高频动作值得固化成命令。我列一下自己一直在用的六个每个都有明确的场景/review代码审查。读取git diff按正确性、安全性、性能、可维护性四个维度输出审查意见并标出每个问题的严重级别。以前我都是手动复制diff丢给AI让它看现在一条命令搞定。/fix修复指定问题。接收问题描述或报错信息定位根因给出修复方案并要求它先说明根因再改代码防止AI上来就一顿乱改。/refactor小范围重构。限定改动边界要求保持接口兼容并自动运行测试验证。/test为本次改动补充测试。自动识别改动函数生成对应的pytest用例标记缺失的mock和断言。/commit生成符合规范的提交信息并追问是否需要我确认后执行git commit。/explain解释一段代码/一个目录结构输出这段代码的作用、核心流程、潜在风险三段式说明。这六个命令基本覆盖了我日常80%的重复性操作。它们的共同特点是有明确的输入形态、有固定的输出格式、有明确的质量要求。如果你的某个操作流程里这三个要素缺了一个说明它还不适合固化成命令先靠对话解决更灵活。比如帮我看看为什么这个性能有瓶颈这类开放性问题就不适合做成命令——因为它没有清晰的输入边界。3.3 参数透传、子命令与占位符技巧命令模板用好之后我发现两个进阶技巧值得分享。第一个是参数透传。很多命令不止一个参数比如/review可以要求只审查api模块、忽略测试文件/test可以指定只给某几个函数生成测试。我的做法是利用$ARGUMENTS做自然语言解析模板里写上如果用户通过$ARGUMENTS注明了范围请优先遵循否则自行从diff判断。这样用户输入/review api 时AI会自动把api作为审查范围约束。这个设计比严格的$1/$2参数化要灵活得多因为自然语言能承载的信息量远大于位置参数。第二种做法是让命令支持无参数默认行为。很多用户输入/review就回车没带任何参数。模板里就应该写明如果$ARGUMENTS为空默认审查所有未提交的改动如果带了路径参数则只审查该路径下的改动。 这样命令既能快速用也能精确用覆盖面广得多。第二个是命令内部的子任务拆分。好的命令模板不应该是一段让AI自己发挥的散文而应该是一个带检查点的流程。比如/review的模板我写的是1. 运行 git diff --stat 确认改动范围 2. 读取改动对应的完整上下文文件 3. 按 正确性/安全性/性能/可维护性 四个维度逐一审查 4. 输出审查结果每个问题标注 严重/中等/建议 三级 5. 最后给出一个总体的改动健康度评分满分10分为什么要把流程写出来因为AI默认不会主动做确认修改范围和读取完整上下文这两件事你不写它就基于你对话里已有的信息直接输出经常漏掉关键上下文。流程化的模板实际上是强迫AI按人类审查的步骤来质量会稳定很多。曾有同事问我为什么他生成的review总是不准我让他打开模板一看就写了三行请审查代码改动并输出意见这种模板等于没有模板。4. Hook模板让质量门禁不再靠口头提醒4.1 PreToolUse拦住危险操作的守门员如果说CLAUDE.md是告诉AI规则那Hook就是在规则被违反之前拦截它。Hook是Claude Code里真正能在执行层面做安全控制的机制它在AI调用工具之前或之后触发让你能用脚本介入。我用得最多的是PreToolUse事件——也就是AI准备调用某个工具的时候先跑你的脚本确认安全。脚本返回一个JSON结构里面如果带hookSpecificOutput字段就可以把工具调用拦下来或者替换参数。我拿一个真实事故说明为什么必须要做这层拦截。某个凌晨我让AI做一个批量任务它不知怎么就脑抽开始执行git push --force直接把同事的分支覆盖了。虽然没有造成大事故但那次之后我再也不敢只靠对话里的不要乱push来保平安。现在的配置是{ hooks: [ { matcher: git push, hooks: [ { type: pre_tool_use, command: node ~/.claude/hooks/guard-git-push.js } ] } ] }脚本逻辑并不复杂检查push命令里是否包含force或者upstream参数如果包含就返回拒绝执行同时把即将执行的命令和触发它的对话上下文记录到日志文件方便事后排查。有了这层物理拦截AI再怎么糊涂也推不掉不该推的代码。4.2 Stop提交信息与变更摘要的强制生成PreToolUse是拦Stop事件则是补。Stop事件在AI准备结束一段响应之前触发非常适合强制它执行收尾动作。我做的第一个Stop Hook是提交信息补全。很多团队的规范是commit message必须包含issue编号和改动摘要但AI经常忘。所以我在Stop阶段加了一个检查如果当前对话中AI说自己完成了改动就让一个脚本检查git status与git diff如果发现存在未提交的改动且当前的响应里没有对应的commit message就输出一条提示检测到改动尚未产生提交信息请先执行/commit命令。这个机制看起来简单实际价值很大。它等于把质量门禁从人的记忆中搬到了工具链里AI想糊弄过去都不行。还有一次我直接让Stop hook自动生成一份改动摘要文本并写入CHANGELOG_pending.md方便发布时统一整理。效果是可以的不过要注意控制生成摘要的时机别每次对话都写一份不然文件会乱。我现在的配置是仅在git status有改动时才触发这样既不会漏核心改动也不会制造噪音。4.3 一套可供参考的最小Hook集合如果你刚开始接Hook不需要搞得很复杂。我推荐从一个最小集合开始先把安全底线兜住再逐渐加码事件匹配对象脚本职责建议策略PreToolUsegit push禁止force/upstream记录命令日志拦截高危参数PreToolUserm, mv, sed检查删除目标是否在项目目录内且非脚本生成目录拦截误删PreToolUseBash(通用)命令包含curl/wget时先下载白名单校验提示确认Stop任意结束检测未提交改动并提示生成commit信息温和提醒PostToolUseBash将执行过的命令追加到execution_history.log中审计留痕这套Hook集合我曾经在内部项目上跑了一个季度最大的感受是Hook管得住硬操作比如推代码、删文件、跑高危命令但管不住软问题比如代码逻辑本身写得烂、架构设计不合理。软问题还是得靠CLAUDE.md斜杠命令模板人工审查去约束。所以正确的姿态是CLAUDE.md负责规则斜杠命令负责流程Hook负责强制执行三者配合而不是互相替代。要知道预设Hook脚本的具体行为在不同版本之间可能存在差异但设计思路是通用的先记录日志再逐步加上拦截逻辑最后才考虑自动修正。这个渐进思路能帮你避免一上来就把AI的正常操作卡死。5. 模板仓库的设计、落地与演进5.1 一个可以直接拉下来改的目录结构前面几节讲的概念比较多现在把它们汇成一个具体的模板仓库结构。下面是我当前使用的 claude-code-templates 目录骨架claude-code-templates/ ├── CLAUDE.md # 模板总说明读起来像使用手册 ├── user/ # 用户级配置 → 复制到 ~/.claude/ │ ├── CLAUDE.md │ └── commands/ │ ├── commit.md │ ├── explain.md │ └── review.md ├── workspace/ # 工作区级配置 → 复制到工作区根目录 .claude/ │ ├── CLAUDE.md │ └── commands/ │ └── cross-repo-sync.md ├── project/ # 项目级模板 → 按需复制到每个仓库 │ ├── CLAUDE.md │ ├── commands/ │ │ ├── fix.md │ │ ├── refactor.md │ │ └── test.md │ └── hooks/ # 项目级Hook脚本 │ ├── guard-git-push.js │ └── check-license.js ├── hooks/ # 通用Hook脚本软链或复制到 ~/.claude/hooks/ │ ├── guard-git-push.js │ ├── guard-dangerous-rm.js │ ├── changelog-summary.js │ └── execution-audit.js └── settings.example.json # 各层settings.json的样例为什么要用这种分层目录因为它跟Claude Code的配置生效机制一一对应复制成本最低。你拉下来之后把user目录内容放到~/.claude/把project目录的内容放到具体的项目根目录就能立刻生效。这种目录结构也方便团队共享——把仓库放到公司内网Git拉下来之后每个人都能按同一套模板初始化自己的开发环境。5.2 命名规范、变量管理与版本管理的细节模板类资产最怕的就是漂移——不同项目的CLAUDE.md越改越不一样最后根本没法统一。所以我给模板定了三条规矩算是用踩坑换来的第一模板正文里不允许出现真实业务信息。所有具体的项目名、数据库连接、API路径一律用占位符表示比如{{PROJECT_NAME}}、{{DB_URL}}、{{API_BASE}}。初始化新项目时全局替换一遍占位符就行。这样模板仓库本身不会泄密也能被不同项目复用。第二模板必须标注适用场景和变更记录。CLAUDE.md文件头部放一个区块写明本模板适用Python后端服务最近变更2025-06 增加Hook安全拦截规则。这个习惯让模板演进时可追溯出了诡异问题也能快速定位是哪次改动引入的。第三模板仓库用语义化版本管理。新增一个命令文件、调整Hook逻辑、修改CLAUDE.md结构分别对应minor、patch、major的递增。团队内部用git tag区分版本每个项目记录当前使用的模板版本号。这样当模板更新时你能批量评估哪些项目需要同步升级。版本管理这块不能偷懒——没有版本号的模板仓库早晚会变成谁都不敢动的烂摊子。5.3 模板初始化的一条龙脚本思路光有静态文件还不够爽我的最终形态是用一个初始化脚本把整个流程自动化。脚本的逻辑很简单把用户级配置复制到~/.claude/在指定目录创建项目级CLAUDE.md、commands、hooks用交互式问答填充占位符最后运行一个自检命令验证AI能正确读取配置。伪代码大概是这样的#!/bin/bash # init-claude-templates.sh # 1. 备份现有配置 cp -r ~/.claude ~/.claude.backup.$(date %Y%m%d%H%M%S) # 2. 复制用户级模板 cp -r templates/user/* ~/.claude/ # 3. 交互式收集项目信息 echo 项目名称: read PROJECT_NAME echo 技术栈 (python/js/go): read STACK # 4. 渲染项目级模板 sed -i s/{{PROJECT_NAME}}/$PROJECT_NAME/ templates/project/CLAUDE.md sed -i s/{{STACK}}/$STACK/ templates/project/CLAUDE.md # 5. 复制到目标项目目录 cp -r templates/project $TARGET_PROJECT_DIR/.claude/ echo 完成。请进入项目后验证配置。这条脚本我第一次跑通时效果确实有种工业感——之前要折腾十几分钟的配置过程变成一条命令三秒搞定。而且因为模板统一了团队里每个人的行为基线一致跨人协作时上下文成本明显降低。当然脚本本身不复杂你也可以根据自己的业务场景扩展比如自动创建.gitignore、初始化README、生成docs/AI_CONTEXT.md等。5.4 模板演进中的几个坑最后聊聊我用这套模板过程中真正踩过、也真的建议你避开的几个坑。第一个坑是把模板当成宝典来写。模板写得越详细AI越容易被海量规则淹没导致关键规则被稀释。我的经验是每个层级的CLAUDE.md都控制在合理篇幅内宁可少写三条不重要的也要保证核心红线足够醒目。我在一个早期版本里写了四十条编码规范结果AI经常忽略最关键的那三条后来精简到十条反而准确率上来了。第二个坑是只建不用。很多人建好模板仓库就当成任务完成后面再也不维护。事实上模板是需要跟实际项目持续对账的——每次你发现AI做出了不理想的决策都应该复盘是模板没写这条规则还是写了但排序权重太低然后下意识地更新模板。我几乎每周都会因为某个翻车案例给模板仓库补一条规则或调整一段描述。第三个坑是Hook配置过于激进。拦截规则写得过死会导致AI的正常操作频繁被打断反而严重影响工作效率。我的建议是Hook先做日志记录跑两周看看误伤率再逐步收紧到真正需要拦截的边界。比如最初我把所有npm install都拦下来确认结果每次跑测试都要弹确认烦得很后来改成只拦截非package.json声明的全局安装误伤率瞬间降下来。第四个坑是混淆了记忆文件与上下文的关系。CLAUDE.md是给AI读的规则不是文档中心。很多团队把CLAUDE.md写成几千行的百科全书其实是对AI为什么表现不好这个问题的错误归因。表现不好首先要排查上下文是不是干净上下文干净了再考虑规则够不够顺序不能反。一些实站体会写到这里基本上把我从每次对话都要重新教学到一套模板跑遍所有项目的全过程都梳理了一遍。现在我个人开新项目的流程已经固定成三步拉取claude-code-templates跑一遍初始化脚本进去问一句根据你的记忆文件我该从哪开始。剩下的对话质量基本就是这套模板质量的直接反馈互动多了之后你会发现模板维护得好AI是真的能替你省掉大量重复性工作。如果你准备动手搭自己的模板我建议别追求一步到位。先建一个最小集合一层CLAUDE.md加两个斜杠命令加一个PreToolUse安全Hook跑两个星期。在这期间把AI每次表现不好的时候是哪里没管住记下来然后迭代进模板。模板这种东西最忌讳的就是闭门造车它是靠真实项目的摩擦喂出来的。我的这套结构能给你当起点但最终的形态一定是你自己踩过坑之后改出来的那版。相信我当你在新项目里第一次说出帮我按咱们的规范初始化一下然后事情真的按预期推进时你会觉得前面那些整理配置的时间都值了。