如果你和我一样用 Claude Code 干活已经成为每天的固定动作那你早晚会遇到同一个问题同一个项目、同一类任务第一次交代时讲得清清楚楚换一个新分支、新开一个会话又得从头再说一遍项目背景、技术栈、代码路径和验收标准。我一开始觉得这只是多点几下键盘的事直到有一次连续开五个会话处理五个 bug每个会话开头都在复制同一段项目说明才意识到这事一点都不优雅。claude-code-templates 这套方法论要解决的就是这个问题把反复出现的背景、规则和任务结构沉淀成模板让 AI 编码助手每一次都能快速进入状态把有限的注意力留给真正需要处理的业务逻辑。这套模板不是什么官方发行的魔法插件它本质上是一组文件组织实践核心载体包括项目根目录的 CLAUDE.md、.claude 目录下的命令模板以及用户目录下的全局规则。适合谁我觉得只要你在认真用 Claude Code 写代码、改代码、审代码都值得花半小时搭一套尤其是多仓库切换开发、团队协作仓库、以及任务类型高度重复的日常维护场景。接下来我把实际项目中打磨出的模板体系完整拆开讲每一层都有具体写法也有可以直接抄走的示例。1. 模板体系为什么是使用 Claude Code 的必经之路1.1 没有模板时我踩过的效率坑早期用 Claude Code我是典型的现场口述流。新建一个仓库先告诉它这是 Go 写的后端服务用的 Gin 框架数据库是 PostgreSQLAPI 风格走 REST测试用标准库的 testing 包……这些信息每次开场都要讲一遍讲完之后才开始安排真正的任务。问题很快就暴露了。第一个问题是上下文被反复灌入的重复信息占满。前面那段项目背景看起来不长但加在一起差不多要一两千 token如果你习惯用中文啰嗦地描述成本更高。任务做到一半Claude 经常开始忘记前面的项目设定我得反复强调我刚才不是说了数据库在 internal/repository 吗。这种体验很像带了一个记忆只有七秒的实习生。第二个问题是输出风格飘忽不定。同一个仓库里它今天用中文注释明天用英文注释今天写测试断言按行描述明天又改成表格驱动。代码审查的时候我得花额外精力去辨别这个风格变化是故意的还是它随机发挥。第三个问题是团队协作时每个人喂给 Claude 的背景口径不一致你说是 A 方案他说是 B 方案最后 AI 生成的东西风格割裂。后来我意识到这不是 Claude 笨而是我给的信息颗粒度太粗、格式也不稳定。更本质的原因是稳定信息没有被抽离成可复用资产。项目背景、代码约定、命令清单这些内容在每一次会话里都相同重复描述它们既浪费上下文又引入了不确定性。模板化的第一层价值就在这里把稳定信息抽出来让每次新会话都能快速加载同一套背景知识。1.2 模板化的三个直接收益收益一上下文预算更充裕。没有模板时每个会话开头要花一两千 token 重复背景有了 CLAUDE.md 之后同样信息用结构化文本承载加载效率更高省下来的 token 全部可以留给真正的编码任务。任务越长、仓库越复杂这种优势越明显。收益二输出一致性显著提升。当模板里写清楚注释语言、命名风格、提交信息格式、测试策略Claude 每次生成的结果会主动对齐规则。我最近在几个项目里都指定了注释用中文、变量命名用英文、commit 用 Conventional Commits 格式之后基本没再收到过风格跑偏的产出。收益三团队协作有了统一底座。几个人共用一个仓库把模板纳入 Git 管理所有人都加载同一份 CLAUDE.md 和同一组命令模板AI 辅助代码质量的下限会被整体抬高。后来我们团队的 Code Review 负担明显变轻因为 AI 生成代码在风格层面几乎不需要人工纠正审查重点可以放在逻辑和业务正确性上。2. 模板体系整体设计三层结构的思路2.1 第一层项目级记忆模板CLAUDE.mdCLAUDE.md 放在项目根目录是 Claude Code 会话启动时的项目记忆。它会在启动时被自动读取相当于一份持续生效的系统指令不需要你每次手工--load或者复制粘贴。我的理解是它解决的是一句话问题让 Claude 在动手之前就知道自己在哪个项目、遵守什么规矩。我写 CLAUDE.md 的三条设计原则只放稳定信息。项目定位、技术栈、目录结构、常用命令、风格规范这些变数小的内容全部沉淀进来。临时任务相关的内容比如这次发布要处理超时问题不要写进 CLAUDE.md应该放任务模板里。不使用形容词。写成运行测试go test ./...不要写请务必认真运行测试写成错误处理统一使用 errors.Wrap不要写尽量做好错误处理。模板是给 AI 的约束不是口号。控制篇幅。我一般控制在 80 到 150 行以内规则数量不超过 15 条。内容太长会导致信息衰减Claude 在处理长上下文时对开头和结尾的注意力更集中所以我能压缩就压缩把最重要的规则放到文件最前面。2.2 第二层任务级提示词模板项目级记忆管背景任务级模板管具体任务怎么做。我会把高频任务固化成独立 Markdown 文件放在 .claude/commands/ 目录下文件名就是斜杠命令名。比如 code-review.md 对应/code-reviewwrite-tests.md 对应/write-testsfix-bug.md 对应/fix-bug。这样做的好处很明显第一不用每次临时组织语言任务模板里已经写清楚目标、范围、约束和输出格式第二模板支持变量占位符调用时可以填充具体参数比如/code-review internal/order/service.go通用性和定制化同时满足第三任务模板可以引用项目级约定两边互相配合不会出现CLAUDE.md 规定了注释用中文任务模板却要求不写注释这种冲突。这个目录建议放进 Git 仓库。团队里的所有人共享同一套命令模板新人上手时看一眼 .claude/commands 就知道这个项目通常用 AI 做什么类型的任务这本身也是团队知识的沉淀。2.3 第三层组织级公共模板在多仓库之间切换久了你会发现项目模板里有大量重复内容比如禁止提交密钥commit 信息用 Conventional Commits 格式遇到不确定需求先提问不要自行假设这些规则几乎每个项目都一样。把这些内容在每个仓库各写一份维护成本太高改一处要同步所有仓库。我会抽到用户目录下的全局模板里实测路径是 ~/.claude/CLAUDE.md不同版本可能有差异装好后先用官方文档确认一下相当于全项目通用的宪法。项目根目录的 CLAUDE.md 只保留差异化信息比如技术栈、命令、架构布局。两层配合加载全局规则管底线项目规则管细节。需要提醒的是不要一上来就做全局抽象。更稳的路径是先在项目里把本地模板用顺几个月后回头看把三四个项目里重复出现的内容抽出来再提升到全局层。过早抽象会抽错位置把项目特有规则误当成通用规则反而给后面的项目埋坑。3. 核心模板细节拆解与写作要点3.1 CLAUDE.md 的结构与写法我推荐的项目级 CLAUDE.md 结构是这样的项目概述两到三句话说明这个项目做什么给 Claude 建立基本认知。技术栈清单用列表列出语言、框架、数据库、关键工具最好带上版本。常用命令测试命令、构建命令、lint 命令、启动命令全部给全命令。代码风格约定命名习惯、注释语言、错误处理偏好、目录组织方式。关键架构信息模块边界、数据流、部署形态让 Claude 知道改一个文件可能影响哪些模块。约束与禁止项不要改哪些文件、不要执行哪些破坏性命令、不提交哪些目录。一段真实的 Golang 项目示例# 项目概述 shop-api 是电商后端服务提供商品、订单、用户三个核心模块的 REST API。 # 技术栈 - Go 1.22 - Gin - PostgreSQL 15 - Redis 7 - Docker / docker-compose # 常用命令 - 启动服务go run ./cmd/server - 运行测试go test ./... - 单测指定包go test ./internal/order/... - 数据库迁移make migrate-up # 代码风格 - 变量、函数使用英文命名注释使用中文 - 错误处理统一使用 errors.Wrap 包装不在底层吞掉错误 - 接口命名动词开头Repository 接口放在 domain 层 - API 响应格式统一为 {code:0,data:...} # 架构信息 - cmd/server 为程序入口 - internal/domain 放领域模型 - internal/repository 负责数据库访问 - internal/service 放业务逻辑 - internal/handler 处理 HTTP 请求 # 约束 - 不要修改 internal/repository 中已有的历史迁移文件 - 不要把密钥写进代码一律使用环境变量 - 修改公共代码时必须同步更新对应的单元测试这个结构里最重要的是约束段。它定义了 Claude 的行为边界相当于告诉 AI 哪些地方不能碰这比告诉它能做什么更重要。我见过太多模板只写这个项目很复杂请小心修改这种模糊约束等于没有约束。3.2 任务提示词模板的四个关键部分任务模板虽然因任务而异但骨架是固定的。我把它拆成四个部分写代码审查、写测试、修 bug、写文档都适用任务目标一句话说清楚要达成什么。不要用请帮助我改进一下要说对本次代码变更进行严格审查找出可能引发线上问题的风险点。输入范围明确告诉 Claude 基于哪些文件、哪些分支、哪些上下文信息去工作避免它自己乱翻目录、扩大行动范围。约束条件写明不要改哪些范围、采用什么算法、遵循什么规范、是否允许修改测试之外的文件。输出格式要求给出结构化的结果比如变更清单、测试结果说明、风险提示。AI 输出一旦有固定格式审查和交接的效率会高很多。我再加一个容易被忽略的部分兜底规则。在模板末尾写一句如果信息不足先列出问题清单向我确认不要自行假设。这句话能拦住 AI 在需求不明确时自作主张对修 bug 这类任务尤其重要防止它猜错根因直接动手。3.3 变量占位符与调用方式在 .claude/commands/ 目录下的模板里支持用{{变量名}}的方式定义参数。调用斜杠命令时Claude 会识别占位符自动提示或要求你补充对应内容。我写命令模板时的习惯是占位符命名一定用可读的名称比如{{文件路径}}、{{问题描述}}不要用a、b这种缩写。占位符数量控制在三到五个太多会让调用流程变得烦琐。能在文件开头用一句话说明的就不要设计成占位符。举个例子我调用/code-review internal/order/service.go模板启动后Claude 会知道审查对象是 internal/order/service.go。如果你在模板里把目标文件定义为占位符那么通知时就可以直接把路径传给命令如果占位符没填Claude 会反过来问你请问这次审查变更涉及哪个文件多一轮交互。4. 实操一套可直接落地的模板配置4.1 第一步写出第一个 CLAUDE.md在实际项目里我不会一口气把 CLAUDE.md 写得很长而是先用十分钟搭底稿之后在真实迭代中持续补充。具体操作在项目根目录创建 CLAUDE.md按第 3.1 节的结构填入内容。如果项目里已经有 README可以直接参考 README 里的技术栈和启动命令但写法要调整README 是给人看的CLAUDE.md 是给 AI 当系统指令用的语气必须更直接信息密度要更高。写完第一个版本后我建议做一件事开一个新会话输入一个只有 AI 知道答案的问题来验证加载。比如问这个项目的测试命令是什么看它能不能直接答出来。如果它答不上来说明模板没有被正确加载检查文件位置和命名然后再进入下一项任务。这个验证动作很便宜能帮你尽早发现路径错误之类的问题。4.2 第二步落地两个高频任务模板任务模板我从使用频率最高的两个开始做。第一个是代码审查文件 .claude/commands/code-review.md--- description: 对指定文件或本次变更做严格代码审查 argument-hint: [目标文件或路径] --- 对代码变更进行一次严格代码审查。 任务目标找出可能引发线上问题、性能隐患和风格偏差的问题。 审查范围本次变更涉及的 {{文件路径}}以及与之直接相关的调用方。 约束 - 不修改代码只输出审查意见 - 按严重程度从高到低排列问题 - 每个问题必须给出文件与行号参考说明原因和修复建议 - 如果发现与 CLAUDE.md 中约定不一致的地方单独列出 输出格式 1. 总体评价3-5 句 2. 高风险问题 3. 中低风险问题 4. 风格与约定问题 5. 建议的下一步动作第二个是修 bug文件 .claude/commands/fix-bug.md--- description: 定位并修复一个 bug argument-hint: [问题描述] --- 现在有一个 bug 需要修复。 Bug 描述{{问题描述}} 复现路径{{复现步骤}} 预期行为{{预期行为}} 实际行为{{实际行为}} 要求 - 先定位根因用 3-5 句话说明根因分析再动手修改 - 只修改必要的文件不要顺手重构无关代码 - 修复后补充一个针对该场景的测试 - 如果涉及数据库变更必须提醒我新增迁移脚本这两个模板覆盖了我日常使用的 70% 场景。后面我陆续加了 write-tests.md、generate-docs.md、commit-message.md但都是在跑顺基础模板之后按需补的没有一开始就铺开。4.3 第三步提交到版本库并维护模板.claude 目录建立后我会把它提交到 Git跟着项目一起管理。这一步是团队协作的关键否则你本地一套模板同事本地一套模板AI 行为仍然无法对齐。我的维护习惯是这样的模板更新也走 code review。比如我想给 CLAUDE.md 增加一条禁止使用 fmt.Print就开个 MR 说明原因同事确认后再合入。模板变更导致的 AI 行为变化有时候比代码变更影响范围还大因为它会影响将来所有的新会话所以不能随手改完就推上去。我还会在模板文件头部写一行最近更新时间和更新原因方便追踪历史。没有这个习惯之前我经常对着一段模板内容想不起来当初为什么加它。注意CLAUDE.md 或命令模板里的内容最好与项目代码保持同步。当你改了架构、换掉框架、废弃了某个命令务必同步更新模板。模板一旦过时AI 会依据错误背景工作比没有模板更糟。5. 常见问题与排查技巧实录5.1 模板没生效Claude 好像不记得 CLAUDE.md 内容这个问题我遇到过一次很典型的。我明明在项目里写了 CLAUDE.mdClaude 还是不知道测试命令后来发现文件放在了 src/ 子目录而 Claude Code 启动时的工作目录在项目根目录它默认读取的是启动目录下的 CLAUDE.md。把文件挪回根目录之后问题就消失了。排查方向按顺序来文件位置和命名确认 CLAUDE.md 在你启动 claude 命令的工作目录下且文件名大小写一致。会话状态如果是在已有会话里新增的模板它可能不会立即加载输入 /clear 清空会话后重新加载或者直接重启终端。内容结构检查 CLAUDE.md 是否超过合理长度。如果文件有一千多行Claude 很可能只记住了开头部分把最关键的规则放在文件最前面。命令模板路径确认命令文件是 Markdown 格式并且位于 .claude/commands/ 目录下文件名对应斜杠命令名。5.2 模板太长导致上下文紧张上下文窗口再大也架不住模板里塞了一堆重复和低信息量的内容。我见过有人把整个团队 wiki 复制进 CLAUDE.md结果每个会话一开始就吃掉几万 token任务做到一半上下文就爆了。我的处理办法是分级存放全局 CLAUDE.md 只放 5 条以内通用底线规则项目 CLAUDE.md 控制在 80 到 150 行展开性的详细说明和长例全部放进斜杠命令模板按需加载。比如 pytest 的完整用法、项目的详细架构设计说明这些只有在写测试或者做深层重构时才需要全部进 write-tests.md 和 refactor.md不要常驻在 CLAUDE.md 里。另外要留意全局模板与项目模板之间的重复。如果两者都写了注释使用中文这条信息就占了两份空间而且如果写的内容冲突AI 还会陷入矛盾。我会在全局模板里声明一句项目根目录的 CLAUDE.md 优先级高于本文件避免同层竞争。5.3 团队协作时的模板冲突模板纳入 Git 之后冲突问题变成了团队协作问题。最典型的情况是A 同事在模板里加了所有 API 返回结构统一加 request_idB 同事可能正在写一个不需要 request_id 的模块结果所有新会话生成的代码都带着这一规则B 的项目代码与模板规则格格不入。我的建议是模板变更必须走代码评审并在变更说明里写明影响范围。另外如果某个仓库有特殊约束不要考虑在全局模板里加豁免条件而是在该仓库的 CLAUDE.md 里明确覆盖。一层管通用一层管特殊两层职责清晰就不需要一堆互相矛盾的规则。还有一个实用技巧把模板文件也纳入 review 时的检查项。提交模板变更的 MR 里除了看模板内容还要检查对应样例输出是否仍然合理。如果在 review 代码时发现某段生成结果风格怪异第一反应可以去看模板最近有没有变更。6. 进阶玩法把模板和自动化流程接起来6.1 用 hooks 在工具调用后自动格式化模板能约束 AI 生成内容的风格但还漏了一层生成代码后是否自动格式化。我目前的做法是在 .claude/settings.json 里配置 PostToolUse hooks在 Claude 编辑或写入文件后自动跑一遍格式化工具。一个大致的配置结构如下具体环境变量名以你所用版本的官方文档为准{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: gofmt -w $CLAUDE_FILE_ABSOLUTE_PATH } ] } ] } }配置好之后Claude 写完文件会自动格式化我不用再手工跑一遍 gofmt也减少了AI 生成的代码格式不规范这类 review 反馈。模板负责内容风格hooks 负责机械格式化两者分开各管一摊。6.2 用模板初始化新项目脚手架模板体系成熟后我会把一套初始化模板单独抽出来放在一个 template 仓库里里面包含 CLAUDE.md 骨架、.claude/commands 基础命令集合、还有目录结构说明。新建项目时直接拷贝这套骨架到新仓库把技术栈、项目描述替换成新项目的真实内容。这个动作能把模板体系的搭建成本压缩到一首歌的时间。新项目一开始就有 CLAUDE.md、代码审查模板、修 bug 模板和提交信息模板不用从零开始踩一遍我前面说过的坑。我自己的体会是模板体系的收益不是一次到位的。最早我只写了一个几十行的 CLAUDE.md后来每次发现 Claude 在项目里反复犯同一个错比如又在 commit message 里写 update 这类无信息量动词或者又擅自改了没让我看到的文件我都会把对应规则补进模板。模板是活的应该跟着项目痛点持续迭代。最后分享一个小技巧如果你在会话中临时给了 Claude 一段效果很好的指令用完立刻追加进对应的命令模板别等以后用到时再回忆。这套体系维护成本很低但回报会随着使用次数不断放大。
Claude Code模板体系实战：用CLAUDE.md与命令模板构建高效AI编码工作流
如果你和我一样用 Claude Code 干活已经成为每天的固定动作那你早晚会遇到同一个问题同一个项目、同一类任务第一次交代时讲得清清楚楚换一个新分支、新开一个会话又得从头再说一遍项目背景、技术栈、代码路径和验收标准。我一开始觉得这只是多点几下键盘的事直到有一次连续开五个会话处理五个 bug每个会话开头都在复制同一段项目说明才意识到这事一点都不优雅。claude-code-templates 这套方法论要解决的就是这个问题把反复出现的背景、规则和任务结构沉淀成模板让 AI 编码助手每一次都能快速进入状态把有限的注意力留给真正需要处理的业务逻辑。这套模板不是什么官方发行的魔法插件它本质上是一组文件组织实践核心载体包括项目根目录的 CLAUDE.md、.claude 目录下的命令模板以及用户目录下的全局规则。适合谁我觉得只要你在认真用 Claude Code 写代码、改代码、审代码都值得花半小时搭一套尤其是多仓库切换开发、团队协作仓库、以及任务类型高度重复的日常维护场景。接下来我把实际项目中打磨出的模板体系完整拆开讲每一层都有具体写法也有可以直接抄走的示例。1. 模板体系为什么是使用 Claude Code 的必经之路1.1 没有模板时我踩过的效率坑早期用 Claude Code我是典型的现场口述流。新建一个仓库先告诉它这是 Go 写的后端服务用的 Gin 框架数据库是 PostgreSQLAPI 风格走 REST测试用标准库的 testing 包……这些信息每次开场都要讲一遍讲完之后才开始安排真正的任务。问题很快就暴露了。第一个问题是上下文被反复灌入的重复信息占满。前面那段项目背景看起来不长但加在一起差不多要一两千 token如果你习惯用中文啰嗦地描述成本更高。任务做到一半Claude 经常开始忘记前面的项目设定我得反复强调我刚才不是说了数据库在 internal/repository 吗。这种体验很像带了一个记忆只有七秒的实习生。第二个问题是输出风格飘忽不定。同一个仓库里它今天用中文注释明天用英文注释今天写测试断言按行描述明天又改成表格驱动。代码审查的时候我得花额外精力去辨别这个风格变化是故意的还是它随机发挥。第三个问题是团队协作时每个人喂给 Claude 的背景口径不一致你说是 A 方案他说是 B 方案最后 AI 生成的东西风格割裂。后来我意识到这不是 Claude 笨而是我给的信息颗粒度太粗、格式也不稳定。更本质的原因是稳定信息没有被抽离成可复用资产。项目背景、代码约定、命令清单这些内容在每一次会话里都相同重复描述它们既浪费上下文又引入了不确定性。模板化的第一层价值就在这里把稳定信息抽出来让每次新会话都能快速加载同一套背景知识。1.2 模板化的三个直接收益收益一上下文预算更充裕。没有模板时每个会话开头要花一两千 token 重复背景有了 CLAUDE.md 之后同样信息用结构化文本承载加载效率更高省下来的 token 全部可以留给真正的编码任务。任务越长、仓库越复杂这种优势越明显。收益二输出一致性显著提升。当模板里写清楚注释语言、命名风格、提交信息格式、测试策略Claude 每次生成的结果会主动对齐规则。我最近在几个项目里都指定了注释用中文、变量命名用英文、commit 用 Conventional Commits 格式之后基本没再收到过风格跑偏的产出。收益三团队协作有了统一底座。几个人共用一个仓库把模板纳入 Git 管理所有人都加载同一份 CLAUDE.md 和同一组命令模板AI 辅助代码质量的下限会被整体抬高。后来我们团队的 Code Review 负担明显变轻因为 AI 生成代码在风格层面几乎不需要人工纠正审查重点可以放在逻辑和业务正确性上。2. 模板体系整体设计三层结构的思路2.1 第一层项目级记忆模板CLAUDE.mdCLAUDE.md 放在项目根目录是 Claude Code 会话启动时的项目记忆。它会在启动时被自动读取相当于一份持续生效的系统指令不需要你每次手工--load或者复制粘贴。我的理解是它解决的是一句话问题让 Claude 在动手之前就知道自己在哪个项目、遵守什么规矩。我写 CLAUDE.md 的三条设计原则只放稳定信息。项目定位、技术栈、目录结构、常用命令、风格规范这些变数小的内容全部沉淀进来。临时任务相关的内容比如这次发布要处理超时问题不要写进 CLAUDE.md应该放任务模板里。不使用形容词。写成运行测试go test ./...不要写请务必认真运行测试写成错误处理统一使用 errors.Wrap不要写尽量做好错误处理。模板是给 AI 的约束不是口号。控制篇幅。我一般控制在 80 到 150 行以内规则数量不超过 15 条。内容太长会导致信息衰减Claude 在处理长上下文时对开头和结尾的注意力更集中所以我能压缩就压缩把最重要的规则放到文件最前面。2.2 第二层任务级提示词模板项目级记忆管背景任务级模板管具体任务怎么做。我会把高频任务固化成独立 Markdown 文件放在 .claude/commands/ 目录下文件名就是斜杠命令名。比如 code-review.md 对应/code-reviewwrite-tests.md 对应/write-testsfix-bug.md 对应/fix-bug。这样做的好处很明显第一不用每次临时组织语言任务模板里已经写清楚目标、范围、约束和输出格式第二模板支持变量占位符调用时可以填充具体参数比如/code-review internal/order/service.go通用性和定制化同时满足第三任务模板可以引用项目级约定两边互相配合不会出现CLAUDE.md 规定了注释用中文任务模板却要求不写注释这种冲突。这个目录建议放进 Git 仓库。团队里的所有人共享同一套命令模板新人上手时看一眼 .claude/commands 就知道这个项目通常用 AI 做什么类型的任务这本身也是团队知识的沉淀。2.3 第三层组织级公共模板在多仓库之间切换久了你会发现项目模板里有大量重复内容比如禁止提交密钥commit 信息用 Conventional Commits 格式遇到不确定需求先提问不要自行假设这些规则几乎每个项目都一样。把这些内容在每个仓库各写一份维护成本太高改一处要同步所有仓库。我会抽到用户目录下的全局模板里实测路径是 ~/.claude/CLAUDE.md不同版本可能有差异装好后先用官方文档确认一下相当于全项目通用的宪法。项目根目录的 CLAUDE.md 只保留差异化信息比如技术栈、命令、架构布局。两层配合加载全局规则管底线项目规则管细节。需要提醒的是不要一上来就做全局抽象。更稳的路径是先在项目里把本地模板用顺几个月后回头看把三四个项目里重复出现的内容抽出来再提升到全局层。过早抽象会抽错位置把项目特有规则误当成通用规则反而给后面的项目埋坑。3. 核心模板细节拆解与写作要点3.1 CLAUDE.md 的结构与写法我推荐的项目级 CLAUDE.md 结构是这样的项目概述两到三句话说明这个项目做什么给 Claude 建立基本认知。技术栈清单用列表列出语言、框架、数据库、关键工具最好带上版本。常用命令测试命令、构建命令、lint 命令、启动命令全部给全命令。代码风格约定命名习惯、注释语言、错误处理偏好、目录组织方式。关键架构信息模块边界、数据流、部署形态让 Claude 知道改一个文件可能影响哪些模块。约束与禁止项不要改哪些文件、不要执行哪些破坏性命令、不提交哪些目录。一段真实的 Golang 项目示例# 项目概述 shop-api 是电商后端服务提供商品、订单、用户三个核心模块的 REST API。 # 技术栈 - Go 1.22 - Gin - PostgreSQL 15 - Redis 7 - Docker / docker-compose # 常用命令 - 启动服务go run ./cmd/server - 运行测试go test ./... - 单测指定包go test ./internal/order/... - 数据库迁移make migrate-up # 代码风格 - 变量、函数使用英文命名注释使用中文 - 错误处理统一使用 errors.Wrap 包装不在底层吞掉错误 - 接口命名动词开头Repository 接口放在 domain 层 - API 响应格式统一为 {code:0,data:...} # 架构信息 - cmd/server 为程序入口 - internal/domain 放领域模型 - internal/repository 负责数据库访问 - internal/service 放业务逻辑 - internal/handler 处理 HTTP 请求 # 约束 - 不要修改 internal/repository 中已有的历史迁移文件 - 不要把密钥写进代码一律使用环境变量 - 修改公共代码时必须同步更新对应的单元测试这个结构里最重要的是约束段。它定义了 Claude 的行为边界相当于告诉 AI 哪些地方不能碰这比告诉它能做什么更重要。我见过太多模板只写这个项目很复杂请小心修改这种模糊约束等于没有约束。3.2 任务提示词模板的四个关键部分任务模板虽然因任务而异但骨架是固定的。我把它拆成四个部分写代码审查、写测试、修 bug、写文档都适用任务目标一句话说清楚要达成什么。不要用请帮助我改进一下要说对本次代码变更进行严格审查找出可能引发线上问题的风险点。输入范围明确告诉 Claude 基于哪些文件、哪些分支、哪些上下文信息去工作避免它自己乱翻目录、扩大行动范围。约束条件写明不要改哪些范围、采用什么算法、遵循什么规范、是否允许修改测试之外的文件。输出格式要求给出结构化的结果比如变更清单、测试结果说明、风险提示。AI 输出一旦有固定格式审查和交接的效率会高很多。我再加一个容易被忽略的部分兜底规则。在模板末尾写一句如果信息不足先列出问题清单向我确认不要自行假设。这句话能拦住 AI 在需求不明确时自作主张对修 bug 这类任务尤其重要防止它猜错根因直接动手。3.3 变量占位符与调用方式在 .claude/commands/ 目录下的模板里支持用{{变量名}}的方式定义参数。调用斜杠命令时Claude 会识别占位符自动提示或要求你补充对应内容。我写命令模板时的习惯是占位符命名一定用可读的名称比如{{文件路径}}、{{问题描述}}不要用a、b这种缩写。占位符数量控制在三到五个太多会让调用流程变得烦琐。能在文件开头用一句话说明的就不要设计成占位符。举个例子我调用/code-review internal/order/service.go模板启动后Claude 会知道审查对象是 internal/order/service.go。如果你在模板里把目标文件定义为占位符那么通知时就可以直接把路径传给命令如果占位符没填Claude 会反过来问你请问这次审查变更涉及哪个文件多一轮交互。4. 实操一套可直接落地的模板配置4.1 第一步写出第一个 CLAUDE.md在实际项目里我不会一口气把 CLAUDE.md 写得很长而是先用十分钟搭底稿之后在真实迭代中持续补充。具体操作在项目根目录创建 CLAUDE.md按第 3.1 节的结构填入内容。如果项目里已经有 README可以直接参考 README 里的技术栈和启动命令但写法要调整README 是给人看的CLAUDE.md 是给 AI 当系统指令用的语气必须更直接信息密度要更高。写完第一个版本后我建议做一件事开一个新会话输入一个只有 AI 知道答案的问题来验证加载。比如问这个项目的测试命令是什么看它能不能直接答出来。如果它答不上来说明模板没有被正确加载检查文件位置和命名然后再进入下一项任务。这个验证动作很便宜能帮你尽早发现路径错误之类的问题。4.2 第二步落地两个高频任务模板任务模板我从使用频率最高的两个开始做。第一个是代码审查文件 .claude/commands/code-review.md--- description: 对指定文件或本次变更做严格代码审查 argument-hint: [目标文件或路径] --- 对代码变更进行一次严格代码审查。 任务目标找出可能引发线上问题、性能隐患和风格偏差的问题。 审查范围本次变更涉及的 {{文件路径}}以及与之直接相关的调用方。 约束 - 不修改代码只输出审查意见 - 按严重程度从高到低排列问题 - 每个问题必须给出文件与行号参考说明原因和修复建议 - 如果发现与 CLAUDE.md 中约定不一致的地方单独列出 输出格式 1. 总体评价3-5 句 2. 高风险问题 3. 中低风险问题 4. 风格与约定问题 5. 建议的下一步动作第二个是修 bug文件 .claude/commands/fix-bug.md--- description: 定位并修复一个 bug argument-hint: [问题描述] --- 现在有一个 bug 需要修复。 Bug 描述{{问题描述}} 复现路径{{复现步骤}} 预期行为{{预期行为}} 实际行为{{实际行为}} 要求 - 先定位根因用 3-5 句话说明根因分析再动手修改 - 只修改必要的文件不要顺手重构无关代码 - 修复后补充一个针对该场景的测试 - 如果涉及数据库变更必须提醒我新增迁移脚本这两个模板覆盖了我日常使用的 70% 场景。后面我陆续加了 write-tests.md、generate-docs.md、commit-message.md但都是在跑顺基础模板之后按需补的没有一开始就铺开。4.3 第三步提交到版本库并维护模板.claude 目录建立后我会把它提交到 Git跟着项目一起管理。这一步是团队协作的关键否则你本地一套模板同事本地一套模板AI 行为仍然无法对齐。我的维护习惯是这样的模板更新也走 code review。比如我想给 CLAUDE.md 增加一条禁止使用 fmt.Print就开个 MR 说明原因同事确认后再合入。模板变更导致的 AI 行为变化有时候比代码变更影响范围还大因为它会影响将来所有的新会话所以不能随手改完就推上去。我还会在模板文件头部写一行最近更新时间和更新原因方便追踪历史。没有这个习惯之前我经常对着一段模板内容想不起来当初为什么加它。注意CLAUDE.md 或命令模板里的内容最好与项目代码保持同步。当你改了架构、换掉框架、废弃了某个命令务必同步更新模板。模板一旦过时AI 会依据错误背景工作比没有模板更糟。5. 常见问题与排查技巧实录5.1 模板没生效Claude 好像不记得 CLAUDE.md 内容这个问题我遇到过一次很典型的。我明明在项目里写了 CLAUDE.mdClaude 还是不知道测试命令后来发现文件放在了 src/ 子目录而 Claude Code 启动时的工作目录在项目根目录它默认读取的是启动目录下的 CLAUDE.md。把文件挪回根目录之后问题就消失了。排查方向按顺序来文件位置和命名确认 CLAUDE.md 在你启动 claude 命令的工作目录下且文件名大小写一致。会话状态如果是在已有会话里新增的模板它可能不会立即加载输入 /clear 清空会话后重新加载或者直接重启终端。内容结构检查 CLAUDE.md 是否超过合理长度。如果文件有一千多行Claude 很可能只记住了开头部分把最关键的规则放在文件最前面。命令模板路径确认命令文件是 Markdown 格式并且位于 .claude/commands/ 目录下文件名对应斜杠命令名。5.2 模板太长导致上下文紧张上下文窗口再大也架不住模板里塞了一堆重复和低信息量的内容。我见过有人把整个团队 wiki 复制进 CLAUDE.md结果每个会话一开始就吃掉几万 token任务做到一半上下文就爆了。我的处理办法是分级存放全局 CLAUDE.md 只放 5 条以内通用底线规则项目 CLAUDE.md 控制在 80 到 150 行展开性的详细说明和长例全部放进斜杠命令模板按需加载。比如 pytest 的完整用法、项目的详细架构设计说明这些只有在写测试或者做深层重构时才需要全部进 write-tests.md 和 refactor.md不要常驻在 CLAUDE.md 里。另外要留意全局模板与项目模板之间的重复。如果两者都写了注释使用中文这条信息就占了两份空间而且如果写的内容冲突AI 还会陷入矛盾。我会在全局模板里声明一句项目根目录的 CLAUDE.md 优先级高于本文件避免同层竞争。5.3 团队协作时的模板冲突模板纳入 Git 之后冲突问题变成了团队协作问题。最典型的情况是A 同事在模板里加了所有 API 返回结构统一加 request_idB 同事可能正在写一个不需要 request_id 的模块结果所有新会话生成的代码都带着这一规则B 的项目代码与模板规则格格不入。我的建议是模板变更必须走代码评审并在变更说明里写明影响范围。另外如果某个仓库有特殊约束不要考虑在全局模板里加豁免条件而是在该仓库的 CLAUDE.md 里明确覆盖。一层管通用一层管特殊两层职责清晰就不需要一堆互相矛盾的规则。还有一个实用技巧把模板文件也纳入 review 时的检查项。提交模板变更的 MR 里除了看模板内容还要检查对应样例输出是否仍然合理。如果在 review 代码时发现某段生成结果风格怪异第一反应可以去看模板最近有没有变更。6. 进阶玩法把模板和自动化流程接起来6.1 用 hooks 在工具调用后自动格式化模板能约束 AI 生成内容的风格但还漏了一层生成代码后是否自动格式化。我目前的做法是在 .claude/settings.json 里配置 PostToolUse hooks在 Claude 编辑或写入文件后自动跑一遍格式化工具。一个大致的配置结构如下具体环境变量名以你所用版本的官方文档为准{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: gofmt -w $CLAUDE_FILE_ABSOLUTE_PATH } ] } ] } }配置好之后Claude 写完文件会自动格式化我不用再手工跑一遍 gofmt也减少了AI 生成的代码格式不规范这类 review 反馈。模板负责内容风格hooks 负责机械格式化两者分开各管一摊。6.2 用模板初始化新项目脚手架模板体系成熟后我会把一套初始化模板单独抽出来放在一个 template 仓库里里面包含 CLAUDE.md 骨架、.claude/commands 基础命令集合、还有目录结构说明。新建项目时直接拷贝这套骨架到新仓库把技术栈、项目描述替换成新项目的真实内容。这个动作能把模板体系的搭建成本压缩到一首歌的时间。新项目一开始就有 CLAUDE.md、代码审查模板、修 bug 模板和提交信息模板不用从零开始踩一遍我前面说过的坑。我自己的体会是模板体系的收益不是一次到位的。最早我只写了一个几十行的 CLAUDE.md后来每次发现 Claude 在项目里反复犯同一个错比如又在 commit message 里写 update 这类无信息量动词或者又擅自改了没让我看到的文件我都会把对应规则补进模板。模板是活的应该跟着项目痛点持续迭代。最后分享一个小技巧如果你在会话中临时给了 Claude 一段效果很好的指令用完立刻追加进对应的命令模板别等以后用到时再回忆。这套体系维护成本很低但回报会随着使用次数不断放大。
