从提示词到技能脚本：构建 Claude Code 模板体系实战指南

先聊两句题外话。Claude Code 发布到现在热度一直没下去我身边不少团队已经从“试一试”变成了日常开发的主力工具。但用得久了你会发现一个尴尬的局面很多人对它的使用还停留在“打开终端问一句”的阶段每次干点正经事都要把需求从头到尾描述一遍回答质量全凭临场发挥换个项目换个目录之前调教好的习惯和指令全部作废。这种感觉就像你雇了一个聪明但失忆的助手每天上班都要重新自我介绍一遍。claude-code-templates 这个项目解决的正是这个问题。它本质上是把 Claude Code 的提示词、配置文件、工作流沉淀成一套可复用、可分享、可版本管理的模板体系。说白了就是给 Claude Code 装上一套“记忆和习惯系统”让它从“能用”变成“好用”。这篇文章我会从模板体系的整体思路、核心类型、落地实操到问题排查完整拆解一套我自己在用的模板方案里面所有目录结构和配置示例都来自实际项目可以直接拿来改。1. 模板体系的设计思路为什么散装指令永远打不过结构化模板1.1 Claude Code 的“失忆症”问题Claude Code 本身是一个终端里的 AI 编程代理它能读写文件、执行命令、调用工具能力上限很高。但它有一个天生的短板每次会话都是独立的上下文窗口它不记得你昨天定的代码规范不记得你惯用的提交信息格式甚至不记得当前项目的技术栈细节。举个例子你在 A 项目里反复强调“所有数据库查询必须走 Repository 层”它记住了表现得很好。但当你切换到 B 项目它又变回一张白纸你得重新讲一遍。项目一多这种重复劳动就非常消耗耐心而且每次口头交代的效果都有折扣有时候它理解了有时候它理解偏了。模板要解决的就是这个“失忆”问题。与其每次靠临场对话碰运气不如把那些高频使用的指令、规范、流程固化成模板文件让 Claude Code 在启动时自动加载或者通过一条简短命令随时唤起。这就像给一个聪明但健忘的同事写了一份详尽的工作手册他只需要翻手册就能找到标准答案不需要每次都来问你。1.2 模板化的三个核心价值我把 Claude Code 模板化的价值归纳成三点消除重复、保持一致性、降低使用门槛。第一是消除重复。凡是你在会话里说过三次以上的话都值得沉淀成模板。比如代码审查的检查清单、提交信息的格式规范、报错信息的分析流程这些内容写成模板之后你每次使用时只需要一句话就能完整唤起省去了大量重复描述。第二是保持一致性。团队协作时不同人用 Claude Code 的方式可能天差地别。有人让它写单元测试有人让它直接改代码有人只会用它解释报错。一套统一的模板体系可以让团队所有成员的工作流对齐输出质量更稳定代码审查的时候也不会因为“你让 AI 干的活和我让 AI 干的活完全不是一回事”而产生认知摩擦。第三是降低使用门槛。对于刚接触 Claude Code 的新人来说最大的障碍不是不会敲命令而是不知道该怎么高效地指挥它。模板就是最好的“新手引导”把成熟的用法直接摆在那里新人只需要套用模板就能获得接近老手的使用效果。1.3 模板体系的分层设计我在实际项目中把模板体系分成三层分别对应不同的作用范围和维护频率。系统级模板放在用户主目录的~/.claude/目录下对当前用户的所有项目全局生效。这一层适合放通用的行为规范比如“默认使用 TypeScript 严格模式”“代码注释必须使用中文”“不要随意删除未使用的导入”这类跨项目通用的规则。项目级模板放在项目的.claude/目录下随项目走进版本库所有协作开发者共享。这一层适合放项目特有的约定比如技术栈说明、目录结构说明、测试命令、启动命令、数据库访问规范、代码分层约定等。这一层是最重要的一层因为它直接决定了 Claude Code 在这个具体项目里的表现。团队级模板其实是一个可选的共享层通常以独立仓库的形式维护通过脚本或者文档分发给团队成员可以理解为“模板的模板”或者“模板的源仓库”。这一层解决的是多人协作时“每个人电脑上的模板不一致”的问题把模板本身纳入版本管理跟着团队规范一起演进。这三层各有侧重系统层管“这个人习惯怎么干活”项目层管“这个项目怎么干活”团队层管“我们这些人怎么一起干活”。三层叠加Claude Code 才能真正融入你每天的工作流而不是一个偶尔打开的工具。2. 核心模板类型拆解提示词、记忆文件与技能脚本2.1 提示词模板把高频场景固化成标准动作提示词模板是 claude-code-templates 体系里最直观、最好理解的一部分。它的本质是把一段完整的、经过验证的指令保存下来需要的时候通过简短的唤起语句触发。我常用的几个提示词模板包括代码审查、提交信息生成、报错分析和架构设计。代码审查模板是我使用频率最高的一个。我把它起名为 “深度代码审查”唤起之后 Claude Code 会依次检查代码的 correctness正确性、性能隐患、边界条件、安全隐患、可读性和测试覆盖最后以固定格式输出审查报告。这个模板的价值在于它把审查维度固化了不会像临时提问那样东一榔头西一棒子。提交信息模板则解决了 commit 信息风格不一致的问题。我把自己项目的 commit 规范写进模板约定使用 Conventional Commits 格式类型限定为 feat、fix、refactor、docs、test、chore并且给 Claude Code 一个明确指令根据 git diff 分析变更内容生成符合规范的提交信息如果一次性提交涉及多个类型以主体变更类型为准。报错分析模板比较特殊它的核心不是让 AI 直接给答案而是要求它按一套标准流程来定位问题先复述报错信息再检查相关代码上下文然后锁定可能的原因最后给出修复建议和验证方法。我特意加了“不要急着改代码先给出结论”的约束避免它一上来就抛出几段修改导致我完全没有理解问题就被带着跑了。架构设计模板用来做模块方案设计。当我需要新增一个功能模块时只需要用一句话说明需求背景模板会自动引导 Claude Code 从需求分析、接口设计、数据模型、目录结构、风险点五个维度输出方案。这比直接问“这个功能怎么做”靠谱得多因为模板里固化了方案输出的格式和深度要求。2.2 CLAUDE.md 记忆文件让模板自动加载如果说提示词模板是“按需触发”CLAUDE.md 就是“自动生效”。这是 Claude Code 的一种记忆文件机制工具在启动时会自动读取CLAUDE.md文件的内容将其作为当前会话的全局背景知识。你可以把它理解成一份随身携带的工作手册每次对话开始前 AI 都会先翻一遍。我见过很多团队对 CLAUDE.md 的用法过于保守只写几句话就完了“这是 XX 项目使用 Vue 3 TypeScript。”坦白说这种写法的效果约等于没有。CLAUDE.md 的价值不在于告诉 AI 项目叫什么而在于把项目里那些“你闭着眼都懂但 AI 永远猜不到的规则”写清楚。我的项目级 CLAUDE.md 一般包含五个部分项目简介与技术栈、开发命令启动、测试、构建、代码检查、目录结构说明、关键规范命名、分层、数据库操作等、常用路径映射。路径映射特别有用因为很多项目的代码分布并不直观直接告诉 AI“工具函数放在src/shared/utils/下领域逻辑放在src/domain/下API 路由定义在src/entry/http/router.ts”它后续处理文件时就会准确得多。CLAUDE.md 的写法还有一个关键技巧要写“规则”而不是写“描述”。比如下面这两句话描述和规则的区别就很明显描述式项目使用 pnpm 作为包管理器。规则式所有依赖安装必须使用 pnpm禁止使用 npm install 或 yarn add。描述只是背景信息AI 可能参考也可能不参考规则是必须遵守的约束AI 在执行相关操作时会主动对约束保持敏感。我自己的实践是 CLAUDE.md 里至少 70% 的内容写成规则句式并且用“必须”“禁止”“优先”这类明确程度高的词。2.3 技能与脚本模板把多轮对话压缩成一条命令技能Skills是 Claude Code 的进阶玩法。它允许你定义一组高度特化的脚本或工作流通过斜杠命令触发比如/review、/commit、/fix。触发后不仅可以注入一段提示词还可以执行本地脚本或者组合多步操作把原本需要好几轮对话才能完成的事情压缩成一次调用。我最初对技能的理解比较浅觉得它就是把提示词换个入口而已。后来深入使用才发现技能真正的威力在于它可以和本地命令结合。比如我的/frontend-lint技能触发后会先读取项目里的 ESLint 配置运行一次 eslint 检查把错误列表传给 Claude Code再让它按照项目规范给出修复建议。这个过程完全自动化信息的获取和问题的分析被串联在一起比单纯贴代码给 AI 看高效太多。还有一个我特别推荐的技能场景项目脚手架生成。我建了一个/new-module技能触发时只需要告诉它模块名称和功能描述它会自动读取项目的目录结构和代码规范生成完整的模块文件组件、接口、路由注册、单元测试文件、样式文件一步到位。这个技能的核心不是“让 AI 写代码”而是把“代码写的对不对、文件放哪、命名规则是什么”这些经验固化进模板让 AI 生成的代码天然符合项目习惯。技能脚本的开发和维护门槛比提示词模板高一些收益也更大。它适合那些你每周都会重复做、且需要结合项目上下文才能完成的任务。初创项目阶段可能用不上但项目规模上来以后技能脚本能帮你省下非常多的时间。3. 从零搭建你的模板仓库目录结构、CLAUDE.md 与技能脚本实战3.1 模板仓库的目录设计我自己维护的模板仓库结构分三大块rules/放全局规则片段skills/放技能脚本和对应的提示词snippets/放短小的提示词片段。这个结构是我试过几种方案之后敲定的对中小团队和个人开发者来说足够清晰扩展性也不错。claude-code-templates/ ├── README.md ├── rules/ │ ├── git-workflow.md │ ├── code-style.md │ └── security-checklist.md ├── skills/ │ ├── review/ │ │ ├── SKILL.md │ │ └── scripts/ │ ├── commit/ │ │ ├── SKILL.md │ │ └── scripts/ │ └── new-module/ │ ├── SKILL.md │ └── templates/ └── snippets/ ├── error-analysis.md ├── api-design.md └── test-generation.md规则片段是 CLAUDE.md 的“素材库”。当你要为一个新项目创建 CLAUDE.md 时不需要从零开始写而是从规则片段里挑选适用的部分拼装。代码风格规则几乎每个项目都能用安全清单则视项目类型而定。这个设计避免了每个项目的 CLAUDE.md 都重复造轮子的问题。技能目录下每个子目录对应一个独立技能。SKILL.md 文件里面写技能的元信息和提示词正文scripts/ 目录放需要执行的脚本文件templates/ 目录放生成项目文件时使用的模板。这样的结构让技能包的迁移变得简单把一个子目录复制到目标项目的.claude/skills/下技能即可生效。片段目录则是留给那些“有价值但还不够单独做技能”的提示词比如接口设计规范、单元测试生成要求等等。这类内容的特点是使用频率中等、长度较短、适配度高适合快速拷贝到对话中使用不需要做成正式技能那么重的形态。3.2 项目级 CLAUDE.md 的写法实践下面这份 CLAUDE.md 是从一个实际项目里精简出来的它是前后端同仓库的 Web 应用核心是三个目标让 AI 快速理解项目结构、遵守代码规范、正确执行开发命令。# 项目记忆文件 ## 项目简介 这是一个全栈 Web 应用前端使用 React 18 TypeScript Vite后端使用 Node.js Express TypeScript。 数据库使用 PostgreSQLORM 使用 Prisma。 ## 开发命令 - 安装依赖pnpm install必须使用 pnpm禁止 npm/yarn - 启动前端pnpm dev:client - 启动后端pnpm dev:server - 运行全部测试pnpm test - 运行代码检查pnpm lint - 生成 Prisma 客户端pnpm prisma:generate ## 目录结构 - src/client/ - 前端代码 - components/ - 通用组件 - pages/ - 页面组件 - hooks/ - 自定义 hooks - src/server/ - 后端代码 - routes/ - API 路由 - controllers/ - 请求处理层 - services/ - 业务逻辑层 - repositories/ - 数据访问层 - middlewares/ - 中间件 - prisma/ - 数据库模型与迁移文件 ## 关键规范 - 后端分层必须严格遵循 routes → controllers → services → repositories 的调用链 - controllers 中禁止出现业务逻辑所有业务逻辑必须放在 services 层 - 数据库查询必须通过 repositories 层禁止在 services 中直接操作 Prisma Client - API 路由命名使用复数形式如 /api/users/api/orders - 前端组件文件使用 PascalCase 命名工具函数使用 camelCase 命名 - 所有时间相关数据统一使用 UTC 时间戳存储 ## 常用路径映射 - 用户相关的路由定义src/server/routes/user.route.ts - 订单业务逻辑src/server/services/order.service.ts - 数据库模型prisma/schema.prisma - 全局类型定义src/client/types/global.d.ts这份 CLAUDE.md 使用后Claude Code 在项目里的表现会有质的提升它不会再问“这个项目的测试命令是什么”“这个项目目录结构怎么规划”而是直接按照文件里的约定去执行。如果你是从零写一份 CLAUDE.md有一点需要记住不要贪多。我见过有人把整个团队开发规范文档全量塞进去结果 AI 上下文被大量无效信息占满重要指令反而被淹没了。CLAUDE.md 应该是项目最关键信息的浓缩那些“偶尔才会用到”的内容不适合放进来。3.3 一个技能脚本的完整实现以 /review 为例技能脚本的 SKILL.md 写法有固定的格式下面我用自己每天都在用的/review技能做例子。这个技能的作用是对指定范围内的代码进行全面的代码审查输出结构化审查报告。--- name: review description: 对当前分支或指定文件的代码变更进行深度审查 --- 执行代码审查任务时请遵循以下流程 1. 使用 git diff 获取当前分支相对 main 分支的变更内容 - 如果用户指定了文件路径则只审查指定文件的变更 2. 从以下维度逐项审查代码 - 正确性逻辑是否合理边界条件是否考虑完整 - 安全性是否存在注入、越权、敏感信息泄露等风险 - 性能是否有不必要的重复计算、循环内请求、大数据量全量加载 - 可维护性命名是否清晰、函数是否过长、职责是否单一 - 规范一致性是否符合项目 CLAUDE.md 中的代码规范 3. 以 markdown 表格形式输出审查结果包含 - 问题级别高/中/低 - 文件路径与行号 - 问题描述 - 修改建议 4. 如果发现高危问题额外追加一段“优先修复项”列表按影响程度排序这个 SKILL.md 本身没有执行任何本地命令它靠的是 Claude Code 内置的 Bash 工具去跑git diff。注意一个细节我明确了对比基准是main分支这个约束很重要否则 AI 可能用任意的 diff 基准或者干脆无法确定变更范围。类似这样的指令细节都是在多次使用过程中逐渐打磨出来的。如果你想把技能做得更智能可以加一个预检查脚本。比如我有个/full-check技能会在 AI 开始审查前先执行pnpm lint和pnpm test把结果嵌入提示词让 AI 优先关注已知的错误项。脚本用最简单的 Node.js 或者 Bash 写就行关键是输出能被 AI 直接理解。#!/bin/bash # scripts/run-checks.sh cd $(git rev-parse --show-toplevel) echo running eslint pnpm lint 21 | tail -50 echo running tests pnpm test 21 | tail -80SKILL.md 里的最终提示词会包含一条指令先执行脚本拿到输出后再开始审查。这样 AI 就在执行审查前掌握了真实存在的 lint 错误和测试失败情况审查报告里可以直接标注“这些问题已被 test 验证为失败”而不是“建议运行测试确认”。它们的可信度完全不同。3.4 联动 MCP 配置让模板获取更多上下文MCPModel Context Protocol配置可以理解为给 Claude Code 接上外部数据源。我在模板体系里用 MCP 打通了几个常用工具GitHub、数据库 schema、内部文档系统。效果最明显的是 GitHub MCP它让 AI 可以直接读取 issue 内容、PR 评论、提交历史在代码审查和 bug 修复场景下非常有价值。之前有一次处理线上 bug我在会话里让 AI 看一下某个接口最近的变更记录它直接通过 GitHub MCP 拉取了相关的 PR 历史精准定位到是前一次重构把参数校验的逻辑弄丢了。如果没有 MCP这个过程需要我手动去 GitHub 页面翻记录再贴给 AI效率不是一个量级的。MCP 的配置文件同样可以纳入模板仓库管理。不同项目的 MCP 配置差异很大有 GitHub 的项目配 GitHub MCP没有的就不配有内部文档系统的配文档 MCP没有的就不配。通过模板仓库把可用的 MCP 配置项和说明文档统一维护团队成员只需要按需启用降低了不少配置成本。4. 实战中的坑与排查技巧模板失效、上下文膨胀与版本管理4.1 我踩过的五个典型问题第一模板不生效。概率最高也最让人困惑。排查顺序是从优先级角度由高到低如果技能脚本没有出现在斜杠命令列表里可能是技能目录放错位置了技能只能放在.claude/skills/下放在别处不会被识别。如果 CLAUDE.md 里的规则没被遵守大概率内容写得偏“描述”而不是偏“规则”或者被后面更具体的指令覆盖了。第二上下文窗口被撑爆。CLAUDE.md 内容如果过多加上技能里动态注入的信息AI 的注意力会被稀释。解决方法是精简单个文件的长度把过长的内容改为按需加载。比如把“发布流程”写成一个独立文件docs/release.md在需要时用 “请阅读 docs/release.md 后执行发布” 的方式唤起而不是放进 CLAUDE.md 常驻上下文。第三提示词模板里的指令过时。模板固化了某个动作的流程但项目规范变了模板里还是旧要求AI 遵循了过时的规则产出的代码与当前代码库风格不一致。解决方法是在模板仓库里做一个规范版本号每次团队规范变更时同步更新模板并且在 README 里记录更新日志。第四多人协作时模板不一致。A 同事的电脑上有一套技能B 同事的电脑上没有两个人跑出来的效果完全不同。解决方法是把模板仓库纳入工程化流程在package.json里加一个setup:claude脚本把团队模板自动同步到每个开发者的项目 .claude 目录中。第五AI 过度遵循模板导致灵活性下降。模板写得太死AI 遇到规则覆盖不到的边缘情况时会死板地套用旧模式。这个问题的解法是模板里加一条“如果遇到模板指令与现实需求冲突优先遵循用户明确指令”的说明同时定期给模板做减法。4.2 模板版本管理与团队协作我的模板仓库从第三天就开始用 git 管理了。有一个深刻教训是模板和代码一样会腐烂如果不维护两周后再打开旧项目就会发现 AI 的表现退步了。我把每次模板的结构性修改都记录在变更日志里包括新增了哪些规则片段、修改了哪个技能的提示词、删除了什么过期约束。团队新成员加入时一份清晰的变更日志能大大降低上手成本。对团队协作的场景我有两个建议。第一模板仓库与项目仓库分离模板不直接作为子模块嵌进项目仓库而是通过同步脚本或文档指引引入。分离的好处是模板可以在多个项目之间复用演进也更灵活。第二重要模板修改走 review类似热门的录屏或逆天代码不能直接上模板改动也一样特别是指令风格相关的改动最好由团队里最常用 Claude Code 的人审一遍再合入否则小改动也可能引发大范围的输出行为变化。4.3 新手配置模板最容易忽略的两个细节新手最容易忽略的第一个细节是 CLAUDE.md 的位置。Claude Code 既支持项目根目录的CLAUDE.md也支持~/.claude/CLAUDE.md用户级配置还支持.claude/CLAUDE.md如果你多个文件同时存在它们的内容是合并的。我见过有人把项目级规范写进了用户级文件结果所有项目都受到了影响。一定记住放用户级目录的内容必须确实是跨项目通用的项目专属的内容务必放到项目目录下。第二个细节是技能的唤醒词污染。技能名称和 description 如果写得不够具体斜杠命令可能唤起错误技能。比如你有一个/db技能用于生成数据库迁移脚本又有一个/d技能用于 debug 调试Claude Code 可能因为前缀模糊匹配唤起错误的技能。解决方法是技能名称尽量用完整词汇不要和已有技能形成前缀歧义。4.4 模板维护的节奏与心得模板不是一次建好就一劳永逸的。我个人的维护节奏是每次使用 Claude Code 完成任务后如果发现“刚才这个事要是当时有个模板就好了”就立刻沉淀每周花 15 分钟回顾本周使用记录把重复出现的模式固化成模板每个迭代周期清理一次不再使用的模板避免维护成本堆积。这个节奏还有一个附带的好处模板仓库本身成了一本“AI 协作进化史”。翻看模板变更日志你能很清楚地看到团队的工作方式在如何演变哪些流程在固化哪些流程被淘汰。这种观察还挺有意思的它会让你对“人和 AI 如何高效协作”这件事产生比单纯用工具更深的体会。5. 进阶玩法从模板库到工作流引擎5.1 用模板组合出多阶段工作流单个模板解决的是单点问题把模板组合起来就是一个完整的工作流。我在团队里搭过一个“需求到上线”的模板链路/parse-requirement需求拆解→/design-solution方案设计→/implement编码实现→/review代码审查→/commit生成提交信息。这套链路跑下来一个功能从需求描述到合并代码的整个过程都有了标准化的 AI 参与方式。每个环节都通过技能唤起某个环节的产出自动作为下一个环节的输入。比如方案设计技能的输出会保留设计文档到docs/目录实现技能被唤起时会自动读取该文档这样 AI 在编码时就能严格遵循已经确定的方案不会出现设计一套、实现另一套的脱节。组合工作流的意义在于它让 Claude Code 从一个“问答工具”变成了一个“执行引擎”。你不需要在每一步都动脑思考如何下达指令只需要在链路上做决策和审批AI 负责执行和推进。5.2 模板仓库的多环境适配模板在不同环境下的适配是需要提前考虑的。项目分前端、后端、移动端三种类型模板仓库里对应的代码风格规则、命令定义、目录结构说明完全不一样。我的做法是在 rules/ 目录下按技术栈拆分子目录比如rules/frontend-react.md、rules/backend-node.md、rules/mobile-react-native.md初始化新项目时按需引入避免把所有技术栈的规范都塞进一个 CLAUDE.md 导致上下文负担过重。环境适配还有一个重要场景个人开发环境与 CI 环境的差异。有些技能在本地执行良好但在 CI 环境会因为缺少依赖或权限受限而失败。如果团队打算在 CI 里也跑 Claude Code 做自动化审查最好在模板里为不同环境预设差异说明比如“CI 环境无法执行 pnpm install请跳过依赖相关操作直接基于已有 node_modules 执行代码检查”。5.3 维护一个可分享的模板库如果你打算把自己积累的模板分享给更多人或者组织内部推广使用有几个建议供参考。模板文件的写法尽量多用“规则句式”减少对某个项目具体路径或命令的硬编码涉及敏感信息的配置一律使用占位符每个模板都写一个 brief 注释说明适用场景方便使用者快速判断“这个模板是否适合我”。分享模板库还有一点容易忽略案例。光有模板没有案例别人很难理解模板到底解决了什么问题。我在 README 里会附上使用前和使用后的效果对比模板本身是静态的但配上真实场景的对比案例后整个模板库的传播价值会高很多。6. 写在最后的个人体会整理 claude-code-templates 这套模板体系的过程本身也是我对自己 AI 使用习惯的一次大扫除。回头看最大的收获不是“省了多少时间”这种可以量化的东西而是我开始用一种工程化的视角去对待 AI 协作这件事。每次沉淀一个模板其实都是在给未来的自己写一份使用说明告诉那个马上就要开始工作的 AI这个项目有什么规矩、这个任务有什么套路、你做完之后我要什么格式的产出。如果你现在还在每次打开 Claude Code 都是临时想怎么提问我建议你从最小的动作开始先为手头最重要的项目写一份 CLAUDE.md把启动命令、目录结构、核心规范写清楚。不用追求一步到位用起来以后哪里不顺就改哪里。当这份 CLAUDE.md 开始真正影响 Claude Code 的输出质量时你自然会想继续沉淀技能和提示词模板。这条路走起来不难就是需要一点点积累但每走一步你手里的工具都会比之前顺手一点。