1. 为什么需要一套 Claude Code 模板体系1.1 从“能用”到“好用”模板背后到底解决了什么先用一个场景把问题说清楚。我最早接触 Claude Code 的时候感觉它就是“终端里的一个对话窗口”你输入需求它给你写代码、跑命令、改文件。听起来很爽但真正用起来会发现几个很头疼的点同一个功能今天让它按“先分析再动手”的方式做明天忘了加这句话它就直奔主题项目结构和代码风格立刻开始“漂移”。我经常怀疑自己是不是在用两个不同的 AI。后来我想明白一件事Claude Code 本身是强交互式的但你的习惯、你的项目规范、你希望它遵守的约束并不会自动沉淀下来。这些信息不会出现在模型参数里只存在于你的提示词里。提示词每次写得是否完整、是否稳定直接决定了输出质量的上限。而 claude-code-templates 这个仓库就是把我日常积累的提示词、工作流、命令定义全部结构化、模板化让“好的用法”从单次对话变成可复用的资产。用大白话说它就是把“这次运气好AI 表现很乖”变成“每次都能复现地乖”。我不是在做一个高大上的框架就是一套很务实的模板集合。你可以把它当成“做一个项目前先铺好的工作台”角色模板规定了 AI 是谁流程模板规定了它先干什么后干什么命令模板规定了你在终端里敲一个斜杠就能触发整套操作。对个人开发者来说它帮你省去每天重复敲提示词的时间对团队来说它让每个人的 AI 写代码风格统一code review 和结对编程都轻松很多。1.2 一套模板库的整体设计思路设计模板库之前我先列了一个需求清单明确这套东西到底要覆盖哪些场景。大致分四类角色设定、任务流程、快捷命令、项目初始化。角色设定解决“AI 以什么身份、什么口吻回答问题”任务流程解决“一件复杂事情分成几步、每步输出什么”快捷命令解决“高频操作一键触发”项目初始化解决“新项目从零开始时不遗漏配置和规范”。这四类不是并列的而是有一层递进关系角色是底座流程是骨架命令是入口脚手架是给新项目用的启动器。目录结构也按这四个维度来铺。我见过很多人的模板仓库乱七八糟一个文件夹里堆了几十个 md 文件名字像“prompt1”“prompt_new”“final”。这种仓库自己都很难维护更别说给别人用了。我的做法是每个类型一个顶层目录目录下按场景拆分子目录文件名统一用“场景-技术栈-动作”的命名方式检索的时候一眼就能定位。后面我会再把具体目录树放出来先记住一个原则模板库本身也要像代码一样讲可维护性否则它很快会变成新的“垃圾堆”。2. 模板分类与内容拆解2.1 角色模板给 AI 一个稳定的人设角色模板是整个体系的底座。没有角色设定Claude Code 的输出就处于“默认模式”你不知道它会偏向简洁还是啰嗦偏向保守还是激进。我的做法是为每个高频任务预设一套角色描述包含四个核心部分身份背景、专业边界、输出风格、强制约束。举个例子我有一个后端开发的常用角色模板名字叫“Python 架构师”。它的内容大致是这样身份背景写着“你是一名有 10 年中大型后端系统设计经验的 Python 架构师擅长 Django、FastAPI、PostgreSQL熟悉高并发场景和分布式事务处理”专业边界写明“你只负责方案设计不负责立即写出全部代码除非用户明确要求”输出风格是“结论先行每个建议都要给出至少一个权衡分析”强制约束是“禁止在主分支直接修改文件所有变更必须先说明影响面”。这里面最关键的是“专业边界”。很多模板失效就是因为只写了“你是专家”但没有写清楚哪些事你替用户做决定、哪些事只给建议。AI 这家伙一旦没有边界特别喜欢越权你问它“要不要用 Redis”它能直接帮你把缓存层代码全写了。加了边界之后它才会先给方案、等确认、再动手。这套逻辑跟带新人很像一开始就要讲清楚授权范围否则新人精力旺盛啥都敢改。角色模板我还会配一个“禁用清单”针对技术债务特别有用。比如规定“不要在实现细节尚未确认时引入新的第三方依赖”“不要臆造不存在的 API 参数”。这类清单不需要很长十条以内但每条必须是你在过去实践中真实踩过的雷。模板的价值不是知识多而是提炼了“哪些错误不应该再犯第二遍”。2.2 流程模板把复杂任务拆成检查清单流程模板解决的是“多步骤任务容易漏步骤”的问题。人写代码时会下意识地思考但 Claude Code 在单次对话里更倾向于“直接给出最终结果”。如果没有流程约束你让它做一个代码审查它可能只扫了一遍语法问题、提几个表面意见就交差。真正的 code review 应该包含哪些环节规矩全在流程模板里。我有一个code-review流程模板它的执行顺序写得很死先梳理变更文件清单和数据流再逐文件检查逻辑正确性然后专项检查并发、缓存、异常处理和 SQL 性能最后汇总输出一个 Markdown 报告。报告格式固定为“问题等级 文件位置 问题描述 修改建议 受影响范围”。为了防漏每一步我都给了对应的检查清单比如并发专项的清单里有“是否有共享可变状态”“是否有资源未释放”“重试逻辑是否会导致重复提交”。为什么敢把执行顺序写死因为代码审查是一个成熟的、高度结构化的认知活动经验丰富的工程师心里都有这套顺序。模板的作用就是把这套顺序显式化让 AI 每次都按这个顺序走。如果你不做限制它默认的路径往往是“从代码开头扫到结尾”而那样很可能忽略掉横向蔓延的问题比如一个数据库连接泄漏不是在某一行里能看出来的是跨函数、跨文件、跨请求生命周期才能看出来的。流程模板里我还习惯加一个“终止条件”小节避免 AI 在任务里绕圈。比如审查时规定“如果某个文件超过 500 行先输出该文件的整体结构再逐段分析不得一次性展开全部内容”这既控制了上下文长度也保证了审查质量。这个细节来自一次实际教训有个上万行的大文件AI 一口气把全文都读进去了不但 token 花得飞快而且注意力被平均分配真正的 bug 在最后几行反而没注意到。给流程加终止条件本质上是帮 AI 分配注意力。2.3 命令模板从“打长指令”到“敲斜杠”Claude Code 本身支持自定义 slash commands这是整套模板体系最“提效”的一层。配置位置在项目的.claude/commands/目录下或者用户级的~/.claude/commands/目录每个文件对应一个命令。文件名就是命令名内容是一个 Markdown 文件文件头可以写一段 YAML frontmatter 声明元信息比如 description、argument-hint、allowed-tools 这些。拿我仓库里的/commit命令举例配置很简单。frontmatter 里写description: Generate a conventional commit message from staged changes然后在正文里写一个精炼的 prompt先读取git diff --cached的输出再对照项目里的提交规范文件如果有的话最后输出一条符合 Conventional Commits 规范的提交信息。因为这个命令只在生成提交消息时需要读取 git 信息所以我在allowed-tools里只放 Read、Bash 两个工具防止它莫名其妙地去改文件。命令模板的优势在于把“动作 约束”打包成了一个入口。你可以用/review触发上节的代码审查流程用/test触发测试用例生成与执行流程用/fix让 Claude Code 针对最近的编译错误做针对性修改。命令文件里写的 prompt 可以直接引用仓库里的角色模板和流程模板形成组合拳。这个设计的思路和函数封装很像通用逻辑下沉入口薄薄一层调用方只需要知道命令名和参数不需要关心背后的复杂流程。写命令模板时有几个很实用的细节。第一description字段要写清楚“这个命令是干什么的、什么时候用”因为 Claude Code 的命令列表会显示描述描述写得好你脑子里搜索命令时能立刻匹配上第二参数用$ARGUMENTS这样的占位符它在命令执行时会替换成用户在命令后输入的内容第三同一个动作如果你既想跑全局也想跑项目级不要写成两个文件而是在全局和项目的 commands 目录里放同一个 symlink后面我会讲怎么用脚本统一管理。2.4 项目脚手架模板新项目开局不再手忙脚乱新项目初始化是最容易被忽略、又最能体现模板收益的场景。你有没有这种经历想开一个新项目在终端里敲了半天一会儿想用哪个框架一会儿想路由怎么组织一会儿想这个模块是不是该先写接口文档最后模板都建好了发现自己已经对着一个空目录发了半小时呆。项目脚手架模板就是为了消灭这种“开局迷茫”。我的脚手架模板不是传统意义上那套“生成完整个项目代码”的方案那太重、太死了。我更倾向于“约束 起步配置”的组合。比如我预设了一个fastapi-service脚手架它的输出包括项目目录结构建议、初始化配置文件清单、数据库与迁移工具选择建议、第一个健康检查接口的示例代码、以及一份写入了项目约定的 CLAUDE.md 文件。CLAUDE.md 是 Claude Code 的项目记忆文件里面记录项目简介、技术栈、命令约定、目录规范等。有了它AI 在后续所有对话中都能自动读取这些上下文相当于给 AI 戴了一副“项目眼镜”。脚手架模板和角色模板、流程模板的协作是这个项目的精髓。初始化的时候Claude Code 读取 CLAUDE.md 之后自然就知道后续该调用哪套角色模板、哪条流程模板。所以我不把 CLAUDE.md 当成一个静态说明文件而是当成模板体系的“索引”它告诉 Claude Code这个项目的角色模板在哪个文件里commit 命令用哪个规范代码生成遵循什么流程。这样一来一个项目从第一天开始就处于“受控状态”而不是等着 AI 在每次对话里自由发挥。3. 实操从零搭建自己的模板库3.1 仓库目录设计与命名规范我建议你直接用一个独立仓库来管理模板集合名字就叫claude-code-templates这样容易识别的名称。仓库的结构我在上面已经给了雏形这里给你一个能直接抄的版本claude-code-templates/ ├── README.md ├── CLAUDE.md ├── templates/ │ ├── roles/ │ │ ├── python-architect.md │ │ ├── go-backend-dev.md │ │ └── database-optimizer.md │ ├── workflows/ │ │ ├── code-review.md │ │ ├── refactor-safe.md │ │ └── test-generation.md │ ├── commands/ │ │ ├── review.md │ │ ├── commit.md │ │ └── fix.md │ └── scaffolds/ │ ├── fastapi-service.md │ └── go-grpc-server.md ├── examples/ ├── scripts/ │ ├── install.sh │ └── generate.py └── tests/ └── smoke_test.sh这个结构里我特意放了一个examples/目录用来放“模板生成效果示例”。比如code-review.md模板在某个真实项目上的输出报告脱敏后放进去。为什么要有 examples因为模板写得好不好最终要看它跑出来的效果。没有示例的模板库别人看着抽象有了真实案例别人一眼就明白“哦原来这个模板能产出这种质量的东西”。这个习惯也是从开源社区学来的好仓库都有清晰的 README 和示例。命名规范我遵守三条文件夹按功能分类不按时间分类有人喜欢按日期建目录那是灾难文件名用“领域-角色/动作-技术栈”比如go-backend-dev.md避免出现final_v2_new.md这种名字每个模板文件内部必须有 frontmatter 头块包含 name、version、适用范围、最后更新时间这样模板多了以后可以做版本追溯。3.2 模板语法与变量替换别把模板写死模板系统里最容易踩的坑是“写死内容”。你以为你在用模板其实是把个性化需求全硬编码进去了换一个项目就得全盘重写。我做了很长时间才意识到真正好用的模板一定要有变量占位。我的做法是用{{variable}}风格做占位符配合一个简单的生成脚本。模板文件里凡是会随项目变化的部分全部写成变量。比如脚手架模板里会有这样一段项目名{{project_name}} 技术栈{{tech_stack}} 数据库{{database_type}} 端口号{{port}} 请基于以上信息生成一个可运行的服务骨架 包含健康检查接口、配置管理、日志初始化和 {{database_type}} 连接池。生成脚本用 Python 写调用方可以用交互模式或者命令行参数传入变量值脚本解析所有模板文件里的占位符并替换然后输出到目标目录。这里我推荐用 Python 内置的string.Template不要一上来就上 jinja2。内置方式足够应付 99% 的替换需求而且没有依赖。代码大概是这样from string import Template def render_template(src_path, dest_path, variables): with open(src_path, r, encodingutf-8) as f: content f.read() tpl Template(content) rendered tpl.safe_substitute(variables) with open(dest_path, w, encodingutf-8) as f: f.write(rendered)为什么用safe_substitute而不是substitute因为substitute碰到模板里有个$符号比如讲解 shell 命令、价格占位、docker 环境变量引用就会直接抛异常safe_substitute只会把无法替换的原样保留安全很多。这个看起来是小问题但真在团队里跑起来报错率高的永远是这种“你没想到那里会有一个美元符号”的地方。除了变量替换我还给模板系统加了条件片段支持。实现方式很简单在模板里用三行标记包裹可选内容比如{{#if:use_redis}} ... {{/if}}生成脚本扫描这些标记根据变量里的布尔值决定保留或删除整段。虽然原理很朴素但实用性很强。有些脚手架想要 Redis有些不要模板不必维护两份脚本在渲染时做一次裁剪就行。这个功能我后来在很多场景都用上了比如是否包含 Dockerfile、是否包含 CI 配置、是否生成单元测试骨架。3.3 安装与接入让模板真正长在 Claude Code 里模板写好了接下来要解决“怎么装进 Claude Code”。Claude Code 的用户级命令目录是~/.claude/commands/项目级是.claude/commands/。我的install.sh做的事情就是把templates/commands/下的所有命令文件链接到两个目录中对应的位置。项目级目录如果不存在就创建全局命令目录同理。用软链接而不是复制文件这样仓库里改了模板生效不需要重新安装。这一点非常重要否则你每次升级模板都要重新跑一遍 copy很容易出现“模板更新了但本地还是旧版本”的问题。脚本再往前一步还能把角色模板和流程模板安装到~/.claude/下的一个子目录里并在 CLAUDE.md 中写上这些模板的路径索引。Claude Code 本身不会自动读取任意目录下的所有 md 文件但它会读 CLAUDE.md所以我们的套路是在 CLAUDE.md 里用“模板索引”的方式告诉 AI当遇到特定类型的任务时去哪个路径读取对应的角色或流程定义。相当于给 AI 做了一个“字典查询入口”而不是把所有内容一股脑塞给它。接入后的使用体验是这样的新项目开启时你敲一个/init命令我自定义的Claude Code 会加载脚手架模板生成一份带 CLAUDE.md 的初始项目后续你敲/commit提交代码它会严格按项目规范生成提交信息你做 review 时敲/review它会执行完整审查流程并输出报告。所有动作都有固定入口不依赖你临场描述。这才是“模板系统接入成功”的状态AI 的工作方式已经被你的规范和习惯接管了。3.4 模板版本管理与团队协作最后聊一下模板本身怎么维护。既然你把它当成工程资产就得用工程的思路管理。我的仓库是 Git 管理每个模板文件头部有 version 字段。版本号遵循语义化版本大改动比如整个流程重新设计升主版本兼容性小改动升次版本错别字、描述措辞调整升补丁版本。模板文件的更新不代表项目代码要更新但模板仓库自身要有 changelog这样你才能知道“模板是不是在我上次 review 之后悄悄变过了”。团队协作的场景下我见过最痛的场景是一个人改了个模板另一个人的本地软链接没有更新于是两个人在同一任务里得到完全不同的 AI 输出。我的解法是模板仓库单独建一个分支改动后先经过至少一位同事 review 再合入主干每个项目的 CLAUDE.md 里记录“本项目锁定的模板仓库版本号”install.sh 每次安装之前先 git pull 并校验版本。这套流程刚开始觉得繁琐但对团队来说它消除的是“AI 输出不可控”里最容易解决的那部分变数——至少它的行为基准是一致的。4. 常见问题与排查实录4.1 模板写了AI 却拒不遵守这是初学者最常遇到的挫败。明明角色模板里写了“结论先行”它还是先来一大段背景分析流程模板里写了“不要改文件”它照样动了文件。原因不在于 AI 不听话而是你的指令之间发生了冲突。比如你在角色模板里说“你是资深架构师要为方案给出完整设计”又在流程模板里说“简洁回答”这两个指令从 AI 的角度看就是矛盾的它不知道哪个优先于是自行判断。解决办法是给指令加优先级。我会在模板开头写“以下指令按优先级从高到低排列冲突时以高优先级为准”然后把“不修改文件”“不新增依赖”这种安全约束放在最高级把风格建议放在最低级。另外不要在同一个模板里既定义角色又定义输出格式这两个职责建议拆到不同模板文件里通过引用而不是一次性堆砌。堆砌的后果是 AI 的注意力被分散关键约束淹在一堆背景描述里。4.2 上下文超长与 token 浪费模板虽然是可复用的但如果你把大量角色描述和流程细节全部塞进 CLAUDE.md那每次新对话时 AI 都会把整个 CLAUDE.md 作为上下文读取token 消耗直接起飞而且还挤占了真正需要处理的代码内容。这个问题在项目大了之后尤其明显CLAUDE.md 很容易变成三千字的长文但真正每次对话都用得到的信息可能只有五分之一。我的解法是做“分层上下文”。CLAUDE.md 里只放高频摘要比如项目简要介绍、技术栈、常用命令、代码风格几大项总长度控制在 500 字以内完整的角色模板、流程模板放在 templates/ 目录里需要用的时候在对话里说一句“请先读取 templates/roles/python-architect.md 再开始设计”AI 会按需加载。这就像你不会把整本手册背在身上而是在目录查一查翻到对应章节再看。模板系统的最高原则不是“让 AI 知道一切”而是“让 AI 在合适的时刻知道合适的事”。4.3 变量替换咬到转义符号我在 3.2 节提过$符号的问题这里展开说下实际坑。用 Python 的Template做变量替换时模板里如果出现$variable会被当作占位符处理。但比如你在模板里写 shell 命令sed s/$foo/bar/、写 docker 的${IMAGE_NAME}、写 golang 模板{{ .Field }}都会踩进替换坑。我有一段时间特别苦恼明明模板内容是对的一渲染就乱。后来我在模板里统一了占位符风格一律用{{variable}}不用$。所有渲染前的替换脚本只认{{ }}的形式而对$开头的字符串完全忽略。此外我在脚本里加了一条预处理逻辑如果检测到模板中有$字符先输出一个警告提醒检查是否存在误用占位符的情况。这个小小的警告让我躲过很多次线上才发现问题的尴尬。如果你用的是 jinja2那语法冲突会更隐蔽因为{{和{%都可能撞车所以我不太推荐在包含技术代码作为角色的场景里用重型模板引擎。4.4 版本升级导致命令失效Claude Code 本身的配置格式不是一成不变的版本更新之后命令的 frontmatter 字段可能会变、allowed-tools 的枚举值可能会调。模板库经常出现的问题是一个月前还能用的/review命令升级后突然不识别了。这个我深有体会每次 Claude Code 发新版本我的第一反应不是看新功能而是先跑一遍模板库的 smoke test。我留了一个小型测试脚本内容很简单对每个命令文件解析 frontmatter检查必填字段是否存在、字段值是否在允许列表里、引用的模板路径是否存在然后对每个模板文件做一次 render 测试传入模拟变量确认没有异常。脚本跑一遍只要几秒钟但能兜住大部分“格式错了”导致的静默失效。建议你把版本锁定信息也写进 README例如“本模板库已在 Claude Code x.y.z 版本验证通过”这样团队升级时心里有数不至于稀里糊涂踩坑。下面整理一个速查表方便你在遇到问题时逐个对照排查症状可能原因处理方案AI 忽略角色约束指令冲突或角色描述太弱增加优先级标注拆分角色与流程模板每轮对话 token 飙高CLAUDE.md 过于冗长精简为摘要深内容按需读文件模板渲染后内容错乱占位符与内容符号冲突统一{{ }}占位对$做转义或忽略命令不识别 / 无响应Claude Code 版本升级格式变更跑 smoke test锁定模板兼容版本4.5 几个避坑小技巧再补充几个无法归类、但实测很有用的技巧。第一CLAUDE.md 里不要写“永远”和“总是”这种词AI 会把绝对化指令执行到让你抓狂的程度。写“除非用户明确要求否则不生成数据库迁移文件”比写“永远不要生成迁移文件”管用前者给了 AI 一个退出路径后者会让它在“我必须遵守”和“用户现在明确要求了”之间产生额外推理负担。第二模板文件的标题尽量用动宾短语比如“生成测试用例”“执行安全重构”这样命令列表出来时信息密度高你扫一眼就知道这个命令是干嘛的。第三测试模板效果时不要只测一次就下结论同一个任务连测三次看输出是否稳定。模板的本职工作是降低方差一次好不叫好三次都保持同一水平线才叫有效。5. 使用心得与进一步扩展模板体系跑到现在我最深的体会是它本质上是一种“人机协作的接口设计”。你没给它模板AI 是通用智能体什么都会一点但不知道你的偏好给了它模板它就变成了你定制过的协作者。真正花时间的不是写模板那一下而是持续迭代模板。我几乎每次踩到一个新坑都会回模板库加一条约束每次发现 AI 某个回答方式特别顺手也会在模板里固定下来。模板库成了我的“第二大脑”但它不是替你思考而是帮你把思考过的结果沉淀下来。做这个仓库之前我总觉得 AI 编程工具用得好不好全看个人功力。现在我觉得个人功力当然重要但功力的体现方式不是临场写提示词写得精妙而是你是否有一套成熟的、能沉淀、能复用、能传承的模板体系。同样是用 Claude Code有人每次都在从零开始有人是在一个持续进化的资产上叠加新的任务。差别不在于模型本身而在于模板。后续我还打算扩展的方向有两个。一个是把模板库做成一个可以通过交互式界面生成模板的工具而不是手动编辑 md 文件另一个是给每个模板加上“适用场景示例”和“不适用场景示例”让使用者在选择模板时更容易判断。如果你也在折腾 Claude Code 的模板我的建议很直接别追求一次写一个大而全的模板从一个你最常做的流程开始把它跑顺再逐步扩展。模板这种东西越用越顺手越堆越有价值但前提是你真的开始堆积它。
