企业官网建设流程全解析

1. 我为什么要维护一套 Claude Code 模板

这个模板库的代号就叫 "claude-code-templates"，但重点不在于名字，而在于它背后的一整套设计思路。我维护它的出发点，是想解决一个很具体的问题：同一个 Claude Code，在不同项目里的表现可以天差地别。同一句话，在一个仓库里它马上能定位到核心模块，在另一个仓库里却只会泛泛而谈。差别不在模型本身，而在你有没有把项目的运行方式提前告诉它。

Claude Code 是一个跑在终端里的 AI 编程环境，它可以读文件、跑命令、看测试输出、修改代码。但你真正让它发挥价值的地方，往往不是"你说一句，它做一步"，而是让它具备对项目上下文的理解。这个上下文从哪里来？就是从 CLAUDE.md、从 .claude 目录下的命令、从你预设的一堆规则和模板里来。

1.1 Claude Code 的"配置坐标"速览

我习惯把 Claude Code 的配置分成三个层次：

• 用户级配置：~/.claude/CLAUDE.md，放在 home 目录下，对所有项目生效。一般只放与项目无关的通用偏好，比如"改代码前先跑测试""遇到不确定的需求先问而不是猜"。
• 项目级配置：项目根目录下的CLAUDE.md，或者新版推荐的.claude/CLAUDE.md。这里写的是这个仓库独有的信息：模块结构、技术栈、启动命令、代码风格、常见坑。
• 项目命令与扩展：.claude/commands/下的 markdown 文件，每个文件就是一个斜杠命令；.claude/agents/下的文件是子代理；.claude/hooks/下则是各种事件钩子。

claude-code-templates 要做的，就是把这三层里可以复用的部分抽取成模板，放在一个独立的仓库里，需要的时候拿过来，按项目微调。这样你换机器、换项目、甚至换队友时，得到的都是同一套稳定的协作方式。

1.2 模板化解决的真实痛点

不用模板的时候，我遇到过几类问题。

第一类是"每次都要重说"。新建一个项目，第一次对话总得花几百字告诉它技术栈是什么、测试命令是什么、别去动哪些目录。一次两次还能忍，项目多了就明显浪费 token 和时间。

第二类是"指令漂移"。同一个项目的配置，今天写一段，明天改一段，最后 CLAUDE.md 又长又乱，Claude 的注意力被稀释，反而抓不住重点。模板不一样，它在设计阶段就规定了结构，后面往约定的格子里填充内容就行。

第三类是"团队不可复制"。我自己调好的配置，换一个人来用，可能又要从头摸索。如果所有配置来自同一套模板，团队里任何一个人 pull 下来都能得到一致的工作方式。

所以模板化不是"把事情搞复杂"，而是把 Claude Code 的使用经验沉淀成资产。这也是我坚持用独立仓库维护 claude-code-templates 的原因：它不该散落在某个项目的 .gitignore 里，而应该成为你自己的基础工具集。

2. CLAUDE.md：项目级模板怎么设计

CLAUDE.md 是整个模板库的核心。它决定 Claude 进入这个仓库之后，第一眼看到什么，后续每次对话默认带着什么上下文。我接下来会给出一个具体的骨架，但先讲清楚设计的思路——因为它直接影响后面所有命令模板的表现。

2.1 我固定的五个段落

我设计 CLAUDE.md 时，不会让它变成一本百科全书，而是固定五个段落，让每个项目都能在这五个段落里找到自己的位置：

1. 项目定位：用一两句话说清楚这个仓库是干什么的，目标用户是谁。作用是帮 Claude 判断哪些改动是合理的，哪些会偏离产品方向。
2. 快速命令：开发、构建、测试、lint 这些最常用的命令，直接给可执行的具体命令，不要写"运行测试"这种模糊表达。
3. 结构地图：核心目录是哪些，各层之间的依赖方向是什么。不用列全所有目录，只列关键路径。Claude 遇到问题时会优先看这些地方。
4. 代码约定：命名风格、错误处理方式、状态管理方案、API 设计约束。这一块是项目差异最大的地方，也是最容易让它写出风格不符代码的地方。
5. 禁忌清单：不能碰的目录、不允许用的工具、既定的历史决定。比如"不要改 migrations 目录下的历史迁移文件""不要用 axios，统一用项目封装的 request"。

这五段不是硬性模板，更像是一个约束框架。你会发现，任何项目都能套进去，但填出来的内容完全不同，这就达到了"模板可复用、内容项目化"的目的。

2.2 "模块化导入"与 @path 的使用

CLAUDE.md 可以很长，但这不一定好。因为 CLAUDE.md 的内容会在对话中被反复用作上下文，塞得太多会挤压模型处理真正任务的空间。我的经验是：把大段内容拆成独立文件，在主 CLAUDE.md 里用 @path 语法引用。

例如项目里有 docs/architecture.md，这是一份很长的架构文档，你不想让 Claude 每次对话都读完几千字，那么可以在 CLAUDE.md 的"结构地图"段落写：

@docs/architecture.md

这样当 Claude 需要理解架构时，它会主动去读对应文件，而不是在每次对话中被动加载一份大文件。

注意：@path 导入会实际读取文件内容，你有多少，它就会读多少。所以放在被引入文件里的东西，同样需要遵守"薄模板"原则，绝不能因为是独立文件就无限堆量。

分离文件还有一个好处：可以单独更新，不影响主模板的稳定。比如架构文档每周在变，主 CLAUDE.md 只写一句"架构请参考 @docs/architecture.md"，就避免了主文件的频繁变动。

2.3 一个可以直接抄的 CLAUDE.md 骨架

下面是我自己在 claude-code-templates 里用的项目级 CLAUDE.md 骨架，你可以直接复制改：

# 项目：xxx ## 项目定位 这个仓库是做什么的，面向谁，核心价值是什么。 请不要偏离这个定位去做功能扩张。 ## 常用命令 - 安装依赖：npm install - 开发启动：npm run dev - 单元测试：npm test - Lint：npm run lint - 构建：npm run build ## 结构地图 - src/main：应用入口，负责启动流程 - src/core：核心业务逻辑，不依赖框架 - src/http：接口层，只做参数校验和响应封装 - docs/architecture.md：整体架构说明，涉及跨模块设计前先读它 依赖方向：core 不依赖 http，http 依赖 core。新增功能优先放 core。 ## 代码约定 - 接口返回统一结构：{ code, data, message } - 业务错误用自定义错误类，不用字符串 throw - 异步一律用 async/await，禁止裸 .then 链 - 命名：组件用 PascalCase，函数用 camelCase ## 禁忌清单 - 不要修改 migrations 中已提交的历史文件 - 不要在业务代码里直接访问第三方 API，统一走 gateway - 不要删除测试夹具里的 fixtures，除非同步更新对应测试

这个骨架的精髓在于：每一条规则都是"可执行、可验证"的，而不是"请写出高质量代码"这类空话。它告诉 Claude 的是边界和偏好，而不是空洞的要求。

3. 斜杠命令模板：把重复操作变成命令

如果说 CLAUDE.md 负责让 Claude "懂"这个项目，那么斜杠命令就是让你快速复用一套固定的工作流程。比如 review、test、commit、refactor，我都会把它们写成命令模板。模板一旦写好，每次敲/%命令都会得到一致的行为，不会被临场措辞影响。

3.1 front matter 字段详解

.claude/commands/下的每个.md文件代表一个斜杠命令。文件头部用 YAML front matter 写元信息，正文部分就是真正发送给 Claude 的指令。最常用的字段有：

description 这一点特别容易忽视。它不是给你自己看的，而是给斜杠命令菜单看的。写得好，下次输入/的时候你一眼就能想起这个命令是干什么的。写得太含糊，命令再强你也懒得用。

命令正文还支持一些模板变量，比如$ARGUMENTS代表用户在斜杠命令后输入的全部参数，$1代表第一个参数。在正文里写"如果 $ARGUMENTS 为空，先问我三个问题"，就能做出可交互的命令。

3.2 三个高频命令模板：review、test、commit

我挑三个最常用的命令，把模板直接贴出来。

首先是/review，做代码审查。它的优点是会把审查维度固定下来，不会每次问法不一样。

--- name: review description: 对本次改动做代码审查，输出问题清单与严重级别 --- 代码审查。只检查当前尚未提交的改动。 审查维度： 1. 正确性：有没有边界条件未处理、返回值缺失、异常吞噬。 2. 一致性：是否符合根目录 CLAUDE.md 中的代码约定。 3. 可测试性：新增逻辑是否容易被测试覆盖，如果能拆更小单元就指出。 输出格式： - 每个问题按 `文件:行号 [严重级别] 描述` 输出。 - 严重级别分为 blocker / major / minor / suggestion。 - 最后给出修复建议，不要直接改代码，等确认后再动。

这个命令最核心的点在于"不要直接改代码"。代码审查工具最怕的是它顺手把代码改了，你说的是 review，它返回来一堆 diff，反而打断节奏。固定"只审不改"之后，审查质量明显上升。

其次是/test，用于定位测试失败原因：

--- name: test description: 运行指定测试文件并分析失败原因 --- 运行测试并分析。 1. 先运行 `npm test -- $1`，如果 $1 为空则运行 `npm test`。 2. 如果测试失败，优先看最近一次改动。 3. 输出失败摘要，包括：失败用例名、期望值、实际值。 4. 如果是红灯，只分析不修复，给出修复方案后等我确认。

写这个模板是因为我发现 Claude 在调试测试时容易陷入一个坏习惯：看到失败就马上改代码，而不是先看失败原因。强制它先运行、再分析、最后等待确认，能减少很多无效改动。

最后是/commit，统一提交信息风格：

--- name: commit description: 根据当前改动生成符合约定格式的 commit message --- 查看 git status 和 diff，生成 commit message。 - 类型使用：feat / fix / refactor / docs / test / chore。 - 正文说明为什么做这件事，而不是只列举改了哪些文件。 - 如果改动涉及破坏性变更，在 footer 标注 BREAKING CHANGE。 - 不要执行 git commit，把建议 message 给我确认。

注意，最后的"不要执行 git commit"非常关键。我见过太多次它把包含临时日志、实验代码的改动直接提交进仓库。模板里明确写上"给我确认"，这个安全的习惯能省掉后续很多 git 历史的麻烦。

4. 技能与代理：进阶模板的边界

CLAUDE.md 和斜杠命令能解决大部分日常工作。再往后走，就到了子代理和钩子的层面。这一层不是所有项目都需要，但 claude-code-templates 里我会为它们预留位置，因为当项目复杂度上涨时，它们往往是让协作再上一个台阶的关键。

4.1 代理模板与命令模板的区别

子代理定义放在.claude/agents/下，也是一个 markdown 文件，用 front matter 描述它的名字和定位，正文写它的行为说明。和斜杠命令最本质的区别是：斜杠命令是在当前对话里执行一段固定的指令，而子代理是一个独立的执行单元，你可以在主对话中让它去跑一个子任务，它用独立的上下文和工具集运行，结束后把结果汇报给你。

在设计模板时，我会把"需要深度搜索代码库"的任务做成子代理，比如"模块梳理""测试影响面分析"；把"有明确格式输出"的任务做成斜杠命令，比如 review、commit。因为子代理可以带上专门的工具配置和更聚焦的指令，不会被主对话里冗长的上下文干扰。

比如一个子代理模板.claude/agents/impact-analyst.md：

--- name: impact-analyst description: 分析一个改动的影响面，列出受影响的模块与测试 --- 你是影响面分析专家。 任务：给定一处改动，找出它影响的所有模块、调用方和测试用例。 规则： 1. 顺着依赖反向查找引用方，不只读直接调用处。 2. 对每个影响点标注影响程度：直接 / 间接 / 潜在。 3. 输出时给出建议的验证路径，如需要运行哪些测试。

这个代理不需要有"改代码"的能力，它的价值在于把"影响面分析"这个容易漏掉细节的动作稳定地做出来。模板里给它的规则越收敛，结果越可预期。

4.2 钩子模板：把自动化前置

钩子比命令和代理更"底层"。它是在事件发生时自动运行的脚本，比如每次用户输入前、每次 Claude 要调用工具前、每次一轮对话结束之后。配置写在.claude/settings.json或.claude/settings.local.json中。

我用的比较多的一个模板是 PreToolUse 钩子，用来拦截对危险命令的直接执行：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git reset --hard)|Bash(rm -rf)", "hooks": [ { "type": "command", "command": "echo '危险命令被触发，已阻止。请先确认操作目标再重试。' && exit 2" } ] } ] } }

这个钩子模板的效果是：当 Claude 打算执行git reset --hard或rm -rf这类破坏性命令时，先被拦截下来，输出一句提示直接退出本次工具调用。配置成本极低，但对防止误操作很有价值。如果你用的版本支持更细的 matcher 语法，还可以加上路径参数，比如只针对包含node_modules的rm -rf做拦截。

4.3 MCP 与工具白名单的取舍

在钩子之外，另一个经常被问到的点是 MCP。Claude Code 可以通过 MCP 接入外部工具，比如数据库、搜索引擎、内部 API。我的建议是：模板里不要把 MCP 工具一股脑全开，而是在命令或代理的 front matter 里用 allowed-tools 做白名单。

为什么？因为 MCP 工具暴露得越多，模型执行时选择面越广，出错的概率也越高。一次只让它碰它这次任务真正需要的工具，结果会稳定得多。这也是 claude-code-templates 里始终保留 allowed-tools 字段的原因：它迫使你在做模板时思考"这个命令到底需要哪些能力"，而不是偷懒地把所有能力都堆上去。

5. 模板库的版本管理与落地经验

模板写到这份上，剩下的问题就是"怎么把它真正用起来"。我见过不少人收藏了一堆配置，但项目里根本没人用，最后变成摆设。要走完最后一公里，需要一点工程化的心态。

5.1 按项目做覆盖层

我维护 claude-code-templates 的方式是：模板仓库只放通用部分，然后通过复制或子模块把它引入具体项目，再在具体项目里创建一个覆盖层。

具体做法是：

• .claude/目录下有基础文件，比如 commands、agents、CLAUDE.md 的骨架。
• 项目里如有特殊命令，放在.claude/commands-local/或直接在项目内新增同名文件做覆盖。
• 对于 CLAUDE.md，根目录的通用模板不要改，把项目专属说明单独拆到 IMPLEMENTATION.md，通过@导入主文件。

这么做的好处是通用模板可以随主仓库更新，而项目专属内容不会被上游覆盖。复制一份到项目里会有一个缺点：上游更新后，项目不会自动同步。如果你不想自己手动比较 diff，可以像我一样每周留一个固定时间，把项目里的.claude目录和模板仓库做一次对齐，同时坚持在 CHANGELOG 里记录每个模板变更的原因。

下面是一份我实际在用的 changelog 片段：

2025-01-12 调整 review 命令： - 增加 suggestion 级别，避免所有问题都是 major - 新增"不要直接改代码"约束，减少误提交 2025-01-05 新增 impact-analyst 子代理模板 - 用于改动影响面分析

5.2 让模板保持"薄"

这是我踩过最大的坑，也是最想提醒你的地方：模板会自发膨胀。一开始你写三条禁忌，过两周变成十条，再过一个月，CLAUDE.md 比项目的 README 还长。此时 Claude 的行为反而不稳定，从模板抓不到重点。

我的判断标准很简单：每条指令都要能回答"如果删掉它，会发生什么可感知的偏差"。如果删掉后功能照跑，只是你心里有点不安，那这条就不该保留。规则和配置不是收藏品，它的价值在于改变行为，不在于存在本身。

上下文预算也要算。Claude Code 有上下文窗口，但窗口再大也经不住每轮对话都把几万字配置反复注入。把大文档拆出去、把过时指令清理掉、把可以收敛成命令流程的规则合并起来，这些动作和写代码一样需要重构。

5.3 我维护这套模板的四个检查项

最后分享我每次更新模板时都会过的四个检查项，算是长期实践下来的一个 checklist：

1. 可读性：如果用一个没有任何背景的新人视角去读这份模板，他能不能看出每条规则为什么存在？如果不能，修改表述。
2. 可验证性：每一条规则是否能被某个命令或某个测试流程验证？比如"遵循项目代码风格"这种话没法验证，但"不要用 axios"可以。
3. 最小化：这条规则是否和现有某条重复？重复会稀释权重，宁可合并成一条更强的规则。
4. 边界感：这条规则是在约束 Claude 的行为，还是在代替项目经理做决策？模板应该管"怎么做"，不该管"做什么"。

这四个检查项看起来简单，实际执行起来很考验取舍能力。模板库的维护，本质上是不断搞清楚"哪些东西值得用固定规则固化下来，哪些东西应该留给模型临场判断"。

我在实际项目里的体感是：刚开始沉淀模板的那两周，时间是明显多花了，但后面每次新项目初始化、每次做 code review、每次让 Claude 跑测试，都比以前顺得多。模板真正值钱的地方，不是让你少打几行字，而是让你和 Claude 的协作方式变得可以被预期、被复用、被改进。如果你也开始维护自己的 claude-code-templates，建议先用最少的规则跑一个项目，再根据真实遇到的问题逐步加长，别一步到位，这种"薄模板起步、按需生长"的方式是我目前最推荐的做法。