开篇先说实话这个标题“claude-code-templates”乍一看平平无奇但真正用Claude Code写过几天代码的人都会意识到“模板”这两个字才是撬动效率的核心杠杆。我自己最初用Claude Code时就是裸奔状态——没有CLAUDE.md、没有命令别名、没有子代理每次对话前都要重复交代项目背景、代码规范、测试命令AI还是时不时给出风格割裂的修改。后来我把常用配置沉淀成一套模板仓库体验完全不一样新项目接入从半小时缩短到三分钟团队新成员上手就能让AI按统一规范工作AI改代码的“乱来”概率也大幅下降。这篇文章不是讲Claude Code的基础安装和聊天技巧而是围绕这套模板工程拆解它背后的设计思路、核心配置项的语法与作用、完整的搭建流程以及我在实践中踩过的坑。适合三类人看正在用Claude Code但觉得AI输出不够稳定的开发者想给团队建立统一AI协作规范的工程负责人以及想深度定制CLAUDE.md、子代理、命令别名这些高级功能的进阶用户。内容会偏实战直接给可复制的代码片段和目录结构。1. 为什么Claude Code需要一套模板体系1.1 裸奔状态下的真实痛点先还原一个很常见的场景你打开终端输入claude然后跟AI说“帮我看看这个项目的登录模块重构一下”。Claude Code确实能读代码、能改代码但它对你的项目一无所知——不知道你用React还是Vue不知道你的测试框架是Vitest还是Jest不知道你的目录命名习惯不知道哪些文件是自动生成的不能动。于是它开始“自由发挥”按照它训练数据里最通用的方式来改代码。结果就是改出来的代码能跑但风格跟你的项目完全不像它可能动了一个你明确说了“不要碰”的配置文件它理解错了你的构建脚本用了错误的命令跑测试。这些问题不是Claude Code能力不行而是缺少约束和前置信息。你当然可以在每次对话里把这些信息重新说一遍但对话一长、上下文一挤它还是会忘。模板体系干的就是这件事把项目的背景知识、规则约束、常用命令、任务流程提前固化到配置文件中。每次启动Claude Code它自动加载这些信息就像新员工入职第一天拿到一本员工手册而不是靠带教人每天口头重复。1.2 模板体系的三个层级我把一套完整的Claude Code模板拆成三个层级分别解决不同粒度的问题项目级规范CLAUDE.md描述这个项目是什么、技术栈是什么、目录怎么组织、代码风格是什么、有哪些禁忌。这是AI在项目里工作的“宪法”优先级最高。命令级封装命令别名和斜杠命令把“跑测试”“lint”“提交commit”这类高频操作封装成固定指令。AI不用反复猜测命令格式你也省去每次手动执行的麻烦。任务级分工子代理与技能针对“代码评审”“安全审计”“写测试用例”这类复杂任务定义专门的子代理。让AI先进入特定角色再执行任务输出质量会稳定很多。这三个层级不是互相替代的关系而是叠加生效的。CLAUDE.md管全局命令别名管操作子代理管任务类型。缺了任何一个模板体系都是不完整的。2. 模板工程的核心设计与配置语法2.1 目录结构从零搭一个模板仓库我维护的模板仓库目录结构大致长这样claude-code-templates/ ├── README.md ├── project-templates/ │ ├── frontend-react/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── commands/ │ │ │ │ ├── test.md │ │ │ │ ├── lint.md │ │ │ │ └── commit.md │ │ │ └── agents/ │ │ │ └── code-review.md │ │ └── .claude/settings.json │ ├── backend-python/ │ │ └── ... │ └── fullstack-next/ │ └── ... ├── shared/ │ ├── agents/ │ │ ├── debugger.md │ │ └── security-auditor.md │ └── command-templates/ │ └── ... └── scripts/ └── init_project.sh每个子目录对应一种典型项目类型复制到目标项目根目录就能用。shared/里放的是跨项目通用的子代理和命令模板避免重复维护。scripts/init_project.sh是一个初始化脚本自动化完成复制和替换占位符的工作。注意不同版本对CLAUDE.md的解析优先级有细微差别如果项目里同时存在根目录和子目录的CLAUDE.md建议以根目录为主、子目录为辅避免多个CLAUDE.md互相冲突。2.2 CLAUDE.md的正确写法CLAUDE.md不是越长越好也不是把项目文档整个抄进去。它需要的是“AI能直接执行”的高密度信息。我的经验是分成五个区块项目概览、技术栈、目录结构、编码规范、执行命令和工作流。一个前端React项目的CLAUDE.md示例# 项目概览 这是一个面向中小商户的POS收银系统前端使用React 18 TypeScript。 主要业务模块商品管理、订单结算、会员营销、数据报表。 UI组件库使用Ant Design 5样式方案为CSS Modules。 # 技术栈约束 - 框架: React 18函数组件 Hooks禁止使用class组件。 - 语言: TypeScript strict模式禁止使用any。 - 状态管理: Zustand不使用Redux。 - 数据请求: React Query AxiosAPI层统一封装在src/services。 - 测试: Vitest React Testing Library禁止使用Jest。 # 目录结构 src/ components/ 通用业务组件按domain分子目录 pages/ 页面级路由组件 services/ API请求封装禁止在组件内直接写fetch stores/ Zustand store定义 hooks/ 自定义Hooks utils/ 纯函数工具库 styles/ 全局样式、CSS变量 # 编码规范 - 组件命名使用PascalCase文件名与组件名保持一致。 - CSS变量在styles/variables.css中定义禁止在组件内写死颜色值。 - 所有表单必须有校验规则错误信息使用中文。 - 禁止修改src/__generated__目录下的任何文件这是代码生成器输出。 # 常用命令 - 安装依赖: npm install - 启动开发服务: npm run dev - 运行测试: npm run test -- --run - 类型检查: npm run typecheck - 构建生产包: npm run build这五块内容里最容易忽略的是“禁止事项”。AI对“不要做什么”的遵守程度往往比对“要做什么”更高因为约束条件越明确搜索空间越小。比如“禁止修改生成目录”“禁止用Redux”“禁止在组件里直接写fetch”这些规则能直接拦住AI最常见的越界行为。2.3 命令别名与斜杠命令的封装思路命令别名的作用是给AI提供一套固定的“操作按钮”。CLAUDE.md里写了“运行测试用npm run test”AI也许能记住但每次对话你都要重新确认。改成命令别名后一个/test就搞定而且AI会严格按别名里的步骤来执行。在项目根目录的.claude/commands/test.md里写--- description: 运行项目完整测试套件 argument-hint: 可指定单个测试文件路径如 /test src/utils/format.ts --- 执行以下步骤 1. 如果项目根目录存在package-lock.json或pnpm-lock.yaml使用pnpm安装依赖若已安装可跳过。 2. 运行 pnpm run typecheck若有类型错误先修复。 3. 运行 pnpm run test -- --run执行全量测试。 4. 若测试失败优先检查最近的代码变更定位到具体组件修复后重新执行。 5. 测试全部通过后用一个简短表格汇报测试用例总数、通过数、失败数、修复的文件列表。注意命令文件头部用了YAML front matterdescription是斜杠命令菜单里显示的文字argument-hint提示用户可以跟参数。这样/test就能被自动补全输入/的时候会弹出命令列表。封装的思路不是简单地把命令字符串写死而是把“执行命令 处理失败 汇报结果”的完整流程写进去。这样AI执行/test的时候不是一个动作而是一个完整的任务闭环。2.4 子代理按任务分配专属AI角色子代理是Claude Code里比较高级的功能本质上是在配置文件中预先定义一组系统提示词告诉AI“遇到这类任务时切换到特定的角色、风格和流程”。代码评审在软件开发中极其重要但让通用的Claude Code直接做评审效果往往一般——它不够严格容易放过问题也容易在没有全局视角的情况下乱提意见。在.claude/agents/code-review.md里我的模板长这样--- name: 代码评审员 description: 对当前代码变更进行严格、全面的评审重点找bug、设计缺陷和安全隐患 tools: Read, Grep, Glob --- 你是一名资深代码评审员参与过大型商业项目的code review。你的目标是找出变更中的真实问题而不是给出泛泛的赞美。 评审流程 1. 先读取当前分支的git diff理解改动的全部内容。 2. 定位每个改动文件读取相关的上下文代码确认改动是否完整。 3. 按以下维度逐项检查 - 逻辑正确性边界条件、空值处理、异步竞态、状态更新是否遗漏。 - 类型安全是否有隐式any、类型断言是否合理、是否绕过类型检查。 - 性能问题循环内是否有重复计算、是否触发了不必要的重渲染。 - 安全风险用户输入是否经过校验、是否有XSS/SQL注入隐患。 - 代码风格命名是否规范、是否有死代码、是否违反项目约定。 4. 输出评审报告按严重程度排序阻塞级、建议级、可选级。 5. 每个问题必须给出文件路径、行号、问题描述、修改建议。禁止笼统地写“代码质量有待提高”。 特别提醒 - 不要建议大规模重构除非当前改动存在明确的架构缺陷。 - 不要只夸优点不说问题评审的价值在于发现问题。 - 如果某个文件没有实质性问题可以跳过不用每个文件都评论。子代理和普通对话的区别在于它会严格遵守name和description里定义的角色并且优先使用声明过的tools。比如这个评审员不声明Write工具意味着它默认不会直接改代码只输出评审报告避免了“评审时顺手改了一堆东西”的失控情况。3. 实操过程从模板仓库到项目落地3.1 初始化脚本的设计与实现模板仓库光有一堆md文件还不行直接复制会有问题——每个项目的项目名、包管理器、端口号不一样。所以需要一个初始化脚本负责把模板里的占位符替换成真实项目信息。我常用的脚本片段长这样#!/usr/bin/env bash # init_project.sh - 把模板复制到目标项目并替换占位符 set -euo pipefail TEMPLATE_DIR$(dirname $0)/../project-templates/frontend-react TARGET_DIR${1:-.} if [ ! -d $TARGET_DIR ]; then echo 错误: 目标目录 $TARGET_DIR 不存在 exit 1 fi # 1. 复制模板文件到目标项目 cp -r $TEMPLATE_DIR/. $TARGET_DIR/ # 2. 询问项目关键信息 read -p 项目显示名称用于README和CLAUDE.md: PROJECT_NAME read -p 包管理器 (pnpm/npm/yarn): PKG_MANAGER read -p 开发端口: DEV_PORT # 3. 替换占位符 find $TARGET_DIR/.claude -type f -name *.md -exec sed -i \ -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{PKG_MANAGER}}/$PKG_MANAGER/g \ -e s/{{DEV_PORT}}/$DEV_PORT/g {} # 4. 检查目标项目是否已有CLAUDE.md避免覆盖用户自定义内容 if [ -f $TARGET_DIR/CLAUDE.md ] [ ! -f $TARGET_DIR/CLAUDE.md.bak ]; then cp $TARGET_DIR/CLAUDE.md $TARGET_DIR/CLAUDE.md.bak echo 已存在CLAUDE.md原文件备份为CLAUDE.md.bak fi echo 初始化完成。建议先打开CLAUDE.md按项目实际情况Adjust内容。这个脚本做的事情其实不复杂复制模板、交互式收集配置、批量替换占位符、保护已有文件。但有一个细节值得注意备份已有CLAUDE.md。因为很多项目可能之前已经有了一份简单的CLAUDE.md直接覆盖会把原有信息丢掉备份是最稳妥的做法。提示不要用脚本一次性做太多事。初始化脚本只负责“复制替换备份”这三件事至于安装依赖、初始化git仓库这些操作建议手动执行避免脚本报错后留下一个半初始化状态的项目。3.2 核心模板文件逐个拆解接下来把每个核心模板文件到底写了什么、为什么这么写逐个过一遍。CLAUDE.md的“禁止事项”设计前面给了一个示例这里再展开讲讲“禁止事项”的写法。很多人的CLAUDE.md只写“项目技术栈是什么、目录结构是什么”不写“不能做什么”这会导致AI在一些灰色地带反复试探。比如“不要修改docs/目录下的文件这些是自动生成的API文档”“不要移除任何已存在的commented-out代码除非用户明确要求”“不要在生产代码中留下console.log”。这些规则看着琐碎但每一条都来自真实事故AI清理过自动生成文件、删过注释掉的兼容代码、在提交前加过调试输出。把这些事故写成规则是模板迭代的主要来源。命令别名的格式细节命令别名的文件格式有几点容易被忽略文件名里的连字符和空格会被转成斜杠命令名例如code-review.md对应的命令是/code-review建议全部用小写加连字符避免输入麻烦。front matter里的description字段最好控制在50字以内太长会在命令列表中截断。如果命令需要用户提供参数记得写argument-hint并且在大纲里用{{argument_hint}}这样的占位符引用用户输入。子代理文件的YAML front matter注意事项子代理文件开头的name字段决定了AI自报身份时用的名字tools字段则严格限制能用哪些工具。一个常见误区是以为tools写得多就好——不是的工具越多AI的选择负担越重越容易跑偏。我的经验是让子代理“会读不会写”把修改动作交回主线程。这样既保证了上下文连贯也便于主线程统一协调。3.3 版本管理与模板迭代策略模板仓库本身要用git管理这是废话但怎么管理是有讲究的。我的策略是模板仓库不追踪任何具体项目的业务代码只存放“去掉业务内容后的骨架”。使用分支来区分模板的大版本比如v1-react-spa、v1-node-api、v2-react-spa。因为技术栈演进很快隔一两个月CLAUDE.md里的最佳实践可能就变了分支可以隔离这些变化。每次从模板生成项目后如果发现CLAUDE.md有写得不准的地方先改模板仓库再同步到已生成的项目里而不是反着来。因为已生成的项目是你当前的工作现场容易夹带业务判断不适合作为规则沉淀的源头。模板迭代还有个很实用的来源Claude Code本身的升级日志。官方文档每个版本都会列出行为变化、新配置项、废弃的旧语法我会挑跟模板相关的更新同步到模板仓库里。比如某次升级后settings.json里新增了permissions字段可以更细粒度地控制文件读写权限这个信息如果不及时同步模板里的旧设置就会失效。4. 常见问题与排查技巧实录4.1 AI忽略CLAUDE.md中的规则怎么办这是被问得最多的一个问题CLAUDE.md里明明写好了“不要用class组件”AI还是生成了class组件。原因有几个逐一排查上下文被用户指令覆盖如果对话中途你说了“这里直接用class组件实现一下”AI会优先听从最近的明确指令这是正常的指令优先级逻辑。解决办法是别跟CLAUDE.md的规则冲突或者在冲突时明确说明“这次破例”。CLAUDE.md太长被截断Claude Code对包含CLAUDE.md在内的上下文有窗口限制如果CLAUDE.md超过几千字AI可能在处理具体任务时把它挤出了有效注意力范围。解决方法是精简规则把最重要的5条放在文件最前面次要规则放到子目录里的CLAUDE.md中按场景加载。规则写得太抽象对比“遵守项目编码规范”和“组件文件统一使用PascalCase命名禁止使用默认导出”后者显然更容易被执行。规则必须落到“看到什么、做什么”的粒度而不是“要专业”这类形容词。4.2 加载模板后AI反而变笨了怎么定位有些情况下挂载了CLAUDE.md和一堆子代理后AI的回答反而变得顾此失彼、反应迟钝。这种时候要按层级做减法排查先临时删掉.claude/agents目录下的所有子代理文件重启会话看是否恢复正常。再注释掉命令别名文件里的所有front matter只保留正文看影响是否还在。最后精简CLAUDE.md从完整版缩减到只有项目概览和命令两节再逐步加回其他内容。这个“逐层删减法”是排查性能劣化的最直接路径。我自己遇到过一次某个子代理文件里写了一个良性但冗长的“输出报告格式”模板导致AI每次响应都要先生成一大段没用的格式头看起来就是变笨了。删掉那段冗余描述后响应速度明显改善。4.3 多项目共用模板文件丢失的问题如果多个项目的.claude/目录是直接复制出来的一旦模板仓库更新旧项目不会自动同步。时间一长各项目的配置会漂移得厉害。解决方案是不要用复制用符号链接或同步脚本。我现在的做法是在每个项目里放一个.claude-sync.yml记录这个项目引用了哪个版本的模板。然后写一个同步脚本在模板仓库更新后跑一遍就能按清单把变更推送到各项目。这样既保留了项目本地化的修改同步时会跳过项目里user-modified文件又能跟上模板的更新节奏。5. 从工具效率到团队协作模板的延伸价值5.1 模板是团队知识的外化载体聊到这里已经不只是技术问题了。很多人以为CLAUDE.md是写给AI看的但我用了大半年后的体会是它首先是一份极其精炼的团队知识文档。过去新人入职要花一周读代码、记规范、熟悉工作流现在一份写好的CLAUDE.md就能让AI在几分钟内按照同样的规范行动。这背后其实是把团队里那些“隐性知识”——比如“报表模块的接口字段不能轻易改会波及下游”“这个目录下的组件已经废弃别用了”——全部显性化写进模板里。对于技术负责人来说值得专门花一个下午把CLAUDE.md从“个人备忘录”升级成“团队共识”并且让模板进入Code Review的流程每次改模板都像改代码一样提交PR、做评审。这样模板就是团队最重要的资产之一。5.2 实测过的几个高价值扩展方向模板体系稳定之后我尝试过几个扩展方向都建议有条件的朋友试一试按任务类型定制评审子代理除了代码评审还可以定义“安全审计员”“SQL优化师”“无障碍检查员”等子代理。把Expertise固化到子代理里需要时调用比临时在对话里描述“你扮演一个安全专家”要可靠得多。把模板和CI流程联动很多团队已经用Claude Code做自动修复和代码生成。把模板作为CI里跑Claude Code任务的基础配置就能实现“PR里让AI按团队规范自动检查并修复”这样的流水线能力。跨项目共享公共规则维护一份shared/目录把几条核心安全规则比如“禁止把API密钥写入代码”“禁止使用不安全的随机数生成器”放到那里然后让所有项目的CLAUDE.md通过引用方式引入。这样团队安全策略的更新改一处就生效所有项目。5.3 关于“AI是否真的需要模板”的思考最后想聊一个观念层面的问题。早期我也有过“Claude Code这么聪明为什么要用模板限制它”的疑问。实际用下来的结论恰恰相反模板不是限制而是给AI搭建了一个落脚点。它让AI不是每次都在混乱中猜你的意图而是站在一个由你精心搭建的“规则地基”上工作。聪明的AI需要的是明确的边界和上下文而不是无限的自由。我自己维护这套模板仓库的时间越长越觉得它像一个“定制化的AI工作台”。每踩一个坑就往模板里加一条规则每发现一个高效用法就封装成一个命令或子代理。模板不只是初始化的那一刻起作用它是伴随项目和团队持续生长的活文档。最后再分享一个小技巧给模板加一个CHANGELOG.md记录每一次改动的原因是“修了什么bug”“新增了什么规则”“哪个AI行为模式发生了变化”。这份日志不仅对你自己有追溯价值对团队其他成员理解“为什么模板会这样写”非常有帮助。毕竟AI协作的新范式下维护好这套配置远比每次对话前临时叮嘱AI一堆要求更高效也更靠谱。
Claude Code模板体系实战：用CLAUDE.md与子代理打造稳定AI编程工作流
开篇先说实话这个标题“claude-code-templates”乍一看平平无奇但真正用Claude Code写过几天代码的人都会意识到“模板”这两个字才是撬动效率的核心杠杆。我自己最初用Claude Code时就是裸奔状态——没有CLAUDE.md、没有命令别名、没有子代理每次对话前都要重复交代项目背景、代码规范、测试命令AI还是时不时给出风格割裂的修改。后来我把常用配置沉淀成一套模板仓库体验完全不一样新项目接入从半小时缩短到三分钟团队新成员上手就能让AI按统一规范工作AI改代码的“乱来”概率也大幅下降。这篇文章不是讲Claude Code的基础安装和聊天技巧而是围绕这套模板工程拆解它背后的设计思路、核心配置项的语法与作用、完整的搭建流程以及我在实践中踩过的坑。适合三类人看正在用Claude Code但觉得AI输出不够稳定的开发者想给团队建立统一AI协作规范的工程负责人以及想深度定制CLAUDE.md、子代理、命令别名这些高级功能的进阶用户。内容会偏实战直接给可复制的代码片段和目录结构。1. 为什么Claude Code需要一套模板体系1.1 裸奔状态下的真实痛点先还原一个很常见的场景你打开终端输入claude然后跟AI说“帮我看看这个项目的登录模块重构一下”。Claude Code确实能读代码、能改代码但它对你的项目一无所知——不知道你用React还是Vue不知道你的测试框架是Vitest还是Jest不知道你的目录命名习惯不知道哪些文件是自动生成的不能动。于是它开始“自由发挥”按照它训练数据里最通用的方式来改代码。结果就是改出来的代码能跑但风格跟你的项目完全不像它可能动了一个你明确说了“不要碰”的配置文件它理解错了你的构建脚本用了错误的命令跑测试。这些问题不是Claude Code能力不行而是缺少约束和前置信息。你当然可以在每次对话里把这些信息重新说一遍但对话一长、上下文一挤它还是会忘。模板体系干的就是这件事把项目的背景知识、规则约束、常用命令、任务流程提前固化到配置文件中。每次启动Claude Code它自动加载这些信息就像新员工入职第一天拿到一本员工手册而不是靠带教人每天口头重复。1.2 模板体系的三个层级我把一套完整的Claude Code模板拆成三个层级分别解决不同粒度的问题项目级规范CLAUDE.md描述这个项目是什么、技术栈是什么、目录怎么组织、代码风格是什么、有哪些禁忌。这是AI在项目里工作的“宪法”优先级最高。命令级封装命令别名和斜杠命令把“跑测试”“lint”“提交commit”这类高频操作封装成固定指令。AI不用反复猜测命令格式你也省去每次手动执行的麻烦。任务级分工子代理与技能针对“代码评审”“安全审计”“写测试用例”这类复杂任务定义专门的子代理。让AI先进入特定角色再执行任务输出质量会稳定很多。这三个层级不是互相替代的关系而是叠加生效的。CLAUDE.md管全局命令别名管操作子代理管任务类型。缺了任何一个模板体系都是不完整的。2. 模板工程的核心设计与配置语法2.1 目录结构从零搭一个模板仓库我维护的模板仓库目录结构大致长这样claude-code-templates/ ├── README.md ├── project-templates/ │ ├── frontend-react/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── commands/ │ │ │ │ ├── test.md │ │ │ │ ├── lint.md │ │ │ │ └── commit.md │ │ │ └── agents/ │ │ │ └── code-review.md │ │ └── .claude/settings.json │ ├── backend-python/ │ │ └── ... │ └── fullstack-next/ │ └── ... ├── shared/ │ ├── agents/ │ │ ├── debugger.md │ │ └── security-auditor.md │ └── command-templates/ │ └── ... └── scripts/ └── init_project.sh每个子目录对应一种典型项目类型复制到目标项目根目录就能用。shared/里放的是跨项目通用的子代理和命令模板避免重复维护。scripts/init_project.sh是一个初始化脚本自动化完成复制和替换占位符的工作。注意不同版本对CLAUDE.md的解析优先级有细微差别如果项目里同时存在根目录和子目录的CLAUDE.md建议以根目录为主、子目录为辅避免多个CLAUDE.md互相冲突。2.2 CLAUDE.md的正确写法CLAUDE.md不是越长越好也不是把项目文档整个抄进去。它需要的是“AI能直接执行”的高密度信息。我的经验是分成五个区块项目概览、技术栈、目录结构、编码规范、执行命令和工作流。一个前端React项目的CLAUDE.md示例# 项目概览 这是一个面向中小商户的POS收银系统前端使用React 18 TypeScript。 主要业务模块商品管理、订单结算、会员营销、数据报表。 UI组件库使用Ant Design 5样式方案为CSS Modules。 # 技术栈约束 - 框架: React 18函数组件 Hooks禁止使用class组件。 - 语言: TypeScript strict模式禁止使用any。 - 状态管理: Zustand不使用Redux。 - 数据请求: React Query AxiosAPI层统一封装在src/services。 - 测试: Vitest React Testing Library禁止使用Jest。 # 目录结构 src/ components/ 通用业务组件按domain分子目录 pages/ 页面级路由组件 services/ API请求封装禁止在组件内直接写fetch stores/ Zustand store定义 hooks/ 自定义Hooks utils/ 纯函数工具库 styles/ 全局样式、CSS变量 # 编码规范 - 组件命名使用PascalCase文件名与组件名保持一致。 - CSS变量在styles/variables.css中定义禁止在组件内写死颜色值。 - 所有表单必须有校验规则错误信息使用中文。 - 禁止修改src/__generated__目录下的任何文件这是代码生成器输出。 # 常用命令 - 安装依赖: npm install - 启动开发服务: npm run dev - 运行测试: npm run test -- --run - 类型检查: npm run typecheck - 构建生产包: npm run build这五块内容里最容易忽略的是“禁止事项”。AI对“不要做什么”的遵守程度往往比对“要做什么”更高因为约束条件越明确搜索空间越小。比如“禁止修改生成目录”“禁止用Redux”“禁止在组件里直接写fetch”这些规则能直接拦住AI最常见的越界行为。2.3 命令别名与斜杠命令的封装思路命令别名的作用是给AI提供一套固定的“操作按钮”。CLAUDE.md里写了“运行测试用npm run test”AI也许能记住但每次对话你都要重新确认。改成命令别名后一个/test就搞定而且AI会严格按别名里的步骤来执行。在项目根目录的.claude/commands/test.md里写--- description: 运行项目完整测试套件 argument-hint: 可指定单个测试文件路径如 /test src/utils/format.ts --- 执行以下步骤 1. 如果项目根目录存在package-lock.json或pnpm-lock.yaml使用pnpm安装依赖若已安装可跳过。 2. 运行 pnpm run typecheck若有类型错误先修复。 3. 运行 pnpm run test -- --run执行全量测试。 4. 若测试失败优先检查最近的代码变更定位到具体组件修复后重新执行。 5. 测试全部通过后用一个简短表格汇报测试用例总数、通过数、失败数、修复的文件列表。注意命令文件头部用了YAML front matterdescription是斜杠命令菜单里显示的文字argument-hint提示用户可以跟参数。这样/test就能被自动补全输入/的时候会弹出命令列表。封装的思路不是简单地把命令字符串写死而是把“执行命令 处理失败 汇报结果”的完整流程写进去。这样AI执行/test的时候不是一个动作而是一个完整的任务闭环。2.4 子代理按任务分配专属AI角色子代理是Claude Code里比较高级的功能本质上是在配置文件中预先定义一组系统提示词告诉AI“遇到这类任务时切换到特定的角色、风格和流程”。代码评审在软件开发中极其重要但让通用的Claude Code直接做评审效果往往一般——它不够严格容易放过问题也容易在没有全局视角的情况下乱提意见。在.claude/agents/code-review.md里我的模板长这样--- name: 代码评审员 description: 对当前代码变更进行严格、全面的评审重点找bug、设计缺陷和安全隐患 tools: Read, Grep, Glob --- 你是一名资深代码评审员参与过大型商业项目的code review。你的目标是找出变更中的真实问题而不是给出泛泛的赞美。 评审流程 1. 先读取当前分支的git diff理解改动的全部内容。 2. 定位每个改动文件读取相关的上下文代码确认改动是否完整。 3. 按以下维度逐项检查 - 逻辑正确性边界条件、空值处理、异步竞态、状态更新是否遗漏。 - 类型安全是否有隐式any、类型断言是否合理、是否绕过类型检查。 - 性能问题循环内是否有重复计算、是否触发了不必要的重渲染。 - 安全风险用户输入是否经过校验、是否有XSS/SQL注入隐患。 - 代码风格命名是否规范、是否有死代码、是否违反项目约定。 4. 输出评审报告按严重程度排序阻塞级、建议级、可选级。 5. 每个问题必须给出文件路径、行号、问题描述、修改建议。禁止笼统地写“代码质量有待提高”。 特别提醒 - 不要建议大规模重构除非当前改动存在明确的架构缺陷。 - 不要只夸优点不说问题评审的价值在于发现问题。 - 如果某个文件没有实质性问题可以跳过不用每个文件都评论。子代理和普通对话的区别在于它会严格遵守name和description里定义的角色并且优先使用声明过的tools。比如这个评审员不声明Write工具意味着它默认不会直接改代码只输出评审报告避免了“评审时顺手改了一堆东西”的失控情况。3. 实操过程从模板仓库到项目落地3.1 初始化脚本的设计与实现模板仓库光有一堆md文件还不行直接复制会有问题——每个项目的项目名、包管理器、端口号不一样。所以需要一个初始化脚本负责把模板里的占位符替换成真实项目信息。我常用的脚本片段长这样#!/usr/bin/env bash # init_project.sh - 把模板复制到目标项目并替换占位符 set -euo pipefail TEMPLATE_DIR$(dirname $0)/../project-templates/frontend-react TARGET_DIR${1:-.} if [ ! -d $TARGET_DIR ]; then echo 错误: 目标目录 $TARGET_DIR 不存在 exit 1 fi # 1. 复制模板文件到目标项目 cp -r $TEMPLATE_DIR/. $TARGET_DIR/ # 2. 询问项目关键信息 read -p 项目显示名称用于README和CLAUDE.md: PROJECT_NAME read -p 包管理器 (pnpm/npm/yarn): PKG_MANAGER read -p 开发端口: DEV_PORT # 3. 替换占位符 find $TARGET_DIR/.claude -type f -name *.md -exec sed -i \ -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{PKG_MANAGER}}/$PKG_MANAGER/g \ -e s/{{DEV_PORT}}/$DEV_PORT/g {} # 4. 检查目标项目是否已有CLAUDE.md避免覆盖用户自定义内容 if [ -f $TARGET_DIR/CLAUDE.md ] [ ! -f $TARGET_DIR/CLAUDE.md.bak ]; then cp $TARGET_DIR/CLAUDE.md $TARGET_DIR/CLAUDE.md.bak echo 已存在CLAUDE.md原文件备份为CLAUDE.md.bak fi echo 初始化完成。建议先打开CLAUDE.md按项目实际情况Adjust内容。这个脚本做的事情其实不复杂复制模板、交互式收集配置、批量替换占位符、保护已有文件。但有一个细节值得注意备份已有CLAUDE.md。因为很多项目可能之前已经有了一份简单的CLAUDE.md直接覆盖会把原有信息丢掉备份是最稳妥的做法。提示不要用脚本一次性做太多事。初始化脚本只负责“复制替换备份”这三件事至于安装依赖、初始化git仓库这些操作建议手动执行避免脚本报错后留下一个半初始化状态的项目。3.2 核心模板文件逐个拆解接下来把每个核心模板文件到底写了什么、为什么这么写逐个过一遍。CLAUDE.md的“禁止事项”设计前面给了一个示例这里再展开讲讲“禁止事项”的写法。很多人的CLAUDE.md只写“项目技术栈是什么、目录结构是什么”不写“不能做什么”这会导致AI在一些灰色地带反复试探。比如“不要修改docs/目录下的文件这些是自动生成的API文档”“不要移除任何已存在的commented-out代码除非用户明确要求”“不要在生产代码中留下console.log”。这些规则看着琐碎但每一条都来自真实事故AI清理过自动生成文件、删过注释掉的兼容代码、在提交前加过调试输出。把这些事故写成规则是模板迭代的主要来源。命令别名的格式细节命令别名的文件格式有几点容易被忽略文件名里的连字符和空格会被转成斜杠命令名例如code-review.md对应的命令是/code-review建议全部用小写加连字符避免输入麻烦。front matter里的description字段最好控制在50字以内太长会在命令列表中截断。如果命令需要用户提供参数记得写argument-hint并且在大纲里用{{argument_hint}}这样的占位符引用用户输入。子代理文件的YAML front matter注意事项子代理文件开头的name字段决定了AI自报身份时用的名字tools字段则严格限制能用哪些工具。一个常见误区是以为tools写得多就好——不是的工具越多AI的选择负担越重越容易跑偏。我的经验是让子代理“会读不会写”把修改动作交回主线程。这样既保证了上下文连贯也便于主线程统一协调。3.3 版本管理与模板迭代策略模板仓库本身要用git管理这是废话但怎么管理是有讲究的。我的策略是模板仓库不追踪任何具体项目的业务代码只存放“去掉业务内容后的骨架”。使用分支来区分模板的大版本比如v1-react-spa、v1-node-api、v2-react-spa。因为技术栈演进很快隔一两个月CLAUDE.md里的最佳实践可能就变了分支可以隔离这些变化。每次从模板生成项目后如果发现CLAUDE.md有写得不准的地方先改模板仓库再同步到已生成的项目里而不是反着来。因为已生成的项目是你当前的工作现场容易夹带业务判断不适合作为规则沉淀的源头。模板迭代还有个很实用的来源Claude Code本身的升级日志。官方文档每个版本都会列出行为变化、新配置项、废弃的旧语法我会挑跟模板相关的更新同步到模板仓库里。比如某次升级后settings.json里新增了permissions字段可以更细粒度地控制文件读写权限这个信息如果不及时同步模板里的旧设置就会失效。4. 常见问题与排查技巧实录4.1 AI忽略CLAUDE.md中的规则怎么办这是被问得最多的一个问题CLAUDE.md里明明写好了“不要用class组件”AI还是生成了class组件。原因有几个逐一排查上下文被用户指令覆盖如果对话中途你说了“这里直接用class组件实现一下”AI会优先听从最近的明确指令这是正常的指令优先级逻辑。解决办法是别跟CLAUDE.md的规则冲突或者在冲突时明确说明“这次破例”。CLAUDE.md太长被截断Claude Code对包含CLAUDE.md在内的上下文有窗口限制如果CLAUDE.md超过几千字AI可能在处理具体任务时把它挤出了有效注意力范围。解决方法是精简规则把最重要的5条放在文件最前面次要规则放到子目录里的CLAUDE.md中按场景加载。规则写得太抽象对比“遵守项目编码规范”和“组件文件统一使用PascalCase命名禁止使用默认导出”后者显然更容易被执行。规则必须落到“看到什么、做什么”的粒度而不是“要专业”这类形容词。4.2 加载模板后AI反而变笨了怎么定位有些情况下挂载了CLAUDE.md和一堆子代理后AI的回答反而变得顾此失彼、反应迟钝。这种时候要按层级做减法排查先临时删掉.claude/agents目录下的所有子代理文件重启会话看是否恢复正常。再注释掉命令别名文件里的所有front matter只保留正文看影响是否还在。最后精简CLAUDE.md从完整版缩减到只有项目概览和命令两节再逐步加回其他内容。这个“逐层删减法”是排查性能劣化的最直接路径。我自己遇到过一次某个子代理文件里写了一个良性但冗长的“输出报告格式”模板导致AI每次响应都要先生成一大段没用的格式头看起来就是变笨了。删掉那段冗余描述后响应速度明显改善。4.3 多项目共用模板文件丢失的问题如果多个项目的.claude/目录是直接复制出来的一旦模板仓库更新旧项目不会自动同步。时间一长各项目的配置会漂移得厉害。解决方案是不要用复制用符号链接或同步脚本。我现在的做法是在每个项目里放一个.claude-sync.yml记录这个项目引用了哪个版本的模板。然后写一个同步脚本在模板仓库更新后跑一遍就能按清单把变更推送到各项目。这样既保留了项目本地化的修改同步时会跳过项目里user-modified文件又能跟上模板的更新节奏。5. 从工具效率到团队协作模板的延伸价值5.1 模板是团队知识的外化载体聊到这里已经不只是技术问题了。很多人以为CLAUDE.md是写给AI看的但我用了大半年后的体会是它首先是一份极其精炼的团队知识文档。过去新人入职要花一周读代码、记规范、熟悉工作流现在一份写好的CLAUDE.md就能让AI在几分钟内按照同样的规范行动。这背后其实是把团队里那些“隐性知识”——比如“报表模块的接口字段不能轻易改会波及下游”“这个目录下的组件已经废弃别用了”——全部显性化写进模板里。对于技术负责人来说值得专门花一个下午把CLAUDE.md从“个人备忘录”升级成“团队共识”并且让模板进入Code Review的流程每次改模板都像改代码一样提交PR、做评审。这样模板就是团队最重要的资产之一。5.2 实测过的几个高价值扩展方向模板体系稳定之后我尝试过几个扩展方向都建议有条件的朋友试一试按任务类型定制评审子代理除了代码评审还可以定义“安全审计员”“SQL优化师”“无障碍检查员”等子代理。把Expertise固化到子代理里需要时调用比临时在对话里描述“你扮演一个安全专家”要可靠得多。把模板和CI流程联动很多团队已经用Claude Code做自动修复和代码生成。把模板作为CI里跑Claude Code任务的基础配置就能实现“PR里让AI按团队规范自动检查并修复”这样的流水线能力。跨项目共享公共规则维护一份shared/目录把几条核心安全规则比如“禁止把API密钥写入代码”“禁止使用不安全的随机数生成器”放到那里然后让所有项目的CLAUDE.md通过引用方式引入。这样团队安全策略的更新改一处就生效所有项目。5.3 关于“AI是否真的需要模板”的思考最后想聊一个观念层面的问题。早期我也有过“Claude Code这么聪明为什么要用模板限制它”的疑问。实际用下来的结论恰恰相反模板不是限制而是给AI搭建了一个落脚点。它让AI不是每次都在混乱中猜你的意图而是站在一个由你精心搭建的“规则地基”上工作。聪明的AI需要的是明确的边界和上下文而不是无限的自由。我自己维护这套模板仓库的时间越长越觉得它像一个“定制化的AI工作台”。每踩一个坑就往模板里加一条规则每发现一个高效用法就封装成一个命令或子代理。模板不只是初始化的那一刻起作用它是伴随项目和团队持续生长的活文档。最后再分享一个小技巧给模板加一个CHANGELOG.md记录每一次改动的原因是“修了什么bug”“新增了什么规则”“哪个AI行为模式发生了变化”。这份日志不仅对你自己有追溯价值对团队其他成员理解“为什么模板会这样写”非常有帮助。毕竟AI协作的新范式下维护好这套配置远比每次对话前临时叮嘱AI一堆要求更高效也更靠谱。
