Claude Code 模板体系：提示词沉淀与 AI 编程工作流

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', encoding='utf-8') as f: content = f.read() tpl = Template(content) rendered = tpl.safe_substitute(variables) with open(dest_path, 'w', encoding='utf-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 版本验证通过”，这样团队升级时心里有数，不至于稀里糊涂踩坑。

下面整理一个速查表，方便你在遇到问题时逐个对照排查：

4.5 几个避坑小技巧

再补充几个无法归类、但实测很有用的技巧。第一，CLAUDE.md 里不要写“永远”和“总是”这种词，AI 会把绝对化指令执行到让你抓狂的程度。写“除非用户明确要求，否则不生成数据库迁移文件”比写“永远不要生成迁移文件”管用，前者给了 AI 一个退出路径，后者会让它在“我必须遵守”和“用户现在明确要求了”之间产生额外推理负担。第二，模板文件的标题尽量用动宾短语，比如“生成测试用例”“执行安全重构”，这样命令列表出来时信息密度高，你扫一眼就知道这个命令是干嘛的。第三，测试模板效果时不要只测一次就下结论，同一个任务连测三次，看输出是否稳定。模板的本职工作是降低方差，一次好不叫好，三次都保持同一水平线才叫有效。

5. 使用心得与进一步扩展

模板体系跑到现在，我最深的体会是：它本质上是一种“人机协作的接口设计”。你没给它模板，AI 是通用智能体，什么都会一点，但不知道你的偏好；给了它模板，它就变成了你定制过的协作者。真正花时间的不是写模板那一下，而是持续迭代模板。我几乎每次踩到一个新坑，都会回模板库加一条约束；每次发现 AI 某个回答方式特别顺手，也会在模板里固定下来。模板库成了我的“第二大脑”，但它不是替你思考，而是帮你把思考过的结果沉淀下来。

做这个仓库之前，我总觉得 AI 编程工具用得好不好全看个人功力。现在我觉得，个人功力当然重要，但功力的体现方式不是临场写提示词写得精妙，而是你是否有一套成熟的、能沉淀、能复用、能传承的模板体系。同样是用 Claude Code，有人每次都在从零开始，有人是在一个持续进化的资产上叠加新的任务。差别不在于模型本身，而在于模板。

后续我还打算扩展的方向有两个。一个是把模板库做成一个可以通过交互式界面生成模板的工具，而不是手动编辑 md 文件；另一个是给每个模板加上“适用场景示例”和“不适用场景示例”，让使用者在选择模板时更容易判断。如果你也在折腾 Claude Code 的模板，我的建议很直接：别追求一次写一个大而全的模板，从一个你最常做的流程开始，把它跑顺，再逐步扩展。模板这种东西，越用越顺手，越堆越有价值，但前提是你真的开始堆积它。