先说一个我自己的直观感受Claude Code这玩意儿裸跑和配置好模板之后完全像是两个产品。最早我把Claude Code装进终端就直接开用了结果发现每次打开新会话都得把项目背景、代码风格、构建命令重新讲一遍。对话稍微长一点模型就开始“选择性记忆”早先交代的约束慢慢就丢了。写出来的代码风格漂移得厉害一会儿用单引号一会儿用双引号常量命名也不统一。后来我花了一整天时间把claude-code-templates这套模板体系搭起来把能固化的上下文全部塞进配置文件里再跑业务项目时那种“每次都要重新调教AI”的疲惫感才算真正消失。这篇文章我打算把搭建模板这件事拆开讲清楚哪些文件是核心每个配置项到底解决什么问题团队场景下模板怎么沉淀、怎么评审、怎么跟随项目演进。内容更偏向那些已经在用Claude Code、但对模板体系还处于“知道有这回事但没系统搭过”状态的开发者。1. 为什么裸跑的Claude Code越用越累先复盘一下最原始的裸跑状态。Claude Code本身能力并不弱终端语义理解、代码检索、多文件编辑这些基本功都在线。但它的工作模式是“每一次交互都是新的”没有长期记忆你在这个会话里告诉它的项目背景到下一个会话就归零了。这就带来三个很具体的问题。第一重复解释成本高。每次开新会话都要把“这是一个前后端分离的电商项目后端Go前端Vue3包管理器用的pnpm数据库表区域划分见docs的ER图”这段话重新粘贴一遍。听起来不费劲但一天开十个会话就是十遍。加上模型还会反问“这个目录是干嘛的”“测试用什么断言库”解释成本直接翻倍。第二上下文窗口被无效信息挤占。Claude Code有上下文窗口上限窗口越满模型越容易丢掉早期的关键指令。如果你每次都在花几百个token重复交代背景真正用来写代码、改代码的token就被压缩了。更尴尬的是交代到一半如果遇到长日志输出窗口直接顶满模型开始“失忆”把最前面定的规范全忘了。第三输出一致性差。没有模板约束时模型会按自己对“最佳实践”的理解来写代码。它今天觉得你项目应该用Error Boundary明天可能就给写成Try-Catch包裹。你要是没盯着代码风格就会一会儿一个样代码评审时全是这类被迫返工的问题。claude-code-templates解决的就是这三件事把项目常识固化成文件让AI在每次会话启动时自动加载替代你每次手动T骨重复交代。把个人偏好和团队规范写进全局配置让任何项目、任何同事跑出来的Claude Code行为都是整齐的。把高频操作改成快捷键位和自定义斜杠命令让日常操作用最短路径触发。我到现在依然认为模板不是“锦上添花”的配置美化而是把Claude Code从“临时助手”变成“长期协作者”的分水岭。1.1 模板体系里到底藏了哪几类文件claude-code-templates并不单指某一个文件而是一整套可以随项目分发、随环境加载的配置集合。按用途可以分为四类规则文件最核心的是CLAUDE.md用来写项目的结构性知识、开发约定、命令手册模型每次启动都会优先读它。环境配置通过settings.json实际路径叫.claude/settings.json控制运行时的默认行为比如模型选择、输出上限、权限白名单。快捷键配置通过.claude/keybindings.json把高频操作绑定为组合键省去每次打开命令面板手动翻找。自定义命令在.claude/commands/目录下放Markdown文件把复杂Prompt沉淀成斜杠命令比如/review就是写死的代码评审指令。这套结构的奇妙之处在于它支持分层覆盖。全局目录有一套默认模板项目目录里可以放更具体的覆盖配置子目录还能继续叠加。这就意味着你完全可以把“通用的开发规范”写在全局把“这个仓库特有的构建步骤”写在项目里互不干扰模型会自动合并读取。1.2 一套好模板要回答的三类问题搭建模板不是想到什么写什么我建议按照三个层级去组织内容。第一层是项目结构知识。这个项目是什么语言、什么框架、包管理器是什么、目录怎么组织、有没有代码生成器、测试怎么跑。这些是模型写对代码的基础不写清楚它就只能靠猜。第二层是个人或团队的开发偏好。缩进用几个空格、组件文件用PascalCase还是kebab-case、提交信息走哪个规范、注释写中文还是英文。这些是让代码保持文案风格一致的关键也是代码评审时最容易被挑刺的地方。第三层是行为约束。告诉模型哪些事可以自动做哪些事必须先征求确认再动手哪些目录绝对不要碰哪些文件修改后必须跑测试。这些是从“会用工具”到“放心用工具”的分水岭。有了这三个层级后面的配置才有方向不会东一句西一句地堆砌。2. CLAUDE.md把项目常识变成AI的长期记忆CLAUDE.md是整个模板体系的灵魂文件。它的加载规则很简单Claude Code启动时会自动读取一个全局的CLAUDE.md通常存放在主目录的.claude/下然后在当前工作目录逐级寻找项目级的CLAUDE.md从根目录到当前目录逐层合并加载。这么说可能有点抽象我举个例子。全局的CLAUDE.md里写的是我这几年跨项目沉淀下来的通用习惯比如“代码注释用中文但变量名必须用英文”“重构类改动一次只动一个模块不要跨文件乱改”“提交信息遵循Conventional Commits”。这些规则不论我打开哪个Git仓库都生效。项目级的CLAUDE.md则放到仓库根目录写的是这个仓库内部的东西服务启动命令是pnpm dev而不是npm start数据库迁移走prisma migrate dev模块结构按features/组织而不是pages/。这些信息换一个项目就不适用了必须跟着仓库走。子目录级的CLAUDE.md用得相对少但遇到大型Monorepo时特别有用。比如packages/worker/下可能就放一份里面写“这个子包只处理消息队列任务禁止引入HTTP框架”“队列命名统一带q.前缀”。这样模型进入子目录改代码时会自动加载这些更细的约束。2.1 优秀CLAUDE.md的写法分区块、给正反例、控制长度我见过很多失败的CLAUDE.md共同问题就两个要么是长篇散文读起来像一篇wiki要么是规则太抽象模型不知道该拿它怎么办。先说分区块。我的习惯是用##划分区域每个区域聚焦一个话题。这样模型在需要的时候可以精准检索到对应区块而不是把整个文件从头啃到尾。一个典型的项目级文件结构大概是## 项目概览 基于 Next.js 14 的官网内容站采用 App Router 目录结构。 内容以 MDX 形式存放在 src/content 下构建时静态生成。 ## 常用命令 - 启动开发服务pnpm dev - 类型检查pnpm typecheck - 单元测试pnpm vitest run - 构建静态产物pnpm build ## 目录约定 - src/app路由页面保持轻量逻辑抽到 src/components - src/componentsUI组件按页面模块分目录 - src/lib工具函数禁止放前端组件 - src/contentMDX内容文件不做数据库存储 ## 代码风格 - 组件一律使用函数组件和React Hooks不写class组件 - Props类型用interface声明后缀名统一加Props - 样式用Tailwind的原子类不写CSS Modules - 状态管理只使用Zustand未经过讨论不要引入Redux ## 禁止事项 - 不要修改 src/content 以外的MDX文件 - 不要自行引入新的依赖包需要加依赖先询问我 - 不要重命名已经存在的导出函数会造成线上引用断裂分段的好处是模型执行代码生成任务时主要会去看“目录约定”和“代码风格”执行命令行任务时会去看“常用命令”而不会因为整个文件太乱导致该看到的内容被挤掉。再说正反例。比如只写“变量命名要清晰”没用模型觉得自己的命名也挺清晰。要写就写具体的对比## 命名规范 - 变量名用语义化英文不要用缩写例如 articleCount 而不是 ac - 组件文件名用PascalCase例如 ProductCard.tsx - 工具函数名用camelCase例如 formatPrice() - 尽量不用 any 类型如果必须用需要写一行注释说明原因给正反例不是为了让模型死记硬背而是帮它建立“这个项目里什么叫作好代码”的基准线。模型对自然语言的理解力比我们想象中强你把范例给明白了它生成的代码会自觉往这个方向上靠。最后说长度控制。我自己有个不成文的约定全局CLAUDE.md控制在400行以内项目级控制在200行以内子目录级尽量控制在100行以内。因为模型每次读文件会消耗上下文窗口文件太长反而挤占它思考代码的余量。规则就写“必须遵守的”可写可不写的统统删掉。2.2 测试用例的写法也值得写进规则很多人写CLAUDE.md只关注代码生成不关注测试这是个遗憾。其实模型完全可以帮你补测试、修测试前提是你告诉它测试文件放在哪里、用什么工具链、往什么风格上靠。我在项目级文件里会专门加一段## 测试约定 - 测试文件与被测模块同目录放置命名为 xxx.test.ts - 使用 Vitest React Testing Library - 组件测试优先测行为不测实现细节 - mock数据统一放在 __fixtures__ 目录下 - 收到“测试挂了”的指令时先跑一遍单测定位崩溃点再修复禁止盲目重写写完这段之后Claude Code处理测试相关任务的正确率高了很多。它不再瞎猜测试框架也不会把mock散落得到处都是而是自动遵守目录习惯测试风格和团队其他人写的保持了同步。3. 模板中真正出效果的配置项规则文件解决了“AI懂不懂业务”的问题配置文件解决的是“AI怎么运行更顺手”的问题。这两者通常是搭配出现的。配置逻辑跟规则文件一样也是分层的主目录下放全局配置任何项目都生效项目仓库的.claude/目录里放项目专属配置只在这个仓库内生效。我通常会优先配置这几类参数。3.1 模型与运行时参数别让默认值拖后腿如果你在settings.json里写了模型选择模板启动时就会直接用你指定的模型而不是每次默认选一个。这个对钱包和效果的影响都很直接。我在CI或批量任务场景会选更便宜的快速模型在复杂重构场景会手动切到更强的长上下文模型。输出长度的设置也值得给尤其是遇到生成大型文件或长重构任务时默认值容易截断。我把输出上限调高之后模型一次性生成完整模块的概率大了不少中途截断需要二次拼接的情况少很多。温度这类参数在编程任务里建议别乱动代码生成场景下低温度更稳定。我见过有人把温度调到1.0想让模型“更有创造力”结果写出来的代码能跑但风格极其诡异改起来更费劲。编程不是写诗稳定优先。3.2 权限与执行范围先收得住再放得开权限配置是很多人会忽略的一层。默认情况下Claude Code能读项目里的文件、能执行命令这对日常使用没问题。但在敏感场景里比如生产环境配置文件、密钥存放目录、自动部署脚本我会在配置里显式加上黑名单{ permissions: { deny: [ Read:src/config/prod.env, Edit:.env*, Bash:rm -rf .*, Bash:git push --force ], allow: [ Edit:src/**, Bash:pnpm dev, Bash:pnpm test ] } }这套配置的意义不是限制AI的能力而是防止手滑。终端操作有时候就是一瞬间的事模型执行力越强越需要一个能兜底的护栏。我宁可多写几条deny规则也不愿意在半夜收到线上事故的告警。另外还建议打开写文件前的确认模式至少让模型在编辑超过5个文件的批量改动前先列出变更清单。这种习惯不能说完全杜绝误操作但确实能拦住大多数低级的批量错误。3.3 快捷键位把高频操作绑成肌肉记忆Claude Code的快捷键位体系支持你自定义热键把常用的斜杠命令或者操作绑到顺手的位置。这个功能表面看只是少打几个字实际影响很大——操作路径短了你会更愿意频繁使用那些“应该频繁执行”的检查动作。我自己常驻的几个绑定CtrlJ调出“代码评审”命令生成当前文件的审查清单。CtrlT跑当前模块的单测快速拿结果。CtrlL让AI打开目录结构概览重新梳理文件布局。CtrlK清空上下文中的日志输出保留主线任务上下文。按键映射记录在.claude/keybindings.json里格式比较直观改起来也没什么学习成本。其实快捷键位更多是个人习惯问题没有标准答案。但你只要花十分钟把常用的三五个动作绑上去后面每天省下来的时间是非常可观的属于低投入高回报的配置项。3.4 自定义斜杠命令把复杂Prompt沉淀成一条指令斜杠命令是我第二喜欢的功能。它可以把一段经常重复使用的Prompt变成一个斜杠指令比如敲/review就好不用再次粘贴那段1000字的“按常规标准审查代码”的要求。命令文件放在.claude/commands/下每个命令一个Markdown文件文件名就是指令名。举一个我一直在用的代码评审命令--- description: 对当前选中的文件执行设计评审 argument-hint: 可选聚焦某模块 --- 对当前打开的代码文件做一次深度评审重点检查以下几方面 1. 可读性命名是否语义化函数是否有单一职责 2. 健壮性边界条件是否处理空值是否兜底异步流程是否遗漏 3. 性能是否存在重复计算、不必要渲染或请求、N1查询 4. 一致性是否与项目中现有模块的实现方式保持一致 5. 测试关键逻辑是否缺测试用例边界分支是否未覆盖 输出格式 - 按严重程度分级阻塞、建议、可忽略 - 每一条意见附带文件路径和具体行号范围 - 结尾给出“是否建议立即修改”的结论 如果用户指定了聚焦模块则重点检查该部分其余部分简要带过。这套命令我用了很久核心价值在于“把专业经验固化到了模板里”。你不需要每次口头组织评审标准只需要一个斜杠命令AI就会按同一条标准线执行。新同事加入项目只要拿到了这套命令文件他跑出来的评审质量也不会差太多。其他同理你可以把“生成提交信息”“补充接口文档”“重构当前组件并保持行为一致性”这些高频复杂任务都做成命令。做的时候注意一点命令文件里尽量写清楚输入和输出格式避免模型自由发挥。4. 把templates变成团队资产模板这东西单人使用是提升效率多人协同时就成了统一基线的工具。团队里如果有十个人都在用Claude Code每个人都按自己的习惯写一套配置那协作起来还是各写各的反而不如不用。我在带团队落地时走的路线是先在配置层面统一基线再在流程层面把模板纳入代码评审和项目脚手架。4.1 模板的版本管理模板本身也要进Git第一件事把模板放入版本管理。建议的做法是在仓库里开一个独立的目录比如ops/claude-templates/把所有配置和命令文件收进去。这样每次修改都有记录出问题可以回滚新人加入时直接跑一条复制命令就能把整套模板装进本地。同时要让模型也读得到这份模板。我的做法是在项目级CLAUDE.md里加一节“本仓库的AI协作规范”在规范里声明“模板位于 ops/claude-templates 目录如果涉及修改AI协作规则请同步更新对应模板文件”。这样AI在改业务代码时如果触发了规则层面变更它会主动提醒我模板是否需要同步更新。版本管理最大的收益不是备份而是形成了“模板演进史”。每一次删掉的规则、改过的命令事后都能查到当时是出于什么原因调整的。团队讨论模板改动时也有了实物可以依托而不是“我记得之前好像不是这样”。4.2 把模板写进代码评审的Checklist代码评审里加一个专门的AI协作项。评审人员在检查变更时除了业务逻辑还需要看三件事变更是否绕过了CLAUDE.md里声明的目录/命名/依赖规则是否引入了仓库中不存在的依赖框架且未同步更新规则文件是否有高频操作本可以固化成命令/快捷键却被写成了重复的注释或文档这看起来像是在“管代码细节”实际作用是防止规则文件与实践脱节。规则如果长时间没人用慢慢就变成废纸了。反过来开发者在Review中高频引用规则也会反向倒逼规则文件的表达更清晰。还有一点代码评审时建议跑一遍/review斜杠命令把AI生成的审查报告当成人肉评审的补充视角。AI看代码的“覆盖面”和人不太一样它可能不会揪着业务逻辑不放但对命名一致性、边界条件、潜在空值这些点的敏感度很高。两条线合并效果通常比单纯代码评审要好。4.3 将模板注入项目脚手架新项目起步是最容易抛弃模板的节点。因为项目都快初始化完了谁还有空去管AI怎么配置结果就是新仓库没有全局模板新同事入职第一个项目的体验又变成“裸跑Claude Code”。解决方法是把模板打进脚手架。我这边的新项目都从一个内部项目模板初始化模板自带.claude/目录里面直接放着最基础的配置默认模型与权限白名单一份标准的项目级CLAUDE.md只有框架信息和常用命令留出填充业务细节的位置基础的Git提交信息命令文件这样新项目一出生就自带AI协作的初始基线后面的业务规则只需要增量补充不需要从零写起。我一直觉得模板的生命力不在于“写一次”而在于“长出来”脚手架提供的那个初始版本就是种子后续跟着项目一起生长。5. 实战下来最值得记住的几条经验最后这部分我不打算罗列功能清单只讲几条实操下来对我影响最深的体会。有些是正面收益有些是踩过坑之后换来的教训。第一模板必须随项目演进持续维护。项目改目录结构了、换了ORM框架、新增了测试工具链这些都要同步改CLAUDE.md。最怕的不是规则被删掉而是规则文件还留着但已经过时了。过期规则比没有规则更坑——模型会严格按过时规则执行产出一堆报废代码。我给自己定的规矩是每次项目发生结构性变更先把更新CLAUDE.md当作任务的一部分完成。第二权限配置先收紧逐步放开。我一开始把权限配置写得很宽松觉得放开了AI才能干活快。结果在某个深夜模型一条命令把我整个构建目录清掉了。现在我的配置原则是默认只放行常规操作涉及删除、强推、生产环境修改的操作一律先询问。宁可稍微多一次确认也不去赌那个万一。第三模板不是控制AI的锁链而是降低沟通成本的共同语言。有同事刚开始会抵触觉得“写模板就是给AI上枷锁自己写代码还要被它管着”。实际跑几周之后就会发现模板更像是项目团队的手册。新人上手看模板比翻几个月前的聊天记录高效得多AI生成的代码也少了很多“常识性错误”整体认知负载是下降的。第四上下文管理靠模板更靠意识。模板能减少重复解释但会话内上下文还是要自己盯。日志输出太多、模型扯远了、跟当前任务无关的文件被翻出来这些还是会占用窗口。我会定期用系统提示让AI总结当前进展并清理无关内容这个习惯比任何配置文件都管用。回头来看搭建claude-code-templates这件事最值钱的地方不在于某个具体功能而是逼着我把大量隐性的项目常识和个人偏好变成了显性的、可管理的文本资产。模板这个东西值得每个认真用Claude Code的开发者好好搭一遍后续维护的收益会持续放大。
Claude Code模板配置指南：告别重复调教，打造长期AI协作助手
先说一个我自己的直观感受Claude Code这玩意儿裸跑和配置好模板之后完全像是两个产品。最早我把Claude Code装进终端就直接开用了结果发现每次打开新会话都得把项目背景、代码风格、构建命令重新讲一遍。对话稍微长一点模型就开始“选择性记忆”早先交代的约束慢慢就丢了。写出来的代码风格漂移得厉害一会儿用单引号一会儿用双引号常量命名也不统一。后来我花了一整天时间把claude-code-templates这套模板体系搭起来把能固化的上下文全部塞进配置文件里再跑业务项目时那种“每次都要重新调教AI”的疲惫感才算真正消失。这篇文章我打算把搭建模板这件事拆开讲清楚哪些文件是核心每个配置项到底解决什么问题团队场景下模板怎么沉淀、怎么评审、怎么跟随项目演进。内容更偏向那些已经在用Claude Code、但对模板体系还处于“知道有这回事但没系统搭过”状态的开发者。1. 为什么裸跑的Claude Code越用越累先复盘一下最原始的裸跑状态。Claude Code本身能力并不弱终端语义理解、代码检索、多文件编辑这些基本功都在线。但它的工作模式是“每一次交互都是新的”没有长期记忆你在这个会话里告诉它的项目背景到下一个会话就归零了。这就带来三个很具体的问题。第一重复解释成本高。每次开新会话都要把“这是一个前后端分离的电商项目后端Go前端Vue3包管理器用的pnpm数据库表区域划分见docs的ER图”这段话重新粘贴一遍。听起来不费劲但一天开十个会话就是十遍。加上模型还会反问“这个目录是干嘛的”“测试用什么断言库”解释成本直接翻倍。第二上下文窗口被无效信息挤占。Claude Code有上下文窗口上限窗口越满模型越容易丢掉早期的关键指令。如果你每次都在花几百个token重复交代背景真正用来写代码、改代码的token就被压缩了。更尴尬的是交代到一半如果遇到长日志输出窗口直接顶满模型开始“失忆”把最前面定的规范全忘了。第三输出一致性差。没有模板约束时模型会按自己对“最佳实践”的理解来写代码。它今天觉得你项目应该用Error Boundary明天可能就给写成Try-Catch包裹。你要是没盯着代码风格就会一会儿一个样代码评审时全是这类被迫返工的问题。claude-code-templates解决的就是这三件事把项目常识固化成文件让AI在每次会话启动时自动加载替代你每次手动T骨重复交代。把个人偏好和团队规范写进全局配置让任何项目、任何同事跑出来的Claude Code行为都是整齐的。把高频操作改成快捷键位和自定义斜杠命令让日常操作用最短路径触发。我到现在依然认为模板不是“锦上添花”的配置美化而是把Claude Code从“临时助手”变成“长期协作者”的分水岭。1.1 模板体系里到底藏了哪几类文件claude-code-templates并不单指某一个文件而是一整套可以随项目分发、随环境加载的配置集合。按用途可以分为四类规则文件最核心的是CLAUDE.md用来写项目的结构性知识、开发约定、命令手册模型每次启动都会优先读它。环境配置通过settings.json实际路径叫.claude/settings.json控制运行时的默认行为比如模型选择、输出上限、权限白名单。快捷键配置通过.claude/keybindings.json把高频操作绑定为组合键省去每次打开命令面板手动翻找。自定义命令在.claude/commands/目录下放Markdown文件把复杂Prompt沉淀成斜杠命令比如/review就是写死的代码评审指令。这套结构的奇妙之处在于它支持分层覆盖。全局目录有一套默认模板项目目录里可以放更具体的覆盖配置子目录还能继续叠加。这就意味着你完全可以把“通用的开发规范”写在全局把“这个仓库特有的构建步骤”写在项目里互不干扰模型会自动合并读取。1.2 一套好模板要回答的三类问题搭建模板不是想到什么写什么我建议按照三个层级去组织内容。第一层是项目结构知识。这个项目是什么语言、什么框架、包管理器是什么、目录怎么组织、有没有代码生成器、测试怎么跑。这些是模型写对代码的基础不写清楚它就只能靠猜。第二层是个人或团队的开发偏好。缩进用几个空格、组件文件用PascalCase还是kebab-case、提交信息走哪个规范、注释写中文还是英文。这些是让代码保持文案风格一致的关键也是代码评审时最容易被挑刺的地方。第三层是行为约束。告诉模型哪些事可以自动做哪些事必须先征求确认再动手哪些目录绝对不要碰哪些文件修改后必须跑测试。这些是从“会用工具”到“放心用工具”的分水岭。有了这三个层级后面的配置才有方向不会东一句西一句地堆砌。2. CLAUDE.md把项目常识变成AI的长期记忆CLAUDE.md是整个模板体系的灵魂文件。它的加载规则很简单Claude Code启动时会自动读取一个全局的CLAUDE.md通常存放在主目录的.claude/下然后在当前工作目录逐级寻找项目级的CLAUDE.md从根目录到当前目录逐层合并加载。这么说可能有点抽象我举个例子。全局的CLAUDE.md里写的是我这几年跨项目沉淀下来的通用习惯比如“代码注释用中文但变量名必须用英文”“重构类改动一次只动一个模块不要跨文件乱改”“提交信息遵循Conventional Commits”。这些规则不论我打开哪个Git仓库都生效。项目级的CLAUDE.md则放到仓库根目录写的是这个仓库内部的东西服务启动命令是pnpm dev而不是npm start数据库迁移走prisma migrate dev模块结构按features/组织而不是pages/。这些信息换一个项目就不适用了必须跟着仓库走。子目录级的CLAUDE.md用得相对少但遇到大型Monorepo时特别有用。比如packages/worker/下可能就放一份里面写“这个子包只处理消息队列任务禁止引入HTTP框架”“队列命名统一带q.前缀”。这样模型进入子目录改代码时会自动加载这些更细的约束。2.1 优秀CLAUDE.md的写法分区块、给正反例、控制长度我见过很多失败的CLAUDE.md共同问题就两个要么是长篇散文读起来像一篇wiki要么是规则太抽象模型不知道该拿它怎么办。先说分区块。我的习惯是用##划分区域每个区域聚焦一个话题。这样模型在需要的时候可以精准检索到对应区块而不是把整个文件从头啃到尾。一个典型的项目级文件结构大概是## 项目概览 基于 Next.js 14 的官网内容站采用 App Router 目录结构。 内容以 MDX 形式存放在 src/content 下构建时静态生成。 ## 常用命令 - 启动开发服务pnpm dev - 类型检查pnpm typecheck - 单元测试pnpm vitest run - 构建静态产物pnpm build ## 目录约定 - src/app路由页面保持轻量逻辑抽到 src/components - src/componentsUI组件按页面模块分目录 - src/lib工具函数禁止放前端组件 - src/contentMDX内容文件不做数据库存储 ## 代码风格 - 组件一律使用函数组件和React Hooks不写class组件 - Props类型用interface声明后缀名统一加Props - 样式用Tailwind的原子类不写CSS Modules - 状态管理只使用Zustand未经过讨论不要引入Redux ## 禁止事项 - 不要修改 src/content 以外的MDX文件 - 不要自行引入新的依赖包需要加依赖先询问我 - 不要重命名已经存在的导出函数会造成线上引用断裂分段的好处是模型执行代码生成任务时主要会去看“目录约定”和“代码风格”执行命令行任务时会去看“常用命令”而不会因为整个文件太乱导致该看到的内容被挤掉。再说正反例。比如只写“变量命名要清晰”没用模型觉得自己的命名也挺清晰。要写就写具体的对比## 命名规范 - 变量名用语义化英文不要用缩写例如 articleCount 而不是 ac - 组件文件名用PascalCase例如 ProductCard.tsx - 工具函数名用camelCase例如 formatPrice() - 尽量不用 any 类型如果必须用需要写一行注释说明原因给正反例不是为了让模型死记硬背而是帮它建立“这个项目里什么叫作好代码”的基准线。模型对自然语言的理解力比我们想象中强你把范例给明白了它生成的代码会自觉往这个方向上靠。最后说长度控制。我自己有个不成文的约定全局CLAUDE.md控制在400行以内项目级控制在200行以内子目录级尽量控制在100行以内。因为模型每次读文件会消耗上下文窗口文件太长反而挤占它思考代码的余量。规则就写“必须遵守的”可写可不写的统统删掉。2.2 测试用例的写法也值得写进规则很多人写CLAUDE.md只关注代码生成不关注测试这是个遗憾。其实模型完全可以帮你补测试、修测试前提是你告诉它测试文件放在哪里、用什么工具链、往什么风格上靠。我在项目级文件里会专门加一段## 测试约定 - 测试文件与被测模块同目录放置命名为 xxx.test.ts - 使用 Vitest React Testing Library - 组件测试优先测行为不测实现细节 - mock数据统一放在 __fixtures__ 目录下 - 收到“测试挂了”的指令时先跑一遍单测定位崩溃点再修复禁止盲目重写写完这段之后Claude Code处理测试相关任务的正确率高了很多。它不再瞎猜测试框架也不会把mock散落得到处都是而是自动遵守目录习惯测试风格和团队其他人写的保持了同步。3. 模板中真正出效果的配置项规则文件解决了“AI懂不懂业务”的问题配置文件解决的是“AI怎么运行更顺手”的问题。这两者通常是搭配出现的。配置逻辑跟规则文件一样也是分层的主目录下放全局配置任何项目都生效项目仓库的.claude/目录里放项目专属配置只在这个仓库内生效。我通常会优先配置这几类参数。3.1 模型与运行时参数别让默认值拖后腿如果你在settings.json里写了模型选择模板启动时就会直接用你指定的模型而不是每次默认选一个。这个对钱包和效果的影响都很直接。我在CI或批量任务场景会选更便宜的快速模型在复杂重构场景会手动切到更强的长上下文模型。输出长度的设置也值得给尤其是遇到生成大型文件或长重构任务时默认值容易截断。我把输出上限调高之后模型一次性生成完整模块的概率大了不少中途截断需要二次拼接的情况少很多。温度这类参数在编程任务里建议别乱动代码生成场景下低温度更稳定。我见过有人把温度调到1.0想让模型“更有创造力”结果写出来的代码能跑但风格极其诡异改起来更费劲。编程不是写诗稳定优先。3.2 权限与执行范围先收得住再放得开权限配置是很多人会忽略的一层。默认情况下Claude Code能读项目里的文件、能执行命令这对日常使用没问题。但在敏感场景里比如生产环境配置文件、密钥存放目录、自动部署脚本我会在配置里显式加上黑名单{ permissions: { deny: [ Read:src/config/prod.env, Edit:.env*, Bash:rm -rf .*, Bash:git push --force ], allow: [ Edit:src/**, Bash:pnpm dev, Bash:pnpm test ] } }这套配置的意义不是限制AI的能力而是防止手滑。终端操作有时候就是一瞬间的事模型执行力越强越需要一个能兜底的护栏。我宁可多写几条deny规则也不愿意在半夜收到线上事故的告警。另外还建议打开写文件前的确认模式至少让模型在编辑超过5个文件的批量改动前先列出变更清单。这种习惯不能说完全杜绝误操作但确实能拦住大多数低级的批量错误。3.3 快捷键位把高频操作绑成肌肉记忆Claude Code的快捷键位体系支持你自定义热键把常用的斜杠命令或者操作绑到顺手的位置。这个功能表面看只是少打几个字实际影响很大——操作路径短了你会更愿意频繁使用那些“应该频繁执行”的检查动作。我自己常驻的几个绑定CtrlJ调出“代码评审”命令生成当前文件的审查清单。CtrlT跑当前模块的单测快速拿结果。CtrlL让AI打开目录结构概览重新梳理文件布局。CtrlK清空上下文中的日志输出保留主线任务上下文。按键映射记录在.claude/keybindings.json里格式比较直观改起来也没什么学习成本。其实快捷键位更多是个人习惯问题没有标准答案。但你只要花十分钟把常用的三五个动作绑上去后面每天省下来的时间是非常可观的属于低投入高回报的配置项。3.4 自定义斜杠命令把复杂Prompt沉淀成一条指令斜杠命令是我第二喜欢的功能。它可以把一段经常重复使用的Prompt变成一个斜杠指令比如敲/review就好不用再次粘贴那段1000字的“按常规标准审查代码”的要求。命令文件放在.claude/commands/下每个命令一个Markdown文件文件名就是指令名。举一个我一直在用的代码评审命令--- description: 对当前选中的文件执行设计评审 argument-hint: 可选聚焦某模块 --- 对当前打开的代码文件做一次深度评审重点检查以下几方面 1. 可读性命名是否语义化函数是否有单一职责 2. 健壮性边界条件是否处理空值是否兜底异步流程是否遗漏 3. 性能是否存在重复计算、不必要渲染或请求、N1查询 4. 一致性是否与项目中现有模块的实现方式保持一致 5. 测试关键逻辑是否缺测试用例边界分支是否未覆盖 输出格式 - 按严重程度分级阻塞、建议、可忽略 - 每一条意见附带文件路径和具体行号范围 - 结尾给出“是否建议立即修改”的结论 如果用户指定了聚焦模块则重点检查该部分其余部分简要带过。这套命令我用了很久核心价值在于“把专业经验固化到了模板里”。你不需要每次口头组织评审标准只需要一个斜杠命令AI就会按同一条标准线执行。新同事加入项目只要拿到了这套命令文件他跑出来的评审质量也不会差太多。其他同理你可以把“生成提交信息”“补充接口文档”“重构当前组件并保持行为一致性”这些高频复杂任务都做成命令。做的时候注意一点命令文件里尽量写清楚输入和输出格式避免模型自由发挥。4. 把templates变成团队资产模板这东西单人使用是提升效率多人协同时就成了统一基线的工具。团队里如果有十个人都在用Claude Code每个人都按自己的习惯写一套配置那协作起来还是各写各的反而不如不用。我在带团队落地时走的路线是先在配置层面统一基线再在流程层面把模板纳入代码评审和项目脚手架。4.1 模板的版本管理模板本身也要进Git第一件事把模板放入版本管理。建议的做法是在仓库里开一个独立的目录比如ops/claude-templates/把所有配置和命令文件收进去。这样每次修改都有记录出问题可以回滚新人加入时直接跑一条复制命令就能把整套模板装进本地。同时要让模型也读得到这份模板。我的做法是在项目级CLAUDE.md里加一节“本仓库的AI协作规范”在规范里声明“模板位于 ops/claude-templates 目录如果涉及修改AI协作规则请同步更新对应模板文件”。这样AI在改业务代码时如果触发了规则层面变更它会主动提醒我模板是否需要同步更新。版本管理最大的收益不是备份而是形成了“模板演进史”。每一次删掉的规则、改过的命令事后都能查到当时是出于什么原因调整的。团队讨论模板改动时也有了实物可以依托而不是“我记得之前好像不是这样”。4.2 把模板写进代码评审的Checklist代码评审里加一个专门的AI协作项。评审人员在检查变更时除了业务逻辑还需要看三件事变更是否绕过了CLAUDE.md里声明的目录/命名/依赖规则是否引入了仓库中不存在的依赖框架且未同步更新规则文件是否有高频操作本可以固化成命令/快捷键却被写成了重复的注释或文档这看起来像是在“管代码细节”实际作用是防止规则文件与实践脱节。规则如果长时间没人用慢慢就变成废纸了。反过来开发者在Review中高频引用规则也会反向倒逼规则文件的表达更清晰。还有一点代码评审时建议跑一遍/review斜杠命令把AI生成的审查报告当成人肉评审的补充视角。AI看代码的“覆盖面”和人不太一样它可能不会揪着业务逻辑不放但对命名一致性、边界条件、潜在空值这些点的敏感度很高。两条线合并效果通常比单纯代码评审要好。4.3 将模板注入项目脚手架新项目起步是最容易抛弃模板的节点。因为项目都快初始化完了谁还有空去管AI怎么配置结果就是新仓库没有全局模板新同事入职第一个项目的体验又变成“裸跑Claude Code”。解决方法是把模板打进脚手架。我这边的新项目都从一个内部项目模板初始化模板自带.claude/目录里面直接放着最基础的配置默认模型与权限白名单一份标准的项目级CLAUDE.md只有框架信息和常用命令留出填充业务细节的位置基础的Git提交信息命令文件这样新项目一出生就自带AI协作的初始基线后面的业务规则只需要增量补充不需要从零写起。我一直觉得模板的生命力不在于“写一次”而在于“长出来”脚手架提供的那个初始版本就是种子后续跟着项目一起生长。5. 实战下来最值得记住的几条经验最后这部分我不打算罗列功能清单只讲几条实操下来对我影响最深的体会。有些是正面收益有些是踩过坑之后换来的教训。第一模板必须随项目演进持续维护。项目改目录结构了、换了ORM框架、新增了测试工具链这些都要同步改CLAUDE.md。最怕的不是规则被删掉而是规则文件还留着但已经过时了。过期规则比没有规则更坑——模型会严格按过时规则执行产出一堆报废代码。我给自己定的规矩是每次项目发生结构性变更先把更新CLAUDE.md当作任务的一部分完成。第二权限配置先收紧逐步放开。我一开始把权限配置写得很宽松觉得放开了AI才能干活快。结果在某个深夜模型一条命令把我整个构建目录清掉了。现在我的配置原则是默认只放行常规操作涉及删除、强推、生产环境修改的操作一律先询问。宁可稍微多一次确认也不去赌那个万一。第三模板不是控制AI的锁链而是降低沟通成本的共同语言。有同事刚开始会抵触觉得“写模板就是给AI上枷锁自己写代码还要被它管着”。实际跑几周之后就会发现模板更像是项目团队的手册。新人上手看模板比翻几个月前的聊天记录高效得多AI生成的代码也少了很多“常识性错误”整体认知负载是下降的。第四上下文管理靠模板更靠意识。模板能减少重复解释但会话内上下文还是要自己盯。日志输出太多、模型扯远了、跟当前任务无关的文件被翻出来这些还是会占用窗口。我会定期用系统提示让AI总结当前进展并清理无关内容这个习惯比任何配置文件都管用。回头来看搭建claude-code-templates这件事最值钱的地方不在于某个具体功能而是逼着我把大量隐性的项目常识和个人偏好变成了显性的、可管理的文本资产。模板这个东西值得每个认真用Claude Code的开发者好好搭一遍后续维护的收益会持续放大。
