企业官网建设流程全解析

把 Claude Code 用顺手之后，我干的第一件事就是整理了一整套 claude-code-templates 目录。这玩意儿说白了就是给命令行里的 AI 编程助手准备的一套“预制动作”——从项目级的 CLAUDE.md 记忆文件，到 /review、/debug、/commit 这类自定义命令，再到配套的提示词模板和自动化脚本。以前我在终端里每次都要把项目背景、代码风格、注意事项从头敲一遍，现在一条命令就能让 Claude Code 进入对应的角色和状态，省下的是大量重复的上下文铺垫，换来的是更稳定、更可控的 AI 协作体验。这篇东西就围绕这套模板聊清楚：它解决什么问题、怎么设计目录、怎么写核心文件、怎么踩坑排错，以及我实际用下来的经验和扩展思路。适合正在重度使用 Claude Code 的开发者，也适合想把团队 AI 协作规范沉淀下来的技术负责人。

1. 先说清楚：claude-code-templates 到底解决什么问题

1.1 我对 Claude Code 的定位理解：这货不是聊天框，是命令行里的“老同事”

很多人第一次接触 Claude Code，会觉得它就是个能读代码、能改文件的聊天机器人。但用久了你会发现，聊天框式的问答和命令行里的 AI 编程助手，体验完全是两码事。聊天框里你问一句它答一句，上下文是断的，它不知道你项目里有哪些约定，也不知道你写代码的风格偏好。而 Claude Code 这种工具，核心价值在于它能长期“待在”你的项目里，通过 CLAUDE.md 这类记忆文件持续了解项目背景。换句话说，它更像是坐你旁边的一个老同事：知道你们项目的目录怎么组织、测试怎么跑、变量怎么命名、哪些坑不能踩。

既然是“老同事”，你肯定不希望每次拉它过来干活，都要重新互相介绍一遍。这就是模板存在的第一个理由：把“老同事的入职培训手册”提前写好。模板化的本质，就是把你平时反复交代的那些话，沉淀成可复用的文件。我今天交代“这个项目用 pnpm，测试跑 vitest，提交信息遵循 conventional commits”，明天遇到另一个项目还是这套，那不如直接做成模板。

1.2 模板的三种作用：记忆、命令、流程

我理解一套完整的 claude-code-templates，由三个层次组成，而不是简单的一个提示词文件。

第一层叫记忆，对应 CLAUDE.md 和项目说明文件。它解决的是“背景信息”问题：项目是什么、架构怎么分层、有哪些关键目录、常见命令是什么。这一层不追求每句话都像咒语一样精确，而是把长期不变的信息固定下来。

第二层叫命令，对应 .claude/commands/ 目录下的自定义 slash 命令。它解决的是“标准动作”问题：代码评审、修 bug、写提交信息、重构、写测试，这些高频任务各有一条命令。你只需要输入 /review 或者 /commit，后面接具体参数，它就知道该用什么角色、什么步骤去执行。

第三层叫流程，对应脚本和 hooks。它解决的是“自动化衔接”问题：比如生成新模板的脚手架脚本、导出会话记录的脚本、在工具调用前后自动检查的 hooks 配置。这一层可以让模板本身更好维护，也可以让 Claude Code 在某些关键节点自动触发动作。

这三层各司其职，构成一个完整的体系。你如果只写一个超大的 system prompt，塞进一堆任务指令，那反而会让 AI 混乱：既要记项目背景，又要记评审标准，还要记提交规范，上下文里全是互相干扰的信息。分开之后，每个模板的职责单一、内容聚焦，效果会好很多。

1.3 为什么模板比现场发挥更稳

常有人问：AI 对话能力这么强，为什么还要套模板？我实测下来的感受是，模板最大的价值不是“让 AI 变聪明”，而是“让 AI 不变傻”。不带模板直接丢任务，模型的输出方差非常大：状态好的时候能给你很漂亮的方案，状态差的时候连项目用什么包管理器都能猜错。模板相当于把输出的期望值提高了，而且每次都在同一水平线上。

举个例子。我写 /review 这条命令时，模板里明确写了“先读测试文件，再读实现文件，最后提出按严重程度分级的问题”。每次评审的节奏就非常固定，不会这一次先挑语法毛病、下一次又揪着测试覆盖率说事。另一个例子是 /commit：模板里定义了“检查 git diff -> 按 conventional commits 规范分组 -> 生成中文提交信息”的顺序，提交信息的格式始终保持一致，这对我这种维护多个仓库的人来说特别重要。

2. 模板仓库的结构设计与核心文件拆解

2.1 目录结构：一套能直接拷走用的骨架

我自己维护的 claude-code-templates 长得是这样：

claude-code-templates/ ├── CLAUDE.md # 全局项目记忆，放到 ~/.claude/ ├── commands/ # 自定义 slash 命令 │ ├── review.md # /review 代码评审 │ ├── debug.md # /debug 问题排查 │ ├── commit.md # /commit 生成提交信息 │ ├── refactor.md # /refactor 重构 │ └── test.md # /test 测试补全 ├── prompts/ # 提示词模板 │ ├── system.md # 系统角色设定 │ └── task-bugfix.md # 修 bug 专用任务模板 ├── scripts/ │ ├── init-project.sh # 初始化新项目模板 │ ├── export-session.sh # 导出会话记录 │ └── new-command.sh # 新建命令模板的脚手架 └── hooks/ └── checklist.md # hooks 使用说明和示例

这套目录的设计原则只有一条：按照“放哪里”来分，而不是按照“项目 A 用什么、项目 B 用什么”来分。因为 Claude Code 的加载机制是分级的：~/.claude/CLAUDE.md 是全局记忆，所有项目都能读到；项目根目录的 CLAUDE.md 是项目级记忆，只有当前项目能读到；commands 目录同理，放全局就是全局命令，放项目 .claude/commands 就是项目专属命令。所以你要做的就是建立一套模板仓库，再从里面复制/链接到对应位置。

提示：不要把整个模板仓库当作项目里的 CLAUDE.md 硬塞进去。里面的全局内容、项目内容混在一起会让 Claude Code 读到一个上下文里，反而降低指令的聚焦度。我的习惯是：模板仓库负责维护，实际使用时用脚本按需复制。

2.2 CLAUDE.md 模板里该写什么、不该写什么

CLAUDE.md 是整套模板体系里最关键的文件。它在 Claude Code 启动时会被自动加载，相当于系统提示词的一部分。写得好，模型从第一句话起就“知道自己在哪”；写得烂，后面所有指令都会受影响。

我的 CLAUDE.md 模板大概长这样：

# 项目身份 这是一个以 Python 为主的后端服务，负责数据采集与报表生成。 当前仓库是 service 层，不包含前端页面。 # 技术栈与路径 - 包管理：uv + pyproject.toml - 测试：pytest，测试文件放在 tests/ 目录 - 代码规范：ruff + mypy，配置见 pyproject.toml - 入口文件：app/main.py - 数据库迁移：alembic，迁移脚本在 migrations/ # 常用命令 - 本地跑服务：uv run uvicorn app.main:app --reload - 跑全部测试：uv run pytest - 跑单个测试：uv run pytest tests/test_user_service.py::test_create_user - 格式检查：uv run ruff check . # 代码风格约定 - 类型注解必须写完整，不允许省略返回类型。 - 公共函数必须带 docstring，说明参数和返回值。 - 业务逻辑写在 service 层，视图层保持薄。 # 禁止事项 - 不要修改 migrations/ 里已经生成的文件，除非明确要求。 - 不要直接操作数据库，必须通过 repository 接口。 - 测试不允许 mock 数据库连接，统一用集成测试的 fixture。

这里有个关键心得：CLAUDE.md 要写“长期稳定、可被一次性记住”的信息，不要写临时任务。比如“今天要把登录接口的超时时间改短”这种内容就不该出现，因为这是任务描述，不是项目背景。临时任务应该通过命令行参数或 /command 传进去。

还有个容易忽略的点：CLAUDE.md 的优先级。Claude Code 加载上下文时，CLAUDE.md 是作为基础信息存在的，你在对话里后续输入的内容，通常优先级更高。利用这个特性，模板里写“不做什么”比“要做什么”往往更有效。比如我明确写了“不要修改 migrations/ 里已生成的文件”，这比写十条“记住要遵循……”管用得多。

2.3 自定义命令模板：review、debug、commit、refactor 怎么写

自定义命令是 claude-code-templates 里最实用的部分。Claude Code 支持在 .claude/commands/ 目录下放 Markdown 文件，文件名就是命令名，文件内容就是执行逻辑。写个 review 命令大概是这样：

--- description: 执行一次代码评审，覆盖结构、性能、可维护性 argument-hint: [可选] 指定文件或目录，默认全量 --- 请以资深代码评审专家的身份，评审当前分支的代码变更。 执行步骤： 1. 先用 git diff --stat 查看变更概览，确认改动范围。 2. 按文件逐个查看 diff，重点关注逻辑变更，而不是格式化改动。 3. 从以下维度评审： - 边界条件与异常处理是否完整 - 是否有明显性能风险（循环嵌套、重复查询等） - 命名与结构是否符合目录规范说明 - 是否缺少必要的测试覆盖 4. 输出格式： - 按严重程度分三档：严重问题 / 建议改进 / 风格建议 - 每条问题给出文件路径和修改建议，不要只说“有问题” 5. 如果 $ARGUMENTS 指定了具体文件，只评审这些文件。

这里面有几个设计要点。第一，给命令配置了 description，这样在运行 /help 时能清楚看到每个命令是干嘛的。第二，明确分步骤执行，能让模型的思维链更稳定。第三，通过 $ARGUMENTS 接收用户传参，比如 /review src/user_service.py 就比 /review 全量评审更可控。

commit 命令我做得更轻量：

--- description: 根据 git diff 生成符合规范的中文提交信息 --- 执行步骤： 1. 运行 git diff --cached --stat 检查暂存区内容；如果暂存区为空，运行 git diff --stat。 2. 运行 git diff --cached 或 git diff 查看具体改动。 3. 根据改动生成提交信息，格式为 <type>(<scope>): <description>。 4. type 使用 feat / fix / refactor / docs / test / chore。 5. 如果 $ARGUMENTS 有内容，把它作为补充描述拼在正文。

debug 和 refactor 命令的写法思路相同，关键都是“把我要你做的事情拆成模型容易一步步执行的子任务”。我自己的经验是，命令文件里步骤数控制在 4 到 8 步之间最合适，太少则信息不足，太多则模型会跳步。

2.4 提示词模板：system 与 task 拆分是效率关键

很多人的误区是写一个“万能提示词”，把各种任务都塞进去。我的做法恰恰相反：把稳定不变的“角色设定”和每次都在变的“任务内容”彻底拆开。

prompts/system.md 里放的是角色的底座：

你是一个严谨的软件工程师，擅长阅读代码、定位问题、重构优化。 你的习惯： - 先理解再动手，重要改动先说明方案，不要直接改一堆文件。 - 修改代码时保持原有风格，不要为了重构而重构。 - 涉及删除代码时，先确认没有其他引用。 - 输出中文，代码里的注释用英文。 - 不确定的地方直接说“这里我不确定”，不要编造。

prompts/task-bugfix.md 则聚焦任务本身：

任务：修复缺陷 缺陷描述：{$BUG_DESCRIPTION} 执行流程： 1. 先运行相关测试，尝试复现问题。 2. 定位可能的原因，列出两个以上的假设，再选择最可能的。 3. 修改前，先用一句话说明你的修改方案。 4. 修复后，补充回归测试并运行相关测试集。 5. 最后给出变更摘要，以及验证结论。

这样拆分的好处是，我可以把 system.md 的内容直接放进 CLAUDE.md 或全局记忆里，保证任何时候 Claude Code 的“人设”都是统一的。而 task-bugfix.md 只有在接到修 bug 任务时才被加载，不会无时无刻占用上下文窗口。

3. 实操：从零装好一套 claude-code-templates

3.1 五步走完本地搭建

第一步，创建模板仓库。不管你是用 Git 管理还是本地目录，先把结构建出来。我一般用 mkdir 一条龙：

mkdir -p ~/claude-code-templates/{commands,prompts,scripts,hooks} touch ~/claude-code-templates/CLAUDE.md

第二步，写全局 CLAUDE.md。这个是全局记忆，放在 ~/.claude/CLAUDE.md。内容不需要太多，写清楚你的通用习惯、常用工具链、代码风格偏好就行。写太长反而会稀释重点，我控制在 200 行以内，发现哪条规则不适用了就删掉，保持精简。

第三步，添加命令文件。把 review.md、debug.md、commit.md、refactor.md 这些命令文件放到 ~/.claude/commands/ 目录。如果你只是想先体验，放一两个就够了，后面再慢慢补。

第四步，写脚手架脚本。scripts/new-command.sh 的作用是帮你快速生成新的命令模板文件，减少重复劳动：

#!/usr/bin/env bash # 用法：./new-command.sh <命令名> <命令描述> set -euo pipefail name=$1 desc=$2 path="${CLAUDE_COMMANDS_DIR:-$HOME/.claude/commands}/${name}.md" if [[ -f "$path" ]]; then echo "文件已存在：$path" exit 1 fi cat > "$path" <<EOF --- description: $desc --- 执行步骤： 1. 2. 3. EOF echo "已创建：$path"

这个脚本很朴素，但很管用。我每加一个命令，先跑一下脚本把骨架搭出来，然后再填正文，比手动创建文件省心，也避免文件名拼错。

第五步，验证。在终端里进入任意项目，启动 Claude Code，输入 /help，看看自定义命令是否出现在列表里。然后在对话里试一下 /review，看看它是否按模板的流程走。如果命令没出现，多半是路径不对，在后面的排查章节我会细讲。

3.2 四种典型场景的模板组合

同一个工具在不同类型的项目里，模板组合的侧重点完全不同。我列一下实际用过的场景：

以数据库脚本为例，这是我最强调“模板保护”的场景。我写过一个专门的命令模板，一开头就是“你只能执行 SELECT 查询，禁止 UPDATE、DELETE、DDL 操作，所有查询必须带 WHERE 条件，涉及到批量数据要加 LIMIT”。原因很简单，模型在上下文中被反复告知这些规则后，几乎不会跑偏，但如果你不写模板，它就容易自由发挥。

3.3 团队协作：模板仓库当代码仓库来管

只要你是多人团队一起用 Claude Code，就应该把 claude-code-templates 当作正式代码仓库来管理。我的维护方式是这样：模板仓库单独建 Git 仓库，改动走分支评审，合并后写版本记录。

在模板文件里加版本号是个被低估的技巧。我在每个命令文件头部用 yaml 加一行 version: 1.2.0，这样当模型输出异常时，我可以查是不是模板版本太老、和当前 CLI 版本不兼容。同时，每次模板改动都会同步更新说明，团队成员 pull 下来后能立即知道变化。

另一个团队协作注意点：严禁把私密信息写进模板。我见过有人把数据库敏感地址、内部服务域名直接写进 CLAUDE.md，然后整个仓库被到处分享。模板里只放项目结构、代码规范这类信息，凡是涉及密钥、地址的，用变量占位符替代。

注意：模板不是越多越好。我见过有人一口气写了三十多条 slash command，结果模型经常在命令之间混淆。我的建议是控制数量，核心高频命令保持在 5 到 10 条，低频任务用普通对话描述就好。

4. 常见问题与排查技巧实录

4.1 自定义命令不生效或没出现在 /help 列表

这个问题十有八九是路径放错了。Claude Code 加载命令的路径是固定的：全局命令放 ~/.claude/commands/，项目命令放项目根目录的 .claude/commands/。文件名必须是小写英文，不带空格，扩展名必须是 .md。

还有一个隐蔽问题：目录创建时间早于当前会话，但改了文件后命令列表还显示旧的。实测中最快的解决方法是退出当前会话重新进入，或者重启终端。如果命令还是不出现，用命令行直接确认文件路径：

ls -la ~/.claude/commands/ cat ~/.claude/commands/review.md

还有个容易踩的坑：有些编辑器默认保存为 .md.txt 之类的双扩展名，命令列表里就会神秘消失。

4.2 模板太长导致模型跑偏

模板给了模型太多指令，模型反而会“抓不住重点”。我在早期把 CLAUDE.md 写到了五百多行，结果模型写出来的代码风格怪怪的，总是夹杂一些我没要求的格式。后来我意识到，模板内容越靠前，权重越高；内容越长，每条规则的权重就越低。

解决思路是分层：CLAUDE.md 只保留最重要的顶层规则，具体场景规则挪到对应的命令文件里。比如格式检查的细节放在 /test 或 /refactor 里，而不是全堆在全局记忆里。

4.3 $ARGUMENTS 变量解析异常

自定义命令里使用 $ARGUMENTS 时，如果传入的内容包含空格或特殊字符，有时候会被截断。我的经验是用双引号把参数包起来，或者在命令模板里明确写“接收原始参数，不需要做额外转义”。不过这个现象在不同版本里表现可能不一样，如果你遇到类似问题，试一下把参数放到命令尾部并用引号包裹。

4.4 CLAUDE.md 的指令和用户对话冲突

模型有时候会忽略模板里的规则，尤其是当你在对话里给它一个相反的指令时。我实测下来，对话指令的权重通常高于文件模板。如果你发现模型“不听话”了，先检查是不是自己对话里有过覆盖性指令。

真要说优先级：对话指令 > 用户目录全局模板 > 项目模板 > 命令文件规则。想让它严格执行文件里的规则，就不要在对话里反复给相反的指令，那不是锻炼它，是在教它模糊执行。

4.5 调试技巧：让模型把“决策依据”说出来

模板执行出错，最有效的手段是让模型自我解释。当模型表现异常时，我会输入一句“请列出你依据哪些规则做了这个决定，逐条对应”。这句话往往能把问题定位到具体某条模板指令。这个方法简直百试百灵，大多数时候你会发现是某条指令写得太模糊，模型理解歪了。

5. 进阶玩法：把模板变成自己的“第二大脑”

5.1 从模板到工作流：一条完整 TDD 任务链

模板练熟了以后，我意识到真正的价值不在于单条命令，而在于把命令串联成一条工作流。比如我处理一个 bug 时，会按这个顺序调用：先用 /debug 定位问题，再用 /test 补失败用例，然后自己改代码，最后用 /review 兜底。这是人在流程中的角色，模板只是工具箱里的固定夹具。

用 bash 写一个 tdd-flow 脚本，把这几步串起来：

#!/usr/bin/env bash # 用法：./tdd-flow.sh "修复用户创建接口的错误码" set -euo pipefail claude -p "用户输入：$1。请先按 /debug 定位问题，再按 /test 写出失败用例并运行，输出候选修复方案。"

这样你只需要输入一个描述，Claude Code 就能按模板链执行。注意脚本里的 claude -p 是“一次性执行模式”，适合自动化场景，不用开交互式会话。

5.2 hooks 模板初探：在工具调用前后插入检查

Claude Code 的 hooks 机制可以让你在它调用某些工具之前或之后执行自己的脚本。我的 hooks/checklist.md 里就设计了这么个用法：在模型运行任何文件写入操作前，先跑一遍必须检查清单。

hooks 配置格式大致如下：

hooks: PreToolUse: - matcher: "Write|Edit" hooks: - type: command command: "python scripts/check-before-write.py"

这个机制的作用不是限制模型，而是给团队规范加一道硬性闸门。比如我写过一个小脚本，作用是在模型试图修改 migrations/ 下文件时弹警告，确实拦截过几次误操作。不过 hook 脚本的编写调试成本比较高，建议先把基础命令模板用熟练，再考虑上这一层。

5.3 模板的版本管理心得

给模板做版本管理这件事，一开始我觉得是过度设计，但实际用下来很值。我自己的做法是：模板仓库里加一个 changelog 文件，每次改命令都记录“改了什么、为什么、影响面”。原因很简单：当你同时维护几个项目、几个分支时，模板改了但没测试过的情况很常见。记录变更帮你快速回滚到上一个可用版本。

另外一个心得是，模板文件里加入“最后修改日期”和“适用范围”，变量迁移到新项目时一目了然。我甚至给核心命令写了一些“使用后反馈示例”，比如 /review 输出应该长什么样，这样模型输出格式跑偏时能马上参照。

5.4 可扩展方向：团队规范沉淀

最后说个方向。claude-code-templates 早期是个人效率工具，但它很容易长成团队级的“可执行规范”。代码评审标准、提交信息规范、测试补充策略，这些原本写在于文档里的条目，一旦转成 Claude Code 命令模板，就变成了“模型每次都会主动执行”的规则，而不是靠人自觉查阅。

我实际感受是，把规范变成模板之后，新同事上手项目的速度明显变快了：他不需要先读一堆规范文档再去问老同事，直接在终端里敲 /review，就能获得和团队标准一致的代码反馈。这才是模板体系最有价值的地方——它把隐性经验显性化、工具化，让普通成员也能获得资深成员的工作习惯。

我自己的习惯是，每隔一段时间就把日常对话里那些重复出现的高质量指令沉淀进模板。早上清理临时目录、写周报、整理代办的这些琐碎动作，我都给 Claude Code 做了专用模板。用得越久，模板库越贴合你自己的节奏。如果你还没有这套体系，从今天开始搭起来，先只写一个 CLAUDE.md 加 /review 命令，用起来再慢慢扩展，很快你就会发现回不去裸奔的用法了。