1. 模板体系的设计思路与适用场景先聊点实在的。Claude Code 这类命令行编程助手我用了大半年最深的感触是它的能力上限其实取决于你喂给它的“语境”够不够精确。很多人把它当成一个能聊天的终端随手提需求让它改代码结果改出来的东西总差那么点意思。真正的用法是把那些反复要交代的规则、偏好、技术栈约束沉淀成一套可复用的模板让每一次会话都从“高起点”开始。所谓 claude-code-templates本质上就是一套围绕 Claude Code 工作流的提示词模板与工程化配置集合。它包含几个层面的东西项目级别的 CLAUDE.md 记忆文件、全局的 .claude/rules 规则集、自定义 slash command斜杠命令、以及针对特定任务比如写提交信息、生成测试、做代码审查的结构化提示词。这些模板的终极目的是解决同一个痛点每次新开会话模型都要重新理解你的项目背景、编码风格和目标。为什么要这么折腾我打个比方。你请了一个能力很强的实习生他脑子好使但对你项目一无所知。你每次布置任务都得从头解释一遍“我们这个模块怎么分层、命名用什么风格、数据库连接走哪个配置”。如果把这些话提前写在一张“员工手册”里实习生来了先读册子再干活是不是效率高得多Claude Code 的模板体系就是这个员工手册。适用场景非常明确。如果你是个人开发者维护三五个不同类型的项目——一个 Python 后端、一个 React 前端、一个运维脚本仓库——那么每个项目根目录放一份 CLAUDE.md让 Claude Code 每进一个项目就自动加载对应语境体验是质的飞跃。如果是团队协作模板的价值更大统一的 .claude/rules 能让所有成员用 Claude 干活时产出风格、代码规范、安全底线完全一致相当于把团队的技术规范直接植入到了 AI 的工作流程里。这套东西适合谁命令行走得溜的开发者、在用或准备用 AI 编程助手的工程师、想把手头重复劳动自动化的人。如果你属于以上任何一类这篇文章值得读完。2. 模板核心构成与编写规范要搭一套好用的 Claude Code 模板体系首先得搞清楚它由哪些部分组成。我习惯把它拆成三个层级全局规则层、项目记忆层、任务模板层。三层各司其职缺一不可。2.1 全局规则层所有项目的“宪法”全局规则通常放在~/.claude/目录下核心文件是CLAUDE.md和rules/目录里的规则文件。这一层定义的是不区分项目的通用约束比如默认使用中文还是英文回复输出代码时的注释风格、命名倾向禁止使用某些不安全的 API 或过时语法回答技术问题时必须给出可执行示例涉及生产环境改动前必须二次确认我把全局规则看作“宪法”项目级模板是“地方法规”。宪法管大方向地方法规管具体执行。写全局规则的时候有个原则要记住不要贪多只写那些你在所有项目中都不希望被违背的底线。比如我自己全局只写了十几条核心是代码安全、输出格式、责任边界。一个容易被忽视的细节是CLAUDE.md的加载机制。Claude Code 会读取这个文件并把它作为系统上下文的一部分但上下文窗口是有限的。如果你把所有东西都堆进全局 CLAUDE.md那些低频信息会挤占高频信息的位置反而降低回答质量。我的做法是全局文件只保留 20 条以内的高优先级规则其他按主题拆到rules/目录下并用关键词触发机制按需加载。2.2 项目记忆层每个仓库的“家谱”项目级CLAUDE.md放在仓库根目录Claude Code 进入项目时会自动读取。相比全局规则这部分要写得极其具体。我通常会包含以下内容块项目一句话简介这个项目是做什么的面向谁技术栈清单语言版本、框架、关键依赖目录结构地图核心目录各自负责什么哪里放业务代码哪里放工具函数编码规范ESLint 规则、prettier 配置、命名是 camelCase 还是 snake_case常用命令如何本地启动、跑测试、构建、部署架构决策记录哪些地方做过关键技术选型为什么以及以后改动的注意事项有些内容也许可以找到相关代码库或文档但模板的重点在于把它们用自然语言描述清楚并注明“改动前先问”的事项。比如我在一个支付项目中写过“除PaymentService外禁止在其他模块直接调用支付网关 SDK如果必须调用先说明理由再动代码。”这种约束在代码层面不容易用检查工具落实但对大模型来说读一遍就能理解并遵守。还要提醒一点项目记忆不是一劳永逸的。每当你做了一次较大的架构调整记得同步更新 CLAUDE.md。否则模板会变成“过期地图”误导 AI 到已经不存在的目录里找代码。2.3 任务模板层与 slash command 的结合如果说前两层是“背景知识”那任务模板层就是“标准作业程序”。Claude Code 支持自定义斜杠命令命令本质上是绑定一段预设提示词。我常用的几个模板命令包括/commit生成符合 Conventional Commits 规范的提交信息/review对当前改动做代码审查重点查安全和性能/testgen为指定函数生成单元测试用例/explain用通俗语言解释一段复杂代码/refactor提出重构方案并按步骤执行每个斜杠命令对应一个.claude/commands/目录下的 markdown 文件。文件里写一段结构化的提示词告诉 Claude 执行任务时应遵循什么步骤、关注什么方面、输出什么格式。比如我的/commit模板核心内容是这样设计的请根据当前的 git diff 生成一个符合 Conventional Commits 规范的提交信息。 要求 1. 类型使用 feat / fix / refactor / chore / docs / test 之一 2. 提交说明简洁不超过 100 字符描述“做了什么”而不是“怎么改” 3. 如果变更涉及破坏性更新在正文中标注 BREAKING CHANGE 4. 只输出提交信息不要输出多余解释你看任务模板把“怎么做”的步骤讲清楚了但不替 Claude 做决定。它在给模型划定了作业边界的同时保留了足够的灵活性。3. 从零搭建一份可复现的模板配置很多教程爱讲原理但真正上手时你会发现“啊原来这个文件放这里”“原来那个命令要这么命名”。这里我直接给出一份我电脑上正在用的实战配置从目录结构到文件内容一步步来。3.1 建立目录骨架先在你的用户目录下规划出整个模板体系的存放位置~/.claude/ ├── CLAUDE.md # 全局记忆文件 ├── rules/ # 按主题拆分按需加载 │ ├── frontend.md │ ├── backend.md │ └── security.md └── commands/ # 全局可用斜杠命令 ├── commit.md ├── review.md ├── testgen.md └── explain.md然后在每个项目仓库里添加项目级的配置项目根目录/ ├── CLAUDE.md # 项目记忆 └── .claude/ ├── rules/ # 仅本项目生效的补充规则 └── commands/ # 仅本项目生效的斜杠命令Claude Code 在查找配置时遵循就近原则项目级配置会覆盖或补充全局配置。这个设计非常合理允许不同项目拥有各自的“性格”又不会完全脱离全局底线。3.2 全局 CLAUDE.md 实例直接看我的一份简化版全局配置。不是让大家照抄而是参考它的结构和表述方式。关键是要具体、无歧义、多用“必须/禁止/优先”这类明确指令。# 全局工作规则 ## 代码输出 - 默认使用 TypeScript 编写代码除非项目另有约定 - 注释使用中文但代码中的标识符和字符串使用英文 - 禁止使用 any 类型可用 unknown 代替 - 所有异步操作必须处理错误禁止静默 catch ## 回答风格 - 先给结论再解释原因 - 面向前端开发者避免堆砌过于底层的术语 - 引用 API 时附上官方文档链接 - 对于不确定的内容明确指出“此方案未验证”并给出备选 ## 安全底线 - 禁止硬编码密钥、密码、token - 涉及删除文件或修改权限的命令必须列出影响范围并确认 - 不允许生成绕过代码审查的脚本这里有个经验不要写“尽量用中文注释”这种模糊表达要写“注释使用中文”。模型对模糊指令的理解空间太大导致每次输出都猜你的心思。把规则变成硬约束产出的稳定性会显著提升。3.3 项目级 CLAUDE.md 实例这个过程也分享个实际例子。之前我做一个数据可视化平台项目里的 CLAUDE.md 是这样写的# DataViz Platform ## 项目定位 面向企业客户的可视化大屏配置工具核心价值是 5 分钟内完成数据接入与图表发布。 ## 技术栈 - 前端React 18 TypeScript Vite Ant Design 5 - 后端Node.js Express PostgreSQL - 部署Docker Compose 单机部署 ## 目录结构 - src/pages - 路由级页面组件 - src/components - 可复用业务组件 - src/api - 接口请求封装禁止页面直接调用 fetch - src/hooks - 自定义业务 hooks - src/utils - 纯工具函数禁止依赖业务模块 ## 编码约束 - 图表组件统一封装在 src/components/charts/ 下接受 data 和 config 两个 props - 所有接口返回 { code, data, message } 结构前端用 api/request.ts 统一处理 - 环境变量以 VITE_ 开头配置文件位于 .env 文件 - 修改数据库表结构时同步更新 migrations/ 目录下的版本文件 ## 本地开发 - 安装依赖npm install - 启动开发环境npm run dev端口 5173 - 运行单元测试npm run test:unit - 构建生产包npm run build /code写这份文件时花了我大概二十分钟此后每一次在项目里用 Claude Code 干活它都能快速理解我的代码组织方式和特殊约定。按我实测的经验模板带来的收益远大于写它的时间成本。特别是那种隔几个月才回来维护的老项目靠一份好的模板模型能立刻恢复到“上周还在写这个项目”的状态。3.4 自定义 slash command 示例再看一个完整可用的/review命令模板。这个命令每次执行Claude 都会按固定流程检查代码# 代码审查命令 你是一名资深代码审查员请对当前工作区的未提交改动进行审查。 ## 审查流程 1. 运行 git diff 查看变更内容 2. 逐个文件检查并输出问题清单 3. 每个问题需标注严重级别阻塞/高/中/低和对应行号 ## 检查重点 - 逻辑错误空指针、边界条件、并发问题 - 安全性注入风险、敏感信息泄露、权限缺失 - 性能不必要的计算、重复请求、内存泄漏 - 可维护性命名是否达意、函数是否过长、是否有死代码 ## 输出格式 - 使用表格列出问题文件、行号、级别、问题描述、建议 - 未发现问题时直接输出“未发现明显问题” - 不要修改代码仅输出审查结果 ## 特别注意 - 对 CPU 密集场景优先建议使用缓存或异步方案 - 对数据库查询关注是否命中索引、是否存在 N1 问题这类命令文件放在~/.claude/commands/review.md或项目.claude/commands/review.md下重启 Claude Code 后就可以直接/review调用了。4. 常见问题与实战排错技巧再好的配置用起来总会遇到各种意外。这里把我踩过的坑、以及社区里常见的问题集中梳理一下按频率排个序。4.1 模板没有被自动加载怎么办现象是明明写了 CLAUDE.md但 Claude 好像完全没读问出来的回答像是“失忆”。排查思路分三步第一步确认文件位置。全局文件必须在~/.claude/下项目文件必须在仓库根目录。放进./.claude/不等于放进根目录。第二步查看会话信息。Claude Code 启动时会打印加载了哪些配置文件留意有没有包含你的 CLAUDE.md。第三步检查文件大小。如果单文件超过几百行模型可能只加载了一部分。我建议把项目级 CLAUDE.md 控制在 100 行以内规则类的拆到 rules 目录按主题加载。另外有个小技巧写完模板后直接在会话里问一句“我们项目用什么技术栈编码规范有哪些”如果回答和模板一致说明加载成功。这个小测试比看日志直观得多。4.2 模型执行偏差写了规则但不遵守有时写明了“严禁在页面组件中直接发请求”它还是会往 useEffect 里塞 fetch。这类问题很常见原因往往不是模型笨而是你的指令被更后方的上下文覆盖了。解决办法把最关键的约束重复出现在任务指令里。每次提问带上简短约束比只写在 CLAUDE.md 里更有效。在模板中使用“如果……则必须……”的句式加重语气。例如“如果要在组件中请求数据必须走src/api封装层否则拒绝生成代码。”利用 slash command 固化流程每次用/newpage之类的命令生成页面时自动带着这些约束。还有一点值得我们注意不要一次给太多规则。一个任务里如果同时要求“用 React”“保持类型安全”“遵循 A 规范”“避免 B 反模式”“性能要达标”“代码要简洁”那模型会平均用力每条都做不彻底。一次对话突出 2-3 个核心约束其他交给全局规则逐步强化是更现实的做法。4.3 模板间的冲突项目规则覆盖全局规则假设全局规则要求“所有代码用 TypeScript”但某个项目本身是 JavaScript 老项目结果模型进入这个项目后仍然强行生成 TS 代码。这是因为项目级 CLAUDE.md 更高优先级如果项目文件里没有明确说“本仓库是 JavaScript禁止混入 TS”它就会跟随全局规则。解决方式很简单项目级 CLAUDE.md 里写清楚覆盖声明。我用过一个固定句式“本项目以本文件为准。若与全局规则冲突以项目文件为准且以下约定优先。”在全局规则里也加一句“项目 CLAUDE.md 与本文件冲突时以项目为准。”两层互相授权就基本不会打架了。4.4 模板上下文过长导致回答质量下降上下文是有成本的把大量模板塞进每次会话会导致模型注意力分散、回答走神。对大型项目更是如此。我统计过自己一个中大型前端项目完整 CLAUDE.md 加上各种 rules 如果全部加载大概要占 20K token 以上这还不算代码文件本身。此时 Claude 的短期记忆会被模板塞满反而忽略了你当前的提问。应对策略是分层加载。全局级别只保留最少量必须信息项目级别负责核心架构说明和技术栈任务级别的信息放进 slash command用到哪个加载哪个。如果你的项目确实太大还应该把 CLAUDE.md 拆成多个文档用“按需引用”的方式组织比如在根文件里写“数据库相关约束见docs/claude/database.md”然后在对话中让 Claude 去读那个文件。实测下来这个做法比一股脑加载更稳定。4.5 给团队使用时成员的模板不一致组内有几个人都在用 Claude Code各写各的模板产出自然五花八门。我的做法是把模板目录纳入 Git 仓库管理。在项目根目录建claude-templates/目录把该共享的 CLAUDE.md、rules、commands 全部放进去然后在 Git 仓库的 README 里注明“新增成员必读先复制 claude-templates 内容到各自环境”。更进一步可以在项目里做一个安装脚本# setup-claude.sh #!/bin/bash TEMPLATE_DIRclaude-templates if [ -d $TEMPLATE_DIR ]; then cp $TEMPLATE_DIR/CLAUDE.md ./CLAUDE.md cp -r $TEMPLATE_DIR/.claude ./ echo Claude templates installed. else echo Template directory not found. fi这样每个成员 clone 后执行一遍脚本环境就统一了。规则文件的版本追踪还能用 git log 回查和代码管理完全同构。5. 从模板到技能的进阶之路如果你已经能用上述模板让 Claude Code 稳定干活下一步可以考虑把它升级成更复杂的“技能”Skills。Skills 是比命令更重量级的能力单元它包含预置的步骤流、工具调用方式、甚至多轮交互逻辑。举个例子你可以做一个“接口联调技能”让 Claude 在生成前端页面之后自动检测缺失的接口定义、模拟返回数据、生成类型声明最后跑一遍 ESLint。为什么要从模板升级到技能模板的核心是一次性“指令”而技能的核心是可编排的“流程”。我在处理一个多模块功能开发时先用的 slash command每步手动触发换成技能后Claude 能自己判断“当前步骤完成了进入下一步”。这个提升是本质性的。但技能的开发成本也更高需要调试的边界情况更多。我的建议是先把模板用熟遇到重复三次以上的多步骤任务时再考虑封装成技能。不要第一周就直接冲技能容易一头扎进去。在实际操作中还有一个体会模板和技能都不是“写完就完”的静态产物。AI 的能力在迭代你的项目在演进团队规范也在变化——模板需要常态化维护。我给自己定的规则是每两周花十分钟过一遍所有 CLAUDE.md看看有没有过时的目录、废弃的命令、不再适用的约束。这个习惯看起来不起眼但长期坚持下来你的模板体系会越来越顺滑Claude Code 的产出也会越来越省心。这也算是我个人目前感受到的最大价值模板不是给 AI 用的是给你未来的自己用的。两个月后回到一个老项目靠着这份模板你不需要翻旧代码回忆上下文AI 已经替你记住了该有的语境。省下来的时间就是我坚持维护这套体系的最大理由。 Claude Code 模板体系：从提示词规范到工程化配置的完整实战指南
1. 模板体系的设计思路与适用场景先聊点实在的。Claude Code 这类命令行编程助手我用了大半年最深的感触是它的能力上限其实取决于你喂给它的“语境”够不够精确。很多人把它当成一个能聊天的终端随手提需求让它改代码结果改出来的东西总差那么点意思。真正的用法是把那些反复要交代的规则、偏好、技术栈约束沉淀成一套可复用的模板让每一次会话都从“高起点”开始。所谓 claude-code-templates本质上就是一套围绕 Claude Code 工作流的提示词模板与工程化配置集合。它包含几个层面的东西项目级别的 CLAUDE.md 记忆文件、全局的 .claude/rules 规则集、自定义 slash command斜杠命令、以及针对特定任务比如写提交信息、生成测试、做代码审查的结构化提示词。这些模板的终极目的是解决同一个痛点每次新开会话模型都要重新理解你的项目背景、编码风格和目标。为什么要这么折腾我打个比方。你请了一个能力很强的实习生他脑子好使但对你项目一无所知。你每次布置任务都得从头解释一遍“我们这个模块怎么分层、命名用什么风格、数据库连接走哪个配置”。如果把这些话提前写在一张“员工手册”里实习生来了先读册子再干活是不是效率高得多Claude Code 的模板体系就是这个员工手册。适用场景非常明确。如果你是个人开发者维护三五个不同类型的项目——一个 Python 后端、一个 React 前端、一个运维脚本仓库——那么每个项目根目录放一份 CLAUDE.md让 Claude Code 每进一个项目就自动加载对应语境体验是质的飞跃。如果是团队协作模板的价值更大统一的 .claude/rules 能让所有成员用 Claude 干活时产出风格、代码规范、安全底线完全一致相当于把团队的技术规范直接植入到了 AI 的工作流程里。这套东西适合谁命令行走得溜的开发者、在用或准备用 AI 编程助手的工程师、想把手头重复劳动自动化的人。如果你属于以上任何一类这篇文章值得读完。2. 模板核心构成与编写规范要搭一套好用的 Claude Code 模板体系首先得搞清楚它由哪些部分组成。我习惯把它拆成三个层级全局规则层、项目记忆层、任务模板层。三层各司其职缺一不可。2.1 全局规则层所有项目的“宪法”全局规则通常放在~/.claude/目录下核心文件是CLAUDE.md和rules/目录里的规则文件。这一层定义的是不区分项目的通用约束比如默认使用中文还是英文回复输出代码时的注释风格、命名倾向禁止使用某些不安全的 API 或过时语法回答技术问题时必须给出可执行示例涉及生产环境改动前必须二次确认我把全局规则看作“宪法”项目级模板是“地方法规”。宪法管大方向地方法规管具体执行。写全局规则的时候有个原则要记住不要贪多只写那些你在所有项目中都不希望被违背的底线。比如我自己全局只写了十几条核心是代码安全、输出格式、责任边界。一个容易被忽视的细节是CLAUDE.md的加载机制。Claude Code 会读取这个文件并把它作为系统上下文的一部分但上下文窗口是有限的。如果你把所有东西都堆进全局 CLAUDE.md那些低频信息会挤占高频信息的位置反而降低回答质量。我的做法是全局文件只保留 20 条以内的高优先级规则其他按主题拆到rules/目录下并用关键词触发机制按需加载。2.2 项目记忆层每个仓库的“家谱”项目级CLAUDE.md放在仓库根目录Claude Code 进入项目时会自动读取。相比全局规则这部分要写得极其具体。我通常会包含以下内容块项目一句话简介这个项目是做什么的面向谁技术栈清单语言版本、框架、关键依赖目录结构地图核心目录各自负责什么哪里放业务代码哪里放工具函数编码规范ESLint 规则、prettier 配置、命名是 camelCase 还是 snake_case常用命令如何本地启动、跑测试、构建、部署架构决策记录哪些地方做过关键技术选型为什么以及以后改动的注意事项有些内容也许可以找到相关代码库或文档但模板的重点在于把它们用自然语言描述清楚并注明“改动前先问”的事项。比如我在一个支付项目中写过“除PaymentService外禁止在其他模块直接调用支付网关 SDK如果必须调用先说明理由再动代码。”这种约束在代码层面不容易用检查工具落实但对大模型来说读一遍就能理解并遵守。还要提醒一点项目记忆不是一劳永逸的。每当你做了一次较大的架构调整记得同步更新 CLAUDE.md。否则模板会变成“过期地图”误导 AI 到已经不存在的目录里找代码。2.3 任务模板层与 slash command 的结合如果说前两层是“背景知识”那任务模板层就是“标准作业程序”。Claude Code 支持自定义斜杠命令命令本质上是绑定一段预设提示词。我常用的几个模板命令包括/commit生成符合 Conventional Commits 规范的提交信息/review对当前改动做代码审查重点查安全和性能/testgen为指定函数生成单元测试用例/explain用通俗语言解释一段复杂代码/refactor提出重构方案并按步骤执行每个斜杠命令对应一个.claude/commands/目录下的 markdown 文件。文件里写一段结构化的提示词告诉 Claude 执行任务时应遵循什么步骤、关注什么方面、输出什么格式。比如我的/commit模板核心内容是这样设计的请根据当前的 git diff 生成一个符合 Conventional Commits 规范的提交信息。 要求 1. 类型使用 feat / fix / refactor / chore / docs / test 之一 2. 提交说明简洁不超过 100 字符描述“做了什么”而不是“怎么改” 3. 如果变更涉及破坏性更新在正文中标注 BREAKING CHANGE 4. 只输出提交信息不要输出多余解释你看任务模板把“怎么做”的步骤讲清楚了但不替 Claude 做决定。它在给模型划定了作业边界的同时保留了足够的灵活性。3. 从零搭建一份可复现的模板配置很多教程爱讲原理但真正上手时你会发现“啊原来这个文件放这里”“原来那个命令要这么命名”。这里我直接给出一份我电脑上正在用的实战配置从目录结构到文件内容一步步来。3.1 建立目录骨架先在你的用户目录下规划出整个模板体系的存放位置~/.claude/ ├── CLAUDE.md # 全局记忆文件 ├── rules/ # 按主题拆分按需加载 │ ├── frontend.md │ ├── backend.md │ └── security.md └── commands/ # 全局可用斜杠命令 ├── commit.md ├── review.md ├── testgen.md └── explain.md然后在每个项目仓库里添加项目级的配置项目根目录/ ├── CLAUDE.md # 项目记忆 └── .claude/ ├── rules/ # 仅本项目生效的补充规则 └── commands/ # 仅本项目生效的斜杠命令Claude Code 在查找配置时遵循就近原则项目级配置会覆盖或补充全局配置。这个设计非常合理允许不同项目拥有各自的“性格”又不会完全脱离全局底线。3.2 全局 CLAUDE.md 实例直接看我的一份简化版全局配置。不是让大家照抄而是参考它的结构和表述方式。关键是要具体、无歧义、多用“必须/禁止/优先”这类明确指令。# 全局工作规则 ## 代码输出 - 默认使用 TypeScript 编写代码除非项目另有约定 - 注释使用中文但代码中的标识符和字符串使用英文 - 禁止使用 any 类型可用 unknown 代替 - 所有异步操作必须处理错误禁止静默 catch ## 回答风格 - 先给结论再解释原因 - 面向前端开发者避免堆砌过于底层的术语 - 引用 API 时附上官方文档链接 - 对于不确定的内容明确指出“此方案未验证”并给出备选 ## 安全底线 - 禁止硬编码密钥、密码、token - 涉及删除文件或修改权限的命令必须列出影响范围并确认 - 不允许生成绕过代码审查的脚本这里有个经验不要写“尽量用中文注释”这种模糊表达要写“注释使用中文”。模型对模糊指令的理解空间太大导致每次输出都猜你的心思。把规则变成硬约束产出的稳定性会显著提升。3.3 项目级 CLAUDE.md 实例这个过程也分享个实际例子。之前我做一个数据可视化平台项目里的 CLAUDE.md 是这样写的# DataViz Platform ## 项目定位 面向企业客户的可视化大屏配置工具核心价值是 5 分钟内完成数据接入与图表发布。 ## 技术栈 - 前端React 18 TypeScript Vite Ant Design 5 - 后端Node.js Express PostgreSQL - 部署Docker Compose 单机部署 ## 目录结构 - src/pages - 路由级页面组件 - src/components - 可复用业务组件 - src/api - 接口请求封装禁止页面直接调用 fetch - src/hooks - 自定义业务 hooks - src/utils - 纯工具函数禁止依赖业务模块 ## 编码约束 - 图表组件统一封装在 src/components/charts/ 下接受 data 和 config 两个 props - 所有接口返回 { code, data, message } 结构前端用 api/request.ts 统一处理 - 环境变量以 VITE_ 开头配置文件位于 .env 文件 - 修改数据库表结构时同步更新 migrations/ 目录下的版本文件 ## 本地开发 - 安装依赖npm install - 启动开发环境npm run dev端口 5173 - 运行单元测试npm run test:unit - 构建生产包npm run build /code写这份文件时花了我大概二十分钟此后每一次在项目里用 Claude Code 干活它都能快速理解我的代码组织方式和特殊约定。按我实测的经验模板带来的收益远大于写它的时间成本。特别是那种隔几个月才回来维护的老项目靠一份好的模板模型能立刻恢复到“上周还在写这个项目”的状态。3.4 自定义 slash command 示例再看一个完整可用的/review命令模板。这个命令每次执行Claude 都会按固定流程检查代码# 代码审查命令 你是一名资深代码审查员请对当前工作区的未提交改动进行审查。 ## 审查流程 1. 运行 git diff 查看变更内容 2. 逐个文件检查并输出问题清单 3. 每个问题需标注严重级别阻塞/高/中/低和对应行号 ## 检查重点 - 逻辑错误空指针、边界条件、并发问题 - 安全性注入风险、敏感信息泄露、权限缺失 - 性能不必要的计算、重复请求、内存泄漏 - 可维护性命名是否达意、函数是否过长、是否有死代码 ## 输出格式 - 使用表格列出问题文件、行号、级别、问题描述、建议 - 未发现问题时直接输出“未发现明显问题” - 不要修改代码仅输出审查结果 ## 特别注意 - 对 CPU 密集场景优先建议使用缓存或异步方案 - 对数据库查询关注是否命中索引、是否存在 N1 问题这类命令文件放在~/.claude/commands/review.md或项目.claude/commands/review.md下重启 Claude Code 后就可以直接/review调用了。4. 常见问题与实战排错技巧再好的配置用起来总会遇到各种意外。这里把我踩过的坑、以及社区里常见的问题集中梳理一下按频率排个序。4.1 模板没有被自动加载怎么办现象是明明写了 CLAUDE.md但 Claude 好像完全没读问出来的回答像是“失忆”。排查思路分三步第一步确认文件位置。全局文件必须在~/.claude/下项目文件必须在仓库根目录。放进./.claude/不等于放进根目录。第二步查看会话信息。Claude Code 启动时会打印加载了哪些配置文件留意有没有包含你的 CLAUDE.md。第三步检查文件大小。如果单文件超过几百行模型可能只加载了一部分。我建议把项目级 CLAUDE.md 控制在 100 行以内规则类的拆到 rules 目录按主题加载。另外有个小技巧写完模板后直接在会话里问一句“我们项目用什么技术栈编码规范有哪些”如果回答和模板一致说明加载成功。这个小测试比看日志直观得多。4.2 模型执行偏差写了规则但不遵守有时写明了“严禁在页面组件中直接发请求”它还是会往 useEffect 里塞 fetch。这类问题很常见原因往往不是模型笨而是你的指令被更后方的上下文覆盖了。解决办法把最关键的约束重复出现在任务指令里。每次提问带上简短约束比只写在 CLAUDE.md 里更有效。在模板中使用“如果……则必须……”的句式加重语气。例如“如果要在组件中请求数据必须走src/api封装层否则拒绝生成代码。”利用 slash command 固化流程每次用/newpage之类的命令生成页面时自动带着这些约束。还有一点值得我们注意不要一次给太多规则。一个任务里如果同时要求“用 React”“保持类型安全”“遵循 A 规范”“避免 B 反模式”“性能要达标”“代码要简洁”那模型会平均用力每条都做不彻底。一次对话突出 2-3 个核心约束其他交给全局规则逐步强化是更现实的做法。4.3 模板间的冲突项目规则覆盖全局规则假设全局规则要求“所有代码用 TypeScript”但某个项目本身是 JavaScript 老项目结果模型进入这个项目后仍然强行生成 TS 代码。这是因为项目级 CLAUDE.md 更高优先级如果项目文件里没有明确说“本仓库是 JavaScript禁止混入 TS”它就会跟随全局规则。解决方式很简单项目级 CLAUDE.md 里写清楚覆盖声明。我用过一个固定句式“本项目以本文件为准。若与全局规则冲突以项目文件为准且以下约定优先。”在全局规则里也加一句“项目 CLAUDE.md 与本文件冲突时以项目为准。”两层互相授权就基本不会打架了。4.4 模板上下文过长导致回答质量下降上下文是有成本的把大量模板塞进每次会话会导致模型注意力分散、回答走神。对大型项目更是如此。我统计过自己一个中大型前端项目完整 CLAUDE.md 加上各种 rules 如果全部加载大概要占 20K token 以上这还不算代码文件本身。此时 Claude 的短期记忆会被模板塞满反而忽略了你当前的提问。应对策略是分层加载。全局级别只保留最少量必须信息项目级别负责核心架构说明和技术栈任务级别的信息放进 slash command用到哪个加载哪个。如果你的项目确实太大还应该把 CLAUDE.md 拆成多个文档用“按需引用”的方式组织比如在根文件里写“数据库相关约束见docs/claude/database.md”然后在对话中让 Claude 去读那个文件。实测下来这个做法比一股脑加载更稳定。4.5 给团队使用时成员的模板不一致组内有几个人都在用 Claude Code各写各的模板产出自然五花八门。我的做法是把模板目录纳入 Git 仓库管理。在项目根目录建claude-templates/目录把该共享的 CLAUDE.md、rules、commands 全部放进去然后在 Git 仓库的 README 里注明“新增成员必读先复制 claude-templates 内容到各自环境”。更进一步可以在项目里做一个安装脚本# setup-claude.sh #!/bin/bash TEMPLATE_DIRclaude-templates if [ -d $TEMPLATE_DIR ]; then cp $TEMPLATE_DIR/CLAUDE.md ./CLAUDE.md cp -r $TEMPLATE_DIR/.claude ./ echo Claude templates installed. else echo Template directory not found. fi这样每个成员 clone 后执行一遍脚本环境就统一了。规则文件的版本追踪还能用 git log 回查和代码管理完全同构。5. 从模板到技能的进阶之路如果你已经能用上述模板让 Claude Code 稳定干活下一步可以考虑把它升级成更复杂的“技能”Skills。Skills 是比命令更重量级的能力单元它包含预置的步骤流、工具调用方式、甚至多轮交互逻辑。举个例子你可以做一个“接口联调技能”让 Claude 在生成前端页面之后自动检测缺失的接口定义、模拟返回数据、生成类型声明最后跑一遍 ESLint。为什么要从模板升级到技能模板的核心是一次性“指令”而技能的核心是可编排的“流程”。我在处理一个多模块功能开发时先用的 slash command每步手动触发换成技能后Claude 能自己判断“当前步骤完成了进入下一步”。这个提升是本质性的。但技能的开发成本也更高需要调试的边界情况更多。我的建议是先把模板用熟遇到重复三次以上的多步骤任务时再考虑封装成技能。不要第一周就直接冲技能容易一头扎进去。在实际操作中还有一个体会模板和技能都不是“写完就完”的静态产物。AI 的能力在迭代你的项目在演进团队规范也在变化——模板需要常态化维护。我给自己定的规则是每两周花十分钟过一遍所有 CLAUDE.md看看有没有过时的目录、废弃的命令、不再适用的约束。这个习惯看起来不起眼但长期坚持下来你的模板体系会越来越顺滑Claude Code 的产出也会越来越省心。这也算是我个人目前感受到的最大价值模板不是给 AI 用的是给你未来的自己用的。两个月后回到一个老项目靠着这份模板你不需要翻旧代码回忆上下文AI 已经替你记住了该有的语境。省下来的时间就是我坚持维护这套体系的最大理由。