1. 为什么模板对 Claude Code 如此关键用 Claude Code 写代码有段时间了我最大的感受是决定 AI 编程体验上限的往往不是模型本身有多大而是你喂给它的“上下文规则”写得好不好。claude-code-templates 这个主题说白了就是研究如何把项目背景、代码规范、工作流程这些东西沉淀成一套固定的模板文件让 Claude Code 一进入项目就能自动读取、自动遵守。这就像给新入职的工程师发一本《团队开发手册》而不是每天靠口头重复交代。很多刚接触 Claude Code 的朋友会走一个弯路拿到工具就直接开聊让 AI 帮忙写代码、改 bug、跑测试。初期确实能跑通但用多了就会发现几个典型的痛点同一个项目今天让它写的代码风格和昨天完全不一致它总是反复问你已经交代过无数次的技术栈细节更麻烦的是每次会话都要重新解释一遍项目结构上下文窗口被大量重复信息占满真正干活的“注意力”反而变少了。这些问题靠聊是解决不了的因为 AI 本身没有跨会话的长期记忆它只认当前终端里能看到什么、读取到什么。模板体系解决的就是这件事。它的核心思路是把人从重复劳动里解放出来你把项目的关键信息、约定、规范写进模板文件Claude Code 每次启动时自动加载这些文件让 AI 在动手之前就“知道”自己身处什么项目、该遵守什么规则、有哪些工具可用。这样做的好处是三重的——对个人来说项目切换成本大幅降低不用每次重建上下文对团队来说所有成员使用同一套模板AI 产出的代码风格和质量趋于一致对项目本身来说经验从人脑沉淀到了仓库里换人维护也不会丢失关键约束。这套思路适合谁来参考首先是用 Claude Code 做日常开发的个人开发者尤其是同时维护多个项目、需要频繁切换上下文的那批人其次是正在尝试把 AI 编码工具引入团队流程的工程负责人模板是让团队 AI 协作“标准化”的最低成本手段最后如果你还没用 Claude Code但对手头 AI 工具频繁出错的根因感兴趣这篇文章里的分层思路同样可以迁移到其他有自定义指令能力的工具上。接下来我会把模板体系的搭建过程、每个文件的写法、以及我踩过的坑一步步完整拆开来讲。2. 模板体系的分层设计与加载机制在动手写模板之前先要理解 Claude Code 的模板文件有哪些层级、各自在什么时候被加载。很多人一上来就往项目里塞一个大文件结果发现某些规则在别的项目也生效或者改了文件之后 AI 行为没有变化——这多半是没搞懂分层机制。2.1 全局层固定你的个人工作习惯全局层只有一个入口就是用户主目录下的~/.claude/CLAUDE.md。这个文件对当前机器上的所有项目生效适合放那些与具体业务无关、纯粹属于你个人工作方式的内容。举个例子我写前端代码时习惯用函数组件而不是 class 组件习惯在提交前跑一遍 lint习惯错误信息里带上上下文变量名——这些偏好放进全局模板就不用在每个项目里反复声明。全局层还有一个容易被忽视的用途定义“行为边界”。比如你希望 AI 默认不修改锁定文件、不主动执行git push、不删除注释代码这类安全红线放在全局是合理的因为它是跨项目的通用约束。不过要严格控制全局模板的篇幅它就像操作系统里的用户级配置塞太多东西会把所有项目都拖累一遍。~/.claude/目录下除了CLAUDE.md还可以放其他辅助配置但核心记忆文件就是这一个。实际操作中我见过有人把整个团队的编码规范复制进全局层结果换个项目风格对不上AI 生成的代码反而变得不伦不类——全局层只放“不变的你”不要放“某个项目的它”。2.2 项目层承载单一项目的完整画像项目层的入口是项目根目录下的CLAUDE.md。这是整个模板体系里最重要、也最需要花心思维护的文件。它承载的是这个项目独有的信息项目是干什么的、用了什么技术栈、目录结构怎么组织的、构建和测试命令是什么、代码里有哪些约定俗成的规矩、有哪些“绝对不能碰”的区域。Claude Code 会在会话启动时自动读取项目目录下的CLAUDE.md并且在你通过/init命令初始化模板时自动扫描项目代码生成一份初稿。这个自动生成的初稿通常能覆盖技术栈识别、构建命令检测、主要目录结构这些基础信息但远远不够——它读不懂你项目里的“潜规则”。比如某个接口的响应格式虽然叫UserInfo但实际字段里name是姓和名拼在一起的这种信息只有人写得出来。项目层模板需要持续迭代。我的习惯是每次 AI 在项目里犯了一个“如果它早点知道就不会犯”的错误就把它提炼成一条规则写进CLAUDE.md。这个文件不是写一次就完事的文档它是你和 AI 协作过程中的“经验沉淀池”是越用越值钱的核心资产。2.3 命令层把高频操作固化成斜杠命令如果你有一些反复使用、流程固定的操作——比如“帮我按团队规范审查本次改动的代码”“生成这个模块的单元测试”“把当前分支和主分支做一次差异分析”——每次都靠现场描述太浪费了。命令层就是为这个场景设计的在.claude/commands/目录下创建 Markdown 文件文件名就是斜杠命令的名字。创建review.md后你在对话里输入/review就会触发这个命令模板AI 按模板里定义的流程执行。命令模板是三层体系里最接近“函数封装”的一层。它不仅能传参——比如/review后面可以接文件名作为参数在模板正文里用$1、$2引用——还能通过 YAML 元信息声明这个命令需要哪些权限只读、允许编辑、可以执行命令。这一点很多人会忽略但实际用起来差别很大一个只读的审查命令和一个允许改代码的重构命令安全边界本来就该不同。命令层适合做什么代码审查、测试生成、提交信息生成、日志分析、依赖更新检查、接口文档生成……凡是你能清晰描述步骤的事都值得封装成命令。我自己的经验是一个命令模板如果连续用过三次以上就值得固化下来——这次多花十分钟下一次就是真正的一句话触发。2.4 技能层引入可复用的专业知识包技能层是 Claude Code 模板体系里更高级的形态对应的是.claude/skills/目录。每个技能是一个子目录里面包含SKILL.md作为技能描述文件还可以附带参考文档、脚本、示例代码。与项目记忆文件不同技能更强调“完成某一类专业任务的能力”——比如“为 Python 项目编写符合规范的单元测试”是一个技能“执行一次完整的依赖安全审计”也是一个技能。打个比方CLAUDE.md告诉 AI“你是谁、你在哪、规矩是什么”而技能告诉 AI“这个领域的活儿该怎么干”。技能文件里可以写一套可执行的操作流程比如先检查项目有哪些测试框架依赖再确认测试目录结构然后识别被测模块的依赖关系最后生成测试骨架。这套流程可以被不同的项目复用只要那个项目也需要这种能力。技能目录里除了SKILL.md还可以放参考文件AI 在需要时会主动去读取。这就让技能的复杂度可以做得比较高——它不再是一页纸的说明而是一个可以携带“附件”的知识包。不过技能层也是四层里最容易过度设计的我的建议是先从CLAUDE.md和命令层用起等项目里真正出现了需要专业知识才能完成的任务再考虑沉淀技能。下面这张表可以帮你快速对照四层模板的定位层级文件位置生效范围适合放什么全局模板~/.claude/CLAUDE.md当前机器所有项目个人习惯、通用红线、默认偏好项目模板项目根目录CLAUDE.md当前项目项目画像、技术栈、命令、规范命令模板.claude/commands/*.md当前项目手动触发高频操作流程、固定审查步骤技能模板.claude/skills/*/SKILL.md当前项目按需读取专业知识、可复用任务流程3. 核心模板写法从入门到可落地的完整范例有了分层设计的框架接下来要看每一层具体怎么写。这一节我会给出几个可以直接套用的模板示例并逐段解释为什么这样写、关键点在哪儿。写模板和写代码有一个共同点看得懂和写得好是两回事真正决定质量的是细节。3.1 项目画像模板一页纸说清项目全貌CLAUDE.md里最核心的部分是项目画像。下面是一个 Python FastAPI 项目的示例它覆盖了 AI 干活前需要掌握的基本盘# 项目订单服务 ## 项目概述 订单服务是电商系统的核心模块负责订单创建、支付回调、退款处理。 服务采用微服务架构通过 HTTP 与用户服务、库存服务交互。 ## 技术栈 - Python 3.11 / FastAPI - PostgreSQL 15通过 SQLAlchemy 2.0 ORM 访问 - Redis 7缓存与分布式锁 - Docker Compose 管理本地依赖生产环境使用 Kubernetes ## 目录结构 - app/api/ HTTP 路由层只做参数校验与响应组装 - app/services/ 业务逻辑层核心决策都在这一层 - app/repositories/ 数据访问层禁止在这一层写业务逻辑 - tests/ 单元测试目录镜像 app 的包结构 ## 常用命令 - 安装依赖poetry install - 本地启动docker compose up -d poetry run uvicorn app.main:app --reload - 跑单元测试poetry run pytest tests/ -x -q - 跑 lintpoetry run ruff check app/ tests/ ## 代码约定 - 模型层禁止出现业务逻辑所有数据操作走仓库层 - 对外接口统一返回 {code: 0, data: ..., message: ok} 结构 - 数据库事务必须使用 transactional 装饰器禁止手动 commit/rollback - 日志必须包含 request_id用 logger.bind(request_idrequest_id) 输出 - 时间字段一律用 UTC 存储接口输出转本地时区 ## 红线 - 禁止直接修改数据库表结构schema 变更必须走迁移文件 - 禁止在 API 层直接调用 ORM 查询 - 禁止删除或改动 tests/ 下已有的测试用例这个模板的核心在于“可执行”。你不光说了技术栈是什么还说了代码该怎么分层的边界在哪不光说了要写日志还具体到用什么 API 带什么字段。AI 是概率模型它需要在模糊地带被规则校准——规则写得越具体输出偏差就越小。3.2 自定义命令模板审查流程也能标准化自定义命令是提升效率最直观的一层。以我最常用的代码审查命令为例.claude/commands/review.md的内容大概是这样的--- description: 按团队规范审查本次改动 agent: code allowed-tools: read, grep, glob --- 请对当前分支的代码改动做一次全面审查。 ## 步骤 1. 先运行 git diff main...HEAD --stat了解改动涉及哪些文件 2. 逐个文件阅读 diff 内容重点关注业务逻辑和异常处理 3. 对照项目 CLAUDE.md 中的代码约定逐项检查是否违反 ## 审查要点 - 是否有明显逻辑错误比如空指针、越界、资源未释放 - 是否缺少异常处理网络请求和文件操作是否做了失败兜底 - 是否有调试残留代码比如 print、临时注释、写死的测试数据 - 是否引入不必要的外部依赖 - 数据库操作是否在事务内完成 - 新增代码是否缺少对应的测试用例 ## 输出格式 按文件分组输出审查结果每个问题标注严重级别 - [严重] 会引发线上事故的缺陷 - [建议] 不影响正确性但影响可维护性的问题 - [疑问] 需要人确认的业务逻辑不确定点 最后用一段话总结改动的整体质量用 5 分制打分并说明理由。注意头部的allowed-tools字段。审查这个动作本质上只需要读代码不需要改任何东西所以我把工具权限限制为read, grep, glob不允许它直接编辑文件或执行写操作。这样设计的好处是安全——即使命令写得不完美最坏的结果也只是得到了一个不准的审查意见而不会引发文件被误改的问题。同理如果你要写一个自动化重构命令你就得显式声明允许编辑文件这是设计命令模板时的基本安全素养。3.3 测试生成模板把“写测试”变成“套流程”很多开发者的痛点是让 AI 写测试写出来的东西看着像那么回事实际跑起来要么断言语义不通要么 mock 了一堆不该 mock 的内部实现。用一个测试生成模板能改善很多。.claude/commands/test.md示例--- description: 为指定模块生成单元测试 agent: code allowed-tools: read, grep, glob, edit, run --- 为 {module} 模块生成单元测试。 ## 遵循规则 1. 先阅读被测模块源码梳理出所有对外公开的函数和类 2. 阅读 tests/ 目录下已有的测试风格保持一致 3. 只 mock 外部服务比如 Redis、PostgreSQL不要 mock 被测模块内部的私有函数 4. 每个测试用例必须有明确的断言禁止只跑通不校验 5. 测试命名使用 test_ 前缀描述具体场景比如 test_create_order_when_stock_not_enough 6. 覆盖正常路径、边界值和异常路径三个维度 ## 输出格式 - 在 tests/ 对应目录创建测试文件 - 文件开头注明被测模块路径和测试日期 - 执行测试并提供结果摘要失败用例需要给出原因分析这个模板之所以强调“只 mock 外部服务不 mock 内部私有函数”是因为很多 AI 生成的测试实际上是在确认“被测试代码自己的逻辑没变”而不是在验证“行为符合预期”——这种测试对工程质量没有任何帮助。模板把这些原则写进去相当于在 AI 动手之前就把它引到了正确的方向上。这里的{module}就是一个参数占位符使用/test app/services/order_service.py这行命令时{module}会被替换成app/services/order_service.py命令层天然支持这种参数化。3.4 规范约束模板把团队约定翻译成 AI 能懂的语言团队通常有自己的编码规范问题是规范文档往往写得很“人类友好”充满了“请合理处理异常”“保持代码整洁”这类模糊表达。AI 无法从这种话里学到什么。规范模板要做的是翻译工作把约定翻译成 AI 可判定的语句。看一组对比模糊写法注意正确处理错误模板写法函数入口处必须用 try/except 包裹 IO 操作except 分支里必须记录日志并返回业务错误码禁止静默吞掉异常模糊写法代码要写清楚模板写法函数体超过 50 行必须拆分变量命名禁止用缩写注释只解释“为什么”不解释“做了什么”模糊写法保证性能模板写法禁止在循环体内执行数据库查询如有需要应先查出全量数据再内存过滤批量写入必须使用 bulk 操作你可以看到模板写法里每一句都是可以在代码 review 时直接检查的规则。AI 对“合理”“清楚”这类词是无感的但对“超过 50 行必须拆分”这种带阈值和方向的句子有非常好的响应。整理规范模板时最好的素材来源就是团队代码 review 时反复提出的意见——那些反反复复被说的问题就是最值得固化成模板的规则。4. 实操过程一套完整模板的组装与落地理论讲完了下面跟着我实际走一遍完整的搭建流程。这次以我之前接手的一个订单服务项目为例目标是让 Claude Code 在这个项目里“熟悉得像老员工”。整个流程按准备、初始化、命令创建、验证迭代四个阶段来做。4.1 准备阶段先盘点项目现状动手写模板之前先用 20 分钟把项目信息整理清楚。我一般会拿一张纸或临时文档记下这五类信息项目一句话简介和核心业务面技术栈清单语言版本、框架、数据库、缓存、消息队列目录结构和各层职责边界完整的构建、测试、lint 命令代码里已经存在的、不成文但大家遵守的约定这个过程不需要写得多漂亮甚至可以用零散的关键词记录关键是信息要准确、完整。你后面所有模板内容都依赖这次盘点如果技术栈版本写错了AI 生成的代码可能直接按错误版本来写。比如 Python 依赖管理用的是 Poetry 还是 pip requirements.txt这决定了它生成新依赖时该用哪种命令。我见过很多人跳过这一步直接让/init自动生成结果生成的 CLAUDE.md 里测试命令还是默认的 unittest而项目实际用的是 pytest——这种基础错误会在后面无数次降低 AI 产出质量。所以哪怕/init的结果再方便人工核对这些事实信息仍然是必不可少的环节。4.2 初始化与人工增补让模板既自动又准确在项目根目录启动 Claude Code然后输入/init。它会自动扫描项目代码生成一份初始的CLAUDE.md其中通常包含依赖文件解析出的技术栈、项目结构、检测到的构建命令。这份初稿的正确率视项目复杂度而定简单项目可能达到七成复杂项目常常只有四五成特别是那些依赖多个服务的项目AI 判断不了服务之间的调用关系和部署结构。拿到初稿后把我在准备阶段记录的笔记和它逐项对照。技术栈有没有漏项目录结构是否和实际一致命令是否准确这些事实性的东西直接修订。接下来做增补也就是把准备阶段的第五类信息“项目里不成文的约定”写进去。这些约定一般是自动生成永远发现不了的比如“订单金额字段是分不是元”“支付回调必须做幂等处理”“状态流转只能用状态机定义的接口”。这些信息对 AI 提升最大也最依赖人来做。增补完成后把CLAUDE.md通读一遍站在一个刚入职的工程师视角提问如果我是新人看到这份文档能立刻上手改代码吗如果有哪些地方还需要问才能动手那就是模板还缺信息的地方。反复调到不再产生歧义为止。4.3 创建命令模板从复用频率最高的事开始项目级 CLAUDE.md 就位后下一步是创建自定义命令。我的建议是先创建第一个你高频使用的命令通常是代码审查或者测试生成。在项目根目录执行mkdir -p .claude/commands然后用编辑器创建.claude/commands/review.md把之前演示的审查命令内容填进去。这里有几个创建命令时的实际操作要点第一命令文件最好纳入版本管理它和业务代码一样需要 review 和变更记录。第二每个命令只聚焦一件事。如果你想做“审查改动并修复发现的问题”那是一个新命令review-and-fix.md不要在review.md里既要求只读审查又要求自动修复这两件事的安全边界完全不同。第三命令名用英文短横线命名触发时用斜杠加名字比如/review和/review-and-fix。创建完第一个命令后先不要急着批量造命令而是花几天时间正常使用 Claude Code把那些“你想重复用但发现没有命令支撑”的操作记下来。等积累到三五个候选场景时再一起创建对应的命令模板。这样做的理由是你的命令模板应该来自真实需求而不是凭空想象的“完美流程”。凭空想出来的命令往往步骤过于复杂、用一两次就闲置了而来自真实痛点的命令每个都能持续用下去。4.4 参数与命令的取舍为什么这么配置在初始化过程中有几个参数值得专门解释一下。一个是/init命令本身它除了生成CLAUDE.md还可以配置permissions相关的选项比如允许 AI 在哪些目录下写文件、禁止访问哪些路径。以订单服务为例我会在权限配置里把deploy/和migrations/目录设为只读因为这两个目录里的内容一旦被 AI 改动后果非常严重。这个操作在命令层的 YAML 元信息里也有体现但项目级权限配置的约束力更强适合做全局兜底。另一个是命令模板里agent字段的选择。Claude Code 里有不同的代理模式通用代码任务是code如果某个命令需要更强的执行能力比如运行数据迁移、批量重命名文件可能需要选general代理并赋予更多的工具权限。但这里有个经验性的原则默认使用最小权限只有在遇到实际报错提示“权限不足”时才考虑提升某个命令的权限等级。一来是安全考虑二来是权限越小AI 越不会在执行任务时“跑偏”去做计划外的操作。最后命令模板里的$1参数和{module}这类占位符的命名也值得讲究。参数名要能让你快速理解该传什么比如{module}、{filename}、{branch_name}而不是抽象的{arg1}。参数太少会让命令过于笼统参数太多会让使用成本变高——一个命令两三个参数是比较舒服的状态。4.5 验证与迭代让模板在真实使用中升级模板创建完不是终点。我第一次给订单服务配完模板后做了这样一轮验证故意挑了一个不太熟悉的模块让 Claude Code 在里面完成一个小需求比如“为折扣规则模块增加一个新的折扣类型”。这个过程能直观检验模板质量如果 AI 一次就找对了文件位置、遵守了分层约束、生成的代码和项目风格一致、测试也一次通过说明模板合格。如果它找错了文件、生成了和现有风格冲突的代码说明模板里缺少了能纠正它的信息。一个更系统化的验证方法是跑一个“基线测试”在没有模板的情况下让 AI 完成一个标准小任务记录结果然后应用模板后再跑同一个任务对比两次的质量差异。这个对比能让你清楚看到模板究竟解决了什么问题。大部分项目的改善是显著的——代码风格更统一了、不再问重复问题、构建命令也顺便跑对了——但具体好在哪里用对比说话最直观。迭代方面我的习惯是建立一个“模板更新日志”每次往模板里加规则时顺手记一行今天因为什么事加了什么规则。这不仅是给自己留档案也能帮你发现规律——比如日志显示大多数新增规则都是因为 AI 在处理日期格式时犯错那你就知道该在模板里把日期处理的规范写得更显眼。5. 常见问题与排查技巧实录模板体系用久了什么情况都可能遇到。这一节我把实际踩过的坑和对应的排查思路整理出来按症状分类方便你快速定位问题。5.1CLAUDE.md为什么“不生效”这是被问得最多的一个问题而且大多数情况不是真的不生效而是改了文件但当前会话还在用旧缓存。Claude Code 对项目模板文件的读取时机是会话启动时所以你在一个已经打开的会话里修改CLAUDE.md后AI 是不会自动感知的。排查的第一步是重启会话看看新规则是否被加载。如果重启也没用那就检查文件位置。CLAUDE.md必须位于项目根目录。很多时候你的项目其实在一个子目录里比如 monorepo 结构下的某个服务包你把文件放到了仓库根目录而 Claude Code 是在子目录启动的那就读不到。解决办法是在子目录里再建一份针对性的CLAUDE.md或者每次从正确的目录启动工具。还有一种概率更低但也发生过的情况文件名拼写错误比如CLAUDE.md被写成了CLAUDD.md或者小写的claude.md。这类错误通常发生在手动创建文件而非用/init生成时。遇到怎么改都没反应的情况先检查文件名是不是和约定完全一致。5.2 模板文件太长导致上下文被挤占有些项目模板越写越长几千字的CLAUDE.md虽然信息丰富但每次会话都会完整加载Tokenizer 一算就是好几千 token。如果模板内容和当前任务没关系这些 token 就全浪费了反而压缩了真正的代码上下文空间。解决这个问题有两个方向。一是精简模板把“常识性内容”删掉只保留项目独有的信息。比如“写代码前先想清楚逻辑”这种废话不要写留出空间给真正有用的规范。二是利用 Claude Code 的引用机制把不常用的细节内容拆到单独的文件里在CLAUDE.md中按需引用。比如把完整的数据库表结构放到docs/db_schema.md只在CLAUDE.md里用docs/db_schema.md引用这样相关任务时 AI 才会去读取明细。我实际对比过精简后的项目模板通常能减少 30% 到 50% 的记忆文件 token 占用而信息覆盖度几乎不变。5.3 自定义命令不出现、名称冲突、参数传不进斜杠命令在输入/时会有自动补全列表如果命令没出现先确认文件是不是放在了.claude/commands/目录下文件名后缀是不是.md。命令系统不识别子目录中的其他命名规则也不支持文件名里带空格。命令名称冲突也是常见问题。如果你在项目里定义了/review而另一个命令文件叫review-and-fix.md触发/review时可能会产生歧义。更严重的冲突是与内置命令重名比如你定义一个/init命令去覆盖内置行为这种行为大概率不会按你的预期工作还可能让会话状态混乱。命名时加项目前缀是最省心的做法比如/order-review、/order-test。参数传不进的原因通常是模板里的占位符语法写错了。命令层的参数引用有两种风格一种是顺序参数$1、$2一种是命名参数{param_name}。如果你在同一个文件里混用了两种风格解析器可能只识别其中一种。统一用命名参数是最稳妥的命令正文里写{module}使用时输入/test app/services/order_service.py解析器会自动把路径填入。如果你的参数带空格比如文件名里有空格用引号包起来再传。5.4 AI 反复无视模板里的规则怎么办这是最让人头疼的问题。你明明在CLAUDE.md里写了“禁止在 API 层直接调用 ORM 查询”它还是会生成这种代码。遇到这种情况先别急着怪模型优先检查你的规则写法是不是足够“可判定”。对比一下“禁止在 API 层直接调用 ORM 查询”和“API 层路由函数内只允许调用 service 层函数所有数据查询通过 service 层转到 repository 层执行”——后者在代码审查时一眼就能判断是否违规前者还需要人先理解什么算“直接调用”模型的语境理解自然更模糊。如果规则本身够具体了AI 还是偶尔无视那就需要提升规则在会话中的显眼程度。Claude Code 对CLAUDE.md中的内容并不会逐字严格算作硬性约束规则写在不显眼的位置时被模型“遗忘”的概率会更高。把最重要的红线规则放在文件开头、用加粗或强烈的语气表述比如“这是本项目最高优先级约束不得违反……”实测下来显著减少违规次数。也可以把关键规则同时写进命令模板里在任务执行前再强调一遍——上下文里重复出现的约束会被模型更牢固地记住。5.5 团队协作场景的模板管理技巧当模板文件被纳入版本管理后新的问题出现了团队成员的模板更新不同步、Pull Request 里对模板的修改没有人 review、有人擅自往CLAUDE.md里塞入大量无关的个人偏好。我在实际协作中总结了一些做法第一模板的变更走和代码一样的审查流程。CLAUDE.md的每一次改动都应该能在 Pull Request 里被看到、被讨论。不要直接推到主分支更不要通过即时聊天工具发文件给队友手动替换。第二区分个人偏好和团队规范。个人习惯比如个人默认用的包管理器放在全局层团队约定比如接口返回结构、事务使用方式放在项目层。如果项目模板里混入了太多个人风格队友使用时会觉得 AI 生成的东西“别扭”但又说不上来哪里不对。第三为模板文件单独建一个维护说明。在项目根目录放一个CLAUDE-MAINTENANCE.md说明哪些文件是模板、各自的作用范围、改动时需要注意什么。新成员接手时不至于把命令模板删了还不知道怎么恢复。下面是一张速查表汇总了模板体系的常见问题症状优先排查点解决方案改了模板没反应会话缓存重启会话再测试新规则不生效文件位置/文件名确认在项目根目录、拼写正确上下文占用过高模板太长精简内容、用 引用拆分命令不出现目录/文件名放到.claude/commands/下命令冲突重名使用项目前缀区分参数传不进占位符语法统一用命名参数{name}规则被无视规则太模糊改写为可判定语句置于显眼位置我个人在实际操作中最大的体会是模板体系不是一蹴而就的工程而是一个持续演化的系统。不要追求第一天就写出完美的CLAUDE.md——先搭一个能覆盖项目基本盘的版本用起来然后在每次 AI 犯错时反问一句这个错误是否可以通过更新模板来预防如果可以就顺手把规则补进去。用这样的节奏迭代一个月你的模板会变得非常贴合项目实际而你也会对“AI 到底需要什么样的信息才能把活干好”这件事有更深的理解。如果你正打算自己搭一套模板我的最后一个小建议是把模板当成代码认真对待给它写维护记录、做结构设计、时常重构不要怕推翻重来。一套好用的模板能带来的效率提升可能比你换一个更“聪明”的模型还要明显。 Claude Code 模板体系实战：从 CLAUDE.md 到自定义命令
1. 为什么模板对 Claude Code 如此关键用 Claude Code 写代码有段时间了我最大的感受是决定 AI 编程体验上限的往往不是模型本身有多大而是你喂给它的“上下文规则”写得好不好。claude-code-templates 这个主题说白了就是研究如何把项目背景、代码规范、工作流程这些东西沉淀成一套固定的模板文件让 Claude Code 一进入项目就能自动读取、自动遵守。这就像给新入职的工程师发一本《团队开发手册》而不是每天靠口头重复交代。很多刚接触 Claude Code 的朋友会走一个弯路拿到工具就直接开聊让 AI 帮忙写代码、改 bug、跑测试。初期确实能跑通但用多了就会发现几个典型的痛点同一个项目今天让它写的代码风格和昨天完全不一致它总是反复问你已经交代过无数次的技术栈细节更麻烦的是每次会话都要重新解释一遍项目结构上下文窗口被大量重复信息占满真正干活的“注意力”反而变少了。这些问题靠聊是解决不了的因为 AI 本身没有跨会话的长期记忆它只认当前终端里能看到什么、读取到什么。模板体系解决的就是这件事。它的核心思路是把人从重复劳动里解放出来你把项目的关键信息、约定、规范写进模板文件Claude Code 每次启动时自动加载这些文件让 AI 在动手之前就“知道”自己身处什么项目、该遵守什么规则、有哪些工具可用。这样做的好处是三重的——对个人来说项目切换成本大幅降低不用每次重建上下文对团队来说所有成员使用同一套模板AI 产出的代码风格和质量趋于一致对项目本身来说经验从人脑沉淀到了仓库里换人维护也不会丢失关键约束。这套思路适合谁来参考首先是用 Claude Code 做日常开发的个人开发者尤其是同时维护多个项目、需要频繁切换上下文的那批人其次是正在尝试把 AI 编码工具引入团队流程的工程负责人模板是让团队 AI 协作“标准化”的最低成本手段最后如果你还没用 Claude Code但对手头 AI 工具频繁出错的根因感兴趣这篇文章里的分层思路同样可以迁移到其他有自定义指令能力的工具上。接下来我会把模板体系的搭建过程、每个文件的写法、以及我踩过的坑一步步完整拆开来讲。2. 模板体系的分层设计与加载机制在动手写模板之前先要理解 Claude Code 的模板文件有哪些层级、各自在什么时候被加载。很多人一上来就往项目里塞一个大文件结果发现某些规则在别的项目也生效或者改了文件之后 AI 行为没有变化——这多半是没搞懂分层机制。2.1 全局层固定你的个人工作习惯全局层只有一个入口就是用户主目录下的~/.claude/CLAUDE.md。这个文件对当前机器上的所有项目生效适合放那些与具体业务无关、纯粹属于你个人工作方式的内容。举个例子我写前端代码时习惯用函数组件而不是 class 组件习惯在提交前跑一遍 lint习惯错误信息里带上上下文变量名——这些偏好放进全局模板就不用在每个项目里反复声明。全局层还有一个容易被忽视的用途定义“行为边界”。比如你希望 AI 默认不修改锁定文件、不主动执行git push、不删除注释代码这类安全红线放在全局是合理的因为它是跨项目的通用约束。不过要严格控制全局模板的篇幅它就像操作系统里的用户级配置塞太多东西会把所有项目都拖累一遍。~/.claude/目录下除了CLAUDE.md还可以放其他辅助配置但核心记忆文件就是这一个。实际操作中我见过有人把整个团队的编码规范复制进全局层结果换个项目风格对不上AI 生成的代码反而变得不伦不类——全局层只放“不变的你”不要放“某个项目的它”。2.2 项目层承载单一项目的完整画像项目层的入口是项目根目录下的CLAUDE.md。这是整个模板体系里最重要、也最需要花心思维护的文件。它承载的是这个项目独有的信息项目是干什么的、用了什么技术栈、目录结构怎么组织的、构建和测试命令是什么、代码里有哪些约定俗成的规矩、有哪些“绝对不能碰”的区域。Claude Code 会在会话启动时自动读取项目目录下的CLAUDE.md并且在你通过/init命令初始化模板时自动扫描项目代码生成一份初稿。这个自动生成的初稿通常能覆盖技术栈识别、构建命令检测、主要目录结构这些基础信息但远远不够——它读不懂你项目里的“潜规则”。比如某个接口的响应格式虽然叫UserInfo但实际字段里name是姓和名拼在一起的这种信息只有人写得出来。项目层模板需要持续迭代。我的习惯是每次 AI 在项目里犯了一个“如果它早点知道就不会犯”的错误就把它提炼成一条规则写进CLAUDE.md。这个文件不是写一次就完事的文档它是你和 AI 协作过程中的“经验沉淀池”是越用越值钱的核心资产。2.3 命令层把高频操作固化成斜杠命令如果你有一些反复使用、流程固定的操作——比如“帮我按团队规范审查本次改动的代码”“生成这个模块的单元测试”“把当前分支和主分支做一次差异分析”——每次都靠现场描述太浪费了。命令层就是为这个场景设计的在.claude/commands/目录下创建 Markdown 文件文件名就是斜杠命令的名字。创建review.md后你在对话里输入/review就会触发这个命令模板AI 按模板里定义的流程执行。命令模板是三层体系里最接近“函数封装”的一层。它不仅能传参——比如/review后面可以接文件名作为参数在模板正文里用$1、$2引用——还能通过 YAML 元信息声明这个命令需要哪些权限只读、允许编辑、可以执行命令。这一点很多人会忽略但实际用起来差别很大一个只读的审查命令和一个允许改代码的重构命令安全边界本来就该不同。命令层适合做什么代码审查、测试生成、提交信息生成、日志分析、依赖更新检查、接口文档生成……凡是你能清晰描述步骤的事都值得封装成命令。我自己的经验是一个命令模板如果连续用过三次以上就值得固化下来——这次多花十分钟下一次就是真正的一句话触发。2.4 技能层引入可复用的专业知识包技能层是 Claude Code 模板体系里更高级的形态对应的是.claude/skills/目录。每个技能是一个子目录里面包含SKILL.md作为技能描述文件还可以附带参考文档、脚本、示例代码。与项目记忆文件不同技能更强调“完成某一类专业任务的能力”——比如“为 Python 项目编写符合规范的单元测试”是一个技能“执行一次完整的依赖安全审计”也是一个技能。打个比方CLAUDE.md告诉 AI“你是谁、你在哪、规矩是什么”而技能告诉 AI“这个领域的活儿该怎么干”。技能文件里可以写一套可执行的操作流程比如先检查项目有哪些测试框架依赖再确认测试目录结构然后识别被测模块的依赖关系最后生成测试骨架。这套流程可以被不同的项目复用只要那个项目也需要这种能力。技能目录里除了SKILL.md还可以放参考文件AI 在需要时会主动去读取。这就让技能的复杂度可以做得比较高——它不再是一页纸的说明而是一个可以携带“附件”的知识包。不过技能层也是四层里最容易过度设计的我的建议是先从CLAUDE.md和命令层用起等项目里真正出现了需要专业知识才能完成的任务再考虑沉淀技能。下面这张表可以帮你快速对照四层模板的定位层级文件位置生效范围适合放什么全局模板~/.claude/CLAUDE.md当前机器所有项目个人习惯、通用红线、默认偏好项目模板项目根目录CLAUDE.md当前项目项目画像、技术栈、命令、规范命令模板.claude/commands/*.md当前项目手动触发高频操作流程、固定审查步骤技能模板.claude/skills/*/SKILL.md当前项目按需读取专业知识、可复用任务流程3. 核心模板写法从入门到可落地的完整范例有了分层设计的框架接下来要看每一层具体怎么写。这一节我会给出几个可以直接套用的模板示例并逐段解释为什么这样写、关键点在哪儿。写模板和写代码有一个共同点看得懂和写得好是两回事真正决定质量的是细节。3.1 项目画像模板一页纸说清项目全貌CLAUDE.md里最核心的部分是项目画像。下面是一个 Python FastAPI 项目的示例它覆盖了 AI 干活前需要掌握的基本盘# 项目订单服务 ## 项目概述 订单服务是电商系统的核心模块负责订单创建、支付回调、退款处理。 服务采用微服务架构通过 HTTP 与用户服务、库存服务交互。 ## 技术栈 - Python 3.11 / FastAPI - PostgreSQL 15通过 SQLAlchemy 2.0 ORM 访问 - Redis 7缓存与分布式锁 - Docker Compose 管理本地依赖生产环境使用 Kubernetes ## 目录结构 - app/api/ HTTP 路由层只做参数校验与响应组装 - app/services/ 业务逻辑层核心决策都在这一层 - app/repositories/ 数据访问层禁止在这一层写业务逻辑 - tests/ 单元测试目录镜像 app 的包结构 ## 常用命令 - 安装依赖poetry install - 本地启动docker compose up -d poetry run uvicorn app.main:app --reload - 跑单元测试poetry run pytest tests/ -x -q - 跑 lintpoetry run ruff check app/ tests/ ## 代码约定 - 模型层禁止出现业务逻辑所有数据操作走仓库层 - 对外接口统一返回 {code: 0, data: ..., message: ok} 结构 - 数据库事务必须使用 transactional 装饰器禁止手动 commit/rollback - 日志必须包含 request_id用 logger.bind(request_idrequest_id) 输出 - 时间字段一律用 UTC 存储接口输出转本地时区 ## 红线 - 禁止直接修改数据库表结构schema 变更必须走迁移文件 - 禁止在 API 层直接调用 ORM 查询 - 禁止删除或改动 tests/ 下已有的测试用例这个模板的核心在于“可执行”。你不光说了技术栈是什么还说了代码该怎么分层的边界在哪不光说了要写日志还具体到用什么 API 带什么字段。AI 是概率模型它需要在模糊地带被规则校准——规则写得越具体输出偏差就越小。3.2 自定义命令模板审查流程也能标准化自定义命令是提升效率最直观的一层。以我最常用的代码审查命令为例.claude/commands/review.md的内容大概是这样的--- description: 按团队规范审查本次改动 agent: code allowed-tools: read, grep, glob --- 请对当前分支的代码改动做一次全面审查。 ## 步骤 1. 先运行 git diff main...HEAD --stat了解改动涉及哪些文件 2. 逐个文件阅读 diff 内容重点关注业务逻辑和异常处理 3. 对照项目 CLAUDE.md 中的代码约定逐项检查是否违反 ## 审查要点 - 是否有明显逻辑错误比如空指针、越界、资源未释放 - 是否缺少异常处理网络请求和文件操作是否做了失败兜底 - 是否有调试残留代码比如 print、临时注释、写死的测试数据 - 是否引入不必要的外部依赖 - 数据库操作是否在事务内完成 - 新增代码是否缺少对应的测试用例 ## 输出格式 按文件分组输出审查结果每个问题标注严重级别 - [严重] 会引发线上事故的缺陷 - [建议] 不影响正确性但影响可维护性的问题 - [疑问] 需要人确认的业务逻辑不确定点 最后用一段话总结改动的整体质量用 5 分制打分并说明理由。注意头部的allowed-tools字段。审查这个动作本质上只需要读代码不需要改任何东西所以我把工具权限限制为read, grep, glob不允许它直接编辑文件或执行写操作。这样设计的好处是安全——即使命令写得不完美最坏的结果也只是得到了一个不准的审查意见而不会引发文件被误改的问题。同理如果你要写一个自动化重构命令你就得显式声明允许编辑文件这是设计命令模板时的基本安全素养。3.3 测试生成模板把“写测试”变成“套流程”很多开发者的痛点是让 AI 写测试写出来的东西看着像那么回事实际跑起来要么断言语义不通要么 mock 了一堆不该 mock 的内部实现。用一个测试生成模板能改善很多。.claude/commands/test.md示例--- description: 为指定模块生成单元测试 agent: code allowed-tools: read, grep, glob, edit, run --- 为 {module} 模块生成单元测试。 ## 遵循规则 1. 先阅读被测模块源码梳理出所有对外公开的函数和类 2. 阅读 tests/ 目录下已有的测试风格保持一致 3. 只 mock 外部服务比如 Redis、PostgreSQL不要 mock 被测模块内部的私有函数 4. 每个测试用例必须有明确的断言禁止只跑通不校验 5. 测试命名使用 test_ 前缀描述具体场景比如 test_create_order_when_stock_not_enough 6. 覆盖正常路径、边界值和异常路径三个维度 ## 输出格式 - 在 tests/ 对应目录创建测试文件 - 文件开头注明被测模块路径和测试日期 - 执行测试并提供结果摘要失败用例需要给出原因分析这个模板之所以强调“只 mock 外部服务不 mock 内部私有函数”是因为很多 AI 生成的测试实际上是在确认“被测试代码自己的逻辑没变”而不是在验证“行为符合预期”——这种测试对工程质量没有任何帮助。模板把这些原则写进去相当于在 AI 动手之前就把它引到了正确的方向上。这里的{module}就是一个参数占位符使用/test app/services/order_service.py这行命令时{module}会被替换成app/services/order_service.py命令层天然支持这种参数化。3.4 规范约束模板把团队约定翻译成 AI 能懂的语言团队通常有自己的编码规范问题是规范文档往往写得很“人类友好”充满了“请合理处理异常”“保持代码整洁”这类模糊表达。AI 无法从这种话里学到什么。规范模板要做的是翻译工作把约定翻译成 AI 可判定的语句。看一组对比模糊写法注意正确处理错误模板写法函数入口处必须用 try/except 包裹 IO 操作except 分支里必须记录日志并返回业务错误码禁止静默吞掉异常模糊写法代码要写清楚模板写法函数体超过 50 行必须拆分变量命名禁止用缩写注释只解释“为什么”不解释“做了什么”模糊写法保证性能模板写法禁止在循环体内执行数据库查询如有需要应先查出全量数据再内存过滤批量写入必须使用 bulk 操作你可以看到模板写法里每一句都是可以在代码 review 时直接检查的规则。AI 对“合理”“清楚”这类词是无感的但对“超过 50 行必须拆分”这种带阈值和方向的句子有非常好的响应。整理规范模板时最好的素材来源就是团队代码 review 时反复提出的意见——那些反反复复被说的问题就是最值得固化成模板的规则。4. 实操过程一套完整模板的组装与落地理论讲完了下面跟着我实际走一遍完整的搭建流程。这次以我之前接手的一个订单服务项目为例目标是让 Claude Code 在这个项目里“熟悉得像老员工”。整个流程按准备、初始化、命令创建、验证迭代四个阶段来做。4.1 准备阶段先盘点项目现状动手写模板之前先用 20 分钟把项目信息整理清楚。我一般会拿一张纸或临时文档记下这五类信息项目一句话简介和核心业务面技术栈清单语言版本、框架、数据库、缓存、消息队列目录结构和各层职责边界完整的构建、测试、lint 命令代码里已经存在的、不成文但大家遵守的约定这个过程不需要写得多漂亮甚至可以用零散的关键词记录关键是信息要准确、完整。你后面所有模板内容都依赖这次盘点如果技术栈版本写错了AI 生成的代码可能直接按错误版本来写。比如 Python 依赖管理用的是 Poetry 还是 pip requirements.txt这决定了它生成新依赖时该用哪种命令。我见过很多人跳过这一步直接让/init自动生成结果生成的 CLAUDE.md 里测试命令还是默认的 unittest而项目实际用的是 pytest——这种基础错误会在后面无数次降低 AI 产出质量。所以哪怕/init的结果再方便人工核对这些事实信息仍然是必不可少的环节。4.2 初始化与人工增补让模板既自动又准确在项目根目录启动 Claude Code然后输入/init。它会自动扫描项目代码生成一份初始的CLAUDE.md其中通常包含依赖文件解析出的技术栈、项目结构、检测到的构建命令。这份初稿的正确率视项目复杂度而定简单项目可能达到七成复杂项目常常只有四五成特别是那些依赖多个服务的项目AI 判断不了服务之间的调用关系和部署结构。拿到初稿后把我在准备阶段记录的笔记和它逐项对照。技术栈有没有漏项目录结构是否和实际一致命令是否准确这些事实性的东西直接修订。接下来做增补也就是把准备阶段的第五类信息“项目里不成文的约定”写进去。这些约定一般是自动生成永远发现不了的比如“订单金额字段是分不是元”“支付回调必须做幂等处理”“状态流转只能用状态机定义的接口”。这些信息对 AI 提升最大也最依赖人来做。增补完成后把CLAUDE.md通读一遍站在一个刚入职的工程师视角提问如果我是新人看到这份文档能立刻上手改代码吗如果有哪些地方还需要问才能动手那就是模板还缺信息的地方。反复调到不再产生歧义为止。4.3 创建命令模板从复用频率最高的事开始项目级 CLAUDE.md 就位后下一步是创建自定义命令。我的建议是先创建第一个你高频使用的命令通常是代码审查或者测试生成。在项目根目录执行mkdir -p .claude/commands然后用编辑器创建.claude/commands/review.md把之前演示的审查命令内容填进去。这里有几个创建命令时的实际操作要点第一命令文件最好纳入版本管理它和业务代码一样需要 review 和变更记录。第二每个命令只聚焦一件事。如果你想做“审查改动并修复发现的问题”那是一个新命令review-and-fix.md不要在review.md里既要求只读审查又要求自动修复这两件事的安全边界完全不同。第三命令名用英文短横线命名触发时用斜杠加名字比如/review和/review-and-fix。创建完第一个命令后先不要急着批量造命令而是花几天时间正常使用 Claude Code把那些“你想重复用但发现没有命令支撑”的操作记下来。等积累到三五个候选场景时再一起创建对应的命令模板。这样做的理由是你的命令模板应该来自真实需求而不是凭空想象的“完美流程”。凭空想出来的命令往往步骤过于复杂、用一两次就闲置了而来自真实痛点的命令每个都能持续用下去。4.4 参数与命令的取舍为什么这么配置在初始化过程中有几个参数值得专门解释一下。一个是/init命令本身它除了生成CLAUDE.md还可以配置permissions相关的选项比如允许 AI 在哪些目录下写文件、禁止访问哪些路径。以订单服务为例我会在权限配置里把deploy/和migrations/目录设为只读因为这两个目录里的内容一旦被 AI 改动后果非常严重。这个操作在命令层的 YAML 元信息里也有体现但项目级权限配置的约束力更强适合做全局兜底。另一个是命令模板里agent字段的选择。Claude Code 里有不同的代理模式通用代码任务是code如果某个命令需要更强的执行能力比如运行数据迁移、批量重命名文件可能需要选general代理并赋予更多的工具权限。但这里有个经验性的原则默认使用最小权限只有在遇到实际报错提示“权限不足”时才考虑提升某个命令的权限等级。一来是安全考虑二来是权限越小AI 越不会在执行任务时“跑偏”去做计划外的操作。最后命令模板里的$1参数和{module}这类占位符的命名也值得讲究。参数名要能让你快速理解该传什么比如{module}、{filename}、{branch_name}而不是抽象的{arg1}。参数太少会让命令过于笼统参数太多会让使用成本变高——一个命令两三个参数是比较舒服的状态。4.5 验证与迭代让模板在真实使用中升级模板创建完不是终点。我第一次给订单服务配完模板后做了这样一轮验证故意挑了一个不太熟悉的模块让 Claude Code 在里面完成一个小需求比如“为折扣规则模块增加一个新的折扣类型”。这个过程能直观检验模板质量如果 AI 一次就找对了文件位置、遵守了分层约束、生成的代码和项目风格一致、测试也一次通过说明模板合格。如果它找错了文件、生成了和现有风格冲突的代码说明模板里缺少了能纠正它的信息。一个更系统化的验证方法是跑一个“基线测试”在没有模板的情况下让 AI 完成一个标准小任务记录结果然后应用模板后再跑同一个任务对比两次的质量差异。这个对比能让你清楚看到模板究竟解决了什么问题。大部分项目的改善是显著的——代码风格更统一了、不再问重复问题、构建命令也顺便跑对了——但具体好在哪里用对比说话最直观。迭代方面我的习惯是建立一个“模板更新日志”每次往模板里加规则时顺手记一行今天因为什么事加了什么规则。这不仅是给自己留档案也能帮你发现规律——比如日志显示大多数新增规则都是因为 AI 在处理日期格式时犯错那你就知道该在模板里把日期处理的规范写得更显眼。5. 常见问题与排查技巧实录模板体系用久了什么情况都可能遇到。这一节我把实际踩过的坑和对应的排查思路整理出来按症状分类方便你快速定位问题。5.1CLAUDE.md为什么“不生效”这是被问得最多的一个问题而且大多数情况不是真的不生效而是改了文件但当前会话还在用旧缓存。Claude Code 对项目模板文件的读取时机是会话启动时所以你在一个已经打开的会话里修改CLAUDE.md后AI 是不会自动感知的。排查的第一步是重启会话看看新规则是否被加载。如果重启也没用那就检查文件位置。CLAUDE.md必须位于项目根目录。很多时候你的项目其实在一个子目录里比如 monorepo 结构下的某个服务包你把文件放到了仓库根目录而 Claude Code 是在子目录启动的那就读不到。解决办法是在子目录里再建一份针对性的CLAUDE.md或者每次从正确的目录启动工具。还有一种概率更低但也发生过的情况文件名拼写错误比如CLAUDE.md被写成了CLAUDD.md或者小写的claude.md。这类错误通常发生在手动创建文件而非用/init生成时。遇到怎么改都没反应的情况先检查文件名是不是和约定完全一致。5.2 模板文件太长导致上下文被挤占有些项目模板越写越长几千字的CLAUDE.md虽然信息丰富但每次会话都会完整加载Tokenizer 一算就是好几千 token。如果模板内容和当前任务没关系这些 token 就全浪费了反而压缩了真正的代码上下文空间。解决这个问题有两个方向。一是精简模板把“常识性内容”删掉只保留项目独有的信息。比如“写代码前先想清楚逻辑”这种废话不要写留出空间给真正有用的规范。二是利用 Claude Code 的引用机制把不常用的细节内容拆到单独的文件里在CLAUDE.md中按需引用。比如把完整的数据库表结构放到docs/db_schema.md只在CLAUDE.md里用docs/db_schema.md引用这样相关任务时 AI 才会去读取明细。我实际对比过精简后的项目模板通常能减少 30% 到 50% 的记忆文件 token 占用而信息覆盖度几乎不变。5.3 自定义命令不出现、名称冲突、参数传不进斜杠命令在输入/时会有自动补全列表如果命令没出现先确认文件是不是放在了.claude/commands/目录下文件名后缀是不是.md。命令系统不识别子目录中的其他命名规则也不支持文件名里带空格。命令名称冲突也是常见问题。如果你在项目里定义了/review而另一个命令文件叫review-and-fix.md触发/review时可能会产生歧义。更严重的冲突是与内置命令重名比如你定义一个/init命令去覆盖内置行为这种行为大概率不会按你的预期工作还可能让会话状态混乱。命名时加项目前缀是最省心的做法比如/order-review、/order-test。参数传不进的原因通常是模板里的占位符语法写错了。命令层的参数引用有两种风格一种是顺序参数$1、$2一种是命名参数{param_name}。如果你在同一个文件里混用了两种风格解析器可能只识别其中一种。统一用命名参数是最稳妥的命令正文里写{module}使用时输入/test app/services/order_service.py解析器会自动把路径填入。如果你的参数带空格比如文件名里有空格用引号包起来再传。5.4 AI 反复无视模板里的规则怎么办这是最让人头疼的问题。你明明在CLAUDE.md里写了“禁止在 API 层直接调用 ORM 查询”它还是会生成这种代码。遇到这种情况先别急着怪模型优先检查你的规则写法是不是足够“可判定”。对比一下“禁止在 API 层直接调用 ORM 查询”和“API 层路由函数内只允许调用 service 层函数所有数据查询通过 service 层转到 repository 层执行”——后者在代码审查时一眼就能判断是否违规前者还需要人先理解什么算“直接调用”模型的语境理解自然更模糊。如果规则本身够具体了AI 还是偶尔无视那就需要提升规则在会话中的显眼程度。Claude Code 对CLAUDE.md中的内容并不会逐字严格算作硬性约束规则写在不显眼的位置时被模型“遗忘”的概率会更高。把最重要的红线规则放在文件开头、用加粗或强烈的语气表述比如“这是本项目最高优先级约束不得违反……”实测下来显著减少违规次数。也可以把关键规则同时写进命令模板里在任务执行前再强调一遍——上下文里重复出现的约束会被模型更牢固地记住。5.5 团队协作场景的模板管理技巧当模板文件被纳入版本管理后新的问题出现了团队成员的模板更新不同步、Pull Request 里对模板的修改没有人 review、有人擅自往CLAUDE.md里塞入大量无关的个人偏好。我在实际协作中总结了一些做法第一模板的变更走和代码一样的审查流程。CLAUDE.md的每一次改动都应该能在 Pull Request 里被看到、被讨论。不要直接推到主分支更不要通过即时聊天工具发文件给队友手动替换。第二区分个人偏好和团队规范。个人习惯比如个人默认用的包管理器放在全局层团队约定比如接口返回结构、事务使用方式放在项目层。如果项目模板里混入了太多个人风格队友使用时会觉得 AI 生成的东西“别扭”但又说不上来哪里不对。第三为模板文件单独建一个维护说明。在项目根目录放一个CLAUDE-MAINTENANCE.md说明哪些文件是模板、各自的作用范围、改动时需要注意什么。新成员接手时不至于把命令模板删了还不知道怎么恢复。下面是一张速查表汇总了模板体系的常见问题症状优先排查点解决方案改了模板没反应会话缓存重启会话再测试新规则不生效文件位置/文件名确认在项目根目录、拼写正确上下文占用过高模板太长精简内容、用 引用拆分命令不出现目录/文件名放到.claude/commands/下命令冲突重名使用项目前缀区分参数传不进占位符语法统一用命名参数{name}规则被无视规则太模糊改写为可判定语句置于显眼位置我个人在实际操作中最大的体会是模板体系不是一蹴而就的工程而是一个持续演化的系统。不要追求第一天就写出完美的CLAUDE.md——先搭一个能覆盖项目基本盘的版本用起来然后在每次 AI 犯错时反问一句这个错误是否可以通过更新模板来预防如果可以就顺手把规则补进去。用这样的节奏迭代一个月你的模板会变得非常贴合项目实际而你也会对“AI 到底需要什么样的信息才能把活干好”这件事有更深的理解。如果你正打算自己搭一套模板我的最后一个小建议是把模板当成代码认真对待给它写维护记录、做结构设计、时常重构不要怕推翻重来。一套好用的模板能带来的效率提升可能比你换一个更“聪明”的模型还要明显。