我大概是从Claude Code还是小范围预览时就入坑的头三个月基本是想到什么问什么后来发现自己在重复做同一类事情开新项目要交代技术栈、写完代码要评审、改完逻辑要补测试、要重构了得先列计划。这些话术每次都要重新组织偶尔还漏掉关键约束输出质量全看当天状态。于是我把高频提示词、项目约定、代码风格说明全部整理成一套可复用的模板也就是这个 claude-code-templates 项目——一个把 Claude Code 的 CLAUDE.md、斜杠命令、Agent 和 Skills 配置做成可版本化、可分发的模板库方案。这篇文章会从模板的三层结构讲起再给完整的模板写法、占位符设计、团队分发和踩坑排查适合正在用 Claude Code 但觉得 AI 输出不稳定、项目上下文总需要反复交代的开发者。1. Claude Code模板体系到底在管理什么先把三层结构看清很多刚接触 Claude Code 的人以为模板就是一个记录项目说明的文件这个理解没错但只覆盖了三分之一。我实际用下来的体感是Claude Code 的模板体系至少分三层每一层管的上下文粒度完全不同搞混了就会出现CLAUDE.md 写了规则但模型就是不遵守的怪现象。1.1 第一层CLAUDE.md 项目记忆文件CLAUDE.md 是 Claude Code 每次启动会话时自动读取的说明书相当于模型在接手项目前先看的一份入职手册。它按作用范围分成几档~/.claude/CLAUDE.md用户级全局配置所有项目通用比如你个人的代码风格偏好、常用的工具调用习惯项目根目录/CLAUDE.md项目级配置核心的上下文来源包含技术栈、目录结构、构建命令、约束规则CLAUDE.local.md本地私有配置通常不进 Git适合放个人分支习惯、本机路径、临时注意事项。这一层的管理重点是写什么、不写什么。它应当承载那些每次对话都需要的稳定信息而不是某个功能点的一次性说明。我在项目级 CLAUDE.md 里固定放五类内容项目是干什么的、技术栈和关键依赖、常用命令、模块边界和约定、明确禁止做的事。这些东西每写一遍都心疼但放进 CLAUDE.md 之后每次新会话模型都能带着完整上下文工作不需要你重新复制粘贴。1.2 第二层.claude/commands/ 自定义斜杠命令如果说 CLAUDE.md 是背景设定那斜杠命令就是一键执行的固定动作。自定义命令放在项目的.claude/commands/目录下每个.md文件对应一个命令文件名就是斜杠命令名。比如.claude/commands/review.md对应/review。命令文件的结构是 YAML frontmatter 加正文模板frontmatter 里写说明、参数提示、允许使用的工具正文就是给模型的提示词模板。你可以把代码评审写单测生成提交信息重构计划这类高频动作全部固化成命令之后每次执行只是把参数换一换核心流程完全一致。我见过很多人只写 CLAUDE.md 不写 commands结果把大量操作细节堆进项目说明里CLAUDE.md 越来越长模型反而抓不住重点。把一次性操作流程挪进斜杠命令CLAUDE.md 只留稳定约束两边都轻松。1.3 第三层Agent 与 Skills 模板以及 settings/hooks到这一层模板从提示词变成了行为定义。.claude/agents/下的子代理可以自带专属的上下文和能力边界适合拆出测试专家、评审专家这类角色.claude/skills/下的技能模板则把某一类专项能力比如数据库迁移、性能分析打包成 SKILL.md让模型在遇到对应任务时自动加载。再往下还有.claude/settings.json里的权限和 hooks 配置。hooks 可以定义模型调用某个工具之前/之后自动跑一段脚本这本质上也是一种流程模板。我的建议是不要一开始就上三层先玩熟 CLAUDE.md 和 commands等确实遇到一个角色需要稳定人设固定工具权限的场景再引入 Agent 和 Skills否则模板库会过早膨胀。2. 从零搭建 CLAUDE.md 项目模板按项目规模拆三种写法CLAUDE.md 不是越长越好它应当跟项目的复杂度和团队规模匹配。我维护模板库时按三种典型场景写了三套不同的 CLAUDE.md差异还挺大的。2.1 个人项目的极简模板只要技术栈和约束个人项目或小工具CLAUDE.md 控制在 30 到 60 行就够。核心是让模型不跑偏而不是给它海量信息。我早期的模板长这样# 项目简介 xx命令行工具用 Go 编写处理 xx 数据导入导出。 # 技术栈 - Go 1.22Cobra 命令行框架 - PostgreSQL 16goose 做迁移 - 日志使用 slog统一 JSON 格式输出 # 常用命令 - 构建: go build ./cmd/... - 测试: go test ./... -race - 迁移: goose up # 约束 - 不要为了小功能引入新依赖除非我先确认 - 错误处理用 errors.Join 聚合不要裸 panic - 不需要支持 Windows 以外的平台差异这套模板的关键是把我认为重要但容易忘的约定写进去。尤其是依赖引入和错误处理这两条模型默认会给出标准但可能不符合你习惯的方案写清楚能省大量来回纠正的时间。个人项目最容易犯的错是把 README 整段复制进 CLAUDE.mdREADME 是给人看的CLAUDE.md 是给模型执行用的侧重点完全不同。2.2 中型项目的结构模板把模块边界写清楚到了有多个模块、有 API 层和数据层的项目CLAUDE.md 就需要包含地图了。模型不知道你的代码放在哪你指望它自己翻完整个仓库再动手成本太高。我在这一档会额外加目录职责说明和跨模块依赖规则# 目录结构 - internal/apiHTTP handler 层只做参数校验和响应封装 - internal/service业务逻辑层禁止直接操作数据库 - internal/repo数据访问层所有 SQL 必须经过这里 - pkg对外可复用的公共库不允许反向依赖 internal # 模块边界 - service 层调用 repo 层通过接口方便 mock 测试 - 新增业务接口时先改 api 层再补 service 和 repo保持层次顺序这段看起来平淡无奇但在模型做跨文件改动时作用很大。比如它拿到一个需求会先按目录边界判断改动范围而不是随手在 handler 里写 SQL。我实测过没有这段说明时模型经常把逻辑塞进离入口最近的函数里有了边界约束之后生成的代码结构和项目现有风格明显更一致。2.3 团队共享模板把规范和流程固化团队项目里的 CLAUDE.md 不再只是个人偏好它变成了团队协作契约。除了技术栈还需要写清楚分支规范、提测流程、代码评审的标准、领域术语表。这里有个容易被忽略的点团队模板一定要写明不要在未确认时自行修改公共代码这类安全约束否则模型在修复一个 bug 时可能顺手重构了公共工具函数引发一堆回归。团队模板里我还会加一个当前迭代背景段落记录正在进行的功能和已知的技术债。做法是把近期上下文从过长的历史文档里抽出来放到 CLAUDE.md 顶部让模型优先关注当下的演进方向。注意这个段落要频繁更新否则放几个月就变成了陈述往事的历史档案反而占上下文。3. 自定义斜杠命令把高频操作固化成一条稳定指令CLAUDE.md 解决的是背景一致自定义斜杠命令解决的是动作一致。我强烈建议把每天都做的操作整理成命令因为同样的评审标准你上午写的和下午写的提示词模型执行出来的颗粒度完全不一样。3.1 最实用的代码评审模板我先给你看我项目中出场率最高的/review--- description: 对指定文件或改动范围做代码评审 argument-hint: 文件路径或 git diff 范围 allowed-tools: Bash, Read, Grep --- 以资深 reviewer 的身份对 $ARGUMENT 范围内的改动做代码评审。 请按以下顺序输出 1. 严重问题Bug、安全漏洞、并发问题必须有文件和行号 2. 逻辑缺陷与边界条件给出复现场景 3. 可维护性问题命名、函数长度、重复代码 4. 建议的修复方案对每个严重问题给出可执行的修改建议 注意 - 不确定的问题明确写需人工确认不要猜测 - 不要重写整段代码只针对问题点提出修改 - 如果改动涉及公共函数额外检查所有调用方是否受影响这个模板之所以稳定是因为它规定了输出顺序和边界。不确定就写需人工确认这一句尤其重要没有它模型会脑补一个看似合理的解释把 review 变成小说创作。allowed-tools限制它只能读文件和跑命令防止它在评审中途突然去改代码。3.2 测试生成、重构、提交信息三个高频命令再给你三个可以直接借鉴的短命令。第一个是生成单测--- description: 为指定模块生成单元测试 argument-hint: 目标函数或文件 --- 为 $ARGUMENT 编写单元测试。要求 - 覆盖正常路径、空输入、异常参数三个层面 - 使用项目现有的测试框架和 mock 方式 - 每个用例写清断言意图不追求覆盖率数字 - 测试通过后用 go test或对应命令跑一遍再给我结果第二个是重构计划。重构最容易翻车的点是模型一头扎进代码里乱改没有全局设计。所以我的命令模板强制它先列计划--- description: 对目标区域做重构前的计划与分步实施 argument-hint: 需要重构的模块 --- 对 $ARGUMENT 做重构。第一步先输出重构计划 - 现状问题列表 - 重构后的目标结构 - 分步骤实施顺序标注每步的影响范围 - 需要补充的测试点 只有我确认计划后才开始第二步的实际代码修改。最后是生成提交信息--- description: 根据 git 改动生成符合规范的提交信息 --- 执行 git diff 和 git status 查看当前改动然后生成提交信息。 要求 - 使用 Conventional Commits 规范 - 提交信息要说明为什么改不只是改了什么 - 如果改动涉及多个主题拆成多个提交建议这三个命令的共同点是先给结构、再动手把模型最容易失控的环节——直接改写大段代码——用流程约束住。3.3 参数槽位和默认值的设计写命令模板时参数槽位决定命令的灵活度。Claude Code 的斜杠命令支持多种占位形式$ARGUMENT引用整段参数$ARGUMENT1、$ARGUMENT2分别取第一、第二个参数$!ARGUMENT表示必填参数没有提供时会主动询问$ARGUMENT:默认值则为参数提供默认值。我在设计参数时遵循两个习惯必填参数尽量少能用默认值的不要做成必填。比如/review的默认参数是当前分支的全部改动显式传参时才缩小范围/commit则完全没有必填参数它自己会去读 git 状态。参数越少命令的容错率越高团队里的人也不需要记住复杂的调用语法。4. 模板不是一堆文字占位符、上下文与输出格式的关键细节模板写出来如果只是好看的一段提示词那和直接在对话里粘贴没区别。真正让模板产生复利的是几个容易被忽略的机制参数如何传递、上下文如何注入、输出格式如何约束。4.1 占位符的完整写法和必填参数先花一分钟把占位符语法说全。命令正文里的$ARGUMENT会在调用时被替换为用户输入。比如执行/review internal/service/user.go正文里的$ARGUMENT就会变成internal/service/user.go。如果调用时没带参数这里会留空所以我通常配合$!ARGUMENT或默认值使用--- description: 分析某个模块的依赖关系 argument-hint: 模块路径 --- 分析 $!ARGUMENT 的依赖关系输出调用图说明。$!ARGUMENT表示这个参数必须提供不提供时模型会主动追问避免命令在缺失关键信息的情况下硬跑。$ARGUMENT:全部改动这种写法适合参数可选的场景用户不输入就用默认值。另外注意不同版本对占位符的支持细节可能有差异升级 Claude Code 后最好抽查几个高频命令是否还按预期解析。4.2 把文件内容和命令输出注入模板斜杠命令并不是只能用用户传参它还可以把项目里的文件内容带进上下文。我在写命令模板时经常直接在正文里用引用文件路径比如在评审命令里带上对应的测试文件请结合 internal/service/user_test.go 中现有的测试风格来评估新增代码。这样模型在执行动作前就有了参考锚点输出的代码风格会跟项目现有测试更接近。类似地有些命令模板需要模型先执行一段脚本再基于结果工作。我会在正文里明确写先运行go list ./...和git diff --stat基于输出结果分析改动范围。用模板把先执行什么、再看什么固定下来比让模型自由发挥稳定得多。要特别注意命令模板里不要写死具体的临时文件路径模型每次执行时环境不同硬编码路径会导致注入失败。4.3 为什么成套模板比临时提问稳定上下文一致性这是我坚持整理模板库最核心的理由。一次临时提问模型拿到的是一个孤立的提示词它不知道你之前评审时关注的侧重点、不知道你项目的代码风格、更不知道你踩过哪些坑。而一套模板相当于把过去若干次成功实践里的共识沉淀了下来。举实际例子我在团队里推行/review之前每个成员的评审结果差异巨大有人关注性能和并发有人只挑命名和格式。模板统一了评审维度和输出顺序后大家的评审报告结构基本一致问题发现率反而提升了因为模型会把注意力集中在你真正关心的维度上而不是平均用力。模板的本质是把你期望模型怎么做从模糊的默契变成显式的契约。5. 模板库的版本管理、热加载与团队分发实践模板库本身也是个代码库需要版本管理、需要变更记录、需要分发给团队。这一节讲我踩熟了的一套流程。5.1 用 Git 管理模板仓库符号链接做本地接入我的做法是建一个独立的模板仓库目录结构直接对齐 Claude Code 的配置路径claude-code-templates/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── test.md │ ├── refactor.md │ └── commit.md ├── agents/ └── skills/然后在需要使用这套模板的项目里用符号链接接入。用户级配置可以直接在 home 目录下建链接ln -s /path/to/claude-code-templates/CLAUDE.md ~/.claude/CLAUDE.md。项目级配置则在项目根目录链接或者干脆把.claude/commands链接进项目。Windows 上用mklink /D等价实现。这样模板仓库更新后所有关联项目自动生效不需要逐个复制粘贴。链接方式的问题是要注意项目里可能已经存在.claude目录链接前先备份原有的 settings.json 和 commands。我吃过一次亏把项目原有的配置目录整个替换掉丢失了本地的权限配置。5.2 模板变更与 CLAUDE.md 的依赖关系模板的生效时机有个容易忽略的区分斜杠命令文件在每次调用时读取改完立刻生效CLAUDE.md 是在会话启动时读取的改了之后要新开一个会话才会加载当前会话里继续聊并不会重新读。排查我改了没生效的问题时第一反应应该是是不是还在旧会话里。另外模板和 CLAUDE.md 之间有依赖关系。比如某个命令模板里假设项目用了特定测试框架如果项目技术栈变了命令也要跟着调整。我的习惯是每次模板变更都顺手更新仓库里的 README记录每个命令的适用场景和依赖前置条件。新成员加入团队时不需要问东问西看 README 就能接入。5.3 团队共享模板评审与更新机制模板库给团队用之后最大的问题是谁的模板进库。我的做法是设立一套轻量评审任何人提 PR 修改模板都要附带一个实际使用案例展示这个命令在一个真实场景下的输出效果。评审者重点看两件事——模板是否引入了会让模型产生误判的含糊表述以及参数设计是否覆盖了团队的主要使用方式。更新节奏上我给模板库打 tag比如v1.2.0CLAUDE.md 里记录当前模板库版本号。项目升级模板后如果出现异常先回退模板版本定位问题再排查代码。这套机制听起来重但对于超过五个人的团队省下来的沟通成本远超管理成本。6. 实测踩过的坑模板膨胀、指令冲突与失效排查最后这块是我最想分享的因为网上教程很少讲失败案例。我在这套模板上踩过的坑按症状—根因—解法整理成下面几条。6.1 模板膨胀与优先级冲突模板库第一版我写了二十多个命令结果实际高频使用的不超过五个。命令数量一多模型会被大量低频模板干扰。斜杠命令的名字还容易和 Claude Code 内置命令撞车比如自定义/review和内置的 review 行为不一致时你自己都分不清执行的是哪一个。我的解法很简单命令总数控制在十五个以内命名统一加业务前缀比如/team-review、/spec-test避免猜测和冲突。CLAUDE.md 的膨胀更隐蔽。它没有数量上限但内容越多模型对每条规则的注意力权重越低甚至出现规则互相矛盾的情况。我有一次在 CLAUDE.md 写了两条前后矛盾的构建命令模型每次执行都在两条之间随机选择排查了很久才发现是模板自身打架。解决办法是定期做减法把超过三个月没被引用或是已经写进命令模板的内容从 CLAUDE.md 里删掉。6.2 占位符没被替换、命令不生效的排查链路模板不生效分好几种我总结了一条排查链路按顺序走能解决九成问题确认命令文件放在.claude/commands/下文件名以.md结尾文件名不含空格在会话里输入/查看命令列表如果命令没出现检查 YAML frontmatter 是否合法description字段是否缺失frontmatter 和正文之间是否有空行检查占位符拼写。$ARGUMENT是整体引用$ARGUMENT1是按位置引用拼错或混用会导致参数为空或整段原样输出确认当前会话是否重新加载了模板。修改命令文件后旧会话里可能还缓存着旧版本新开会话再测如果命令执行报权限类错误检查allowed-tools白名单是否把命令需要调用的工具堵死了。我见过最让人抓狂的一次是命令没生效最后发现是终端里敲命令时多了一个空格斜杠命令被当成普通文本发送了。这种低级问题放在排查链路的第零步先确认你输入的命令名和文件名的精确匹配。6.3 我现在的维护节奏最后说下我当前的实际维护习惯。模板库不是一次性建完的而是跟着真实项目长出来的。我的节奏是每完成一个新项目阶段回顾哪些操作重复出现了三次以上如果重复了就抽成命令或写进 CLAUDE.md每个月做一次模板库清理删掉低频命令压缩过长的 CLAUDE.md。模板的版本写进项目 README升级模板后如果项目出现异常先回退模板版本再排查代码。这套 claude-code-templates 的玩法没有标准答案关键是把 AI 辅助编码从每次随机对话变成有沉淀、有版本、可复用的工程实践。你从两三个命令开始搭就行重要的是让模板跟着你的真实痛点长而不是一开始就堆一个庞大的体系。