1. 为什么要给 Claude Code 配一套模板集先说说我这段时间的实际感受。Claude Code 这东西能力确实强但如果不加约束地直接用你会发现它经常给你“自由发挥”出完全不符合项目预期的代码——注释风格乱、测试覆盖看心情、改一个文件顺手把无关地方也动一遍。这种问题不是模型能力不行而是你给的上下文和约束不够。我试过很多种方式去“调教它”最后发现最可靠的方案就是把它可能遇到的场景全部模板化让它在不同的工作节点自动加载对应的提示词模板。这就是我整理 claude-code-templates 这套模板集的初衷。它本质上不是一个复杂的框架也没有依赖任何第三方运行时就是一套适合 Claude Code 使用的提示词模板集合覆盖代码审查、需求拆解、测试生成、重构建议、技术方案设计这些高频工作。你把它放到项目里Claude Code 在启动时会自动读取相关配置在运行时按需调用这些模板输出就会稳定很多不需要你每次重复写一大段背景说明。适合谁来用呢说实话只要你日常在用 Claude Code 写代码、做 code review、或者让它辅助做技术方案这套东西就值得试一试。它不要求你会写复杂的配置核心只需要理解一个文件怎么写、模板是干什么的然后照葫芦画瓢往里面塞内容就够了。接下来我会把这套模板集的拆解思路、核心文件怎么写、实操示例、以及我踩过的坑全部展开说明你可以直接参考复现。2. 模板集的整体设计与工作逻辑2.1 Claude Code 的提示词机制与模板价值要理解模板集为什么有效得先清楚 Claude Code 的工作方式。它和普通的聊天式 AI 不同Claude Code 是在你的终端里运行的编码代理能直接读写项目文件、执行命令、调用各类工具这意味着它在运行过程中接收的信息量非常大除了你主动输入的内容还会同时看到整个项目的文件树、git 状态、编辑历史等上下文。这个特点既是优点也是挑战。优点是它能基于真实项目状态做判断不会凭空想象挑战是当上下文太杂的时候模型容易丢失重点。举个例子你让它“写一个用户登录的接口”它可能会参考项目里现有代码的风格但如果项目里同时存在老旧的 PHP 代码和新写的 TypeScript 模块它就不一定能准确判断该对齐哪个风格这时候模板的价值就体现出来了。模板本质上扮演的是一个“稳定的角色设定”和“输出约束器”。在提示词模板里预先写清楚项目的技术栈、代码规范、目录结构、设计偏好再把输出格式、审查重点、测试要求这类信息固化下来Claude Code 在这些约束下给出的结果就会稳定得多。你可以把模板理解成给模型戴了一副定制的眼镜让它只看该看的忽略不该看的。从项目结构上说一套完整的 claude-code-templates 通常包含三大块项目全局配置比如 CLAUDE.md、自定义命令提示词slash commands、技能文件skills。全局配置负责“它怎么看待这个项目”自定义命令负责“它怎么执行具体任务”技能文件负责“它如何完成某个专项工作”。三者各司其职构成了一个完整的模板体系。2.2 模板集的项目结构设计参考实际搭建模板集的时候不需要凭空发明一套复杂的层级我的建议是尽量跟随 Claude Code 官方兼容的约定来组织目录这样工具能直接识别维护起来也简单。一个比较理想的结构长这样claude-code-templates/ ├── CLAUDE.md # 项目级全局指令 ├── commands/ │ ├── review.md # 代码审查模板 │ ├── refractor.md # 重构建议模板 │ ├── test.md # 测试用例生成模板 │ └── plan.md # 需求拆解与技术方案模板 ├── skills/ │ ├── security-check/ │ │ ├── SKILL.md # 安全审查技能定义 │ │ └── checklist.py # 辅助脚本可选 │ └── api-design/ │ ├── SKILL.md # API 设计技能定义 │ └── examples/ └── hooks/ └── pre-commit.md # 提交前自动触发的检查模板这个结构里CLAUDE.md 是核心配置做的是全局约束commands 目录放的是你通过斜杠命令主动触发的模板skills 目录则更像是给 Claude Code 装备的一套专业技能包它能在合适的场景下自动被调用。hooks 目录是给一些自动化检查用的比如提交前自动跑一遍代码风格检查。理解这个结构的关键是要分清楚“全局配置”和“任务模板”的边界。全局配置解决的是模型的“人设”和“世界观”例如项目是什么技术栈、代码风格偏什么方向、有哪些目录是绝对不能动的任务模板解决的是“这一次工作要做到什么效果”例如这次 code review 要重点看并发安全问题还是只做 API 兼容性检查。把两者混在一起模板会变得非常臃肿而且不容易复用到其他项目。2.3 模板集在不同场景下的分工逻辑我整理了这段时间实战下来比较清晰的场景分工大致分成四类输入型任务、分析型任务、生成型任务、校验型任务。每类任务的模板写法差别很大需要有针对性地设计。输入型任务典型的是“需求拆解”它的核心目标是让用户提供的信息快速结构化。这种模板的写法偏提问式设计好固定的问题列表让 Claude Code 在接收需求后主动向用户确认关键信息例如目标用户是谁、验收标准是什么、有没有性能指标约束等。分析型任务典型的是代码审查和方案评估模板里应该写明审查维度、优先级顺序、输出格式让模型按既定路径分析而不是随机发挥。生成型任务典型的是代码生成和测试编写模板里应该包含强烈的输出格式约束例如必须在代码块内输出、必须包含哪些注释头、必须遵守哪些命名规范。校验型任务典型的是 git 提交信息规范化、代码风格检查模板要给出明确的通过标准和失败后的处理逻辑最好是能让 Claude Code 比较机械化地去执行。把这四类模板分开设计之后整体使用体验会提升非常明显。以前我经常遇到的一个问题是让 Claude Code 写测试的时候它一边写测试一边帮我把业务代码也重构了这让我非常恼火。后来我在测试生成模板里明确加上一条“只允许修改 test 目录下的文件禁止改动业务代码”这个问题就再也没出现过。3. 核心文件逐一拆解与写法详解3.1 CLAUDE.md全局上下文的定海神针CLAUDE.md 是整套模板集里最重要的一个文件没有之一。它是 Claude Code 每次启动时都会自动读取的项目描述文件相当于给 AI 的一份“入职手册”。它不需要特别长但信息密度要极高。我自己用的 CLAUDE.md 模板大致包含以下区块项目一句话简介让 AI 第一眼就知道这个项目是干什么的。不要小看这句话它直接影响后续所有判断的基座。技术栈清单列清楚后端语言、前端框架、数据库、ORM、构建工具等。写清楚版本号更好。目录结构说明不只画目录树还要说明哪些目录是核心业务、哪些是基础设施、哪些是生成代码千万别动。代码规范摘要缩进几个空格、单引号还是双引号、命名用 camelCase 还是 snake_case、提交信息格式要求。常用命令清单怎么跑测试、怎么启动开发环境、怎么构建、怎么 lint。Claude Code 在执行任务时会频繁使用这些命令。避免事项列表例如“严禁自动安装新依赖”、“严禁修改 migrations 目录”、“不要在未经确认时执行删除操作”。这么写的理由很简单Claude Code 每次输出代码和方案前会基于项目上下文做自洽分析如果上下文里有明确规范它遵循规范的概率会大幅提升。以前我经常碰到它生成的代码混用两种 quote 风格后来在 CLAUDE.md 里写死“一律使用单引号JSX 属性使用双引号”这个问题就基本绝迹了。这里有一个非常重要的实操细节CLAUDE.md 不要写情绪化的表达也不要写一堆空话。比较无语的写法是“请提供高质量的代码确保代码健壮性和可维护性”——这种话模型听了跟没听一样因为缺少可执行的标准。“高质量”是什么衡量标准是测试覆盖率 90% 还是通过 lint模板写作要做的是把抽象形容词翻译成具体规则。打个比方你带新人进组光说“你干活要认真一点”是没用的你得说“提交代码前必须跑一遍npm run lint npm test全部通过才能提 MR”。CLAUDE.md 的写法就是这个逻辑。3.2 commands 模板让每个任务都有章可循commands 目录下的模板对应的是 Claude Code 里可执行的具体任务。每个模板文件就是一次任务的完整提示词头部通常会写元信息来描述用途和参数正文部分定义任务目标、执行步骤、输出格式。举一个最简单的代码审查模板的例子我实际在用的模板结构大致是这样的--- name: review description: 对指定范围内的代码进行全面审查输出问题清单和修复建议 argument_hint: 可选指定审查范围例如 src/utils 或 file1.ts file2.ts --- 你是一名资深代码审查专家正在对项目的代码进行审查。 审查范围{{argument}}如果未指定则审查当前分支相对于 main 分支的全部变更。 请按以下维度依次审查 1. 正确性是否存在明显的逻辑错误、边界条件遗漏 2. 并发安全涉及共享状态时是否有竞态条件 3. 性能是否存在可避免的重复计算、不合理的 N1 查询 4. 可维护性命名是否清晰、函数是否过长、是否有重复代码 5. 安全是否可能引入 XSS、注入等问题 输出格式要求 - 按“问题严重级别Critical/Major/Minor→ 问题描述 → 文件位置 → 修复建议”的结构输出 - 每个问题一行层级不要嵌套太深 - 修复建议必须给出可执行的伪代码或思路不能只说“需要优化” - 如果没有发现问题请明确输出“未发现问题”不要强行凑数这个模板的实际效果是把审查的维度固化成清单Claude Code 按清单逐项扫描输出结果结构统一。以前没有模板时同样的审查请求它可能重点看代码风格也可能重点看算法性能全看心态。用了模板后输出的问题列表稳定而有序我再配合项目里的自动化工具就能快速处理。这种模板设计的核心原则是“把步骤写进提示词”。你不需要让模型去猜应该怎么做而是把资深工程师的做法直接拆解成步骤让它照着做。你越是能详细描述任务的处理流程输出质量就越稳定。命令模板之间还可以互相组合调用比如重构模板执行完后自动调用测试模板或者代码生成完后自动调用审查模板。这个在 Claude Code 的自定义 agent 流程里能做稍后我展开说。3.3 skills 技能文件精细化场景能力的封装skills 目录的设计思路和 commands 有一点相似但更偏“能力注入”而不是“任务下发”。一个 skill 通常包含一个 SKILL.md 文件里面描述的是该技能针对的场景、使用的方法论、以及需要遵守的流程。举例来说我写了一个“安全审查”技能它的 SKILL.md 开头是这样--- name: security-check description: 对 Python Web 项目的常见安全风险点进行深度检查 --- 当需要审查代码安全风险时请激活该技能。 核心检查面 - 身份认证与会话管理是否存在硬编码凭据、会话固定、弱口令逻辑 - 输入校验是否存在 SQL 注入、命令注入、路径穿越风险 - 数据保护敏感数据是否加密存储、日志是否泄露敏感信息 - 依赖安全是否存在已知漏洞的依赖版本 - 业务逻辑越权操作、水平权限提升、支付金额篡改等场景 每项检查需要说明风险等级、触发条件、修复方案。 禁止在未实际执行 grep 或读取文件的情况下凭空报告风险。这个技能文件的作用是当 Claude Code 在执行其他任务过程中发现涉及安全相关操作时可以自动激活该技能框架使它的判断维度更加完善。技能文件的写法比命令模板更加骨架化不需要按步骤执行更像是一套“思维框架”的注入。在我的实践中把命令和技能分开管理能显著降低维护成本。命令模板强调的是“做什么事、按什么步骤做”技能文件强调的是“面对某一类问题应该用哪些维度想”。前者像菜谱后者像营养学常识——一个管过程一个管认知。4. 实操过程与关键环节实现4.1 从现有项目起步的迁移流程我最初并不是从零搭建这套模板的而是从一个已经跑了很久的项目开始的。直接在一个成熟的、代码量很大的项目里引入模板集是需要谨慎操作的因为 Claude Code 的行为变化会直接影响到正在进行的开发工作。我的建议流程是这样的先在本地建一个新分支把模板集的三个核心文件放入项目跑一遍现有测试确保模板本身没有破坏代码。然后逐步引入 commands而不是一次性全量铺开。例如第一周只引入 review 命令让代码审查结果出来和同事的 review 意见做对比看是否靠谱第二周引入 test 命令对比其生成的测试和手工编写的测试之间的覆盖率差异。这种渐进式迁移的最大好处是每一次变更都可以度量和回滚。在迁移中我需要特别强调 CLAUDE.md 的引入顺序。如果你没有在 CLAUDE.md 里写清楚“禁止自动安装依赖”Claude Code 很可能会在你让它写一个缺失的库时自动执行安装命令而这种行为在真实项目中是非常危险的。在这套模板集里我默认在 CLAUDE.md 中加入这样一条规则任何安装依赖或修改依赖配置的行为都必须先征求用户确认。这不算保险丝但至少让它有了一个刹车机制。还有一个小技巧是用环境变量区分开发环境和生产环境下的模板行为。Claude Code 支持在配置里读取系统环境变量这样你可以在一套模板集里定义两种行为比如本机调试时允许自动执行命令在 CI 环境里则强制所有写入操作前先输出 diff。4.2 模板中参数与动态变量的高级用法写模板时不光要写固定文本还要善于利用 Claude Code 支持的动态参数。前面说到的{{argument}}就是命令模板的内置参数你还可以自定义变量组合来扩展动态行为。举个例子设计一个测试生成模板我希望它能接受一个参数来指定测试类型比如 unit 或 integration不同测试类型关注点完全不同。模板可以这样设计--- name: test description: 为指定模块生成测试用例 argument_hint: 测试类型: unit | integration模块路径或文件名 --- 测试类型{{argument}} - 如果参数包含 unit则按单元测试规范生成mock 所有外部依赖、聚焦单函数逻辑、断言输出。 - 如果参数包含 integration则按集成测试规范生成连接测试数据库、关注接口间协作、验证数据流转。 - 如果参数什么都没说默认按 unit 处理。 测试文件命名规则与目标文件同目录命名为 {文件名}.test.tsTypeScript 项目或 {文件名}_test.pyPython 项目。 生成完成后输出一份覆盖率预估说明列出哪些分支暂时未覆盖。参数化之后你不需要为每种测试类型各写一个模板一份模板就能按需自适应。这种写法对日常效率的提升是很明显的因为大量任务中间的差异其实只是一个变量而不是整个逻辑流程都不同。深度实操建议是不要只把参数当成一个“字符串透传”来用而是让模板根据参数的值改写执行步骤。因为 Claude Code 本身是有推理能力的你只需要在模板里设定条件分支它会自动选择合适的逻辑路径。这样做出来的模板灵活性远超简单填空。4.3 用模板组合搭建自动化工作流前面提过命令之间可以互相调用这块我展开讲一个我实际在生产中用的工作流开发一个新功能并准备提 MR 时的完整流程。我在 commands 目录下建了一个feature-flow.md命令模板它的执行步骤是分析用户给出的需求描述在docs/下生成一篇简化的技术设计文档包含目标、接口变更、数据模型变更、风险分析四块内容。根据设计文档生成核心业务代码同时只修改与需求相关的文件。调用 test 命令为新增代码生成对应测试。运行测试命令确认全部通过。调用 review 命令对全部变更执行一次快速自审。整理变更涉及的文件清单输出 git commit message 建议。这样做下来从需求到提交概览的整个链条被模板完整串起来了。实际跑一次的效果在简单需求上大概能省掉 30 到 40 分钟的手工整理时间在复杂需求上至少省一小时。需要注意的一点是模板串联多个步骤时要在模板里清晰地定义每一步输出的传递方式比如第一步生成的设计文档在第二步中通过读取文件来获取而不是靠模型记忆上下文。Claude Code 的上下文窗口虽然不小但让模型去记忆跨步骤的中间结果远不如让它显式读文件来得可靠。4.4 模板调试与效果验证的标准路径写模板不是一遍就成功需要不断调试。我的调试方法分三步。第一步是语法与加载检查确认模板文件能被正确加载命令能够正常出现在命令列表里。第二步是功能验证拿一个典型场景去测试模板执行一次的完整输出看输出的格式是否符合预期、是否执行了所有预设步骤。第三步是边界测试构造一些特殊输入例如空参数输入、异常格式输入看模板是否还能保持稳定。这个步骤最容易被忽略但恰恰是模板质量的分水岭。我举一个真实的调试经历。早期我在 review 模板里加了一条“输出问题时按严重级别排序”结果实际使用时发现模型经常把所有问题都标成 Minor因为它倾向于弱化问题严重性。调试之后我在模板里加入了对各级别的量化定义“Critical 指会导致程序崩溃、数据丢失或安全漏洞的问题Major 指功能不符合预期但无崩溃风险的问题Minor 指代码风格、可读性等不直接影响功能的问题。”加了量化定义之后级别判断准确率提升非常明显。这件事给我的经验是给模型明确的尺子比让它自由裁量要靠谱得多。5. 常见问题与实战避坑记录5.1 模板写了很多但 Claude Code 行为变化不大这个坑我最初踩过。花了一下午精心设计了一套模板结果运行时发现模型输出还是老样子。仔细排查后发现问题出在模板加载机制上CLAUDE.md 是自动加载的但 commands 目录下的模板需要被主动调用才会生效而 skills 目录的技能文件则需要满足特定触发条件才会参与推理。如果你的模板没生效先检查是不是把这个顺序搞混了。另外还有一层Claude Code 有自己内置的系统提示词你在模板里写的规则如果和系统提示词冲突模型通常会倾向于遵循系统提示词。应对办法不是去对抗而是把模板里的规则写得更加具体和操作化用“什么时候做什么事”的句式替代“不要做什么事”的句式。例如“不要使用双引号”就不如“字符串变量声明一律使用单引号”有效因为后者的约束更直接、更容易被执行。还有一个常见问题是模板文件头部的元信息格式不对导致命令根本没被注册。具体格式要求可以对照官方文档检查常见错误是漏了name字段或description字段或者argument_hint的写法不规范。这类问题通常没有任何报错只是命令静默消失所以排查起来比较隐蔽。5.2 模板过于复杂导致输出稳定性反而下降另一个极端是模板写了一堆内容结果模型每次输出都在不同位置偏移。这个现象的背景是提示词里的信息越多模型越难精准定位重点。尤其是把全局约束、任务目标、输出格式、示例、强调事项全部塞进一个命令模板时效果反而变差。我的实践结论是单个命令模板控制在 300 到 600 字之间最合适。超出这个范围就要考虑拆解把“背景信息”移到 CLAUDE.md“操作等级约束”移到 skills 文件“流程定义”留在 commands 里。层次清晰了模型才能精准拿捏不同提示词的作用域。这个字数是基于大量实测得出的经验值不一定适合所有人但至少可以作为调整的起点。另外模板中不要堆太多“同义反复”的强调词。例如你看了一些模板会写“必须”、“严格必须”、“绝对必须”这种语气词实际上对模型来说这些语气词几乎不贡献约束力徒增噪音。与其说三遍“必须写测试”不如写清楚“测试文件需覆盖新增函数的正常路径和异常路径两个分支”。5.3 动态参数解析异常或不稳定{{argument}}参数解析的问题最常见的是参数中包含空格、引号、中文逗号等特殊字符导致模型错误拆分参数。比如你输入unit, src/utils/date.ts模型可能把整个字符串当成一个参数或者拆分成unit, src/utils/date.ts两个。这会让模板里的条件判断走向完全不同的路径。我的办法是约定参数分隔符在项目文档里明确说明“传多个参数时用英文逗号和空格分隔参数内不要包含逗号”。同时模板里也可以加上容错逻辑“如果参数中包含多个路径尝试按空格或逗号拆分并分别处理”。当然这个策略不是万无一失所以在重要任务执行前我会先让 Claude Code 输出一下它对参数的理解确认无误后再进入下一步。5.4 模板更新后旧行为失效的排查思路当你修改了一个模板发现 Claude Code 的表现和之前不同有时候是预期内改变有时候是意外回归。要快速定位差异最直接的做法是维护一份变更记录。我每次调整模板都会在 git commit message 里标注“prompt: review 模板新增并发检查维度”这样后续查找历史时能快速锁定某次行为变化对应的改动点。另外建议每次只改一个变量。很多人喜欢一次性调整多个模板结果出问题后完全无法判断是哪个改动导致的。保持单一变量调整配合 git diff 快速对比排查效率会高很多。这一点其实和排查普通代码问题的思路完全一致只是在提示词调试里更容易被忽视。6. 模板集的进阶方向与个人经验总结6.1 让模板具备跨项目复用能力模板集做到一定程度后你一定会遇到跨项目复用的问题。不同项目的技术栈和代码风格差异会让一套模板无法完全适应所有项目。我的做法是把模板分层第一层是通用模板不涉及任何具体技术栈例如需求拆解、方案评审第二层是技术栈模板例如针对后端项目的 SQL 审查模板、针对前端项目的组件规范模板第三层是项目专属模板包含特定业务逻辑相关的内容。项目初始化时从三个层级里按需组装而不是把全部模板都丢进去。这套思路有点像是把模板集做成了乐高积木而不是一个固定的模具。长期维护下来跨项目迁移的成本会越来越低因为你只需要替换第二层和第三层第一层基本不用动。这也是为什么我建议在项目里把 CLAUDE.md、commands、skills 分开设计和存储混在一起以后拆分会非常痛苦。6.2 团队共享与协作中的模板规范如果你的团队一起使用 Claude Code模板集就应该纳入版本管理并且约定更新流程。强烈不建议每人在自己本地维护一套模板否则行为差异会让团队协作变得混乱。我的建议是在仓库根目录维护模板集通过 MR 流程更新每次更新附上示例输出差异让其他成员知道行为发生了什么变化。团队共享模板还有一个要注意的事情模板里的措辞要保持中立和可理解。同一个提示词不同人的理解会不同所以模板中尽量使用可验证的操作描述而不是依赖阅读者“共情”。比如你可以写“生成测试时新测试必须实际执行一次不能只生成代码”但不能写“认真对待测试工作确保测试闭环”。前者是可验证的后者是空话。Claude Code 对这两类描述的执行效果差别是非常明显的。6.3 我实际使用中几条最重要的心得最后分享几条我在这段时间使用模板集过程中沉淀下来的心得不算全面但每条都是踩过坑换来的。第一条模板的本质是“复制资深工程师的思路”而不是“写一篇更长的提示词”。你写模板时要时刻问自己一个懂行的同事接手这个任务他第一步做什么、关注什么、用什么标准判断成果把这些回答变成模板质量自然就上来了。第二条模板需要持续维护它的时效性很短。技术栈升级、工程规范调整、团队成员变化都会让旧模板不再适用。我基本每两周会抽半小时过一遍现有模板删除失效的规则、补充新的场景。第三条模板的最终价值是省心而不是炫技。不要为了把提示词写长写花而加内容要时刻警惕维护成本是否大于收益。现在这版 claude-code-templates 在我这边已经稳定跑了挺长时间覆盖从需求到交付的主要代码工作流。它不是什么惊天动地的工程但确实让我和 Claude Code 的协作变得顺手了很多。如果你是刚开始尝试建议别贪多先写好一个 CLAUDE.md 加一个最常用的命令模板比如代码审查跑上两周感受变化再决定要不要扩展。这套东西的投入产出比非常高真正试过之后你会回来感谢自己把模板这件事认真做了。