企业官网建设流程全解析

我第一次把前一个项目的CLAUDE.md原封不动复制到新项目的时候，发现这个新项目用的完全是另一套技术栈、另一套构建工具、另一套团队规范，结果 AI 满嘴跑火车式地按旧规矩给我“优化”代码，气得我当场把文件删了。从那天起我就意识到，Claude Code 的模板不是说你攒一个文件然后到处复制，它应该是一套可以按需组合的积木：项目规则、斜杠命令、钩子脚本、技能文件、脚手架脚本，每一层管一件事，组合起来才是真正好用的claude-code-templates。

这篇文章把我自己沉淀了大半年的模板体系完整拆给你看。我默认你已经在用 Claude Code，至少知道claude命令能在终端里跑起来，知道它会把对话上下文发给模型。至于模板怎么设计、怎么落盘、怎么排错，我会全部展开讲。内容适用于独立开发者，也适用于团队协作场景，拿来改一改就能直接进你的仓库。

1. 先弄清楚：模板到底在“套”什么东西

1.1 我说的模板，不是你想的那个模板

大部分人听到“模板”两个字，第一反应是 UI 层面的东西，比如生成一份 Markdown 文件、生成一个 React 组件。但 Claude Code 是终端里的 AI 编程助手，它的“模板”概念要宽得多。我把它拆成四层：

• 上下文模板：也就是CLAUDE.md，告诉 Claude“这个项目是什么、有什么规矩、哪些东西不能碰”。
• 命令模板：放在.claude/commands/下的斜杠命令，相当于给 AI 预置好的“动作脚本”，输入/review就执行一套完整的代码审查流程。
• 钩子模板：挂在settings.json里的自动触发脚本，拦截特定事件，比如“AI 准备执行 Bash 命令前先检查一遍”。
• 技能模板：也就是 Agent Skills，以 Markdown 文件组织的可复用方法论，让 Claude 在遇到相关任务时自动加载对应的操作手册。

这四层各管一摊，彼此又耦合。上下文模板打底，命令模板管一次性动作，钩子模板管纪律，技能模板管方法论。把它们组合成一个目录结构再交给 git 管理，这就是你个人的claude-code-templates。

1.2 模板体系要解决的三个实际问题

我在没有模板体系之前，每天在终端里重复劳动。第一个问题是每次开新对话都要重新解释项目背景，明明上一个会话已经聊清楚了，换个目录又是从零开始；第二个问题是项目规则靠嘴说，AI 听完就忘，今天遵守明天不遵守；第三个问题是团队的代码规范在 Claude Code 这里根本没有落到实处的通道，Review 不严、测试不跑、提交信息乱写。

模板体系就是冲着这三个问题去的。CLAUDE.md解决“每次都要重复解释”的问题，命令模板解决“动作流程不可复用”的问题，钩子解决“规则只靠自觉”的问题，技能解决“团队方法论没法沉淀”的问题。一套模板建好之后，你在一台新机器上拉下仓库，装好 Claude Code，几秒钟就能得到和原来完全一致的 AI 协作环境。

我一直强调一个观点：模板不是给 Claude 看的，是给你的工程流程看的。Claude 只是一个执行体，你在模板里写清楚流程，它的输出质量才能稳定在及格线以上。这个过程本身，就是在给 AI 编程这件事做“配置管理”。

2. 第一层：CLAUDE.md——把项目语境变成可复制的文件

2.1 CLAUDE.md 到底该怎么写

很多人以为CLAUDE.md写得越多越好，恨不得把整个 wiki 灌进去。我在早期也犯过这个错，写了两千多行，结果 Claude 反而抓不住重点，经常被无关细节带偏。后来我总结出一个判断标准：CLAUDE.md里的每一句话，都应该能直接影响 AI 的行为决策。不能影响决策的垃圾信息，全部拿出去。

一份合格的CLAUDE.md应该包含这五块内容：

• 项目身份：一句话说清这个项目是干什么的，技术栈是什么，仓库结构长什么样。
• 核心命令：开发、构建、测试、检查这些常用命令分别是什么。AI 一旦知道怎么跑测试，它就会在改完代码后主动跑一遍。
• 编码规范：缩进、命名、组件边界、状态管理方式等硬性约定。
• 禁区条款：哪些依赖不能引入，哪些目录不能修改，哪些模式已经被淘汰。禁区比建议更重要，AI 非常擅长在你不注意的时候偷偷引入新依赖。
• 当前工作流：目前团队在用什么模型、什么部署流程、什么测试策略。这个部分需要随项目迭代而更新。

开头那段“项目身份”一定要精炼。我见过有人写十行，Claude 也没理解到底谁是谁。我用的是一个很粗暴的做法：一句话说“这是一个面向 XXX 场景的 XXX 服务，主要技术栈是 XXX”，然后给一段目录结构示意，再给两三行“这里的关键模块是 XXX”。这样即使是一个从未见过这个仓库的 AI，也能在第一次交互时就建立基本空间感。

2.2 一套可以抄的通用 CLAUDE.md 模板

下面这个模板我几乎在每个新项目里都会先铺一层，然后再按项目特性增删。你直接复制到项目根目录，把方括号里的内容换成自己的就行。

# CLAUDE.md ## 项目身份 - 一句话：这是一个 [项目类型] ，主要解决 [核心问题]。 - 技术栈：[语言] + [框架] + [数据库/缓存等]。 - 仓库结构： - `apps/web` 前端应用 - `apps/api` 后端服务 - `packages/shared` 共享代码 ## 常用命令 - 安装依赖：`pnpm install` - 本地开发：`pnpm dev` - 运行测试：`pnpm test` - 代码检查：`pnpm lint` - 类型检查：`pnpm typecheck` - 构建：`pnpm build` ## 编码规范 - 使用 TypeScript strict 模式。 - 组件使用函数式写法，禁止使用 class 组件。 - 状态管理统一使用 [zustand / pinia / vuex]，不要自造状态容器。 - 样式使用 [CSS Modules / Tailwind / 样式组件]。 - 提交信息遵循 conventional commits 格式。 ## 禁区 - 不要引入 [某个已经被否决的库]，改用 [替代方案]。 - 不要直接修改 `packages/shared` 中已被标记为 frozen 的 API。 - 不要为单测构造复杂 mock，优先使用真实依赖做集成测试。 ## 当前工作流 - 主分支：`main`，发布流程：PR 合入后自动触发部署。 - CI 中必须通过 lint、typecheck 和 test，否则不能合入。 - 数据库迁移由专门的迁移脚本管理，禁止手工改库。

这份模板的关键在于“命令优先”。Claude 最终要落到执行上，如果它连测试命令是什么都得猜，效率一定低。你可以把常用命令放在最显眼的位置，甚至重复出现两次都没关系，只要它能在需要的时候快速检索到。

2.3 我踩过的“规则打架”坑

写了半年CLAUDE.md，我最深刻的教训是“规则会打架”。举个真实的例子：我在一个项目里写了“优先使用现有的工具函数”，又在另一个项目里写了“禁止使用全局工具函数，必须在模块内实现”。结果两个规则分别被不同子任务触发，AI 经常一边说“按全局规范来”，一边实现了一套完全相反的做法。

后来我学乖了。所有进入CLAUDE.md的规则必须先做一次一致性检查，问自己一个问题：这条规则和现有的哪条规则可能冲突？一旦发现两条规则指向不同的行为方向，要么删掉一条，要么加上明确的适用边界。另外我还会在末尾加一个“规则优先级”小节，明确写“当规则冲突时，越靠前的规则优先”。这样就算漏了一条矛盾语句，AI 也有一套自己的仲裁逻辑。

还有一个容易踩的坑是：不要在CLAUDE.md里放“希望型”语句。比如“代码质量尽量高一点”这种话，AI 无法把它变成可执行动作。它应该被翻译成“所有新增函数必须包含 JSDoc 注释”“单测覆盖率不能低于 80%”这种可检查、可验证的硬性条件。

3. 第二层：斜杠命令——把高频操作沉淀成指令模板

3.1 命令模板的存放规则

Claude Code 的自定义斜杠命令放在两个位置：用户级的~/.claude/commands/和项目级的.claude/commands/。用户级适合放通用的、工作流相关的命令，比如“写周报”“解释这段代码”；项目级适合放和当前仓库强相关的命令，比如“运行这个项目的测试”“按本项目的规范新增加接口”。

文件的命名决定了命令名。你创建.claude/commands/review.md之后，在 Claude Code 对话框里输入/review就能触发这个模板。文件里的内容会作为提示词注入当前对话，相当于你替 Claude 写好了一整套审查指令。

我强烈建议所有团队成员都使用项目级命令目录。这样不管谁在哪个分支上工作，执行同一个/review命令，得到的行为是一致的。如果放在个人级目录里，每个人存的文件内容都不一样，执行效果当然就五花八门。

3.2 实战命令模板：代码审查、测试、加接口

我给你三个最常用的命令模板作参考。

第一个是/review，代码审查命令。它的一般形态是这样：

--- description: 审查当前分支的代码变更，输出问题和修改建议 --- 你是一名资深代码审查者。请按以下步骤开展审查： 1. 先执行 `git diff main...HEAD --stat` 查看变更概览。 2. 再执行 `git diff main...HEAD` 获取逐行差异。 3. 逐个文件分析，重点关注： - 逻辑错误和边界情况 - 性能隐患（不必要的循环、重复计算、内存泄漏） - 安全风险（注入、越权访问、敏感信息泄露） - 与项目规范的偏差 4. 输出格式： - **严重问题**：必须修复后才能合入 - **建议改进**：不影响合入但应当关注 - **亮点**：写得好的地方，给点正向反馈 注意：如果差异太大，先向用户确认审查范围，不要一次灌入超过 2000 行代码。

这个模板做对了三件事：先看概览再看细节，避免 AI 一上来就被淹没；把审查目标写成可检查的清单，而不是一句“帮我看看代码”；最后加了一个“差异太大先确认范围”的保护条款，防止长分支把上下文撑爆。

第二个是/add-test，为指定文件补测试的命令模板：

--- description: 为指定模块补充单元测试 --- 请为 {{file_path}} 文件中的核心逻辑编写单元测试。 要求： 1. 先读取原文件，梳理公开函数和边界场景。 2. 测试文件放在与源文件同级的 `__tests__` 目录。 3. 覆盖以下场景：正常输入、空输入、异常输入、依赖不可用。 4. 使用项目已有的测试框架和 mock 方式。 5. 写完测试后运行对应命令，确认全部通过。 如果原文件没有可测试逻辑，直接说明原因并给出重构建议。

这个模板充分利用了{{file_path}}这个占位变量，AI 会自动读取你在对话里选中的文件路径。这样就不用每次手写一遍“哪个文件”，效率高很多。

第三个是/new-api，按项目规范新增一个接口。这个模板和项目强相关，因为不同项目的接口规范完全不同：

--- description: 新增后端 API 接口 --- 请实现一个新的 API 接口。 步骤： 1. 确认已有的路由注册方式，参考 `apps/api/src/routes/` 下的现有模块。 2. 在对应模块中新增路由和处理函数。 3. 补充入参校验，校验规则参考项目现有的 zod 定义。 4. 更新 OpenAPI 文档。 5. 新增对应的集成测试。 6. 运行 `pnpm typecheck && pnpm test` 确认无回归。 注意：不要引入新的 HTTP 框架，不要绕过现有鉴权中间件。

3.3 让命令模板接受参数的技巧

命令模板里能用的占位符比我想象中灵活。{{file_path}}会自动绑定当前选中的文件，{{file_content}}会带着文件内容一起进来。你还可以在模板里写普通变量，比如{{module_name}}，AI 会结合上下文尝试推断。不过我的经验是，占位符别太贪多，一个模板最多两三个变量就够了，否则 AI 大概率会为了凑变量而胡编。

更实用的技巧是利用 Bash 命令动态注入信息。比如在模板里写：

当前分支：$(git branch --show-current) 最近提交：$(git log --oneline -5)

AI 执行命令后就能拿到实时信息，比我们在模板里手动维护状态要可靠得多。这招在写周报、写发布说明、做审查时特别管用。

4. 第三层：Hooks——把纪律做成自动化的钩子

4.1 钩子能拦住哪些“手滑”

Claude Code 的钩子机制允许你在 AI 生命周期的关键节点挂上自己的脚本。和命令模板的“人类主动触发”不同，钩子是被动触发、自动执行的，适合用来做纪律性拦截。

我实际用到最多的三个场景是：

• PreToolUse 拦截：AI 准备执行某个 Bash 命令之前先检查命令内容。比如我写过一段脚本，禁止 AI 在生产环境目录里直接执行rm -rf，一旦匹配到高危命令就中断执行。
• PostToolUse 检查：AI 执行完某个工具之后，脚本可以读取输出并判断结果。比如每次 Edit 操作结束之后自动跑一遍格式化，确保代码风格统一。
• Stop 钩子收尾：AI 回复用户之前触发。我在这里挂了一个小脚本，检查当前是否有未解决的 lint 错误，如果有就在回答里附加一句警告。

钩子的设计原则是“小、快、专一”。一个钩子只做一件事，脚本尽量短，不要在里面写复杂业务逻辑。因为钩子会在 AI 的每次操作中被反复触发，一旦脚本卡住或者抛异常，整个会话都会受影响。

4.2 一套安全的 hooks 配置长什么样

这里给你看一份简化版的settings.json配置，文件位于项目根目录的.claude/settings.json：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "sh .claude/hooks/guard-danger-commands.sh" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "sh .claude/hooks/auto-format.sh" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "sh .claude/hooks/check-pending-todos.sh" } ] } ] } }

对应的guard-danger-commands.sh可以写成这样：

#!/usr/bin/env bash input="$1" dangerous_patterns=("rm -rf /" "DROP TABLE" "git push --force") for pattern in "${dangerous_patterns[@]}"; do if echo "$input" | grep -q "$pattern"; then echo "blocked: 检测到高危命令 $pattern，已阻止执行。" exit 2 fi done exit 0

钩子通过标准输入接收 JSON 格式的事件数据，第一个参数是事件 JSON，所以脚本里读取$1能拿到具体命令内容。exit 0表示放行，exit 2表示阻止。我用这个号区分业务逻辑错误和人为拦截，调试起来更容易定位问题。

4.3 编辑 hooks 时的调试方法

钩子脚本有个让人头大的特点：它是静默失败的。AI 在终端里命令执行失败，还能看到红色的报错，但钩子脚本如果出问题，可能只是日志里多了一行hook failed，不影响主流程。所以我在开发钩子阶段会特意让脚本输出大量调试信息。

最实用的做法是：先在终端里手动跑一遍钩子脚本，把事件 JSON 存成文件，再用它当输入来调脚本。比如：

# 把真实事件 JSON 存下来 cat <<< "$(claude hooks debug-event PreToolUse)" > /tmp/event.json # 直接用这个文件测试脚本 sh .claude/hooks/guard-danger-commands.sh < /tmp/event.json

这样每次改脚本不需要重新启动 Claude Code，直接循环调脚本后再测试。等你确认稳定了，再去掉多余的调试输出。

另一个经验是钩子脚本不要用太新潮的语法特性。Claude Code 的钩子最终是在本机 shell 里跑的，不同机器上的 bash 版本差距巨大。我统一用最基础的 POSIX 语法写脚本，规避掉一群“在我电脑上明明是好的”问题。

5. 第四层：Agent Skills——把团队方法论喂给 AI

5.1 Skill 模板的基本结构

Agent Skills 是 Claude Code 里相对较新的能力。它本质上是一组 Markdown 文件，放在.claude/skills/<skill-name>/目录下，每一个 Skill 目录里必须有一个SKILL.md作为入口。

SKILL.md的头部需要 YAML frontmatter，里面至少要有name和description。description非常关键，因为它是 AI 判断“什么时候该加载这个 Skill”的依据。如果你的描述里包含了触发场景的高频词，AI 就更可能在相关任务发生时主动加载这个 Skill。

一个典型的 Skill 文件结构长这样：

--- name: dependency-audit description: Review package dependencies for security, duplication, and architecture fit. Use when analyzing package.json or dependency-related issues. --- # Dependency Audit ## 背景 本技能用于检查一个 Node.js 项目的依赖健康状况。 ## 执行步骤 1. 读取 `package.json`，列出顶层依赖清单。 2. 检查重复依赖，确认是否存在同一功能的不同库。 3. 识别长期未更新的依赖，评估升级风险。 4. 检查是否有已被标注为 deprecated 的包。 5. 输出一份 dependencies 风险报告，按严重程度排序。 ## 判断标准 - 同一个核心功能出现两个以上库时，给出合并建议。 - 依赖版本落后主版本超过 3 年时，标记为高风险。 - 框架级别的依赖必须与项目主体技术栈保持一致。

5.2 我推荐的三个轻量 Skill

Skill 这种东西，做多了容易变成知识库垃圾场。我目前长期维护的只有三个轻量 Skill，效果比维护二十个强得多。

第一个是codebase-guide。它存储的是“如何阅读这个项目的代码”的方法论，比如“先看哪个文件夹”“核心链路在哪个模块”“什么时候该看 OpenAPI 文档”。表面上是给 AI 的导航，实际上是在把团队新人的 onboarding 手册翻译成 AI 能读的格式。

第二个是test-writer。它存的是这个团队写测试的风格约定，比如“测试命名规范”“mock 偏好”“集成测试和单测的边界”。AI 加载这个 Skill 之后再写测试，就不再出现“测了一个没用函数”或者“mock 了不该 mock 的依赖”这种尴尬情况。

第三个是error-diagnosis。它是一套排查报错的固定流程：先复现，再缩小范围，分开检查代码和配置，最后看系统日志。这个方法论听起来很简单，但对 AI 特别有用。没有这套流程时，AI 面对一个报错经常东猜一下西猜一下，加载 Skill 之后就会老老实实按步骤走，反而更快能定位到问题。

5.3 Skills 和命令模板怎么分工

这是我被问得最多的区分问题。命令模板是“人主动触发的一次性动作”，技能是“AI 根据场景自动选择的方法论”。同样是做代码审查，/review命令适合你主动喊一句“给我审查一下最近改动”，而code-review-guideSkill 适合在 AI 日常修改代码的过程中，自动遵守一套审查标准。

所以我的建议很直接：如果某个流程是你要主动执行的，做成命令模板。如果某个流程希望 AI 在背后一直遵守，做成 Skill。两者可以配套使用，比如命令模板里注明“请先加载某 Skill”，AI 就会在触发命令时把对应的技能文件一并纳入上下文。

6. 第五层：脚手架——让新项目五秒启动

6.1 最小可用目录结构

四层模板本身已经很能打了，但要让“整套体系”真正落地到新项目，还差最后一步：脚手架。我维护了一个claude-code-templates仓库，里面保存了一套完整的模板骨架，新建项目时直接复制进去就行。最小的目录结构长这样：

project/ ├── CLAUDE.md └── .claude/ ├── settings.json ├── commands/ │ ├── review.md │ ├── add-test.md │ └── new-api.md ├── hooks/ │ ├── guard-danger-commands.sh │ ├── auto-format.sh │ └── check-pending-todos.sh └── skills/ ├── codebase-guide/SKILL.md ├── test-writer/SKILL.md └── error-diagnosis/SKILL.md

这个结构一小部分我直接用上一份项目的，大部分是最近整理出来的子类。我试过把整个模板库硬拷到仓库里，结果每次项目迭代都要同步主仓库，累死。现在改成“按需复制 + 模板仓库版本管理”的组合策略，舒服多了。

6.2 应用脚手架的自动化脚本

手工复制多了还是会烦，所以我在模板仓库里放了一个bootstrap.sh，用它一键初始化。核心逻辑很简单：复制目录、替换占位符、根据交互输入写入项目名和技术栈。

脚本片段示意：

#!/usr/bin/env bash set -euo pipefail template_dir="$(dirname "$0")/template" target_dir="${1:?Usage: bootstrap.sh <target-dir>}" cp -r "$template_dir"/. "$target_dir"/ cd "$target_dir" # 替换项目名占位符 sed -i "s/__PROJECT_NAME__/$project_name/g" CLAUDE.md # 根据技术栈选择性的保留命令模板 if [[ "$stack" == "node" ]]; then mv .claude/commands/new-node-service.md .claude/commands/new-api.md fi rm .claude/commands/__unused__.md

我刻意让脚本保持简单。有些人喜欢用交互式引導，但我追求的是“新环境里一分钟跑完，而且每一条命令都看得懂”。一旦脚本复杂到需要调试，就违背了脚手架工具的本意。

6.3 分发和团队同步

模板仓库本身也扔在 git 里，这个不用多说。团队协作时有两种同步方式。第一种是直接复制，适合模板还不稳定、团队规模小于五人的时候；第二种是用 git submodule 或者 subtree 挂到各项目里，适合模板已经稳定、且多个项目需要共用时。

我想强调一个细节：模板仓库里的任何修改，都不会自动同步到已经复制出去的项目里。所以团队里要有一个明确的“模板更新流程”。我的做法是每季度抽出半天把各项目中已经跑通的改进合并回模板仓库，反向把模板仓库的更新公告发到团队频道。这个过程虽然手动，但它能强制大家思考“这条规则真的适合所有项目吗”，不至于把特别个性化的规则硬化成全公司模板。

7. 实战排错与避坑笔记

7.1 常见问题速查表

我把这一年来最常遇到的问题整理成一份速查表，大家可以直接对着查。

这些问题绝大多数不是 Claude Code 本身的问题，而是我们作为使用者的工程习惯问题。模板体系本质上也是一套工程系统，排错思路和调试后端服务没什么两样——先确认配置加载了没有，再确认输入输出是否符合预期，最后才查业务逻辑。

7.2 那些文档不会告诉你的小细节

经验里还有几个细节，十分隐蔽，这里一并记录下来。

第一个是：命令模板里尽量不要写死超长常量。把一大段 JSON 直接塞在命令模板里，会导致每次触发时上下文被瞬间占满，后续对话的质量明显下降。我的做法是把长内容放进单独的文件，命令里只写“参考.claude/context/api-rules.md中的定义”，让 AI 按需读取，而不是一次性把全部内容灌进上下文。

第二个是：CLAUDE.md并不是只会读根目录的那个。Claude Code 会从当前工作目录向上逐级寻找CLAUDE.md，也会识别子目录中的同名文件。利用这个机制，我经常把大的规则拆成两层：根目录放全局约束，子模块目录放局部约束。比如apps/web/CLAUDE.md只讲前端特有的事项，根目录的CLAUDE.md讲各端共用的规则。

第三个是：钩子脚本的标准输入是 JSON 数据流，不是普通参数。很多人都栽在这里过，动不动就写成cat $1，结果发现 reads 不到内容。正确做法是input=$(cat)或者把脚本写成从 stdin 读取解析 JSON。还要记得用jq做字段提取，比用 grep 硬抠字符串要可靠得多。

第四个是：模板仓库里不放私密信息。这是最重要的安全底线。我见过有人把数据库连接串、API token 直接写进CLAUDE.md，AI 在执行对话时有概率把它带进日志或者外部调用中，潜在风险非常大。所有的密钥类信息必须通过环境变量注入，模板里只保留变量名占位符。

7.3 从“复制粘贴”到“体系化沉淀”的转变

我前面写的这些，本质上是一次思维转变的总结。最开始我也只是一个简单的复制粘贴玩家，每次建项目都去旧的仓库里翻CLAUDE.md和命令目录，然后慢慢补丁式地加内容。这种方式虽然能跑，但每一次手工复制都是错误发生的窗口。

当我开始用模板仓库统一管理之后，新的问题出现了：模板更新了，老项目怎么合入？解决方案就是我在 6.3 里写的 submodule 和定期回流。这套流程跑顺之后，我的新项目从“初始化 Claude Code 环境”到“AI 能稳定地按项目规范工作”，花的时间从原来的一个上午缩短到十分钟以内。

这个收益不只是效率上的，更重要的是确定性。以前每次都靠对话提示词去约束 AI，效果随我的心情和技术水平波动；现在模板就是制度，制度就是产出质量。AI 依然是那个 AI，但使用 AI 的方式已经变成了一条可追踪、可回滚、可团队复用的流水线。

最后分享一个小技巧：定期去翻一翻你项目里的.claude目录，看看哪些命令模板半年都没被用过，果断删掉。模板不是收藏癖的玩具，留着不用的模板只会增加 AI 误触发的概率。保持精简，保持克制的模板库，比堆了一堆看似全面实则无用的文件，更能让你在真正的任务里跑得更快。