企业官网建设流程全解析

如果你是一个每天要在终端里敲命令的开发者，你大概率已经听说过 Claude Code。但你可能没有想过，真正让 Claude Code 从“玩具”变成“生产力工具”的，不是模型本身，而是你丢给它的那套模板。claude-code-templates这个项目，说白了就是一套把 Claude Code 从“问一句答一句”的 chat 工具，变成一个“懂你项目、按套路干活”的团队成员的完整方案。这篇文章不是介绍原理，而是我搭建、迭代、在真实项目里使用这套模板一个多月之后的完整复盘，包括目录结构怎么设计、每个模板该写什么、哪些坑你必须绕着走。

1. 模板库的定位与设计思路

1.1 为什么需要模板

很多人第一次用 Claude Code 的感觉是“很强，但很不稳定”。同一个需求，上午问它，它给出一套实现方案，下午换个措辞再问，它给出另一套，有时候第二套还不如第一套。这不是模型变笨了，而是你给它输入的上下文约束不够。Claude Code 默认情况下就像一个极了聪明的新员工，能力很强，但不知道你的编码规范、不熟悉你的项目结构、不清楚你期望的输出格式。每次对话都在“试探”，结果自然飘忽不定。

模板的作用，就是把这些“应该默认知道”的东西固定下来。它解决三个具体问题：第一，减少重复描述，你不用每次都说“请阅读 src/service 下的代码，按照 PEP8 规范，输出带有注释的 diff”；第二，锁定输出质量，模板里规定了目标格式、边界条件和验收标准，模型的表现方差会明显缩小；第三，让新手能快速上手，一个团队里有人经验丰富，有人刚接触 AI 编程，模板能把高级用法沉淀下来，让所有人都能踩在同一个水平线上出发。

我见过很多开发者说“我用 Chat 写代码就够了”，这种人大概率没有经历过一个 10 万行代码仓库里，让 Claude 自己找修改点找到崩溃的场景。模板不是束缚，是锚点。

1.2 设计模板的三条核心原则

我在反复试错之后，把模板设计原则收敛为三条：确定性、渐进式、可插拔。

确定性是第一步。模板里必须写清楚“你要什么”“边界是什么”“输出长什么样”。比如代码审查模板，我会明确要求“只报问题，不夸优点”“每个问题标注风险等级”“按文件维度组织”。如果不写这些，Claude 会把精力浪费在无关紧要的注释风格上，甚至给你来一段“整体结构清晰”的空话。

渐进式是因为 Claude Code 的上下文窗口再大，也有上限。一次性把项目规范、历史决策、本次需求全部塞进去，不仅浪费 token，还会让模型“注意力稀释”。我的做法是把模板分成两层：CLAUDE.md 里放全局信息，比如项目结构、代码风格、常用命令；具体任务模板里放局部信息，比如本次要实现的接口约束、需要参考的既有代码位置。先加载全局，再按需加载局部。

可插拔意味着每个模板尽量单一职责。一个模板只解决一类问题：写测试的、重构的、修 bug 的、生成 commit message 的。避免搞一个大而全的“万能模板”，因为任务切换时它会产生巨大噪音，还可能把上一类任务的指令带进来，造成幻觉。单一职责模板配合按需加载，是我用下来最稳的模式。

1.3 目录结构与命名规范

模板库的物理结构要直观，不然你自己过两周都会忘。我的claude-code-templates目录长这样：

claude-code-templates/ ├── prompts/ │ ├── code-review.md │ ├── test-generation.md │ ├── refactor.md │ ├── bugfix.md │ └── commit-message.md ├── workflows/ │ ├── feature-dev.md │ ├── hotfix.md │ └── api-design.md ├── scripts/ │ ├── init-repo.sh │ ├── apply-template.sh │ └── backup-templates.sh ├── examples/ │ └── basic-rest-api/ └── CLAUDE.md

命名规范我用的是“动词-目标”格式，比如code-review.md、test-generation.md。好处是目录列表一拉出来，你就知道这个模板是干嘛的。prompts是通用提示词，workflows是带步骤顺序的复杂流程，scripts是配套的 shell 脚本，examples是模板的验证样例。CLAUDE.md 是入口文件，Claude Code 启动时读取它加载整套模板路径。

这个结构不是拍脑袋定的。我一开始把所有模板塞在一个templates.md里，结果很快变成 600 行“屎山”，Claude 在里面翻来翻去，效率极低。拆成独立文件之后，我可以直接用/prompts/code-review.md这种方式按需引用，也方便用 git 做版本管理。

2. 核心模板类型拆解

2.1 提示词模板：让 Claude 进入状态

提示词模板是整个体系的地基。它的目标不是给 Claude 一条指令，而是给它“角色”、“背景”、“行为准则”和“输出协议”。

拿code-review.md举例，我是这样写的：

# Role 你是一名资深代码审查者，擅长发现潜在缺陷、性能瓶颈和安全漏洞。 # Context 当前项目使用 Python 3.11 + FastAPI。请审查以下文件或代码块。 # Behavior 1. 只报告真实问题，不进行无关建议。 2. 每个问题标注严重级别：Critical / Warning / Suggestion。 3. 优先检查：错误处理、资源泄漏、并发安全、默认参数陷阱。 4. 忽略纯格式问题，除非违反项目 pep8 配置。 # Output 按文件维度组织，输出 markdown 表格： | 文件 | 行号 | 级别 | 问题描述 | 修改建议 | 最后给出最多 3 条整体改进建议。

这里的关键是“Output”部分。如果你不锁定输出格式，Claude 会用各种风格给你输出，有的给一段长文，有的给一堆代码块，很难直接集成到 review 流程里。锁成表格后，我可以直接把这个输出贴到 GitLab MR 评论区，或者用脚本解析成结构化数据。

很多人觉得“Claude 这么聪明，不需要这么死板”，但我的实测结果是：越是自由发挥，越容易跑偏。尤其在代码审查这种场景下，Claude 很容易被“夸奖冲动”带跑，用模板把它按在问题清单上，输出质量提升非常明显。

2.2 CLAUDE.md 项目记忆模板

CLAUDE.md 是 Claude Code 的“项目记忆文件”，在项目根目录下，每次对话都会自动加载。这个文件不能贪多，它是全局上下文，装的是“这个项目是谁、用什么技术栈、有哪些约定”。

我维护的 CLAUDE.md 一般包含五个板块：

# 项目概览 - 技术栈：FastAPI + SQLAlchemy + PostgreSQL - 目录结构：app/api 放路由，app/models 放 ORM 模型，app/services 放业务逻辑 # 常用命令 - 启动开发服务：uvicorn app.main:app --reload - 跑测试：pytest tests/ -q - 生成迁移：alembic revision --autogenerate # 编码规范 - 使用 type hints，禁止使用 Any（极少数情况除外） - 所有业务异常必须定义在 app/errors.py 并统一处理 - API 响应统一包裹 { code, message, data } # 项目约定 - 数据库 session 使用 FastAPI 依赖注入，禁止全局 session - 所有外部调用必须设置超时，默认 5 秒 - 新增接口必须附带 OpenAPI 文档描述 # 角色定位 你是本项目的资深后端工程师，负责完成所有代码任务。 所有修改必须保持向后兼容，除非用户明确要求破坏性变更。

你看，CLAUDE.md 里没有一个字是“夸夸其谈”，全部是可执行、可校验的信息。写这个文件要克制，只写那些“换了个人/模型就需要问一遍”的信息。项目历史决策、架构权衡这种隐形知识，比代码本身更值钱，放进去之后 Claude 的表现会有一个质的飞跃。

2.3 工作流模板：从需求到实现

提示词模板解决“单次任务”，工作流模板解决“多步过程”。最典型的是feature-dev.md。它把一次功能开发拆成 Step 1 到 Step 6，并要求 Claude 每一步做完都要暂停确认。

# Workflow: Feature Development 你是本项目的资深工程师，请严格按照以下步骤完成新功能开发。 Step 1: 信息收集 - 阅读需求描述，列出疑问点 - 检查是否已有相关代码或接口，输出影响范围 Step 2: 方案设计 - 给出实现方案，包括数据模型、接口定义、组件划分 - 评估方案的兼容性和风险，最多给出 2 个备选方案 Step 3: 用户确认 - 用以下格式展示方案，等待用户输入 CONFIRM 后再继续 - 方案摘要 / 影响范围 / 潜在风险 / 预计改动文件 Step 4: 代码实现 - 按项目规范实现代码，必须包含单元测试 - 每完成一个文件，输出文件路径和改动摘要 Step 5: 自检 - 运行相关测试，修复失败项 - 按 CLAUDE.md 编码规范自查 Step 6: 提交说明 - 生成符合规范的 commit message，说明改动意图

关键在 Step 3，这里强制加入了人的决策环。AI 编程最可怕的问题不是写不出代码，而是“写错了方向还一直写下去”。有了确认环，Claude 会在动手前把方案摊开给你看，你发现方向不对，提前止损。这个模板让我的功能开发成功率从 60% 左右提到了 85% 以上。

2.4 脚本模板：自动化辅助

脚本模板是容易被忽视的部分。Claude Code 本身能执行 bash 命令，但每次写同样的 shell 片段很烦。比如init-repo.sh，它会根据模板库初始化一个新的项目目录、创建 CLAUDE.md、拉取基础 .gitignore、安装依赖：

#!/usr/bin/env bash # 初始化一个新的 Claude Code 项目 set -euo pipefail PROJECT_NAME="$1" TEMPLATE_DIR="$2" # path to claude-code-templates mkdir -p "$PROJECT_NAME"/{src,tests,docs} cp "$TEMPLATE_DIR/CLAUDE.md" "$PROJECT_NAME/CLAUDE.md" cp "$TEMPLATE_DIR/prompts/"*.md "$PROJECT_NAME/.claude/prompts/" cat <<EOF >> "$PROJECT_NAME/.gitignore" __pycache__/ *.pyc .env dist/ build/ EOF cd "$PROJECT_NAME" git init -q echo "Project $PROJECT_NAME initialized with Claude Code templates."

还有一个apply-template.sh，负责从模板库里复制指定模板到当前项目.claude/目录，这样就不用手动 cp。这些脚本把模板库从“纸面规范”变成了“可执行工具”，我每周能用它省下半小时的重复劳动。

3. 从零搭建模板库的完整实操

3.1 初始化目录与版本管理

搭建模板库的第一步跟搭普通代码库没区别：建目录、git init、建分支策略。我强烈建议用 git 管理模板，因为模板会随项目经验持续演进，你需要知道哪些调整带来了效果，哪些是瞎折腾。我的提交习惯是“一次改动对应一个具体失败案例”，比如 commit message 写fix: review template fails on config files without line numbers，这样回溯才知道当时为什么改。

初始化命令：

mkdir claude-code-templates cd claude-code-templates git init -b main mkdir -p prompts workflows scripts examples touch CLAUDE.md README.md git add . git commit -m "init template structure"

别忘了 README.md。README 要说明模板的安装方式、每个模板的适用场景、如何提交新的模板。它既是文档，也是团队协作的“入口指引”。

3.2 编写第一个提示词模板

从最简单的commit-message.md开始，训练写模板的感觉。最开始不要追求复杂，找一个你每天重复最多的任务，把它规范化。

我的commit-message.md长这样：

# Role 你是项目代码变更记录专家。根据 git diff，生成 commit message。 # Input （此处由用户粘贴或工具提供 git diff） # Rules 1. 使用 Conventional Commits 规范（feat/fix/docs/refactor/test/chore） 2. 主题行不超过 50 个字符 3. 正文按“原因-改动-影响”结构描述 4. 如果同时涉及多个改动，用空行分隔分条目描述 删除任何现存的 comment，直接输出结果字符串。

写完后，进入 Claude Code 交互界面，输入/commit引用该模板，然后让模型读当前 git 暂存区的 diff。它会严格按规则输出一条信息。如果你不满意，最多调两轮模板描述，而不是去反复跟模型“讲道理”。

3.3 配置 CLAUDE.md 实现全局生效

要让模板库真正被 Claude Code 自动加载，有几步配置。

第一步，项目的 CLAUDE.md 里放一段“模板索引”：

# Template Index - 代码审查：.claude/prompts/code-review.md - 测试生成：.claude/prompts/test-generation.md - 功能开发：.claude/workflows/feature-dev.md - 提交说明：.claude/prompts/commit-message.md 使用方式：输入 /模板名 或 /prompts/文件名 调用。

第二步，把模板文件软链接到项目.claude目录。我是用脚本批量处理的：

ln -sfn "$TEMPLATE_DIR/prompts" .claude/prompts ln -sfn "$TEMPLATE_DIR/workflows" .claude/workflows

这样模板更新后不需要每个项目重复拷贝，而且可以用 git submodule 或 subtree 复用。如果团队使用，推荐 submodule 方式跟进模板库版本。

第三步，验证加载。在项目目录启动 Claude Code 后，直接问“你的项目模板索引里有哪些内容”，如果它答得上，说明刚才的配置生效了。有时候它会因为上下文太长而忽略 CLAUDE.md 后半部分，这种情况我们放到第 4 节排查。

3.4 用模板驱动一次真实开发任务

理论讲太多没意义，我实际走一遍。假设现在要给一个 FastAPI 项目新增“导出用户列表为 CSV”的功能。

启动 Claude Code，输入：

根据 feature-dev.md 工作流，我要新增一个导出用户列表 CSV 的接口。需求：支持指定字段，默认全部字段；用户量大时避免内存溢出；接口权限为管理员。

Claude 读取 feature-dev.md 后开始走流程。第一步它会列出影响范围：app/api/users.py新增路由、app/services/users.py新增导出函数、tests/api/test_export.py新增测试。第二步给出方案，我注意到它建议用StreamingResponse流式返回，这对大用户量是正确选择。第三步它把方案摘要发给我，我确认 CONFIRM。

接着它开始实现。中间我发现它生成的 SQLAlchemy 查询没有使用yield_per，可能导致大数据集加载慢。我在对话中直接打断：“Step 4 需要优化查询，使用 yield_per 分批加载”。它很快修正并补充了测试。自检阶段它运行了 pytest，通过了新增和原有测试。整个功能 15 分钟完成，比我手写快很多，而且因为有工作流模板，每一步都可追踪、可回滚。

这个例子的意义在于：模板不是让 Claude 变得“自动化”，而是让它的输出更加可预期。我知道它会在哪个节点停下来问我，我知道它会在写完代码前先测一遍。这种“可预期”是团队合作的基础。

4. 实战中的问题与排查

4.1 模板失效：上下文被冲掉怎么办

最常见的问题是“用了模板，但后续对话又变回自由发挥”。原因是 Claude Code 的上下文是滚动的，长对话中早期指令会被新的内容冲淡。我踩过的坑和对应的解法有三个。

第一，模板命令要在关键节点重复触发。比如 code-review 模板，不要在对话开头用一次就指望后面全程生效；每 review 一个新文件，就再调用一次/code-review刷新指令。第二，把最关键的行为约束写进 CLAUDE.md，因为它是每次请求前缀里稳定存在的内容，比对话中的模板更持久。第三，对于非常关键且不能忘的规则，比如“禁止修改接口签名”，可以在模板里写“这是最高优先级约束，每一步执行前必须检查是否违反”，并在Output里附上单独的“合规自检”列表。

4.2 上下文膨胀：如何控制 token 消耗

模板多了之后，CLAUDE.md 容易变成一本长篇小说。我见过有人把整个团队 wiki 塞进去，结果每次请求还没开始干活，光 token 就烧掉一大截。控制上下文膨胀有几个原则。

CLAUDE.md 只能放“全局常量”，比如项目结构、编码规范、常用命令，控制在 80 行以内。具体场景知识放进独立模板，用时才加载。工作流模板里不要放示例代码，示例代码放到examples/目录，需要时让 Claude 去读文件而不是粘贴内容。还有一个办法是利用 Claude Code 的“文件引用”能力，CLAUDE.md 里只写详见 .claude/prompts/refactor.md，把上下文负载延后。

我实际测过，把 CLAUDE.md 从 200 行压缩到 60 行之后，同一个任务的 token 消耗降低了约 30%，而且回答稳定性反而提升了，因为核心约束更醒目。

4.3 模板与真实项目冲突：如何处理

模板是通用的，但项目是具体的。最典型的冲突是编码规范不一样：模板要求 type hints，但老项目是 Python 2 风格，Claude 会坚持模板要求导致重构越做越大。

我的处理办法是在 CLAUDE.md 里写明“本项目与通用模板冲突的例外列表”。比如：

# Overrides - 通用模板要求的所有接口必须 type hints，但本项目的旧模块 legacy/ 除外 - 代码审查模板要求报告安全漏洞，但本项目的第三方依赖更新需单独提工单，不要在 review 中直接给出修改

这个 Overrides 段落要放在 CLAUDE.md 靠前位置，确保模型优先读到。模板库的定位永远是“建议基线”，允许项目用显式配置覆盖通用约定。

4.4 常见问题速查表

我把平时被问到最多的几个问题整理成表格，方便直接查。

排查时还有一个独门技巧：让 Claude 自己解释“你当前的工作文档是什么”。如果它复述的内容和你的 CLAUDE.md 不一致，说明上下文加载出了问题，大概率是文件路径错误或者软链接断了。这个调试方式比翻日志高效得多，因为模型能告诉你它“看到”了什么。

在实际使用中我还发现，模板需要像代码一样持续重构。每两周我会检查一次所有模板，把那些“用了没效果”或“反而拖慢节奏”的模板删掉，把“新踩的坑”补充进对应模板。模板库是活的项目，不是一次写完就封存的一次性交付物。

最后分享一个我个人的习惯：每次给 Claude 分配任务前，先花 30 秒想清楚“这个任务归属哪类模板，要不要用”。如果我犹豫，就不用。一个不合适的模板带来的上下文噪音，远比你手动多写几句描述的成本高。把模板当成一种“投资”，只在真正高频、重型的任务上使用，才能收获最明显的回报。