企业官网建设流程全解析

聊到claude-code-templates，先说说我自己的经历。最初接触 Claude Code 时，我完全没考虑模板这回事，每次干活都是在命令行里现场敲提示词，今天让 AI 做代码审查，明天让它写测试，后天让它重构模块。结果就是同一个项目里，AI 的行为风格一天一个样，有时候它太啰嗦，有时候又太沉默；该限制的工具没限制，不该让它动的文件它反而动了。直到我把整套 prompt、命令、子代理、钩子规则沉淀成模板库，才真正把 Claude Code 从"一个聪明的对话窗口"变成了"一个符合我团队习惯的虚拟结对程序员"。

这篇文章想写的就是这套claude-code-templates模板体系：它包含哪些文件、每个文件解决什么问题、怎么从零搭建并复用、多项目怎么同步，以及我在实际使用中踩过的坑。不管你是刚接触 Claude Code 的新手，还是已经用了一段时间但觉得"差点意思"的老手，这套模板思路都能帮你把 AI 编码工作流固定下来，减少重复调教，也减少意外破坏。

1. 模板体系到底在解决什么问题

1.1 没有模板时的工作流痛点

我见过太多人用 Claude Code 的方式是"裸奔"：装好命令行工具，直接在会话里说"帮我看下这个项目"。工具确实很聪明，但有两个绕不开的问题。

第一个问题是上下文管理失控。Claude Code 默认会读取项目文件、git 状态、目录结构，但如果项目里没有一份明确的说明文件，它对业务规则、代码风格、目录约定的理解全靠猜。你可以在对话里反复纠正，但新会话一开，它又"失忆"了。第二个问题是权限和流程不可控。默认配置下，AI 可能会尝试执行它认为合适的命令、修改它认为相关的文件，而"它认为"和"你认为"之间经常存在一条很宽的裂缝。

我自己踩过一个典型例子：让 AI 修一个前端组件的小问题，结果它顺手把 package.json 里的依赖升级了，CI 直接红了一下午。问题本身不大，但暴露了一个关键点——如果没有模板把"哪些操作允许、哪些操作先问、哪些操作绝对禁止"说清楚，你再怎么在单次对话里强调，下个会话还是会忘。模板的本质，就是把一次性的口头约定，变成项目里持久、可复用、可版本管理的显式配置。

1.2 模板体系的核心组成

一套完整的claude-code-templates，核心是由四种文件组成的，我习惯把它们称作"四件套"：

• CLAUDE.md：项目级说明书，告诉 AI 这个项目是什么、代码组织方式、技术栈、常用命令、约定和禁忌。它相当于给 AI 的"入职手册"。
• commands 目录（Slash Commands）：把高频任务固化成命令，比如/review、/fix、/test。每个命令是一个 Markdown 文件，里面写清楚触发后 AI 该做什么、按什么步骤做、输出什么格式。
• agents 目录（Subagents）：定义角色化的子代理，比如"代码架构师""安全审计员""测试策略师"。每个子代理有独立的人格和行为边界，适合在复杂任务中并行分工。
• hooks 配置：在关键事件上挂脚本，强制流程。比如"用户提交提示词时"、"AI 调用工具之前"、"AI 生成回复之后"，都可以触发脚本做校验或拦截。

这四件套分别解决不同层次的问题：CLAUDE.md 管"背景和记忆"，commands 管"高频操作的标准化"，agents 管"复杂任务的角色分工"，hooks 管"流程的安全兜底"。

1.3 模板复用的设计原则

在动手写模板之前，我建议你先想清楚一条原则：模板是给 AI 看的代码，不是给人看的文档。这句话有两层意思。

第一，模板内容要有明确的指令性。你写"项目使用模块化架构"远不如写"新增业务代码请放到src/modules/下，每个模块包含controller/、service/、dao/三个子目录"有用。第二，模板要尽量短小、可执行。AI 处理冗长文本时也会"注意力稀释"，写一大堆背景介绍不如直接给它一份目录结构图和三条操作硬规则。

另外，我强烈推荐把模板库当成代码来维护：放进 git 仓库，写 commit，做版本管理。我甚至会单独建一个templates仓库，和项目代码分离，然后通过软链接或脚本把模板分发到各个项目里。这样你升级模板时，可以批量同步到所有项目。

2. 核心文件逐个拆解

2.1 settings.json：先把权限和安全边界定死

很多人容易忽略的一个事实是：模板体系里最先应该写的不是 prompt，而是权限配置。Claude Code 的权限逻辑通常由settings.json控制，分项目级和用户级两层。项目级的放在.claude/settings.json，用户级放在用户主目录下的.claude/settings.json。用户级适合放通用规则，项目级适合放这个项目特有的边界。

我建议至少关注这几个配置项：

• permissions.allow：允许 AI 直接执行的操作白名单，比如Read、Edit、Bash(npm run lint:fix)。注意：白名单越短越安全。
• permissions.ask：需要先询问用户的操作，比如Bash(git push:*)、Edit(api/**/*)。
• permissions.deny：绝对禁止的操作，比如Bash(rm -rf *)、Edit(credentials.json)。
• model：默认模型，可以用model: "sonnet"或"opus"来控制复杂度和成本。
• env：为 AI 设置环境变量，比写在 shell 里更聚焦。

所以哪怕你的 prompt 写得再漂亮，只要权限配置不靠谱，翻车是迟早的事。命令类的授权粒度要尽可能细。举例来说，与其允许Bash(npm install)，不如列清楚依赖锁定情况后再决定；对于会写入全局状态的命令，比如git push、docker compose up，务必放进ask列表，让 AI 每次执行前都跟你确认。

2.2 CLAUDE.md：给 AI 写一份高质量“入职手册”

CLAUDE.md 是整个模板体系里性价比最高的一个文件，但它也是被人误解最深的一个。它不是在写"项目介绍"，而是在写"AI 在这个项目里的行为准则"。

我的写法一般分成五段：

1. 项目极简摘要：用三五句话说明系统是什么、核心业务边界在哪、技术栈要点。
2. 命令速查：列出开发中最常用的命令，比如构建、测试、lint、启动 dev server、数据库迁移。格式是"命令：作用"。
3. 目录结构约定：不需要贴全部目录树，只写关键的、AI 容易猜错的部分。例如"src/api/下是路由定义，src/services/下是业务逻辑，两者不要互相直接调用"。
4. 代码风格与架构规则：这是真正的干货区。比如"新代码使用 TypeScript 严格模式""错误处理优先返回 Result 类型而不是抛异常""数据库表结构变更必须附带迁移脚本"。
5. 硬性禁忌：明确列出 AI 不该做的事，比如"不要修改dist/目录下的产物""不要在没有用户确认时执行git push""不要升级第三方依赖的主版本"。

写 CLAUDE.md 时有个常见误区：试图把所有信息都塞进去。实际上 Claude Code 对超长文档的处理是检索式引用的，你塞得越多，关键信息反而越不容易被触发。更好的做法是：保持 CLAUDE.md 本身短小精悍，把细节放进项目内的技术文档里，然后在 CLAUDE.md 中写明"遇到 X 类问题时，先阅读docs/architecture.md"。

还有一个技巧：CLAUDE.md 里可以用引用文件的方式，把多个分散的说明合并进来，但把最核心的规则放在最顶部。因为 AI 读取上下文时对前面的内容权重通常更高，把最重要的"禁忌清单"放在文件头部，效果比藏在文末好很多。

2.3 Slash 命令模板：把高频操作变成按钮

CLAUDE.md 解决"AI 懂不懂项目"的问题，Slash 命令解决的是"AI 每次干活靠不靠谱"的问题。它的思路和快捷键差不多：把你反复做的操作，固化成/命令名，敲下去就不用再重复解释背景和期望了。

Slash 命令在.claude/commands/目录下，每个命令一个 Markdown 文件，文件名就是命令名。文件头部有一段 YAML frontmatter，里面可以定义命令的描述、可用工具、模型等元信息，核心的description会被展示在命令列表里，所以要写得一看就懂，比如"审查当前分支代码改动并生成审查报告"。

命令正文就是真正的 prompt，它能接收到用户输入的参数。最常用的是$ARGUMENTS，代表用户在命令后输入的完整参数。比如/review --focus=security，$ARGUMENTS就是--focus=security；你还以在 frontmatter 里声明参数提示，让用户知道该填什么。

我实际最常用的几个命令是：

• /review：让 AI 审查当前改动，按"正确性、安全性、性能、可维护性"四层输出问题列表。
• /fix：指定文件或错误信息，让 AI 局部修复而非大范围重写。
• /test：让 AI 为当前改动补测试，输出可执行的测试代码并运行。
• /explain：让 AI 解释一段代码的逻辑，输出调用关系图和关键设计取舍。

命令的价值在于把质量标准给固定下来。同样是"写测试"，不同程序员心里的标准完全不一样。你在/test命令里写清楚"必须包括正常路径、异常路径、边界值三类用例"，AI 每次执行都会遵守这个标准，这就是模板比临时对话强的地方。

2.4 Subagents：给复杂任务配一个专业角色

如果你发现单个 Claude Code 会话同时做架构设计、代码编写、安全检查会很累，而且经常上下文混在一起出昏招，那就该上 Subagents 了。Subagent 本质上是独立的子任务执行单元，有自己的 context window、人设和可用工具，工作时不会和主对话互相污染。

定义方式是在.claude/agents/目录下建 Markdown 文件，每个文件同样有 YAML frontmatter：name、description、tools、model。description很关键，它是主模型判断"什么任务该交给哪个 subagent"的依据，所以写作重点反而是"这个 agent 适合处理什么、不适合处理什么"。

我目前模板库里常驻三个角色：

• 代码架构师：负责梳理模块关系、评估重构方向、检查依赖隔离。我给它配置了Read和Grep工具，但禁止它直接改代码。这样它能给出客观的评审意见，而不会手痒去改文件。
• 安全审计员：负责检查代码中的注入、越权、敏感信息硬编码、依赖漏洞。它被允许跑Bash(git log *)和读安全相关文件，但默认模型选更谨慎的版本。
• 测试策略师：负责分析现有测试覆盖率、指出高风险区域、生成测试计划。它生成的用例模版会交给主会话去落地。

用 subagent 的最大好处，是可以把不同角色的系统提示词彻底隔离。比如"安全审计员"的 prompt 会反复强调"只报告问题，不顺手修复""禁止在报告中隐瞒高危风险"，这些约束在一个人格下能稳定执行，但混在主对话里很容易被其他任务冲淡。如果你团队里的任务经常涉及多角色配合，花时间做好 agents 是你回报最高的投入。

2.5 Hooks：把流程和安全规则变成强制约束

无论模板文件写得多好、命令设计得多细，总会有意外情况。Hooks 就是最后一道兜底防线，它在关键事件点触发一段预定义脚本，脚本会收到事件相关的 JSON 数据，然后可以决定"放行""阻止""修改"AI 的行为。

Claude Code 里常用的 hook 事件包括：

• UserPromptSubmit：用户在对话中提交消息前触发，适合做敏感词检测或动态注入上下文。
• PreToolUse：AI 准备调用任何工具前触发，这是最常用的拦截点，基本的安全检查都在这层做。
• PostToolUse：AI 调用完工具后触发，适合做文件变更后的 lint、格式化或状态记录。
• Stop：AI 生成完回复即将结束时触发，可以在这里统一记录会话日志。

举个我实际在用的例子。我在PreToolUse里挂了一个脚本，匹配条件是Bash且命令中包含git push时直接返回 blocked，同时给出提示"推送操作请走团队代码评审流程"。这个规则单独靠 CLAUDE.md 很难百分百生效，因为 AI 一次没被阻止，下次可能还会犯，但 hooks 是程序级拦截，说不行就是不行。

再比如PostToolUse里我会监听Edit事件，在 AI 修改完文件后自动跑一下prettier --check。如果格式不对，就让钩子脚本给 AI 返回一个修正提示，相当于给每次自动编辑加了个质量门。这个能力是纯 prompt 做不到的，属于"规矩写在代码里"的典型场景。

3. 实操：从零搭建一套可复用的模板库

3.1 目录结构和初始化

我建议你在自己的电脑上建一个独立的模板仓库，而不是直接在项目里开写。这样做的好处是可以在多个项目间复用，也能单独做版本管理。我常用的目录长这样：

claude-code-templates/ ├── README.md ├── setup.sh # 一键分发/更新脚本 ├── user/ │ ├── settings.json # 用户级权限 │ └── agents/ # 通用 subagents │ ├── security-auditor.md │ └── code-architect.md └── project/ ├── CLAUDE.md.tpl # 项目说明书模板 ├── settings.json.tpl # 项目级权限模板 ├── commands/ # 通用 slash 命令 │ ├── review.md │ ├── fix.md │ ├── test.md │ └── explain.md └── hooks/ # hooks 脚本 ├── block-push.sh └── prettier-check.sh

初始化时，我会在用户主目录的.claude/路径下放置用户级文件和通用 agents，再把项目级模板分发到各自项目仓库的.claude/目录。setup.sh做的事情很简单：先检查.claude/目录是否存在，不存在就创建，然后把模板文件复制过去。我特意用软链接的方式处理 commands 目录，这样模板仓库更新一个命令，所有项目立即生效，不用再手动同步。不过软链接在 Windows 上需要开启开发者模式，团队里的 Windows 同事偶尔会踩这个坑，所以我也会在脚本里处理权限问题。

3.2 编写核心命令：review、fix、test

写 slash 命令最重要的原则是：不要试图让 AI "理解"你的意图，要让它"执行"你的条款。拿/review举例，我的命令文件大致是这样的：

--- description: 审查当前分支的全部代码改动，输出分级问题清单 argument-hint: [--focus=<正确性|安全性|性能|可维护性>] --- 你是一名资深代码审查者。请执行以下步骤： 1. 运行 `git diff HEAD~1` 查看当前分支的完整改动。 2. 按以下四个维度逐一审查，严禁跳项： - 正确性：逻辑错误、边界未判断、资源未释放。 - 安全性：注入风险、越权访问、敏感信息泄露。 - 性能：明显低效的循环、不合理的 IO、缺失的缓存。 - 可维护性：命名模糊、函数过长、重复代码。 3. 若用户通过 --focus 指定了维度，则只审查该维度。 4. 输出格式为分级清单： - 🔴 P0：必须修复，阻断合入 - 🟠 P1：强烈建议修复 - 🟡 P2：可与后续迭代合并处理 5. 如果所有维度都没有问题，输出"未发现需要阻塞合入的问题"，不许为了凑数硬找问题。

这里有几个要点：给 AI 设一个"宁可漏报不可误报"倾向能显著减少噪音；步骤要明确到"先跑什么命令再看什么"，避免 AI 凭感觉行动；输出格式固定，后续接 CI 解析或人工 review 都很方便。

/fix的写法则完全不同，它强调的是限定范围。我的命令里会先让 AI 复述它准备修改的文件清单，经用户确认后才能动手。这个"预确认机制"非常管用，因为 AI 最容易犯的错就是一修修一片。那种把 20 个文件的改动直接铺开的操作，哪怕内容没错，review 成本也高到吓人。

/test命令我会把测试策略直接写进模板：不追求覆盖率数字，但规定"每个新增或修改的函数必须覆盖正常路径、异常路径、空值/边界值"。这三个词听起来简单，但实际执行时 AI 的产出质量会有天壤之别。你手动写一遍这段命令后，再对比一下没有命令时候的随意发挥，会明显感觉到模板的价值。

3.3 设计 subagent 角色模板

Subagent 的设计难点不在 prompt 文采，而在能力边界的设置。前文提到的安全审计员，我最终的 agents 文件大概长这样：

--- name: security-auditor description: 执行安全审计。适合在代码合并前检查注入、越权、敏感信息泄漏、依赖漏洞等安全问题。不适合做常规代码风格检查。 tools: Read, Grep, Bash model: sonnet --- 你是一名独立的代码安全审计员。以下是你的行为准则： 1. 只报告安全问题，不要顺手修改代码。除非用户明确要求，否则你给出的输出是问题清单而非补丁代码。 2. 审查重点包括： - SQL 注入、命令注入、路径遍历 - 越权访问（缺少鉴权或权限校验） - 硬编码密钥、令牌、数据库连接串 - 使用了已知存在漏洞的依赖版本 3. 每个问题必须标注文件路径、行号倒推逻辑、影响等级（高/中/低）和修复建议。 4. 如果某项风险不存在，明确写"未发现"，禁止含糊其辞。 5. 你的输出会被直接贴进代码评审系统，所以格式必须结构化。

重点在于description里的"不适合做"部分，这能防止主模型啥事都丢给它；tools限定了它能读哪些信息，防止它乱跑命令；model的选择则关乎质量和成本的平衡，安全审计这类任务对稳定性要求高，用更好的模型回报也更明显。

创建 subagent 后，你还可以要求主会话调度它。比如 main 任务下Use the security-auditor subagent to review the auth module，主模型就会自动委派。多角色并行时，注意任务切分要足够独立，接口一旦出现相互等待，整个流程就会卡住。

3.4 配置 hooks 做质量闸门

Hooks 的实现和配置是模板体系里最像"写代码"的部分。以"阻止 git push"为例，步骤是这样：

首先在项目.claude/settings.json中声明 hook：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash .claude/hooks/block-push.sh" } ] } ] } }

然后编写脚本，核心逻辑是从 stdin 读取 JSON，判断 command 里是否包含git push，如果包含就返回带blocked标记的 JSON：

#!/usr/bin/env bash input=$(cat /dev/stdin) tool_name=$(echo "$input" | jq -r '.tool_name') command_input=$(echo "$input" | jq -r '.command_input') if [[ "$tool_name" == "Bash" && "$command_input" == *"git push"* ]]; then echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"decision\":\"block\",\"reason\":\"git push 不允许直接执行，请走代码评审流程\"}}" exit 0 fi echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"decision\":\"allow\"}}"

这块有两点值得注意。一是hook 事件触发频率很高，PreToolUse 每一步都会触发，所以脚本必须轻量，不要写复杂的循环或网络请求，否则整个 AI 响应会明显变慢。二是输出 JSON 格式必须精确，一个字段拼错，hook 就静默失败了，而且往往没有任何报错。我调试时先用一个假样本手动把脚本跑通，再接入 Claude Code，效率会高很多。

PostToolUse 还可以做更高级的事情，比如在 AI 编辑完后自动编译相关模块，把编译错误回传给 AI 继续修。这就形成了一条自动化的"改代码-检查-修错"闭环，只要规则写得准，整个循环就能跑得非常稳。不过要留个心眼：这种循环容易导致 AI 反复试错不收敛，所以一定要给 PostToolUse 的自动修正加次数上限，超过次数就停下来人工介入。

3.5 settings.json 权限模板设计

权限模板必须和命令、hooks 配合，否则命令写得再规范，AI 也可能从旁路把事办了。我项目级的settings.json一般长这样：

{ "model": "sonnet", "permissions": { "allow": [ "Read", "Grep", "Edit", "Bash(npm run lint:fix)", "Bash(npm test)", "Bash(git diff *)", "Bash(git log *)", "WebFetch(api.github.com/*)" ], "ask": [ "Bash(npm install *)", "Bash(git add *)", "Bash(git commit *)", "Edit(package.json)", "Edit(pnpm-lock.yaml)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push *)", "WebFetch(*)", "Edit(config/production.json)" ] } }

这个模板背后有逻辑：allow里只放确定安全、频率又高的操作，让 AI 不用每个小动作都回来问你，流畅度会好很多；ask里放的是"会改变项目状态但不一定有害"的操作；deny里放的是"无论什么时候都不该让 AI 自己做"的高危动作。

一句经验：权限配置宁可先紧后松。刚接进项目时让 AI 多做几次询问不是坏事，你可以观察它的行为模式；等确认它的判断稳定了，再逐步放权到allow。反过来一旦出事，你把权限收紧，整个团队的开发习惯又要重新适应，损失更大。

4. 常见问题与排查实录

4.1 命令加载不出来或行为奇怪

命令文件放好之后，我经常遇到两类问题：要么/review敲下去提示命令不存在，要么命令能触发但 AI 完全没有按我 frontmatter 里的描述执行。

第一类问题的排查思路几乎总是路径问题。确认你的命令文件放在.claude/commands/目录下，文件名后缀必须是.md，且目录名不能写错。第二类问题更隐蔽，通常和 frontmatter 有关：YAML 解析失败会被静默忽略，命令倒是能跑，但 AI 看不到你的描述、参数提示等元信息，自然执行得像是"裸奔"。解决方法是检查 YAML 语法，尤其注意冒号后面是否有空格、多行字符串是否正确缩进。

4.2 上下文爆炸与模板过长

模板文件太长会让 AI 抓不住重点。我自己早期写过一个 3000 行的 CLAUDE.md，觉得自己很全面，结果 AI 连最基本的目录约定都会搞错。后来做了减法，把文档压到 80 行核心规则加几个"遇到 X 时读 Y"的指引，效果反而好了很多。这个现象背后的原因叫做"lost in the middle"，对 AI 来说超长上下文里中间段落的注意力权重会衰减，所以关键规则得放开头，剩下细节放文档链接。

如果遇到"AI 老是读取无关文件"的问题，可以考虑在 CLAUDE.md 里显式标注"忽略以下目录：docs/archive/、vendor/、node_modules/"。这个操作看起来简单，实际对上下文预算的节省非常明显。

4.3 多项目模板同步问题

当你同时维护五六个项目时，模板库能不能干净、及时地同步到所有项目，决定了整个体系是否会烂尾。我之前用"复制粘贴"的方式分发，结果有的项目落后三个版本，有的项目被我一次性覆盖掉了本地定制内容，苦不堪言。

后来的方案是"模板库 + 软链接 + 分级定制"：

• 通用命令（review、fix、test）全部用软链接指向模板仓库，改一处，所有项目生效。
• 项目级 CLAUDE.md 不软链，因为几乎每个项目的业务背景都不同，它天然该是各写各的。不过我会在模板仓库里维护一份 CLAUDE.md 的"骨架模板"，新项目初始化时由setup.sh复制并引导填空。
• settings.json 的权限部分做一个基础版，但每个项目还要再加一层自己的deny规则，尤其涉及生产配置、部署脚本的内容。

这样既保证了通用能力的一致更新，又给每个项目保留了定制的空间。同步脚本真正执行的时候我还会加一个--dry-run参数，先打印将要操作的文件清单，人确认后再真正动手。

4.4 常用问题速查表

这张表基本覆盖了我被问到最多的场景。其余的大多数问题，绕来绕去最后都会回到一句话：先确认你自己设的规则，有没有真正进入 AI 看到的那份上下文里。

5. 模板体系的扩展心得

模板固定下来之后，你会慢慢发现一个有意思的变化：你不再需要操心"这次该给 AI 什么提示词"，而是开始操心"这次该跑哪条命令、该让哪个 agent 上"。这个心智模型的转变，才是模板体系真正的收益。

我在实际使用中还会把模板库和一个简单的"命令使用手册"文档绑定在一起，每个命令只写一小段说明加一个示例。这个文档不是给 AI 看的，是给团队新同事看的。新人在我的指导下，花半天读文档、跑几条命令，基本就能掌握"用 /review 做合入前检查、用 /fix 做定向修改、把复杂重构拆给架构师 agent"这套全流程，学习成本低到几乎没有。

最后再分享一个小技巧：模板库一定要定期复盘。我每两个礼拜会看一眼近期 AI 协作失败的实际案例，把新问题沉淀成新的命令参数、新的 deny 规则，或者一条新的 CLAUDE.md 条款。模板不是写完就完事的静态文档，它应该跟着你和团队的做事方式一起成长。花在这个复盘上的时间，比你在单次会话里反复调教 AI 的碎片时间，不知道划算到哪里去了。