企业官网建设流程全解析

1. 这套模板库到底在解决什么问题

1.1 我为什么开始收集 Claude Code 模板

先说背景。我大概在 Claude Code 刚开放命令行版本时就开始用了，一开始对它最大的感受是：很强，但也很“飘”。它不像传统 IDE 里的插件那样有明确的配置面板，一切交互都靠自然语言驱动。你用得好，它是资深结对程序员；用得不好，它就是个答非所问的话痨。

于是问题就来了：同样一个版本库、同样一个任务，有的人能让 Claude Code 自动完成一轮带单测的代码重构，有的人却在上下文里反复纠正风格、解释业务背景、补充边界条件，忙活一晚上也就改了半个文件。差别在哪？差在你有没有给它一套稳定的、可复用的“工作方法”。

claude-code-templates本质上就是一套给 Claude Code 使用的提示词、指令和配置文件的集合。我把它看作一个沉淀了团队规范和个人经验的“能力包”：你把这些模板放进项目或全局目录，之后每一次对话都自带这些背景和规则，不用每次都把需求从头解释一遍。这不是什么魔法，就是把重复劳动前置化，让模型在动手之前就知道你想要的产出长什么样。

1.2 没有模板时的典型翻车现场

我先说几个我真实踩过的坑，你看有没有同样遭遇。

第一个是“答非所问型”。我让它“给这个函数补单元测试”，它确实补了，但用了项目里根本不存在的测试框架，断言风格还是它自己编的。原因是我的项目里用了 pytest + unittest.mock，但对话里没交代，它默认按它训练数据里最常见的 Jest 风格生成，结果整个测试文件没法跑。

第二个是“风格漂移型”。第一天让它写 Python 模块，它写得挺规矩，类型注解、docstring、异常处理都齐了；第二天同样一个仓库，它突然不写类型注解了，函数命名也变成了另一种风格。原因是第一天对话里有人无意中说了“这个项目按 Google 风格来”，第二天没人说，模型就回到了默认习惯。这就是典型的口头约定失效，没有固化成模板。

第三个是“上下文爆炸型”。一个任务本来一两百行就能交代清楚，但因为没有把仓库规则、目录结构、命令习惯提前放进模板，我不得不在每次对话开头复制粘贴背景说明。一长串背景贴进去，真正要干活的指示被挤到后面，模型的理解重点反而错位了。

这些问题的共性，是“凭感觉协作”。人凭感觉猜模型的套路，模型凭感觉猜项目的规则，两个都猜不准。模板要解决的就是这件事：把项目里稳定不变的东西抽取出来，变成每次对话都自动加载的默认项，让模型把注意力留给真正需要考虑的增量信息。

2. 模板库的整体设计思路

2.1 按任务类型分层，而不是按语言分

我在设计这套模板时第一原则是：不要按编程语言去分，而要按任务类型去分。

市面上很多类似的提示词集，喜欢分 Python 专用、JavaScript 专用、Go 专用，我一开始也这么干，用了一阵发现维护成本极高。因为实际任务里，语言只是约束条件之一，更关键的是“这件事怎么干”：是修 bug、加功能、补测试、做重构，还是做代码审查？

同样是“补测试”，Python 项目和 TypeScript 项目的共同点远多于不同点：都需要先摸清被测对象的行为，都需要看已有测试的组织方式，都需要保证新测试不破坏 CI。语言差异只是在最后“生成代码”这个环节体现出来。所以我做成了一套“任务型模板 + 技术栈扩展模板”的组合：

• 任务型模板管工作流：如何理解需求、如何制定计划、如何动手修改、如何自检。
• 技术栈模板管知识约束：用哪个测试框架、遵循什么命名风格、依赖怎么管理。
• 角色型模板管视角：让你站在“代码审查者”还是“性能优化者”的角度思考。

这三层叠起来，就能覆盖 90% 的日常开发场景，又不会因为新增一个项目语言而推翻整个模板体系。

2.2 全局模板和项目模板拆开

这套模板库还有一个核心决策：把“通用规则”和“项目特化规则”拆成两层。

我参考了 Claude Code 本身的机制。它支持项目级的CLAUDE.md文件，放在仓库根目录，每次会话启动就会自动加载；也支持用户级的全局设置，放在~/.claude/下。于是我把模板库分成global/和project/两个目录。

全局模板放什么？放所有项目都不会变的做事原则。例如：

• 修改代码前先解释你的理解和计划，确认后再动手。
• 代码改动必须与现有风格一致，优先模仿同目录旧代码的写法。
• 禁止在没有测试保护的情况下直接重构核心逻辑。
• 每次输出代码都要给出简短的“改了什么、为什么改”说明。

项目模板放什么？放这个仓库特有的约束。例如：

• 这个项目用 pnpm 而不是 npm，锁文件是pnpm-lock.yaml。
• API 错误统一返回{ code, message, data }结构。
• 数据库迁移文件必须手写，不允许用 ORM 自动同步。
• 发布前必须跑pnpm lint && pnpm test。

这样拆分的好处很明显：换项目时，全局模板不用改，项目模板跟着仓库走。我甚至会把项目模板提交到代码仓库里，让团队所有成员共享同一套规则，新人进来第一天就能让 Claude Code 按团队规范干活。

2.3 模板的原子化是后期不烂尾的关键

另一个让我受益很大的设计思路，是“一个模板只干一件事”。早期我图省事，把“代码审查”和“生成文档”塞进同一个模板文件里，结果就是每次用它，模型都搞不清你到底是要它找 bug 还是写说明文档，常常两边都不讨好。

后来我把所有模板都拆成原子化的片段，每个片段只约束一个职责边界。比如审查模板只管挑刺，列出问题清单，不负责改代码；重构模板只管按既定目标调整结构，不做无关格式化；补测试模板只管生成测试，不顺手帮你优化被测函数。这样单个模板的指令长度很短，模型遵循起来特别稳定。

原子化还带来了一个额外的便利：可以自由组合。我做了几个“组合模板”，内部用分隔符把原子模板顺序拼起来。比如“重构并补测试”这个组合，实际上就是“重构模板”执行到改动结束，然后自动切换“补测试模板”接续干活。模型本身有不错的上下文理解能力，只要每个阶段的指令边界清晰，它就能顺畅地在不同工作模式之间切换。

3. 核心模板拆解与实操要点

3.1 CLAUDE.md：让规则成为默认配置

要说这套模板库里最重要的一个文件，那一定是CLAUDE.md。它相当于 Claude Code 每次启动对话前自动读取的“公司章程”。

我踩过很多次坑之后才意识到，CLAUDE.md不是越长越好，而是越“分层”越好。我见过有人把几千字的规范全部塞进去，结果模型加载了大量冗余文字，真正关键的约束反而淹没在里面。我的做法是控制在 150 行左右，只用短句列事实，不用长篇大论解释原因。

举个例子，我维护的某个 Python 服务项目，CLAUDE.md长这样：

# 项目概览 - 这是一个 FastAPI 写的异步任务调度服务 - Python 版本 3.11，包管理用 uv - 目录结构：app/ 存放业务代码，tests/ 存放测试，migrations/ 存放 SQL 迁移文件 # 代码风格 - 类型注解必须完整，禁止省略 - 函数 docstring 只写一句说明用途，不写参数细节 - 异步函数必须以 async def 定义，I/O 操作禁止用同步阻塞库 - 异常处理统一走 exceptions.py 里的自定义异常类 # 测试约定 - 测试框架用 pytest，异步测试用 pytest-asyncio - 单测文件命名 test_xxx.py，与模块同名 - 涉及外部 API 的测试必须打 mock，不允许真实调用 # 常用命令 - 本地启动：uv run uvicorn app.main:app --reload - 跑测试：uv run pytest -q - 代码检查：uv run ruff check .

写的时候有几个要点。第一，尽量用“禁止”“必须”这种强约束词，代替“建议”“尽量”这种模糊词，模型对确定性指令的遵从度要高得多。第二，把命令写清楚，这样它要跑测试或启动环境时不用猜。第三，目录结构一定要写，模型判断代码放哪、测试放哪，基本就靠这段描述。

3.2 任务型模板：五个覆盖日常的高频场景

我模板库里实际使用频率最高的任务型模板有五个：需求拆解、代码修改、补测试、代码审查、重构。每一个都向模型描述了完整的执行流程，而不只是一个目标。

以“补测试”模板为例，我给它定义了五步流程：

1. 读取被测模块代码，列出所有公有函数和类。
2. 检查 tests/ 目录下已有测试的组织方式和命名习惯。
3. 对每个公有函数，先看已有覆盖率，只补缺口。
4. 生成测试代码时，边界值和异常场景必须覆盖，接口 mock 清晰。
5. 写完后把测试跑一遍，保证新增用例全部通过。

这五步看起来简单，但效果立竿见影。模板跑起来后，Claude Code 会先自己列一个测试计划再动手，而不是上来就写一大段重复代码。我最直观的感受是，补出来的测试覆盖率从大概 60% 提到了接近 90%，而且不再有“为了覆盖而覆盖”的无效断言。

至于“代码审查”模板，我要求模型输出统一采用“问题 + 严重级别 + 建议修改 + 对应文件行号”的格式，并且明确划分阻断项和非阻断项。用了这个模板之后，审查报告读起来舒服多了，可以直接贴给同事看，不用我再整理。

3.3 角色型模板：换一个视角看同一个仓库

除了任务型模板，角色型模板也很有用。所谓“换视角”，就是让模型把注意力聚焦到一个特定关注点上。

我最常用的角色型模板有两个：一个是“安全审查官”，专门扫描 SQL 注入、敏感信息硬编码、权限校验缺失这类问题；另一个是“性能优化师”，专门分析循环体、N+1 查询、不必要的大对象拷贝。

它们的写作方式和任务型模板不太一样。角色型模板不定义完整工作流，而是定义“只看到什么、忽略什么”。比如安全审查模板的开头一段我写的是：

你现在是安全审查官。你只关心与安全相关的问题：注入风险、越权访问、敏感信息泄露、不安全的反序列化、缺失输入校验。你忽略代码风格、命名规范、性能细节。发现问题时，先解释攻击路径，再给出修复建议。

这段指令看似简单，但对模型行为的影响很大。它会强制模型进入“专职扫描”状态，而不是做一个全能评审。我在一次前端项目审查里，靠这个模板发现了三个真实的越权接口，都是平时人工 review 没注意到的。

不过要提醒一句：角色型模板的定位是辅助排查，不是万能扫描器。它不能代替静态分析工具和渗透测试，但它能在你改完代码之后快速给出第二双眼睛，性价比很高。

4. 模板怎么接入 Claude Code 并跑起来

4.1 模板目录结构与存放位置

整套模板我建议按这样的目录结构组织：

claude-code-templates/ ├── README.md ├── global/ │ ├── CLAUDE.md │ ├── code-review.md │ ├── write-tests.md │ ├── refactor.md │ ├── explain-code.md │ └── commands/ │ ├── review.md │ ├── test.md │ └── refactor.md └── project/ ├── python-fastapi/ │ └── CLAUDE.md ├── react-typescript/ │ └── CLAUDE.md └── go-service/ └── CLAUDE.md

global/下的文件是通用规则和通用模板，project/下是按技术栈或项目类型定制的规则片段。commands/目录我单独说明，它是用来实现自定义斜杠命令的。

我把这套目录直接放在我自己常用的几个开发机里，用软链接指到各项目的.claude/目录下。如果你们团队用 Git 协作，更建议直接把CLAUDE.md提交进各自的项目仓库，这样所有成员共享同一套规则。

4.2 用自定义 Slash Commands 把模板做成指令

自定义斜杠命令是模板落地最顺手的方式。我最常用的几个命令是/review、/test、/refactor，它们其实都是把我前面写的原子模板压缩成一个短指令。

实现方式不复杂。Claude Code 支持在.claude/commands/目录下放 Markdown 文件，文件名就是命令名。比如.claude/commands/review.md就对应/review命令。文件里的内容，实际上是一个高度精炼的指令集。

以/review为例，我文件里写的是：

对当前改动执行代码审查。按以下维度逐一检查：正确性与边界条件、错误处理、性能隐患、安全问题、可读性。忽略代码风格问题。输出格式： 1. 每条问题以 "文件:行号 - 问题描述" 开头 2. 标注严重级别：阻断 / 严重 / 一般 / 建议 3. 阻断和严重级别的问题必须给出修复建议 4. 最后汇总一句总体评价

写完这个文件，我在编辑器里选中要审查的改动，输入/review，Claude Code 就会自动按这套格式执行审查。整个交互从一大段自由对话变成了一个稳定可复用的标准动作，团队里其他人用起来也有统一预期。

4.3 模板内容的版本管理与团队同步

模板不是写一次就完事的，它会随着项目习惯演变而调整。我用几个简单的办法保持版本同步：

第一，模板库本身做成一个 Git 仓库，每次修改都提交并写明原因。这样谁改了什么规则、为什么要改，都有据可查。

第二，项目级CLAUDE.md和代码一起进同一个 Git 仓库。正好代码合并请求里如果改了测试约定或命令规范，review 的人能看到这个变化，团队就不会出现“代码改了但规范文档没跟上”的情况。

第三，定期做一次“模板瘦身”。我每两三个月会把模板里已经失效的规则清掉。比如某个项目原来用setup.py构建，后来切到pyproject.toml，如果没清理旧规则，模型就会在新对话里混淆构建方式。保持模板和实际工具链同步，比什么都重要。

5. 实际使用中的问题与避坑清单

5.1 模板越长效果越差，原因不在模型

我用这模板踩过的最大一个坑，是一开始把CLAUDE.md写得太长。我原以为给的信息越多模型越懂，结果恰恰相反。那一次我写了两百多行，包含大量背景说明、设计理由、历史决策。模型确实读了，但真正关键的执行步骤在超长上下文中被稀释了，它在改代码时仍然按照自己的默认习惯来。

后来我做了个对比实验：同一份代码，一个用精简到 80 行的CLAUDE.md，一个用 200 行的详细版本，各执行同样的重构任务。精简版的重构方案完全符合团队风格，详细版反而出现了不少奇怪偏离。原因是很多“背景说明”其实与当前任务无关，模型在读入的时候也抓不准优先级。

所以我的经验是：模板里只留事实描述和硬性约束，一切“解释性”文字全部删掉。别写“这是一家金融公司的核心交易系统，因此稳定性极其重要”，直接写“该模块禁止使用淘金式异常捕获，必须明确处理每个错误分支”就够了。模型不需要懂业务背景，它只需要知道现在怎么做。

5.2 角色模板互相打架怎么办

当你同时用多套模板时，可能出现“打架”的情况。我一开始把它当 bug 处理，后来才意识到，其实是一个优先级问题。

典型场景是：项目CLAUDE.md里规定了“所有对外函数必须写完整类型注解”，但某个角色模板是“性能优化师”，它为了减少运行时开销，可能会建议去掉不必要的类型检查。这时候到底听谁的？

我的解法是在每个角色的模板开头加一句“优先级声明”。比如：

本模板专注性能优化。除安全问题外，不改变项目的代码风格与类型规范。风格规范以项目 CLAUDE.md 为准。

这句话本质上是在告诉模型：你的任务是提建议，不是改项目规则。有了这种优先级声明，角色模板就只会聚焦在它该管的维度上，不会越界推翻全局约定。类似的，我还会在项目CLAUDE.md的末尾加一行“如果与项目内其他指令冲突，以本文件的硬性约定优先”。

5.3 模板没覆盖边界条件时，代码仍然偏薄

模板能规范流程，但解决不了“模型想不到的边界情况”。比如我让它用模板生成一个文件上传接口，它做得有模有样，但没考虑磁盘满、文件名非法、文件大小超过限制这些分支。不是说模板没用，而是模板要在流程上预留“自查边界”这一步。

所以我在“代码修改”类模板里都加了一个固定步骤：完成主逻辑后，主动列出这个改动涉及的三类边界条件——输入异常、资源限制、并发冲突，并确认每一类都有明确处理。这招非常管用，因为它把“思考边界”从可选项变成了必选项，模型每次都会真的停下来检查一遍，而不是直接输出完事。

5.4 多仓库项目怎么让模板不串味

我会在多个项目之间切换，最怕的就是上一个项目的规则串到下一个。比如一个项目禁用any，另一个项目恰好相反，模板如果不隔离，模型就可能把上一个项目的禁any规则带过来。

解决办法其实很简单：项目级模板只放在项目仓库里，同时全局模板保持最小化。不要试图建立一个“覆盖所有项目”的统一规范，尤其不要在全局层写类似“所有 Python 代码必须做类型注解”这种话，因为总有项目不这么要求。要紧的规则全部下沉到项目级，全局只留最普适的协作原则。

还有一个细节，我会在切换项目时，主动清掉 Clude Code 的旧会话，而不是继续在一个会话里跨仓库对话。旧会话里残留大量上一项目的上下文，比模板串味更难清理。新开一个会话，让新项目的CLAUDE.md干净加载，才是正确的用法。

6. 从模板库到团队工作流的一点体会

模板库做到这一步，其实已经不只是一个技术分享了。我在实际维护中发现，模板内容本身就代表了团队对“代码应该怎么写”的共识。今天你往CLAUDE.md里加了“禁止在业务层拼 SQL 字符串”，明天模型就会严格警告任何人这么干；今天你删掉了某条过时规则，明天新人提交的代码就会立刻反映这个变化。

所以我现在看这套模板库，它更像是“把团队代码评审意见汇总成了一份可执行文档”。以前 code review 里反复提到的问题，现在模型在生成阶段就提前避免了；以前要花很多时间口头交代的项目背景，现在模型天然就懂。省下来的时间被用在了更值得关注的事情上，比如复杂业务逻辑的设计和跨团队协作。

最后分享一个个人习惯：我不追求模板大而全，只保证每一条规则都是当前项目真正需要的。写进模板的每句话，都要有对应的实际场景；没有达成共识的规则，绝不提前写进去。这个原则让我避开了所有“模板管理本身变成负担”的坑。模板是为干活服务的，它永远不应该比干活本身更复杂。