企业官网建设流程全解析

我维护自己的 Claude Code 模板仓库已经快半年了，从最开始在会话里随手贴一段 prompt，到后来把所有高频操作都沉淀成 claude-code-templates，算是把这条路完整走了一遍。这篇文章不是讲某个库的 README，而是把我整理的模板结构、命令脚本写法、hooks 设计思路全部拆开讲，适合已经用过 Claude Code、想把它变成团队生产力工具的人，也适合刚接触这个工具、想一步到位搭好工作流的开发者。

直接说结论：模板的意义不是"省几行字"，而是让 AI 的行为可预期。没有模板，每次对话都是一次新的掷骰子；有了模板，至少你投喂给模型的上下文是稳定、结构化的。下面按我在实际项目里沉淀模板的顺序，逐个模块讲透。

1. 为什么在 Claude Code 工作流里，模板比提示词更重要

1.1 从"每次重写 prompt"到"模板驱动"

我最早用 Claude Code 的时候，动辄在终端里敲上千字的上下文：项目架构、技术栈、目录结构、注意事项、本次任务目标。一次两次还能忍受，等任务多了就会发现几个问题：

一是相同的信息重复描述，口径还不一致。比如我一开始写"后端是 Python 3.11 + FastAPI"，后一次改成"Python 3.12 + FastAPI"，模型可能就把两个版本都当成事实混在一起处理。二是每次会话都要重新"教育"模型项目规则，真正干活的时间被压缩。三是团队里每个人给 Claude 的指令风格完全不同，A 让模型写单测，B 让模型写文档，出来的代码风格和质量完全不可控。

claude-code-templates 解决的就是这三个问题。它本质上是一个工程目录，按照 Claude Code 的约定，把项目规则、命令脚本、辅助脚本、参考资料全部塞进去。只要你把这个仓库克隆下来，或者作为子模块挂到项目里，Claude Code 启动时就会自动读取这些模板文件，把"你是谁、项目是什么、该按什么规矩干活"一次性交代清楚。

1.2 模板库最核心的三种形态

在研究 Claude Code 的配置机制后，我把模板分成三个层次，分别对应不同生命周期：

这三个层次各有分工：CLAUDE.md 解决"AI 知道什么"，命令模板解决"AI 能做什么"，hooks 解决"AI 做错之前怎么挡下来"。我见过不少人的 template 仓库里只有 CLAUDE.md，命令目录和 hooks 目录空着，等于只用了 30% 的能力。

1.3 什么时候模板反而是负担

这个部分必须泼一盆冷水：模板不是越多越好。

我试过把几十个斜杠命令塞进.claude/commands，结果输入/之后列表巨长，连自己也记不清每个命令的用途。React 经典的"太多了反而不知道用哪个"问题，在 AI 命令面板里同样存在。后来我把模板按"高频、复用"两个维度做过滤，留下大约 12 个命令，覆盖需求拆解、代码审查、单测生成、重构、提交信息生成这几个刚需场景。

另外，模板文件里的描述如果写得过于抽象，模型对命令的理解就会飘。比如你的命令模板里写"对代码进行全面优化"，模型可能不知道边界在哪里，容易乱改代码。模板文字越具体、约束越明确，实际执行效果越好。

2. CLAUDE.md 是"项目记忆层"：先把类型化知识固化下来

2.1 CLAUDE.md 的自动加载机制

Claude Code 启动时，会从当前目录向上查找 CLAUDE.md，并把它作为系统上下文的一部分加载。这意味着它不需要你手动引用，模型在回答任何问题之前就已经看过这份文件。这是整个模板体系中最基础的机制，也是很多人用不好的一环。

CLAUDE.md 的内容不是给人类看的 API 文档，而是给 AI 看的"项目入职手册"。写它的思路应该跟给新同事写 onboarding 文档类似，但节奏要更紧凑，因为模型对长文本的注意力是有上限的。如果你把 CLAUDE.md 写成 5000 字的需求文档，它反而可能忽略关键信息。

2.2 一份高复用 CLAUDE.md 模板的段落结构

我在 claude-code-templates 里维护的 CLAUDE.md 模板，固定分为六段：

# 项目识别信息 项目名称：xxx-service 技术栈：Python 3.12 / FastAPI / PostgreSQL 16 / Redis 7 语言：项目注释、提交信息、PR 描述一律使用中文 # 架构与目录约定 src/api 放路由，src/services 放业务逻辑，src/models 放 SQLAlchemy 模型 禁止在 api 层编写业务逻辑 新增数据库迁移必须同时更新 docs/migrations/CHANGELOG.md # 命令与运行方式 启动：poetry run uvicorn app.main:app --reload 测试：poetry run pytest tests/ -q --no-header 代码风格：ruff check src/ && ruff format src/ # 现有约定与样式 日志使用 structlog，格式为 JSON 异常码统一使用 BUSINESS_XXX，禁止直接抛裸 Exception 所有接口返回统一包装为 {code, message, data} # 注意事项 - 禁止修改 alembic/versions 下已提交的迁移文件 - 生产环境配置只允许通过环境变量注入，不放进代码仓库 - 删除代码前先搜索是否有引用，破坏性变更必须同步更新 README # 当前任务（会话结束后清空） <在这里描述本次会话的具体目标，避免污染长期规则>

最后这行"当前任务"是我后来加的，用来区分离散任务和长期规则。CLAUDE.md 是持久的状态，而任务是一次性的；如果直接把任务写进 CLAUDE.md，后几次会话它会把旧任务当成项目规则，正确率会下降。

2.3 常见写法误区：把 TODO 写进去、把代码示例写太长

写 CLAUDE.md 最容易踩的坑，我列几个实际观察到的。

第一个是把 TODO、下周计划、未完成需求写进去。模型无法区分"事实"和"待办"，你写"计划接入消息队列"，它可能在下一次会话时直接告诉你系统已经接入了消息队列。解决办法是新建一个project-status.md，通过@project-status.md手动引用，而不是写进 CLAUDE.md 自动加载。

第二个是代码示例过多。CLAUDE.md 里每贴一段代码，模型都会在生成代码时倾向于复刻这段代码的风格和字段，如果示例已经过时，会把旧 API 带出来。我后来把代码示例精简到每个场景不超过 10 行，并明确标注"参考结构，不要直接复制"。

第三个是把 CLAUDE.md 当作唯一的知识来源。实际上一旦工程规模变大，所有内容硬塞一份文件，模型加载起来非常吃力。更合理的做法是 CLAUDE.md 只写高置信度的稳定规则，其余知识分散到 docs 目录，通过额外的@docs/xxx.md引用按需加载。

3. 斜杠命令模板：把高频操作变成可复用的"工作流快捷键"

3.1 命令文件的位置与 YAML frontmatter

Claude Code 的斜杠命令本质上是一段带元信息的 Markdown 或脚本文件。把文件放到.claude/commands/目录下，文件名去掉扩展名就是命令名。比如.claude/commands/review.code.md触发/review。

每个命令模板文件的开头必须包含一段 YAML frontmatter，至少定义description和argument-hint。description很关键，因为当你输入/时，Claude Code 会用它做模糊匹配；argument-hint则是一段提示文本，告诉模型用户传给这个命令的参数长什么样。

--- description: 审查当前分支的改动，给出按严重程度排序的问题清单 argument-hint: "[可选：指定审查范围，如 src/api, src/services]" ---

正文部分就是你的指令。这里有个技巧：把指令写成"规则 + 输出格式 + 约束"三块，比单纯让模型"检查代码问题"效果稳定得多。

3.2 我在 pr-review.code 模板里怎么设计

拿我最常用的pr-review.code.md举例，它是专门用来审查 MR/PR 的：

# 角色与目标 你是资深代码审查者，只基于项目 CLAUDE.md 与当前分支 diff 进行审查，不臆测需求。 # 审查流程 1. 运行 `git diff --stat` 了解改动范围 2. 重点检查：安全漏洞、数据一致性、错误处理、破坏性变更、测试覆盖 3. 如果 diff 超过 800 行，按模块分批审查，先输出总体结论 # 输出格式 按严重程度分三类输出： - **阻塞**：可能导致线上事故、数据错误、安全风险 - **建议**：可维护性、性能与扩展性改进，不影响合并 - **细节**：命名、注释、格式化等非阻塞问题 每个问题必须包含：文件路径、起始行号、问题描述、最小化修复建议。 # 约束 - 不修改任何代码文件，只输出审查结论 - 不重复已知的 lint 错误（如 ruff、eslint 可直接定位的问题） - 如果已有自动化测试通过，则不再建议补充无关单测

这个模板用了三个关键设计。一是"基于 diff 而不是整库分析"，审查速度会快很多，也不会被无关代码带偏。二是"按严重程度分三类"，这样模型不会把格式问题和业务逻辑问题混在一堆输出里，我拿到结论后可以直接决定如何处理。三是"不重复已知 lint 错误"，这是防止模型输出低质量噪音的过滤条件。

3.3 多级参数校验与增量输出

后来自从我发现 Claude Code 的命令模板支持内嵌脚本执行后，我开始在命令模板里混合使用 Markdown 指令和 bash/python 片段。这样做的核心收益是可以做参数校验和上下文预加载。

比如我的/follow-up命令，作用是"基于上一次会话继续开发"。模板里会内嵌一段 bash 脚本，把最近一次会话的摘要文件路径读出来，然后用cat拼接给模型：

# 自动读取最近会话摘要 if [[ -f .claude/session-last.md ]]; then cat .claude/session-last.md else echo "警告：未找到会话摘要文件，本次基于当前代码库状态继续" fi

这比让模型自己去翻历史对话可靠得多。因为 Claude Code 会话之间不会自动共享上下文，你把状态文件当作中间媒介，模板脚本负责载荷，模型只负责处理，分工非常清晰。

如果你在团队里使用这套模板，建议在命令模板里明确输出边界，例如：

• 只输出结论，不输出思考过程的命令（如审查类）
• 允许展示推理过程分析的命令（如排查 bug 类）
• 直接执行修改类命令（如格式化、生成文件名列表）

4. 参考文档模板和 hooks：让规范自动生效

4.1 把技术规范、依赖矩阵做成"可检索常识库"

CLAUDE.md 能承载的知识量是有限的。项目里的规范文档、依赖清单、环境变量说明、部署流程，这些内容如果都写进 CLAUDE.md，既冗长又难以维护。我的做法是把这些内容拆成独立文档，存在CLAUDE-reference/目录下，然后在 CLAUDE.md 里只放一份索引表。

# 参考文档索引 - @CLAUDE-reference/dependencies.md —— 依赖版本与升级注意事项 - @CLAUDE-reference/api-design.md —— 接口设计规范与状态码定义 - @CLAUDE-reference/migration-guide.md —— 数据库迁移流程与回滚方案 - @CLAUDE-reference/production-runbook.md —— 生产部署、健康检查、常见故障

这样模型在需要的时候通过@引用精准加载，而不是把所有文档一股脑读进上下文。依赖矩阵是我个人最喜欢用的一个模板：

| 依赖 | 当前版本 | 可升级版本 | 升级风险 | 备注 | | --- | --- | --- | --- | --- | | fastapi | 0.115 | 0.116 | 低 | 仅小版本更新 | | pydantic | 2.9 | 2.11 | 中 | 需检查自定义泛型 | | sqlalchemy | 2.0.36 | 2.0.40 | 低 | 无破坏性变更 |

模型拿到这个表之后，当发生变化时就能自动意识到"升级有风险要先查迁移说明"，而不是盲目建议升级依赖。

4.2 hooks 模板：在错误发生之前拦截

hooks 是 Claude Code 比较容易被忽略的能力。它在 AI 调用工具、生成内容、会话结束等节点可以触发脚本，实现精确控制。我常用的三个 hooks 模板：

• PreToolUse：在 AI 准备执行危险命令前拦截。比如检查命令是否为rm -rf、DROP TABLE、git push --force，命中则阻断，要求模型先向用户说明修改计划。
• PostToolUse：在 AI 执行完工具后校验输出。比如git diff之后检查是否改动了锁定文件。
• Stop：在每次生成暂停时，把当前状态追加到.claude/session-last.md，方便后续会话延续。

拿PreToolUse的钩子脚本举例（以 bash 模板）：

#!/usr/bin/env bash set -euo pipefail json_input=$(cat) # 提取工具名称和参数 tool_name=$(echo "$json_input" | jq -r '.tool_name') command_str=$(echo "$json_input" | jq -r '.tool_input.command // ""') # 定义危险命令黑名单 if [[ "$tool_name" == "Bash" ]]; then case "$command_str" in *"DROP TABLE"*) echo '{"decision": "block", "reason": "禁止直接执行 DROP TABLE，请输出迁移 SQL 并交由人工执行"}' >&2 exit 2 ;; *"rm -rf"*) echo '{"decision": "block", "reason": "检测到 rm -rf，阻断高危删除操作"}' >&2 exit 2 ;; esac fi # 默认放行 echo '{"decision": "allow"}' >&2 exit 0

这个脚本的结构非常直白：读 stdin 拿到 JSON 参数，判断工具是否命中黑名单，然后向 stderr 输出决策结果。注意输出格式是 JSON，并且一定要>&2，这是因为 hooks 的决策信息走的是错误输出通道，混入 stdout 会导致 Claude Code 解析失败。

把这些 hooks 放进.claude/hooks/后，AI 触发的危险操作就会被自动拦截。这套东西在公司里的价值尤其明显，因为新同事不熟悉项目约束时，AI 的高速生成可能带来潜在的操作风险，而 hooks 是最后一道防线。

4.3 团队场景下模板库的版本控制与同步

最后讲一下模板库的落地问题。单个开发者维护一套模板没问题，但团队协作时，三天两头改模板会让大家很烦。我建议把 claude-code-templates 作为一个独立 git 仓库，然后用子模块或者构建脚本的方式安装到业务项目里。

具体做法是：

1. 模板仓库单独建库，按照目录结构维护，不掺杂任何业务代码；
2. 业务项目通过git submodule add <模板仓库地址> .claude把模板引入；
3. 团队约定每个迭代更新一次模板子模块，比如用git submodule update --remote .claude；
4. 模板仓库的 CLAUDE.md 里写明"变更规则"，比如新增命令必须附带一个使用示例，避免团队成员不知道怎么用它。

我还踩过一个坑：一开始我把模板做成"开箱即装"的 npm 包，直接npx一条命令安装。结果发现模板里有很多项目特定内容，比如团队内部约定的异常码、接口规范，这些内容根本不应该被通用分发。后来我把模板拆成两部分：core部分完全通用（审查流程、hooks 模板、命令骨架），project部分按项目定制。通用部分才进包，项目部分留在 git 子模块里。这个拆分让模板的复用性大幅提升，也不怕敏感信息被传出去。

我个人在实际维护中的体会是：模板库不是写完就一劳永逸的东西。每当我在会话里发现 Claude 重复问同一类问题，或者反复犯同一个错误，我就会打开模板库，把对应的规则或命令补进去。这个迭代过程比你想象中花的时间少，但带来的流畅感提升非常明显。如果你也打算搭建自己的 claude-code-templates，建议从 CLAUDE.md 和三个常用命令模板起步，别一上来就铺开 hooks 和参考文档库，先把最烦人的重复问题解决掉，后面自然知道该往哪个方向扩展。