企业官网建设流程全解析

说实话，我第一次拿到Claude Code的时候，觉得这玩意儿确实聪明，但用一个星期就发现了个别扭的问题：每开一个新会话，都得把项目背景、代码规范、注意事项重新交代一遍。说得少了它容易跑偏，说得多了又浪费时间，而且团队里每个人“教”它的方式还不一样，出来的代码风格五花八门。后来我把这套“开场白”沉淀成了 claude-code-templates，也就是 CLAUDE.md、自定义命令、hooks 这类模板文件，情况立刻不一样了。AI 在会话一开始就带着完整上下文工作，新成员进来也不用再凭感觉和 AI 对话，照着模板就能让输出稳定、风格统一。这篇文章就把我搭模板的完整思路、实操步骤和踩过的坑整理出来，适合所有在用 Claude Code 写代码、做 Code Review、维护老项目的朋友参考。

1. 内容整体设计与思路拆解

1.1 为什么 AI 编码需要“模板化”

先说痛点。如果你已经用 Claude Code 写过一段时间代码，大概率遇到过这几个场景：一是上下文丢失，明明昨天刚跟它敲定“这个模块用函数式风格写”，今天新开一个会话它就忘得一干二净，又开始给你搞面向对象；二是输出风格飘忽，同一个需求，有时候它给你一段极其详细的方案，有时候又偷懒给你几句概括；三是团队协作失配，后端同事习惯用英文提问，前端同事用中文，AI 给出的代码注释风格也跟着变来变去。

这些问题的根源在于：Claude Code 本身是一个“无状态”的工具，每次会话默认只依赖当前对话里的内容。你不告诉它背景，它就靠猜。而模板化的本质，就是把“稳定预期”注入到 AI 的每一次工作里。用个生活化的类比，公司来了新员工，与其每天口头交代一遍“我们风格是代码要写注释、提交要用 convention commit”，不如直接甩给他一本《员工手册》。Claude Code 的模板就是这个手册。

从机制上讲，Claude Code 在启动时会自动读取项目根目录下的 CLAUDE.md 文件，以及用户全局目录下的 CLAUDE.md 文件，把它们作为长期记忆注入到上下文中。也就是说，你根本不用等 AI 问“这个项目是什么”，它在你还没开口之前就已经“读过”项目规范了。这也是为什么模板比每次手动输入更可靠——它是被框架自动加载的，不依赖某个人的对话习惯。

1.2 一套模板体系由哪几层构成

我自己在实践里，把 claude-code-templates 拆成四层，每一层负责不同粒度的问题。光说“建一个模板文件”是不够的，得让模板体系各司其职，才不会变成一锅粥。

这四层的关系是：用户级手册管“你这个人喜欢怎么干活”，项目级手册管“这个项目有什么规矩”，自定义命令管“你高频重复的动作”，hooks 管“不能只靠提示语约束的硬性要求”。

设计这套体系时，我给自己定了三条原则。第一，最小化原则——模板不是文档库，能写一页纸解决的绝不写十页，因为上下文窗口是有限的，塞太多废话反而稀释重点。第二，渐进式原则——不要第一天就追求完美，从一页纸开始，用着用着发现 AI 哪里跑偏，再针对性补一条规则。第三，版本化原则——所有模板文件纳入 Git 管理，改了什么一目了然，回滚也方便。

2. 核心细节解析与实操要点

2.1 CLAUDE.md：项目级的“操作手册”

项目级 CLAUDE.md 是整套模板体系里最核心的一块。它放在项目根目录，只要在这个目录下启动 Claude Code，它就会被自动加载，相当于 AI 的“入职第一天培训”。

我建议 CLAUDE.md 至少包含这几块内容：项目一句话概述、常用命令、代码风格约定、关键架构说明、明确禁止的事项。概述让它快速理解业务场景，命令部分让它不用每次去猜“怎么跑测试”，风格约定让产出保持一致性，架构说明减少理解偏差，禁止事项则是安全底线。

一个我实际用过的精简示例：

# 项目：电商平台用户服务 ## 项目概述 用户服务是电商平台的核心微服务，负责注册、登录、个人信息管理。 技术栈为 Go + PostgreSQL + Redis，部署在 Kubernetes。 ## 常用命令 - 本地启动：make dev - 跑单测：make test - 跑全量集成测试：make integration - 生成 mock：make mock ## 代码风格 - 使用 Go 1.22，开启 strict mode - 错误处理必须 return，不允许 panic - 接口优先，依赖注入 - 所有对外 API 必须带 tracing ## 架构地图 - gateway 目录：HTTP 入口，负责参数校验 - service 目录：业务逻辑层 - repository 目录：数据库访问层，禁止在 service 里直接写 SQL - pkg 目录：可复用的基础库 ## 禁止事项 - 禁止在 service 层直接操作 Redis - 禁止绕过 repository 层访问数据库 - 禁止使用全局变量保存请求上下文

写 CLAUDE.md 有个关键技巧：要用“指令式”语言，不要写散文。AI 对明确的 do/don't 句式非常敏感，你写“建议使用依赖注入”，它可能真的只当建议；你写“必须使用依赖注入，构造函数的依赖一律显式传入”，它就会严格遵守。另外，文件靠前的部分权重更高，所以把最重要的信息放在开头。

这里有个实操心得：不要试图把整个项目的技术文档都塞进 CLAUDE.md。上下文窗口虽然不小，但也不是无限的，塞得越多，AI 在真正干活时反而容易被无关信息干扰。我的标准是，一页纸以内能说完的才写进去，深层设计文档用链接引到外部文件，让 AI 需要时自己去看。

2.2 自定义命令：把高频动作变成“快捷键”

如果说 CLAUDE.md 是 AI 的长期记忆，那自定义命令就是你的“快捷键”。它放在项目的 .claude/commands/ 目录下，每个命令是一个 markdown 文件。你只需要输入/命令名就能触发对应的提示词模板，省去每次手敲一长段指令。

我最常用的一个命令是 code-review。以前做代码审查，我得手动跟 AI 说“请对当前分支的改动进行审查，重点看并发安全、SQL 性能、错误处理，按严重程度输出结果”，每次打一遍挺烦。做了模板之后，只需要输入：

# /code-review 请对 {branch} 分支相对当前分支的改动做一次全面代码审查，分三个维度输出： 1. 正确性：是否存在逻辑错误、并发问题、资源泄漏 2. 性能：是否有关键路径性能隐患，特别是 SQL 查询和锁粒度 3. 可维护性：命名是否清晰、函数是否过长、是否有重复代码 每个问题按 严重 / 中 / 低 分级，严重问题必须给出具体文件和修复建议。

调用方法和参数替换也很简单。输入/code-review main，AI 就会把{branch}替换成 main，然后执行审查。实测下来，把审查指令沉淀成模板之后，团队里所有人拿到的 Code Review 质量都差不多，不会再出现“有人让 AI 随便看看，有人让 AI 逐行审”的落差。

除了纯提示词模板，命令文件还可以是 bash 脚本。比如自动跑测试、自动生成 changelog 之类的操作，你可以写一个 .bash 文件放进 commands 目录，让 Claude Code 直接执行。这个我建议有一定经验再用，新手还是从纯提示词模板开始比较稳。

给命令命名也有讲究：统一用小写短横线风格，比如code-review、release-note，不要用空格和大写。命令内容里如果有参数，一定要在模板里说明参数含义和可选范围，否则 AI 可能不知道{branch}到底指的是什么。

2.3 用户级模板：个人偏好的沉淀

项目级模板管项目规矩，但每个人干活的方式不一样。有人喜欢代码里带详细中文注释，有人偏好简洁英文；有人要求 AI 所有回复都用中文，有人习惯英文。这些偏好，放到用户级模板~/.claude/CLAUDE.md里最合适。

我自己的用户级模板写的是：

# 个人偏好 ## 回复语言 - 默认使用中文回复，代码标识符、文件名、报错信息保留英文 ## 编码风格 - 前端代码使用 TypeScript，函数式优先，避免 class 组件 - 所有函数必须有明确的输入输出类型定义 - 注释只写 WHY，不写 WHAT ## 通用约定 - 提交信息使用 conventional commits 格式 - 遇到不确定的技术假设，先列出假设再继续，不要闷头写 - 需要修改状态管理逻辑时，先给出迁移方案再动手

这样设置之后，无论我进入哪个项目，AI 都会默认带上这些个人偏好。和项目级模板是叠加关系——用户级偏好在先，项目级规范在后，当两者冲突时以更具体的项目规范为准。比如我全局写着“前端采用函数式优先”，但某个项目团队明确要求用 class 组件，那么项目级说明应该优先。

这里有个重点提醒：用户级文件是跨项目生效的，千万不要在里面写某个公司的私有信息、内部项目名、保密架构。我见过有人把这文件当成随手记事本，结果走到哪儿 AI 都在惦记上一家公司的内部系统，那场面别提多尴尬。

2.4 Hooks 与 Settings：把规则从“建议”变成“强制”

CLAUDE.md 和自定义命令本质上还是“提示”，AI 可以遵守也可以打折扣。但有些规则是安全底线，必须强制执行，这时候就要用到 hooks 机制。它配置在.claude/settings.json里，可以在特定事件点触发一段命令或脚本。

举个例子。我有个项目，生产数据库特别敏感，任何人在任何情况下都不允许通过 Claude Code 直接执行数据库删除操作。光在 CLAUDE.md 里写“禁止删除数据”不够，因为 AI 有时候会“忘记”。于是我配了一个 PreToolUse hook，在 AI 调用 Bash 工具执行命令之前拦截检查：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "command": "sh .claude/hooks/check-dangerous-command.sh" } ] } }

对应的脚本内容是：

#!/bin/sh input=$(cat) echo "$input" | grep -iE 'drop table|truncate|delete from|rm -rf /' > /dev/null if [ $? -eq 0 ]; then echo "block_reason=检测到高危命令，已拦截。请联系管理员确认！" exit 2 fi exit 0

配置好之后实测，AI 一旦试图跑危险命令，就会被 hook 直接拦住，并在对话里看到拦截原因。这种机制的本质是：把规约从“靠 AI 自觉”变成“靠系统强制”。你不需要赌 AI 每一次都听话，因为钩子会在它动手之前把路堵死。

hooks 配置虽然好用，但也有几个坑。一是 hook 脚本必须幂等，重复执行结果一致，因为你不知道它会被触发多少次；二是脚本里不要写死绝对路径，用相对路径配合.claude/hooks目录管理最稳；三是 hook 执行失败时要有明确的输出信息，否则 AI 会一脸懵不知道为什么工具调不了。

3. 实操过程与核心环节实现

3.1 从零搭建一套模板体系

说再多理论，不如直接动手。这里我把从零搭建的完整过程走一遍，以我常用的版本为例，具体命令路径你可以对照手头的 Claude Code 版本来微调。

第一步，先建用户级模板。打开终端执行：

mkdir -p ~/.claude touch ~/.claude/CLAUDE.md

然后把个人偏好写进去。这一步花十分钟搞定，以后所有项目都受益。

第二步，进到具体项目目录，创建项目级模板：

cd /path/to/your/project touch CLAUDE.md

把 2.1 节里的项目概述、命令、风格、架构、禁令全部填进去。对老项目来说，写架构说明可能要花些时间，但绝对值回票价。

第三步，添加自定义命令：

mkdir -p .claude/commands touch .claude/commands/code-review.md touch .claude/commands/release-note.md

第四步，配置 hooks 和 settings：

mkdir -p .claude/hooks touch .claude/hooks/check-dangerous-command.sh touch .claude/settings.json

四步做完，你的目录结构应该是这样：

project/ ├── .claude/ │ ├── commands/ │ │ ├── code-review.md │ │ └── release-note.md │ ├── hooks/ │ │ └── check-dangerous-command.sh │ └── settings.json ├── CLAUDE.md └── ...其他项目文件

这套体系搭完之后，并不是一劳永逸了。我强烈建议把它纳入 Git 版本管理，任何修改走 commit，这样一旦某条新规则引入了意料之外的问题，你可以快速回滚到上一个版本。

3.2 CLAUDE.md 编写实操：从“AI 听不懂”到“AI 照着做”

编写 CLAUDE.md 最忌讳的是写得太虚。比如“代码要优雅”“注意性能”，这种话 AI 听到等于没听到，因为它无法判断什么叫优雅。真正有效的写法是具体、可验证、有边界。

我一步步演示一个从差到好的修改过程。初始版本：

## 性能要求 - 性能要好，接口不能慢

这条模板等于白写。改成：

## 性能要求 - 所有查询必须利用索引，禁止全表扫描 - 列表接口单次查询数据量不得超过 100 条，需要分页 - 任何新增接口必须包含 explain 分析结果，慢查询（超过 200ms）必须优化后才能提交

这样 AI 在执行时就有了明确的判断标准，它甚至可以自己在开发过程中自查。

再比如代码风格的描述：

## 代码风格 - 统一使用异步编程

这也是不够具体的。更有效的版本是：

## 代码风格 - 使用 async/await，禁止使用 .then/.catch 链式回调 - 禁止使用 var，统一用 const 声明常量、let 声明变量 - 数据不可变性优先，禁止直接修改函数的入参对象 - 浮点数金额计算必须使用 Decimal 类型，禁止用 Number 直接运算

我踩过的一个坑是：在 CLAUDE.md 里写了太多“原则上”开头的句子，结果 AI 遇到具体场景时把“原则上”理解为“看情况”。后来我把所有软性表述都删掉，只留硬性规则，执行率明显提高。当然，规则太多也会限制 AI 的灵活性，所以只把必须遵守的硬约束写进去，剩下的让它自己发挥。

另外还有个验证模板是否生效的小技巧。写完 CLAUDE.md 后新开一个会话，直接问 AI：“这个项目怎么启动，测试命令是什么？”如果它不看文档就能准确回答，说明模板被成功加载了。如果它开始胡说八道，就该检查文件路径和内容了。

3.3 自定义命令实操：写一个带参数的命令

带参数的命令比纯固定提示词更实用，因为它的适用面更广。我以“生成发布说明”为例，完整展示怎么写。

在.claude/commands/release-note.md里写：

# 生成 {version} 版本的发布说明 请基于 Git 历史生成发布说明，要求如下： 1. 对比当前分支与标签 {version} 之间的所有提交 2. 按类型分组输出：新功能、Bug 修复、性能优化、重构、依赖升级 3. 每个条目一句话概括，避免技术黑话，面向产品/运营阅读 4. 若有 breaking change，必须在文档开头用警示框标出 输出格式为 Markdown，直接展示在对话里，不要写入文件。

使用的时候输入/release-note v1.2.0，AI 就会自动替换参数并执行。这里有一个参数替换的细节：参数格式是{变量名}，凡是模板里出现的{变量名}都会被用户输入替换。如果用户没有提供对应值，AI 通常会主动询问，你可以把这种情况也写进模板，比如“如果版本号未提供，请先问我”。

调试命令的时候，先输入/看看命令列表里有没有你刚创建的命令。如果列表里没有，检查文件名后缀是不是.md，以及是否放在正确的目录。命名上千万别带空格，我用过一个名字叫do review.md的文件，结果斜杠命令解析失败，改成do-review.md就好了。

给团队成员共享命令模板时，记得把.claude/目录纳入 Git，这样团队拉下来代码的同时也拿到了命令。我见过有的团队把命令散落在聊天记录里，新人进来找不到，最后又回到各写各的混乱状态，这跟不设模板的初衷就背道而驰了。

3.4 模板版本管理与团队共享

模板这个东西，用起来之后一定会频繁迭代，所以版本管理特别重要。我的做法是给模板单独建一个仓库，比如claude-code-templates，里面统一管理用户级模板、常用命令、hooks 脚本，然后通过安装脚本部署到本地或各个项目。

大致目录结构：

claude-code-templates/ ├── user/ │ └── CLAUDE.md ├── commands/ │ ├── code-review.md │ ├── release-note.md │ └── generate-test.md ├── hooks/ │ ├── check-dangerous-command.sh │ └── post-stop-cleanup.sh ├── install.sh └── README.md

install.sh 的作用是把这些模板复制或软链到正确的位置。用了软链之后有一个额外好处：模板仓库更新了，项目里的模板也跟着更新，不用每个项目手动同步。

#!/bin/sh # install.sh set -e # 安装用户级模板 mkdir -p ~/.claude ln -sf "$(pwd)/user/CLAUDE.md" ~/.claude/CLAUDE.md # 安装命令模板（复制到当前项目，也可以改成软链） mkdir -p .claude/commands for f in commands/*.md; do cp "$f" .claude/commands/ done echo "模板安装完成"

团队协作时有个重要建议：模板的变更一定要走评审。不要把“个人觉得这样可以”的规则直接塞进公共模板，因为这不只是影响你自己，还会影响团队里所有人跟 AI 的协作方式。我们团队的做法是，每次模板变更至少拉一个同事 Review，变更记录写清楚“这条规则解决了什么问题”，避免模板慢慢变成一堆没人懂的“祖传咒语”。

4. 常见问题与排查技巧实录

4.1 模板不生效？先查这三处

我见过的最常见问题就是改了 CLAUDE.md，但 AI 完全不当回事。这时候先别急着怀疑 AI“不听话”，大概率是这几个原因。

第一，路径和文件名不对。CLAUDE.md 必须放在项目根目录，文件名必须是全大写CLAUDE.md，少写一个字母或者改成claude.md都不会被自动加载。自定义命令则必须放在.claude/commands/目录下，后缀.md或.bash都可以，但文件名的斜杠命令必须用小写短横线风格。

第二，没有新开会话。模板加载发生在会话启动的时候，如果你在一个已经进行中的会话改完模板，AI 不会立即感知到变化。需要新开一个会话，或者至少重启一下当前会话，改动才会生效。

第三，与其他配置冲突。你可能在项目级模板和用户级模板里写了相反的要求，AI 遇到矛盾时会感到困惑，可能随机选择一边执行。排查办法是把两个文件里的规则逐条对照，以项目级为准统一掉。

我写了一个快速自检脚本的思路，直接在对话里让 AI 描述当前生效的模板内容，如果它说出来的和你写的不一致，基本就是前两个原因。

4.2 上下文变长变慢怎么办

CLAUDE.md 写太长了，会对会话产生另一个副作用——上下文占用过大，导致 AI 响应变慢，甚至影响它聚焦当前任务。有段时间我把整个项目的 API 文档都塞进去了，结果 AI 每一次回复都要带上一大堆背景信息，明显感觉到它“变笨了”。

解决这个问题有三个办法。第一，精简内容，把 CLAUDE.md 控制在一页纸以内，只保留最核心的规则。第二，把详细文档放到外部文件，在 CLAUDE.md 里只写一行：“数据库表结构说明见 docs/database.md，需要时自行查看。”第三，把不常用但偶尔需要的信息放到自定义命令里，而不是常驻上下文。比如“数据库表清单”这种信息，AI 需要的时候才去查，而不是每次会话都背一遍，效果会好很多。

我这边的经验是，维护一个分层的模板策略，线上环境跑一段时间后评估一下哪些内容真正被高频使用，哪些一次都没用到。超过一个月没被用到的规则就删除或外链，保持模板精干。

4.3 命令冲突与模板覆盖问题

自定义命令也可能互相“抢地盘”。比如我在用户级目录~/.claude/commands/里建了一个code-review命令，项目级.claude/commands/里也放了一个同名命令，那么实际生效的是项目级那个，它会覆盖用户级的同名命令。这个优先级规则也可以用来做团队强制统一，但如果没有意识到这一点，就会出现“我在本地怎么跑不通”的困惑。

另一个容易踩的坑是命令内容里的参数名冲突。比如模板里用了{version}，但 AI 在上下文中恰好也在讨论其他叫 version 的变量，它可能会困惑。我的习惯是参数名加前缀，比如{target_version}，尽量具体化，减少歧义。

排查命令问题时，可以用一个笨但有效的办法：把命令模板里的内容直接复制到对话里，手动去掉{参数}换成真实值，看 AI 的执行结果。如果手动版正常、命令版不正常，那就是参数解析或命令加载的问题。如果手动版也不正常，说明模板内容本身符合预期，而是 AI 的理解出了问题，需要调整提示词的表述方式。

4.4 团队协作的坑

团队用模板最大的坑是“模板被悄悄改成个人风格”。我遇到过一位同事，觉得自己喜欢超长详细输出，就把公共模板里的规则全改成了“必须输出 5000 字完整方案”，结果其他人用的时候全都抱怨 AI 太啰嗦。所以模板仓库分支保护和变更评审，并不是形式主义，它是保证公共模板质量的生命线。

另一个常见问题是模板更新滞后。项目架构已经变了，CLAUDE.md 还停留在几个月前，导致 AI 给出的方案过时。这里我建议把模板维护写进项目迭代流程，比如每次技术方案评审时顺带问一句“CLAUDE.md 需不需要同步更新”。哪怕只是一个小改动，也要形成习惯，不然过几个月再回头清理，工作量会大得让人不想动。

最后一个忠告：模板一定要从实际槽点里长出来，而不是先写一堆完美规则然后强迫所有人遵守。我最开始搭模板的时候，一口气写了三十多条规则，结果 AI 反而因为约束太多而束手束脚，团队成员也嫌模板太教条。后来改成“碰见一个问题就补一条规则”的迭代模式，每条规则都有真实的场景支撑，模板才真正活起来。

说实话，踩过几次坑之后，我现在的习惯是：每次发现 AI 在新会话里“忘事”，第一反应不是再解释一遍，而是去补一条模板；每次发现某个指令重复用了三次以上，就把它改成一条命令。模板这东西，不是第一天写得多全，而是跟着你的真实使用场景慢慢长出来的。我这套 claude-code-templates 的经验不一定适合所有团队，但思路是通用的——先明确你要稳定的预期是什么，再决定用哪一层模板去承载它。希望这篇文章能帮你少走点弯路。