claude-code-templates 这个名字乍看像是某个代码仓库的清单实际上一到手就会发现它是一套围绕 Claude Code 的“开箱即用配置包”把项目记忆、自定义命令、技能文件、初始化脚本全部模板化让代码助手从“一个聪明但健忘的实习生”变成“一个熟悉你项目所有规矩的老师傅”。我最初只是随手整理了几个 CLAUDE.md 片段后来越用越觉得这套东西值得系统化于是干脆把常用结构抽成模板。这篇东西不聊空泛的“AI 编程趋势”只讲 claude-code-templates 这个思路下每个文件怎么写、为什么这么写、以及我踩过的坑。1. 先理解模板到底在解决什么问题1.1 没有模板时代码助手为什么“记不住上下文”很多人第一次用 Claude Code 的感觉是单次对话很强换一个会话就像换了个人。原因不复杂——你每次启动都等于给一个全新的助手交代背景它不知道你的组件命名习惯、不知道你们的接口返回格式、不知道哪些命令是危险的。你可以在对话里反复粘贴说明但这是反人性的而且贴多了照样会漏。模板体系解决的就是这件事把你和团队长期沉淀出来的“项目常识”固化到文件里让助手每次启动时自动读取。CLAUDE.md 就是最典型的一层它相当于给 Claude Code 写了一份入职手册。我实测下来有了这份手册同样一个需求生成代码的规范度肉眼可见地提高不需要每次开场白都重复“我们项目用 pnpm不要用 npm”。1.2 模板这套体系由哪几块拼成claude-code-templates 这类模板库通常不只有 CLAUDE.md我会按功能拆成四块记忆层CLAUDE.md 及其变体描述项目的静态常识、命令、规范。指令层自定义斜杠命令Slash Commands把“生成提交信息”“写单测”“做代码审查”这类高频动作封装成/commit、/test这样的快捷指令。技能层Agent Skills 文件给助手提供某个专业领域的完整操作规程比如 SQL 审查、安全审计、迁移脚本编写。工程层初始化脚本、目录骨架和配套的 settings 文件保证新项目三分钟就能接入整套配置。这个分层思路不是拍脑袋定的。我的经验是记忆层负责“知道项目规矩”指令层负责“降低操作门槛”技能层负责“提升专项质量”工程层负责“让这一切可以复制”。四者配合才是一个完整的模板体系只放一个 CLAUDE.md效果是有的但撑不起复杂项目的需求。2. 项目记忆文件 CLAUDE.md 的模板化写法2.1 CLAUDE.md 的三个层次CLAUDE.md 不是越长越好模板化的关键在于分层。我把它拆成“全局层、项目层、模块层”三种分别放在不同位置全局记忆放在~/.claude/CLAUDE.md写你自己的通用偏好。比如“代码注释用中文”“命令行输出不要中文”“不要自作主张改公共依赖版本”等等。这层是所有项目共享的底层约束。项目记忆放在仓库根目录的CLAUDE.md写这个项目独有的技术栈、目录结构、构建命令、发布流程。子目录记忆放在packages/service/CLAUDE.md这类子目录里写模块专属约定。Claude Code 在读取时会把这个目录链上的相关文件都带上粒度控制得好了长上下文也不会被无效信息占满。我见过不少团队把根目录 CLAUDE.md 写成 300 行的“百科全书”结果关键信息淹没在废话里。模板化的意思是把最常用的 20 条约定放在最前面把冷门但重要的规则放到子级文件里。Claude Code 的注意力是有限的文件分层就是变相的信息排序。2.2 一个可直接用的 CLAUDE.md 模板下面这份模板是我在多个前端项目里反复调整后的版本结构上照着填就行# 项目概况 - 项目名称xxx-admin - 技术栈TypeScript React 18 Vite 5 pnpm - 包管理器pnpm禁止使用 npm/yarn 混用锁定文件 - 运行环境Node.js 20 # 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 执行单测pnpm test -- --watch - 类型检查pnpm typecheck - 构建产物pnpm build # 目录约定 src/ components/ 通用业务组件必须带 index.ts 导出 pages/ 页面组件文件名即路由路径 services/ API 层统一走 request.ts 封装 utils/ 纯函数工具禁止引入业务代码 hooks/ 自定义 Hooks一个文件一个 Hook # 代码规范 - 组件使用函数组件 Hooks不写 class 组件 - 路径别名 / 指向 src/ - API 响应统一为 { code: number, data: T, message: string } - 时间处理一律使用 dayjs禁止手写日期格式化 - 样式方案使用 CSS Modules禁止全局 class 污染 # 变更要求 - 修改接口前先查看 services/ 下的注释文档 - 涉及路由改动必须同步更新侧边栏配置 - 新增加依赖前先说明理由禁止顺手安装这份模板的核心并不是命令列表本身而是“目录约定”和“变更要求”这两个部分。我发现很多人在写 CLAUDE.md 时只写技术栈和命令却忘了写团队真正踩过的坑。你越是把“这里的逻辑容易写错”写清楚助手生成的代码就越不容易踩雷。3. 自定义命令模板把高频操作变成斜杠指令3.1 命令文件的骨架Claude Code 的自定义命令不是写在配置里的字符串而是一个个 Markdown 文件放在.claude/commands/目录下。每个文件就是一个/指令名文件名就是触发词。文件头用 YAML 风格的 frontmatter 声明描述和工具权限正文写执行步骤。一个标准命令模板的结构大致是这样--- description: 生成符合 Conventional Commits 规范的提交信息 argument-hint: 一句话说明本次改动目标 allowed-tools: Bash, Edit --- 你的任务是根据代码改动生成提交信息。 1. 运行 git diff --stat 查看本次改动的文件范围 2. 运行 git diff 查看具体代码变更 3. 结合 argument 和我给出的背景说明判断本次提交类型 4. 按 Conventional Commits 格式输出格式为 type(scope): subject 5. 只输出提交信息文本不要执行 git commit这里面有两个关键点。第一是allowed-tools这个字段它决定了这个命令能调动什么能力。写提交信息只需要读 git 变更那我就不给它 Edit 或 Write 权限防止它顺手改文件。第二是正文里的“只输出文本不要执行 commit”这种“约束性指令”是模板最有价值的部分——少一个步骤后面就少一次擦屁股。3.2 高价值命令模板示例我实际在用的几个命令模板分享出来可以直接放进你的.claude/commands/目录。代码审查命令适合提交 MR 前自查--- description: 对当前分支的改动进行系统性代码审查 allowed-tools: Bash, Read --- 请对当前分支相对 main 分支的改动进行审查 1. 执行 git diff main...HEAD --stat 了解改动规模 2. 逐文件审查 diff重点关注逻辑错误、边界条件、错误处理缺失 3. 检查是否符合项目 CLAUDE.md 中的代码规范 4. 输出审查结论按「严重问题 / 建议优化 / 风格问题」三级分类 5. 每条建议都要给出文件路径和行号方便我定位单元测试生成命令适合给新模块补测试--- description: 为指定模块生成单元测试 argument-hint: 模块路径或函数名例如 src/utils/format.ts allowed-tools: Read, Edit, Bash --- 1. 读取 argument 指定的文件 2. 提取其中的纯函数逻辑列出输入输出边界 3. 使用 vitest 编写测试用例覆盖正常路径和异常路径 4. 测试文件放在同目录下命名为 filename.test.ts 5. 写完后运行 pnpm test 验证通过并修复失败用例这些命令模板看起来简单但真正的价值在于“稳定复现”。我手动审查代码时经常漏掉边界条件但命令模板把审查点固定了下来每次执行都按同一套标准来质量下限被抬高了。4. Agent Skills 技能模板让助手具备“岗位能力”4.1 SKILL.md 的标准结构如果说自定义命令是“快捷键”那 Agent Skills 更像是“岗位说明书”。技能文件放在.claude/skills/技能名/SKILL.md它给 Claude Code 提供一种可被按需加载的专业能力。技能不是每轮对话都加载而是当任务匹配到它的描述时助手会自动读取。一个 SKILL.md 的标准结构通常包含三部分--- name: sql-review description: 对 SQL 变更进行性能与安全审查。当用户要求检查数据库查询、索引优化、上线前 SQL 评估时使用本技能。 --- # SQL 审查流程 ## 第一轮结构审查 - 检查 JOIN 是否缺少关联条件是否有笛卡尔积风险 - 检查 WHERE 子句中函数包裹索引列的情况 - 检查 ORDER BY 是否可能触发文件排序 ## 第二轮安全审查 - 检查是否有全表更新的风险UPDATE 不带 WHERE - 检查是否有 SELECT * 需要改为显式字段 - 检查参数是否可能被拼接进 SQL ## 第三轮输出格式 - 按「风险等级 / 问题描述 / 涉及语句 / 修改建议」输出 - 高风险项必须给出改写后的 SQL 示例关键点有三个name要短description要写清楚“什么时候触发”正文要把流程拆成可执行的轮次。description 写得好不好直接决定技能会不会被正确调用我有一次把描述写得太泛结果助手在不需要审查 SQL 的时候也调用了反而拖慢速度。4.2 技能模板的编写要点与示例编写技能模板时我总结了一个“三段式”经验定义边界、拆分流程、固定输出。边界是让助手判断要不要用本技能流程是让助手一步步按顺序执行固定输出是保证结果格式统一方便你快速扫一眼就能确认质量。再给一个我常用的“依赖升级”技能模板片段--- name: dep-upgrade description: 安全地升级项目依赖包。当用户要求升级 npm/pnpm 依赖、处理版本冲突、检查依赖安全公告时使用。 --- # 依赖升级流程 1. 先看 package.json 当前版本和项目 Node 版本要求确定升级目标版本范围 2. 用 pnpm outdated 列出可升级包优先处理 major 升级 3. 对于 breaking changes先阅读该包官网的 migration guide 再动手 4. 修改后运行 pnpm install 更新锁文件然后执行 typecheck 和核心单测 # 处理冲突 - 如果出现 peerDependencies 冲突优先升级共同依赖到满足范围的最低版本 - 如果存在循环依赖先拆出公共依赖再升级这套技能模板的价值在于没有它的时候升级依赖助手可能直接pnpm update一把梭然后留下一堆兼容性问题。有了技能模板它至少会先看 breaking changes会先跑测试。这种“行为约束”就是技能模板存在的全部意义。5. 模板仓库的整体组织与初始化脚本5.1 仓库目录设计当你开始维护一个 claude-code-templates 仓库时目录结构要像项目模板一样清晰。我的组织方式是这样claude-code-templates/ ├── claude/ │ ├── global/ │ │ └── CLAUDE.md # 个人全局偏好 │ ├── commands/ # 通用斜杠命令 │ │ ├── commit.md │ │ ├── review.md │ │ ├── test.md │ │ └── changelog.md │ ├── skills/ │ │ ├── sql-review/ │ │ │ └── SKILL.md │ │ ├── dep-upgrade/ │ │ │ └── SKILL.md │ │ └── security-check/ │ │ └── SKILL.md │ └── settings.json # 权限与钩子配置 ├── project-scaffold/ │ ├── CLAUDE.md # 项目级模板 │ └── commands/ # 项目专属命令 ├── scripts/ │ └── init.sh # 一键接入脚本 └── README.md # 使用说明与维护指南我把“通用”和“项目专属”分开存放通用部分跨项目复用项目专属部分在初始化时再按需拷贝。这样做的好处是同一个命令模板可以有稳定的版本管理不会因为某个项目的特殊要求而污染通用库。5.2 从零搭建一套模板库具体接入一个新项目时我习惯写一个初始化脚本代替手工拷贝。脚本的核心逻辑不复杂根据项目类型拷贝对应模板、替换占位符、提示用户确认关键选项。#!/usr/bin/env bash # 用法: ./init.sh project-name [web|node|service] set -euo pipefail PROJECT_NAME${1:?请传入项目名} PROJECT_TYPE${2:-web} TEMPLATE_DIR$(dirname $0)/../project-scaffold echo 开始初始化 ${PROJECT_NAME} (${PROJECT_TYPE}) # 拷贝项目级 CLAUDE.md cp ${TEMPLATE_DIR}/CLAUDE.md ./CLAUDE.md # 替换项目名占位符 sed -i s/{{PROJECT_NAME}}/${PROJECT_NAME}/g ./CLAUDE.md # 创建 .claude 目录并拷贝通用命令 mkdir -p .claude/commands .claude/skills cp ${TEMPLATE_DIR}/commands/*.md .claude/commands/ # 根据类型选择特殊配置 case ${PROJECT_TYPE} in web) cp ${TEMPLATE_DIR}/skills/react-best-practice/*.md .claude/skills/ ;; service) cp ${TEMPLATE_DIR}/skills/api-review/*.md .claude/skills/ ;; esac echo 模板接入完成请检查 CLAUDE.md 中的占位符是否替换准确这个脚本里有几个细节很容易忽略。set -euo pipefail是为了避免静默失败PROJECT_TYPE的 case 分支让不同技术栈接到不同技能模板。脚本最后那句“请检查占位符”不是废话——CLAUDE.md 里如果残留{{PROJECT_NAME}}助手在读记忆时会一脸茫然。自动化最怕的就是半自动脚本能做的做到位剩下的该人工确认就人工确认。6. 维护模板库时踩过的坑6.1 模板不生效的几个原因我遇到过不少“明明写了模板却不生效”的情况排查下来集中在三个原因按频率排序目录或文件名不对。Claude Code 对目录位置有约定命令要放在.claude/commands/技能要放在.claude/skills/name/SKILL.md。拼错一个目录名整个文件就会被静默忽略而且不给任何提示。frontmatter 格式错误。比如description忘记写、allowed-tools大小写不对命令照样能加载但行为不可控。我的经验是写完模板后用任意 YAML 校验工具过一遍别偷懒。被系统版本差异影响。Claude Code 的版本迭代很快不同版本对 frontmatter 字段的支持不完全一致。我维护模板仓库时会在 README 里注明“已验证版本”并且关键字段只用主流版本都支持的。排查这类问题时我的思路是先在会话里执行/help或/status看当前版本再逐步缩小范围先确认文件路径再确认 frontmatter最后确认正文指令是否被系统策略拦截。多数问题出在“正文写得像废话”——步骤不明确助手只能自由发挥。6.2 模板越堆越乱怎么办模板库最大的敌人是膨胀。每加一个命令看起来都合理但三个月后你会发现很多命令使用率极低却在每次初始化新项目时都被拷过去白白占用上下文。我的解决方法是定期“复盘裁撤”。具体做法是每个季度翻一次命令文件的使用日志按触发次数排序。使用率最低的三个直接移入archive/目录不从默认初始化里拷贝。有需要再启用而不是默认全量保留。这个思路和代码清理一脉相承——模板也是代码也要面对维护成本。另外一个我特别想提醒的坑是不要用远程模板仓库取代本地检查。templates 仓库更新之后旧项目里的 CLAUDE.md 不会自动同步。我一开始以为这是“顺便的”直到一次事故模板更新了接口规范老项目还沿用旧写法前后端联调时出了一堆兼容性问题。现在我会在模板仓库的 README 里明确写“如何同步到存量项目”把更新步骤文档化。6.3 多项目复用的最佳实践最后聊聊我在多项目之间复用这套模板库的经验。最理想的状态是通用模板放在独立仓库通过子模块或简单地复制粘贴接入各项目然后允许每个项目在本地覆盖部分文件。我用的是一个简单规则通用文件只许收敛不许发散。如果某个项目改了通用命令要么把改动反哺回模板仓库要么就在本地明确标注为“项目私有”绝不混在一起。项目A/.claude/commands/ ├── commit.md # 来自通用模板未修改 ├── review.md # 来自通用模板未修改 └── release.md # 项目私有不反哺模板库这个规则听起来简单但真正做到需要纪律。我见过最混乱的模板库是命令文件里全是按项目写的 if/else读起来像一坨历史遗留代码。模板的价值是“少而精”不是“多而全”。我在实际操作中最大的体会是模板工程和软件工程没有本质区别——抽象得当、边界清晰、文档同步才能真正让团队受益否则它只会变成另一份没人愿意维护的文档。最后分享一个我最近才养成的习惯每次把模板仓库里的内容接入新项目时顺手在命令文件里加一行“最后验证日期”。这行字不占什么容量却能让半年后接手的人一眼看出这份模板是还在维护的活文件还是早已停尸房的僵尸配置。模板这东西活着才有用。