★ FEATURED ARTICLE 如果你把 claude-code 当成一个普通的对话式代码助手用上一周就会发现一个特别别扭的现象每次新建会话它都像失忆了一样。目录结构要重新解释代码规范要重新教测试命令要重新说昨天刚纠正过的同一个问题今天换个文件它又犯了。我最早整理 claude-code-templates 这个仓库就是被这些重复劳动逼出来的——把项目背景、行为规则、高频任务的执行流程全部固化成模板让 Claude Code 一进来就进入状态而不是每次从零开始教。这个仓库解决的核心问题简单说就是把每次都要重新说的东西变成启动时自动加载的东西、敲一下斜杠就能触发的东西。适合所有日常重度使用 Claude Code 的开发者尤其是同时维护多个项目、或者需要和团队共享同一套 AI 工作方式的人。这套思路不复杂但里面有几个很容易踩的坑。比如 CLAUDE.md 写太长导致上下文被撑爆、命令模板的指令太模糊导致输出风格飘忽不定、全局模板和项目模板互相打架等等。这篇文章我会把我实际整理这套模板库的过程、每一类模板的设计思路、以及踩过坑之后的修正方案全部写出来你照着搭一套自己的模板体系应该没什么问题。1. 这个模板仓库到底在整理什么先看清问题的本质1.1 模板不是提示词堆砌而是入职文档很多人第一次看到 claude-code-templates 这类仓库第一反应是这不就是一堆提示词吗。这句话对了一半但恰恰是没想清楚的那一半导致很多人抄了模板也用不好。Claude Code 本质上是一个通用能力很强的模型外壳它有海量的编程知识但缺少对你项目特有的知识。每次会话都是全新的上下文它不记得你上周说的这个项目的 service 层不允许直接操作数据库。你可以在对话里教它一次、两次、十次但它不会主动记住下一次会话照样按自己最顺手的习惯来。这就像一个业务能力很强的资深工程师被外派到一个新团队第一天没人给他看项目文档和代码规范他写出来的东西大概率风格和团队完全不搭。模板的作用就是补上这个缺口而且要做的事只有两件第一注入上下文——让 AI 知道这个项目长什么样、用什么技术栈、目录怎么划分、测试怎么跑第二注入行为约束——让 AI 知道你希望它怎么干活是先出方案再动手还是直接改代码代码审查要按什么维度检查提交信息用什么格式。这两件事想清楚了模板的内容基本就定了。想不清楚堆再多华丽辞藻模型该自由发挥还是自由发挥。1.2 三类模板的划分记忆型、命令型、流程型我最初整理模板的时候尝试过按技术栈分、按场景分、按任务类型分最后发现最实用的分法其实是按加载方式来分。因为不同加载方式的模板对内容的要求完全不一样混在一起写会非常别扭。模板类型作用加载方式典型文件记忆型提供项目背景和常驻规则启动会话时自动加载CLAUDE.md命令型封装高频任务的执行指令手动敲/命令名触发commands/review.md流程型固化多步任务的 SOP手动触发或内嵌在命令中workflows/feature-dev.md记忆型模板的核心是自动两个字。CLAUDE.md 放在项目根目录每次会话启动都会自动读进上下文所以适合放那些每次工作都必须知道的信息项目一句话说明、常用命令、目录职责边界、强制规范。它要求精简因为每次加载都占 token塞太多低价值内容会拖慢响应速度还会稀释真正重要的指令。命令型模板的核心是按需触发。你敲/review、/commit、/test它才会执行相当于把高频任务封装成了快捷键。这类模板可以写得比 CLAUDE.md 更详细因为它不是每次会话都加载只有你明确调用时才消耗上下文。命令型模板特别适合那些步骤多、格式要求严格的任务——与其每次手打一遍审查清单不如把清单固化成一个文件。流程型模板更像一份操作手册。它描述的是当一个复杂任务发生时应该按什么顺序执行哪些环节比如新功能开发的完整流程、报错排查的定位路径。它可以是独立的 Markdown 文档也可以直接内嵌到命令模板的正文里。我实际用下来的感觉是流程型模板适合处理那些一上来就动手容易翻车的任务它的价值在于强制 AI 在动手之前先做分析和规划。2. 核心模板内容与设计要点拆解2.1 CLAUDE.md 应该写什么、不写什么CLAUDE.md 是整套模板体系的地基也是最容易写烂的一份文件。我见过很多人把它写成一本项目百科恨不得把每个模块都拆出来讲一遍结果模型看了半天抓不住重点而真正想约束的行为反而被淹没了。一份好用的 CLAUDE.md 我建议只包含六块内容项目的一句话说明、技术栈与关键依赖、常用开发命令、目录结构与职责边界、代码规范与禁止事项、运行与部署注意事项。每块都尽量短短到不能再短。# 项目订单服务 ## 技术栈 - Node.js 20 TypeScript Express - PostgreSQL Prisma ORM ## 常用命令 - 测试npm run test - Lintnpm run lint - 类型检查npm run typecheck ## 目录约定 - src/routes只放路由定义 - src/services业务逻辑 - src/repository数据库访问层 ## 代码规范 - 新增功能必须附带单元测试 - 错误信息统一从 errors.ts 中引用 - 禁止在 service 层直接操作数据库注意我写的是禁止在 service 层直接操作数据库而不是建议在 service 层保持业务逻辑纯净。模型对禁止这种强约束词的遵循率远高于建议尽量最好这类弱表述。这是我在对比多种写法之后确认的一份 CLAUDE.md 里指令越明确AI 的行为就越稳定写得像散文它就会把你的话当参考意见。不写什么同样重要。版本号不用写依赖升级就会过期个人的任务待办不写那是你自己的清单不是 AI 的历史的变更记录不写模型不需要知道三个月前重构过什么。每次会话都会加载 CLAUDE.md所以你写的每一句话都在消耗上下文窗口。真正合理的状态是这份文件压到一页以内每一行都是不可删减的高价值信息。如果有些细节确实需要让 AI 知道但没必要常驻可以用README.md这种方式引用外部文件让 Claude 在需要时再去读完整内容。2.2 高频命令模板从 /review 到 /commit命令模板是 claude-code-templates 里数量最多、也最容易被拿来即用的一类。它的机制不复杂在.claude/commands/或用户级~/.claude/commands/目录下放一个 Markdown 文件文件名就是命令名会话里敲/文件名就能触发。文件头部可以有一段 YAML 格式的 frontmatter里面写description命令列表里会显示这段说明。以代码审查为例一个能直接落地的/review命令长这样--- description: 对当前改动做代码审查输出结构化评审意见 --- 你是一名严格的代码审查者。请执行以下步骤 1. 读取当前分支的改动 diff。 2. 按以下维度逐项检查 - 逻辑正确性与边界条件 - 错误处理是否完整 - 测试覆盖是否到位 - 命名与代码风格是否符合项目约定 3. 输出格式 - 问题列表按严重程度排序 - 每个问题给出具体位置或函数名 - 能直接修复的给出修改建议 - 最后给出结论approve 或 request changes 注意不要输出空洞的赞美不要复述代码只关注真正影响质量的问题。这个模板里最值钱的是最后那句负面约束。我实测下来如果你不告诉模型不要复述代码它至少会花三分之一篇幅把代码重新讲一遍加了这句之后输出立马变得干净。很多命令模板失效不是因为模型能力不够而是因为模板里只有正向要求没有负面约束。再看/commit命令它的价值在于把提交信息的格式统一起来--- description: 根据当前改动生成符合规范的提交信息 --- 根据当前 git diff 生成一条提交信息。 要求 - 遵循 Conventional Commits 格式type(scope): summary - type 只在 feat / fix / refactor / docs / test / chore 中选择 - summary 使用祈使句不超过 50 个字符 - 如果有破坏性变更在正文中说明 BREAKING CHANGE 如果 diff 内容不足先询问我要提交的范围。设计命令模板时的关键点有两个。第一正文开头要明确定义角色比如你是一名严格的代码审查者模型对角色设定的响应非常敏感。第二步骤要分点列出模型按清单执行的稳定性远高于让它读一段散文式的描述。一个命令模板写完后在真实项目里跑一次看输出和期望的差距再反向修改措辞这比凭空堆砌指令高效得多。2.3 流程型模板把怎么做固化成 SOP流程型模板是我后来才补上的一类起因是一次惨痛的教训。当时我让 Claude Code 直接实现一个涉及多模块的新功能它跳过了需求分析直接开始改核心文件改到一半我发现它完全理解错了方向。问题不在模型能力而在于我没有告诉它遇到复杂任务应该先做什么、后做什么。一个可用的新功能开发流程模板大概是这样的你现在要协助实现一个新功能。请严格按下面的流程执行 1. 复述你对需求的理解列出涉及的文件和模块。 2. 评估影响面这个改动会影响哪些现有功能是否存在破坏性风险 3. 给出实现方案包括要新增的文件、要修改的文件、数据结构变化。 4. 停下来向我确认得到确认后再开始写代码。 5. 实现过程中每完成一个子步骤先自测再继续下一步。 6. 全部完成后更新相关文档并运行测试。这份流程里最重要的是第 4 步。如果你不强制模型在方案确认前停下来它大概率会自作主张往下做而一旦方向错了损失的不只是时间还可能引入一堆需要回滚的代码。模板的价值就是给 AI 戴上一道刹车把它从急于完成的倾向拉回到先规划再执行的轨道上。调试类流程模板也同理应该强制它先复现问题、看日志、定位根因再谈修复否则它就大概率上来就试一堆看似合理的方案。3. 从零搭建自己的模板库实操记录与配置要点3.1 先设计仓库目录结构模板仓库的目录结构我建议按用途划分而不是按项目划分。这样做的原因是命令模板和流程模板往往可以跨项目复用只有 CLAUDE.md 这类记忆型模板和具体项目强相关。我最终采用的目录结构是这样的claude-code-templates/ ├── project/ │ ├── nodejs-ts.md │ ├── python-fastapi.md │ └── react-nextjs.md ├── commands/ │ ├── review.md │ ├── plan.md │ ├── commit.md │ └── test.md ├── workflows/ │ ├── feature-dev.md │ ├── debugging.md │ └── refactoring.md └── install.shproject 目录下放的是不同技术栈的 CLAUDE.md 模板每个文件对应一种项目脚手架初始化新项目时直接复制改名为 CLAUDE.md 即可。commands 目录下是所有命令模板文件名就是命令名复制到项目的.claude/commands/或用户级~/.claude/commands/就能用。workflows 目录下的流程模板比较特殊它们既可以作为独立文档供对话时引用也可以把核心步骤内嵌进命令模板正文——我比较推荐后一种方式因为内嵌后少一步手动搬运。3.2 写一份可复用的 CLAUDE.md逐段拆解以 Node.js TypeScript 项目为例一份可复用的 CLAUDE.md 模板我会写成下面这样然后每段解释为什么要这么写。# 项目项目名称 ## 技术栈 - Node.js 20 TypeScript Express - PostgreSQL Prisma ORM - 测试框架Vitest ## 常用命令 - 启动开发服务npm run dev - 运行测试npm run test - 类型检查npm run typecheck - Lintnpm run lint ## 目录约定 - src/routes路由定义不写业务逻辑 - src/services业务逻辑禁止直接操作数据库 - src/repository数据库访问层唯一的 Prisma 调用位置 ## 强制规范 - 所有新增业务功能必须附带单元测试 - 错误信息统一从 errors.ts 导出禁止在业务代码里硬编码错误文案 - 提交信息遵循 Conventional Commits - 修改公共接口时必须先列出调用方再进行变更 ## 禁止事项 - 禁止在 components 目录写业务逻辑 - 禁止绕过 repository 层直接使用 Prisma Client - 禁止在没有测试的情况下重构核心交易流程强制规范和禁止事项我故意分成两块的。前者告诉 AI 应该主动做什么后者明确划出红线。实际使用中负面表述的红线往往比正面要求更有效模型在生成代码时对明确不可做的约束的遵守率显著更高。目录约定部分关键不是罗列目录结构而是说明每个目录的职责边界尤其是什么不允许在这里出现。AI 一旦知道了边界就不会在路由文件里塞一堆业务逻辑。这份模板里我没有写任何版本号也没有写业务的详细说明。版本号会过期业务细节应该在对话里临时提供或通过README.md引用。模板只承载那些每时每刻都需要遵守的稳定规则这是它保持长期有效的前提。3.3 命令模板的 frontmatter 与正文写法命令模板的创建步骤很简单但有几个细节会影响最终效果。第一步是在.claude/commands/或~/.claude/commands/下新建一个.md文件。第二步写 frontmatter至少要写description因为命令菜单里显示的就是这段描述它必须让人一眼看懂这个命令是干什么的。第三步写正文正文前 1 到 3 行必须是最核心的指令比如角色设定和任务目标因为模型对长文本前部的注意力最强。第四步是在真实项目中测试根据输出调整措辞。--- description: 编写单元测试确保覆盖核心逻辑和边界情况 --- 你是这个项目的测试工程师。为指定的模块或函数编写单元测试。 执行步骤 1. 阅读被测代码列出所有公共方法和主要逻辑分支。 2. 检查是否已有测试文件确认测试框架和现有写法。 3. 编写测试覆盖正常路径、边界输入、异常输入三类情况。 4. 运行测试并确认全部通过。 5. 输出测试文件和用例清单。 约束 - 不修改被测代码除非发现明显的 bug且修改后必须另行说明 - 不使用 any 逃逸类型检查 - 测试命名用 given_when_then 结构frontmatter 里除了description部分版本还支持限制工具或指定模型等元信息但这个不在必需范围内新手阶段只要写好 description 就够了。正文写作时有个容易被忽略的点负向约束要单独放一段不要混在步骤里。我早期的命令模板把不要修改被测代码写在步骤 3 的括号里结果模型经常忽略它单独成段之后遵守率明显提升。这里还有一个优先级问题项目级.claude/commands/会覆盖用户级~/.claude/commands/的同名命令。所以我的实践是用户级目录放所有项目通用的命令比如 commit、review项目级目录放那些和当前项目绑定的命令比如特定框架的测试生成命令。这样可以避免同名冲突也让模板在不同粒度上各自复用。3.4 版本管理与跨项目复用模板仓库本身应该用 git 管理这一点毫无疑问。真正的问题是怎么把模板安装进一个新项目。我最初是手动复制后来觉得麻烦写了一个 install.sh 脚本。#!/usr/bin/env bash # 用法./install.sh project-type target-dir # 示例./install.sh nodejs-ts ./my-app PROJECT_TYPE$1 TARGET_DIR$2 if [ -z $PROJECT_TYPE ] || [ -z $TARGET_DIR ]; then echo 用法: ./install.sh project-type target-dir exit 1 fi if [ ! -f project/${PROJECT_TYPE}.md ]; then echo 错误: 未找到 project/${PROJECT_TYPE}.md 模板 exit 1 fi # 安装 CLAUDE.md cp project/${PROJECT_TYPE}.md ${TARGET_DIR}/CLAUDE.md # 安装命令模板 mkdir -p ${TARGET_DIR}/.claude/commands cp commands/*.md ${TARGET_DIR}/.claude/commands/ echo 模板已安装到 ${TARGET_DIR}这个脚本的思路是根据项目类型把对应的 CLAUDE.md 复制过去然后把所有通用命令模板一次性复制到项目的.claude/commands/目录。理论上也可以支持符号链接这样模板仓库更新后项目里的命令自动同步但实际使用下来链接方式在多人协作时容易造成困惑复制方式虽然笨一点但胜在隔离性好、行为可控。团队协作时的最佳实践是把模板仓库作为团队公共资产维护CLAUDE.md 提交到项目的 git 仓库这样所有人共享同一套 AI 行为约束。但要注意个人偏好不要写进项目级 CLAUDE.md比如代码行宽 80 字符这类个人习惯应该放到用户级~/.claude/CLAUDE.md。项目级只放团队共识用户级放个人偏好这个边界一旦混乱模板的维护成本就会直线上升。4. 常见问题与排查技巧实录4.1 CLAUDE.md 没有生效最典型的症状是你明明在 CLAUDE.md 里写清楚了目录约定和命令但 AI 的行为完全不像看过这份文件的样子。我建议按下面这个顺序排查。第一确认文件名是CLAUDE.md全大写而不是claude.md、Claude.md大小写错了不会加载。第二确认文件在项目根目录不在 src 或子目录里——子目录也有 CLAUDE.md但那是作用于该子目录的不会在项目根会话里加载。第三确认你是新开的会话已经启动的会话不会读取后续修改的 CLAUDE.md。第四也是最容易被忽略的文件太长了模型在长上下文里会把后面的内容遗忘或忽略。排查时可以开一个新会话直接问一句话请列出 CLAUDE.md 中定义的项目目录约定。如果它答不上来说明文件没有被加载或内容没被重视如果答得上来但行为不遵守那问题就出在措辞太模糊上需要改成强约束词。4.2 模板输出风格不理想命令模板触发成功了但输出风格和预期差很远。比如让它做代码审查它给你写了一篇温和的建议书而不是带严重程度排序的问题清单。这通常是正文里只有要求没有格式导致的。模型对输出格式这种明确指令的遵循度很高但对认真审查仔细检查这种抽象要求会自由发挥。解决办法是在模板里把输出格式写死分点列出应该输出的结构甚至可以给一个最小示例。另外负面约束需要放在正文的独立段落像不要输出空洞的赞美不要复述代码这类话放在步骤中间容易失效。4.3 token 开销过大响应变慢CLAUDE.md 写得太长是响应变慢的主要原因。每句话都会随每次会话加载进上下文写三千字的项目说明书等于每次请求都带着三千字背景模型处理时间自然变长。一个简单的衡量标准是CLAUDE.md 超过一页纸大概 1200 字就要警惕。遇到这种问题先把明显冗余的段落删掉比如项目背景介绍、团队介绍、冗长的架构描述。再把那些需要时才知道的细节移到外部文档用README.md或其他引用方式按需加载。需要常驻这份文件的永远只有项目目录约定、强制规范、禁止事项这类每次干活都离不开的信息。把不常用内容强行塞进 CLAUDE.md是这套体系里性价比最低的操作。4.4 全局模板与项目模板冲突用户级~/.claude/CLAUDE.md、项目根目录的 CLAUDE.md、子目录的 CLAUDE.md 会叠加加载子目录的规则优先级最高。一旦内容冲突模型行为就会飘忽不定。比如用户级说代码风格使用 StandardJS项目级 CLAUDE.md 里又写使用 ESLint 的 Airbnb 配置模型每次遇到风格问题时就会在两个规则之间摇摆。解决方式是在模板体系设计阶段就划分好职责。用户级只放不可协商的基本规则比如永远不要在未确认的情况下删除代码这类底线项目级放项目特有的规范子目录级只放目录专属约束。每加一条规则之前先想想这条规则会不会在另一层出现冲突。我在实际维护模板仓库时定期会跑一遍所有模板搜索互相矛盾的词条比如不同层级同时出现风格、路径或命令规范的情况及时清理。最后再分享一个我自己维护这套模板库的小习惯。每当我发现 Claude Code 连续两次在同一个问题上犯错我不会在对话里反复纠正它而是停下手头的活花十几分钟把这个教训固化成一条模板规则。比如它总是把没测过的代码直接提交我就会在 commit 模板里加上在生成提交信息之前先确认测试已运行通过这一条。使用模板的时间越长这个仓库就越像一份和 AI 一起工作的行为契约——每一轮纠错都在修订契约而不只是在单次对话里发脾气。这个思路比模板本身更值得你借鉴。
阅读完成 · 觉得有帮助？
