claude-code-templates这个标题说白了就是一套让 Claude Code 从能用变成好用的工程化方案。我见过太多人打开终端敲一句claude 帮我写个模块就等着出活结果出来的代码要么风格不对、要么没写测试、要么直接偏离项目架构——问题不在模型能力在于你根本没告诉它你的项目规矩是什么。模板就是干这个的把你的技术栈、编码规范、架构约束、输出格式全部固化成交互指令让 AI 每次干活都站在同一个基准线上。这篇文章我会把模板的底层机制拆透给出可直接抄作业的模板实例并把我踩过的坑一并交代清楚。1. 为什么 Claude Code 需要模板从会说话到靠谱干活1.1 模板到底解决什么问题很多人对 Claude Code 的第一印象是能聊天的终端但真正上手后你会发现它的核心能力其实是在代码库里自主执行任务——读文件、改代码、跑测试、提交 commit都是它在终端里替你做。问题是这种自主性一旦缺乏约束就会变成脱缰野马。举个我实际遇到的例子我让人帮我把一个 Python 模块从 requests 迁移到 httpx它确实改完了但是用了sync风格而不是项目里统一的async风格也没有更新对应的单元测试docstring 更是跟源码完全脱节。你说它错了吗功能上是通的但跟项目规范完全是两个世界。模板解决的就是这个规范对齐问题。它本质上是给模型一份持久化的项目说明书让它在每次交互前先读到你的规则。核心价值有三点一致性同一个项目里不论你当天心情好坏、提示词写多写少模板能保证输出风格、代码结构、文档格式稳定。前置约束把容易忘记的检查项比如测试覆盖、类型标注、错误处理固化进指令让模型在动手前就知道验收标准。上下文节省不需要每次开会话都重新交代一遍技术栈、目录结构、构建命令模板帮你一次性把背景信息塞进模型视野。一句话总结模板是把你的团队规范、个人偏好编译成模型能稳定执行的上下文协议。1.2 模板体系的三层结构在实际工程里我建议把模板分成三个层次来规划而不是随手在一个文件里堆砌所有规则。第一层全局用户级模板~/.claude/CLAUDE.md。放那些跟你个人习惯强相关的规则比如默认使用 TypeScript strict 模式commit message 遵循 Conventional Commits不喜欢 JSDoc 注释只认参数类型标注等。这层对所有项目生效是写在你工作习惯里的固有偏好。第二层项目级模板/CLAUDE.md。放跟当前仓库强相关的业务规则比如技术栈版本、构建命令、目录结构约定、常见坑警告。这层是项目新成员不管是人还是 AI都必须先读的入职手册。第三层任务级模板斜杠命令 Skill 文件。放一次性、可复用的任务指令比如代码审查、模块生成、Bug 定位。这一层是模板库的核心竞争力也是我会在后面花大篇幅拆解的部分。理解了这个三层结构你就不容易把模板库写成一团浆糊。每一层各司其职层一管我是谁层二管这个项目怎么运层三管这一类任务怎么做。2. 模板的核心类型拆解从 CLAUDE.md 到斜杠命令2.1 CLAUDE.md项目上下文的持久化CLAUDE.md是 Claude Code 框架里最基础的配置文件它的定位是放在项目根目录下的 Markdown 文件在每次会话启动时被自动加载进 Claude 的上下文。它的写法有几个关键心得。首先是结构要一眼可扫模型对长文本的注意力是递减的我看过很多人写几千行的项目说明书恨不得把 git history 都写进去结果模型真正高频用到的如何运行测试目录结构规定反而被淹没在中段。我自己的习惯是前 50 行内必须覆盖四个元信息# 项目说明 ## 技术栈 - 语言: Python 3.12 - 框架: FastAPI SQLAlchemy 2.x (async) - 构建: uv - 测试: pytest pytest-asyncio ## 常用命令 - 安装依赖: uv sync - 运行测试: uv run pytest tests/ -x - 启动开发服务: uv run uvicorn app.main:app --reload - 代码检查: uv run ruff check . uv run mypy app/ ## 目录结构 app/ api/ # 路由层只负责参数校验和响应封装 services/ # 业务逻辑层禁止放 SQL 和 HTTP 相关代码 models/ # ORM 模型禁止在模型里写业务方法 schemas/ # Pydantic 模型对应 API 请求/响应 tests/ unit/ # 单测不依赖外部服务 integration/ # 集成测试需要测试数据库 ## 编码规范 - 所有数据库操作必须走 services 层禁止在路由里直接查库 - 新功能必须配套单元测试核心链路必须有集成测试 - 错误信息统一使用中文格式为 操作失败: 具体原因这段内容看起来简单但每一行都是我在实际项目中反复踩坑后固化的规则。比如禁止在路由里直接查库这条就是早期让 AI 帮忙加功能时它最喜欢偷懒的地方——直接在路由函数里await session.execute(...)短平快但完全破坏分层架构。把这种约束写进模板等于给 AI 立规矩。其次CLAUDE.md 可以被嵌套。大型仓库往往不止一个模块你可以在app/services/子目录下再放一个CLAUDE.md只写这个子模块的特殊规则。Claude Code 在读取上下文时会按目录层级把多份 CLAUDE.md 合并加载层级越近的文件权重越靠后、优先级越高。这招对 monorepo 尤其有效我后面还会细讲。2.2 斜杠命令与自定义模板把重复劳动固化成指令CLAUDE.md解决的是背景知识但真正的高频复用场景是任务流程。比如帮我 review 一下这个 PR按这个模块结构帮我生成一个 controller——每件事都要重复描述步骤太浪费了。斜杠命令slash command负责把这类重复劳动固化。在~/.claude/commands/或项目.claude/commands/里新建一个 Markdown 文件文件名就是命令名比如review.md然后在 Claude Code 对话中输入/review就会加载这个文件内容作为一次性指令。它的强大之处在于支持参数占位符和子命令参数比如# 代码审查 审查当前 git diff重点关注 1. 正确性是否存在并发问题、空指针、资源未释放 2. 架构一致性新代码是否遵循项目分层不跨层调用、不绕开 services 3. 测试覆盖关键分支是否有对应测试测试是否断言了业务结果而非实现细节 4. 安全隐患是否硬编码密钥、是否缺少输入校验 5. 代码风格命名是否表意、函数是否过长、魔法数字是否抽常量 输出格式 - 【问题等级】位置 | 问题描述 | 建议修改 - 等级划分: P0 必须修复 / P1 应当修复 / P2 建议优化这段指令的价值在于它把审查 diff这个模糊任务拆解成了模型可以逐项核对的可执行清单。我实际使用下来带这五个维度清单的 review比直接喊帮我 review 代码要多发现至少三倍的隐藏问题特别是架构一致性这条没有明确指令时模型几乎不会主动对照分层规则检查。包括参数化设计也很简单在文件中用$ARGUMENTS接收输入# 生成模块 为功能「$ARGUMENTS」创建一个新的后端模块按以下结构实现 - 路由层: 负责参数校验与请求封装 - 服务层: 实现核心业务逻辑返回领域对象 - 校验层: 定义 Pydantic 请求/响应模型 - 依赖注入: 按 FastAPI 的 Depends 模式注册 - 配套测试: 覆盖成功路径、边界条件、异常分支 完成后输出模块清单、每个文件的职责说明、测试运行命令。有占位符的模板才叫模板没有占位符的只能叫写死的脚本。参数设计是命令模板的核心灵魂。2.3 子代理与 Skills角色化模板的高级玩法如果说 CLAUDE.md 是背景资料斜杠命令是任务脚本那subagents和skills就是模板体系的角色化进阶版。子代理subagent是 Claude Code 中的独立角色它有自己的名字、描述、工具集和系统提示词可以作为主代理的分身被委派任务。定义方式是在.claude/agents/下放一个带 YAML frontmatter 的 Markdown 文件--- name: sql-reviewer description: 审查所有数据库相关代码检查 SQL 注入、N1 查询、缺少索引等问题。当任务涉及数据库操作或 ORM 使用时应委派给该代理。 tools: Read, Grep, Glob, Bash ---然后在正文里写这个代理的专属行为规则比如必须检查查询是否走索引禁止使用select *关联查询必须验证是否会产生 N1等。主代理会根据description的匹配程度自动决定是否委派。这是模板体系里最接近微服务的设计——把不同领域的审查、生成、测试逻辑拆成独立可复用的专家角色。Skills则是另一种形态它定义的是能力范围。一个 Skill 通常包含SKILL.md技能说明 使用指引和一组参考脚本/示例文件。Claude 会在需要时自主决定是否调用某个 Skill而不是像斜杠命令那样必须由用户主动触发。如果你有一批内部工具脚本、代码片段库、设计规范文档都可以封装成 Skill 让模型在合适时机自动检索使用。我个人的分层经验是一句话能讲清楚的规则放 CLAUDE.md需要按步骤执行的任务放斜杠命令需要独立知识背景和专业判断的工作放子代理和 Skills。3. 构建高质量模板的五个实操要点3.1 先写不要做什么再写要做什么这是我在大量模板迭代中得出的最重要经验。模型的默认行为倾向于自由发挥而自由发挥的产物经常违背你的架构约束。你先写禁止规则等于先把最容易跑偏的行为挡住再给正确方向效果会好很多。拿我上面那个 FastAPI 项目的模板举例禁止在模型里写业务方法、禁止在路由里直接查库、禁止跨层调用这几条禁令比写十句请遵循分层架构都管用。模型是概率生成机制明确的否定约束比抽象肯定描述更容易被执行。建议把项目的雷区清单单独收集成一个区块维护每次模型犯同样的错就往模板里加一条禁令。用久了你会发现这个清单本身就是团队最有价值的隐性知识库。3.2 用示例约束输出格式模型对格式的遵循能力靠描述远不如靠例子。如果你想要某种特定的代码风格、注释格式或提交信息格式最好的办法是给它一两个正例和反例。举个实际的例子我想要模型生成会议纪要保持统一格式我在提示词里写了三段式背景、讨论结论、行动项。结果它生成的纪要每段的风格都不一样有的行动项带负责人有的没有。后来我直接给了示例## 行动项 - [ ] 张三 完成 API 限流逻辑周一前端联调前交付 - [ ] 李四 补充压测数据与王五确认阈值后再定目标给了这个之后格式漂移几乎消失。模型的 few-shot 能力远远强于 zero-shot 指令遵循能力模板里尽量多用示例。3.3 控制模板规模与上下文预算这是模板设计中最容易被忽视的硬约束。Claude Code 的上下文窗口是有限的CLAUDE.md 被加载后会一直占用上下文空间而任务对话、工具返回结果也在不断消耗预算。一份 500 行的 CLAUDE.md 看着内容丰富但代价是留给实际任务分析的空间变少到对话中后期模型容易遗忘前面的项目规范。我的经验标准是项目级 CLAUDE.md 控制在 300 行以内单条斜杠命令控制在 80 行以内。超过这个量优先考虑拆分成子代理或 Skill让模型按需加载而不是一股脑全塞进上下文。另外要遵循就近原则信息放在它被使用的层级里。全项目通用的规范放根目录 CLAUDE.md只影响某个子系统的规则放子目录 CLAUDE.md只影响某类任务的规则放命令或 Skill 里。这样既能保证上下文精简又能让规则在正确的层次生效。3.4 参数化设计模板写命令模板最容易犯的错是写死——把一次任务中的具体内容硬编码进模板文件复用性极差。模板的生命力在于抽象。把功能模块名目标文件路径技术选项这些变量暴露为$ARGUMENTS占位符才能实现一套模板应对多类任务。我一般这样设计参数化层# 生成 API 端点 功能描述: $ARGUMENTS 请实现一个完整的 RESTful 端点包括 - 路由注册按项目路由前缀规范 - Pydantic 请求/响应模型 - 服务层业务函数 - 参数校验与错误处理 - 单元测试与集成测试 若功能涉及数据库操作需在服务层中补充事务管理与异常回滚。调用时输入/api 用户注册接口邮箱密码认证方式需支持验证码模型就能把参数融入指令流执行。参数化不是让模板变聪明而是让模板保持通用把具体变化留给每次调用时的输入。3.5 嵌套与分层让模板随目录生效模板体系想应对大型仓库就必须拥抱分层嵌套。Claude Code 的 CLAUDE.md 是按目录层级逐级读取的启动会话时它找到所有相关目录下的 CLAUDE.md按距离当前目录的远近排列并合并加载。这个机制的价值在于局部规则可以覆写全局规则。比如整个仓库规定用 PostgreSQL但某个模块因为历史原因用了 MongoDB你可以在该模块子目录下放一个 CLAUDE.md 说明此模块数据层使用 MongoDB禁止改动为 SQL除非有单独指令。这样模型在处理这个模块时读到的是就近规则不会把全局规则一刀切。嵌套还有一个进阶用法把子代理定义在项目内.claude/agents/而不是全局目录这样这个代理只在这个仓库内生效团队其他人拉到仓库后也自动继承这套角色配置。模板跟着代码走是团队协作效率最高的一种形态。4. 几套可以直接抄作业的模板实录前面讲了不少原理和方法下面直接给出我自己在生产环境验证过的模板实例。这些模板不是给人看的理论而是已经在我多个项目中稳定运行的配置你可以根据自身技术栈略作修改后直接投入实战。4.1 新功能模块生成模板用途让 AI 生成一个符合项目规范的全新业务模块而不是只写一个孤零零的文件。# 生成业务模块 模块名称: $ARGUMENTS 请按以下步骤生成: 1. 先阅读项目根目录 CLAUDE.md 中的目录结构与编码规范 2. 查询现有模块的相似实现保持风格一致 3. 按既有分组模式生成路由 / 服务 / 模型 / 校验 / 测试 4. 生成配套数据库迁移脚本如有表结构变更 5. 运行全部相关测试并修复失败项 约束: - 禁止修改与本模块无关的现有文件 - 所有对外接口必须有 Pydantic 响应模型 - 服务层函数必须做输入合法性校验 - 错误码规范模块前缀 错误类型 完成输出: - 新增/修改文件清单及职责说明 - 数据库迁移内容摘要 - 测试覆盖率摘要和测试结果这套模板的核心价值在第一步按既有模式实现——它迫使模型先去了解仓库里同类模块的写法而不是凭空生成一套新风格。我实测过加了查询现有模块风格这句之后新生成代码与手写代码的相似度显著提升review 成本大幅下降。4.2 代码审查模板代码审查是模板收益最明显的场景。没有模板时模型审查基本停留在这段代码有什么 bug层面有模板后它可以按你的架构规范和隐患清单逐项排查。# 代码审查 请审查当前分支相对于 main 的全部 diff按以下维度输出: ## 维度与检查项 1. 架构合规 - 是否遵循分层架构有无跨层调用 - 是否有绕过统一异常处理的情况 - 新依赖是否合理是否已评估影响 2. 正确性 - 并发场景是否存在竞态或死锁 - 资源文件、数据库连接是否及时释放 - 是否有未处理的失败路径 3. 安全性 - 是否硬编码密钥/口令 - 用户输入是否有边界校验与白名单过滤 - 是否输出敏感信息到日志 4. 可维护性 - 函数是否过长、命名是否表意 - 是否缺少必要注释或存在误导性注释 - 魔法数字和重复逻辑是否合理抽取 5. 测试质量 - 断言是否针对结果而非实现细节 - 是否覆盖异常分支和边界值 ## 输出格式 所有问题按 [P0/P1/P2] 分级输出表格 | 等级 | 文件位置 | 问题描述 | 修改建议 | 最后汇总: P0 数量、P1 数量、总体评审结论通过/需修改/需重写。这套模板的精髓在于输出格式强制表格化。用了几次之后你就知道表格比自由文本好用太多——导出到 issue、群聊、文档里都一目了然。另外 P0/P1/P2 分级制能有效防止 AI 把所有问题都一视同仁地列出来。4.3 Bug 定位与修复模板用 AI 修 bug 最大的坑是模型经常跳过复现直接改代码改完你都不知道是否真的解决了。修复模板强制它按定位 → 复现 → 修复 → 验证的完整链路走。# 修复 Bug Bug 描述: $ARGUMENTS 严格按以下步骤执行每个步骤完成并输出中间结果后再进入下一步: 1. 定位搜索相关代码路径梳理调用链指出最可疑的 2-3 个位置并说明理由 2. 复现通过阅读测试代码或运行复现脚本确认 Bug 触发的确切条件 3. 修复修改代码保持项目风格一致 4. 验证编写或更新针对性测试运行相关测试套件证明修复有效 5. 总结说明根因、修复方案、影响范围 禁止: - 在步骤 2 完成前直接修改代码 - 用临时 print 或日志方式掩盖问题 - 修改与修复无关的代码那条禁止在步骤 2 完成前直接修改代码是血泪教训换来的。AI 模型尤其对经验丰富的大模型很容易在读完代码后产生我看懂了直接改的冲动但结果经常是修了表现没修根因。强制它先说清楚复现条件和根因看起来多了一步实际省掉了反复横跳。4.4 重构与迁移模板重构任务的特点是范围大、风险高模板的核心任务是给重构画一条安全边界。# 重构模块 重构目标: $ARGUMENTS 执行前: 1. 列出当前模块对外暴露的接口和所有调用方 2. 确认重构目标是否保持对外行为不变或列出允许的行为变化 3. 制定重构步骤顺序确保每个中间状态可运行、可测试 执行中: - 每次小步完成即运行相关测试 - 所有行为变更必须写入变更说明 - 保留必要的历史注释和演进逻辑不删除重要背景信息 执行后: - 运行全量测试和 lint/类型检查 - 输出: 变更摘要、行为变化清单、调用方影响范围、新增测试说明这套模板最有用的是中间状态可运行、可测试这条约束。它让模型不会一次性给你一个改完所有文件但还是跑的起来的大炸弹而是像正经工程师做重构那样一步一验证。4.5 测试生成模板测试生成是 AI 最擅长的领域之一但如果不加约束它生成的测试往往是happy path 套娃——跑全绿但覆盖不了边界和异常。# 生成测试 被测模块: $ARGUMENTS 请阅读被测代码后生成以下测试: 1. 常规路径正常输入、正常流程、返回结果断言 2. 边界条件空值、极值、超长字符串、类型边界 3. 异常分支依赖失败、校验不通过、并发冲突、超时 4. 数据完整性数据库事务回滚、外键约束、唯一冲突 对每个测试断言的要求: - 必须断言业务结果返回值、状态变化、数据库数据而不是只断言不抛异常 - 对异步函数必须断言 await 后的最终结果 - 测试命名遵循 test_被测行为_条件_期望 格式 输出: - 测试文件路径清单 - 每个用例的一句话场景说明 - 运行结果: pytest tests/ -x -q记得第一次用这套模板时模型给一个文件生成测试居然补上了超时重试三次后才返回失败这个我完全没提到但代码里确实存在的分支。对比之前它只会给信息拼装测试模板的引导作用肉眼可见。5. 常见问题与排查技巧实录5.1 模板不生效模型还是我行我素这是最让人崩溃的场景CLAUDE.md 写得清清楚楚但模型批改代码时就是视而不见。排查思路有三个第一确认有没有更近目录的 CLAUDE.md 覆盖了你的规则。嵌套层级里距离当前工作目录更近的规则优先。如果你在子模块目录下写了一条相反规则根目录的规则会被覆盖。第二看规则是否与系统提示冲突。如果你的全局模板与项目模板冲突比如全局说默认 Python项目说当前是 TypeScript模型可能按全局执行。此时在项目模板里显式写本项目使用 TypeScript忽略全局的 Python 规则会更有效。第三检查规则的具体性。遵循项目编码规范太抽象模型宁可做也不愿意停下来问。把规则细化成函数参数超过 3 个时必须用数据类封装这种可执行判断模型才能稳定遵循。5.2 模板太长把上下文撑爆模板终究要进入上下文而上下文空间是真实资源。我见过有人把整个团队的 wiki 粘进 CLAUDE.md结果模型对话到第 10 轮就开始失忆。解决方法有两招一是用主干 分支结构。主干 CLAUDE.md 只放最高频的 50 条规则低频详情拆成命令模板、子代理定义或独立的参考文档让模型在需要时按路径读取而不是一次性加载。二是明确标注优先级或必须遵守字样。模板中信息不是平等重要的把我的项目**核心不可违反的规则比如安全规范、架构边界**放在文件最开头后面再写操作指引。模型对前 100 行内容的遵循度远高于后 300 行。5.3 输出格式漂移同样是要求输出表格模型上次用 Markdown 表格这次用列表下次直接写段落。对付格式飘移唯一的可靠办法是给示例。在模板里直接放一段输出样例甚至声明严格按以下格式输出不要增加说明文字。对模型来说示例的约束力远大于描述。如果还不稳定就在后处理里加一道校验让模型先输出再自我检查是否符合格式。5.4 团队协作时的模板维护模板一旦进了仓库就成了团队资产必然涉及版本演化和意见冲突。我的经验是模板合入走 PR 流程模板变更影响面大必须有人 review每条规则都要有为什么免得后人维护时不敢动定期清理给模型新增的坏习惯能补禁令的直接补而不是靠每次多写几句提示词模板维护是持续投资建议在仓库里建个docs/ai-development-guide.md把模板变更的背景、讨论过程记录下来。这样大家看到某条规则时不仅能知道怎么做还能知道当初为什么这么定。有了这层上下文模板的可靠性会逐步提升AI 协作的质量和团队知识沉淀会融为一体。从我自己几个项目的实践看Claude Code 模板库的建设是典型的投入少见效快工程。花一两个晚上把 CLAUDE.md 和几条高频命令模板落地第二天就能感到 AI 交付质量的明显变化——代码风格统一、架构约束不越界、测试完善度大幅提升。而且模板这东西是滚雪球的每次发现模型跑偏就往对应模板里补一条规则规则库越丰富模型就越了解你的项目。如果你正在用 Claude Code 但还没建模板今晚就可以从复制上面几套实例开始如果你已经在用模板欢迎按你项目的特点继续迭代——使用模板的经验恰恰就是你和 AI 协作效率的分水岭。
