claude-code-templates：用三层模板固化 AI 上下文，让编程助手不再失忆

写模板之前先说说我为什么要捣鼓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 读取的时机都不同层级存放位置适用场景核心作用全局层~/.claude/CLAUDE.md所有项目通用定义 AI 的角色边界、通用禁忌、默认编码风格项目层项目根/.claude/CLAUDE.md特定项目定义技术栈、目录结构、构建命令、部署流程等任务层.claude/commands/下按需调用高频特定操作把“加一个新接口”“修复一个 Bug”“跑一遍 Code Review”沉淀成固定流程这个设计参考的是 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 自作主张给代码补一堆没必要的注释或者把原有的逻辑重构成另一个样子。那么我的全局模板第一段就写得很明确你是我的编程助手执行我的指令时要遵循以下原则最小改动原则优先做完成任务所需的最小变更不擅自重构无关代码。保持风格一致严格遵循项目现有代码风格不引入与现有代码风格不一致的习惯用法。注释克制不为简单逻辑增加注释只有当逻辑复杂或有非直观决策时才添加。主动汇报不确定性遇到不确定的改动方案时先列出选项和处理后果再做选择时间充足时优先询问我。这四条看起来简单但每一句背后都有血泪教训。比如“最小改动原则”这个事早期我让 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 15docker 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 处理器里禁止写业务逻辑 - 添加外部依赖前先说明理由 ## 调试和日志 - 日志统一使用 slogJsonHandler 输出到 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 模板维护清单与问题速查表最后给一张我在长期使用中沉淀的问题排查速查表遇到问题先按这个清单走一遍基本能覆盖九成情况现象可能原因处理动作AI 完全忽略项目技术栈项目模板.claude/CLAUDE.md不存在或路径错误检查文件是否存在并位于项目根目录全局规则和项目规则冲突两个文件里同一话题说法不一致统一为项目层优先全局层只保留通用底线模板内容正确但 AI 执行时遗忘模板过短没有在上下文中占据足够关注度适当扩充关键命令和项目文化描述增强存在感AI 频繁把快捷键/命令当作要执行的操作模板里命令与说明混排所有命令放进代码块与叙述文字明确隔离改了模板但表现没变会话还是旧的未重启新开会话测试必要时使用/clear清空上下文AI 输出过于冗长、带太多分析模板里没有输出格式约束在项目模板末尾加上“输出格式结论先行、原因后置按列表返回”这张表我贴在项目 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 行为的变化稳定了再慢慢加任务模板。模板本身不要图大而全重点是那些反复出问题的点被固化下来它就会成为你工作中最省心的那部分。