很多人第一次用 Claude Code 都是直接开聊把需求一贴回车然后看着它在终端里自己折腾。试过几次就会发现它确实能干活但干活的方式完全取决于它当时“脑子里”的上下文。今天心情好就给你写好一点漏了几个关键约束它可能就顺着自己的思路跑偏了。我自己经历过几次“代码倒是生成了结果全要改”的尴尬之后才意识到问题不在模型本身而在我没有给它一份足够清晰的项目操作手册。这份操作手册就是 Claude Code 场景下所谓的 templates也就是模板。它不是什么花哨的插件而是一种把“你希望模型如何工作”固化成文本和规则文件的做法。核心载体就是 CLAUDE.md以及配套的指令集、任务流定义、代码风格约束甚至是一整套 Agent SDK 级别的模板工程。这篇文章我把自己的模板思路完整拆一遍从 CLAUDE.md 的基本骨架、分层设计到实操接入、问题排查和模板的自我迭代全部摊开来说。不管你是刚接触 claude-code还是已经在用但觉得不够顺手这套方法应该能帮你把“会写代码的助手”调教成“懂你项目规矩的队友”。1. 模板的本质不是提示词是给 AI 的一份项目操作手册先说清楚一个概念很多人把模板理解成“一段写得很长的提示词”这不对。提示词是一次性的你这次告诉它“用 Go 写注意错误处理”它下次可能就忘了。模板是持久化的上下文Claude Code 启动时会把关键规则自动加载进上下文窗口。它写的不是一条指令而是一套后台运行的“默认规矩”。你在项目里放了 CLAUDE.md模型干活之前就先看到这些规则然后才看需求、读代码、做改动。这两者的差别直接决定了输出的稳定性和一致性。1.1 模板到底要解决什么问题没有模板的时候Claude Code 的默认状态是什么我把一段需求丢进去它会自己判断要读哪些文件、用什么风格、做不做边界检查。这种“自主性”看似聪明但在真实工程里特别危险。举个例子有一次我让它帮我重构一个内部工具的错误处理逻辑需求写得很清楚“统一 error 格式加 context 信息”。它干完了代码能跑测试也过了。但我一 review 差点崩溃——它把所有错误信息都改成了英文因为我项目里有几条日志用了英文它把错误码的类型从字符串改成了自定义结构体理由是“更规范”。问题在于这个项目的既有约定是中文日志、字符串错误码、只在模块边界做错误转换。模型不知道这些约定只能猜。这一猜就是一场代码风格事故。模板要解决的就是这件事把项目里那些“大家都知道但没人写下来”的规矩变成模型启动时的必读内容。它约束的不只是“怎么写代码”还包括“哪些不要动”“哪些先确认再动手”“什么情况下要问人”。一个完整的模板体系能让你的 AI 助手从“什么都敢干”变成“知道边界和分寸”。1.2 Claude Code 模板的三大类型与选型思路在实操层面我通常把 Claude Code 的模板分成三个层次项目级规则模板核心是 CLAUDE.md放在项目根目录描述这个仓库的技术栈、目录结构、编码规范、测试要求和发布流程。这是最常用、最基础的一层。用户级偏好模板放在 ~/.claude/CLAUDE.md描述你个人的偏好比如“默认使用 TypeScript 编写可复用模块”“优先使用小写驼峰命名”等。它不属于某个项目而是跟随用户身份在所有项目中生效。Agent 模板 / SDK 模板偏工程化的模板。它不仅仅是文本规则而是通过 Claude Agent SDK 封装出可复用的任务执行单元包含工具定义、Prompt 模板、参数校验和输出格式适用于构建自动化流水线或多步 Agent 任务。这三层选型有一个基本原则能写进全局的不要写进项目能写进项目的不塞进 Agent。全局模板管你的个人习惯项目模板管仓库特有约束Agent 模板管超出一问一答范畴的自动化流程。如果全堆在一个文件里很快就会因为互相冲突而失效后面我会专门讲这一点。2. 一个可复用的 CLAUDE.md 模板骨架我最早写 CLAUDE.md 是从抄社区模板开始的但抄了几版都不太合用。核心问题是别人的模板太侧重“展示世界观”什么“你是资深工程师”开头我看了都想笑。后来我按实际需求重新设计把 CLAUDE.md 拆成了五个明确分区每个分区只干一件事。这套骨架目前我用在好几个项目里效果比较稳定。2.1 分区规划身份、指令、工作流、禁区一个相对完整的 CLAUDE.md 骨架长这样# CLAUDE.md ## 项目身份 - 项目名称internal-api - 技术栈Python 3.11, FastAPI, SQLAlchemy 2.x - 架构风格模块化单体按业务域分包 - 测试框架pytest httpx ## 编码规范 - 优先使用类型注解所有公共函数必须有 docstring - 错误处理统一使用模块级 AppError禁止直接抛 HTTPException - 日志统一使用 logging禁止 print 调试输出 - 新增接口必须附带 OpenAPI schema 校验 ## 工作流约束 - 执行一个任务前先列出你计划修改的文件清单 - 涉及数据库 schema 变更时必须先检查 migrations 目录 - 所有 Python 代码提交前必须通过 ruff 和 mypy 检查 - 遇到不确定的设计决策时列出两个选项并给出推荐等待确认 ## 安全与禁区 - 严禁删除或改写 migrations 目录中已标注 immutable 的文件 - 严禁在修改代码前直接执行测试套件先读测试文件了解既有行为 - 涉及 secrets 或密钥信息严禁写入代码和日志这五段看起来简单但每一个分区背后都有明确的考虑。拿“工作流约束”来说这不是在展示规范而是在纠正模型最常见的坏毛病上来就改代码从不先给计划。你给它一个“先列文件清单”的约束它每一次行动就多了一个关键步骤这个步骤能让你在它跑偏之前有机会喊停。2.2 为什么“禁区”比“推荐”更重要很多模板写作者有个误区把大量篇幅放在“你应该怎么做”上却忽略了“你绝对不能做什么”。实际上模型在开放生成中犯的严重错误大部分来自边界问题而不是能力不足。我吃过一次亏。有个项目里我让 Claude Code 帮忙优化数据库查询它的操作是把 SQLAlchemy 的 lazy load 改成 eager load。从技术上来说这个优化是对的。但它顺手改动了一个模型的 relationship 定义导致一个完全无关的模块的查询行为变化测试直接炸了。我对它发了半天脾气才想明白问题不在“优化方式”而在没有一个规则告诉它“relationship 定义属于共享模型层改动前必须单独说明确认”。从此以后我的每个模板里都单独划一块“禁区”列得越具体越好。与其写“请谨慎修改模型层”不如写“model/ 目录下任何字段变更视为 breaking change必须先提供影响分析”。AI 对“谨慎”的理解很抽象但对“先做影响分析再动手”的理解要具体得多。2.3 模板长度与加载成本的权衡CLAUDE.md 不是越长越好。我见过有人把整个团队的编码规约一万多字全文塞进去结果 Claude Code 每次启动都要先消化大段文本上下文空间被挤占真正干活的指令反而模糊了。我的经验是CLAUDE.md 控制在 60-80 行为佳超过 100 行就要考虑拆分了。超过这个体量时可以把详细规约放到 docs/ 目录下然后在 CLAUDE.md 里写一行“数据库 schema 变更规则见 docs/database_workflow.md改动前必须阅读”。这种“间接引用”的方式有效避免带着一堆常态用不上的文本进行推理。模板是给人用的也是给模型推理用的每个 token 都应该花在刀刃上。3. 实操接入项目级、用户级、Agent SDK 级三层玩法拆完了模板骨架接下来是落地。我把接入方式分成三层建议从项目级开始然后再逐步搭建用户级和 Agent 级。这层跟层之间是递进关系不需要一口气全部铺开。3.1 项目级接入让每个仓库自带规矩项目级接入是最直观的。在仓库根目录创建 CLAUDE.md按要求写好上面的内容Claude Code 会自动加载。唯一要注意的是路径管理。如果你用的是 monorepo至少有两种选择根目录放一份全局规则每个子包放自己的一组子规则。Claude Code 对 CLAUDE.md 的加载机制是支持分层覆盖的子目录下的规则优先级高于根目录。我之前在 monorepo 里踩过一个坑根目录的模板写了“统一使用 pnpm”但某个子包因为历史原因是 npm-only。模型看了根目录规则理所当然地跑 pnpm 装依赖。修复方案很简单在这个子包目录里单独放一份 CLAUDE.md注明“本包仅支持 npm所有安装和脚本执行使用 npm”优先级高于全局一次就解决了。注意项目级模板不是写一次就完事的。每当项目新增了特殊流程或约定记得回填到 CLAUDE.md让模板跟着项目演进。3.2 用户级接入个人偏好一次配置全局生效用户级模板放在~/.claude/CLAUDE.md适合放跨项目都成立的个人偏好。比如我自己写 Python 时要求所有输入参数必须显式声明类型禁止使用动态属性测试文件命名统一为 test_ 前缀。这些偏好不管在哪个项目都适用没必要每个项目重复声明。团队协作时这条还能避免一个尴尬场景A 同学和 B 同学都用 Claude Code但 A 的全局模板要求“代码提交前生成 changelog”B 的全局没有。如果项目级模板也没写清Claude Code 在 A 手里和 B 手里的表现会明显不一致。解决办法是项目级模板只写团队共同约定的硬性规矩个人偏好的部分留给用户级模板去定义。两者要有明确边界尽量避免在项目级写“我觉得”式的内容。3.3 Agent SDK 级模板把多步任务变成可复用流水线当你要处理的不是一个“给我写个函数”的交互式任务而是一条需要多轮执行的自动化流水线时文本模板就不够用了需要上 Claude Agent SDK。下面是我用 SDK 定义任务模板的示例from claude_agent_sdk import Agent, LLMConfig agent Agent( namecode_reviewer, configLLMConfig( modelclaude-3-7-sonnet-20250219, system_promptload_template(reviewer_prompt.md), ), context{ max_tokens: 8192, allowed_tools: [read_file, run_tests, list_dir], }, )这个模板解决的核心问题是每一次跑代码 review它都会按同样的标准动作执行——先读变更文件列表再运行相关测试最后输出带有风险等级的问题清单。不用模板直接用 API 调用当然也能做但格式大概率五花八门。模板通过 system_prompt 和工具的固定配置约束了行为边界让每次执行都保持同一种质量水位。实际使用时我会维护一个templates/目录按任务类型存reviewer_prompt.md、refactor_prompt.md、db_migration_prompt.md再写一个简单的 loader 按需加载。这种方式比在代码里堆字符串优雅得多也方便复用和版本管理。4. 常见问题与排查技巧实录模板写多了踩的坑也不少。这里整理几个最典型的问题附带我自己的排查思路和修复方案希望能帮你省点时间。4.1 模型就是不按模板干活怎么办这是最普遍的现象。你明明在 CLAUDE.md 里写了“所有 Python 代码提交前必须通过 mypy”它却总是生成完代码就停手理由是没有可用的 mypy 环境。我的排查顺序是先确认模板是否真的被加载。看会话开头的上下文记录确认 CLAUDE.md 被读入。如果加载正常但行为不听话检查模板措辞是否过于模糊。“请注重代码质量”基本等于没说。“所有公共函数必须有 docstring”才算可执行指令。如果指令足够明确还是失效那就是规则太多模型在长上下文中丢失了非关键约束。解决方法是对规则做优先级排序把最高优先级的写在文件最前面。模型对上下文头部内容的注意力显著高于中后部关键规矩必须前置。4.2 模板“肿胀”后的压减策略模板越写越长有很多现实原因项目复杂了规则自然多工程师流动有些规矩为了避免重复踩坑就固化进了模板。但模板一旦超限整体效果反而下降甚至因为约束互相牵扯模型连基础任务都开始犹豫。我压减模板时用了一个“饮鸩止渴”式的问题清单逐条过一遍这条规则在过去 30 天的会话中真正触发过几次如果一次都没有删除。这条规则描述的是“倾向”还是“硬性约束”如果是倾向考虑移到人脑层不需要写进模板。这条规则能不能合并到已有工具配置里比如“代码风格统一”直接用 ruff 配置表达比写在模板里更可靠。这样做完之后我的模板几乎瘦了一半。真正留下来的都是像“禁止修改 immutable migrations”这种删了就真会出事的规则。4.3 规则冲突时的优先级设计规则冲突在多个模板并存时极其致命。用户级模板要求“所有配置用环境变量”项目级模板却规定“本地开发使用 config.py 加载”模型会被两头拉扯产生不可预测的行为。我从这个问题开始给所有模板规则加了一个优先级编号规则。用数字前缀标注权重数字越小优先级越高## 规则优先级 [1] 安全与数据完整性规则最高优先级 [2] 项目架构约定 [3] 编码风格与工具链 [4] 个人偏好最低优先级可被项目覆盖同时我会把自己检查一遍不同层级模板之间是否有语义重叠。只要出现在两个模板里的同一类主题就强制统一口径或标注覆盖关系。与其让模型在冲突中猜不如直接告诉它哪个说了算。这里给一个很实用的技巧在子目录的规则里显式写“如与根目录 CLAUDE.md 冲突以本文件为准”。4.4 上下文窗口被模板吃满的问题最后是上下文管理。模板是常驻上下文一旦过大留给代码、文件内容和对话历史的 token 就变少模型的可工作记忆萎缩生成质量跟着下降。我目前的做法是主模板只保留绝对必要的规则碰到内容较长的专项流程就在主模板里留一个触发词。例如在主模板里写“执行数据库迁移时必须先读取 docs/db_migration_rules.md”。当模型确实开始处理数据库相关任务时才会去加载这个文档。按需加载比一次性全量注入要高效得多上下文空间压力大幅减少。5. 进阶玩法让模板自我进化模板不是静态文本。真正好用的模板应该像代码一样可以校验、可测试、可迭代。我坚持做三件事让模板体系始终保持活性。5.1 用脚本校验模板的完整性和一致性模板文件也是文件可以自动化检查。我写了一个简单的脚本校验 CLAUDE.md 是否包含所有必填关键字、是否有重复指令、是否超出预估 token 数。每次改动模板后跑一遍能省掉很多低级错误。# 简易模板校验 claude-check --require project_identity,code_style,workflow --max-lines 80# 核心检查逻辑示例 def verify_template(path: str, required_sections: list[str]) - None: text Path(path).read_text(encodingutf-8) missing [sec for sec in required_sections if sec not in text] if missing: raise ValueError(fMissing sections: {missing}) if len(text.splitlines()) 80: raise Warning(Template exceeds 80 lines)这套校验机制的价值在于规则变更不只是“改一段文本”而是经过和普通代码变更一样的规范和审查流程。你可以通过 CI 让模板变更也走 diff review避免退化。5.2 从失败模式反推模板更新模板更新最有价值的来源就是真实会话中模型的失败模式。每次调用 Claude Code 遇到一个需要反复纠正的行为我都会记下来复盘一句“如果模板里有哪条规则模型就不该犯这个错”然后把这条规则补进模板。举个例子之前我负责一个项目模板里只写了“新增接口必须附带 OpenAPI schema 校验”但没有规定异常处理逻辑。结果模型生成的接口在遇到数据库错误时直接吞掉异常返回空结果整个调用链的日志里一点错误痕迹都没有。我补了一条规则所有模块边界必须暴露足够错误上下文禁止捕获后静默忽略。从那以后类似问题再没出现过。这种“从失败中长出来的模板”通常比书面上设计的规则更贴合实际问题。因为每一条都对应一个真实事件不是拍脑袋编出来的。5.3 团队级模板也要走版本管理个人使用模板可以比较随意团队协作就不能只靠口头同步。模板变更直接影响所有人的使用体验必须纳入版本管理。我们的做法是模板文件集中在infra/claude_templates/变更走普通的 merge request 流程评审人需要对比变更内容与实际开发体验是否一致。每次有模型行为异常或开发流程调整我们会更新对应模板并留下变更记录说明“为什么这条规则被加进来”。这其实已经把模板当作代码来维护了。每次项目复盘的时候我习惯把“模型在哪里不符合预期”作为固定议题。这些真实案例就是下一版模板最可靠的素材来源。最后再说点我的体会我自己用 Claude Code 的时间不算短最大的转折点不是学会了某个高级用法而是开始认认真真维护模板体系。你给它一套清晰的规则它会还你一批可预测的产出你偷懒不写它就用大量无序的输出消耗你的时间和耐心。如果你现在刚开始用 claude-code我给的建议很直接别一上来就追求全套模板构架。先挑一个你最常被模型惹毛的问题写一条明确的规则放进 CLAUDE.md跑一周看效果。有效就坚持无效就调整。迭代十几轮之后你自然就积累出一套自己用着最顺手的模板库了。这个过程比抄别人的任何成品模板都值钱。
Claude Code 模板体系：从 CLAUDE.md 到 Agent SDK
很多人第一次用 Claude Code 都是直接开聊把需求一贴回车然后看着它在终端里自己折腾。试过几次就会发现它确实能干活但干活的方式完全取决于它当时“脑子里”的上下文。今天心情好就给你写好一点漏了几个关键约束它可能就顺着自己的思路跑偏了。我自己经历过几次“代码倒是生成了结果全要改”的尴尬之后才意识到问题不在模型本身而在我没有给它一份足够清晰的项目操作手册。这份操作手册就是 Claude Code 场景下所谓的 templates也就是模板。它不是什么花哨的插件而是一种把“你希望模型如何工作”固化成文本和规则文件的做法。核心载体就是 CLAUDE.md以及配套的指令集、任务流定义、代码风格约束甚至是一整套 Agent SDK 级别的模板工程。这篇文章我把自己的模板思路完整拆一遍从 CLAUDE.md 的基本骨架、分层设计到实操接入、问题排查和模板的自我迭代全部摊开来说。不管你是刚接触 claude-code还是已经在用但觉得不够顺手这套方法应该能帮你把“会写代码的助手”调教成“懂你项目规矩的队友”。1. 模板的本质不是提示词是给 AI 的一份项目操作手册先说清楚一个概念很多人把模板理解成“一段写得很长的提示词”这不对。提示词是一次性的你这次告诉它“用 Go 写注意错误处理”它下次可能就忘了。模板是持久化的上下文Claude Code 启动时会把关键规则自动加载进上下文窗口。它写的不是一条指令而是一套后台运行的“默认规矩”。你在项目里放了 CLAUDE.md模型干活之前就先看到这些规则然后才看需求、读代码、做改动。这两者的差别直接决定了输出的稳定性和一致性。1.1 模板到底要解决什么问题没有模板的时候Claude Code 的默认状态是什么我把一段需求丢进去它会自己判断要读哪些文件、用什么风格、做不做边界检查。这种“自主性”看似聪明但在真实工程里特别危险。举个例子有一次我让它帮我重构一个内部工具的错误处理逻辑需求写得很清楚“统一 error 格式加 context 信息”。它干完了代码能跑测试也过了。但我一 review 差点崩溃——它把所有错误信息都改成了英文因为我项目里有几条日志用了英文它把错误码的类型从字符串改成了自定义结构体理由是“更规范”。问题在于这个项目的既有约定是中文日志、字符串错误码、只在模块边界做错误转换。模型不知道这些约定只能猜。这一猜就是一场代码风格事故。模板要解决的就是这件事把项目里那些“大家都知道但没人写下来”的规矩变成模型启动时的必读内容。它约束的不只是“怎么写代码”还包括“哪些不要动”“哪些先确认再动手”“什么情况下要问人”。一个完整的模板体系能让你的 AI 助手从“什么都敢干”变成“知道边界和分寸”。1.2 Claude Code 模板的三大类型与选型思路在实操层面我通常把 Claude Code 的模板分成三个层次项目级规则模板核心是 CLAUDE.md放在项目根目录描述这个仓库的技术栈、目录结构、编码规范、测试要求和发布流程。这是最常用、最基础的一层。用户级偏好模板放在 ~/.claude/CLAUDE.md描述你个人的偏好比如“默认使用 TypeScript 编写可复用模块”“优先使用小写驼峰命名”等。它不属于某个项目而是跟随用户身份在所有项目中生效。Agent 模板 / SDK 模板偏工程化的模板。它不仅仅是文本规则而是通过 Claude Agent SDK 封装出可复用的任务执行单元包含工具定义、Prompt 模板、参数校验和输出格式适用于构建自动化流水线或多步 Agent 任务。这三层选型有一个基本原则能写进全局的不要写进项目能写进项目的不塞进 Agent。全局模板管你的个人习惯项目模板管仓库特有约束Agent 模板管超出一问一答范畴的自动化流程。如果全堆在一个文件里很快就会因为互相冲突而失效后面我会专门讲这一点。2. 一个可复用的 CLAUDE.md 模板骨架我最早写 CLAUDE.md 是从抄社区模板开始的但抄了几版都不太合用。核心问题是别人的模板太侧重“展示世界观”什么“你是资深工程师”开头我看了都想笑。后来我按实际需求重新设计把 CLAUDE.md 拆成了五个明确分区每个分区只干一件事。这套骨架目前我用在好几个项目里效果比较稳定。2.1 分区规划身份、指令、工作流、禁区一个相对完整的 CLAUDE.md 骨架长这样# CLAUDE.md ## 项目身份 - 项目名称internal-api - 技术栈Python 3.11, FastAPI, SQLAlchemy 2.x - 架构风格模块化单体按业务域分包 - 测试框架pytest httpx ## 编码规范 - 优先使用类型注解所有公共函数必须有 docstring - 错误处理统一使用模块级 AppError禁止直接抛 HTTPException - 日志统一使用 logging禁止 print 调试输出 - 新增接口必须附带 OpenAPI schema 校验 ## 工作流约束 - 执行一个任务前先列出你计划修改的文件清单 - 涉及数据库 schema 变更时必须先检查 migrations 目录 - 所有 Python 代码提交前必须通过 ruff 和 mypy 检查 - 遇到不确定的设计决策时列出两个选项并给出推荐等待确认 ## 安全与禁区 - 严禁删除或改写 migrations 目录中已标注 immutable 的文件 - 严禁在修改代码前直接执行测试套件先读测试文件了解既有行为 - 涉及 secrets 或密钥信息严禁写入代码和日志这五段看起来简单但每一个分区背后都有明确的考虑。拿“工作流约束”来说这不是在展示规范而是在纠正模型最常见的坏毛病上来就改代码从不先给计划。你给它一个“先列文件清单”的约束它每一次行动就多了一个关键步骤这个步骤能让你在它跑偏之前有机会喊停。2.2 为什么“禁区”比“推荐”更重要很多模板写作者有个误区把大量篇幅放在“你应该怎么做”上却忽略了“你绝对不能做什么”。实际上模型在开放生成中犯的严重错误大部分来自边界问题而不是能力不足。我吃过一次亏。有个项目里我让 Claude Code 帮忙优化数据库查询它的操作是把 SQLAlchemy 的 lazy load 改成 eager load。从技术上来说这个优化是对的。但它顺手改动了一个模型的 relationship 定义导致一个完全无关的模块的查询行为变化测试直接炸了。我对它发了半天脾气才想明白问题不在“优化方式”而在没有一个规则告诉它“relationship 定义属于共享模型层改动前必须单独说明确认”。从此以后我的每个模板里都单独划一块“禁区”列得越具体越好。与其写“请谨慎修改模型层”不如写“model/ 目录下任何字段变更视为 breaking change必须先提供影响分析”。AI 对“谨慎”的理解很抽象但对“先做影响分析再动手”的理解要具体得多。2.3 模板长度与加载成本的权衡CLAUDE.md 不是越长越好。我见过有人把整个团队的编码规约一万多字全文塞进去结果 Claude Code 每次启动都要先消化大段文本上下文空间被挤占真正干活的指令反而模糊了。我的经验是CLAUDE.md 控制在 60-80 行为佳超过 100 行就要考虑拆分了。超过这个体量时可以把详细规约放到 docs/ 目录下然后在 CLAUDE.md 里写一行“数据库 schema 变更规则见 docs/database_workflow.md改动前必须阅读”。这种“间接引用”的方式有效避免带着一堆常态用不上的文本进行推理。模板是给人用的也是给模型推理用的每个 token 都应该花在刀刃上。3. 实操接入项目级、用户级、Agent SDK 级三层玩法拆完了模板骨架接下来是落地。我把接入方式分成三层建议从项目级开始然后再逐步搭建用户级和 Agent 级。这层跟层之间是递进关系不需要一口气全部铺开。3.1 项目级接入让每个仓库自带规矩项目级接入是最直观的。在仓库根目录创建 CLAUDE.md按要求写好上面的内容Claude Code 会自动加载。唯一要注意的是路径管理。如果你用的是 monorepo至少有两种选择根目录放一份全局规则每个子包放自己的一组子规则。Claude Code 对 CLAUDE.md 的加载机制是支持分层覆盖的子目录下的规则优先级高于根目录。我之前在 monorepo 里踩过一个坑根目录的模板写了“统一使用 pnpm”但某个子包因为历史原因是 npm-only。模型看了根目录规则理所当然地跑 pnpm 装依赖。修复方案很简单在这个子包目录里单独放一份 CLAUDE.md注明“本包仅支持 npm所有安装和脚本执行使用 npm”优先级高于全局一次就解决了。注意项目级模板不是写一次就完事的。每当项目新增了特殊流程或约定记得回填到 CLAUDE.md让模板跟着项目演进。3.2 用户级接入个人偏好一次配置全局生效用户级模板放在~/.claude/CLAUDE.md适合放跨项目都成立的个人偏好。比如我自己写 Python 时要求所有输入参数必须显式声明类型禁止使用动态属性测试文件命名统一为 test_ 前缀。这些偏好不管在哪个项目都适用没必要每个项目重复声明。团队协作时这条还能避免一个尴尬场景A 同学和 B 同学都用 Claude Code但 A 的全局模板要求“代码提交前生成 changelog”B 的全局没有。如果项目级模板也没写清Claude Code 在 A 手里和 B 手里的表现会明显不一致。解决办法是项目级模板只写团队共同约定的硬性规矩个人偏好的部分留给用户级模板去定义。两者要有明确边界尽量避免在项目级写“我觉得”式的内容。3.3 Agent SDK 级模板把多步任务变成可复用流水线当你要处理的不是一个“给我写个函数”的交互式任务而是一条需要多轮执行的自动化流水线时文本模板就不够用了需要上 Claude Agent SDK。下面是我用 SDK 定义任务模板的示例from claude_agent_sdk import Agent, LLMConfig agent Agent( namecode_reviewer, configLLMConfig( modelclaude-3-7-sonnet-20250219, system_promptload_template(reviewer_prompt.md), ), context{ max_tokens: 8192, allowed_tools: [read_file, run_tests, list_dir], }, )这个模板解决的核心问题是每一次跑代码 review它都会按同样的标准动作执行——先读变更文件列表再运行相关测试最后输出带有风险等级的问题清单。不用模板直接用 API 调用当然也能做但格式大概率五花八门。模板通过 system_prompt 和工具的固定配置约束了行为边界让每次执行都保持同一种质量水位。实际使用时我会维护一个templates/目录按任务类型存reviewer_prompt.md、refactor_prompt.md、db_migration_prompt.md再写一个简单的 loader 按需加载。这种方式比在代码里堆字符串优雅得多也方便复用和版本管理。4. 常见问题与排查技巧实录模板写多了踩的坑也不少。这里整理几个最典型的问题附带我自己的排查思路和修复方案希望能帮你省点时间。4.1 模型就是不按模板干活怎么办这是最普遍的现象。你明明在 CLAUDE.md 里写了“所有 Python 代码提交前必须通过 mypy”它却总是生成完代码就停手理由是没有可用的 mypy 环境。我的排查顺序是先确认模板是否真的被加载。看会话开头的上下文记录确认 CLAUDE.md 被读入。如果加载正常但行为不听话检查模板措辞是否过于模糊。“请注重代码质量”基本等于没说。“所有公共函数必须有 docstring”才算可执行指令。如果指令足够明确还是失效那就是规则太多模型在长上下文中丢失了非关键约束。解决方法是对规则做优先级排序把最高优先级的写在文件最前面。模型对上下文头部内容的注意力显著高于中后部关键规矩必须前置。4.2 模板“肿胀”后的压减策略模板越写越长有很多现实原因项目复杂了规则自然多工程师流动有些规矩为了避免重复踩坑就固化进了模板。但模板一旦超限整体效果反而下降甚至因为约束互相牵扯模型连基础任务都开始犹豫。我压减模板时用了一个“饮鸩止渴”式的问题清单逐条过一遍这条规则在过去 30 天的会话中真正触发过几次如果一次都没有删除。这条规则描述的是“倾向”还是“硬性约束”如果是倾向考虑移到人脑层不需要写进模板。这条规则能不能合并到已有工具配置里比如“代码风格统一”直接用 ruff 配置表达比写在模板里更可靠。这样做完之后我的模板几乎瘦了一半。真正留下来的都是像“禁止修改 immutable migrations”这种删了就真会出事的规则。4.3 规则冲突时的优先级设计规则冲突在多个模板并存时极其致命。用户级模板要求“所有配置用环境变量”项目级模板却规定“本地开发使用 config.py 加载”模型会被两头拉扯产生不可预测的行为。我从这个问题开始给所有模板规则加了一个优先级编号规则。用数字前缀标注权重数字越小优先级越高## 规则优先级 [1] 安全与数据完整性规则最高优先级 [2] 项目架构约定 [3] 编码风格与工具链 [4] 个人偏好最低优先级可被项目覆盖同时我会把自己检查一遍不同层级模板之间是否有语义重叠。只要出现在两个模板里的同一类主题就强制统一口径或标注覆盖关系。与其让模型在冲突中猜不如直接告诉它哪个说了算。这里给一个很实用的技巧在子目录的规则里显式写“如与根目录 CLAUDE.md 冲突以本文件为准”。4.4 上下文窗口被模板吃满的问题最后是上下文管理。模板是常驻上下文一旦过大留给代码、文件内容和对话历史的 token 就变少模型的可工作记忆萎缩生成质量跟着下降。我目前的做法是主模板只保留绝对必要的规则碰到内容较长的专项流程就在主模板里留一个触发词。例如在主模板里写“执行数据库迁移时必须先读取 docs/db_migration_rules.md”。当模型确实开始处理数据库相关任务时才会去加载这个文档。按需加载比一次性全量注入要高效得多上下文空间压力大幅减少。5. 进阶玩法让模板自我进化模板不是静态文本。真正好用的模板应该像代码一样可以校验、可测试、可迭代。我坚持做三件事让模板体系始终保持活性。5.1 用脚本校验模板的完整性和一致性模板文件也是文件可以自动化检查。我写了一个简单的脚本校验 CLAUDE.md 是否包含所有必填关键字、是否有重复指令、是否超出预估 token 数。每次改动模板后跑一遍能省掉很多低级错误。# 简易模板校验 claude-check --require project_identity,code_style,workflow --max-lines 80# 核心检查逻辑示例 def verify_template(path: str, required_sections: list[str]) - None: text Path(path).read_text(encodingutf-8) missing [sec for sec in required_sections if sec not in text] if missing: raise ValueError(fMissing sections: {missing}) if len(text.splitlines()) 80: raise Warning(Template exceeds 80 lines)这套校验机制的价值在于规则变更不只是“改一段文本”而是经过和普通代码变更一样的规范和审查流程。你可以通过 CI 让模板变更也走 diff review避免退化。5.2 从失败模式反推模板更新模板更新最有价值的来源就是真实会话中模型的失败模式。每次调用 Claude Code 遇到一个需要反复纠正的行为我都会记下来复盘一句“如果模板里有哪条规则模型就不该犯这个错”然后把这条规则补进模板。举个例子之前我负责一个项目模板里只写了“新增接口必须附带 OpenAPI schema 校验”但没有规定异常处理逻辑。结果模型生成的接口在遇到数据库错误时直接吞掉异常返回空结果整个调用链的日志里一点错误痕迹都没有。我补了一条规则所有模块边界必须暴露足够错误上下文禁止捕获后静默忽略。从那以后类似问题再没出现过。这种“从失败中长出来的模板”通常比书面上设计的规则更贴合实际问题。因为每一条都对应一个真实事件不是拍脑袋编出来的。5.3 团队级模板也要走版本管理个人使用模板可以比较随意团队协作就不能只靠口头同步。模板变更直接影响所有人的使用体验必须纳入版本管理。我们的做法是模板文件集中在infra/claude_templates/变更走普通的 merge request 流程评审人需要对比变更内容与实际开发体验是否一致。每次有模型行为异常或开发流程调整我们会更新对应模板并留下变更记录说明“为什么这条规则被加进来”。这其实已经把模板当作代码来维护了。每次项目复盘的时候我习惯把“模型在哪里不符合预期”作为固定议题。这些真实案例就是下一版模板最可靠的素材来源。最后再说点我的体会我自己用 Claude Code 的时间不算短最大的转折点不是学会了某个高级用法而是开始认认真真维护模板体系。你给它一套清晰的规则它会还你一批可预测的产出你偷懒不写它就用大量无序的输出消耗你的时间和耐心。如果你现在刚开始用 claude-code我给的建议很直接别一上来就追求全套模板构架。先挑一个你最常被模型惹毛的问题写一条明确的规则放进 CLAUDE.md跑一周看效果。有效就坚持无效就调整。迭代十几轮之后你自然就积累出一套自己用着最顺手的模板库了。这个过程比抄别人的任何成品模板都值钱。
