有一段时间我几乎每天都泡在 Claude Code 的终端界面里。代码生成、仓库调研、测试补全、重构迁移……用得越顺手越发现一个问题每次新任务开对话我总要把同样一堆约束、角色设定、输出规范重新复制一遍。有时候粘错一段回复风格立刻跑偏。后来我把自己常用的一套提示词和工作流固定成模板建了一个叫claude-code-templates的小仓库。坚持整理几个版本之后工作方式的提升比我想象中明显很多。这篇就把我踩过的坑、怎么设计模板、怎么写规则、怎么和 Claude Code 无缝集成从头到尾完整梳理一遍。无论你是刚开始用 Claude Code还是已经重度依赖它这篇文章都能帮你少走不少弯路。1. 为什么需要自己的 Claude Code 模板库1.1 Claude Code 和模板各自的定位Claude Code 是跑在终端里的 AI 编程助手和你在网页端聊天不太一样。它可以直接读取项目文件、执行命令、修改代码甚至自己跑测试、看运行结果再把修复反馈给你。真正使用下来它更像一个“住在终端里的结对程序员”而不是一个简单的问答框。但正因为能力强它对“对话输入质量”的敏感度也特别高。同样一段需求换一种说法给不给上下文限不限制输出格式结果可能天差地别。默认情况下Claude Code 在空对话里就像一个刚来团队、什么都不知道的新人。你要它做代码审查至少要告诉它“项目背景、技术栈、关注重点、输出格式”这些信息要它重构模块至少要交代“边界在哪里、偏好什么风格、保留什么行为”。这些信息每次都现场写既慢又不稳定。模板就是把这个过程固化下来。把高频任务里反复出现的“角色、背景、输入结构、规则约束、输出格式”提前写好每次只需要把变量替换掉然后直接调用。Claude Code 本身也支持自定义 slash command允许你把模板挂到一个命令后面比如/review就能触发审查流程。这样既保留了 AI 的灵活性又有了工程化的确定性。1.2 模板解决的三类真实问题我整理模板库之前最头疼的问题是“每次上下文不一致”。同样让 Claude Code 审查代码心情好多写两句背景代码风格就偏“鼓励型”急着上线只丢一个文件路径审查结果就变流水账。回复风格天天变等于没有标准团队其他人也很难接手。第二个问题是“提示词越来越长”。刚开始我习惯把完整需求写在提示词里几轮对话之后上下文很臃肿。真正高频重复的判断原则、编码规范、错误优先级本来应该沉淀下来不该让每次对话从头讨论一遍。模板能把公共部分收敛到一处只把真正变化的部分暴露出来对话自然清爽得多。第三个问题更隐蔽Claude Code 在长对话里会慢慢“忘了”你最开始提的要求。前几轮还能按规范走做到第十步就开始自由发挥。模板不仅用于第一轮输入还可以通过重新注入关键规则来“拉回”当前状态。我经常在每轮交接时重新贴一遍模板里的核心约束效果比期待它自己记住要可靠得多。1.3 把模板当代码工程来管理其实大多数人所谓的“用模板”就是几个散落在备忘录里的提示词。这也能用但一旦任务变多、涉及协作问题就来了没有版本记录不知道自己改了什么没有分类临时找模板全靠翻没有目录约定团队里的每个人各自维护一套风格完全割裂。所以我从一开始就决定把claude-code-templates当一个小型代码库来维护。用 Git 管版本用目录做分类用统一的 frontmatter 格式记录模板的用途和参数用 CHANGELOG 记录每次规则变更。本质上提示词和代码没有区别都是需要维护、评审、演进的东西。一套真正好用的 Claude Code 模板库最后都会长得像一个开源项目。2. 模板库整体设计思路2.1 按任务类型划分模板目录模板库的第一步不是写内容而是定目录结构。我建议按“任务类型”划分而不是按“项目”划分。按项目分的问题是同样的“代码审查”需要在三个项目里复制三份按任务分一层是通用场景一层是项目专属适配复用性高很多。我现在的模板库大致长这样claude-code-templates/ ├── commands/ │ ├── review.md │ ├── refactor.md │ ├── test.md │ └── explain.md ├── agents/ │ ├── senior-reviewer.md │ ├── backend-architect.md │ └── ui-developer.md ├── projects/ │ ├── backend-service/ │ └── frontend-app/ ├── shared/ │ ├── code-style.md │ ├── security-checklist.md │ └── output-format.md ├── hooks/ │ └── context-loader.sh ├── CHANGELOG.md └── README.md每个目录的定位很清晰commands存放可以直接对应到 slash command 的完整工作流模板比如审查、解释、测试生成。agents是“角色化”模板平时直接当背景设定用适合比较长期的专项任务。shared是公共片段。不是完整的提示词而是某个规则块写模板时用include的方式引入避免重复粘贴。projects放项目专属上下文解释这个项目特有的目录结构、技术决策和编码偏好。2.2 模板文件的结构规范为了让模板可维护不是随手堆一段文字我强制每个模板文件有一个统一的头部结构。类似这样--- name: 代码审查 command: review description: 对指定文件或改动进行系统性审查输出问题列表和修改建议 tags: [review, code-quality] input: - files: 待审查文件列表 - focus: 重点审查维度可选 model: claude-sonnet-4-5 temperature: 0.2 encoding: utf-8 --- ## 角色 你是一名资深的代码审查专家习惯从可维护性、可测试性、安全性三个角度评审代码。 ## 背景 用户会提供一段完整代码或一个 diff。项目技术栈请根据实际情况填写。 ## 规则 1. 先定位问题再给修改建议不要直接整段重写。 2. 严重程度分为 P0/P1/P2/P3必须明确标注。 3. 如果没有足够的上下文允许提出澄清问题但不要超过 3 个。 ## 输出格式 ### 问题清单 - [P1] 问题描述 / 位置 / 建议 ### 修改建议 - 针对每个 P0/P1 给出具体 patch 思路用这种结构化 Head 的好处是脚本可以读取 frontmatter 自动生成命令菜单也可以校验参数是否齐全。内容则分成“角色、背景、规则、输出格式”四个部分让 Claude Code 的每一轮输出都有迹可循。2.3 公共片段与模板“组合复用”我早期犯过一个错误每个模板都写得很完整结果大量内容重复。角色设定重复输出规范重复安全清单重复。后来一改规则要改一堆文件改漏一个就会出现“两个模板输出风格不一致”的问题。真正稳定的做法是拆分公共片段。比如shared/code-style.md只管编程风格约束shared/security-checklist.md只管安全风险检查项。写新模板时用“引用体”把它们组合进来请严格遵循以下公共规范 include pathshared/code-style.md / include pathshared/security-checklist.md /这里的include是我自己定的一种伪指令实际加载时用脚本或手动复制内容。好处是规则分属单一来源不会产生多个副本。缺点是需要额外一层加载逻辑后面我会讲怎么在 Claude Code 环境里处理这件事。3. 核心模板拆解与编写要点3.1 代码审查模板先定规则再让模型“圈问题”代码审查是我最常用也最容易被低估的场景。很多人直接丢一段代码给 Claude Code 说“帮我看看有什么问题”结果它给你回一堆“这段代码不错、逻辑清晰”的客套话最后附两条无关紧要的建议。真正好用的审查模板必须先把“审查基线”定义清楚。审查基线包括几个维度优先级怎么排、问题怎么表述、哪些内容不审、是否需要给出修复 patch。我自己的审查模板里有一个“不要做什么”的清单## 禁止项 - 不要夸奖代码不要使用鼓励性语言 - 不要在没有定位到具体函数/行号的情况下泛泛而谈 - 不要修改代码只在建议中给出关键代码思路这段内容看起来很简单但对输出质量的改变是决定性的。我发现 Claude Code 的默认倾向是“配合用户”如果你只模糊地问“帮我看看”它会倾向于说好话。把禁止项写清楚等于直接切断了这种倾向。入参部分我建议模板里预留一个“待审查内容区块”。可以是一个 diff、一个完整的文件或者一个函数。用显眼的分隔符包裹起来--- 待审查代码开始 --- ... --- 待审查代码结束 ---分隔符有两个作用一是让模型知道哪些部分是数据不能被当成它的指令二是方便脚本从某个路径自动读取内容填入避免手动复制大段代码。3.2 重构模板输入“现状”和“目标”中间推导交给模型重构任务最容易翻车因为 Claude Code 容易“过度发挥”。你说“把这个函数拆开”它能顺手把变量名、注释、周边逻辑全部改了。代码能运行但 diff 大得吓人code review 的时候多花两倍时间。重构模板的核心是两个区块现状描述区和目标约束区。## 现状 - 文件: src/utils/date.ts - 当前行为: formatDate 函数混合了时区转换、格式化和边界判断 - 问题: 逻辑纠缠测试困难 ## 目标 - 将 formatDate 拆成 parseDate 和 formatDate 两个纯函数 - 保持对外导出接口兼容 - 不改变函数语义不修改调用方 - 不做额外重命名或代码清理这里最关键的一句是“不改变函数语义不修改调用方”。这句话说清楚之后Claude Code 的重构范围明显收敛很多。如果不说它很容易把 API 也顺手改了。另外重构模板的输出格式我会要求“先给计划再给执行步骤最后给 check list”。因为它不是一次生成就完事往往需要跑测试、看 diff、再迭代。3.3 新功能开发模板从一句话需求到任务清单Claude Code 最强的地方是能拉通项目上下文所以“新功能模板”我的目标不是让它直接写代码而是让它先做“需求分析”和“任务拆解”。很多新人容易犯的错是需求还没聊清楚就让它开始写导致后面反复返工。新功能模板这样设计## 角色 你是这个项目里技术决策能力和架构直觉都很强的高级工程师。 ## 输入需求 用户会用自然语言描述一个功能需求可能模糊允许存在信息缺口。 ## 处理步骤 1. 先用问题列表补齐需求缺口最多 5 个问题 2. 根据项目现状给出实现方案包含涉及的文件和接口 3. 输出按依赖顺序排列的任务清单每个任务有验收标准 4. 在所有问题得到回答前不要生成代码第四点尤其关键。Claude Code 默认喜欢直接干活但需求不明确的提前写代码等于埋雷。模板里把这个步骤优先级提得非常高实际使用中给我省下很多返工时间。3.4 角色模板把“判断偏好”固化成长期会话任务型模板适合一次性执行角色模板则适合挂在长期任务或复杂会话里。比如我现在负责一个后端服务我会启动一个“后端架构师”角色把架构原则、技术栈、目录约定、不喜欢什么风格全都初始化进去然后在这个角色下持续讨论和开发。角色模板和任务模板的主要区别是它更强调“价值观”和“判断偏好”## 架构偏好 - 优先简单方案能不用中间件就不用 - 对性能优化保持克制先度量再优化 - 接口设计倾向显式优于隐式 - 所有异步任务必须考虑失败重试和幂等 ## 技术栈约束 - Python 3.12 FastAPI - 数据库访问统一走 SQLAlchemy 2.x - 新代码禁止引入未评审的第三方依赖这些内容不会直接出现在一条输出里但会持续影响模型后续的每个决定。我觉得这是使用 Claude Code 最有价值的部分它不只是“按指令办事”而能在每一次回答里体现你的工程品味。3.5 编写提示词的四个隐性技巧写模板一段时间后我总结出四个值得分享的小技巧规则要放在“输入内容”前面。Claude Code 对指令的记忆强度会随内容增长减弱关键规则越靠前保持得越久。用“必须”和“禁止”代替模糊的“尽量”“最好”。模型对绝对词的执行率远高于程度词。给一个期望的反例。比如在输出格式里写一份“这种结果不合格”的例子比只写正面要求有效得多。不要把策略和事实混在一起。策略是“你应该怎么做”事实是“当前项目是什么”。分开写模型对两者的使用方式完全不同。这些技巧听起来很玄但其实都能从原理上解释Claude Code 本质上是一个基于概率的上下文推理系统它的每一轮输出都受前文影响。框架越清晰、规则越明确、反例越具体它的“随机发挥”空间就越小。4. 实操过程从零搭建一个可用模板库4.1 初始化仓库和基础结构第一步是建目录。按前面说的结构初始化即可不用太复杂。如果你已经有一个常用项目仓库把模板库作为一个子目录放进去也行。但我更建议单独建一个仓库因为模板它本身是跨项目的资产。mkdir claude-code-templates cd claude-code-templates git init mkdir commands agents projects shared hooks touch README.md CHANGELOG.md .gitignore这些操作都很常规真正值得花时间的是写好根目录的README.md。它要回答几个问题这份模板库覆盖哪些场景每个命令怎么用新增模板时需要遵循什么格式团队新成员看一眼 README 就知道怎么贡献这比口头沟通高效太多。4.2 编写第一个完整模板从需求到可运行接下来用一个具体例子演示怎么从零写一个能用的模板。假设我要做一个“测试生成”模板。起草阶段先列出这个模板必须包含的信息- 需要测试的函数名或模块路径 - 项目使用的测试框架Jest / Vitest / Pytest / Go testing - 需要覆盖的测试类型单测、边界、异常路径 - 输出格式生成可运行的测试文件路径和代码然后写成正式的模板--- name: 测试生成 command: testgen description: 为指定函数或模块生成单元测试包含边界和异常场景 --- ## 角色 你是一名对测试敏感度很高的工程师熟悉多种测试框架。 ## 背景 技术栈信息会自动从项目配置中获取。请先确认项目使用的测试框架再输出代码。 ## 规则 1. 测试必须使用 AAA 结构Arrange / Act / Assert 2. 不允许只测“正常路径”必须补充至少两个边界用例 3. 如果一个函数有异常抛出必须为每个异常分支写一个用例 4. mock 外部依赖时必须注释说明为什么需要 mock ## 输出格式 每个测试用例包含测试名称、测试意图、期望结果。 最终输出可直接运行的测试代码文件名按被测模块自动命名。把这个文件保存为commands/testgen.md后它还只是一个普通 markdown需要接到 Claude Code 的 slash command 里。Claude Code 支持通过配置文件注册自定义命令大致写法是/testgen 使用测试生成模板读取 commands/testgen.md并替换其中的输入变量如果你用的客户端支持 prompt 文件或 slash command 文件直接加载那就更省事把模板放到指定目录即可。不同版本的 Claude Code 配置方式有差异但核心逻辑是一样的模板内容负责定义怎么思考命令入口负责决定何时调用。4.3 参数化模板从“一次性提示词”到“可复用资产”模板写好后下一步是参数化。这一步很关键因为如果每个模板都要手改 markdown 里的大段文字那不是模板库只是备忘录。我常用两种方式实现参数化第一种是占位符替换。在模板里写{{files}}、{{focus}}这类变量加载时用脚本读取命令行参数替换到模板内容里。例如load_template() { local template$1 local target$2 sed s/{{files}}/$target/g $template /tmp/prompt.md }这种方式简单直接适合 CLI 场景。缺点是不能处理复杂转义文件名里如果有特殊字符容易出问题。所以我更常用第二种方式让模板自己读取上下文。实际操作是模板里只写一句话“请从运行目录下读取CHANGELOG.md和最近的 diff”然后把数据文件的路径作为参数传进去。Claude Code 本身有文件读取能力让它自己去读不仅省去了内容替换还能让它更早接触真实文件并且形成对全局的理解。## 输入 请读取以下文件作为本次审查的输入 - 变更文件: {{files}} - 变更范围: git diff HEAD~1 - 重点维度: {{focus}}这里的{{files}}会被脚本替换为实际参数git diff HEAD~1则是模板里的固定指令。让 Claude Code 自己去执行 git 命令读取 diff比我们手动粘贴一段 diff 要优雅得多而且也不容易截断。4.4 与项目上下文的深度集成模板库如果和项目上下文完全割裂价值会大打折扣。Claude Code 本来就有项目级记忆机制通常是一个CLAUDE.md文件里面放项目简介、技术栈、命令习惯。很多模板里需要重复出现的“项目背景”其实都应该放到CLAUDE.md而不是放进每个模板。我的做法是分层集成CLAUDE.md放最稳定的公共事实比如项目结构、启动命令、代码风格。shared/公共片段放跨项目的判断规则比如安全清单、重构红线。commands/模板放任务流程它会自动引用前两者的内容。这样你在执行/review命令时模板真正加载的内容可能只有几十行但 Claude Code 的上下文里已经有项目全局、公共规范、任务流程三层信息。它比一个几百行的“巨型提示词”效果好得多因为事实部分不需要重复灌输规则部分独立可更新流程部分保持精简。5. 常见问题与排查技巧实录5.1 模板明明写了规则为什么还是被无视这个问题几乎每个人都会遇到。我排查时第一步是确认“规则是不是在有效位置”。如果规则写在模板文件的末尾或者混在示例代码之后很容易被后来的内容冲淡。Claude Code 本身有比较强的“最近信息优先”倾向所以核心规则必须放在首次指令的最前面。第二个原因是规则和数据混在一起。如果你在模板里写了一段示例代码然后要求“这是反例不要照着做”模型很可能会被示例带偏反而生成类似文本。解决方法是把反例放在最后并用清晰的“禁止”句式包裹。第三个原因更隐蔽规则和任务冲突。比如模板说“不要修改代码”但前面又说“如果有 bug请直接修复”模型在执行时就会产生摇摆最后随机选择一边。所以写模板时一定要检查规则之间有没有互相打架的表述。5.2 回复越来越长核心内容却越来越少Claude Code 在长对话中很容易出现“注水”现象。早期我的审查模板输出特别长每条问题都给大段说明review 变成了一篇论文真正需要改的反而被淹没。针对这个我做了两个调整。一是给输出格式加上强约束比如“每个问题描述不超过两行建议部分用简短代码展示”。二是增加“二次压缩环节”模板里写清楚审查完成后用三行以内总结最需要优先处理的三个问题。## 最终总结 只输出 3 个最需要人工关注的问题每行一个包含位置和一句话描述。这个“二次压缩”非常重要。它让模型在完成详细分析后做一个提炼动作相当于自己做了摘要。它比从一开始就要求“简短输出”更有效因为详细分析时模型信息更充足压缩出来的摘要也更有判断力。5.3 如何避免每次调用模板时重新读一遍项目这是我自己踩过最深的坑。早期每次启动 Claude Code 会话模板里都有一句“请先读取 package.json、README.md、src 目录结构”然后它会花很长时间探索项目前几分钟全在做无用功。后来我把探索结果收敛到CLAUDE.md里。第一次手动让它生成一份项目摘要之后每次会话启动时先把摘要注入它就不需要重复扫描。这个方法对大型项目尤其有效上下文占用从几万 token 降到了几十行响应速度提升非常明显。当然项目结构变化后摘要会过期所以还应该配套一个“重新生成摘要”的模板命令比如/refresh-context每周触发一次保证信息不过期。5.4 多人协同时模板风格无法统一一个人维护模板库最容易团队协作就会冒出各种问题。有人喜欢详细有人喜欢精简有人把自己的偏好写进公共模板结果所有人被影响。我建议把模板库分成“稳定区”和“试验区分支”稳定区的模板需要经过 review通过后才能合并进主分支。个人试验模板放在自己的分支或单独目录里不轻易影响别人。模板本身的可读性要纳入 code review 范围。看到语义不清的规则及时指出。同时CHANGELOG 要跟上。每次改规则哪怕只改半句话也记一笔写上为什么改。否则模板库几个月后没人知道当初某句约束的价值最后只能推倒重来。5.5 模板库自身的维护与边界最后说一点维护层面的经验。模板库和正式代码库一样也会腐化。一段时间不维护里面的技术栈描述过期了公共片段里的规范已经不符合新团队实践了继承下来的模板就反向变成“历史包袱”。我自己的节奏是每个月抽半天时间做一次“模板评审”。把高频命令调出来实际跑一遍看看输出质量有没有下降看看公共片段有没有冗余看看有没有哪些规则因为项目演进已经失去意义。这个习惯听起来很“过程化”但实际投入回报比很高因为一套高质量的模板库真的能撑起你一整年的 AI 辅助编程体验。其实维护模板库最大的心得就是别把它当成“一次性提示词收藏夹”。它更像一套不断进化的操作手册今天你写下的每一行约束都在替未来的自己省去一次即将发生的方向跑偏。我现在每次新建会话都从模板库出发代码质量的稳定性也肉眼可见地提高了。
Claude Code模板库实战：从提示词工程到高效AI编程工作流
有一段时间我几乎每天都泡在 Claude Code 的终端界面里。代码生成、仓库调研、测试补全、重构迁移……用得越顺手越发现一个问题每次新任务开对话我总要把同样一堆约束、角色设定、输出规范重新复制一遍。有时候粘错一段回复风格立刻跑偏。后来我把自己常用的一套提示词和工作流固定成模板建了一个叫claude-code-templates的小仓库。坚持整理几个版本之后工作方式的提升比我想象中明显很多。这篇就把我踩过的坑、怎么设计模板、怎么写规则、怎么和 Claude Code 无缝集成从头到尾完整梳理一遍。无论你是刚开始用 Claude Code还是已经重度依赖它这篇文章都能帮你少走不少弯路。1. 为什么需要自己的 Claude Code 模板库1.1 Claude Code 和模板各自的定位Claude Code 是跑在终端里的 AI 编程助手和你在网页端聊天不太一样。它可以直接读取项目文件、执行命令、修改代码甚至自己跑测试、看运行结果再把修复反馈给你。真正使用下来它更像一个“住在终端里的结对程序员”而不是一个简单的问答框。但正因为能力强它对“对话输入质量”的敏感度也特别高。同样一段需求换一种说法给不给上下文限不限制输出格式结果可能天差地别。默认情况下Claude Code 在空对话里就像一个刚来团队、什么都不知道的新人。你要它做代码审查至少要告诉它“项目背景、技术栈、关注重点、输出格式”这些信息要它重构模块至少要交代“边界在哪里、偏好什么风格、保留什么行为”。这些信息每次都现场写既慢又不稳定。模板就是把这个过程固化下来。把高频任务里反复出现的“角色、背景、输入结构、规则约束、输出格式”提前写好每次只需要把变量替换掉然后直接调用。Claude Code 本身也支持自定义 slash command允许你把模板挂到一个命令后面比如/review就能触发审查流程。这样既保留了 AI 的灵活性又有了工程化的确定性。1.2 模板解决的三类真实问题我整理模板库之前最头疼的问题是“每次上下文不一致”。同样让 Claude Code 审查代码心情好多写两句背景代码风格就偏“鼓励型”急着上线只丢一个文件路径审查结果就变流水账。回复风格天天变等于没有标准团队其他人也很难接手。第二个问题是“提示词越来越长”。刚开始我习惯把完整需求写在提示词里几轮对话之后上下文很臃肿。真正高频重复的判断原则、编码规范、错误优先级本来应该沉淀下来不该让每次对话从头讨论一遍。模板能把公共部分收敛到一处只把真正变化的部分暴露出来对话自然清爽得多。第三个问题更隐蔽Claude Code 在长对话里会慢慢“忘了”你最开始提的要求。前几轮还能按规范走做到第十步就开始自由发挥。模板不仅用于第一轮输入还可以通过重新注入关键规则来“拉回”当前状态。我经常在每轮交接时重新贴一遍模板里的核心约束效果比期待它自己记住要可靠得多。1.3 把模板当代码工程来管理其实大多数人所谓的“用模板”就是几个散落在备忘录里的提示词。这也能用但一旦任务变多、涉及协作问题就来了没有版本记录不知道自己改了什么没有分类临时找模板全靠翻没有目录约定团队里的每个人各自维护一套风格完全割裂。所以我从一开始就决定把claude-code-templates当一个小型代码库来维护。用 Git 管版本用目录做分类用统一的 frontmatter 格式记录模板的用途和参数用 CHANGELOG 记录每次规则变更。本质上提示词和代码没有区别都是需要维护、评审、演进的东西。一套真正好用的 Claude Code 模板库最后都会长得像一个开源项目。2. 模板库整体设计思路2.1 按任务类型划分模板目录模板库的第一步不是写内容而是定目录结构。我建议按“任务类型”划分而不是按“项目”划分。按项目分的问题是同样的“代码审查”需要在三个项目里复制三份按任务分一层是通用场景一层是项目专属适配复用性高很多。我现在的模板库大致长这样claude-code-templates/ ├── commands/ │ ├── review.md │ ├── refactor.md │ ├── test.md │ └── explain.md ├── agents/ │ ├── senior-reviewer.md │ ├── backend-architect.md │ └── ui-developer.md ├── projects/ │ ├── backend-service/ │ └── frontend-app/ ├── shared/ │ ├── code-style.md │ ├── security-checklist.md │ └── output-format.md ├── hooks/ │ └── context-loader.sh ├── CHANGELOG.md └── README.md每个目录的定位很清晰commands存放可以直接对应到 slash command 的完整工作流模板比如审查、解释、测试生成。agents是“角色化”模板平时直接当背景设定用适合比较长期的专项任务。shared是公共片段。不是完整的提示词而是某个规则块写模板时用include的方式引入避免重复粘贴。projects放项目专属上下文解释这个项目特有的目录结构、技术决策和编码偏好。2.2 模板文件的结构规范为了让模板可维护不是随手堆一段文字我强制每个模板文件有一个统一的头部结构。类似这样--- name: 代码审查 command: review description: 对指定文件或改动进行系统性审查输出问题列表和修改建议 tags: [review, code-quality] input: - files: 待审查文件列表 - focus: 重点审查维度可选 model: claude-sonnet-4-5 temperature: 0.2 encoding: utf-8 --- ## 角色 你是一名资深的代码审查专家习惯从可维护性、可测试性、安全性三个角度评审代码。 ## 背景 用户会提供一段完整代码或一个 diff。项目技术栈请根据实际情况填写。 ## 规则 1. 先定位问题再给修改建议不要直接整段重写。 2. 严重程度分为 P0/P1/P2/P3必须明确标注。 3. 如果没有足够的上下文允许提出澄清问题但不要超过 3 个。 ## 输出格式 ### 问题清单 - [P1] 问题描述 / 位置 / 建议 ### 修改建议 - 针对每个 P0/P1 给出具体 patch 思路用这种结构化 Head 的好处是脚本可以读取 frontmatter 自动生成命令菜单也可以校验参数是否齐全。内容则分成“角色、背景、规则、输出格式”四个部分让 Claude Code 的每一轮输出都有迹可循。2.3 公共片段与模板“组合复用”我早期犯过一个错误每个模板都写得很完整结果大量内容重复。角色设定重复输出规范重复安全清单重复。后来一改规则要改一堆文件改漏一个就会出现“两个模板输出风格不一致”的问题。真正稳定的做法是拆分公共片段。比如shared/code-style.md只管编程风格约束shared/security-checklist.md只管安全风险检查项。写新模板时用“引用体”把它们组合进来请严格遵循以下公共规范 include pathshared/code-style.md / include pathshared/security-checklist.md /这里的include是我自己定的一种伪指令实际加载时用脚本或手动复制内容。好处是规则分属单一来源不会产生多个副本。缺点是需要额外一层加载逻辑后面我会讲怎么在 Claude Code 环境里处理这件事。3. 核心模板拆解与编写要点3.1 代码审查模板先定规则再让模型“圈问题”代码审查是我最常用也最容易被低估的场景。很多人直接丢一段代码给 Claude Code 说“帮我看看有什么问题”结果它给你回一堆“这段代码不错、逻辑清晰”的客套话最后附两条无关紧要的建议。真正好用的审查模板必须先把“审查基线”定义清楚。审查基线包括几个维度优先级怎么排、问题怎么表述、哪些内容不审、是否需要给出修复 patch。我自己的审查模板里有一个“不要做什么”的清单## 禁止项 - 不要夸奖代码不要使用鼓励性语言 - 不要在没有定位到具体函数/行号的情况下泛泛而谈 - 不要修改代码只在建议中给出关键代码思路这段内容看起来很简单但对输出质量的改变是决定性的。我发现 Claude Code 的默认倾向是“配合用户”如果你只模糊地问“帮我看看”它会倾向于说好话。把禁止项写清楚等于直接切断了这种倾向。入参部分我建议模板里预留一个“待审查内容区块”。可以是一个 diff、一个完整的文件或者一个函数。用显眼的分隔符包裹起来--- 待审查代码开始 --- ... --- 待审查代码结束 ---分隔符有两个作用一是让模型知道哪些部分是数据不能被当成它的指令二是方便脚本从某个路径自动读取内容填入避免手动复制大段代码。3.2 重构模板输入“现状”和“目标”中间推导交给模型重构任务最容易翻车因为 Claude Code 容易“过度发挥”。你说“把这个函数拆开”它能顺手把变量名、注释、周边逻辑全部改了。代码能运行但 diff 大得吓人code review 的时候多花两倍时间。重构模板的核心是两个区块现状描述区和目标约束区。## 现状 - 文件: src/utils/date.ts - 当前行为: formatDate 函数混合了时区转换、格式化和边界判断 - 问题: 逻辑纠缠测试困难 ## 目标 - 将 formatDate 拆成 parseDate 和 formatDate 两个纯函数 - 保持对外导出接口兼容 - 不改变函数语义不修改调用方 - 不做额外重命名或代码清理这里最关键的一句是“不改变函数语义不修改调用方”。这句话说清楚之后Claude Code 的重构范围明显收敛很多。如果不说它很容易把 API 也顺手改了。另外重构模板的输出格式我会要求“先给计划再给执行步骤最后给 check list”。因为它不是一次生成就完事往往需要跑测试、看 diff、再迭代。3.3 新功能开发模板从一句话需求到任务清单Claude Code 最强的地方是能拉通项目上下文所以“新功能模板”我的目标不是让它直接写代码而是让它先做“需求分析”和“任务拆解”。很多新人容易犯的错是需求还没聊清楚就让它开始写导致后面反复返工。新功能模板这样设计## 角色 你是这个项目里技术决策能力和架构直觉都很强的高级工程师。 ## 输入需求 用户会用自然语言描述一个功能需求可能模糊允许存在信息缺口。 ## 处理步骤 1. 先用问题列表补齐需求缺口最多 5 个问题 2. 根据项目现状给出实现方案包含涉及的文件和接口 3. 输出按依赖顺序排列的任务清单每个任务有验收标准 4. 在所有问题得到回答前不要生成代码第四点尤其关键。Claude Code 默认喜欢直接干活但需求不明确的提前写代码等于埋雷。模板里把这个步骤优先级提得非常高实际使用中给我省下很多返工时间。3.4 角色模板把“判断偏好”固化成长期会话任务型模板适合一次性执行角色模板则适合挂在长期任务或复杂会话里。比如我现在负责一个后端服务我会启动一个“后端架构师”角色把架构原则、技术栈、目录约定、不喜欢什么风格全都初始化进去然后在这个角色下持续讨论和开发。角色模板和任务模板的主要区别是它更强调“价值观”和“判断偏好”## 架构偏好 - 优先简单方案能不用中间件就不用 - 对性能优化保持克制先度量再优化 - 接口设计倾向显式优于隐式 - 所有异步任务必须考虑失败重试和幂等 ## 技术栈约束 - Python 3.12 FastAPI - 数据库访问统一走 SQLAlchemy 2.x - 新代码禁止引入未评审的第三方依赖这些内容不会直接出现在一条输出里但会持续影响模型后续的每个决定。我觉得这是使用 Claude Code 最有价值的部分它不只是“按指令办事”而能在每一次回答里体现你的工程品味。3.5 编写提示词的四个隐性技巧写模板一段时间后我总结出四个值得分享的小技巧规则要放在“输入内容”前面。Claude Code 对指令的记忆强度会随内容增长减弱关键规则越靠前保持得越久。用“必须”和“禁止”代替模糊的“尽量”“最好”。模型对绝对词的执行率远高于程度词。给一个期望的反例。比如在输出格式里写一份“这种结果不合格”的例子比只写正面要求有效得多。不要把策略和事实混在一起。策略是“你应该怎么做”事实是“当前项目是什么”。分开写模型对两者的使用方式完全不同。这些技巧听起来很玄但其实都能从原理上解释Claude Code 本质上是一个基于概率的上下文推理系统它的每一轮输出都受前文影响。框架越清晰、规则越明确、反例越具体它的“随机发挥”空间就越小。4. 实操过程从零搭建一个可用模板库4.1 初始化仓库和基础结构第一步是建目录。按前面说的结构初始化即可不用太复杂。如果你已经有一个常用项目仓库把模板库作为一个子目录放进去也行。但我更建议单独建一个仓库因为模板它本身是跨项目的资产。mkdir claude-code-templates cd claude-code-templates git init mkdir commands agents projects shared hooks touch README.md CHANGELOG.md .gitignore这些操作都很常规真正值得花时间的是写好根目录的README.md。它要回答几个问题这份模板库覆盖哪些场景每个命令怎么用新增模板时需要遵循什么格式团队新成员看一眼 README 就知道怎么贡献这比口头沟通高效太多。4.2 编写第一个完整模板从需求到可运行接下来用一个具体例子演示怎么从零写一个能用的模板。假设我要做一个“测试生成”模板。起草阶段先列出这个模板必须包含的信息- 需要测试的函数名或模块路径 - 项目使用的测试框架Jest / Vitest / Pytest / Go testing - 需要覆盖的测试类型单测、边界、异常路径 - 输出格式生成可运行的测试文件路径和代码然后写成正式的模板--- name: 测试生成 command: testgen description: 为指定函数或模块生成单元测试包含边界和异常场景 --- ## 角色 你是一名对测试敏感度很高的工程师熟悉多种测试框架。 ## 背景 技术栈信息会自动从项目配置中获取。请先确认项目使用的测试框架再输出代码。 ## 规则 1. 测试必须使用 AAA 结构Arrange / Act / Assert 2. 不允许只测“正常路径”必须补充至少两个边界用例 3. 如果一个函数有异常抛出必须为每个异常分支写一个用例 4. mock 外部依赖时必须注释说明为什么需要 mock ## 输出格式 每个测试用例包含测试名称、测试意图、期望结果。 最终输出可直接运行的测试代码文件名按被测模块自动命名。把这个文件保存为commands/testgen.md后它还只是一个普通 markdown需要接到 Claude Code 的 slash command 里。Claude Code 支持通过配置文件注册自定义命令大致写法是/testgen 使用测试生成模板读取 commands/testgen.md并替换其中的输入变量如果你用的客户端支持 prompt 文件或 slash command 文件直接加载那就更省事把模板放到指定目录即可。不同版本的 Claude Code 配置方式有差异但核心逻辑是一样的模板内容负责定义怎么思考命令入口负责决定何时调用。4.3 参数化模板从“一次性提示词”到“可复用资产”模板写好后下一步是参数化。这一步很关键因为如果每个模板都要手改 markdown 里的大段文字那不是模板库只是备忘录。我常用两种方式实现参数化第一种是占位符替换。在模板里写{{files}}、{{focus}}这类变量加载时用脚本读取命令行参数替换到模板内容里。例如load_template() { local template$1 local target$2 sed s/{{files}}/$target/g $template /tmp/prompt.md }这种方式简单直接适合 CLI 场景。缺点是不能处理复杂转义文件名里如果有特殊字符容易出问题。所以我更常用第二种方式让模板自己读取上下文。实际操作是模板里只写一句话“请从运行目录下读取CHANGELOG.md和最近的 diff”然后把数据文件的路径作为参数传进去。Claude Code 本身有文件读取能力让它自己去读不仅省去了内容替换还能让它更早接触真实文件并且形成对全局的理解。## 输入 请读取以下文件作为本次审查的输入 - 变更文件: {{files}} - 变更范围: git diff HEAD~1 - 重点维度: {{focus}}这里的{{files}}会被脚本替换为实际参数git diff HEAD~1则是模板里的固定指令。让 Claude Code 自己去执行 git 命令读取 diff比我们手动粘贴一段 diff 要优雅得多而且也不容易截断。4.4 与项目上下文的深度集成模板库如果和项目上下文完全割裂价值会大打折扣。Claude Code 本来就有项目级记忆机制通常是一个CLAUDE.md文件里面放项目简介、技术栈、命令习惯。很多模板里需要重复出现的“项目背景”其实都应该放到CLAUDE.md而不是放进每个模板。我的做法是分层集成CLAUDE.md放最稳定的公共事实比如项目结构、启动命令、代码风格。shared/公共片段放跨项目的判断规则比如安全清单、重构红线。commands/模板放任务流程它会自动引用前两者的内容。这样你在执行/review命令时模板真正加载的内容可能只有几十行但 Claude Code 的上下文里已经有项目全局、公共规范、任务流程三层信息。它比一个几百行的“巨型提示词”效果好得多因为事实部分不需要重复灌输规则部分独立可更新流程部分保持精简。5. 常见问题与排查技巧实录5.1 模板明明写了规则为什么还是被无视这个问题几乎每个人都会遇到。我排查时第一步是确认“规则是不是在有效位置”。如果规则写在模板文件的末尾或者混在示例代码之后很容易被后来的内容冲淡。Claude Code 本身有比较强的“最近信息优先”倾向所以核心规则必须放在首次指令的最前面。第二个原因是规则和数据混在一起。如果你在模板里写了一段示例代码然后要求“这是反例不要照着做”模型很可能会被示例带偏反而生成类似文本。解决方法是把反例放在最后并用清晰的“禁止”句式包裹。第三个原因更隐蔽规则和任务冲突。比如模板说“不要修改代码”但前面又说“如果有 bug请直接修复”模型在执行时就会产生摇摆最后随机选择一边。所以写模板时一定要检查规则之间有没有互相打架的表述。5.2 回复越来越长核心内容却越来越少Claude Code 在长对话中很容易出现“注水”现象。早期我的审查模板输出特别长每条问题都给大段说明review 变成了一篇论文真正需要改的反而被淹没。针对这个我做了两个调整。一是给输出格式加上强约束比如“每个问题描述不超过两行建议部分用简短代码展示”。二是增加“二次压缩环节”模板里写清楚审查完成后用三行以内总结最需要优先处理的三个问题。## 最终总结 只输出 3 个最需要人工关注的问题每行一个包含位置和一句话描述。这个“二次压缩”非常重要。它让模型在完成详细分析后做一个提炼动作相当于自己做了摘要。它比从一开始就要求“简短输出”更有效因为详细分析时模型信息更充足压缩出来的摘要也更有判断力。5.3 如何避免每次调用模板时重新读一遍项目这是我自己踩过最深的坑。早期每次启动 Claude Code 会话模板里都有一句“请先读取 package.json、README.md、src 目录结构”然后它会花很长时间探索项目前几分钟全在做无用功。后来我把探索结果收敛到CLAUDE.md里。第一次手动让它生成一份项目摘要之后每次会话启动时先把摘要注入它就不需要重复扫描。这个方法对大型项目尤其有效上下文占用从几万 token 降到了几十行响应速度提升非常明显。当然项目结构变化后摘要会过期所以还应该配套一个“重新生成摘要”的模板命令比如/refresh-context每周触发一次保证信息不过期。5.4 多人协同时模板风格无法统一一个人维护模板库最容易团队协作就会冒出各种问题。有人喜欢详细有人喜欢精简有人把自己的偏好写进公共模板结果所有人被影响。我建议把模板库分成“稳定区”和“试验区分支”稳定区的模板需要经过 review通过后才能合并进主分支。个人试验模板放在自己的分支或单独目录里不轻易影响别人。模板本身的可读性要纳入 code review 范围。看到语义不清的规则及时指出。同时CHANGELOG 要跟上。每次改规则哪怕只改半句话也记一笔写上为什么改。否则模板库几个月后没人知道当初某句约束的价值最后只能推倒重来。5.5 模板库自身的维护与边界最后说一点维护层面的经验。模板库和正式代码库一样也会腐化。一段时间不维护里面的技术栈描述过期了公共片段里的规范已经不符合新团队实践了继承下来的模板就反向变成“历史包袱”。我自己的节奏是每个月抽半天时间做一次“模板评审”。把高频命令调出来实际跑一遍看看输出质量有没有下降看看公共片段有没有冗余看看有没有哪些规则因为项目演进已经失去意义。这个习惯听起来很“过程化”但实际投入回报比很高因为一套高质量的模板库真的能撑起你一整年的 AI 辅助编程体验。其实维护模板库最大的心得就是别把它当成“一次性提示词收藏夹”。它更像一套不断进化的操作手册今天你写下的每一行约束都在替未来的自己省去一次即将发生的方向跑偏。我现在每次新建会话都从模板库出发代码质量的稳定性也肉眼可见地提高了。