很多人在用Claude Code的时候都有一种感觉刚上手觉得惊为天人好像什么都能干用了一两周以后又觉得差点意思好像每次对话都在讲故事同一个坑反复踩同一个风格反复强调。我最初也有这个困扰。后来我把项目中所有跟Claude Code打交道的约定、技能、审核清单、命令模板全部抽出来做了一套claude-code-templates仓库才真正把这套工具从“聊天”变成“团队里的固定工程师”。这篇文章就分享这套模板体系从设计到落地的完整过程包括目录结构、CLAUDE.md的写法、自定义命令、hooks自动化、以及我踩过的坑。适合所有在用Claude Code或者准备引入命令行AI助手的开发者和技术团队参考。1. claude-code-templates到底在解决什么问题1.1 默认状态下的Claude Code用起来是什么感受先说个现实Claude Code默认是“有记忆但不多”的。单次会话里它能记住上下文表现很不错但每次新开会话它就忘了你项目里的代码风格、命名习惯、哪些文件不能动、测试要跑到什么程度。于是你会反复遇到这些场景。你在A项目里刚详细说明过“线上配置用environment变量注入不允许写死在代码里”到了B项目它照样给你硬编码。你要求它“每次改完代码必须跑测试”它用完pip install就停了。你想让它“只改指定模块别动其他文件”它一顺手把格式化工具跑完整个仓库多了几十个无关文件。这不是Claude Code变笨了而是它缺少一套稳定的“项目约定上下文”。你口头说一次它记住一次你换会话、换机器、换项目一切归零。我最早解决这个问题的方法是每次对话开头贴一大段说明烦且容易漏。后来我意识到所有这类说明都应该做成模板文件放进项目里让Claude Code启动时自动加载。1.2 模板体系的核心价值把个人经验沉淀成固定套路我做的这套模板体系核心思想就一句话把“你希望AI如何工作”从聊天的临时约定变成仓库里的持久配置。它由四类东西组成。第一类是CLAUDE.md也就是项目的“长期记忆文件”告诉Claude Code这个项目的技术栈、目录结构、代码规范、命令用法。第二类是自定义命令模板把高频操作固化成斜杠命令比如/code-review、/commit、/test像给AI装上了快捷指令。第三类是hooks脚本在Claude Code执行某种工具动作前自动触发比如不允许编辑某个文件、不允许执行某类命令。第四类是settings配置控制模型行为、权限、日志等等。把这四类整合进一个git仓库好处非常明显。团队共用一套配置新成员拉下来就能获得和自己完全一致的AI工作流不同项目只需fork或引用同一套模板基线再针对项目特性增量覆盖配置的变更全部可追溯谁改了什么、为什么改一清二楚而不是靠某个人口头同步。1.3 这套模板适合谁如果你属于下面任何一种情况这套东西对你会有实际价值。每天高频使用Claude Code但总感觉它在重复踩坑的独立开发者希望让AI按团队规范工作、减少人工review返工的小团队负责维护多个项目、想让不同项目快速获得一致AI行为的技术负责人。就算你只用Claude Code写写脚本、做点原型验证也可以借用CLAUDE.md来减少每次开新对话的“背景说明”成本只是收益不会像重度用户那么明显。2. 模板仓库的整体架构设计2.1 目录结构如何组织一套好的模板仓库第一步是目录结构要清晰。我的仓库大概长这样。claude-code-templates/ ├── README.md ├── base/ │ ├── CLAUDE.md │ └── .claude/ │ ├── settings.json │ ├── commands/ │ │ ├── code-review.md │ │ ├── commit.md │ │ ├── test.md │ │ ├── explain.md │ │ └── ... │ └── hooks/ │ ├── pre-tool-use.md │ └── post-tool-use.md ├── stacks/ │ ├── python/ │ │ └── CLAUDE.md.python │ ├── javascript/ │ │ └── CLAUDE.md.javascript │ └── golang/ │ └── CLAUDE.md.golang └── projects/ ├── demo-service/ │ ├── CLAUDE.md │ └── .claude/ └── tools/ └── ...base目录是通用基线不涉及具体技术栈只包含通用的行为约束比如“禁止修改锁定文件”“每次改动必须通过测试”“回答代码问题必须附带文件路径”。stacks目录是技术栈相关的配置片段不同项目按需“配菜”。projects目录是给特定项目定制的覆盖配置优先级最高。这样分级的好处是通用规则维护一份技术栈规则按语言维护一份项目特殊规则单独一份不会互相污染也不会出现项目A的规则跑到项目B里去。优先级上项目内的配置会覆盖全局配置这是Claude Code的加载机制决定的后面会详细说。2.2 模板的命名规范和分类逻辑命名规范这东西乍一看啰嗦真正维护起来才知道多重要。我的模板命名遵循一个简单的规则模板文件名为动词对象比如code-review、write-test、init-project。“code-review.md”一眼就知道是干什么的“test-plan.md”是测试计划。不建议用“template.md”“utils.md”这种谁看都猜不出内容的文件名。分类逻辑上我把所有模板分成三类动作类、知识类、审计类。动作类直接触发Claude Code干活比如/commit、/refactor。知识类不直接干活而是注入背景知识与约定比如“项目结构说明”“部署流程”可以挂在CLAUDE.md里。审计类专门做代码审查、安全检查、依赖检查一般输出一份结构化报告。这个分类直接影响模板内容的写法。动作类模板必须写清楚“目标是什么、步骤是什么、完成标准是什么”。知识类模板写作重点是准确、简洁、不要废话。审计类模板看的是“检查哪些方面、输出什么格式、哪些是严重项”。把分类搞清楚以后写模板就变成填空题了。2.3 版本管理与同步策略模板仓库本身必须用git管理这是底线。每个模板文件的变更都要有commit记录。我建议仓库里维护一个CHANGELOG.md简单记录每个版本的变更点。这样当某个项目里的行为突然变了你能快速定位是模板仓库的哪次commit引起的而不是两眼一抹黑。同步策略上我踩过几次坑后总结出一个相对稳妥的方式。主模板仓库作为上游各项目通过git submodule或者直接把模板拷贝进项目里来使用。小团队建议用submodule模板更新后项目里git submodule update一下就行。如果项目已经很大、不想引入submodule也可以用一个简单的同步脚本把仓库里的base目录同步到目标项目的.claude目录里。千万不要手动逐步拷贝漏文件、漏更新是大概率事件。另外模板仓库最好建在独立的git仓库里不要放在某个业务项目的目录下。这样才能做到多项目复用不会因为某个项目解散导致模板也跟着丢掉。把这些结构定好之后接下来就是具体写每一块模板内容了这也是整个方案最花时间的部分。3. 核心模板拆解CLAUDE.md的写法3.1 CLAUDE.md在项目里的加载机制CLAUDE.md是Claude Code读取项目约定的核心文件。启动对话时它会自动加载当前工作目录下的CLAUDE.md以及~/.claude/CLAUDE.md这个全局文件。加载顺序大致是全局配置先加载然后是项目里.claude目录下的配置再是项目根的CLAUDE.md最后是会话中用户临时提供的说明。越靠后的优先级越高相同主题以后者为准。这意味着你可以把通用规则放在全局的CLAUDE.md里把技术栈规则放在stacks片段里把项目特有规则放在项目CLAUDE.md里让Claude Code在每次对话开始时自动“读完”这些内容。它不需要你重复说一遍“我们是Python项目测试用pytest不要改接口签名”这些已经在它脑子里了。这个机制也是一把双刃剑。CLAUDE.md写得好AI的表现会有质的提升写得烂比如塞了一堆互相矛盾的规则AI反而会变纠结甚至频繁在对话里问你要听哪一条。所以CLAUDE.md不是越长越好而是要精炼、无歧义、有优先级。3.2 项目级CLAUDE.md怎么写才有用我见过太多人把CLAUDE.md当成一个大杂烩什么信息都往里塞结果模型被大量低价值信息挤占注意力。我自己写项目级CLAUDE.md时严格遵循一个模板结构。第一段写项目是什么几句话讲清楚技术栈、架构、目录结构。第二段写代码风格约束包括命名习惯、模块职责边界、注释风格、禁止事项。第三段写常用命令比如怎么跑测试、怎么构建、怎么本地起服务以及这些命令在什么目录下执行。第四段写“禁区”比如哪些文件不能改、哪些目录是自动生成的、哪些环境变量不允许暴露在代码里。第五段写项目当前的技术债或者特殊约定比如某个模块有历史遗留问题改动时要小心。举一个实际的CLAUDE.md片段是我在某个Python服务里用的# 项目约定 ## 项目概览 - 技术栈: Python 3.11 FastAPI PostgreSQL - 架构: 分层架构, controller - service - repository - 目录说明: app/api 放路由, app/services 放业务逻辑, app/repositories 放数据库访问 ## 代码风格 - 类型注解必须写, 返回值类型也要写 - service 层不允许直接操作数据库, 必须通过 repository - 日志使用 structlog, 不允许在业务代码里使用 print ## 常用命令 - 测试: pytest tests/ -q - 本地启动: uvicorn app.main:app --reload - 依赖更新: poetry update ## 禁止事项 - 不要修改 alembic/versions 下已生成的迁移文件 - 不要编辑 .env, 本地配置统一放在 .env.local这段内容看起来平淡但实际效果非常好。Claude Code处理代码时看到“service层不允许直接操作数据库”就直接避开了最常见的架构违规看到“不要修改已生成的迁移文件”就不会手贱去改数据库迁移历史。这比我每次对话前口头叮嘱高效太多了。3.3 全局配置目录.claude里的内容项目根目录下创建.claude目录里面可以放一些比CLAUDE.md更结构化的配置。我会在这个目录里做三件事。第一放settings.json统一配置模型参数和权限。比如{ model: claude-sonnet-4-5, permissions: { defaultMode: acceptEdits, allow: [ Read, Edit, Write ], deny: [ Bash(npm install -g *), Bash(pip install -g *) ] } }第二放commands目录里所有自定义命令的模板。第三放hooks目录里的hook脚本。这个.claude目录在Git里提交、在团队内共享每个人在项目里看到的行为就是一致的。有一点要提醒settings.json的deny规则很强大但也容易误伤。比如你deny了所有Bash命令Claude Code就完全没法跑测试了。第一次配置时建议先只deny高风险命令等跑了一段时间摸清哪些操作需要禁止再逐步收紧。这个迭代过程最好记在CHANGELOG里不然团队里某个人突然发现“AI怎么不能装包了”就是因为你上周加的deny规则。4. 自定义命令模板把高频操作做成斜杠指令4.1 自定义命令的格式Claude Code支持通过.claude/commands目录下放置Markdown文件来创建自定义命令。文件名就是命令名比如commit.md对应的就是/commit。文件内容以YAML frontmatter开头定义命令元信息正文里写指令逻辑。一个最小可用的模板长这样--- description: 生成符合规范的commit信息 argument_hint: 可选, 补充本次改动的意图 allowed-tools: Git, Read --- 你是一个擅长写commit信息的工程师。根据当前git diff的内容生成一个简洁清晰的commit message。 要求 - 使用 conventional commit 格式, 如 feat:, fix:, refactor: - 第一行不超过50个字符 - 如果用户提供了argument, 把它作为 commit 主要意图 - 输出建议的完整命令, 不要直接执行这里说一下frontmatter里的关键字段。description是命令菜单里显示的说明文字必须简短让人一看就知道这条命令干什么。argument_hint用来提示用户输入参数比如“可选补充本次改动的意图”这样对话时Claude Code会提示用户提供补充信息。allowed-tools则限定了这条命令允许调用的工具写code-review的模板时就不要放开Bash避免AI真的去改代码。4.2 几个高频模板的实战示例/write-test 是我项目里使用频率最高的自定义命令。它的作用不是简单地说“写测试”而是把测试规范一次性说清楚--- description: 根据当前函数生成单元测试 argument_hint: 指定要测试的函数或文件 --- 根据当前的代码和用户指定的文件生成对应的单元测试。 要求 - 使用 pytest 风格, 不要使用 unittest 类 - 测试文件放在 tests/test_module.py - 每一个测试用例都要有明确的测试意图, 禁止写无用断言 - mock 外部依赖, 不要发起真实网络请求 - 只生成测试代码, 不要修改被测文件 - 生成完测试后, 运行 pytest tests/ 确认所有用例通过这个模板解决了一个我长期头疼的问题Claude Code默认写测试时特别喜欢顺带“优化”被测试的源码。只要不约束清楚它写测试的同时可能把函数签名都改了。加了“只生成测试代码不要修改被测文件”后行为立刻老实了。/code-review 则是给代码审查场景准备的--- description: 对指定代码或改动做代码审查 argument_hint: 指定要审查的文件路径或git diff范围 --- 你是资深工程师, 请对指定范围进行代码审查。 输出结构: 1. 总体评价: 一段话概括本次改动质量 2. 严重问题: 列出会导致bug、安全漏洞或数据丢失的问题 3. 规范问题: 列出违反项目规范或最佳实践的问题 4. 改进建议: 按优先级列出可执行的改进方案 约束: - 只审查, 不修改任何文件 - 引用代码时附带文件路径和行号 - 严重问题必须说明为什么严重, 不要含糊 - 不要给出“代码可以更优雅”这类空泛建议这个模板最关键的字是“不修改任何文件”。如果不加这句AI审查到一半可能就顺手给你“修复”了一个格式问题。审查和修复是两个动作拆开做效率最高。/commit 是一个我每天都在用的命令它和普通的“帮我写commit”区别在于它严格绑定了git操作流程。这个模板我会让它检查git status读diff生成message但默认不直接commit而是把命令输出给你确认。加不加“直接执行”这一步完全看个人习惯我倾向于AI负责产出人来确认毕竟commit message是给团队看的东西主动权要留给自己。4.3 参数变量和上下文注入自定义命令不只是静态指令它还能读取用户输入和会话上下文。在命令模板里$ARGUMENTS代表用户在斜杠命令后面输入的原始文本$1、$2可以取到按空格分割的参数。举例来说/test foo.py这个输入$ARGUMENTS就是foo.py$1也是foo.py。如果用户输入/explain server.py auth那$1是server.py$2是auth。我的模板习惯是能用$ARGUMENTS的地方就不去拆$1/$2因为大多数场景只需要一段自由文本作为补充。例如“/commit”“/write-test”传一个文件名就够。只有像/review xxx分支名这样参数相对固定的命令才去拆$1和$2。另外还要提醒一点自定义命令模板里写的“你是一个擅长XX的工程师”这类角色设定不是废话。Claude Code在斜杠命令场景下会自动把这个角色设定和应用到当前对话中对输出质量有明显影响。角色设定越具体输出越聚焦。与其写“你是代码审查专家”不如写“你是有12年后端经验的资深工程师尤其擅长Python和分布式系统”。5. hooks与自动化让模板自动生效5.1 hooks文件与事件类型如果说CLAUDE.md是让Claude Code“知道规则”那hooks就是让规则变成硬性约束。hooks是一组在特定事件发生时自动执行的脚本或指令可以在Claude Code执行某个动作前或动作后触发。常见的事件类型包括PreToolUse、PostToolUse、Notification、UserPromptSubmit等。PreToolUse是在Claude Code调用某个工具比如Edit、Write、Bash前触发适合做禁令检查。PostToolUse在动作完成后触发适合做验证检查。UserPromptSubmit在用户发消息后触发适合做内容过滤或上下文注入。我的实际体验里PreToolUse用到的频率远高于其他几个因为大多数约束在事情发生前拦截最有效。hooks文件同样是Markdown放在.claude/hooks目录下。以PreToolUse为例一个简单的示例--- event: PreToolUse tool: Edit, Write --- 如果用户要求编辑或写入的文件匹配以下任一模式, 立即终止操作并说明原因: - .env* - *.pem - alembic/versions/*_generated_*.py - dist/ - build/这个hook的意思很直白有任何工具试图去写这些敏感文件直接拦下来。比起在CLAUDE.md里写“不要改.env”这个方案是物理级别的防护AI就算“忘了”规则也触发不了操作。5.2 hooks的典型场景与配置方法hook最常见的使用场景就是做文件保护。前面说的.env、密钥文件、自动生成文件都属于这类。文字约束最大的问题是依赖AI的理解和记忆hooks则完全不依赖这些它就是一个“规则引擎”命中即拦截。第二个场景是做命令准入控制。在PreToolUse里针对Bash事件做检查--- event: PreToolUse tool: Bash --- 检查命令内容, 如果匹配以下模式, 直接拒绝执行: - rm -rf - git push --force - npm publish - pip install 无虚拟环境第三个场景是自动附加审查要求。在UserPromptSubmit事件里检测到用户消息中包含“review”或“审查”关键词时自动追加一段指令“请按/code-review的模板执行审查并在输出时提供文件行号。”这一步能把某些你已经固化在模板里的规则自动套用到普通对话中。配置hooks时最容易犯的错是规则写得太多太细导致Claude Code的正常操作频繁被拦截。我建议第一版只写最关键的几条禁令比如“永远不要动.env”“永远不要rm -rf”然后用一个星期观察实际拦截情况再逐步梳理哪些动作需要额外限制。先松后紧别一上来就把自己绊倒。这里还要提一个工作流上的小技巧hook拦截信息一定要写得足够详细表明是哪条规则、哪个文件、为什么被拦。不然Claude Code被拦后可能会尝试“绕过规则”换个方式操作反而把事情搞复杂。我在hooks里都加上一句“如果确实需要修改此文件请先向用户说明原因并获得明确授权”给AI留一条合规的沟通路径。6. 常见问题与排查技巧实录6.1 自定义命令总是输不对路径我最初把.claude目录放在项目根目录下命令模板放在.claude/commands里理论上没问题但实际操作中Claude Code在解析路径时可能会基于当前working directory来找命令文件。如果你用了一个子目录作为工作区比如在apps/web下启动的会话直接/commit可能加载不到全局配置。我的经验是把通用命令放在全局~/.claude/commands下项目专属命令放在项目根目录的.claude/commands下。这样无论从哪个子目录启动会话通用命令都能被找到项目独有的命令因为项目根目录的配置会被自动扫描到从项目内任意子目录进入也都能正常工作。6.2 CLAUDE.md内容互相矛盾这个问题在配置丰富以后非常常见。全局CLAUDE.md说“所有日志用loguru”项目CLAUDE.md说“本项目用structlog”结果AI今天听前者、明天听后者行为随机。排查方法是直接在对话里问Claude Code“你认为本项目日志库是什么依据是什么”它能告诉你读取了哪份配置。如果发现两个配置打架赶紧统一。我给自己的规则是全局只放“通用无害”的约定比如“不修改锁定文件”“测试前先更新快照”。涉及具体技术栈和项目规范的内容一律放到项目CLAUDE.md里。全局文件越薄越好否则一定会跟某个项目冲突。6.3 模板更新后不生效Claude Code对配置的加载不是每次都重新读盘的某些情况下会使用缓存。更新了CLAUDE.md或新增了一个命令模板但对话里怎么都不生效十有八九是开了很久的旧会话。新建一个会话测试基本就能确定是不是缓存问题。另外如果你用submodule同步模板仓库别忘了项目里需要执行git submodule update。我曾在模板仓库改了hooks规则开新会话发现没变化排查半天发现是submodule的指针根本没更新。这种低级错误很费时间建议在README里写清楚同步流程。6.4 模板仓库本身如何做测试模板仓库影响的是AI行为很容易“改了没感觉”。我建议在仓库里维护一组测试用例用固定的示例项目运行模板检查输出是否符合预期。比如写一个test-fixture目录里面放一个模拟的Python服务和一组Git历史跑/code-review看输出格式、跑/write-test看生成的测试是否遵守约束。这个过程不一定要全自动手动跑一轮也就几分钟但能有效防止模板改动引入的回归。我目前维护的模板仓库除了配置还有一个smoke-test脚本每次修改模板后跑一遍基本检查。成本很低收益非常明显尤其当模板开始被多个项目复用后回归测试几乎是必须的。最后再分享一个我个人的小习惯。我所有模板文件的结尾都会加一行“如果上述规则与用户明确指示冲突以用户明确指示为准”。这不是怂而是给模板体系留一个逃生通道。AI工具有时候需要的是规则感而不是绝对约束。留了这条后真遇到边界case时我可以手动干预而不会被自己设的规则锁死。这套模板体系我维护了大半年越用越离不开它本质上就是把“你会用AI”固化成了“AI会听你的”这两件事的差距就是这套模板的价值。