写模板之前，先说说我为什么要捣鼓claude-code-templates这个东西。用过 Claude Code 的朋友应该都有同感：这玩意儿单次对话很聪明，但一旦项目复杂度上来，任务一多，它就开始“失忆”了——今天的它不知道昨天的它定了什么规范，换个目录甚至换个终端，整个上下文就清空了。我一开始也没当回事，直到连续几次让它在同一个项目里反复做同一类改动，每次都给我换一套写法，我才意识到问题出在哪儿：上下文没有沉淀，每次会话都是在重新认识这个项目。

claude-code-templates就是奔着解决这个问题去的。它不是某个现成的工具插件，而是一套围绕 Claude Code 设计的方法论加文件体系：把项目的技术栈、编码规范、高频任务流程、禁区约束写成结构化的模板文件，让 AI 每次启动时都能快速加载这些“项目大脑”。说到底就是一句话——给 AI 写一份使用说明书，而且是它每次开工前都必须读的那种。

这篇文章我会从设计思路、模板文件结构、实际配置写法、踩坑记录一路讲下来，最后聊聊这东西怎么在团队里推广。适合正在用 Claude Code 但觉得效果不稳定的人看，也适合刚接触、想一开始就规范化使用的人参考。

1. 项目整体设计与核心思路拆解

1.1 模板要解决的本质问题：AI 的上下文失忆症

先讲一个真实场景。我有几个项目跑在不同的语言栈上，一个是 Go 微服务，一个是 Next.js 前端，还有一个是 Python 的数据处理脚本。最早我用 Claude Code 的时候，采用最原始的做法：每次开新会话，先花三五分钟把项目背景、目录结构、技术栈、代码风格全部口头交代一遍，然后才开始真正干活的对话。问题是项目一多，这套开场白就开始变形，今天忘了说“不要动 migrations”，明天忘了说“日志用 slog 别用 log"。AI 一旦缺了这些关键约束，就会自顾自地发挥，改出来的代码有时能跑，但风格上跟老代码格格不入，要么就是不小心踩了不该踩的目录。

模板要解决的核心就是用文件把“项目上下文”固化下来。AI 本质上是无状态的，你给它多少上下文，它就有多少发挥依据。与其靠脑子里维护一个“对 AI 的接口文档”，不如把这个文档落到磁盘上，作为项目的一部分。这就是claude-code-templates最基本的出发点——不是让 AI 更聪明，而是让它每次开工时都站在同样的信息起点上。

确定了这个方向之后，我意识到光有一个 README 式的说明文档是不够的。AI 读取文件的能力很强，但面对一堆自由散漫的文档，它仍然要靠猜去判断哪些内容重要、哪些是废话。所以这个模板体系必须分层：什么级别放全局，什么级别放项目，什么级别针对具体任务，每一层的措辞方式和指令密度都不一样。这就是接下来要讲的层次划分。

1.2 三层模板架构：从全局到任务的距离递减

我把模板体系规划成三层，每一层管的事情和 AI 读取的时机都不同：

这个设计参考的是 CSS 的优先级意象：全局层像 reset 样式，给 AI 安全兜底；项目层像主题样式，定义项目特性；任务层像组件样式，最具体、最直接指导动作。三者在 AI 的 prompt 上下文里天然有先后顺序和覆盖关系，全局层一般不重复项目层的内容，项目层一般不重复任务层的内容，避免指令冲突。你可能会问，为什么不把所有内容都堆在一个文件里？因为我们按需加载，任务层只有特定指令触发时 AI 才去读那个文件，全局和项目文件则是默认注入。这样既能控制上下文长度，又能做到精度最高的指令只在最需要的时刻出现。

这个三层划分在实测中非常有效。以前我可能跟 AI 说十句话才能把它“带入状态”，现在它启动时自动读取全局加项目模板，基本上一两句短指令就能直接干要干的活儿。这部分后面实操章节我会给一个可以直接复制的文件模板，你先记住这个架构，后面全是基于它展开的。

2. 模板库结构与配置文件写法详解

2.1 目录规划：每一层该放什么文件

claude-code-templates作为一个项目，其目录结构其实也遵循了这套分层思想。我建议所有想复用这套方案的人都按下面的结构组织：

claude-code-templates/ ├── README.md # 模板库总览，讲解怎么使用 ├── global/ │ └── CLAUDE.md # 全局模板，软链或复制到 ~/.claude/CLAUDE.md ├── project/ │ ├── CLAUDE.md.example # 项目级模板的示例 │ └── structure.example.md # 项目结构说明示例 └── commands/ ├── add-feature.md # 任务级模板：添加新功能 ├── fix-bug.md # 任务级模板：排查和修复 Bug └── code-review.md # 任务级模板：代码审查

为什么要把全局模板和项目模板分开存放？因为两者更新的频率和触发范围完全不同。项目模板是跟着具体仓库走的，你改的越频繁越合理，因为项目在演进；全局模板是你长期稳定的个人偏好，一年也动不了几次。分开之后，你可以单独维护模板库这个仓库，项目层通过软链或者复制到具体项目里，任务层直接原位放置。我一个朋友把全局模板用 git 管理了之后，换新电脑只需要 clone 一个仓库再执行一个安装脚本，整套环境就回来了，非常舒服。

这里有个细节很容易踩坑：Claude Code 读取模板的默认位置是有讲究的，全局模板必须放在~/.claude/CLAUDE.md这个固定的路径，而不是你模板库里的global/目录。所以我的模板库里永远不会直接放这个文件名，而是放一个源文件，通过脚本去分发。项目模板则放在项目根目录的.claude/CLAUDE.md，这个是 Claude Code 自动发现的位置。记住这个区别，不然你费心写的模板根本不会被读到。

2.2 全局模板写法：管好 AI 的“身份认同”

全局模板里我放的第一件事是角色定义和边界。举个例子，我平时写 Go 和 TypeScript 比较多，而且我很反感 AI 自作主张给代码补一堆没必要的注释，或者把原有的逻辑重构成另一个样子。那么我的全局模板第一段就写得很明确：

你是我的编程助手，执行我的指令时要遵循以下原则：

1. 最小改动原则：优先做完成任务所需的最小变更，不擅自重构无关代码。
2. 保持风格一致：严格遵循项目现有代码风格，不引入与现有代码风格不一致的习惯用法。
3. 注释克制：不为简单逻辑增加注释，只有当逻辑复杂或有非直观决策时才添加。
4. 主动汇报不确定性：遇到不确定的改动方案时，先列出选项和处理后果，再做选择；时间充足时优先询问我。

这四条看起来简单，但每一句背后都有血泪教训。比如“最小改动原则”这个事，早期我让 AI 修一个 bug，它顺手把我整个路由文件格式化了一遍，diff 里头充满了无关修动，review 的时候差点崩溃。有了这行明确的指令后，这种“热情过度”的情况大幅减少。注意写法上的关键点：一定是祈使句 + 场景，不能说“请尽量保持代码风格一致”，因为“尽量”这种词在 AI 眼里约等于没有约束。

全局模板后半段是通用的工程约定，比如：不要在没有明确要求的情况下删除文件；执行命令之前先解释要执行什么；涉及第三方服务时不要假设有凭据可用，需要先说明环境变量。这些内容每个项目适用，属于底线级别的要求，适合我上文说的“兜底”角色。

2.3 项目模板写法：定义技术栈与关键约束

项目模板是把一个仓库的“脸面”立起来的关键文件。我先给出一个可直接套用的基础骨架，然后在后面逐一解释每部分为什么要这么写：

# Project Context ## 技术栈 - 语言: Go 1.22 - Web 框架: gin - 数据库: PostgreSQL 15，通过 docker compose 启动 - 缓存: Redis 7，通过 docker compose 启动 - 主要第三方库: sqlc、jwt-go、stripe-go ## 目录结构 - `cmd/server/`：服务入口 - `internal/`：业务逻辑，内部包 - `internal/handler/`：HTTP 处理器 - `internal/service/`：业务服务层 - `internal/repository/`：数据访问层 - `migrations/`：数据库迁移文件 - `test/integration/`：集成测试 ## 常用命令 - 构建: `go build ./...` - 测试: `go test ./...` - 数据库启动: `docker compose up db` - 迁移: `migrate up` ## 关键约束 1. 不在 `internal/` 之外引用内部包 2. 数据库改动必须新增迁移文件，不直接改已有迁移历史 3. 错误处理统一使用 `fmt.Errorf` 包裹上下文，不裸抛 4. API 响应结构遵循 `{code, message, data}` 规范

这套模板的写法最核心的技巧是“具体到命令，精确到路径”。你给 AI 的信息越具体，它瞎编的概率就越小。我刚开始写的时候犯过跟很多人一样的错误：只写“本项目是 Go 微服务”，就以为够用了。结果 AI 问我用什么框架、数据库在哪启动、测试命令是什么，一个问题接一个问题，比我还像个新人。把“常用命令”写进模板是为了让 AI 在执行操作时可以直接照抄，而不是靠猜。你甚至可以把构建命令从简单到复杂都列出来，它执行错一次的概率就低一分。

关键约束那部分需要针对项目壁垒来写。什么算壁垒？就是你吃过亏、不想再重复的教训。比如“数据库改动必须新增迁移文件”，是因为我早期让 AI 顺手改了一个已经提交过的迁移文件，导致 dev 环境数据全乱。写进模板之后，这类错误就彻底从我的工作流里消失了。项目模板是可以随项目演进长期持续更新的，每次踩坑、总结出来，就把它固化进模板，下一次 AI 就能自动避开。

3. 从零搭建 claude-code-templates 的完整实操

3.1 初始化模板仓库与全局配置

说了这么多理论，实际动手才是正经事。首先在自己的工作目录里初始化模板仓库：

mkdir claude-code-templates cd claude-code-templates git init mkdir -p global project commands

全局模板我建议直接用文件复制的方式，而不是软链，因为软链在换机器的时候容易断。先在global/CLAUDE.md里写上最通用、最底线的几条原则，内容可以参考 2.2 节的那四条基础原则，再补充两条属于你个人的偏好。这里重点提醒一下：全局模板不是越多越好，而是越通用越好。什么东西放全局，什么东西放项目，判断标准就是：这一条规则对“我所有的项目”都成立吗？如果不成立，就应该下沉到项目模板里去。比如“错误处理用fmt.Errorf”只对 Go 项目成立，就不能写进全局。

写完之后执行分发：

mkdir -p ~/.claude cp global/CLAUDE.md ~/.claude/CLAUDE.md

这里有个我个人的习惯：全局模板我坚持用文本文件而非代码片段来管理，因为它本身就是要持续迭代的“元文档”，用文本文件让 AI 读起来零障碍。不要小看这一步，文件路径放对了，Claude Code 每次新会话都会自动加载，几乎没有任何感知成本。很多人的全局模板没效果，最后排查下来都是因为路径放错了位置。

3.2 项目层模板的编写思路与完整示例

接下来是最能体现这套模板体系价值的部分：项目层。假设你现在正在一个新起的 Go 项目里跑 Claude Code，第一次用的时候就该把.claude/CLAUDE.md建起来。我直接给你一个可以复制的完整示例，然后逐段讲为什么这么写：

# 项目：用户账单系统 ## 技术栈 - Go 1.22 + gin + sqlc - PostgreSQL 15（docker compose） - Node.js 20 + pnpm（仅用于前端资源构建） ## 目录结构 - `cmd/api/main.go`：服务入口，占位极小 - `internal/domain/`：领域模型，DTO - `internal/app/`：应用层，用例与编排 - `internal/infra/`：基础设施层：数据库、缓存、外部 API - `internal/interfaces/api/`：API 接口层，gin handler ## 常用命令 - 启动全栈服务: `docker compose up` - 运行后端测试: `go test ./...` - 启动本地开发: `go run ./cmd/api` - 生成数据库代码: `sqlc generate` - 数据库迁移新增: `go run ./cmd/migrate new <name>` ## 编码规范 - 领域层不依赖任何外部包 - 数据库错误统一转换为领域层错误，不向上抛原始错误 - HTTP 处理器里禁止写业务逻辑 - 添加外部依赖前先说明理由 ## 调试和日志 - 日志统一使用 `slog`，JsonHandler 输出到 stdout - 禁止在日志中记录敏感信息，如用户密码、token - 调试时可以增加临时日志，但提交前必须移除

细看这段示例，你会发现它的结构遵循一个稳定顺序：先让 AI 知道项目“靠什么跑起来”，再告诉它“代码在哪里”，再告诉它“怎么操作项目”，最后告诉它“写代码的时候要注意什么”。这个顺序是有讲究的，因为 AI 解析模板时如果先看到一长串规范，它反而容易忽略后面的命令；而先给技术栈和命令，它就能在“行动”之前建立一个基本的行为框架。

还有一个细节值得单独说：像“添加外部依赖前先说明理由”这种约束，很多人觉得是画蛇添足，但实测下来非常有用。AI 常常在修复一个问题时顺手引入一个新的库，而这个库替换的逻辑本来可以避免。把这条约束加进去后，至少它会先问一句“这里想引入 xxx 库处理 xxx，是否可以？”，给你一个干预的机会。类似的“边界条款”，写几条最痛的即可，不要每个都能想到的都写进去，不然模板会变得冗长，而且 AI 的注意力会被稀释。

3.3 任务层模板：把高频动作变成固定流程

任务是模板体系里最有即时回报的部分，因为它是按需加载的，而且指令密度最高。比如你经常让 AI 修 Bug，就可以写一个.claude/commands/fix-bug.md，内容结构大概是这样：

# 修复 Bug 的标准流程 ## 输入 - 用户提供的 bug 描述，或一段复现步骤 ## 排查步骤 1. 先复现问题，执行相关测试或启动服务复现 2. 定位到相关文件，读取里面的上下文，不要只看报错堆栈 3. 写一个可复现的最小测试用例（如果测试体积过大，说明核心问题所在） 4. 修复后，执行相关包的测试，确认全部通过 5. 检查改动范围内是否有相似问题，顺手标记，但不在本次修复中改动 ## 提交说明 - 修复单次问题，提交信息描述为 “fix: <问题概括>” - diff 中不得出现超出修复范围的代码变动

这类任务模板的价值在于把“让 AI 按你的工作习惯做事”这个需求变成了现实。就说“先复现问题”这个点，多数 AI 在没有指引的前提下偏好从堆栈到代码直接猜原因，而用模板约束之后，它会先尝试复现，从现象端一步步跑，成功率提升得非常明显。写任务模板时注意一点：指令要写成流程式，步骤之间要有明确的先后顺序，而不是并列的几条信息。AI 执行这类流程式指令比执行“一条规则列表”要稳定得多，因为它天然是 step-by-step 的推理模型。

其他任务模板也都是这个逻辑：add-feature.md里可以写上“先读相邻功能的实现 -> 列出接口影响 -> 分步骤实现 -> 追加测试”；code-review.md里可以写上“按安全、正确性、可维护性的优先级逐项检查-输出 summary 表格”。关键是把你自己解决问题时脑子里的“检查单”搬到文件里，AI 会替你按清单执行，而且不会省略任何一步。

4. 实测中踩过的坑与排查实录

4.1 模板文件不生效的 5 个高频原因

盲目自信地配好模板后，我发现有时 Claude Code 仿佛还是不认识它。排查了几次之后，我总结出最容易导致“模板失活”的原因：

第一，文件路径放错了。全局模板必须放在~/.claude/CLAUDE.md，项目模板必须放在项目根目录下的.claude/CLAUDE.md。路径差一个层级，AI 压根不会读它。别以为放到docs/里 AI 就会去翻，不行，自动加载是有固定路径的。第二，Markdown 语法被 AI 理解成了别的意思，比如过量的 # 层级让它误以为是代码注释。有个朋友给的模板里出现了大量#开的示例代码行，结果 AI 把代码当注释忽略掉了，等于模板白写。解决方式很直接：代码示例尽量空行隔开并用反引号包住。第三，模板里塞了类似“if 条件成立，则……”的指令，AI 在处理时可能只读取分支之一。我最开始写过“如果前端构建失败，就尝试使用 pnpm 重新安装依赖”，就这一条造成了两次执行断裂。后来我把指令改成“遇到前端构建失败时，执行pnpm install后重试”，干净得多。第四，全局和项目模板出现冲突。全局写了“不要自动重构”，项目里却写了“修复时顺手把过时的函数签名更新下”，AI 会两头不知道听谁的。这要求我在写模板的时候必须做一层“重叠区检查”，同一话题在两个文件里只能定义一个方向。第五，同一会话里改了模板，AI 已经加载过旧版本。这个不算模板问题，但很容易让人误判模板没生效，正确做法是新开一个会话再测试。

4.2 指令过于口语化导致的执行偏差

这算是我在模板写作上最常犯的错，也是最能体现写作能力差异的地方。比如我以前在某条约束里写“不要瞎改代码风格哦”，AI 反而经常会困惑“哦”字到底算不算指令的一部分。后来我把所有口语化的语气词全部去掉，改成“不修改与任务无关的格式”。再比如“尽量不要用全局变量”这种说法，AI 的分析倾向仍然是“尽量”意味着可做可不做。对付这种模糊语气，我的规则是模板中只能出现两类动词：必须做什么和禁止做什么，中间态的“尽量”“可以”“最好”全部删除或转换为明确指令。比如“尽量复用现有工具函数”改成“优先复用现有工具函数；若有新需求且现有函数不满足，先说明再新增”。这样写虽然啰嗦，但执行效果天差地别。

说实话，写模板本身就是一种提示词工程修炼。你越能把自己脑子里的隐性规则显式化，模板的质量就越高。我之前一直觉得自己“心里知道”就是写清楚了，但 AI 抓不住潜台词。踩过几次坑之后我的做法是：每写完一条约束，都从“一个完全不了解本项目的新人”的角度读一遍，觉得不够清楚就继续改。这一步看似消耗时间，但省下的远不止将来反复解释的时间。

4.3 模板维护清单与问题速查表

最后给一张我在长期使用中沉淀的问题排查速查表，遇到问题先按这个清单走一遍，基本能覆盖九成情况：

这张表我贴在项目 README 里，团队成员遇到问题时先自查，只有少数疑难问题才需要找我。对我来说，模板能不能帮团队提升效率，很大程度取决于这份“维护文档”是否完善。毕竟模板本身是活的，它是跟随项目演化不断更新的，没有维护文档就容易随人记忆而衰退。

5. 从个人工具到团队协作：模板体系的进阶玩法

5.1 用 Git 管理模板版本的演进节奏

模板体系最容易被忽视的收益，其实是“版本可追踪”。我最初把claude-code-templates当作个人私藏，直到有一次我调整了全局模板里的“错误处理”规范，导致旧项目里的 AI 行为风格一夜之间全变了，我才意识到模板无版本管理是一个隐患。从那以后我坚持所有模板进 Git，每次修改都写清楚变更说明，提交信息用简短的一句话描述意图，比如“feat: 增加 Database 变更前确认流程”“fix: 移除全局层与项目层关于日志格式的冲突”。

这种方式带来的直接好处是：当 AI 行为出现异常回归时，你可以通过 Git 历史快速定位到是哪一次模板变更引起的。比如某个项目突然开始“自作主张重构代码”，一查提交记录发现是 N 天前在项目模板里加了一条“可以顺手清理重复代码”，于是回滚或者改措辞。模板变更管理本质上跟代码变更管理没什么区别，都应该对接 Code Review 流程，特别是团队里如果有人提议改模板，至少得让其他人知道“为什么要改、影响范围是什么”。模板这东西的副作用延迟很久，不靠版本控制很难追责——虽然我们通常不需要“追责”，但我们很需要“回滚”。

在版本演进节奏上我的建议是“少而稳”。全局模板一年大改两到三次就够了，项目模板可以跟项目迭代节奏走，任务模板则是随时按需新增。不要因为 AI 今天表现不好就立刻改模板，先判断是不是上下文没喂够，或者指令本身不清晰。模板里的每一条都应该是在多轮实践中有效后才固化的，临时起意写进去的东西不但帮不上忙，有时还会添乱。

5.2 团队团队的协同复用：模板库配置评审与分发机制

模板从个人工具走向团队，这一步的难度不在于文件本身，而在于大家对“AI 协作规范”是否认同。我团队里的做法是：把claude-code-templates变成一个公共仓库，所有人可以提 PR，但合并前要经过一次快速评审。评审的标准就三条：内容是否与项目实际情况一致；指令是否为最小必要集；表述是否足够明确无歧义。评审通过之后，由维护者统一合并并打 tag，成员拉取更新后再复制到自己的项目里。

这时候你可能要问了，为什么不直接在项目仓库里维护模板？我个人的经验是：公共仓库负责沉淀“方法论”，项目仓库里的.claude/CLAUDE.md负责落地“实战细节”。这两者需要同步，但由公共仓库统一管理版本会更清晰。团队在项目中使用时，建议把公共模板作为起步，然后往项目里补充只有这个项目才有的约束。定期（比如每个迭代结束）同步一次“项目模板里的新增约束是否能沉淀回公共模板”，这样团队的 AI 协作效率就能持续往上走。

还有一个细节非常值得提：分发给团队时，不要只给一套模板文件，一定要配一个简短的“使用说明”，告诉成员这个模板会在什么时机被读取、修改后需要新开会话才会生效、哪些规则不适合绕过。我见过太多团队成员拿到模板后以为它是文档，翻了一遍就忘了；而实际上它是配置文件，需要被放在正确的位置、与被 AI 自动加载的机制配合，才能真正发挥作用。补齐“分发机制”这一环，团队使用模板的有效率至少翻倍。

根据我目前的经验，这套claude-code-templates体系最大的价值不是单一某条规则，而是让“与 AI 协作”这件事从凭感觉变成了可以演进、可以收敛的系统工程。我身边已经有几个同事在自己的项目里套用了这套结构，虽然各自的模板内容差异很大，但骨架基本一致。如果你也打算试试，我建议就从最轻的方式开始：先写一个全局限定的模板，再写一个项目模板，跑两天感受下 AI 行为的变化，稳定了再慢慢加任务模板。模板本身不要图大而全，重点是那些反复出问题的点被固化下来，它就会成为你工作中最省心的那部分。