很多第一次接触Claude Code的人最先搜的都是怎么安装怎么启动。但真用上一两周你会意识到另一个更现实的问题每天敲进终端里的指令翻来覆去就是那几句。我大概连续三周都在干同一件事——让Claude Code按项目习惯检查代码、写提交信息、处理异步调用。指令重复输入了无数遍每次的措辞还不一样AI的发挥也忽好忽坏。于是就有了我自己的claude-code-templates。这个名字看起来像某个开源仓库其实就是我自建的一套模板库把提示词、项目规范、技能配置、钩子脚本全部沉淀成文件放进Git仓库统一管理。它解决的不只是不用重复打字这个表层问题更重要的是把AI的输出质量拉到可复现、可检查、可迭代的水平。这篇分享面向两类人一类是长期使用Claude Code、希望摆脱重复劳动的个人开发者另一类是想在团队里统一AI辅助开发节奏的技术负责人。我会把从零搭建这套模板库的思路、目录设计、Prompt写法、Skill与Hook的挂载方式以及踩过的坑完整讲一遍。1. 为什么我要把一次性对话改成模板化资产1.1 重复输入同样的指令浪费的不只是手速大模型对话的上下文窗口是固定资源。每次让AI干活之前你都要先把背景、要求、约束复述一遍这些文字本身就会占用上下文长度。重复次数越多上下文里真正留给干活的空间就越小模型也容易被你前后表述不一致的废话干扰。我遇到过一个很典型的例子。项目里约定所有HTTP请求都用httpx不走requests。这个约定只在前几次对话中提到过后来某个新会话里我忘了说Claude Code就很自然地给我生成了一段requests代码。按项目规则重写可以但又是新一轮沟通成本。如果这个约定一开始就在模板里AI根本不会在用什么库这件事上犯错。把重复指令模板化本质上是在给AI建立开机默认值。每次会话不是从白纸开始而是从你积累下来的行为规范开始。省下来的时间反而是次要的关键是输出稳定。1.2 模板化解决的三个问题稳定、可审计、可迁移首先是稳定。同一类任务AI每次按同一套标准执行。代码审查永远按同一套检查清单走提交信息永远按同一个commit规范生成。不会因为某天我多写了句更严格一点输出方式就整体漂移。其次是可审计。规则从脑子里搬进文件里之后团队任何人都能查看、讨论、提修改意见。以前我说了算的隐性规则变成了写在CLAUDE.md里的显性约定。哪条规则不好用直接改文件效果立竿见影。最后是可迁移。换电脑、换项目、新同事入职一行install.sh就能把整套行为规范装进目标环境。不用重新口头交代几十条注意事项。我自己的体会是模板库用久了它比我的终端配置还重要——终端配置决定的是界面长什么样模板库决定的是AI替我做事的水平线。1.3 哪些内容值得模板化哪些不值得我的判断标准很简单过去两周里重复出现过三次以上的任务才值得写进模板。值得模板化的有三类任务型代码审查、Bug排查、提交信息生成、知识型技术栈约定、目录结构、命名规范、流程型发布前检查、合并前检查。这三类都有一个共同特点——执行路径相对固定翻车点也相对固定。不值得的是一堆乱七八糟的临时需求。今天写一个API的POST方法这种任务每次上下文都不一样硬做模板只会得到一个空壳子。还有更新频率太快的事项也不适合比如某个正在快速演进的内部SDK用法你今天写进去下周可能就过期了。我早期犯过这个错模板库里有好几个这样的僵尸模板后来全清了。2. 动手前先把Claude Code的扩展入口摸清楚2.1 CLAUDE.md项目级共识的加载入口CLAUDE.md是Claude Code启动时自动读取的说明文件。放的位置不同生效范围也不同放在项目根目录就是项目级规则放在用户全局配置目录就是所有项目通用规则。它的作用不是教你用工具而是告诉模型在我们这个环境里事情是怎么做的。我把它类比成给新人的入职文档。不需要科普什么是Python只需要写明测试用pytest还是unittest日志走哪个logger文件应该放在哪个目录发布前必须跑哪几条命令。这些规则写进去之后日常对话里就完全不用复述了。2.2 .claude目录配置、技能、钩子的总装车间除了CLAUDE.mdClaude Code还会读取项目里的.claude目录。settings.json里放配置skills目录里放技能定义hooks脚本用来挂事件。很多新手不知道这一点于是所有规则都堆在对话里或者散落在一堆无结构的txt文件里。模板库真正要做的事情就是把散落在各处的说明文件、技能定义、脚本统一收纳到一个仓库里再通过安装脚本分发到目标项目。如果连.claude目录都还没建过说明你还停留在用对话完成任务的阶段还没进入管理AI行为的阶段。2.3 Skills与Hooks静态文档变成可执行行为Skill是带元信息的指令文件。我在一个SKILL.md文件头部写清楚name和description当对话涉及description描述的场景时Claude Code就会主动参考这个技能。这比每次手动粘贴模板规范要自然得多。Hook是事件触发的脚本。在某个时机满足时比如AI调用工具前、回复停止后自动执行指定shell命令。它能让模板库里的部分行为完全自动化AI写完成代码终端里直接跑一遍lint和类型检查准备提交时自动根据git diff生成commit message草稿。这就是模板库与普通提示词收藏夹的分水岭。收藏夹只是把文本存起来模板库则可以让一部分行为自动生效。2.4 换模型时模板不受影响现在有不少人会把Claude Code接到其他模型服务上比如在DeepSeek的不同模型之间切换。工具上有ccswitch之类的方式也可以用环境变量指向不同的API服务端。我自己的经验是CLAUDE.md、SKILL.md、hooks这套机制是相对通用的切换底层模型不会让模板失效。真正需要微调的是某些模型对长指令的遵循程度会有差异。遇到这种情况优先调整模板措辞比如把可以改成必须而不是推翻整个模板库。3. 模板库的目录结构按可复用来设计3.1 我用的一套目录结构这是我的claude-code-templates仓库目录claude-code-templates/ ├── README.md # 库的说明和使用方式 ├── install.sh # 一键安装到目标项目 ├── common/ │ ├── CLAUDE.md # 所有项目通用的规则 │ ├── review-code.md # 通用代码审查模板 │ ├── commit-msg.md # 提交信息生成模板 │ └── debug-issue.md # Bug 排查模板 ├── stacks/ │ ├── python-fastapi/ │ │ ├── CLAUDE.md # Python 项目的技术栈规则 │ │ └── review-code.md # 技术栈专属审查模板 │ └── typescript-react/ │ └── CLAUDE.md ├── skills/ │ ├── review-code/ │ │ └── SKILL.md # 可自动触发的 Skill │ └── rewrite-code/ │ └── SKILL.md └── hooks/ ├── after-stop.sh # 停止生成后跑检查 └── before-bash.sh # 执行 bash 前的安全检查common放所有项目通用的东西stacks按技术栈打包配套规则skills放带元数据的技能定义hooks放脚本。这样分层的核心原因是规则的通用度不一样。一个完全通用的Prompt如果混进FastAPI的路由细节在React项目里就是纯粹的噪音反过来技术栈规则如果单独拆出来就能在对应项目里发挥更大作用又不会污染其他环境。3.2 命名规范没有它模板库三个月就废了模板文件名用动词对象的格式。review-code.md、write-commit.md、debug-issue.md一眼就知道干什么用。绝对不要出现tmp.md、final_v2.md这种东西。版本管理靠文件头部的frontmatter不靠文件名。我在每个模板文件开头都留了两段固定格式的说明这个模板干什么应该在什么场景用。六个月后回来翻模板能快速判断它是否过期。不要让模板变成只有自己才看得懂的碎片笔记。3.3 用软链接而不是复制一开始我也用复制。把模板文件复制到各个项目里方便是方便但模板更新之后项目里的副本全是旧版。找了一整天才发现有一个项目还在用老版本的审查模板。后来我改成了软链接。install.sh里做这样的事ln -sfn ~/claude-code-templates/common/CLAUDE.md /path/to/project/CLAUDE.md mkdir -p /path/to/project/.claude/skills ln -sfn ~/claude-code-templates/skills/review-code /path/to/project/.claude/skills/review-code源文件就是仓库本身改一处所有项目同步生效。缺点也明显Windows下创建软链接可能需要开发者模式或管理员权限跨平台的时候要提前跟团队说清楚。如果项目要求锁定某次模板快照那就用复制并且在install.sh里把版本参数固定下来。3.4 我踩过的坑把CLAUDE.md写成万字长篇第一次设计模板库我恨不得把能想到的规则全写进一个CLAUDE.md。结果是AI面对十几条规则时权重被严重稀释。真正重要的四五条核心规则反而被淹没在日志要打什么级别注释要怎么写这类次要细节里。输出质量不升反降。后来我把规则按重要程度拆分。全局规则只保留最通用的技术栈规则放stacks目录真正需要时才加载的任务指令放到skills里。CLAUDE.md的定位变成了底线规则不是百科全书。4. 模板的核心高质量Prompt的写法4.1 任务型模板的五段式骨架任何一个任务型模板都可以按角色、目标、输入、步骤、输出五段来组织。角色给AI一个明确的立场。它在本任务里是资深代码审查者、前端性能顾问还是刚入职但熟悉你项目的新人工程师。目标一句话说清楚完成的定义。比如找出可能引发线上事故、数据错误或维护困难的问题并给出修复建议。输入列出这个模板需要外部提供的动态信息用占位符表示。步骤按顺序写执行流程每一步都尽量可验证。输出规定格式和最低信息量。五段里最重要的是输出约束。AI很擅长生成看起来没问题的废话但如果你在模板里明确要求每条问题必须给出文件名、行号、问题描述、修复建议它就没法糊弄了。一个糟糕的模板长这样请帮我检查代码。什么都没约束AI自然按它想象的重度自由发挥。一个合格的代码审查模板至少应该长这样# 代码审查任务 你在本项目中担任资深代码审查者熟悉项目的架构和既有技术栈。 ## 目标 找出本次变更中可能导致线上事故、数据错误或后续维护困难的问题并给出修复建议。 ## 输入 - 变更文件{{changed_files}} - 相关Issue{{issue_link}} ## 步骤 1. 先阅读变更文件定位改动边界。 2. 检查安全与异常处理参数校验、错误捕获、并发竞争。 3. 检查是否遵循项目约定文件位置、命名、依赖使用。 4. 运行必要的静态检查命令如 tsc --noEmit、pytest记录输出异常。 5. 汇总问题按严重程度排序。 ## 输出 - 按“严重问题 / 建议改进 / 风格问题”三档输出问题清单。 - 每条问题必须给出文件名、行号、问题描述、修复建议。 - 如果没有问题明确写“未发现需要阻塞合并的问题”不要用模糊评价。这一版跑出来的效果跟请帮我检查代码完全是两个维度。4.2 知识型模板写决策而不是写百科技术栈相关的CLAUDE.md最怕写成教程。AI不需要你教它FastAPI是什么它需要知道的是你的项目里哪些库允许、哪些禁止、默认怎么写路由。比如# Python FastAPI 项目规则 - 使用 httpx 进行所有 HTTP 调用禁止使用 requests。 - 路由统一放在 app/routers 下按业务模块拆分。 - DB 操作使用 SQLAlchemy 2.0 风格repository 层统一封装。 - 错误处理使用 app/errors.py 里的自定义异常不要随意返回裸 dict。这种决策型规则的价值远高于科普型规则。它直接定义了AI在这个环境里的行为边界。4.3 变量化模板能复用的关键模板里不要写死实际的类名、路径或服务名除非它在所有目标项目里都一样。需要变化的位置用{{变量名}}标出来。这个习惯一开始就要养成不然三个月后你会发现自己写了十几个内容几乎相同、区别只是项目名不同的模板。措辞上也要注意。模板里的可以考虑尽量这类建议性语言对模型的约束力很弱。我实测下来把模板里的建议性语言全部改成命令式必须不允许如果……则……输出质量提升非常明显。AI对清晰的指令服从度天然更高模糊的指令只会放大它的随机性。5. 从静态模板到自动执行Skill与Hook的实战5.1 Skill文件怎么写在.claude/skills/skill-name/SKILL.md里文件开头用frontmatter写元信息正文写具体的执行说明。这是我的一个skill示例--- name: review-code description: 当用户要求进行代码审查、检查代码质量、准备提交合并请求、或查看Pull Request时使用。不要主动用于一般的代码生成任务。 --- 在开始评审前先阅读项目根目录的 CLAUDE.md 获取项目规则。 1. 定位本次所有变更文件。 2. 使用项目配置的工具执行类型检查与测试如 package.json 中的 scripts.test、lint。 3. 按下面模板输出审查结果 - 严重问题 - 建议改进 - 风格问题这里最关键的字段是description。描述写太窄该触发的时候它不出来描述写太宽AI什么任务都想套它。我第一次把review-code的description写成检查代码质量结果Claude Code连生成新功能时都先来一轮审查输出里全是注意命名规范这种没意义的话。后来改成仅在用户明确要求审查代码、检查PR或准备提交合并时使用触发频率恢复正常。5.2 Hook让模板绑定的脚本自动跑起来Hooks配置在.claude/settings.json里作用是在某个动作发生前后自动执行命令。我常用的是在AI每次回复结束Stop后自动跑一遍类型检查和lint。配置大概是这样的{ hooks: { Stop: [ { matcher: , command: bash ~/.claude/hooks/after-stop.sh } ] } }不同版本的Claude Code对hooks字段写法会有一点变化第一次配置时建议对照官方文档确认参数名。我的踩坑经历是先找个最简单的echo脚本确认事件能触发再逐步加逻辑不要一上来就搞一个复杂脚本出了问题很难排查。5.3 两个值得挂到Hook上的场景第一个是停止生成后自动执行pnpm lint pnpm tsc --noEmit。AI改完代码错误直接留在终端里。相当于每次代码生成后面都跟了一道自动闸门错误能立刻暴露。第二个是提交信息辅助。准备提交流水线之前根据git diff生成一份符合项目规范的commit message草稿再由人来确认编辑。这个场景非常适合Hook因为它的触发时机非常固定而且生成质量通常很稳定。5.4 手动安装其他仓库的Skill有时候在GitHub上看到别人写的Skill想直接拿来用不需要复杂操作。把整个Skill目录下载下来放到本项目的.claude/skills/下或者放到用户级的skills目录。目录名和SKILL.md里的name保持一致。装完重启Claude Code会话再描述对应的场景看它是否识别出这个技能。我的习惯是社区里好的Skill拿回来先按自己的项目习惯改写法再沉淀进模板库。这也让模板库持续有了新的输入来源。6. 实战复盘一个代码审查模板的完整调校过程6.1 第一版我把模板写成了立场声明第一版特别短你是一名资深工程师请认真审查代码找出潜在问题并输出优化建议。结果是AI确实把所有文件都扫了一遍但输出内容全是正确的废话建议增加异常处理建议提取公共逻辑注意命名不一致。没有一条可执行没有行号连具体文件都说得含含糊糊。我不得不重新再读一遍全部代码模板等于摆设。问题出在三个地方没告诉AI什么叫问题没指定审查顺序没约束输出格式。它们共同导致AI只能用通用经验敷衍。6.2 第二版加入检查单和输出格式第二版我加入了5.1里那个完整版本。明确检查维度安全与异常处理、并发竞争、项目约定、静态检查。同时强制输出文件名行号修复建议。关键动作是把检查是否遵循项目约定写进执行步骤里这样模型会主动去读CLAUDE.md而不是凭一般经验应付。6.3 连续三周的实测结果我做了个简单记录让AI在一个临时分支上做审查然后自己对照真实合并记录打分。版本有效问题/次错误建议/次可直接操作占比第一版无模板1.21.520%第二版有检查单2.80.565%第三版强化行号要求3.10.380%提升最明显的是第二版。误差主要集中在个别修复建议会破坏现有测试以及行号在改版之后偶尔有偏差。第三版我加了如果问题涉及多行给出起止行号这条约束错误建议率才进一步降下来。6.4 最终保留的经验模板里的命令式语气必须占比更高。像必须给出行号不要使用模糊评价如果没有问题要明确写出来这类话每一条都是为了让AI不偷懒。尤其是最后一条防止AI为了显得勤快而硬编问题。输出报告之后人只需要扫一遍标出的行号不需要重新审查全部代码。这才是模板的价值——它把人的精力从通读全部变成抽查可疑点。7. 把模板库变成团队资产7.1 Git仓库里除了模板还要放什么模板本身只是仓库的一部分。一个可以分发给团队的模板库至少还得有README写清楚怎么安装、怎么使用、每个目录是干什么的。CHANGELOG每次新增或修改模板记录一行变更原因。方便团队回滚。验收样例我把几个真实项目的匿名化审查结果放到examples目录作为模板效果的验收基线。更新模板后用这些样例跑一遍能快速发现退化。7.2 分发方式的选型人群不同分发方式真的不一样。我列一下我的对比结果方式优点缺点适合场景软链接改一处全部项目生效Windows有权限问题个人多项目复制简单稳定容易过时一次性项目Git Submodule版本同步明确操作复杂度高团队多仓库脚本拉取最新版分发快需要联网团队标准环境个人多项目我现在用软链接团队场景我推荐脚本方案。不管选哪种README里都要写清楚模板库是源头项目里的文件只是视图。7.3 团队协作时的三条约定第一模板变更必须走PR。哪怕只改了一个字也要走一遍评审流程防止一句话模板混进库里。第二新模板要有试用期。我建议至少两周用真实任务验证效果合格了才合并进正式目录。第三绝对不把密钥、内部服务器地址写进模板。模板库一旦跨项目复制或跨团队分享这些信息就是泄露面。凡是涉及环境差异的变量统一从.env读取不写进模板文件。7.4 维护节奏不要以为模板库是一次性工程。我一般两周做一次模板体检看最近两周的AI输出中有没有常见的低质量信号看有没有新出现的重复指令看旧模板中是否有规则被持续忽略。如果某条规则反复被忽略先检查是不是措辞太弱。改成命令式之后还忽略那就是排版太臃肿被其他规则淹没了需要精简。最后聊点我自己的体会。模板库最忌讳的就是想一口气建成终极形态。我一开始试图覆盖所有开发场景结果它臃肿到我自己都不想打开。后来把原则改成只把过去两周重复出现三次以上的需求写成模板整个库才真正活过来。如果你想做一套自己的claude-code-templates我的建议是从最常做、最容易衡量效果的任务入手比如代码审查。先写角色和目标再加三步执行步骤最后加上明确的输出格式约束。拿一个真实PR试跑看它给出的结果可不可用然后按第6节的思路迭代两三轮。模板库的价值从来不是数量多少而是每一条被加载的规则都被AI认真对待。