企业官网建设流程全解析

1. 从"每次手写长指令"到"模板资产化"：这个项目到底解决了什么

先说我自己的处境。我在团队里用 Claude Code 做日常编码接近一年，最初的习惯是每个任务临时打一大段 Prompt，比如"帮我看一下这个文件的问题并修复""写个测试""按规范生成 commit message"。一开始还好，后来发现同一个仓库里反复出现的任务其实就那几类，而我在每次开始前输入的引导语，有七八成是重复的。真正耗时的地方不是让模型跑代码，而是我自己的"废话"占了上下文，输出还经常跑偏。

所以我动手整理了这套claude-code-templates。目的很直接：把高频任务的指令沉淀成固定模板，放进工程仓库，让每一次调用都有稳定的角色设定、上下文注入、约束条件和输出格式。这里要澄清一个常见误区——模板不是"提示词大全"，不是把上百条 Prompt 堆在一个 markdown 文件里就完事。真正的模板，本质上是把一个人对代码库的理解、编码习惯、避坑经验，固化成可复用、可演进、可交给他人的工程资产。

模板化之后的收益，我实测下来有三点很明确：

• 输出稳定性。同一个任务，不管谁来用、什么时候用，模型的输出结构基本一致。比如代码审查，之前十次有十种排版，现在统一按"严重程度排序+文件定位+修改建议"输出，review 效率提高了一截。
• 上下文质量。模板里预置了项目规范、相关文件引用、历史约定，模型不需要靠猜，第一次输出就接近可用状态。
• 知识传递。团队新成员上手时，看一遍模板就懂了这个项目的代码习惯和常见坑，相当于把一个老开发的经验写进了文件。

这套做法不只适用于编码，凡是需要重复向模型描述"你是谁、要干什么、遵守什么规则、输出成什么样"的场景，都可以模板化。下面我会从载体、设计方法、可抄作业的模板实例，到工程化细节和踩坑清单，完整拆一遍。

2. 两个核心载体：CLAUDE.md 的"人格设定"与斜杠命令的"技能包"

Claude Code 的模板能力，我理解下来其实就是靠两个东西落地：一个是CLAUDE.md，一个是自定义斜杠命令（Slash Commands）。两者互相配合，搞懂边界之后，模板体系才算立住。

2.1 CLAUDE.md：项目级的长期记忆与编码锚点

CLAUDE.md是放在项目根目录（也可以按需放在子目录）的说明文件，Claude Code 在执行任务时会自动读取，相当于给模型一份"关于这个项目的长期记忆"。你可以在这里写项目技术栈、目录结构、启动命令、编码规范、常用脚本、禁止事项。

我常用的写法是这样：

# 项目概况 - 基于 TypeScript 的 Node.js 服务，使用 pnpm 管理依赖 - 采用 monorepo 结构，核心业务代码在 packages/core - 运行测试：pnpm test --filter core # 编码规范 - 缩进使用 2 空格，不写分号 - 组件一律函数式声明，禁止使用 class 组件 - 接口返回统一包一层 { code, data, message } # 常见命令 - 本地开发：pnpm start - 构建：pnpm build

这份文件建议保持在 30～60 行的量级，太长模型会稀释注意力。它是项目级模板的"地基"：所有斜杠命令都跑在它所定义的上下文之上。比如你在命令里说"按项目规范写代码"，模型就会去CLAUDE.md里找规范，不需要命令文件里再重复一遍技术栈。

2.2 Slash Commands：把高频任务做成"技能包"

斜杠命令是 Claude Code 里的自定义指令，默认放在.claude/commands/目录下，每个命令对应一个 markdown 文件。你在交互界面里输入/bug-fix、/code-review这类斜杠命令，模型就会按照文件里写好的指令执行。

一个典型命令文件长这样：

--- description: 定位并修复代码缺陷 argument-hint: 文件路径或问题描述 --- 你是一名资深后端工程师，请修复用户描述的问题。 问题描述：{{$ARGUMENTS}}

这里的$ARGUMENTS是参数占位符，你在命令后面输入的参数会自动填充进去。命令文件的正文，才是真正的指令模板本身；frontmatter 里的description和argument-hint用于在命令列表中展示，让调用者知道这个命令是干什么的、参数怎么传。

我把 CLAUDE.md 理解成"项目人格设定"，斜杠命令理解成"高频技能包"。人格设定负责全局一致，技能包负责专项任务。两者边界如果不分清，就会出现两种情况：要么命令文件把项目背景重复写八遍，浪费 token 不说还容易跟CLAUDE.md冲突；要么CLAUDE.md里塞满了各种任务流程，导致每次普通对话也背着沉重的上下文。

2.3 目录组织与命名习惯

在确定建立模板库之后，我建议一上来就规划好结构：

.claude/ commands/ bug-fix.md code-review.md gen-tests.md commit-msg.md explain.md

命令文件名就是斜杠命令名，划线命名更清晰，不要用空格。description这一项一定要写具体，因为团队其他人要能从命令列表里一眼看出用途。另外，命令文件可以引用项目里的其他文件，后面我会专门讲怎么用@文件引用做上下文注入。

3. 模板设计方法论：五要素拆解与参数注入

很多模板不好用的原因，不是模型不行，而是指令本身写得不行。我拆过自己和同事写的各种模板，发现高质量模板基本都包含五个要素：角色、上下文、任务、约束、输出格式。一套模板只要把这五件事写清楚，质量就有八成保证了。

3.1 五要素模板的完整样例

下面是我设计模板时最常用的骨架，你可以直接参考它的结构：

--- description: <用一句话说清楚这个命令做什么> argument-hint: <提示用户该传什么参数> --- <角色>你是一名具备 X 年经验、熟悉 Y 技术的资深工程师。</角色> <上下文>项目背景、目标文件、相关规范，必要的时候用 @ 引用具体文件。</上下文> <任务>请完成以下事项： 1. 先定位问题 2. 再输出修改方案 </任务> <约束> - 不要修改与本次任务无关的代码 - 不确定的信息明确说明，不要编造 </约束> <输出格式> 请按以下结构输出： ## 问题分析 ## 修改方案 ## 验证步骤 </输出格式>

你会发现这五要素其实就是回答模型的五个问题：你是谁？你在什么情境下？你要做什么？有什么不能做？做完给我什么格式的东西？模型的所有幻觉、跑偏、格式混乱，几乎都能追溯到这五件事里的某一件没写清楚。

3.2 参数注入的三种方式

模板不能总是"无参函数"，实际使用中需要针对不同文件、不同需求做变化。参数注入我实测常用三种方式：

• 命令行参数：直接写在命令后面，通过{{$ARGUMENTS}}注入。适合传文件名、函数名、关键词。比如/explain src/utils/date.ts。
• 文件引用：在命令文件里用@路径引用项目文件，Claude Code 会把文件内容读进来作为上下文。比如@src/services/userService.ts，比让用户手动复制粘贴代码方便得多。
• 环境信息：通过CLAUDE.md或系统级配置提供的项目信息，比如技术栈、目录结构。这部分不需要每次传，模型会自动携带。

我用得最频繁的是前两种。比如gen-tests模板，用户只需传一个文件路径，模板内部用@把源码引进来，再让模型基于源码生成测试。这样命令是固定的，输入参数却非常灵活。

3.3 为什么"短指令、长上下文"是最优解

这是我从多次实践中总结出来的一个重要原则：模板里尽量少写"你应该如何思考"这种大道理，把空间留给真实的上下文。

举个例子，同样是写测试模板，差的版本是：

请认真阅读上面的代码，分析函数逻辑，考虑到各种边界情况，包括空值、非法输入、大字段、超时……然后写出高质量的单元测试。

好的版本是：

目标文件：@src/utils/format.ts 请针对该文件的每个导出函数生成单元测试。测试框架为 Vitest。

信息密度完全不同。前者大量内容是在"叮嘱"模型，这些词对模型没有实际指导意义，反而稀释真正的指令；后者把对象、框架、动作全部钉死，模型可以直接开工。CLAUDE.md里已经写过测试框架，那么模板里甚至可以不写"测试框架为 Vitest"，上下文会自动带上。模板文件应该保持精简，把上下文从项目文件里拉进来，而不是把所有背景塞进命令文件里。

4. 五个可直接照抄的实战模板

下面这五个模板是我目前项目里每天都在用的，全部经过多轮迭代。你可以直接复制到.claude/commands/目录下，按需微调。

4.1 模板一：bug-fix，让模型先复现再动手

--- description: 定位并修复指定代码缺陷，输出根因分析和修改方案 argument-hint: 文件路径或简要问题描述，多个参数用空格分隔 --- 你是一名资深软件工程师，擅长通过代码审查和日志分析定位问题。 问题描述：{{$ARGUMENTS}} 请严格按以下步骤执行： 1. 先阅读相关代码，复现问题逻辑，不要急于修改 2. 定位根因：指出问题所在的文件、函数、具体行号 3. 给出修复方案：说明修改思路，以及影响范围 4. 修改代码：输出完整 diff 或修改后的代码块 约束： - 区分"已确认的根因"与"可能的猜测"，不要含糊 - 如果问题描述中缺少复现信息，先列出你还需要的三个关键信息 - 不要修改与本问题无关的代码 输出格式： ## 问题复现路径 ## 根因分析 ## 修改方案 ## 修改后的代码 ## 验证建议

这个模板的核心是第一步"先复现"。模型最常见的毛病是一上来就猜一个原因，然后对着那个猜测改代码，最后原问题没解决。我在模板里强制它先列出复现路径，既是为了让模型自己捋清逻辑，也是为了让使用模板的人能判断它的理解是否正确。

4.2 模板二：code-review，审查意见要"可执行"，不要"正确的废话"

--- description: 对指定文件执行结构化代码审查，输出分级问题清单 argument-hint: 文件路径 --- 你是一名严格的代码审查者，熟悉本项目的开发规范（参考 CLAUDE.md）。 审查对象：{{$ARGUMENTS}} 请按以下结构输出审查意见： ## 审查概览 一句话概括本次审查范围和代码整体质量。 ## 问题清单 按严重程度从高到低排列，每个问题包含： - 严重级别：P0（可导致故障/安全风险）、P1（逻辑缺陷）、P2（可维护性问题） - 位置：文件路径 + 函数名/行号 - 问题描述：说明为什么这是一个问题 - 修复建议：给出具体修改思路，不要写"建议优化"这种空话 - 是否阻塞合并：是 / 否 ## 亮点 如果代码中有值得肯定的设计，列出来。 约束： - 不要吹毛求疵，不要为了凑数量列问题 - 如果某处只是为了风格偏好而非逻辑问题，明确标注为"风格建议" - 涉及依赖安全、异常捕获、状态变更的内容要特别标注

用过之后最明显的感觉是：P0/P1/P2的分级让团队 review 效率大幅提升，大家只用看 P0 和 P1 就能决定是否合并。模板里特别写了一条"不要为了凑数量列问题"，因为模型默认会自动生成一堆无伤大雅的小毛病，没有这条约束，审查清单会非常吵。

4.3 模板三：gen-tests，先列行为矩阵，再写测试代码

--- description: 基于源码生成单元测试，输出测试矩阵和可运行代码 argument-hint: 文件路径 --- 你是一名测试工程师，擅长编写边界充分的单元测试。 目标文件：{{$ARGUMENTS}} 请先用 @ 引用目标文件，阅读源码后按以下步骤执行： 1. 列出测试用例矩阵：每个导出函数对应的用例名称、输入、预期行为 2. 覆盖要求：正常路径、边界值、空值/undefined、异常输入、大字段 3. 依据测试矩阵生成测试代码，使用项目已有测试框架 4. 输出代码前说明 mock 了哪些外部依赖及原因 约束： - 不要生成只能自我证明的测试（比如 mock 了被测函数内部实现） - 不要为了覆盖率强行造用例 - 外部服务、网络请求必须 mock，纯函数不做无谓 mock 输出格式： ## 测试用例矩阵 ## 测试代码 ## mock 说明 ## 建议补充的集成用例

为什么先要"测试用例矩阵"？因为矩阵是给人的评审依据，模型列矩阵时如果对函数理解错了，人的评审成本比"读完一堆跑不动的测试代码再发现方向错了"低得多。矩阵确认没问题，测试代码基本一次成型。我实测下来，这个模板把"从零写单测"从半小时压缩到五分钟，而且质量比我手写还整齐。

4.4 模板四：commit-msg，从 git diff 生成规范提交信息

--- description: 根据暂存区或指定 diff 生成符合规范的 commit message argument-hint: 可传可选背景说明 --- 你是一名熟悉 Conventional Commits 规范的开发者。 请先执行 `git diff --cached` 查看暂存区改动，也读取一下最近五条提交历史来参考项目实际的提交风格。 任务： 1. 概括本次改动的主题 2. 生成一条 commit message，格式：<type>(<scope>): <subject> 3. type 限定为 feat / fix / docs / refactor / test / chore / perf 4. subject 控制在 50 字以内，正文可以描述动机 约束： - 不要添加冒号、引号等与提交无关的装饰 - 如果暂存区为空，明确提示并停止 - 不确定的改动意图，列出两种可能的提交信息让用户选择 输出： 只输出 commit message 本体，不要输出解释。

这个模板看起来简单，实际很有讲究。很多人让模型生成 commit message，得到的是一堆"优化了代码结构并提升了可维护性"的空话。所以我在模板里加了两个关键约束：让它参考最近五条提交历史（模仿团队真实风格），以及"只输出 commit message 本体"（防止模型废话连篇）。实际体验非常好，commit 质量肉眼可见地提升，历史看起来整齐多了。

4.5 模板五：explain，陌生代码的阅读路径

--- description: 解释指定代码的执行逻辑与设计意图 argument-hint: 文件路径（可附带具体函数名） --- 你是一名代码讲解专家，擅长把复杂逻辑讲清楚。 目标文件：{{$ARGUMENTS}} 请按以下结构输出： ## 一句话概述 ## 执行流程 从入口开始，按调用顺序解释主要执行路径，可以标注关键分支条件 ## 关键数据结构 涉及到的对象、状态、缓存等 ## 调用关系 被谁调用、调用了谁，用列表说明 ## 设计意图 这个模块为什么这样设计？解决什么问题？ ## 潜在风险点 状态变更、异常处理、性能隐患

explain是我给新人准备的模板。团队里新人接手旧代码时，往往不知道从何看起。以前是我陪着他一行行讲，现在他把文件路径丢给这个模板，先拿到一套结构化的解释，再带着疑问来问我，效率完全不同。注意模板里我用了"潜在风险点"而不是"改进建议"，因为对于解释场景，识别风险比给建议重要，新人不需要一上来就想着改代码。

5. 模板工程化的四个细节：上下文、约束、变量与质量兜底

模板能用只是第一步，要稳定、可维护，还得把这四个工程化细节处理到位。这些都是我在多轮迭代中慢慢补出来的。

5.1 用 @ 文件引用注入上下文，而不是让用户粘贴代码

命令文件里出现@src/utils/format.ts，Claude Code 会读取该文件内容并注入上下文。这是模板最实用的能力。它意味着：

• 用户只需要传一个路径，不需要把代码复制进参数
• 模型读到的文件内容比用户粘贴的更完整，不会因为粘贴截断而丢上下文
• 模板本身保持干净，不用内嵌大段代码

文件引用还能组合多个文件。比如做代码审查时引用源码和对应的测试文件：@src/utils/format.ts @tests/format.spec.ts。同一个任务，模型能同时看到实现和用例，审查质量比只看源码好很多。我在bug-fix和code-review模板里都推荐用户尽量传文件路径而非问题描述，就是这个原因。

5.2 用 frontmatter 维护命令的"元数据"

每个命令文件开头的---部分是 YAML frontmatter，里面可以写这个命令的元信息。我至少会维护两个字段：

这两个字段不写，命令也能用，但团队其他人根本无法从命令列表里判断该选哪个、参数怎么传。我经历过这种情况：同事把/bt当 bug 修复命令用，结果我那个bt其实是"build type"的缩写。所以description一定要具体，命名尽量用完整单词。

5.3 防幻觉约束：把"区分事实与推测"写进指令

模板工程化里最重要的一条，是防幻觉。我的做法是：在模板里显式声明某些输出必须区分"已确认的事实""基于上下文的合理推断""需要你进一步确认的部分"。典型语句：

如果某个信息不能从上下文确认，明确标注"需要确认"，不要自行假设。

这句话看起来简单，实际能救回很多错误。比如 bug 修复时，模型会把一个没依据的猜测说得斩钉截铁，有了这条约束，它会主动列出"还需要用户提供哪些信息"。发布、迁移、删除操作这类高风险任务，我还会额外加一句"涉及破坏性变更时，先列出变更清单并等待确认，再继续执行"。

5.4 输出即产物：把"验收清单"写进模板

最后一个工程化细节是让模板自带验收标准。很多模板只写了"做什么"，没写"做完怎么判断对不对"。我在程序生成类和重构类模板里都会加一段"验收清单"：

输出前请自查： - [ ] 代码可以独立运行且无编译错误 - [ ] 主流程和边界场景均有处理 - [ ] 没有修改无关代码 - [ ] 涉及外部依赖时已说明 mock 原因

这段自查清单看起来是给模型看的，实际上是给人看的。模型输出之前按照清单逐项检查，能显著减少"代码看起来完整但根本跑不起来"的情况。我见过不少模板生成的代码，凡是加了自查项的，可直接用的比例明显更高。

6. 团队模板沉淀与个人避坑实录

模板这种东西，单个开发者自己用是效率工具，团队一起用才是资产。最后这部分聊聊怎么把模板在团队里落地，以及我在迭代过程中踩过的坑。

6.1 团队统一模板的三个落地原则

• 模板进版本库。.claude/目录跟着代码仓库走，新成员 clone 下来就能用。不要放在个人电脑的零散文件夹里，那样根本沉淀不下来。模板变更走 PR 流程，review 模板的人同时也是模板的使用者。
• 先固定两个命令，再拓展。团队刚开始引入时，不要一次性铺开十个命令。我会建议先固定code-review和commit-msg这两个，因为它们几乎每个项目都通用。跑两周，收集反馈，再慢慢添加bug-fix、gen-tests这些。一次铺开太多，大家对模板质量没信心，后面就没人用了。
• 模板要有 owner。每个模板指定一个人维护。模板质量问题、输出结构变化，由 owner 收集意见迭代。没有 owner 的模板很快就会烂掉。

我在团队里的真实体会是，模板机制推行最难的从来不是写文件，而是让大家相信"模型输出稳定可预期"。前两次如果输出格式变动很大，信任就崩了。所以早期固定一套结构非常重要，宁可内容少一点，结构不要变来变去。

6.2 踩坑清单：这些错误我全部犯过

错误一：指令太宽泛。我最开始写的 bug 模板是"请修复代码中的问题"，没有任何约束。模型输出了一堆无关紧要的优化，真正的 bug 没找到。后来加上"先复现、再定位根因、给行号、区分事实与猜测"，才变得可用。

错误二：没有输出格式约束。这是所有模板最容易忽略的一点。同一份 code-review，第一次输出用表格，第二次用列表，第三次用段落，直接导致无法用任何自动化脚本或人工习惯去消费它。现在我的每个模板都强制写清输出格式小节，格式一旦稳定，后续解析和处理都方便。

错误三：上下文不足就硬让模型干活。有一段时间我的gen-tests模板只让模型写测试，不引用源码。模型只能靠记忆里模糊的项目知识去猜函数签名，生成的测试一半跑不起来。改成必须用@引用目标文件后，问题才彻底解决。

错误四：模板里堆积太多"正确的废话"。"你是一个专业且富有经验的开发者"这种话在十个模板里出现，把真正有用的约束淹没了。我现在写模板的原则是：每个指令词都必须服务于任务的某一环，不能只为了显得专业而存在。

6.3 一个提高模板迭代质量的小习惯

最后分享一个我坚持到现在的小习惯：定期统计模板的失败率。我的做法是在每个模板的description里不做文章，而是每两周围绕常用模板做一次回查，把"输出不可用"的例子收集起来，看是哪个环节出了问题。修复模板，本质上是修复"人类描述需求的精度"，而不是修复模型。这个视角很重要。

如果让我给还没开始做模板的人一个建议，那就是：从commit-msg这种小命令开始，先感受一下"固定指令带来稳定输出"的体验，再逐步构建自己的模板体系。模板库不需要一次建成，它会随着你对项目、对工具的认知一起演进。