企业官网建设流程全解析

1. 为什么要折腾一套 Claude Code 模板

1.1 从一次手忙脚乱聊起

“claude-code-templates”在我这里不是某个开源仓库的名字，而是我给自己的一整套工作方式起的外号。围绕 Claude Code 这个命令行编程助手，我积累了大半年的使用经验，最后发现真正决定体验上限的，不是模型本身有多强，而是你喂给它的那些约定文件——模板。

引起我认真做模板的是一次真实的手忙脚乱。当时我接手一个中等规模的 React 项目，代码按照 features 目录组织，组件拆到 shared 和业务域两类，测试统一用 Vitest，接口层强制走一个自己封装的 fetch。听起来很常规对吧？但我每开一个新会话，基本都要重新把这些约定讲一遍：哪个目录放组件，测试文件命名要用.test.tsx还是.spec.tsx，API 调用是否要走 hook 封装……工具确实能听懂，问题是每开一个会话就得重新讲，讲漏一处，它给出的代码就会跑偏。那段时间我做得比较狼狈，约等于每个工作日都在向一个记性很差的新同事解释同一套规范。

后来我把这些约定全部写进了一份CLAUDE.md，从“组件文件放features/xxx/components/下，使用默认导出”到“测试命令用npm run test:watch”，一条条往下列。它生效的方式非常朴素：每次会话开始，工具会自动把它作为背景信息读入。这个文件对我来说就是“项目交接文档”。以前是我开口说，现在是它自己读。效果立竿见影，同一份模型权重，带模板和不带模板，产出质量的差距非常明显。

1.2 模板到底解决什么问题

做模板这半年，我总结出它最重要的四个价值点。

第一，上下文连续性。工具没有长期记忆，每次对话都是全新开始，但项目是长期存在的。模板就是项目记忆的外置存储，把“我们约定过什么”固化下来，避免每次重建全会话的上下文。没有模板的时候，开工前十分钟通常都是在补背景知识；有了模板，开工前十分钟变成了看 diff。

第二，减少重复劳动。代码风格、目录结构、提交信息格式，这些都是重复决策。如果不写进模板，你每次都要口述一遍；写进去之后，模型默认就会遵守，你只需要在分歧出现时纠正它。举个例子，你只要在模板里写一句“提交信息遵循 Conventional Commits”，后面它生成的 commit message 就会规规矩矩地带上feat:、fix:这些前缀。

第三，统一输出样式。团队里如果大家都用工具辅助开发，有人有模板，有人没有，提交上来的代码就是两套风格。模板相当于把评审意见中最常说的“别那样写，应该这样写”翻译成机器可以执行的规则，减少交付后的返工沟通成本。这个价值在多人协作的项目里尤其明显。

第四，明确“完成”的标准。模板里写清楚什么算“任务完成”，比写清楚怎么实现更重要。模型在没有验收标准的情况下，很容易在功能基本跑通后就把状态标成完成，而边界条件和异常分支被忽略了。模板把完成条件逐一列出，它才会知道那步测试过了才算真的做完。

这四个价值是 claude-code-templates 的核心动机。后面讲到模板文件怎么设计时，其实都是在围绕这四个点做文章。

2. 把 CLAUDE.md 当成项目说明书来设计

2.1 CLAUDE.md 本质上是注入到上下文里的“交底书”

我花了一段时间才摸清CLAUDE.md的机制。从使用表现上看，它会出现在会话开始时的高优先级上下文中，相当于给模型一个“接下来你要为这个项目负责”的设定。你写进文件里的内容，模型不是每次都按原文引用，而是作为必要背景参与生成。所以文件结构很重要。

一开始我的CLAUDE.md像流水账，什么内容都往里塞。后来发现效果不好，因为模型读取背景时也需要抓重点。改成“角色说明 + 硬性规则 + 常用命令 + 验收要求”这种结构化排版之后，至少有三个好处：一是模型在开放任务里能够较快识别相关条款；二是你后续更新的时候容易定位段落；三是读的人（比如团队里另一个成员）也容易理解这套约定到底约束了什么。

还有一个值得记住的优先级关系：我自己的经验是，项目级文件比用户级文件更优先。如果你在用户目录放了一套通用的“我习惯怎么写代码”，但项目CLAUDE.md里约定了相反的做法，模型最后通常会听项目的。这其实很合理，因为项目的约定能被硬性约束验证——比如测试文件的命名规则，lint 配置在仓库里是真实存在的。

提示：判断模板是否生效最直接的办法，是在会话里问一句“当前项目的关键代码约定有哪些”。它如果答得出来，说明文件生效了；答不出来，问题多半出在路径或优先级上。

2.2 一份靠谱模板的四个层次

我整理模板时遵循四层结构。每一层的功能不一样，而且有顺序：先定责任边界，再给项目地图，最后谈命令和验收。

第一层，角色与边界。开头用一段话说明模型在这个项目里是什么角色。我最常写的：“你是本项目的长期维护工程师，职责是修改既有代码，不要重写整个项目。”第二句话通常是禁忌：“不要动数据库迁移脚本，不要自动升级依赖版本，不要重构与本次需求无关的文件。”边界写清楚，后面出错概率会小很多。角色和边界如果缺失，模型会默认自己是个万能生成器，经常产出“看起来很有道理但完全不属于本任务”的改动。

第二层，项目结构与命名约定。这里我会贴一个精简后的目录树，标注每个目录的用途和出口。比如：

src/ features/ 业务模块，按领域划分 auth/ components/ 页面级组件 hooks/ 业务 hooks api/ 接口封装，统一走 src/lib/request shared/ 可复用组件，不依赖业务领域 lib/ 请求、鉴权、通用工具

配合命名规则：“组件文件使用 PascalCase 默认导出，hooks 文件使用 camelCase 具名导出，utils 文件使用 kebab-case。”这些看起来细枝末节，但模型产出如果不一致，后续改起来很头疼。

第三层，命令与工具接入。直接列出常用命令，最好用代码块，方便模型在生成脚本时参考：

npm run dev # 启动 dev server npm run typecheck # 类型检查 npm run test # 全部测试 npm run lint # lint npm run validate # typecheck + lint + test

这一层的细节是项目负责人最容易忘记更新的。一旦换了包管理器或者加了新的校验步骤，模板里没同步，模型就会按旧习惯执行，然后你会看到它自作主张跑了一条早就不存在的命令。

第四层，验收标准与输出格式。这是四层里最容易被忽略但长期价值最高的一层。我通常会写：

• 新功能必须带至少一个测试，覆盖正常路径和一个边界条件
• 修改公共 API 时必须更新对应文档和变更日志
• 提交信息遵循 Conventional Commits 规范，格式为<type>(<scope>): <description>
• 不通过 lint 的代码不视为完成

验收标准定义了“完成”的含义。没有这层，模型很可能在功能能跑通时直接停下，或者在改完代码但忘了补测试时报“完成”。有了这层，它的完成判断就要先和标准比对，这对依赖工具提效的开发流程非常有用。

2.3 模板库的目录组织

很多新人会把所有约定塞进同一个文件，导致CLAUDE.md越来越大，最后没有人敢改，模型也用不好。我更推荐把模板做成一个目录，入口文件负责放全局常量和指针，细节放旁边。

我的目录结构长这样：

.claude/ ├── CLAUDE.md ├── commands/ │ ├── review.md │ ├── refactor.md │ └── docs.md └── references/ ├── testing-conventions.md ├── architecture.md └── style-guide.md

入口文件只写“如果你要做代码评审，先读commands/review.md；如果你要修 bug，先读references/bugfix-flow.md”。模型在实际会话里发现任务属于某个场景时，再按指引去读取对应片段。这样每份文件都不会太长，模型可以按需组合上下文，整体效率比一份长文件高不少。

3. 按工作流拆分模板：让工具“知道”该干什么

3.1 验收驱动式模板

我经常遇到一个场景：接到一个需求，背景已经在对话里讲清楚了，但工具在实现完 main path 之后直接宣告“完成”。为了解决这个问题，我后来写了“验收驱动式模板”。它其实是一个场景指令，核心是把任务描述和验收标准放在一起，让模型先确认再动手。

一个典型例子是，实现用户列表分页接口时，我在模板里写：

## 任务 实现 GET /api/users 分页查询接口 ## 验收标准 - 参数 page、pageSize、filters 做合法性校验 - 返回结构为 { items, total, page, pageSize } - 当 page 小于 1 时返回 400，且有测试覆盖 - 不修改现有数据库迁移文件 ## 完成判定 满足上述验收标准、相关测试全部通过，才算完成。

这个模板的妙处在于把“完成”从“能编译”升级为“满足验收标准”。模型在执行过程中会频繁对照验收标准，一旦发现某个边界情况没有被覆盖，它会主动停下来补测试或告诉你风险，而不是糊弄过去。我在实际使用里最明显的感受是：带验收模板的任务，补齐的边界测试数量明显更多。

3.2 重构模板

重构类任务让我栽过几次坑。模型最容易犯的问题是在重构时“顺手”改掉了一些行为，而测试又没覆盖到那部分行为，导致回归到线上才发现问题。后来我写的重构模板强制规定了四条：

• 每次只重构一个行为点
• 重构前先建立测试基线，重构后再跑一遍对比
• 行为发生变化时立即停下，向开发者说明
• 重构结束后删除所有临时实验代码

“建立测试基线”是我最看重的步骤。通常我会让模型先跑一次npm run test，把通过、失败数量记录到一个临时文件里，重构完成后再跑一次，对比结果。如果通过数少了，或者出现了本来不该出现的失败，代码就要回滚。这个流程就像给车换零件之前先拍一张仪表盘的照片，换完之后对比读数，才能知道哪里没装对。

有一次我用这个模板处理一个老模块，模型按照模板先建了基线，然后把一个三层嵌套的回调拍平了，测试从 23 个通过变成 23 个通过，没有引入任何行为变化。整个过程里模板提供的不是“怎么改”的指令，而是“什么能改、什么时候必须停”的护栏。

3.3 代码评审模板

代码评审模板是我在团队里使用频率最高的一个。它不是用来生成代码的，而是用来审查已有改动。最早的版本因为我没定义边界，导致模型把一段本来还算合理的代码改得面目全非。后来我给它加了严格的操作范围：

• 只审查 diff，不重写整个文件
• 按“逻辑正确性 > 边界条件 > 性能 > 可读性 > 命名”的优先级给意见
• 每条意见必须给修改建议，不能只批评
• 区分“必须修改”和“建议优化”
• 问题必须指出对应测试是否覆盖

这套模板把评审从“AI 觉得该怎么写”变成“基于 diff 的可执行清单”，输出格式很适合直接粘贴到 PR 评论里。团队里用了一段时间后，大家甚至开始习惯工具给出的“必须修改”优先处理，再快速扫过“建议优化”，评审效率提升了不少。

3.4 文档与交付模板

文档类任务的模板，核心是“不要写华丽，要写完整”。我要求模型在生成功能文档时至少覆盖以下信息点：

• 功能说明
• 关键设计决策和理由
• 使用示例
• 参数、返回值、异常情况
• 已知限制和后续优化方向

之前没有这个模板的时候，模型经常生成看起来结构清晰、实际上漏掉关键信息的文档。比如它不会专门提某个参数在什么情况下会返回空值，用户照着文档做才发现不对。模板写清楚“必须包含”项之后，生成的文档就基本能用了。变更日志同理，我会约定格式，要求每处改动对应到CHANGELOG.md里的具体版本条目。

3.5 快捷指令模板

Claude Code 支持把常用的提示词存成命令，用/review、/refactor这种斜杠指令来调用。我建议在.claude/commands/目录下面为每个工作流建立一个 markdown 文件，文件名就是指令名。需要注意：命令模板只放该场景的专项指令，不要把项目通用规则复制进去，因为项目通用规则本来就在CLAUDE.md里。如果命令文件里又重复一遍，会徒增指令冲突的风险。

快捷指令最大的价值是降低“记忆负担”。我不需要每次手动输入一大段参数和验收标准，敲一个/review就行。命令模板本身也适合走版本管理，团队里谁想让命令更完善，直接提 PR，评审通过后所有人受益。

4. 在团队里用模板做标准化

4.1 模板是团队协作协议，不是个人偏好

当模板由多人共享时，它就不再是个人玩具，而是团队协议。我的经验是把它当成仓库里的“一等公民”：模板文件纳入版本控制，评审任何功能改动时，涉及到的约定变更也会顺带检查。

一个真实的例子：我们团队规定所有新组件必须用函数组件和 hooks，不使用 class 组件。最开始这只是一条口头约定，新同事经常违反，评审时总是反复提醒。后来我在CLAUDE.md里加了一句话：“新组件一律使用函数组件，优先使用 hooks，禁止使用 class 组件（历史代码除外）。”从那以后，工具生成的新组件就很少再出现 class 写法。这个例子说明模板的价值不只是工具效率，还包括让团队规范真正落地。

4.2 模板维护和迭代

模板也会过期。项目升级了包管理器、改了目录结构或者调整 lint 规则，模板如果滞后，就会给出错误的指导。我的做法是：每当全局性变更影响到代码规范，就在改动当天同步更新.claude下对应的文件；如果发现某个模板在连续几个会话里都被纠正，说明它的措辞有问题，需要重写，而不是继续打补丁。

另外，尽量避免在多个项目里复制同一段模板。公用规则放到用户级的“base 模板”里，项目里只写差异。如果一个规则在五个项目里被改过五次，说明它应该向上提升；反过来，如果一个 base 规则在一个项目里总被绕过，说明它对那个项目太强，应该下沉到项目层去适配。模板的分层逻辑和代码的分层逻辑本质上是一样的。

4.3 模板粒度和项目规模

模板粒度是团队里经常被争论的话题。小项目我就放一个几十行的CLAUDE.md，不搞目录和命令文件，因为没有那么多复杂场景；大项目才需要拆分成 commands 和 references，因为一个文件写不下。别陷入“必须把模板建得非常完整”的焦虑。模板本身是沉淀产物，先有内容再有结构。当你发现某个文件经常要翻到后半部分才能找到需要的规则时，那才是拆分的时机。

5. 常见问题与避坑实录

5.1 模板不生效

最常碰到的问题有三个。第一个是路径放错了，项目根目录的CLAUDE.md才是默认读取位，放在子目录里不会自动生效。第二个是优先级干扰，用户级模板和项目级模板同时存在，项目级优先级更高。如果你发现自己写的规则没生效，先问模型“当前项目有哪些代码约定”，看它答出来的内容里有没有你刚写的句子。第三个是格式问题，模板里如果堆满杂乱符号和不明语法，解析和权重都会受影响，尽量用清晰的 Markdown，少用花哨排版。

注意：模板不生效有时候是因为你改完文件但会话并没有刷新。如果确认路径和优先级都没问题，建议开一个新会话再试，因为很多工具是在会话开始时加载文件的。

5.2 上下文被撑爆

模板太长会导致上下文集被快速消耗。模型上下文窗口有上限，模板占得越多，留给任务背景和代码片段的空间就越小。这种情况下的典型表现是模型“变笨了”——不是模型能力下降，而是上下文预算被无意义的规则占掉了。我通常把单个CLAUDE.md控制在 200 行以内，超过的部分拆到按需读取的 references 里。这样既保留完整约定，又不会让常规会话背负全部上下文。记住一个原则：模板是让人尽快理解项目的速览，不是把所有历史决策都塞进去的档案库。

5.3 指令冲突

当用户级模板、项目级模板、命令模板都写满了规则，冲突是不可避免的。最典型的是测试框架的冲突：项目里用 Vitest，用户级模板里却写着“优先使用 jest”，模型在两套指令里左右为难，最后随机选了一个。解决办法是用更明确的措辞区分优先级，在项目文件里写“本项目使用 Vitest 作为唯一测试框架；与用户级配置冲突时以本文件为准”。模型需要一个断点判断权，你在模板里明确写清优先级，比重它自己推测可靠得多。

5.4 “万能模板”陷阱

很多人想做一个带大量参数的万能模板，通过修改变量来适配各种项目。我试过之后发现，这种模板越大，不确定性就越高。一个模板里塞了十几个条件分支，模型很难判断哪条适用，最后产出可能完全不符合预期。推荐反过来：做“少量模板 + 明确复用点”的架构。十个项目可以共用一份 react-ts base 模板，然后每个项目再加一个几十行的差异文件。差异文件越短，模板越稳。

5.5 模板风格 vs 代码风格

最后说一个容易被忽视的细节：模板本身也有“风格”。如果你在模板里写“所有代码必须加极详细的注释”，它会直接影响代码产出风格，但可能不符合项目偏好。我吃过这类亏：模板里强调“可读性优先”，结果模型给所有复杂表达式都补了一长串注释，代码看起来反而啰嗦。所以模板里定“用什么库、什么命名、什么测试框架”，可以很刚性；但涉及代码风格的地方，应该写成“符合项目现有风格，保持最小改动”，给模型留一点因地制宜的空间。

6. 个人心得与一点小技巧

6.1 一次改写让我看到了模板的上限

在模板这件事上我最大的体会是：模板是“好决策的沉淀”，不是“给 AI 的命令集”。我最有成就感的一次，是在团队模板里加了一句“新代码必须先写测试，再写实现”。仅仅这一行规范，配合工具的强制约束，整个仓库的测试覆盖率在一个月内提升了近十个百分点。模型没有变，工具没有变，变的只是默认决策的提示词。这件事让我意识到，模板的真正价值不在于它能写出多惊艳的代码，而在于它能把团队里那套“对的做法”固化下来，让每次生成都站在同一条基准线上。

6.2 给新手的入场建议

最后分享一个重要的小技巧：模板里不要只写“要做什么”，一定要写“不要做什么”。禁忌往往比倡导更有约束力。比如“不要为了满足 linter 而给代码补无意义的注释”“不要重构与本次需求无关的代码”“当你不确定数据库字段含义时，必须询问，不要自行猜测”。负向指令让模型在开放任务中更谨慎，因为它天生倾向于“多做”，模板的边界就是帮它把多余的动作挡住。

如果你刚开始接触 claude-code-templates，我建议从项目里最痛的一个点开始，比如测试约定、提交信息格式、目录规范。先写一个小的，跑一两个星期，观察它到底改变了什么，然后再逐步扩展。模板不是一次成型的东西，它更像一个会持续生长的记录，迭代的幅度越小，越容易保持干净。等你积累了几套顺手的工作流模板，再回头看最初手忙脚乱的那个阶段，会觉得这半小时的整理工作，其实是最值回票价的一次“元编程”。