企业官网建设流程全解析

1. 先说结论：模板决定了 AI 编码助手的体验上限

用了好几个月的 claude-code 之后，我最大的感受是：这个工具好不好用，七成取决于你给它的模板够不够好。刚上手时我也跟大多数人一样，直接在终端敲claude开干，问什么答什么，写什么补什么，结果就是典型的"AI 泛泛而谈"——代码能跑但风格混乱，重构会做但不敢动边界，测试写了但覆盖率全靠运气。

后来我把项目里沉淀出来的套路一点点固化成了CLAUDE.md、斜杠命令、hooks 这类"模板资产"，体验才真正发生了质变。同一段代码交给它 review，之前只能挑出几个风格问题，现在能直接指出潜在并发风险和数据一致性问题；同一个重构需求，之前要来回拉扯好几轮，现在一条命令下去，它连改动方案和自测清单都给你列好了。

这篇内容就是把我自己从"裸奔式使用"到"模板化驱动"的完整过程整理出来，包括我踩过的坑、验证过的写法、以及每个模板文件背后的设计理由。适合的人群是：已经在用或准备用 claude-code 的开发者，尤其是那些觉得"AI 写的东西总差那么点意思"的人。看完你至少能照着一套落地，把自己项目里的模板库搭起来。

2. 配好地基：我那套两层的 CLAUDE.md 结构

2.1 用户级和项目级怎么分工

先纠正一个常见的误解：很多人以为 CLAUDE.md 只能放在项目根目录，其实它有两个层级。

• 用户级：放在~/.claude/CLAUDE.md，相当于给 claude-code 加载的"全局人格设定"，描述的是你这个人的编程偏好，比如"方法名用动词开头、变量名不用缩写、提交信息用 conventional commits 格式"，这些跟具体项目无关的习惯性要求，都放这一层。
• 项目级：放在项目根目录，描述的是"这个项目"的上下文，比如技术栈选型、目录结构、启动命令、常见坑位。项目级的内容会被每个进入这个仓库的 claude-code 实例自动读取。

我一开始犯的错是什么？就是把所有东西都堆在项目级 CLAUDE.md 里。结果每个项目 Copy 一份不说，改了全局习惯还得挨个同步。后来把"个人偏好"和"项目事实"彻底分开，两边的维护成本都降下来了。

2.2 项目级 CLAUDE.md 我到底写了什么

直接上我目前在用的一个模板结构，你可以照着填：

# 项目概况 一句话说明这个项目是做什么的，核心业务价值是什么。 # 技术栈 后端: Python 3.11 + FastAPI 前端: React 18 + Vite 数据库: PostgreSQL 14 + Redis 7 # 目录结构 app/ # 核心业务代码 api/ # 路由层 services/ # 业务逻辑层 models/ # ORM 模型 tests/ # 测试目录，按照模块镜像 scripts/ # 运维脚本 # 常用命令 依赖安装: pip install -e . -r requirements.txt 启动开发: uvicorn app.main:app --reload 跑测试: pytest tests/ -x -q 代码检查: ruff check . && ruff format . # 容易踩的坑 - DB session 必须在 service 层统一管理，不能直接在 api 层建立 - 新加 Redis key 必须带项目前缀，防止与其他项目冲突 - 修改 models 层字段后必须先生成迁移再跑测试

每一条都有讲究。"项目概况"不是废话，是给 Claude 建立业务上下文——它知道这是个电商订单系统还是日志采集平台，才能在做技术决策时给出更贴合的方案。"常用命令"这节看似琐碎，实际非常关键：Claude 经常需要自己跑命令验证代码，你提前告诉它标准命令是什么，它就少猜一次，也就少一次乱装依赖或跑串脚本的机会。

"容易踩的坑"是我自己最得意的一节。Claude 哪怕再聪明，对项目里前人趟过的雷一无所知。你把坑写进去，它就相当于站在你团队的经验上干活，很多隐性约束直接变成显性规则，省掉了反复踩雷、反复解释的沟通成本。

2.3 写得短比写得全更重要

这是我从惨痛教训里换来的认知。最开始我恨不得把整个项目的架构决策全都写进 CLAUDE.md，写了两千多字，结果发现 Claude 反而变傻了——上下文被无关信息填满，真正重要的规则被稀释，回复变得拖沓且重点模糊。

现在的原则是：项目级 CLAUDE.md 控制在 600 到 800 字以内，只写"这个项目里不可推断、不得不说明"的事。技术栈其实可以从源码推断出来，但启动命令、目录约定、隐性约束是 Claude 没法从代码里直接看出来的，这才值得写。能用代码结构表达的东西，永远不要用文字再解释一遍。

3. 按任务裁剪：三个每天都在用的高价值模板

CLAUDE.md 解决的是"全局上下文"问题，但具体到一次 review、一次重构、一轮测试，你还需要针对性的指令模板。我试过直接在对话里打一大段需求描述，每次都要重新组织语言，麻烦不说，效果还不稳定。后来我把高频任务做成了三个模板，输入输出质量立刻上了一个台阶。

3.1 代码审查模板：从"看风格"进阶到"看风险"

原始版本的 review 请求是"帮我 review 一下这个文件"，Claude 的默认行为是给你吐一堆"代码风格统一、函数命名规范、建议补充注释"这类正确的废话。问题在于，这些评论对资深开发者几乎没有价值。

我现在用的是这样一个结构：

[任务] 对以下代码变更进行代码审查 [审查重点] 1. 正确性：是否存在边界条件遗漏、空指针风险、并发问题 2. 数据一致性：数据库操作是否有事务保护，缓存与 DB 是否可能不一致 3. 安全性：是否存在注入、越权、敏感信息泄露风险 4. 可维护性：改动是否与现有架构一致，是否有重复逻辑 5. 性能：是否存在明显不必要的循环、N+1 查询、大对象常驻内存 [输出格式] 按严重程度从高到低输出，每一条标注：文件位置 / 问题说明 / 为什么是问题 / 修改建议 如果某部分没有问题，直接跳过，不要输出无意义的"看起来很好"

关键在"按严重程度输出"和"没问题就跳过"这两条约束。它们逼着 Claude 做优先级判断，而不是机械地罗列凑数。实测下来，我把同一段有并发隐患的代码分别用默认模式和这个模板 review，默认模式完全没提到竞态条件，模板模式则直接指出了check-then-act的经典 bug，还给了加锁方案。

3.2 重构模板：先给方案再动代码

重构是另一个高频场景，也是最容易跑偏的场景。Claude 做一个几百行的重构时，经常改着改着就偏离了原始目标，顺带把无关代码也优化了一遍——这在大项目里简直是灾难。

我的重构模板是这样约束它的：

[任务] 对 {目标模块} 进行重构 [重构目标] 不要修改任何外部行为，只调整内部结构 [范围约束] - 只允许改动以下文件列表：{文件列表} - 对外接口签名、返回结构保持不变 - 不允许顺手优化无关代码 [执行流程] 1. 先分析当前结构的核心问题，输出重构方案 2. 方案里必须列出涉及的方法、改动前后的结构对比 3. 改完后跑 {测试命令}，确保所有测试通过 [特别提醒] 如果有任何地方让你觉得"忍不住想顺手改"，先停下来，把它记录到"额外发现"列表里，不要直接改。

"范围约束"和"不允许顺手优化无关代码"是我用血泪换来的。Claude 的"发挥主动性"在重构场景里是个双刃剑，你让它重构订单模块，它能顺手把用户模块的命名规范也改了，然后整个 PR 的 diff 失控，你 review 起来想哭。加了这两条之后，它的行为边界清晰了很多。

3.3 测试生成模板：用行为描述引导测试思路

写测试是 Claude 的强项，但默认模式下它生成的测试往往有个通病：为了覆盖率而覆盖，测试逻辑跟实现逻辑高度耦合，几乎没有"防御性"价值——也就是说，实现改动后测试也会跟着挂，测试根本没起到保护作用。

我的测试模板核心思想是：让 Claude 先描述行为，再写测试代码。

[任务] 为 {模块} 生成单元测试 [步骤1] 先阅读源码，列出该模块所有外部可观察行为，包括： - 正常输入的预期输出 - 边界输入（空值、最大值、格式错误）的处理 - 异常路径的抛出方式 [步骤2] 基于行为列表编写 pytest 测试 [约束] - 每条测试用例使用 given-when-then 注释说明行为 - 禁止为了通过测试而放松断言 - 每个测试函数只测一种行为 [输出] 直接输出可运行的测试代码，并列出哪些行为暂时无法覆盖以及原因

加了这个模板之后，生成的测试质量变化很明显——Claude 会主动设计边界条件的测试用例，而不是照抄实现代码里的分支。有一次我改了排序算法的中间逻辑，但保持了外部行为不变，旧方式生成的测试全挂了，新方式生成的测试几乎原样通过，那一瞬间我真实感受到了模板的价值。

4. 把模板收编成命令：斜杠命令和 hooks 的落地

4.1 自定义斜杠命令：把 prompt 模板固化为一等命令

模板每次都手动复制粘贴还是太低效。claude-code 支持把 Markdown 文件放到.claude/commands/目录下，自动注册成斜杠命令。文件名就是命令名，文件内容就是你想要塞给它的指令。

我现在的命令目录长这样：

.claude/commands/ ├── review.md # /review 代码审查 ├── refactor.md # /refactor 重构辅助 ├── test.md # /test 生成测试 ├── commit.md # /commit 生成提交信息 └── explain.md # /explain 解释一段代码

每个文件的内容其实就是第三节里那些模板的完整版，不过是把变量部分用了个运行时占位符。比如review.md的开头是：

请对我的代码变更进行审查，审查重点包括正确性、数据一致性、安全性、可维护性、性能五个方面。请按严重程度从高到低输出，每条标注文件位置、问题说明、为什么是问题、修改建议。如果没有发现问题，直接说"未发现重要问题"。当前变更的具体内容如下：

实际使用的时候，我会在斜杠命令后面额外补充文件名或路径范围，比如/review app/services/order.py。Claude 会把我补充的文本和命令模板的内容合并理解。这套机制的好处是：模板只需要维护一份，所有人都用同一套标准，不会出现"今天的 review 标准和昨天不一样"的情况。

4.2 hooks：在关键动作前后自动执行检查

如果说斜杠命令是你主动调用模板，那 hooks 就是让模板在关键时刻自动生效。我用得最多的是两类：

第一类是PostToolUse钩子，作用是每次 Claude 写完文件后自动跑代码检查。举一个具体配置思路的例子：当你给 claude-code 配了"编辑文件后自动执行ruff check"这类钩子时，它一旦输出不符合规范的代码，会在同一个会话里直接被纠正，不用你亲自盯输出、再手动反馈一遍"这代码风格不对"。长会话里这个钩子的价值极大——Claude 不会因为对话轮数多了就把风格越写越跑偏。

第二类是PreToolUse钩子，作用是在 Claude 执行敏感命令前拦截确认。比如某些部署命令，你可以在钩子里设定规则：除非用户输入了明确的确认口令，否则不允许执行。这比单纯依赖对话记忆要硬得多。

hooks 的配置位置通常在.claude/settings.json里，类似这种结构：

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "ruff check --fix $(echo $CLAUDE_FILE_EDITED | xargs dirname | head -1)" } ] } ] } }

每次 Claude 改完文件，系统都会自动对相关目录做一次代码规范检查。如果检查失败，Claude 通常会看到错误输出并主动修复，实现一定程度的"自纠错"。这类机制的原理是：把人工反馈循环变成自动反馈循环，让模型的质量收敛速度显著变快。

4.3 权限配置：模板里必须划清楚的红线

Claude 有时会自行猜测它可用的命令全集。为了不让它做一些越权的操作，我在.claude/settings.json里做了权限约束。思路很简单：默认宽，关键命令就必须显式确认。

比如说，我会把只读命令放进允许清单，不需要每次确认；而rm -rf、直接修改生产环境配置、执行部署脚本这类命令，则必须经过我手动确认。Claude 执行这些命令前会停下来询问，这样即使模板里写了"自动执行测试""自动部署"之类的流程指示，最终的关键动作仍然卡在你手里。

这里有个团队协作的额外考虑：如果模板和权限配置只存在你本地，换台机器、换个同事就全部失效。所以我会把.claude/整个目录放进 Git 仓库，让每个人 clone 下来就得到了同一套命令、同一套 hooks、同一套权限边界。这就是"模板库"的概念开始成型的地方。

5. 模板库的长期运营：从个人配置到团队资产

5.1 用 Git 管理模板仓库

刚开始我的模板都是散落在各个项目.claude目录里的零散文件，直到有一次想在新项目里复用，才发现要一个个项目去翻找，痛苦至极。

后来我建了一个独立的模板仓库，结构是这样的：

claude-code-templates/ ├── project/ │ ├── CLAUDE.md # 项目级 CLAUDE.md 的通用骨架 │ └── commands/ # 通用斜杠命令 │ ├── review.md │ ├── refactor.md │ └── test.md ├── user/ │ └── CLAUDE.md # 用户级 CLAUDE.md 模板 ├── hooks/ │ ├── post-edit-check.json # 编辑后自动检查的 hooks 配置 │ └── pre-deploy-guard.json # 部署前拦截确认的配置 └── install.sh # 一键复制到新项目/用户目录的脚本

install.sh的本质逻辑很简单：把project/下的文件复制到目标项目的.claude/目录，把user/CLAUDE.md追加或合并到当前用户的~/.claude/CLAUDE.md。实际过程中因为有重复文件的处理逻辑，不是单纯 Copy 能解决的，但核心思路就是"一份模板，多处复用"。

5.2 团队共享时的协作机制

当模板开始被三五个团队成员一起使用时，几个新问题浮出来：谁来改动？怎么通知？改坏了怎么办？

我目前的协作做法很简单：

• 模板仓库分两个目录：stable/目录放经过大家评审、确定不会再频繁变动的模板；experimental/目录放新的尝试，愿意尝鲜的人可以试用，用得好再晋升到 stable。
• 每次实质性修改都发一条简短变更说明。比如"review 模板增加了数据一致性检查维度"，让团队知道当前这套标准变了哪里。
• 项目内允许局部覆盖。团队通用模板解决的是共性问题，但某些项目有特殊约定，就在项目内部的.claude/commands/里再放一个同名文件，按 claude-code 的加载优先级优先使用项目本地版本。这种分级设计，既保证了标准统一，又给项目留了灵活性。

这套机制跑了一个多月，团队的 review 风格高度一致，新成员上手时的学习成本也明显降低了——模板本身就是最好的文档。

5.3 把模板和 CI 流程接起来

另一个值得做的动作是把模板里的验证命令和你的 CI 流程对齐。如果你的 CI 里跑的是ruff check和pytest，那 hooks 里和 CLAUDE.md 里写的也必须是这两条命令，否则 Claude 在本地自认为验证通过了，推到远端 CI 却挂了，反噬的是你的信任度。

我见过一个反面例子：CLAUDE.md 里写了"跑测试用python manage.py test"，实际项目 CI 用的是pytest，结果 Claude 每次改完代码都自信地告诉你"测试已通过"，实际上跑的是另一个框架、另一份测试，根本没起到作用。这种"文案与事实不一致"的问题，在模板体系里是致命的，因为它会系统性误导模型的行为。

6. 踩得最深的坑：模板做过头，反被模板伤

6.1 上下文被模板吃干，Claude 变"近视"

有一段时间我追求模板的"完备性"，把 CLAUDE.md 写到了两三千字，又接了一堆 MCP 工具，hooks 里挂了三四个自动检查。表面看起来万事俱备，实际用起来却越来越不对劲。最典型的现象是：Claude 开始"看近不看远"，你问它一个跨文件的功能依赖关系，它会在细枝末节的规范上花大量篇幅，反而把握不住整体架构。

这就是上下文资源的博弈。模板确实给了模型更多有效信息，但每一条信息都在消耗它的注意力窗口。模板的目的不是填满上下文，而是筛选出值得占用的那部分上下文。

我的纠偏策略是给每条模板内容设一个"准入标准"：这条规则是否存在"不写就一定会出问题"的高概率？如果只是"写了可能更规范一些"，那就删掉。用这个标准过一遍，我项目级 CLAUDE.md 从两千字缩到了七百字，Claude 的表现反而明显回升。

6.2 过度约束摧毁了模型的长板和主动性

这个坑比上一条更隐蔽。模板的本意是约束行为边界，但约束过多时，Claude 会变得畏手畏脚：让它生成代码，它每写一段都要先自我怀疑是不是踩了什么规则；让它做架构设计，它优先考虑的不是最优解，而是"最不违反规则"的解法。

说白了，模板约束的是底线和流程，而不是思路和方案。我在 review 模板里最初写了一条"禁止使用任何非标准库实现"，本意是保证可维护性，结果 Claude 连标准库里有现成方案也视而不见，强行手写了一段又长又复杂的逻辑来绕开我设的限制，因为它把自己的判断理解为"必须遵守的硬规则"。

现在的做法是给每条约束标注等级：

[强烈约束] 修改涉及数据库 schema 时必须同时提供迁移脚本 [中性建议] 优先使用项目已有的工具函数，如无现成方案可自行实现 [灵活边界] 在性能与可读性冲突时，默认选可读性，但有充分理由可以打破

等级标注之后，模型终于恢复了一个资深工程师该有的"判断力"——在不该灵活的地方绝不灵活，在可以灵活的地方给出合理取舍。

6.3 版本割裂：项目里的模板过时了

最后一个坑发生在模板库初步成型之后。我在模板仓库里更新了 review 模板，加入了对数据一致性的审查维度，但老项目里的.claude/commands/review.md还是旧版本。结果两个项目用一样的/review，出来的审查深度完全不同。

解决方法是两层：一是给模板仓库加版本号，每个项目的.claude/目录里记录一下引用的模板版本，隔一段时间做个 diff；二是尽量减少"需要维护多份拷贝"的情况——通用的东西全部从仓库拉取，项目里只留真正个性化的覆盖文件。

这一套流程走下来，我自己的体感是：模板库不是一个写完了就放着吃灰的东西，它跟代码一样需要持续迭代、定期复盘。每次你发现"为什么 Claude 在这里是这么做的，这不是我想要的"，其实就是一个新的模板条目或规则修订的触发点。把模板当作一等公民来维护，收获会远超你一开始的预期。

我现在最常用的一句话是：不要问"AI 能写什么"，要问"你希望 AI 在什么边界内写什么"，而模板就是回答这个问题的载体。如果你刚从默认配置开始用 claude-code，我的建议是先搭一个精简的 CLAUDE.md 跑一周，再把高频任务逐个固化进斜杠命令，最后才考虑 hooks 和权限体系。一步步来，别像我一样一上来就堆料，踩过一遍才知道什么叫"少即是多"。