企业官网建设流程全解析

最近我把手头项目的 Claude Code 配置文件完整重写了一遍，顺手整理成了一个 claude-code-templates 模板仓库。说实话，折腾完才发现，大部分人用 Claude Code 的方法从一开始就错了——大家喜欢在对话里反复解释项目背景、构建命令、代码规范，每次开新会话都要重来一遍。而真正能稳定发挥 AI 编程助手价值的，恰恰是那些事先写好的模板。这篇文章我就把自己的模板搭建思路、目录设计、踩过的坑完整拆开讲，适合正在使用 Claude Code 做日常开发的人，也适合想给团队统一 AI 协作规范的技术负责人。

1. 模板到底是什么，为什么它比临时对话可靠

先给没接触过的朋友打个底。Claude Code 本质上是一个跑在终端里的 AI 编程助手，它可以读取项目文件、执行命令、修改代码。但它默认情况下对你的项目一无所知：不知道你的技术栈是什么，不知道测试命令怎么跑，也不知道你代码里哪些风格是雷区。每次你新建会话，都相当于把一个什么都不懂的新人丢进一个复杂代码库，然后靠对话一点点喂给它上下文。

模板要解决的正是这个问题。所谓 claude-code-templates，就是把"每次都要解释的那些话"固化下来，让 Claude 在开工之前就自动掌握项目的基础信息。最早期的模板就是一份 CLAUDE.md 文件，后来版本迭代又加入了 agents、commands、hooks 等部件，模板从一个文件变成了一整套工程化体系。

我强烈建议把模板当工程来做，而不是随手写几个提示词收藏起来。原因有三点：

第一，上下文是有限资源。Claude 能处理的 token 数量不是无限的，你每次在对话里贴一大段项目背景，看起来没毛病，但真正留给推理、留给你要修改的大文件的 token 就变少了。与其临时挤占，不如让模板在对话开始时就精准地提供必要信息，省下上下文空间。

第二，一致性难以靠"记住"维持。一个人可能上午跟 Claude 说"用 pnpm，别用 npm"，下午忘了又说"去装一下依赖"，结果出来一堆 npm 锁文件。模板是明文规则，不存在记忆偏差，也方便团队审查。

第三，新人上手成本直接降一个量级。团队里来了个不熟悉项目的人，只要他把模板仓库拉到本地，运行 Claude Code 就能获得跟老手差不多的 AI 辅助效果。老手积累的这些配置，也沉淀成了团队的公共资产。

我见过很多人花大量时间研究怎么写"高质量 prompt"，这对画图、写作类 AI 或许有用，但对 Claude Code 这类的agent 型工具，真正重要的是把项目上下文结构化、沉淀成模板。prompt 是一次性消耗品，模板是可迭代的工程产物。

2. 模板体系里最值得花时间研究的四个部件

把 claude-code-templates 拆开看，核心部件无非四样：CLAUDE.md、agents、commands、hooks。这四个东西分别解决了"懂项目""专业分工""高频操作""自动触发"四类问题。下面逐个展开，我会尽量结合我自己的项目来讲。

2.1 CLAUDE.md：把项目规则写清楚

CLAUDE.md 是整个模板体系的地基。它是一个 Markdown 文件，放在项目根目录，Claude 每次启动时会自动读取它。你也可以在用户目录放一个全局的~/.claude/CLAUDE.md，管的是跟具体项目无关的通用偏好；也可以在某些子目录放 CLAUDE.md，实现只对特定目录生效的局部规则。这样就有了三个层级的作用域：全局、项目、目录。

写 CLAUDE.md 有一个最关键的原则：它不是 README，不要写一堆产品介绍和架构历史，而要写"Claude 在这个项目里干活时必须知道的操作规则"。我自己的模板里固定包含这几块内容：项目一句话概述、常用的开发/构建/测试命令、代码风格约定（比如是否强制 strict TypeScript、注释语言用中文还是英文）、目录结构提示（哪块代码在哪个目录）、以及最重要的"禁忌清单"——哪些操作绝对不能做。

举个例子，我的某个后端项目里明确写了一条规则："所有数据库迁移必须通过迁移脚本执行，禁止直接连接生产库修改表结构。"没有这条规则时，Claude 可能为了图方便直接改开发库的表，一旦有人把它推到生产环境后果不堪设想。这种负面约束往往比正面引导更管用。

需要注意的是 CLAUDE.md 不要写太长。见过有人的模板写了三四千字，恨不得把每个函数怎么命名都写进去。结果就是每次对话前光加载这个文件就吃掉大量 token，Claude 反而开始丢三落四。我的经验是控制在 500 到 800 字左右，只写那些"不知道就会出错"的硬规则，其余内容放到 agents 或按需调用的命令里。

2.2 agents：给 Claude 戴上专业角色的眼镜

agents 是 Claude Code 的"子助手"机制，允许你定义一批有专门分工的 AI 角色，比如"代码评审员""测试用例生成器""TypeScript 重构专家"。定义文件放在项目的.claude/agents/目录下，每个 agent 对应一个 Markdown 文件，采用 frontmatter 加正文的结构。

frontmatter 里最重要的是name、description、tools三项。name是角色名，description是用来告诉主 Claude"什么时候该调用这个子 agent"的行为描述，tools则限制了该 agent 能使用哪些工具。正文部分就是角色设定和具体工作规则。

我在模板里做过最简单也最有效的 agent 是 code-reviewer，它的 tools 只给了 Read、Grep、Glob 这类只读能力，没给写权限。这样它审查代码时只能看、不能改，天然避免了审查者顺手改代码的混乱场面。而另一个重构 agent 则给了 Edit 与 Write 权限，但任务边界写得很清楚：只做类型重构，不做逻辑变更。

这里有一个实用技巧：给 agent 的 description 写得更"场景化"一点。不要写"负责代码审查"这种宽泛的句子，而要写"当用户要求检查代码质量、安全隐患、或者提交前最后确认时，应该调用此 agent"。主 Claude 判断要不要用子 agent，基本靠的就是这个 description。写得太抽象，它很可能该调用时不调用，或者乱调用。

2.3 commands：把高频操作变成斜杠命令

如果你用 Claude Code 的频率足够高，你会发现自己反复要求它做几件固定的事：帮我跑一遍测试看看哪里挂了、帮我按项目规范写 commit message、帮我检查这次改动的 diff 里有没有安全问题。这些高频操作完全适合做成自定义斜杠命令，也就是 commands 模板。

自定义命令放在.claude/commands/目录下，每个命令是一个 Markdown 文件，文件名就是斜杠命令的名字。比如review.md对应/review，commit.md对应/commit。frontmatter 里的description给主 Claude 看，argument-hint用来提示用户可以传什么参数，正文就是命令触发后 Claude 需要执行的 prompt 模板。

commands 最爽的一点是支持用户传参。比如我定义了一个/commit命令，用户可以直接写/commit 修复登录接口超时的问题，命令模板里用$ARGUMENTS接收这句话，再结合 git diff 去生成 commit message。这样提交信息既符合团队的 conventional commits 规范，又不会啰嗦。

在设计 commands 时要学会"做减法"，不要把全部流程塞进一个命令里。宁可多做几个用途单一的命令，也不要做一个什么都能干但什么都干不好的"万能命令"。我自己最开始写过一个大而全的/workflow命令，试图让它一口气完成从读需求、写代码、跑测试到提交的全流程。结果就是每到一个环节都要猜，产出反而不可控。后来拆成/spec、/review、/commit三个小命令，每个只负责一段清晰的动作，效果立竿见影。

2.4 hooks：在关键节点自动触发检查

hooks 是让模板从"被动响应"走向"主动监督"的关键机制。它允许你在 Claude 执行某些动作前后挂载自定义脚本，从而实现类似"提交代码前自动跑一遍 lint""禁止 Bash 执行危险命令""任务结束后自动通知你"这类能力。

hooks 的配置统一放在.claude/settings.json文件里，核心是事件类型加触发命令。我目前用得比较多的场景有两个。第一个是 PostToolUse 事件，监听 Bash 工具，每当 Claude 执行完一条命令，就触发一个脚本来记录它到底干了什么。这个"操作日志"在排查问题的时候价值很大，能精确还原 Claude 是执行了哪条命令才把环境搞坏的。第二个是 PreToolUse 事件，拦截特定命令。比如我配了一个规则，当 Bash 的工具输入里出现rm -rf /或被明确列入黑名单的路径时，直接拒绝执行。

配置 hooks 有一个很大的坑：脚本返回值格式要求很严格，尤其是异步脚本，如果处理不当，Claude 那边收不到正确的 JSON 响应，整个流程就断了。我的建议是 hooks 脚本尽量用 bash 写简单的同步逻辑，复杂任务不要试图在一个 hook 里塞太多事，宁可多配置几条 hook，让每条只做一件事。

3. 从零搭建一套可用模板的完整实操记录

前面讲了那么多理论，现在落点实操。我以一套比较通用的 TypeScript Node.js 服务端项目模板为例，把你需要做的步骤一步步拆开。

3.1 先梳理自己的工作流，再动手写文件

很多人建模板上来就写文件，写到一半发现哪个都需要，最后搞出一个又长又乱的配置堆。正确顺序应该是先画工作流。我把平时用 Claude Code 做开发的流程画成了一根链路：理解需求 -> 找到要改的代码 -> 写代码 -> 跑测试 -> 审查 diff -> 提交。然后顺着这个链路，反推每一步需要什么模板支撑。

理解需求阶段，需要的是项目背景信息，那 CLAUDE.md 里就必须有项目概述和目录索引。找到要改的代码阶段，依赖的是对项目结构的了解，CLAUDE.md 里同样要覆盖。写代码和跑测试阶段，技术栈和命令必须写清楚。审查 diff 阶段，需要评估标准，我会写一个 review agent。提交阶段，需要一个 commit 命令。这样一梳理，模板该包含什么几乎自己就浮现出来了。

3.2 目录结构与命名规范

一套标准的 claude-code-templates 目录结构大致长这样：

. ├── CLAUDE.md # 项目级规则，放根目录 ├── .claude/ │ ├── settings.json # 全局 hooks 配置 │ ├── agents/ │ │ ├── code-reviewer.md │ │ └── ts-refactorer.md │ └── commands/ │ ├── commit.md │ └── review.md └── docs/ └── templates-guideline.md # 模板编写规范说明

命名规范这块是我的血泪教训。agent 和 command 的文件名就是它们的触发名，所以尽量用连字符小写，比如code-reviewer.md、commit.md，别用什么CodeReviewerAgent.md、commit-message-generator.md这类容易打错的名字。描述信息放在 frontmatter 里，文件名只保留稳定标识符。

3.3 写一份靠谱的 CLAUDE.md

我的 CLAUDE.md 模板骨架大致是这样：

# 项目概述 短业务描述 + 技术栈一句话，避免长段背景介绍。 ## 常用命令 - pnpm install：安装依赖 - pnpm dev：启动开发服务，默认端口 3000 - pnpm test：运行全部测试 - pnpm lint：代码风格检查 ## 代码风格要求 - TypeScript 开启 strict 模式 - 组件和函数使用命名导出，禁止默认导出 - 注释一律使用中文，但代码标识符使用英文 ## 目录结构提示 - src/api：路由层，只做参数校验和响应格式化 - src/service：业务逻辑层，禁止在这里直接操作数据库 - src/model：数据模型与数据库访问层 ## 纪律红区 - 禁止绕过迁移脚本直接修改表结构 - 禁止提交包含本地绝对路径的配置 - 禁止把 node_modules 或编译产物加入版本控制

注意我刻意把"目录结构提示"写得很精简，只画大块归属，不逐层罗列。因为 Claude 本身有读取文件的能力，大型项目你给它一个目录树反而造成信息冗余。让它知道"什么代码该出现在哪儿"就够了，具体细节它可以自己去翻。

3.4 设计一个角色 agent 的完整示例

拿前文提到的 code-reviewer 举例，它的完整文件内容大致如下：

--- name: code-reviewer description: 当用户要求评审代码质量、寻找潜在缺陷、检查安全风险，或在代码提交前做最后确认时，使用该 agent。 tools: Read, Grep, Glob, Bash --- 你是一名资深代码评审员，专注于发现逻辑缺陷、并发问题、安全隐患和性能隐患。 评审时遵循以下流程： 1. 首先读取本次涉及变更的文件清单。 2. 对每个文件依次检查：边界条件是否处理、错误是否被吞掉、是否存在重复代码。 3. 检查是否存在调试残留，如 console.log、TODO、注释掉的代码块。 4. 输出结果按严重程度分组：紧急（需立即修复）、建议（应当调整）、可选（风格类问题）。 严格禁止修改任何文件，你的职责是发现问题并输出报告。

这个 agent 的 tools 里有 Bash，严格说 Bash 具备一定破坏力。但因为我只给了它只读类工具与 Bash，同时正文明确禁止修改文件，实际使用中它最多跑跑git diff之类的只读命令。如果你想要更严的隔离，可以把 Bash 也从 tools 列表里去掉，只保留 Read、Grep、Glob。

3.5 定义常用命令的细节

commit.md命令模板我写得很简单，但实际效果非常好：

--- description: 根据当前 git diff 生成符合规范的 commit message。 argument-hint: 本次提交的概况，例如：修复登录接口超时问题 --- 请先运行 `git diff --cached` 查看已暂存的改动，若暂存区为空则查看 `git diff`。 根据改动内容与用户提供的概况生成一条 commit message，要求： - 遵循 Conventional Commits 格式，type 在 feat / fix / refactor / test / chore 中选择 - subject 不超过 50 个字符，使用中文描述 - 若改动较大，在 subject 下一行补充 body，列清楚主要变更点 用户概况：$ARGUMENTS

这里有个细节值得说：命令模板里明确让它先去看 diff，而不是光靠用户的概况去猜。因为用户说"修复登录超时问题"和实际 diff 里的代码可能相差很大，AI 必须结合真实改动才能生成准确的提交信息。命令模板本质上是一个"带流程的 prompt"，好的命令应该把执行路径也定下来，而不是只提个笼统要求。

3.6 hooks 配置示例：提交前强制过测试

为了让模板真正具备"守门员"能力，我配了一个简单的 hooks：当 Claude 完成任务准备结束（Stop 事件）时，如果项目根目录存在package.json，就自动提醒它执行一次测试。配置长这样：

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "cd $CLAUDE_PROJECT_DIR && test -f package.json && echo '请确认本次修改是否已运行通过 pnpm test'" } ] } ] } }

说实话，这种"温柔提醒"型的 hook 实际作用有限，Claude 可能嘴上说"好的我确认一下"然后就没下文。我更推荐用硬性钩子：PreToolUse 拦截危险命令，或者 PostToolUse 自动跑完格式化脚本再继续。真正有约束力的是在操作发生之前或者之后强制介入，而不是靠对话里的自觉。

3.7 用 Git 管理模板仓库并同步到团队

模板也是代码，跟项目代码一样需要版本管理。我建议把模板独立成一个仓库，或者至少在项目仓库里建一个templates/分支来专门维护。每次模板有变动，都要像代码评审一样过一遍 diff。

团队同步方面，可以把模板仓库放到 Git 远端，让大家git pull更新本地。如果想要更自动化，也可以写一个简单的安装脚本，把模板文件软链接到各项目的.claude/目录下。这样主模板更新后，各项目只需重新拉取就能生效。

4. 实际使用中踩过的坑与排查经验

在"模板能跑通"和"模板真的好用"之间，隔着大量实际使用中才能发现的坑。这部分我直接整理成几张问题速查表，并附上我的排查思路。

4.1 CLAUDE.md 越长，AI 反而越笨

这是我最先踩到、也最影响体验的一个问题。最初我把项目里所有能想到的规则全部塞进一份 CLAUDE.md，包括代码风格、技术栈、目录解释、术语表、常见陷阱、甚至还有一段公司文化介绍。结果就是 Claude 每次响应前都要处理一大坨信息，输出开始变得拖沓，甚至出现"你看看 CLAUDE.md 里第三条规则"这种明显甩锅的情况。

排查之后我做了三层拆分：CLAUDE.md 只保留操作级规则，大概七八百字；详细的术语表和技术选型背景挪到了 docs 目录，按需让 agent 读取；那些只针对某个模块的特别要求，直接写成对应子目录下的局部 CLAUDE.md。这个调整对质量的提升几乎是立竿见影的。

4.2 多个 CLAUDE.md 同时生效导致规则打架

规模稍微大点的项目，不建议只在根目录放一个 CLAUDE.md，可以用子目录级 CLAUDE.md 来覆盖局部逻辑。比如src/legacy/目录里有一套老代码，不允许改动接口签名，那就在这个目录下放一个 CLAUDE.md 单独说明，这样 Claude 处理这个目录时就会加一层额外约束。

但这里有一个隐患：当根目录 CLAUDE.md 与子目录 CLAUDE.md 同时存在，且内容互相矛盾时，到底以哪条为准，不同版本的行为不完全一致。我踩过的具体场景是根目录要求"所有新代码使用 TypeScript"，但某个子目录又写着"本目录维持 JavaScript 以兼容旧系统"，Claude 在生成代码时就开始摇摆。解决办法是，在根目录 CLAUDE.md 里专门写一条"作用域冲突"处理原则：子目录规则优先于全局规则，但若子目录没有明确说明，自动回退到全局规则。

4.3 模板里写死绝对路径，换机器就失灵

我在模板里最早写过这样一条 hook：每天清理某个临时目录时，直接写了/Users/myname/projects/xxx/tmp。结果同事拉下来用的时候，脚本完全跑不通，报错信息还特别隐晦。后来排查才发现是路径写死了。

只要是模板，就必须假设它会被多台机器使用。所有路径用相对路径或环境变量替代，比如$CLAUDE_PROJECT_DIR就是 Claude Code 提供的项目目录变量，hooks 脚本里直接引用它，基本能解决问题。这个习惯越早养成越好，别等团队踩坑了再改。

4.4 子 agent 缺少父会话的上下文

用 agents 时最常遇到的问题是：子 agent 被调起来了，但它完全不知道父对话里已经讨论过什么。比如我在主对话里跟 Claude 说"刚才我们把方案定为优先走缓存策略，现在让 code-reviewer 看看这个方案的改动"，结果子 agent 一上来就质疑"为什么不用缓存策略"，因为它没有继承前文的决策记录。

解决方案是，主 Claude 在调用子 agent 时，必须把相关决策摘要写进 prompt。这个行为可以通过在 agent 定义里专门加一条规则来引导——"当子 agent 被调用时，若任务依赖前序讨论，必须先补全决策上下文"。另外，也可以要求子 agent 优先读取相关的设计文档或需求文件，让它在文件层面获得上下文，而不是仅依赖提示词。

4.5 hooks 脚本返回异常导致任务中断

hooks 的 JSON 返回值格式必须严格，这是排障时最让人抓狂的部分。有一次我配了个 PostToolUse hook，脚本逻辑很简单，就是跑完后输出一个测试耗时统计。但我在脚本里用了console.log输出统计数据，然后又用process.exit(0)正常退出，结果 Claude 端一直报错说解析失败。

后来查官方文档才发现，PostToolUse 类的 hook 需要把结构化结果通过 stdout 输出成 JSON，比如{"hookSpecificOutput": {"hookEventName": "PostToolUse", "commandOutput": "..."}}，而额外日志要写到 stderr 避免污染 stdout。这种问题靠肉眼很难排查，我后来总结经验是：先在终端里手动执行一遍 hook 对应的命令，看它在纯命令行环境下的输出是什么样，如果这里就不规范，那进到 Claude Code 里大概率也是坏的。

4.6 模板更新了，但团队里有人还在用旧版

如果模板是放在独立仓库里共享的，那就一定会遇到版本同步问题。有人提交了新规则，其他同事不 pull 新版本，导致同项目里两个人调出不同的 Claude 行为，互相审查代码时就会产生分歧。

我给团队定的规范很土但有效：模板仓库的 README 顶部放一个版本号，变更必须写进 CHANGELOG，并且要求每次模板更新必须开 PR、过评审、合并后由一个人统一通知。这个流程看着繁琐，但能保住模板作为"团队资产"的严肃性。模板如果失去一致性，那它的价值就直接打了对折。

5. 关于模板维护，再分享几条实在的经验

最后这段，算是我整理 claude-code-templates 之后沉淀下来的一些个人判断，不一定适合每个人，但大概率对想认真用 Claude Code 的人有参考价值。

模板不是一步到位的作品，而是持续演进的工作流沉淀。不要追求第一次就写出一套完美配置，先搭一个最小可用集，然后在真实项目里跑两周，再根据不舒服的地方逐步加规则。这个"不舒服清单"远比任何理论推导可靠。

把模板当成代码来对待，是我这几年最想强调的一点。它需要命名规范、需要版本控制、需要代码评审、需要定期清理死代码。很多人的模板仓库慢慢变成垃圾场，就是因为写的时候不认真、维护的时候又堆砌新规则而不清理，最终变成没人敢动的毛线团。

我个人目前最推荐的做法是从两三个关键文件起步：一份精简的 CLAUDE.md 加一个 review 命令，就足以覆盖日常开发的大部分效率提升需求。跑顺了之后，再增加 agent 和 hooks。你可以先在自己的个人项目里试用这套模板，确认稳定后再推给团队。踩过几次坑之后你会发现，真正省时间的不是让 AI 多干活，而是让它少做"无效的上下文猜测"，而模板就是达成这个目标最高效的途径。