我从 2024 年底开始认真研究 Claude Code最初只是把它当成一个“能看懂代码的终端助手”后来发现真正拉开效率差距的并不是模型本身有多聪明而是你有没有给它一套足够稳定的工作框架。这套框架如果沉淀成文件就成了标题里说的claude-code-templates——一堆可以被重复加载的指令、流程和规则模板。这个仓库解决的实际问题很具体怎么让 Claude Code 在生成代码、审查代码、写提交信息时不跑偏不自由发挥不浪费时间在无意义的探索上。它适合已经在用 Claude Code 但觉得输出不稳定的人也适合准备把 AI 编码助手引入团队工作流的技术负责人。这篇文章就把我设计和维护这套模板的全过程拆开讲一遍包括目录结构、核心写法、测试方法和踩过的坑。1. 先搞清楚Claude Code 模板到底在解决什么问题很多人第一次接触模板会把它等同于“一段长 Prompt 存成文件”这个理解不算错但维度太低了。我在实际使用中发现单独的提示词很难同时控制 Claude Code 的思考路径、输出格式和行动边界尤其当任务变复杂以后模型很容易在上下文里迷失最终给出一份看起来合理但没法落地的结果。模板的真正价值是把“一次性对话经验”转成“可重复执行的流程协议”。1.1 模板不是提示词它是“工作流的容器”我把模板拆成三个层次对应 Claude Code 的三个原生机制指令层通过CLAUDE.md告诉模型“在这个项目里什么能做、什么不能做”。比如我们团队约定“所有异步逻辑必须显式处理错误”这条规则写进项目级CLAUDE.md后每次对话都会生效。流程层通过.claude/skills/目录下的SKILL.md文件把一类任务拆成固定的操作步骤。比如“代码审查”技能规定必须先读 diff再逐项检查安全、性能、可维护性最后按固定格式输出报告。约束层通过自定义 Agent 定义文件把边界条件写死。比如审查 Agent 只负责审查逻辑不负责重构不越权修改代码。这三层由文件系统组织起来互相配合才算得上一个真正意义上的模板。单独抽出来任何一个文件效果都会大打折扣。这也是我不建议直接从网上复制一段 Prompt 就当模板用的原因——一段话没有文件结构支撑很难在不同项目里稳定复现。1.2 我的仓库里到底放了哪些东西我维护的这套模板库目录结构是长这样的claude-code-templates/ ├── CLAUDE.md # 项目级行为基线 ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── review_rating.py │ ├── sql-migrate/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── example.md │ └── docs-writer/ │ ├── SKILL.md │ └── style-guide.md ├── agents/ │ ├── code-reviewer.json │ └── test-planner.json ├── prompts/ │ ├── component-generator.md │ └── refactor-plan.md └── scripts/ └── render_template.shCLAUDE.md是总入口定义所有任务默认遵守的规则。skills/下每一个子目录是一个技能包技能包的核心是SKILL.md里面通过 frontmatter 写名称和描述词正文写任务流程和输出标准。agents/下的 JSON 文件则用来定义更细粒度的子 Agent这些 Agent 可以被主对话按需调用。prompts/存放给用户直接启用的长模板通常是跨项目通用的大任务比如“生成一个带单元测试的 React 组件”“制定一个重构计划”。每个人情况不同但我的基本判断是如果你只维护一个CLAUDE.md那只能叫备忘单只有把常用任务拆成可复用技能才算真正进入模板化的工作模式。1.3 模板能解决的实际问题我在团队里和社区里观察到用 Claude Code 的人通常会遇到这么几类问题而这些问题靠模板都能得到明显缓解输出不稳定同一个问题问三次得到三种不同风格的答案模板固定了输出结构和代码规范稳定性主要靠约束。上下文被冲散长会话里模型容易忘掉前几轮的关键结论模板通过固定的流程节点强制模型复述关键信息。新人不友好团队引入 AI 助手后每个人都用自己的方式提问效果参差不齐模板相当于给了一个标准操作手册。规范不落地代码规范写在飞书文档里没人看但把它提炼进CLAUDE.md和技能文件里AI 每次都会遵守。用一句话总结模板的本质是把隐性知识显式化然后交给 AI 去消费。这个过程中真正考验人的不是写提示词而是你能不能把团队的协作流程提炼成清晰的规则。2. 设计模板之前的三个关键判断很多人一上来就开始写文件结果就会写成一大堆形容词堆砌的“大而全文档”模型看到之后要么选择性忽略要么过度响应。我经过几轮重构以后慢慢总结出一个经验设计模板之前先想清楚三个问题比动手写更重要。2.1 模板是给 AI 看的但也要能让人读懂我知道这听起来像废话但这是最容易翻车的一点。你写的指令虽然最终消费者是 Claude但维护它的却是人而且人是优先级最高的消费者。如果一份SKILL.md写得像一份只有机器才能解析的配置文件那等到项目迭代、人员变动的时候根本没人敢碰它模板就会慢慢发霉。我自己的做法是模板文件里永远保留“给人类看”的章节放在最前面。比如每个技能文件开头有一段“这个技能什么时候该用、什么时候不该用”的说明后面的指令部分才是给 Claude 看的。这不只是文档洁癖还有实际作用——当模型在模糊场景下决定要不要调用技能时它也会参考这段说明因为说明里往往包含了任务类型的边界。具体到格式我习惯用表格维护“触发条件”和“不适用场景”。Claude Code 的技能匹配机制主要根据description字段来判断所以我会把 description 写得像搜索索引一样精准标题、动词、名词都指向任务本身避免模糊词。这一点在后面的测试章节里还会展开。2.2 输出格式的设计比提示语更重要我见过不少模板花了 80% 的篇幅反复强调“要高质量”“要专业”却没有定义到底什么算高质量。模型对形容词的理解是概率性的但对格式的理解却非常有确定性——所以聪明的做法是直接规定输出格式。拿代码审查技能举例我不会写“请认真检查代码质量”而是写输出必须包含以下四段 1. 结论摘要200字以内给出整体评价通过 / 有条件通过 / 不通过 2. 严重问题按 P0、P1、P2 分级列出必须标注文件路径和行号 3. 改进建议每条建议对应一段可执行的修改示例 4. 修改预估估算每个 P0/P1 问题需要花费的时间当模型看到这样明确的格式节点时它的注意力会天然被引导到各个维度上审查的标准化程度会直线上升。这个原理其实跟给人类新员工写任务书是一样的模糊的指令带来模糊的执行精确的流程框架带来稳定的结果。2.3 约束条件怎么定才不会力度过重模板刚开始写的时候我犯过一个大毛病什么都想约定。字体命名要规范、组件命名要规范、CSS 属性顺序要规范……结果模型每次生成代码都要思考一堆条条框框简单任务也变卡顿了反而影响效率。后来我才意识到约束的本质不是越多越好而是只对“容易犯错、且犯错成本高”的地方做限制。我现在的标准很简单一个领域最多三条硬规则。比如“数据库迁移模板”里我硬性规定“禁止使用DROP COLUMN必须通过新表 迁移脚本处理”“所有操作必须包装在事务里”“每个迁移文件必须有 rollback 语句”。这三条的共同点是违反任意一条都可能造成线上事故。至于表名用单数还是复数这种风格问题我反而不会写进模板让模型按上下文自由发挥就行。做减法这个原则不仅适用于规则条数也适用于模板整体长度。一个SKILL.md如果超过 80 行我就会怀疑它是不是拆得不够细。技能应该像 Unix 工具一样一件事做到极致而不是一个全家桶。3. 落地实现目录结构、文件写法与迭代节奏上面讲的是方法论这一章进入实操。我尽量按我实际创建这套模板的顺序来写这样如果你是新手也能照着一路做下来。3.1 物理结构CLAUDE.md、Skills、Agents 的配合方式先说全局入口。项目根目录的CLAUDE.md我建议写得短一点只放所有人都必须遵守的规则。不要在里面塞具体任务的步骤否则每次对话都会加载大量无关内容既费资源又干扰判断。我的CLAUDE.md核心部分大概长这样# Project Guidelines ## 通用规则 - 在修改代码前先说明你的修改计划等待确认后再动手。 - 所有新增代码必须附带单元测试。 - 变更任何公共 API 时必须同步更新对应的文档文件。 ## 代码风格 - 遵循项目现有风格不自行引入新的模式。 - TypeScript 项目中禁止使用 any。这里每一项都是好几轮迭代后留下来的。以前我写了很多“提倡使用函数式编程风格”之类的软性建议后来发现模型不一定能理解“风格”这个词的边界反而容易产生破坏性重构于是全部删掉只保留可验证的硬规则。skills/目录则是按任务维度组织的。每个技能是一个文件夹核心是SKILL.md。一个最小可用的SKILL.md结构分为三块frontmatter元信息、instruction给模型的指令、resources附带参考文件。frontmatter 里最关键的是description它决定了模型什么时候会自动调用这个技能。我对比过不同写法发现用“当用户要求 xxx 时使用”这种句式明确度最高比“用于处理 xxx 任务”更直接。agents/目录下放子 Agent 的 JSON 定义。它的作用和技能又不一样技能偏向“怎么干事”Agent 偏向“雇佣谁干事”。比如我定义了一个code-reviewerAgent它就具备独立的系统提示词、工具列表和输出偏好主对话可以根据任务难度决定是否调用它。这样做的好处是审查逻辑不会把主对话的上下文撑爆。3.2 手把手写一个代码审查模板我觉得最好的教学方式就是完整走一遍我写“代码审查”技能的过程。这个技能在所有模板库中使用频率最高也最能体现结构化思维的好处。第一步确定触发条件和描述词。我在SKILL.md的 frontmatter 里写--- name: code-review description: 当用户要求审查代码质量、优化建议或提交 Pull Request 审查时使用。适用于 diff 分析、安全性检查、性能优化和可维护性评估。 ---第二步写执行流程。执行流程不能太跳跃否则模型会漏掉步骤。我分成了固定的五个子步骤要求模型必须按顺序执行并在输出中标注每个步骤的完成状态读取目标代码和 diff。定位变更影响范围包括被调用的函数、依赖方。按安全、性能、可维护性、测试覆盖四个维度逐项检查。汇总问题清单并按 P0/P1/P2 分级。生成最终审查报告。第三步规定输出格式。前面已经说过格式比形容词重要。我在模板里直接给出 Markdown 结构甚至给出了评分示例。这样模型输出的报告可以直接贴到代码合并请求里不用再二次整理。这个模板我当时花了大概一个晚上写完本来以为很完美结果测试的时候发现模型经常在“影响范围”这一步偷懒给出的分析明显是基于猜测而不是实际读取代码。后来我在流程里加了一条硬性要求“在输出影响范围之前必须先逐行列出你阅读过的文件列表并给出阅读顺序。”加了这条后模型会真的去执行工具调用而不是编个大概。3.3 参数化与复用让模板像函数一样被调用模板变成资产之后必然会遇到一个需求同样一个模板在不同项目里要替换项目名、代码风格、目录结构等变量。如果一个一个复制修改维护成本会很重。我的做法是用一个简单的 Shell 渲染脚本来处理占位符。比如模板里写项目名{{PROJECT_NAME}} 代码路径{{SRC_DIR}} 测试命令{{TEST_COMMAND}}然后调用scripts/render_template.sh传入参数./render_template.sh templates/refactor-plan.md \ -p PROJECT_NAMEmy-api \ -p SRC_DIRpackages/api/src \ -p TEST_COMMANDpnpm --filter api test脚本本质就是sed替换没用什么高级技术但效果非常好。团队里任何成员都可以通过统一命令生成项目定制的模板文件再配合 Git 分支管理做到“模板库升级项目内定制文件不冲突”。这种“模板 渲染参数”的思路其实来源于一个很朴素的想法模板不该是死的文件而应该像函数一样有入参、有出参。入参是项目和任务的上下文出参是给 Claude Code 加载的指令文件。这样结束后整个体系就具备可组合性了。4. 模板测试方法论怎么验证它真的有效很多人在写完模板之后就默认它生效了这是我见过的最大误区。模板是典型的“写起来简单测起来复杂”的东西看起来有逻辑实际跑起来可能处处有意外。我后来形成了一套固定的测试流程每次给模板库打 Tag 之前都要完整跑一遍。4.1 先跑最小可复现案例给新模板写一个最小测试用例通常是公开仓库里的一段代表性代码。比如测试“代码审查”模板我会拿一个只有一个文件、包含 3~4 个明显问题的示例仓库来跑问题包括一个未处理异常、一个硬编码密、一个多余循环。如果模板连这种简单场景都不能稳定发现问题那就不必浪费精力去跑真实项目了。这里的“稳定”很关键。我会把同一个案例连跑三次确认每次都输出相同的问题集。如果不稳定说明模板流程的约束力不够——大概率是步骤之间出现了模糊地带比如“检查可维护性”这一步没有给出判断标准模型就自由发挥了。建议在测试时固定模型温度参数至少在 Claude Code 配置里把随机性调到低档这样能区分是模板问题还是模型随机性导致的波动。4.2 用边界情况攻击模板过了最小案例后我会故意做一些让模板“难受”的输入比如空目录、超长文件、全是 TODO 注释的伪代码、混合多种语言的仓库。这些边界情况往往能暴露模板里过于刚性的假设。举一个真实例子我的“SQL 迁移”模板最初假定所有迁移脚本都放在migrations/目录下结果有一次测试时放在db/scripts/里模板立刻判断错误以为项目没有迁移记录差点生成重复的初始化脚本。后来我在模板里加了一个探测步骤先扫描目录结构如果找不到标准路径就主动询问用户而不是直接按默认路径执行。边界测试的本质是检查模板是否具备“失败反馈”能力。一份好的模板在遇到无法处理的情况时应该明确说出来“这里我判断不了需要补充信息”而不是硬着头皮瞎猜。4.3 把模板从个人体验固化成团队资产单人验证和团队推广之间还有一道鸿沟。今年我把这套模板引入到团队后发现每个人对模板的期望不一样有人觉得审查模板太严格有人觉得生成模板太啰嗦。后来我建立了一个简单的反馈机制每个模板文件头部放了一段维护记录模板从 v1.0 升到 v2.0 时写清楚改动原因所有改动经过至少两次代码审查再合入主分支。同时我强烈建议在模板库里单独建一个examples/目录每个模板附带一个标准输出样例。团队成员看着样例就能理解模板意图也方便测试时对比模型输出。这个目录到现在仍然是我认为投入产出比最高的部分。5. 踩坑实录与排查技巧最后一部分我写几个自己反复踩坑后总结出来的排查思路都是文档里不会写的东西希望对你有实际帮助。5.1 模板正在“污染”上下文还不知道有一次我把所有能想到的规则都塞进CLAUDE.md结果模型每次处理任务都变得很迟钝而且很多指令之间互相冲突。比如我既写了“代码尽量简短”又写了“必须详尽注释”模型就开始精神分裂。排查之后才发现模板不是越多越好长上下文不但占用模型容量还会放大指令之间的冲突概率。现在我给自己定了个指标CLAUDE.md不超过 30 行单个技能文件不超过 80 行。超过这个量就必须拆分子任务而不是靠堆字数。上下文空间非常宝贵与其让它浪费在冗余指令上不如用来容纳真实的代码结构。5.2 模板太抽象还是太死板需要找平衡这类问题在技能描述里尤其明显。写太抽象比如“审查代码质量”模型不知道该不该调用写太具体比如“当用户输入 xxx 文件路径时使用”模型在其他场景下就又想不起来。我最后的解法是描述词里同时包含本地触发词和语义触发词例如“当用户要求审查代码、优化建议或提到 Pull Request 时使用”这样既能捕获明确请求也能覆盖间接表达。如果遇到模板经常被跳过或误调用第一个排查项一定是 description 写得太窄或太宽而不是模型“太笨”。我在迭代中反复验证过修改描述词对命中率的提升比修改正文指令还明显。5.3 关于凭证、安全和协作的几个提醒模板库里最容易出事故的是含路径、Token、内网地址等信息的配置。我强烈建议所有模板文件都通过环境变量注入敏感信息不要直接把真实值写进示例。渲染脚本里我已经做了脱敏处理遇到{{ENV_KEY}}这种占位符会优先从环境读取。还有一个容易忽略的点模板语法要区分 Markdown 和纯文本。Claude Code 的原生技能配置文件里支持 Markdown但如果你用渲染脚本生成最好统一输出纯文本否则夹杂特殊符号会导致模型理解混乱。最后想分享一个很私人的习惯我把模板库当成一个持续演化的代码项目来维护每个模板都有版本记录、测试文件夹和变更日志。这听起来很工程化但正是这种“把提示词当代码管理”的态度才让整套模板从一次性脚本变成团队可持续复用的基础设施。如果你也想做一套自己的claude-code-templates我建议从最小面积极小的一个任务开始跑通后再逐步加料——模板不是写出来的是用出来的。
Claude Code模板设计：从提示词到可复用工作流
我从 2024 年底开始认真研究 Claude Code最初只是把它当成一个“能看懂代码的终端助手”后来发现真正拉开效率差距的并不是模型本身有多聪明而是你有没有给它一套足够稳定的工作框架。这套框架如果沉淀成文件就成了标题里说的claude-code-templates——一堆可以被重复加载的指令、流程和规则模板。这个仓库解决的实际问题很具体怎么让 Claude Code 在生成代码、审查代码、写提交信息时不跑偏不自由发挥不浪费时间在无意义的探索上。它适合已经在用 Claude Code 但觉得输出不稳定的人也适合准备把 AI 编码助手引入团队工作流的技术负责人。这篇文章就把我设计和维护这套模板的全过程拆开讲一遍包括目录结构、核心写法、测试方法和踩过的坑。1. 先搞清楚Claude Code 模板到底在解决什么问题很多人第一次接触模板会把它等同于“一段长 Prompt 存成文件”这个理解不算错但维度太低了。我在实际使用中发现单独的提示词很难同时控制 Claude Code 的思考路径、输出格式和行动边界尤其当任务变复杂以后模型很容易在上下文里迷失最终给出一份看起来合理但没法落地的结果。模板的真正价值是把“一次性对话经验”转成“可重复执行的流程协议”。1.1 模板不是提示词它是“工作流的容器”我把模板拆成三个层次对应 Claude Code 的三个原生机制指令层通过CLAUDE.md告诉模型“在这个项目里什么能做、什么不能做”。比如我们团队约定“所有异步逻辑必须显式处理错误”这条规则写进项目级CLAUDE.md后每次对话都会生效。流程层通过.claude/skills/目录下的SKILL.md文件把一类任务拆成固定的操作步骤。比如“代码审查”技能规定必须先读 diff再逐项检查安全、性能、可维护性最后按固定格式输出报告。约束层通过自定义 Agent 定义文件把边界条件写死。比如审查 Agent 只负责审查逻辑不负责重构不越权修改代码。这三层由文件系统组织起来互相配合才算得上一个真正意义上的模板。单独抽出来任何一个文件效果都会大打折扣。这也是我不建议直接从网上复制一段 Prompt 就当模板用的原因——一段话没有文件结构支撑很难在不同项目里稳定复现。1.2 我的仓库里到底放了哪些东西我维护的这套模板库目录结构是长这样的claude-code-templates/ ├── CLAUDE.md # 项目级行为基线 ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── review_rating.py │ ├── sql-migrate/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── example.md │ └── docs-writer/ │ ├── SKILL.md │ └── style-guide.md ├── agents/ │ ├── code-reviewer.json │ └── test-planner.json ├── prompts/ │ ├── component-generator.md │ └── refactor-plan.md └── scripts/ └── render_template.shCLAUDE.md是总入口定义所有任务默认遵守的规则。skills/下每一个子目录是一个技能包技能包的核心是SKILL.md里面通过 frontmatter 写名称和描述词正文写任务流程和输出标准。agents/下的 JSON 文件则用来定义更细粒度的子 Agent这些 Agent 可以被主对话按需调用。prompts/存放给用户直接启用的长模板通常是跨项目通用的大任务比如“生成一个带单元测试的 React 组件”“制定一个重构计划”。每个人情况不同但我的基本判断是如果你只维护一个CLAUDE.md那只能叫备忘单只有把常用任务拆成可复用技能才算真正进入模板化的工作模式。1.3 模板能解决的实际问题我在团队里和社区里观察到用 Claude Code 的人通常会遇到这么几类问题而这些问题靠模板都能得到明显缓解输出不稳定同一个问题问三次得到三种不同风格的答案模板固定了输出结构和代码规范稳定性主要靠约束。上下文被冲散长会话里模型容易忘掉前几轮的关键结论模板通过固定的流程节点强制模型复述关键信息。新人不友好团队引入 AI 助手后每个人都用自己的方式提问效果参差不齐模板相当于给了一个标准操作手册。规范不落地代码规范写在飞书文档里没人看但把它提炼进CLAUDE.md和技能文件里AI 每次都会遵守。用一句话总结模板的本质是把隐性知识显式化然后交给 AI 去消费。这个过程中真正考验人的不是写提示词而是你能不能把团队的协作流程提炼成清晰的规则。2. 设计模板之前的三个关键判断很多人一上来就开始写文件结果就会写成一大堆形容词堆砌的“大而全文档”模型看到之后要么选择性忽略要么过度响应。我经过几轮重构以后慢慢总结出一个经验设计模板之前先想清楚三个问题比动手写更重要。2.1 模板是给 AI 看的但也要能让人读懂我知道这听起来像废话但这是最容易翻车的一点。你写的指令虽然最终消费者是 Claude但维护它的却是人而且人是优先级最高的消费者。如果一份SKILL.md写得像一份只有机器才能解析的配置文件那等到项目迭代、人员变动的时候根本没人敢碰它模板就会慢慢发霉。我自己的做法是模板文件里永远保留“给人类看”的章节放在最前面。比如每个技能文件开头有一段“这个技能什么时候该用、什么时候不该用”的说明后面的指令部分才是给 Claude 看的。这不只是文档洁癖还有实际作用——当模型在模糊场景下决定要不要调用技能时它也会参考这段说明因为说明里往往包含了任务类型的边界。具体到格式我习惯用表格维护“触发条件”和“不适用场景”。Claude Code 的技能匹配机制主要根据description字段来判断所以我会把 description 写得像搜索索引一样精准标题、动词、名词都指向任务本身避免模糊词。这一点在后面的测试章节里还会展开。2.2 输出格式的设计比提示语更重要我见过不少模板花了 80% 的篇幅反复强调“要高质量”“要专业”却没有定义到底什么算高质量。模型对形容词的理解是概率性的但对格式的理解却非常有确定性——所以聪明的做法是直接规定输出格式。拿代码审查技能举例我不会写“请认真检查代码质量”而是写输出必须包含以下四段 1. 结论摘要200字以内给出整体评价通过 / 有条件通过 / 不通过 2. 严重问题按 P0、P1、P2 分级列出必须标注文件路径和行号 3. 改进建议每条建议对应一段可执行的修改示例 4. 修改预估估算每个 P0/P1 问题需要花费的时间当模型看到这样明确的格式节点时它的注意力会天然被引导到各个维度上审查的标准化程度会直线上升。这个原理其实跟给人类新员工写任务书是一样的模糊的指令带来模糊的执行精确的流程框架带来稳定的结果。2.3 约束条件怎么定才不会力度过重模板刚开始写的时候我犯过一个大毛病什么都想约定。字体命名要规范、组件命名要规范、CSS 属性顺序要规范……结果模型每次生成代码都要思考一堆条条框框简单任务也变卡顿了反而影响效率。后来我才意识到约束的本质不是越多越好而是只对“容易犯错、且犯错成本高”的地方做限制。我现在的标准很简单一个领域最多三条硬规则。比如“数据库迁移模板”里我硬性规定“禁止使用DROP COLUMN必须通过新表 迁移脚本处理”“所有操作必须包装在事务里”“每个迁移文件必须有 rollback 语句”。这三条的共同点是违反任意一条都可能造成线上事故。至于表名用单数还是复数这种风格问题我反而不会写进模板让模型按上下文自由发挥就行。做减法这个原则不仅适用于规则条数也适用于模板整体长度。一个SKILL.md如果超过 80 行我就会怀疑它是不是拆得不够细。技能应该像 Unix 工具一样一件事做到极致而不是一个全家桶。3. 落地实现目录结构、文件写法与迭代节奏上面讲的是方法论这一章进入实操。我尽量按我实际创建这套模板的顺序来写这样如果你是新手也能照着一路做下来。3.1 物理结构CLAUDE.md、Skills、Agents 的配合方式先说全局入口。项目根目录的CLAUDE.md我建议写得短一点只放所有人都必须遵守的规则。不要在里面塞具体任务的步骤否则每次对话都会加载大量无关内容既费资源又干扰判断。我的CLAUDE.md核心部分大概长这样# Project Guidelines ## 通用规则 - 在修改代码前先说明你的修改计划等待确认后再动手。 - 所有新增代码必须附带单元测试。 - 变更任何公共 API 时必须同步更新对应的文档文件。 ## 代码风格 - 遵循项目现有风格不自行引入新的模式。 - TypeScript 项目中禁止使用 any。这里每一项都是好几轮迭代后留下来的。以前我写了很多“提倡使用函数式编程风格”之类的软性建议后来发现模型不一定能理解“风格”这个词的边界反而容易产生破坏性重构于是全部删掉只保留可验证的硬规则。skills/目录则是按任务维度组织的。每个技能是一个文件夹核心是SKILL.md。一个最小可用的SKILL.md结构分为三块frontmatter元信息、instruction给模型的指令、resources附带参考文件。frontmatter 里最关键的是description它决定了模型什么时候会自动调用这个技能。我对比过不同写法发现用“当用户要求 xxx 时使用”这种句式明确度最高比“用于处理 xxx 任务”更直接。agents/目录下放子 Agent 的 JSON 定义。它的作用和技能又不一样技能偏向“怎么干事”Agent 偏向“雇佣谁干事”。比如我定义了一个code-reviewerAgent它就具备独立的系统提示词、工具列表和输出偏好主对话可以根据任务难度决定是否调用它。这样做的好处是审查逻辑不会把主对话的上下文撑爆。3.2 手把手写一个代码审查模板我觉得最好的教学方式就是完整走一遍我写“代码审查”技能的过程。这个技能在所有模板库中使用频率最高也最能体现结构化思维的好处。第一步确定触发条件和描述词。我在SKILL.md的 frontmatter 里写--- name: code-review description: 当用户要求审查代码质量、优化建议或提交 Pull Request 审查时使用。适用于 diff 分析、安全性检查、性能优化和可维护性评估。 ---第二步写执行流程。执行流程不能太跳跃否则模型会漏掉步骤。我分成了固定的五个子步骤要求模型必须按顺序执行并在输出中标注每个步骤的完成状态读取目标代码和 diff。定位变更影响范围包括被调用的函数、依赖方。按安全、性能、可维护性、测试覆盖四个维度逐项检查。汇总问题清单并按 P0/P1/P2 分级。生成最终审查报告。第三步规定输出格式。前面已经说过格式比形容词重要。我在模板里直接给出 Markdown 结构甚至给出了评分示例。这样模型输出的报告可以直接贴到代码合并请求里不用再二次整理。这个模板我当时花了大概一个晚上写完本来以为很完美结果测试的时候发现模型经常在“影响范围”这一步偷懒给出的分析明显是基于猜测而不是实际读取代码。后来我在流程里加了一条硬性要求“在输出影响范围之前必须先逐行列出你阅读过的文件列表并给出阅读顺序。”加了这条后模型会真的去执行工具调用而不是编个大概。3.3 参数化与复用让模板像函数一样被调用模板变成资产之后必然会遇到一个需求同样一个模板在不同项目里要替换项目名、代码风格、目录结构等变量。如果一个一个复制修改维护成本会很重。我的做法是用一个简单的 Shell 渲染脚本来处理占位符。比如模板里写项目名{{PROJECT_NAME}} 代码路径{{SRC_DIR}} 测试命令{{TEST_COMMAND}}然后调用scripts/render_template.sh传入参数./render_template.sh templates/refactor-plan.md \ -p PROJECT_NAMEmy-api \ -p SRC_DIRpackages/api/src \ -p TEST_COMMANDpnpm --filter api test脚本本质就是sed替换没用什么高级技术但效果非常好。团队里任何成员都可以通过统一命令生成项目定制的模板文件再配合 Git 分支管理做到“模板库升级项目内定制文件不冲突”。这种“模板 渲染参数”的思路其实来源于一个很朴素的想法模板不该是死的文件而应该像函数一样有入参、有出参。入参是项目和任务的上下文出参是给 Claude Code 加载的指令文件。这样结束后整个体系就具备可组合性了。4. 模板测试方法论怎么验证它真的有效很多人在写完模板之后就默认它生效了这是我见过的最大误区。模板是典型的“写起来简单测起来复杂”的东西看起来有逻辑实际跑起来可能处处有意外。我后来形成了一套固定的测试流程每次给模板库打 Tag 之前都要完整跑一遍。4.1 先跑最小可复现案例给新模板写一个最小测试用例通常是公开仓库里的一段代表性代码。比如测试“代码审查”模板我会拿一个只有一个文件、包含 3~4 个明显问题的示例仓库来跑问题包括一个未处理异常、一个硬编码密、一个多余循环。如果模板连这种简单场景都不能稳定发现问题那就不必浪费精力去跑真实项目了。这里的“稳定”很关键。我会把同一个案例连跑三次确认每次都输出相同的问题集。如果不稳定说明模板流程的约束力不够——大概率是步骤之间出现了模糊地带比如“检查可维护性”这一步没有给出判断标准模型就自由发挥了。建议在测试时固定模型温度参数至少在 Claude Code 配置里把随机性调到低档这样能区分是模板问题还是模型随机性导致的波动。4.2 用边界情况攻击模板过了最小案例后我会故意做一些让模板“难受”的输入比如空目录、超长文件、全是 TODO 注释的伪代码、混合多种语言的仓库。这些边界情况往往能暴露模板里过于刚性的假设。举一个真实例子我的“SQL 迁移”模板最初假定所有迁移脚本都放在migrations/目录下结果有一次测试时放在db/scripts/里模板立刻判断错误以为项目没有迁移记录差点生成重复的初始化脚本。后来我在模板里加了一个探测步骤先扫描目录结构如果找不到标准路径就主动询问用户而不是直接按默认路径执行。边界测试的本质是检查模板是否具备“失败反馈”能力。一份好的模板在遇到无法处理的情况时应该明确说出来“这里我判断不了需要补充信息”而不是硬着头皮瞎猜。4.3 把模板从个人体验固化成团队资产单人验证和团队推广之间还有一道鸿沟。今年我把这套模板引入到团队后发现每个人对模板的期望不一样有人觉得审查模板太严格有人觉得生成模板太啰嗦。后来我建立了一个简单的反馈机制每个模板文件头部放了一段维护记录模板从 v1.0 升到 v2.0 时写清楚改动原因所有改动经过至少两次代码审查再合入主分支。同时我强烈建议在模板库里单独建一个examples/目录每个模板附带一个标准输出样例。团队成员看着样例就能理解模板意图也方便测试时对比模型输出。这个目录到现在仍然是我认为投入产出比最高的部分。5. 踩坑实录与排查技巧最后一部分我写几个自己反复踩坑后总结出来的排查思路都是文档里不会写的东西希望对你有实际帮助。5.1 模板正在“污染”上下文还不知道有一次我把所有能想到的规则都塞进CLAUDE.md结果模型每次处理任务都变得很迟钝而且很多指令之间互相冲突。比如我既写了“代码尽量简短”又写了“必须详尽注释”模型就开始精神分裂。排查之后才发现模板不是越多越好长上下文不但占用模型容量还会放大指令之间的冲突概率。现在我给自己定了个指标CLAUDE.md不超过 30 行单个技能文件不超过 80 行。超过这个量就必须拆分子任务而不是靠堆字数。上下文空间非常宝贵与其让它浪费在冗余指令上不如用来容纳真实的代码结构。5.2 模板太抽象还是太死板需要找平衡这类问题在技能描述里尤其明显。写太抽象比如“审查代码质量”模型不知道该不该调用写太具体比如“当用户输入 xxx 文件路径时使用”模型在其他场景下就又想不起来。我最后的解法是描述词里同时包含本地触发词和语义触发词例如“当用户要求审查代码、优化建议或提到 Pull Request 时使用”这样既能捕获明确请求也能覆盖间接表达。如果遇到模板经常被跳过或误调用第一个排查项一定是 description 写得太窄或太宽而不是模型“太笨”。我在迭代中反复验证过修改描述词对命中率的提升比修改正文指令还明显。5.3 关于凭证、安全和协作的几个提醒模板库里最容易出事故的是含路径、Token、内网地址等信息的配置。我强烈建议所有模板文件都通过环境变量注入敏感信息不要直接把真实值写进示例。渲染脚本里我已经做了脱敏处理遇到{{ENV_KEY}}这种占位符会优先从环境读取。还有一个容易忽略的点模板语法要区分 Markdown 和纯文本。Claude Code 的原生技能配置文件里支持 Markdown但如果你用渲染脚本生成最好统一输出纯文本否则夹杂特殊符号会导致模型理解混乱。最后想分享一个很私人的习惯我把模板库当成一个持续演化的代码项目来维护每个模板都有版本记录、测试文件夹和变更日志。这听起来很工程化但正是这种“把提示词当代码管理”的态度才让整套模板从一次性脚本变成团队可持续复用的基础设施。如果你也想做一套自己的claude-code-templates我建议从最小面积极小的一个任务开始跑通后再逐步加料——模板不是写出来的是用出来的。
