企业官网建设流程全解析

很多人第一次接触 Claude Code 时，都会有一个特别直观的感受：明明是同一个人写的提示词，换一个项目、换一台机器、换一个同事来跑，出来的效果却像换了个人。你在自己电脑上调教得服服帖帖的 AI 助手，换到别人手里就又笨又愣，连最基本的项目结构都要重新解释一遍。

这个问题的根子，不在于大模型本身行不行，而在于你压根没把该给它的上下文给够、把该定好的规则定好。这也就是claude-code-templates这类模板库存在的真正意义：把项目语境、操作规范、高频任务的执行方式全部固化下来，让 Claude Code 在任何环境下都能稳定地输出高质量结果。

这篇文章我会从一个实际折腾过模板库的人的角度，把整个claude-code-templates的核心机制、目录结构、搭建步骤、实战用法和常见坑位一次讲清楚。

1. 模板不是“锦上添花”，是 Claude Code 的骨架

1.1 为什么同样用 Claude Code，体验天差地别

我见过很多团队把 Claude Code 当成了一个“聊天框”来用，直接打开终端敲一句“帮我看看这个项目的 bug”，然后就等着 AI 自由发挥。这种用法偶尔能出几个漂亮结果，但更多时候你会看到一个拿着 Read 工具疯狂翻文件的 AI，翻了半个小时还在原地打转，最后给出一个泛泛而谈的建议。

问题出在哪？出在 Claude Code 默认状态下对你的项目一无所知。它不知道你的技术栈是什么，不知道你的代码规范是什么，不知道你想要的输出格式是什么，更不知道这个仓库里哪些目录可以直接忽略、哪些文件才是真正的核心。它就像一个刚入职的实习生，能力很强但没有方向，干起活来全凭运气。

而当你把一个设计良好的模板库铺进项目之后，一切都会变得不一样。Claude Code 在启动阶段就能读到项目背景、技术栈清单、目录说明、常见操作规范，遇到高频动作时可以直接调用你定义好的斜杠命令。这时候的它不再是实习生，而是一个带着工作手册的老员工，知道什么该做、什么不该做、做完之后用什么样的格式汇报。

1.2 模板体系到底解决什么问题

抛开那些花哨的“让 AI 更听话”之类的说法，模板体系本质上解决的是三个非常实际的问题。

第一是一致性。同一个仓库，今天张三来跑 Claude Code 是这个效果，明天李四来跑又是另一个效果。你不可能让每个开发者都去手工维护一套自己的提示词，但只要你把模板库放进仓库里，所有人都共享同一份项目语境和操作规范。这就好比你给每个新员工发了一本操作手册，不管谁来操作系统，出来的流程都是一样的。

第二是效率。没有模板的时候，你每开一个会话都要花很长的时间去描述项目背景、解释技术栈、交代注意事项。有了模板之后，这些信息在会话开始就被自动加载了，你可以直接把有限的概念上下文（也就是大模型的 context window）全部花在真正的任务上。我自己的体感是，同样一个需求，有模板的会话至少能比没模板的会话少花三分之一的 token，而且产出的代码质量更稳定。

第三是质量门槛。通过 agents 子代理和 slash commands，你可以把一套严格的“交互准则”固化下来。举个例子，你希望提交代码之前必须跑一遍测试，希望代码评审必须从安全性、性能、可维护性三个维度给出意见，希望生成提交信息时必须遵循 Conventional Commits 规范。这些要求如果靠口头跟 AI 说，每隔几轮对话它就会忘掉，但只要你把它们写进模板和命令里，每一次执行都会被强制遵守。

2. 模板体系的底层机制与目录结构

2.1 CLAUDE.md 是记忆层，不是摆设

在正式开始搭模板库之前，先得把 Claude Code 的上下文体系讲清楚，不然你连文件该放哪、写了有什么用都不知道。整个体系里最核心的文件就是CLAUDE.md，它相当于一个长期的记忆层，会在每次会话启动时被自动加载进上下文。

很多初学者一听“自动加载”，就恨不得把所有想说的话全塞进一个 CLAUDE.md 里，写出一份两千行的项目百科。这个做法非常不可取，因为大模型的上下文窗口是有限的，你在 CLAUDE.md 里塞的每一句废话，都是在挤压真正用于思考任务的资源。更合理的做法是：全局的~//.claude/CLAUDE.md放通用的个人偏好和跨项目规则，项目根目录的CLAUDE.md放这个项目特有的背景信息、技术栈、目录结构说明。

还有一个很多人忽略的细节：Claude Code 不只是读根目录的 CLAUDE.md，它还会读取子目录里的 CLAUDE.md，比如src/module-a/CLAUDE.md，只有当 AI 访问到对应子目录时才会触发加载。这是一个非常实用的机制，你可以用它做梯度记忆：根目录记得少而广，子目录记得深而专。

2.2 .claude/ 目录里的三个核心角色：命令、子代理与钩子

除了 CLAUDE.md，真正的模板体系核心藏在项目的.claude/目录里。这里有几个不同的角色，各管一摊，用好了才算是真正吃透了 Claude Code。

一个是Slash Commands（斜杠命令）。它们放在.claude/commands/目录下，格式是 Markdown 文件。当你创建了一个叫review.md的命令文件，在会话里输入/review就会触发这段预先写好的提示词。命令文件头部可以写 frontmatter 元数据，包括命令的 description、参数提示（argument-hint）、允许使用的工具列表等。这是固化高频操作流程最直接的手段。

另一个是Agents（子代理）。它们放在.claude/agents/目录下。跟普通斜杠命令不同，子代理可以配置自己的模型参数和专属系统提示词，相当于在一个会话里开辟了一个“专职岗位”。比如你想让 Claude Code 切到一个只做代码评审的专家模式，就可以定义code-reviewer这个 agent，把评审标准和输出格式写进它的 system prompt。

还有一个是Hooks（钩子）。它放在.claude/hooks/目录下，配置在 settings.json 里，用来监听工具调用的事件。比如你希望在 AI 执行Bash命令之前自动拦截并检查命令内容，或者在某个工具执行结束后自动触发一个清理脚本，都可以通过 hook 来实现。它是在“会话交互”这个层面之外的自动化护栏，用好了能干很多让你惊喜的事。

2.3 一份标准模板库的基本结构

我建议你直接用一个独立仓库来维护自己的模板库，方便做版本管理和跨项目复用。下面是我目前用的模板库目录结构，你可以直接照着搭：

claude-code-templates/ ├── CLAUDE.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── commit.md │ │ └── test.md │ ├── agents/ │ │ ├── code-reviewer.md │ │ └── test-engineer.md │ └── hooks/ │ └── check-bash-command.sh ├── project-templates/ │ ├── python-fastapi/ │ │ └── CLAUDE.md │ └── react-frontend/ │ └── CLAUDE.md └── README.md

在这个仓库里，CLAUDE.md是全局记忆，commands/保存了一系列可复用的斜杠命令，agents/定义了不同角色的子代理，hooks/放的是自动化脚本。project-templates/目录则是针对特定技术栈生成的项目级 CLAUDE.md，当你启动一个新项目时，直接把对应的子目录内容拷过去，改一改就能用。

这样一套结构下，你在任何新项目里都只需做一件事：把模板库里对应技术栈的 CLAUDE.md 复制到新项目根目录，然后把.claude/目录同步过去，一个带完整上下文的 Claude Code 工作区就瞬间搭好了。

3. 从零搭建一套可复用的 claude-code-templates

3.1 建立全局模板仓库并同步到新项目

动手第一步，是建立你自己的全局模板仓库。这个仓库不一定要公开，但建议做好 git 版本管理，因为模板是会迭代的。

mkdir claude-code-templates cd claude-code-templates git init mkdir -p .claude/commands .claude/agents .claude/hooks project-templates

做完这一步，你还需要在全局配置里指向你的模板库，或者在需要时手动同步。我目前的做法比较简单粗暴：全局记忆放在~/.claude/CLAUDE.md，项目级模板用 git 仓库管理，每次新建项目时直接cp -r复制需要的模板文件。要更精细一点，可以写一个小脚本实现“新项目初始化”，一键把模板复制过去，顺便修改项目名等变量。

3.2 写一份有灵魂的 CLAUDE.md：三个原则

CLAUDEMD 是整个模板体系的灵魂，写得好不好直接决定 AI 的“工作状态”。我总结出了三个原则，你可以直接拿去用。

第一，要具体，不要抽象。不要说“本系统是微服务架构”，要说“本系统包含 order-service（负责订单）、user-service（负责用户），通过 RESTful API 通信，数据库使用 PostgreSQL 15”。AI 需要的是事实清单，不是形容词。你给出的事实越精确，它的推理就越靠谱。

第二，要说“不要做什么”。大模型和人类新手很像，你只告诉它“要做什么”远远不够，得告诉它哪些事情坚决不能做。比如“不要修改 migrations 目录下的文件”“不要使用 lodash 库”“不要在模型层写业务逻辑”，这类负面清单能大幅减少 AI 跑偏的概率。

第三，要保持精简。一条规则如果能用十句话说完，绝不要用二十句。AI 读到冗长的规则时会抓不住重点，反而容易在执行时“选择性失忆”。我见过一个团队的 CLAUDE.md 写了四十多条规范，结果 AI 真正稳定遵守的只有最先写入的七八条，后面的规则基本都在长上下文里被稀释掉了。

下面给你一个可以直接改着用的模板示例：

# 项目：订单管理系统 ## 技术栈 - 后端：Python 3.12 + FastAPI - 前端：React 18 + TypeScript + Vite - 数据库：PostgreSQL 15 + SQLAlchemy 2.0 - 测试：pytest + Playwright ## 目录说明 - src/api/：REST 路由层，只做参数校验和响应序列化 - src/services/：业务逻辑层，核心业务代码都在这里 - src/models/：SQLAlchemy 模型定义，禁止在此写业务逻辑 - tests/：单元测试目录，与 src/ 保持相同结构 ## 关键约束（负面清单） - 不要修改 src/models/ 下的迁移逻辑，迁移文件只能由 alembic 生成 - 不要引入新的第三方库，除非经过技术评审并更新 requirements.txt - 不要使用 print 调试，统一用 logging 模块 - 不要在 api 路由层捕获所有异常，由全局异常处理器统一处理 ## 常用命令 - make dev：启动本地开发环境 - make test：运行全部测试 - make lint：运行 ruff 检查

这份 CLAUDE.md 看起来不长，但每一条信息都在后续的 AI 交互中发挥实际作用。技术栈告诉 AI 生成代码时该用什么语法、什么依赖；目录说明告诉它改代码时该往哪个文件里放；负面清单则拦截了一堆常见的不规范操作。

3.3 用 Slash Commands 固化高频操作流程

CLAUDE.md 解决的是“项目是什么”的问题，而 Slash Commands 解决的是“这件事怎么做”的问题。在.claude/commands/目录下，每一个 Markdown 文件就是一个斜杠命令，文件名就是命令名。

举个例子，我团队里最常用的一个命令是/commit，它的作用是让 AI 根据当前代码变更生成符合 Conventional Commits 规范的提交信息。看一下这个文件的写法：

--- description: 生成符合 Conventional Commits 规范的 git commit 信息 argument-hint: 可选的额外说明，比如本次变更的意图 allowed-tools: Bash, Read, Grep --- 你是一位遵循 Conventional Commits 规范的提交信息生成专家。 先运行 git status 和 git diff 查看当前变更内容，然后按以下要求生成提交信息： 1. 提交类型必须是以下之一：feat（新功能）、fix（修复）、refactor（重构）、test（测试）、docs（文档）、chore（杂项） 2. 使用祈使句写 description，首字母小写，不超过 50 个字符 3. 如果有破坏性变更，必须在正文中写上 BREAKING CHANGE 说明 4. 输出两条备选提交信息，第一条为主推，第二条为备选 5. 输出前不要执行 git commit，等待用户确认

注意到 frontmatter 里的argument-hint了吗？它会在用户输入/commit时提示补充一句可选说明，比如/commit 修复了支付流程中偶尔回调失败的问题。这句额外输入会被追加到提示词末尾，让 AI 在生成信息时有更多方向性的参考。

斜杠命令的价值在于：把一套原本需要每次重复交代的流程，压缩成了一个字符。你不需要在对话里说教“提交信息要用壮语语气、要按规范分类型……”你只需要敲下/commit，AI 自己就知道该去读 git diff、按什么格式输出。这比任何口头约束都稳定得多。

同样的思路还可以做很多命令。/review让 AI 按固定维度执行代码评审，/test让它针对变更内容生成测试用例，/explain让它解释指定模块的设计逻辑。每一条命令都是你把“个人经验”沉淀成“团队规范”的过程。

3.4 用子代理给 AI 配几个“专职员工”

两三年前你会觉得“给 AI 设置角色”是一件有点玄乎的事，但在 Claude Code 里这是实实在在的工程化能力——通过.claude/agents/下的 Markdown 文件定义子代理，可以让同一个会话中容纳多个不同专长的 AI 角色。

子代理的典型配置长这样：

--- name: code-reviewer description: 专职代码评审专家，对变更代码进行严格审查并输出结构化报告 model: sonnet system: 你是一位拥有十年大型系统架构经验的技术评审专家。你的任务是对给定的代码变更进行评审。 评审时必须覆盖以下四个维度： 1. 正确性：是否存在逻辑错误、并发隐患、边界条件遗漏 2. 安全性：是否存在注入风险、敏感信息泄露、越权访问 3. 性能：是否存在明显的性能瓶颈、N+1 查询、不必要的重复计算 4. 可维护性：命名是否清晰、职责是否单一、复杂度是否过高 每个维度输出 3 条以内最重要的问题，按严重程度排序。如果发现严重问题，必须引用具体文件路径和行号。 --- 执行评审时，先读取 git diff 获取变更内容，再读取涉及文件的上下文，最后按上述维度输出结构化评审报告。

当你在会话中调用/code-reviewer时，Claude Code 会启动一个独立的子代理，它只负责代码评审这一件事，不会被你的其他闲聊或无关任务干扰注意力。你可以给它配置更小的模型来节省 token，也可以给它一个和主会话完全不同的“人设”。

这里有个设计上的心得：子代理的 system prompt 一定要写得像“岗位说明书”而不是“使用手册”。你要给它明确的职责边界、输出格式、评审标准，而不是告诉它“请做一个聪明的 AI 助手”。你越是把它当专业人士来要求，它输出结果就越专业。

3.5 用 Hooks 添加自动化护栏

如果说斜杠命令是“主动触发”的流程，那 Hooks 就是“被动触发”的自动化。我在.claude/settings.json里配置 hooks，让 AI 在特定工具调用时自动执行一些检查逻辑。

举一个实际有用的场景：我想阻止 AI 在项目里随手运行pip install或npm install这类会修改依赖环境的命令。为此，我写了一个 hook，在 AI 每次准备调用 Bash 工具之前先检查命令内容，如果发现高危操作就直接拦截并提示。

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hook": "/path/to/claude-code-templates/.claude/hooks/check-bash-command.sh", "timeout": 5 } ] } }

对应的check-bash-command.sh长这样：

#!/usr/bin/env bash input=$(cat) if echo "$input" | grep -qE "pip install|npm install|yarn add|rm -rf"; then echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"halt\": true, \"message\": \"该命令被项目 hook 拦截。如确需执行，请先与用户确认。\"}}" exit 2 fi exit 0

说实话这个 hook 的逻辑非常简单，但它代表了一种很重要的理念：模板体系可以帮你把“AI 的行为边界”以代码的形式固化下来，而不是依赖每次对话时一而再再而三地口头强调。

4. 实战案例：把模板库真正用起来

4.1 场景一：从零开一个新项目时如何秒级接好上下文

假设你要开一个 Python FastAPI 新项目。以前的做法是先让 Claude Code 自己去探索文件结构、猜测技术栈，现在你只需要把模板库里project-templates/python-fastapi/目录下的 CLAUDE.md 复制到新项目根目录，再把.claude/整个拷贝过去。

cp -r ~/claude-code-templates/.claude ./ cp ~/claude-code-templates/project-templates/python-fastapi/CLAUDE.md ./

接着启动 Claude Code，什么都不用写，它就已经知道这是一个 FastAPI 项目、目录结构长什么样、哪些事情不能做。你可以直接开口说“帮我写一个用户注册接口”，它生成的代码从一开始就会使用 SQLAlchemy 模型、放进src/services/的业务逻辑层、补上路由层参数校验——所有细节都在线。

这个体验的差异，用过的人才会懂：以前是“人教 AI 了解项目”，现在是“项目自己告诉 AI 一切”。

4.2 场景二：把代码评审做成标准动作

代码评审是我在模板库上受益最多的场景。在我们的团队里，没有模板的时候代码评审质量全看当天心情，没有固定标准，评审意见也经常一页纸都写不满。但现在我定义了一个/review命令，所有人都用它来跑预提交评审。

实际执行的时候，AI 会先读 git diff，再针对性地翻看涉及文件的上下文，接着按正确性、安全性、性能、可维护性四个维度输出结构化意见。如果你给代码评审 agent 配置了更好的模型，还可以让它给出修改建议的具体代码片段。

我的经验是：用模板固化评审标准之后，AI 提出的问题往往比多数人肉 review 还要全面，尤其是并发安全、错误处理、边界条件这类平时人容易忽略的细节。

4.3 场景三：让 AI 遵循 Git 工作流规范

很多团队对 commit message 都有一套自己的规范，但人肉执行起来很难守住。我在模板库里把 commit 命令做成了带参数提示的版本，配合项目 CLAUDE.md 里的规范说明，AI 生成提交信息时基本不会跑偏。

实操中还遇到过一种情况：AI 在帮忙提交代码时会顺手执行git add .，把所有文件都加进暂存区，这很容易把不该提交的临时文件、环境配置文件带进去。解决方案同样是用 hook 拦截git add .，强制要求只添加明确的文件名。这类小坑如果你不写进模板，真的每隔几天就会踩一次。

5. 常见坑与排查技巧实录

5.1 模板怎么就不生效了？加载顺序和覆盖关系

我遇到最多的问题是 CLAUDE.md 更新了但 AI 依然按旧规则行事。这通常是两个原因：一是会话的上下文里已经缓存了旧的记忆，新会话才生效；二是项目的 CLAUDE.md 覆盖了全局的~/.claude/CLAUDE.md。

Claude Code 的加载优先级大致是：子目录的 CLAUDE.md 会覆盖项目根目录的凭证，项目级会覆盖全局级。如果你改了全局模板希望在项目里生效，先确认项目的 CLAUDE.md 里没有写一条冲突的同名规则。

5.2 命令文件写了不触发怎么办

斜杠命令不触发的常见原因有三个：

• 文件扩展名不是.md，或者文件名里有空格，改成全小写字母和连字符。
• frontmatter 格式写错了，比如description字段拼写不对，或---分隔符没配对。
• 命令文件放在.claude/commands/之外，Claude Code 扫描不到。

我的建议是写完模板之后先在干净环境下跑一下claude看斜杠列表是否出现新命令，别再稀里糊涂写一堆之后找不到问题出在哪。

5.3 加了 hook 之后所有 Bash 命令都被卡住了

hook 逻辑写得太激进是另一个高频坑。如果你在 PreToolUse 里把所有 Bash 都拦截住了，AI 连git status都跑不了，整个会话直接瘫痪。

正确的做法是：hook 的逻辑要精细，只拦截真正危险的操作，其余的放行。而且 hook 脚本里要记得设置合理的超时时间，hang 住的 hook 会直接影响工具调用效率。

另外有一个细节：跑完 hook 脚本之后，如果你想让 AI 看到操作结果的反馈，需要注意输出格式。如果输出的不是预期的 JSON 结构，AI 可能会一脸懵。测试 hook 时最好先在命令行手动运行一遍，确认输出无误再挂到配置里。

5.4 子代理和主会话上下文其实是隔离的

很多人以为定义一个 agent 之后，它什么都知道，其实子代理只能拿到自己 system prompt 里的信息，以及工具调用时读取的文件内容。它并不会自动继承主会话里的上下文。

所以，如果你希望子代理知道某个细节（比如当前分支、本次变更范围），有两种做法：一种是在调用时把上下文写在输入里，另一种是在 agent 的 prompt 里明确要求它先跑git status之类的命令去获取信息。建议优先用后者，因为让 AI 自己读比你费劲描述要可靠得多。

5.5 安全性的隐患：模板会执行命令

这是我特别想强调的一条。模板体系赋予了 Claude Code 很强的能力，但它本身也可能成为风险点。你在模板里写的allowed-tools、你在 hook 脚本里执行的 shell 命令，这些都不是无风险的。

一个极端的例子：如果你从网上直接下载了某个模板库，里面有恶意的 hook 脚本，它可以在你的电脑任意执行命令。我的建议是：不要盲目信任第三方模板，尤其不要跑从网上拿来的 hook 脚本和安装脚本，拿回来后一定要打开读一遍，每一行都看清楚了再挂载。你自己的模板库也要做好权限管理，别把它放到人人可写的共享目录里。

5.6 模板库版本管理的教训

最后再补一个经验：模板库一定要做版本管理。我早期吃过一个亏，某个项目的 CLAUDE.md 被同事改了几行之后，AI 的行为变得很怪异，但我们花了一个多小时排查才发现是模板规则被改了。

后来我把模板库迁移到独立的 git 仓库，建立了简单的分支策略：main 分支只存放经过验证的稳定模板，其他人要改直接提 PR，改完测试通过再合并。项目里只引用仓库的 release 版本，不轻易跟随 main 变动。这套流程虽然简单，但让模板的质量有了基本保障。

常见问题速查表

我个人的体感是，配好一套模板库之后，Claude Code 的工作效率至少提升了一个量级，而且团队的协作体验会变得非常统一。如果你还没有配过模板，我建议你从最小的一套开始：先写项目 CLAUDE.md，再加上两个最常用到的 slash command，剩下的 agents 和 hooks 可以在实际使用中慢慢迭代。模板不是一次写好的，它是你每一次踩坑之后沉淀下来的产物。