我每天在终端里敲claude的次数比打开浏览器的次数还多。从最开始的新鲜劲过去之后我发现一个让人又爱又恨的真相Claude Code 确实能顶半个工程师但每次开新项目、接新任务我都得把同样的话翻来覆去地交代一遍——“你先读一下 README”“别急着改代码先给方案”“测试命令是 pnpm test”“代码风格参考 src 里已有的文件别自创风格”。说多了人就会烦烦了就会想一劳永逸的办法。于是我把这些重复内容全部固化成了模板就叫claude-code-templates。这篇文章会把我从零搭建这套模板库的完整过程、真实结构、踩坑经历和迭代思路全部分享出来适合所有用 Claude Code 干活、又不想每次都重复调教的开发者。这套模板库解决的本质问题是让 Claude Code 从“一个有点笨的通用助手”变成“熟悉你项目规范和团队习惯的协作者”。它不是一段简单的 prompt而是一套包含指令、快捷命令和自动化脚本的组合。如果你已经用过 Claude Code 几天觉得“这家伙不错但还差点意思”那这篇文章大概率能帮上忙。1. 为什么 Claude Code 必须配合模板使用先说一个反直觉的结论Claude Code 的默认状态是“无记忆”的。每次在项目目录下敲claude它确实会自己扫描文件结构、读取 git 状态、看看最近的改动但它不会记得你上次交代过“这个仓库不允许用 anyscript 类型”“测试只能用 vitest 不用 jest”“提交信息必须符合 conventional commits”。这意味着什么意味着每次新会话你都要重新把项目背景、技术栈、命令规范这些信息教一遍。教一次两次还行如果你同时维护五六个仓库每换一个项目就得重新解释上下文对话质量和效率会直线下降。模板解决这个问题的方式套用一句通俗的话**给 Claude Code 准备一份“入职手册”。**每个新人入职公司都要发一份手册里面写清楚我们用什么框架、代码怎么组织、上线流程是什么、哪些红线不能碰。Claude Code 也一样它需要一个项目级的“手册”让它在进入项目后第一时间知道“我在哪里、我要守什么规矩、推荐用什么命令”。我在实际使用中把claude-code-templates拆成了三个层次项目级的 CLAUDE.md存放在仓库根目录Claude Code 每次启动会话时都会自动读取。它相当于项目的“宪法”规定上下文和基础行为准则。自定义 slash commands存放在.claude/commands/目录下。它们的价值是缩短高频操作的指令长度。比如直接输入/review就能触发一套代码审查流程而不是反复打一大段“帮我把当前分支未提交的改动进行严格代码审查注意可读性、潜在bug、类型安全……”。Hooks 自动化脚本存放在.claude/hooks/目录下监听工具调用事件。比如某些危险操作批量删除文件、大规模重构时自动增加确认环节或者在每次会话结束时自动清理临时内容。这三层就像部队里的三级建制日常纪律靠手册、战术动作靠命令、警戒哨兵靠 hook。三者配合Claude Code 才能从“实习生水平”提升到“熟手水平”。你可能觉得 “CLAUDE.md 我早就在用了”但要真把模板管理系统化而不是零散堆内容是另一回事。注意CLAUDE.md 本身不需要任何额外配置把文件放在项目根目录即可。而.claude/commands/也不是必须手动创建——Claude Code 首次运行时就会自动生成这个目录骨架你只需要往里面塞文件。2. 模板项目的核心结构目录、文件与命名规范我见过很多开发者搭建模板库的方式就是写一个又长又全的 CLAUDE.md把所有东西塞进同一个文件然后草草收工。这样做的问题在于Claude Code 每次启动都会完整读取 CLAUDE.md文件越长prompt 消耗越大响应也会变慢。而且全塞一个文件维护性和复用性都很差。我的claude-code-templates采用的是一个独立仓库 按项目分发的模式。模板库本身不直接参与任何项目的代码管理它更像一个“母版仓库”里面存放所有可复用的骨架文件。使用时将对应文件复制到目标项目的.claude/目录或根目录下面。下面是我当前模板库的典型目录结构claude-code-templates/ ├── README.md ├── CLAUDE.md # 通用项目级手册模板 ├── commands/ │ ├── review.md # 代码审查命令模板 │ ├── feature.md # 新功能开发流程模板 │ ├── bugfix.md # Bug 修复流程模板 │ └── refactor.md # 重构操作模板 ├── hooks/ │ ├── post-tool-use.sh # 工具调用后处理脚本 │ └── pre-tool-use.sh # 工具调用前确认脚本 └── docs/ ├── naming-guide.md # 模板与命令命名规范 └── usage-guide.md # 分发与使用说明为什么这样拆原因很简单**模板的本质是“组合的起点”不是“最终的答案”。**每个项目都有自己的特殊性拿到一个模板后大概率要修改。拆得越细替换和组合越方便。比如你有三个项目A 项目只需要通用手册 review 命令B 项目需要通用手册 bugfix 命令 hook 预处理C 项目只需要 review 命令。如果你全部写进一个 CLAUDE.md那就被迫整包复制根本无法按需取用。文件命名上要遵循几个原则都是踩坑踩出来的命令文件名必须匹配触发斜杠命令。review.md对应/reviewfeature.md对应/feature。写错文件名Claude Code 会直接忽略而且不报错很坑。CLAUDE.md 模板和 commands 里的 md 文件不需要 YAML frontmatter 之外的复杂元数据。每份模板只保留三块内容触发条件、执行步骤、交付标准。其他一律精简。hooks 脚本单独放一个目录不要用相对路径依赖 commands 里的内容。脚本不归 Claude Code 解析它是被系统直接执行的路径写错就静默失败。再强调一遍命名规范commands 目录下文件名是全小写用连字符连接多个单词比如security-check.md因为斜杠命令支持连字符CLAUDE.md 必须是这个确切的名字大小写敏感hooks 目录下脚本文件用.sh或.js都可以但模板默认用 shell原因后面会说。这个核心结构既是模板库的骨架也是你日后扩展所有模板的地基。3. 从零搭建可复用的模板库三大核心文件实操3.1 CLAUDE.md项目级手册的写法与边界很多人以为 CLAUDE.md 就是写“我是谁我要干什么”其实那只是最最基础的一层。CLAUDE.md 真正发挥价值是在它具备以下四个功能段之后项目背景段一句话说清这个仓库是做什么的、面向谁的、核心领域是什么。技术栈段列出主要框架、语言、包管理器、可用脚本命令。规范段代码风格、命名习惯、测试方式、commit 规范。注意这里要写“怎么做”不要写“必须负责/帮助用户”这种没用的废话。禁区段明确写出哪些操作不能做或需要额外确认才能做。下面是一份我高度精简的通用模板可以直接参考# 项目名称 ## 项目背景 - 一句话描述项目定位 - 目标用户与核心价值 ## 技术栈 - Language: TypeScript (strict mode) - Runtime: Node.js 20 - Package Manager: pnpm - Test: Vitest - Lint: ESLint Prettier ## 常用命令 - 安装依赖: pnpm install - 测试: pnpm test - 单测模式: pnpm test -- --watch - 类型检查: pnpm typecheck - 本地启动: pnpm dev ## 代码风格规范 - 所有新代码必须通过 pnpm typecheck 和 pnpm lint。 - 组件文件使用 PascalCase普通工具函数使用 camelCase。 - 禁止使用 any 类型如果确实无法避免加显式注释说明原因。 - 公共 API 必须写 JSDoc 或 TSDoc。 ## 禁区 - 禁止直接在 main 分支上提交代码。 - 禁止批量重命名文件操作除非先列出影响范围并得到用户确认。 - 禁止删除不存在于任何 commit 记录中的未跟踪文件。这里特别要提“禁区段”这条是很多教程不会写但实际效果最明显的部分。Claude Code 强大是因为它有行动力但行动力太强偶尔会变成灾难。记得有一次它做重构把 src 下一个还没提交的目录当临时缓存删了我当时还没进入 git 追踪压根找不回来。从那以后所有模板的禁区段里必有一句“禁止删除未跟踪文件”。在 CLAUDE.md 里我还习惯加一段“工作模式”说明。比如## 工作模式 - 默认适合先做探索和方案设计不要直接改代码除非用户明确要求“直接修改”。 - 在给出修改方案时优先考虑最小改动、向后兼容的方案。 - 如果发现需求和现有架构有冲突先提醒用户而不是自己决定架构演进方向。这段“工作模式”的价值是让 Claude Code 在“行动派”和“谨慎派”之间找到平衡。没有它默认状态下它倾向于“你说改我马上改”有了它改之前它会先给你看方案有效减少来回返工。注意CLAUDE.md 不是越细越好。越长的文件意味着每次会话都消耗越多的 context。通用规范保持在一百五十行以内特殊情况可以单独写在某个命令的正文里而不是塞进 CLAUDE.md 全局生效。3.2 slash commands把高频操作做成“一键执行”Slash command 的机制是用户在 Claude Code 对话框中输入/xxxClaude Code 就会去.claude/commands/xxx.md读取里面的 prompt把文件内容当作用户消息的补充发送给模型。因此command md 文件的写法就是“把一段高质量的 prompt 固化下来成为可重复调用的模板”。一个典型的review.md长这样--- description: 对当前分支未提交的改动执行严格代码审查 --- 对当前分支相对于 main 分支的未提交改动进行代码审查。 参考项目 CLAUDE.md 中定义的代码风格规范展开检查。重点关注以下方面 1. 正确性是否存在逻辑错误、边界条件遗漏、并发问题。 2. 可读性命名是否准确自解释函数是否过长、职责是否单一。 3. 安全性是否引入新的依赖依赖版本是否可用是否处理用户输入校验。 4. 性能是否存在明显可避免的重复计算或不必要的网络/IO 操作。 5. 一致性是否符合现有代码的模式而非另起炉灶。 对每一条问题按 [严重 / 中等 / 轻微] 分级给出具体文件和行号。输出格式为 Markdown 清单。 如果未发现问题明确写出“未发现明显问题”不要用模糊的话应付。这里有两个容易被忽略的细节frontmatter 里必须写description。当你输入/时Claude Code 会列出所有可用命令并展示这个描述帮助你判断该用哪条。没有描述的 command 在列表中就是空白一行很影响体验。正文不要用“请帮我”这种客套话。Slash command 的设计目标是精确、高效直接把任务和要求写清楚让 Claude Code 照着执行。客套话只会稀释指令的清晰度让模型分不清主次。除了review.md我还会针对常见任务写feature.md。它的模板逻辑有点不一样因为新功能的开发过程比审查更复杂。所以我拆成“先了解 - 再计划 - 再实现 - 最后自测”四个阶段并用清晰的编号告诉模型按顺序走。相比 review 那种一次性动作feature 更像一个工作流。同样地bugfix 类命令强调“先复现再修复”refactor 类命令强调“先摸清依赖再动手”。每种命令的 prompt 都围绕它特有的核心风险展开避免模板之间只是换了标题而内容雷同。用斜杠命令最大的收益其实不是“少打字”而是稳定输出结构。人工组 prompt 时每次措辞都会有细微差异Claude Code 的输出质量也因此有波动。模板把质量下限拉到一定高度即便你状态再差敲个/review也能得到一份结构清晰的审查结果。3.3 hooks在关键时刻兜底和自动化Hooks 是 Claude Code 提供的自动化扩展机制可以在特定工具调用前或后触发脚本。这是模板库中最有“高级感”的部分也是胆子最大、最容易翻车的地方。我建议所有模板库第一版不要立刻上 hooks先把 CLAUDE.md 和 commands 跑顺手再逐步引入。我当前模板里的 hooks 分两类PreToolUse工具调用前——用来做“危险操作确认”。举个例子当 Claude Code 准备调用 Bash 工具执行rm命令时我们希望脚本检查命令内容如果包含rm -rf就弹出一个确认提示或者干脆中断工具运行。#!/usr/bin/env bash # file: .claude/hooks/pre-tool-use.sh tool_name$1 input_json$2 echo $input_json | grep -q rm -rf { echo 检测到危险命令 rm -rf已阻止执行请先确认文件列表。 2 exit 2 } exit 0这里的核心是 Claude Code 的 hook 机制通过标准输入把 JSON 格式的工具调用参数传给脚本脚本通过环境变量拿到事件类型PostToolUse 或 PreToolUse再根据实际内容做判断。PostToolUse工具调用后——用来清理副作用或记录日志。比如每次 Claude Code 运行完Write工具后自动检查文件是否遵守了行宽规范或者在大量文件改动后自动跑一遍已有的 lint 命令补充异常报告。#!/usr/bin/env bash # file: .claude/hooks/post-tool-use.sh tool_name$1 input_json$2 if [ $tool_name Write ]; then echo 检测到文件写入建议运行以下检查: pnpm lint --fix 2 fi exit 0hook 脚本的退出码也大有讲究。0 表示放行非 0 表示阻断对应不同的错误级别2 通常用于用户取消3 用于突发错误。设置成“发现危险操作直接退出非 0”就能打断 Claude Code 的自动行动把决定权交回给你。但我要郑重提醒**hooks 的调试难度比 CLAUDE.md 高出好几倍。**Shell 脚本里引号、空格、换行处理稍有差错就会导致 Claude Code 的行为完全异常。所以 hooks 脚本内部每个分支都要写清楚日志输出到2因为 Claude Code 会把 stderr 内容回显给会话你才看得到它到底发生了什么。4. 实战从通用到垂直场景的六套模板结构搭好之后模板内容才决定最终体验。我这里直接分享我仓库里目前在用的六套模板每套都标注了使用场景和核心写法。你可以直接复制调整不用全部照搬。4.1 新功能开发模板feature.md这套的核心是“先规划再动手”。因为新功能最常出问题的地方不是写代码而是想不清楚就开干搞到一半发现方向错了。--- description: 按流程开发新功能需求分析 - 方案设计 - 编码 - 自测 --- 功能目标{{用户输入的功能描述}} 按以下步骤执行 1. 先在项目中搜索相关功能是否已有部分实现或组件避免重复建设。 2. 阅读涉及模块的现有代码结构梳理依赖关系。 3. 输出简要设计思路改动哪些文件、新增哪些文件、是否需要修改数据结构。 4. 等待用户确认设计后再进行代码实现。 5. 实现完成后运行项目对应的类型检查和测试命令确认无报错并把结果反馈给用户。这里的要点是第 4 步“等待用户确认”。没有这个步骤Claude Code 很容易在你刚给出设计草案后就埋头实现一次改个十几二十个文件给你造成巨大的 review 压力。加上确认环节每次开发都保持“小步快跑”的节奏。4.2 代码审查模板review.md前面已经展示过内容这版的特色在于分级问题输出。我后来做了一处优化要求 Claude Code 把审查结果按“必须修改”和“建议优化”分开列。这样你在处理时可以先改硬伤再看可选建议效率大幅提升。4.3 Bug 修复模板bugfix.md--- description: 定位并修复 Bug先复现再排查 --- Bug 描述{{用户输入的 bug 现象或报错信息}} 执行步骤 1. 搜索与 bug 现象相关的代码路径提取可能导致问题的候选模块。 2. 尝试构造复现条件。如果不能直接复现给出你的推测原因等级排序。 3. 输出“根因分析”报告说明为什么这段代码会导致该问题。 4. 等待用户确认根因后再进行修复。 5. 修复后运行相关测试并额外编写一条回归测试用例防止问题复发。bugfix 模板的重点在第 2 步和第 5 步。很多开发者让 Claude Code 直接修 bug它确实能修但没法证明没修坏其他东西。要求它写回归测试相当于逼着它对修复结果做验证而不是改完就跑。4.4 重构建议模板refactor.md重构类任务最怕的是“为了重构而重构”。我的模板强调先量化收益--- description: 评估并实施代码重构优先保证行为不变 --- 重构目标{{用户输入的模块或代码片段}} 执行步骤 1. 找到目标代码的全部调用点明确影响面。 2. 列出当前代码结构的主要问题重复代码、过深的嵌套、不可测逻辑等。 3. 给出重构前后对比方案标注重构后的可维护性收益。 4. 等待用户确认后再动手。重构过程必须保持外部行为不变不得顺手调整业务逻辑。 5. 重构完成后运行完整测试套件提供前后 diff 摘要。4.5 提交信息规范模板commit.md不要小看这个命令。它的思路是让 Claude Code 分析当前 git diff按 conventional commits 标准生成提交信息并用中文或英文输出一份可复制的信息。--- description: 基于当前 git diff 生成符合 conventional commits 的提交信息 --- 分析 git diff --staged 或 git diff 的内容总结变更类型和影响范围。 输出格式要求 - 标题type(scope): 简短描述 - type 使用 feat / fix / refactor / docs / test / chore / perf - scope 使用模块或目录名 - 如果涉及破坏性变更在正文中起始处标注 BREAKING CHANGE 只需输出提交信息不需要任何额外解释。很多开发者的提交信息写得很随意如果 AI 能帮我们生成规范且表达准确的提交信息其实节省的时间非常可观。这里我特别要求它“只需要输出提交信息”是为了防止 Claude Code 自作主张多写几百字分析文字。4.6 新项目初始化模板init.md这是我最常用、也最能体现模板价值的命令之一。它让 Claude Code 帮我初始化一个新项目的骨架。--- description: 初始化新项目结构自动创建基础配置和目录 --- 初始化一个 {{项目类型}} 项目。 要求 - 使用当前最新的推荐模板。 - 创建目录结构src / tests / docs / scripts。 - 生成基础配置包管理器配置、lint 配置、测试框架配置。 - 生成一个最小可运行的示例文件。 - 初始化 git 仓库并创建初始 commit。 初始化完成后展示项目结构和下一步推荐动作的清单。你会发现 init 模板最核心的变量只有“项目类型”一个。剩下的全部通过对目录和配置的定义来约束。这让它具备很强的通用性同一个模板可以用于前端、Node 后端、甚至一个工具库项目。5. 模板落地过程中的五个高频坑与对应解法模板库写好了你以为就万事大吉不是。我在实际使用中反复栽进过下面这些坑每一个都值得单独拿出来说。5.1 模板写得太“角色扮演”反而削弱了 AI 的执行力很多网上流传的 prompt 模板喜欢给 Claude Code 安一个身份“你是世界顶级的工程师拥有二十年从业经验……”我在早期模板里也这么写过后来发现效果反而变差了。原因是身份设定会诱导模型专注于模仿“身份风格”而非“执行任务细节”。同样一套 task今天要求输出代码、明天要求输出审查报告用一个僵硬的角色套所有任务只会让输出变得“有架势、没干货”。我的解法CLAUDE.md 里完全去掉角色设定只保留事实性规则和业务约束。命令模板同理——聚焦“步骤”和“交付物”比身份更重要。5.2 CLAUDE.md 太长消耗大量 context拖慢每轮响应这是最隐蔽的性能杀手。你往 CLAUDE.md 里塞了大量“关于项目的历史背景”“团队成员介绍”“会议记录摘要”结果每轮对话 Claude Code 都要携带这些信息模型响应会越来越慢越到对话后期越容易跑题。模板必须严格控制长度。把 CLAUDE.md 当成“入参”而不是“说明书”。那些一次性的背景描述应当在会话中直接以用户消息方式提供而不是固化到全局模板里。我甚至建议定期用 Token 估算工具检测 CLAUDE.md 的长度如果你发现它超过 4000 token就该考虑拆分或精简了。5.3 命令文件里的占位符和变量被 Claude Code 误解Slash command 模板中经常出现{{用户输入的功能描述}}这类占位符。问题在于当你直接输入/feature 我想实现一个导出 CSV 的功能Claude Code 会替换掉这个占位符这部分做得好但如果你输入的是含花括号的文本可能和模型解析产生冲突导致命令无法正常触发。解决方式用方括号[项目名]或[模块名]代替花括号减少解析冲突。在命令正文第一行固定写明“本文档中的描述为模板占位必须根据实际情况替换”避免 Claude Code 把占位符当成真实代码或文件名处理。5.4 hooks 脚本静默失败没有任何报错提示Shell 脚本的坑太多环境变量在不同 shell 下加载不同、路径写错、权限没加执行位chmod x——这些都可能导致 hook 没生效。更坑的是Claude Code 在某些版本下对 hook 脚本的失败是静默的并不会在会话中提示你。我的对策是在每一条 hook 脚本开头强制 echo 一行调试日志到 stderr并且第一版只在测试项目上跑不做正式发布的自动化。另外要注意hooks 的执行环境和会话终端可能不同尤其是 mac 上使用 zsh 与 bash 的差异。如果你写的是 bash 脚本务必在文件头加上#!/usr/bin/env bash并保证脚本不依赖 SHELL 环境变量里没有的别名或函数。5.5 模板堆栈化 —— 多套命令互相调用导致依赖混乱我曾经尝试让/feature命令自动调用/review命令做法是在 feature.md 末尾写“完成后执行 review 工具”。听起来效率很高实际却很混乱因为 Claude Code 并不会像编程一样严格按顺序执行它可能在 feature 未完成时就调用 review或者 review 之后又跳回去改了代码整个会话的行为变得不可预测。后来我把所有命令设计成“幂等独立”的每套命令可以单独执行也可以作为另一个命令的建议后续但绝不强制依赖。这样既保留了灵活性又避免了任务间的状态纠缠。6. 模板不是一次写好的持续迭代与版本管理我第一次搭好模板库时的状态自认为相当完善。真正用了一个月后再回头看至少有三分之一的内容被推倒重写过。这里分享一下迭代的思路和工具。迭代周期我保持每两周做一次模板全面复盘。复盘的方式是翻看 Claude Code 的会话历史重点标记两类内容在使用了模板后我仍然需要反复手动补充说明的信息。这类信息应该被写进 CLAUDE.md 或者对应命令。模板里写了但 Claude Code 在实际执行中经常“无视”的规则。这说明写法有问题需要重写表达方式或者拆分成更强烈的指令。举个例子我在 CLAUDE.md 里写过“所有新增的公共函数必须有单元测试”但 Claude Code 实践中经常只跑 codegen 不写测试。后来我把这句话从 CLAUDE.md 挪到了/feature命令的第 5 步效果立刻改善因为命令是“本次任务执行时的强指令”而 CLAUDE.md 更像是“背景信息”。同一个约束放在不同层级的载体里影响力完全不同。版本管理模板本质也是代码所以别再用“复制到桌面再改”这种野路子。我的claude-code-templates直接放在 Git 仓库中每次调整都走正常的 commit、merge、review 流程。团队协作时每个人拉下来自己的分支做实验确认可用后合并回主分支。发布时用 Git tag 标版本号例如v1.2.0。分发到项目仓库时我用两种方式复制粘贴最简单适合项目少、模板不常更新的场景。Git submodule 或 Node 脚本拉取适合团队多人复用、模板持续演进时的场景可以在极短时间内同步所有项目到最新模板版本。如果已经有一套 dotfiles 管理方案直接加一个目录映射即可不必搞复杂。和团队共享时我会额外维护一份“模板维护指南”写在仓库的 docs 目录下。里面规定谁可以新增命令、命名是否规范、是否经过验证、进主分支前必须写清楚使用场景。这听起来有点官僚但模板库一旦多人维护没有约束就会迅速腐烂成个人风格的堆砌失去通用性。最后留一个我很喜欢的小技巧在模板库的 CLAUDE.md 模板里可以加入一条“自省指令”——让 Claude Code 在执行任务末尾附带一个“本次执行建议”哪些模板指令可以优化、哪些步骤多余、哪些信息模板里缺失。把这些建议收集起来就是最好的迭代素材胜过你自己盯着模板冥思苦想。我自己实践下来的最大感受是模板库的收益不是单次的、线性的而是复利型的。前期搭好东西每个月的维护成本很小但每次会话都在替你省下重复交代上下文的五分钟、十分钟。用得越久它对项目习惯的适配度越高你甚至会产生一种“它好像知道我接下来要说什么”的错觉。这是套件最令人上瘾的地方。
