企业官网建设流程全解析

我做 Claude Code 模板库这件事，起因其实特别朴素：同一个项目里的代码审查、模块重构、质量巡检，我每天都要对着终端重复输入差不多的指令，换汤不换药。最开始还能接受，觉得自己写 Prompt 写得挺溜，直到连续几天被同一个问题折腾——每次新开会话，模型都要重新理解一遍我的代码规范、目录结构、测试命令，输出质量忽高忽低，上下文一长就开始忘。后来我干脆把这一整套重复劳动沉淀成了claude-code-templates这个模板库，把高频操作变成可复用的命令、参数化模板和固定的执行流程。这篇文章就完整拆解一下这个模板库的设计思路、核心实现、踩过的坑，以及从无模板到有模板之后的一组真实对照数据，希望能给你一个可以直接照抄的参考。

模板这个东西，说白了就是给 Claude Code 这类命令行 Agent 编程工具用的"干活的规矩"。它的价值不是让你少打字，而是让模型把你最熟悉的业务动作，从"每次都要重新解释一遍"变成"调用一次就按标准流程走"，把那些靠临场发挥解决不了的问题，变成靠流程设计解决掉。不管你是个人开发者在自己的仓库里折腾，还是团队想统一 Agent 协作的规范，这套模板库的思路都能用。

1. 从"重复说明"到"一键复用"：模板要解决的真实问题

1.1 Claude Code 给编程工作流带来了什么

Claude Code 本质上是一个跑在终端里的编程助手，它可以读你仓库里的文件、改代码、执行命令、跑测试，甚至自己完成 git 提交。跟直接在对话里贴代码问问题不一样，它能直接操作整个项目。听起来很强大，但这也带来一个新问题：你没法用一句"帮我重构一下 payment 模块"就完事，因为它的上下文再大，也不了解你项目里的全部背景。你需要在每次会话开始时，把大量背景知识塞给它，否则它就按通用套路来，产出离项目实际情况很远。

我最早就是这么用的：每次开会话，先写一段很长的背景说明，再描述任务。短任务还好，任务一复杂就崩，崩得最狠的时候是它改完代码直接告诉我"改好了"，我一看，测试全红，还把别的模块给碰坏了。当时我就意识到，问题不在模型能力，而在我给的指令太过自由，缺少结构化的约束。

1.2 没有模板的时候，一段典型的浪费场景

举一个很有代表性的场景，我之前在一个内部项目里做数据迁移，涉及一个 8000 多行的 Python 模块，里面全是手写 SQL 拼接和旧 API 调用，准备重构到新的 DB 访问层。没有模板的流程是这样的：

• 第一轮对话，我花十分钟写背景，告诉它项目结构、模块位置、测试命令、重构目标；
• 第二轮，它给出一个大而全的重构方案，覆盖十几个文件；
• 第三轮，我发现方案里有一半不符合项目现有约定，需要逐条解释；
• 第四轮，它开始改代码，改到一半上下文被撑爆，忘记最开始约定的边界条件；
• 第五轮，我重新补充背景，它重新理解，然后又在同一个问题上重复犯错。

整场下来，光是"让模型理解背景"就消耗了大量轮次和 token，真正干活的时间反而没多少。更麻烦的是，同样这个重构任务，隔一周再执行，过程完全不具可复现性，上次总结出来的经验教训全丢光了。于是我开始琢磨：能不能把背景信息、执行步骤、约束条件、输出格式这些固定不变的部分，抽出来做成模板，每次调用时只需传入具体目标模块，其余都是自动化的。

1.3 模板的本质：把稳定流程和变化内容切干净

做模板库之前，我一直以为模板就是"写得更好的 Prompt"，做完了才发现它其实是一次工作流拆解。真正有价值的模板，不是把话说得多漂亮，而是把整个任务拆成两块：

• 稳定不变的部分：代码规范、测试命令、评审标准、目录结构、安全注意点、报告格式。这一块放模板里，写一次永远生效，100% 稳定。
• 变化的部分：本次要处理的具体模块、要迁移的具体接口、要修的 bug 编号。这一块通过参数注入模板。

这个拆分逻辑，决定了模板的通用性。稳定部分写得多，覆盖面就广，但代价是模板内容长、占用上下文多；变化部分设计得好，单个模板可以适配各种任务，不用每个任务单独新建模板。我在这套模板库里的原则是：稳定部分只写跨项目通用的方法论，项目专属信息放进CLAUDE.md或者通过变量注入，模板本身保持纯净。

2. 模板库的顶层设计：目录、命名与职责边界

2.1 目录结构：让模板像工具库一样好检索

我在仓库里用的结构是这样的：

claude-code-templates/ ├── templates/ │ ├── source/ │ │ ├── review.md │ │ ├── refactor.md │ │ ├── design.md │ │ ├── audit.md │ │ └── migrate.md │ └── variables.yaml ├── scripts/ │ └── render_templates.py ├── .claude/ │ └── commands/ │ ├── review.md │ ├── refactor.md │ ├── design.md │ ├── audit.md │ └── migrate.md ├── tests/ │ └── golden_samples/ └── README.md

templates/source是源文件，里面允许存在{{ 变量 }}，方便参数化。scripts/render_templates.py负责渲染，把变量替换后生成到.claude/commands，这样 Claude Code 就能直接把这些文件当作斜杠命令调用。之所以搞两层而不是直接编辑commands目录，是因为源文件可以被变量控制，不同项目渲染出不同版本的命令，但源文件只有一份，便于维护。

tests/golden_samples是回归样本集，这个后面单独说。如果你不做变量渲染，直接把写好的 Markdown 文件扔到.claude/commands也能用，少一层反而更轻量。严格来说，这两套方案没有绝对优劣，看你是个人用还是团队用。

2.2 命名与版本管理：模板也要能追溯

模板命名我统一用的是"动词 + 对象"的格式：review（评审）、refactor（重构）、design（方案设计）、audit（巡检）、migrate（迁移）。这套命名的好处是，命令语义清晰，调用时看到斜杠命令就知道是干什么的，不会出现v2_final这种灾难。

模板的版本管理走的是 git。每当我们调整一个模板的执行步骤或约束条件，这个改动本身要像代码一样被 review、留痕、可回滚。用模板的时候最怕一种情况：团队里有人私下改了自己的本地模板，跑出来的效果跟其他人完全不一样，这其实已经不是在用模板，而是在开盲盒。版本管理解决的正是这个问题，所有变更集中到一个仓库，大家 clone 同一份，各自的差异只通过变量配置体现。

2.3 模板文件里的公共骨架

我观察到一个现象：好的模板和差的模板，在文件结构上差别非常明显。差的模板是一大段散文式描述，好的模板一定是有明确骨架的。我用的公共骨架是五段式：

1. 角色与目标：让模型明确自己此时扮演什么角色、这项任务的最终验收标准是什么；
2. 输入参数：列出本次任务需要传入的变量，比如目标模块路径、测试命令、分支名；
3. 执行步骤：按顺序排列的、可执行的步骤清单，每一步都要有明确产出；
4. 硬性约束：模型绝对不能做的事，比如"不要跨文件修改""不要自动安装依赖"；
5. 输出格式：规定最终交付物的格式，比如评审报告要有表格、重构要有每步的 diff 摘要。

这套骨架的价值在于：它把自由发挥的空间压缩到执行细节上，把方向、边界、交付标准都锁定死。模型再笨，按照这个骨架执行，产出也不会跑太偏；如果骨架本身设计得有问题，那也是可修正的，不会像自由对话那样每次都是全新的混乱。

3. 五个高频场景模板的完整实现

3.1 变更评审模板 /review：先判断影响面，再动代码

代码评审是我用得最多的场景。它最大的痛点是模型经常拿到一行 diff 就埋头找毛病，忽略整体影响面。我设计的review模板强制执行三段式：

# 变更评审 /review ## 角色与目标 你是一名资深代码评审员。你的目标是对当前已有的变更进行完整、客观、可执行的评审，而不是替开发者重写代码。 ## 输入 - 变更范围：{{ change_scope }}（默认当前分支相对 {{ default_branch }} 的差异） - 评审深度：{{ review_depth }}（可选：quick / medium / deep，默认 medium） ## 执行步骤 1. 先读取变更范围内的文件清单和整体 diff，输出"影响面分析"： - 变更涉及哪些文件； - 是否有对外接口、数据结构、公共依赖发生变更； - 是否有测试文件同时更新，如果没有，标注为风险点。 2. 再逐项检查具体问题，按以下优先级排列： - 安全相关：敏感信息、注入风险、越权访问、错误的认证判断； - 正确性：边界条件、空值处理、并发问题、异常捕获后是否吞掉错误； - 可维护性：命名、魔法数字、重复代码、死代码。 3. 输出评审结论。 ## 硬性约束 - 只做评审，不直接修改代码； - 每个问题都必须标注文件、行号、严重程度（P0/P1/P2）和具体建议； - 不确定的问题标注"待确认"，不要用猜测语气下结论。 ## 输出格式 ### 影响面分析 - 文件清单与影响范围简述 - 测试覆盖情况 ### 问题列表 | 严重程度 | 位置 | 问题描述 | 建议 | | P0 | xxx.py:42 | ... | ... | | P1 | xxx.py:78 | ... | ... | ### 结论 - 通过 / 需修改 / 需讨论 - 如需修改，列出最关键的 3 个问题

这个模板改过我四版，最初没有"影响面分析"这一步，模型上来就盯着具体代码找 bug，经常会抓住一个非关键变量命名说半天，真正影响上线安全的 P0 问题没发现。加了第一步之后，它先看全局再落细节，有效多了。另外，我不让它直接改代码，因为评审和修改这两个职责混在一起时，模型会倾向"这里不好，我帮你改掉"，一下子引入大量无关变更，评审结果完全失焦。

3.2 模块重构模板 /refactor：把大改动切成可回滚的小步

重构模板是我做完之后收益最大的一个。此前让模型重构模块，最怕的就是它一口气改十几个文件，改完全盘崩盘，连它自己都说不清楚哪一步引入的问题。所以这个模板的核心设计是"小步走、每步验证"：

# 模块重构 /refactor ## 角色与目标 你是本次重构的执行者。核心目标是：在不改变外部行为的前提下，完成指定模块的重构。外部行为是否保持，以测试命令是否通过为判断标准。 ## 输入 - 目标模块：{{ target_module }} - 测试命令：{{ test_command }}（默认 pytest -x -q） - 允许的行为变更：{{ behavior_changes }}（默认无） ## 执行步骤 1. 阅读目标模块全部代码，输出一份"现状地图"： - 模块内函数清单及职责； - 已识别的坏味道列表（重复代码、超长函数、全局状态、硬编码常量）； - 改动优先级排序。 2. 开始逐个小步重构，每步必须满足： - 单步改动不超过 200 行； - 每完成一步，立即执行测试命令； - 测试失败时，回退到上一步，绝不带着失败进入下一步。 3. 全部分完成以后，输出最终报告。 ## 硬性约束 - 禁止跨文件连锁修改。确需修改其他文件的，先列出依赖关系，单独用一次命令处理； - 禁止改动公共接口签名，除非 {{ behavior_changes }} 明确允许； - 禁止删除任何被测试覆盖但未理解用途的代码； - 不做与本次重构目标无关的格式化，特别是不要在重构过程中顺手格式化整个文件。 ## 输出格式 ### 规划摘要 - 现状地图关键结论 - 分步计划 ### 执行记录 | 步骤 | 改动摘要 | 测试结果 | 备注 | | 1 | 抽取 SQL 构建函数 | 通过 | - | | 2 | 移除魔法数字 | 通过 | - | ### 最终报告 - 完成度 - 剩余风险 - 建议后续处理项

这个模板里最有价值的一条约束是"禁止在重构过程中顺手格式化整个文件"。我踩过这个坑：让模型重构的同时顺手把一段代码改成符合它审美的新写法，结果 diff 里混进了大量无关格式变化，真实业务逻辑改动反而被淹没。后来的经验就是，重构动作必须和格式化动作分离，一次命令只干一件事。

3.3 技术方案模板 /design：让 Agent 产出可选方案而不是自作主张

技术方案设计这一类任务，最大的风险不是模型写得不好，而是模型太自信。让它"设计一个订单超时取消的方案"，它往往会一口气选定一个方案，然后给你讲这个方案有多好，根本不给你比较和权衡的机会。design模板就是专门治这个毛病的：

# 技术方案设计 /design ## 角色与目标 你是一名技术方案设计师。你的目标是围绕给定问题，产出至少 2 个可选方案，并基于明确的标准给出推荐，而不是直接决定唯一方案。 ## 输入 - 问题定义：{{ problem_statement }} - 约束条件：{{ constraints }}（性能、成本、人力、兼容性等） - 推荐偏好：{{ preference }}（比如偏保守 / 偏重构） ## 执行步骤 1. 先澄清问题：列出你对此问题的理解、不确定点、需要补充的信息。 2. 设计 2-3 个方案，每个方案必须包含： - 核心思路： - 改动范围： - 成本评估（开发、测试、迁移）： - 风险点： - 可回滚性： 3. 用对比表格汇总各方案差异。 4. 给出推荐方案，并说明推荐理由和放弃其他方案的理由。 ## 硬性约束 - 不得在未经过方案比较之前直接给出唯一结论； - 每个方案都要说明可回滚性，无法回滚的方案必须标注高风险； - 成本评估必须用相对量（低 / 中 / 高），而不是编造具体工时。 ## 输出格式 - 问题澄清 - 方案对比表格 - 推荐结论与理由

这个模板的巧妙之处是它把"决策"和"探索"分离了。模型负责把方案和代价铺开，人来拍板。Agent 工具再聪明，它也没有你的业务上下文和团队政治判断力，所以别让它替你决定方向。用这个模板产出的方案文档，可以直接拿到团队评审会上作为讨论底稿，非常省事。

3.4 质量巡检模板 /audit：固定检查项 + 优先级上报

巡检这件事特别适合模板化，因为它的检查项是高度稳定的。audit模板直接内置一套固定检查清单，模型不需要思考"该检查什么"，只需要按图索骥：

# 质量巡检 /audit ## 角色与目标 你是一名代码质量巡检员。基于固定的检查项，对目标目录或模块进行巡检，输出按优先级排序的问题列表。 ## 输入 - 目标范围：{{ audit_target }} - 附加检查项：{{ extra_checks }}（可选） ## 固定检查项 1. 未处理的异常（裸 except、忽略异常） 2. 敏感信息硬编码（API Key、密码、token、连接串） 3. 公共函数缺少类型标注 4. 单函数超过 300 行 5. 重复字符串常量 6. 明显的性能风险（循环内查询、N+1 查询、无索引字段过滤） 7. 死代码（未被引用的函数、变量） ## 执行步骤 1. 根据目标范围递归读取文件； 2. 逐项对照固定检查项扫描； 3. 对每个问题判断严重程度； 4. 输出巡检报告。 ## 硬性约束 - 只报告代码中确实存在的问题，不进行代码修改； - 不做代码风格类的主观评论（比如"这个命名不够优雅"除非它有实际可读性风险）； - 重复问题合并上报，不逐行重复列举。 ## 输出格式 ### 巡检汇总 | 优先级 | 位置 | 问题类别 | 具体描述 | 建议修复方案 | | P0 | src/db.py:15 | 敏感信息硬编码 | 数据库密码写死 | 改用环境变量注入 | ### 统计 - 检查文件数：N - 发现问题数：N（P0/P1/P2 各多少） - 建议优先处理项

这个模板的意义在于消除随机性。同一段代码，不带模板让模型巡检，每次报出来的问题可能差很远；带模板，模型的注意力被锁在固定检查项上，报告结构也稳定，方便接入自动化流程做趋势分析。我后来甚至用它定期对老项目做巡检，把结果归档到文档里，大版本升级前翻一眼心里就有底了。

3.5 存量迁移模板 /migrate：锁死版本与兼容边界

最后一个高频场景是存量代码迁移，比如把旧 ORM 迁移到新 ORM，或者把一种 API 风格替换成新风格。这个任务最怕的是模型在迁移过程中顺手"优化"其他东西，导致迁移 diff 里混入大量无关逻辑变化。migrate模板的核心就是锁死边界：

# 存量迁移 /migrate ## 角色与目标 你是本次迁移的执行者。任务是把指定范围从旧实现迁移到目标实现，迁移过程中不允许改变任何非必要的业务行为。 ## 输入 - 迁移范围：{{ migration_scope }} - 旧实现模式：{{ legacy_pattern }}（例如：`session.query(User).filter_by(...)`） - 目标实现模式：{{ target_pattern }}（例如：`select(User).where(...)`） - 排除规则：{{ exclude_rules }}（可选，需要跳过的文件或路径） ## 执行步骤 1. 统计迁移范围内匹配旧实现模式的全部位置，输出清单； 2. 按文件逐个迁移，每完成一个文件，执行一次相关测试； 3. 迁移完成后，全量执行测试命令 {{ test_command }}； 4. 输出迁移报告。 ## 硬性约束 - 只允许做模式替换和必要的结构性修改，禁止修改此范围内的业务逻辑； - 禁止"顺手"重构迁入文件中的其他无关代码； - 遇到使用模式复杂、无法简单替换的位置，保留原状并记录在报告中，不得猜测改写； - 一个文件迁移完成后，diff 范围内不得出现与迁移无关的格式化差异。 ## 输出格式 ### 迁移清单 | 文件 | 命中位置数 | 已完成 | 失败/跳过原因 | |---|---|---|---| | src/xxx.py | 12 | 是 | - | ### 未处理项清单 | 文件:行号 | 原因 | 建议 | |---|---|---| | src/yyy.py:88 | 涉及动态生成的查询条件 | 人工确认后再处理 | ### 最终结论 - 测试通过情况 - 剩余风险

用这个模板跑过一次用户表查询迁移，印象最深的是"遇到复杂位置保留原状并记录"这条。最初版本模板没有这条，模型在遇到一个涉及动态条件的查询时，直接按照模式匹配硬改，把语义改了，测试挂得一塌糊涂。加了这个约束以后，模型会把拿不准的位置记录下来留给人工判断，从源头规避了大部分迁移事故。

4. 模板工程化：上下文控制、成本核算与回归验证

4.1 上下文是一切问题的隐藏根源

模板不是写得越长越好。我踩过最大的坑就是：模板写太详细，命令一执行，模板本身占掉大量上下文，真正留给代码分析的上下文就被压缩了。模型不是机器，它的注意力资源是有限的，上下文里塞满了规则，它就没有余力去处理代码细节了。

所以模板工程化的一个核心工作，是控制模板自身的长度。我那五个模板每个都在 30~60 行以内，只保留真正的执行关键点。比如refactor模板里我就没写"遵守 PEP8""保持代码整洁"这种废话，因为这类指令对模型来说属于低价值的宽泛约束，起不到实际作用，反而占据空间。

还有一个容易被忽略的点：模板里所有涉及路径、命令、变量名的部分，要确保能正确解析。如果模板里写了一个项目里不存在的测试命令，模型会一本正经地尝试执行然后报错，你就得花额外轮次让它纠正。我的做法是把这些值全部做成变量，渲染时从项目的配置文件统一注入，这样至少不会有拼写错误。

上下文控制还有一个层面：让模型按需读取文件。模板里我会明确限定"只读取audit_target指定目录下的文件""不要扫描 tests 之外的目录"，这比让它无限探索仓库高效得多。对于一个大型 monorepo，这一步的 token 成本差异非常大，不限制的话模型可能扫十几个模块才找到需要的内容。

4.2 模板的回归测试与"黄金样本"

模板本身也需要测试。如果模板改了执行顺序，换了一个约束条件，怎么知道它对任务的实际效果提高了还是降低了？我的方案是做一组"黄金样本"：挑 3 到 5 个有代表性的历史任务，把任务描述、输入参数、期望的输出形态记录下来，放在tests/golden_samples里。

每当我调整模板，就拿着黄金样本重新跑一遍，重点观察：

• 模型是否完整遵循了模板中的步骤顺序；
• 输出结构是否符合模板规定的格式；
• 硬性约束是否被遵守（比如review模板里"不修改代码"这条）；
• 有没有出现模板改动之前没有的新问题。

这不是自动化测试，而是一套人工对照的回归验证流程。但它带来的安全感是无价的：以前改模板全凭感觉，现在我可以明确说出"这个版本的回退率比上个版本低"。

如果想让这个过程半自动化，可以在模板中加一段"

校验输出格式"的步骤，让模型自己检查输出是否符合模板定义的 Markdown 结构，检测到偏差就修正后再输出。我把这套自检逻辑加进了review和audit模板，实测能减少大概一成的格式错乱。

4.3 团队协作场景下的模板版本管理

如果只是自己一个人用模板，那 git 仓库管理其实可有可无。但团队用起来，问题就不一样了。模板的价值在于统一行为，一个团队如果每个人手里都是不同版本的模板，那就等于没有模板。

我们在团队里的做法是：模板仓库独立存放，作为所有成员共享的一个基准。每个成员在自己的项目里通过一个variables.yaml声明专属配置，渲染时合并默认模板和项目配置。修改模板本身必须走 PR 流程，由固定的一个人 review，因为模板的改动影响面是所有项目，不能随手改。

这里要提醒一下：模板文件里不要写具体的人名、具体的项目代号这类信息。通用模板要刻意保持"干"的状态，所有项目相关的东西都通过变量注入。一旦模板里混入单个项目的特殊信息，它就会慢慢从通用工具变成某个项目的专属脚本，适配能力直线下降。我见过一个团队的模板，里面直接写了另一个团队的项目代号和目录名，新成员拿到手一头雾水，这就是模板被"污染"了。

5. 一组真实项目数据：用模板前后的差距

5.1 对照样本与观测方式

数据来自我实际维护的一个老项目：一个 8000 多行、混合了 SQLAlchemy 旧查询方式和大量手写 SQL 的 Python 模块。任务是把其中一组核心查询迁移到新的查询接口，并在迁移过程中修复两个已知的边界条件问题。

我做了一个简单的对照：先完全不使用模板，用传统的方式跟 Claude Code 对话完成这个任务；两周后，用migrate模板配合review模板做一次同样的迁移。两次任务的目标完全一致，模型也是同一个版本。当然这不是严谨的控制变量实验，两次之间我的理解也更深了，但数据趋势仍然很有参考意义。

5.2 三个关键指标的对比

无模板那一次的 23 轮里，有大概 6 轮是在反复澄清背景、重新解释项目结构和目标；用模板之后，这些解释全部被模板和变量覆盖掉了，模型的关注点全程集中在迁移本身。

单步测试通过率的对比是最有说服力的。没有模板时，模型习惯一次改一大片再跑测试，一失败就回到起点重新理解，这种工作方式既浪费 token 也浪费我的耐心。而migrate模板里明令"一个文件迁移完立即测试"，模型被迫采用小步快跑策略，问题在产生时就被发现了。

5.3 模板的适用边界

数据看着不错，但必须诚实地讲一下模板的适用边界。模板最适合的是结构化程度高的任务：评审、重构、巡检、迁移、数据验证，这些任务的流程是可描述的、步骤是可预期的。如果任务属于探索性质，比如"帮我研究一下这个新框架的某种能力"，或者"看看这个仓库里有没有值得借鉴的设计模式"，模板的价值就很有限，甚至可能帮倒忙——因为模板会把模型约束在固定流程里，限制它自由探索的空间。

还有一个边界是模型本身的能力。模板是把稳定流程固化下来，但执行质量的底线还是取决于模型对代码的理解能力。如果模型根本读不懂某个文件的逻辑，再好的模板也只是让它"按错误的方式更高效地犯错"。所以我的建议是：模板不能替代你选择模型版本的决策，但能让模型的不同版本之间，协作体验更稳定。

6. 常见问题排查与避坑技巧

6.1 模板失效的四种典型原因

用纯模板跑了很多次以后，我把遇到过的"模板突然不好使了"的情况归纳成四类：

第一类：模板变量渲染失败。模板里写了{{ test_command }}，但渲染脚本没定义这个变量，模型就直接把{{ test_command }}当成字符串执行，结果跑出一个不存在的命令。排查方法很简单：渲染完成后打开commands目录里的最终文件，扫一遍有没有残留的花括号模板变量。

第二类：上下文过长导致模板尾部指令被忽略。模型上下文被大量代码内容占满之后，模板里写在后面的"硬性约束"和"输出格式"部分容易被稀释，模型就漏掉了关键约束。对策是把最关键的硬性约束尽量往模板前面放，或者单独作为一条不可省略的简短指令紧跟输入之后。

第三类：模板被项目特有信息污染。模板里混入某个项目的具体路径或命令之后，换一个项目根本没法用，而且你还不容易察觉。我给自己的检查标准是：每过一两个月审视一遍模板，凡是出现具体文件路径、具体模块名、具体工具链的内容，一律改成变量。

第四类：模型版本更迭导致风格不匹配。换一个新版本模型之后，模板里的某些指令风格可能不再被严格执行，比如新模型更倾向于详尽输出，把原本很简洁的表格撑得巨长。碰到这种情况，需要对模板做一次回归验证，而不是默认"以前能用现在也一定能用"。

6.2 排查问题的方法与顺序

如果你发现某个模板跑出来的效果不对劲，我建议按这个顺序排查，基本能覆盖大部分问题：

1. 先看最终渲染产物。打开.claude/commands下的对应文件，确认变量是否正确替换、有没有残留模板语法。
2. 再确认模板本身是否完整。有时候编辑模板时语法错误，比如表格的分隔线少了，模型解析出来就是一个普通段落，输出格式完全失效。
3. 然后检查上下文是否超限。可以通过观察模型是否有"忘了约束"的倾向来判断，如果前半段执行很好、后半段开始跑偏，大概率是上下文压力导致的。
4. 最后考虑模型版本因素。把同样模板在旧版本上跑一次做对照，如果旧版本正常而新版本异常，那就是风格不匹配问题，需要微调模板指令的措辞。

6.3 我踩过之后才明白的几个设计原则

原则一：模板里的"禁止事项"比"建议事项"更值钱。模型跟人一样，给它十个"应该做什么"，它可能每个都做一点；给它三个"绝对不要做什么"，执行效果反而清晰。我的模板里每条硬性约束都是可验证的，比如"禁止跨文件修改""禁止改动接口签名"，而不是抽象的"请保证代码质量"。

原则二：输出格式要具体到可以直接粘贴。模板里定义输出表格时，我会把表头直接列出来，模型就会照着这个结构走。如果你只是说"请用表格输出"，它可能给你来一个没有任何列的文本列表，格式形同虚设。

原则三：模板的执行步骤要按依赖关系排序。先全局、后局部，先分析、后动作。这个排序逻辑在review和refactor模板里都死死锁着。一旦顺序乱了，输出的价值就大打折扣。

原则四：不要追求一个模板解决所有问题。我最初也尝试做一个"万能模板"，结果它因为约束太多变得非常僵化，简单任务也走重流程，反而拉低效率。后来回到"高频场景独立模板"的路子，才回到正轨。每个模板专注一个职责，哪怕职责比较窄也没关系，因为组合使用多个模板比一个重模板灵活得多。

最后说点个人体会。做这个模板库最大的收获，不是省了多少时间，而是让我从"每次跟模型对话都是一次碰运气"变成了"每次对话都是按既定流程执行"。模板的本质不是限制模型，而是把你自己之前的成功经验、失败教训、踩过的坑都固化下来，让每次执行都站在上一次的肩膀上。如果你也想做自己的模板库，我的建议是不要一开始就想着做一套大而全的东西，从你日常重复最多的那个操作开始，先做第一个模板，把它用熟、测透，再慢慢扩展。一个能稳定解决你 80% 重复工作的模板库，比一个覆盖所有场景但每个都跑不稳的模板库强太多了。