企业官网建设流程全解析

1. 先搞明白：claude-code-templates 到底是什么

最开始看到 claude-code-templates 这个名字，很多人第一反应是“给 Claude Code 用的代码模板”。这个理解只说对了一半。它真正指的是面向 Claude Code 这一终端编码工具的一套可复用配置模板，包括 CLAUDE.md 规则文件、技能（skills）的目录结构、常用提示词片段、角色定义和工作流约定。你可以把它理解成给 Claude Code 准备的“入职手册”和“操作 SOP”。

Claude Code 本身是 Anthropic 推出的 CLI 编码工具，你可以在终端里通过自然语言让它读代码、改代码、跑测试、提 PR。它厉害的地方是能感知你当前的项目结构，但默认情况下它就像一个“聪明但对你项目一无所知的新人”——它不知道你们的代码规范、不知道哪些目录不能动、不知道测试命令是什么、不知道你希望它用什么语气提交代码。而 claude-code-templates 这类模板库，就是把这些“项目常识”固化下来，让工具一进入项目就能很快进入状态。

适合谁看？如果你刚接触 Claude Code，一两周了还在反复解释项目背景，或者你已经用了几个月但每次新项目都要复制一份旧的配置文件，又或者你带团队、想让所有人都按同一套标准使用这个工具——这文章就是给你写的。下面所有内容，都是我自己在真实项目里试出来的经验，没有花架子。

2. 核心设计思路：模板到底在解决什么问题

2.1 先理解 Claude Code 的记忆机制

想写好模板，得先搞清楚 Claude Code 是怎么“记住”上下文的。它的记忆主要来自几个层面：系统提示词（system prompt）内置的通用能力、你在终端里输入的自然语言指令、以及它能自动读取的规则文件。规则文件里最核心的就是 CLAUDE.md，Claude Code 会在对话开始、文件变动、每个关键节点自动加载它。

很多人忽略一个细节：Claude Code 每次加载 CLAUDE.md 都要消耗上下文窗口。你不是写得越多越好，而是写得越“精准”越好。一份 500 行的 CLAUDE.md 和一份 200 行的 CLAUDE.md，看着前者信息多，但因为上下文被无关内容挤占，真正干活时它反而更容易“丢三落四”。

模板库存在的意义，就是帮你把“每次都要重复写在命令行里的话”变成“它自己翻开就能看到的东西”。我做 claude-code-templates 这类项目时，第一原则就是：所有规则必须能回答“为什么”，而不是单纯“是什么”。比如“不要修改 node_modules”和“node_modules 是第三方依赖目录，改动会导致安装锁文件失效，不用管它”，后者明显更容易让模型在复杂情况下做出正确判断。

2.2 模板的分层结构：全局、项目、技能

一个健壮的 claude-code-templates 库，通常包含三层：

我强烈建议：全局层只放通用习惯，项目层聚焦仓库细节，技能层解决“特定场景的高质量输出”。不要把项目特有的技术栈写进全局模板，否则换一个项目它就开始张冠李戴。我见过有人把 Vue 的规范写进全局层，结果用 React 的项目里它反复建议用 Vue 语法。

技能层是 Claude Code 后来引入的能力，相当于给工具预置了一套“专业技能包”。每个技能是一个目录，里面放一个 SKILL.md，描述这个技能何时触发、执行步骤是什么、有哪些注意事项。技能只有在用户提问或行为匹配到它的描述时才会被加载，所以它不占每轮对话的上下文，非常划算。

2.3 模板库的两个核心收益：一致性和可复制性

团队里多人用同一个工具，最怕的是同一个问题问出十个不同的答案。有人让它“修一下”，有人让它“把报错处理了”，结果它给出的改动风格完全不同。模板库能把这种差异降到很低：大家都读同一份 CLAUDE.md、用同一组技能，输出的代码风格、提交信息格式、注释习惯都会趋同。

可复制性也很关键。终端的 AI 编码工具已经成了我很多项目的基础设施，那基础设施的配置就不能“只可意会不可言传”。把配置沉淀成模板仓库，新项目 clone 下来跑一条安装脚本，五分钟内就拥有一套成熟配置。新同事入职，教他跑一次安装脚本，剩下的他自己探索都能少踩很多坑。

3. 实操搭建：从零构建你的 claude-code-templates 仓库

3.1 仓库目录结构规划

我通常按下面这个结构组织模板库：

claude-code-templates/ ├── global/ │ ├── CLAUDE.md # 全局规则 │ └── .claude/settings.json # 全局行为设置 ├── project/ │ ├── CLAUDE.md # 项目级规则示例 │ └── .claude/ │ └── skills/ # 技能目录示例 ├── skills/ │ ├── code-review/ # 代码审查技能 │ │ └── SKILL.md │ ├── performance-check/ # 性能检查技能 │ │ └── SKILL.md │ └── refactor-safe/ # 安全重构技能 │ └── SKILL.md ├── prompts/ │ ├── git-commit.md # 提交信息规范 │ ├── issue-report.md # 问题报告模板 │ └── onbording.md # 新项目引导 ├── scripts/ │ ├── install.sh # 一键安装脚本 │ └── update.sh # 更新模板脚本 └── README.md

这个结构的好处是能区分“通用层”和“示例层”。global/是实际会被装到本机的文件，project/是给具体项目用的样板，skills/是技能库，prompts/是可能需要手动粘贴的常用指令片段。

3.2 编写 CLAUDE.md：把“常识”翻译成规则

写 CLAUDE.md 最忌讳的是把它写成一份“企业规章制度”。Claude Code 能理解的不是抽象的条文，而是具体的指令。我举一个我真实项目里的例子：

# Demo API 项目规则 ## 项目简介 这是一个基于 FastAPI 的订单服务，主要提供订单创建、查询、取消接口。 数据库使用 PostgreSQL，ORM 是 SQLAlchemy 2.0，缓存用的是 Redis。 代码仓库根目录是 /demo-api，所有命令都在此目录下运行。 ## 常用命令 - 启动开发服务器：python -m uvicorn app.main:app --reload - 运行全部测试：pytest tests/ -v - 运行单个测试文件：pytest tests/test_orders.py -v - 代码格式化：ruff check . --fix ## 目录职责 - app/main.py —— 应用入口与路由注册 - app/models/ —— 数据库模型，禁止在 service 层直接写 SQL - app/services/ —— 业务逻辑，一个 service 只负责一个业务域 - app/routers/ —— API 路由层，只做参数校验与响应封装 - tests/ —— 单元测试与集成测试 ## 编码规范 - 新增接口必须附带 OpenAPI 文档注释 - 所有时间字段统一用 UTC 存储，序列化时转东八区 - 数据库变更必须新增 migration，禁止直接改表结构 - 日志用 app.utils.logger 模块打出结构化日志，不要用 print - 不要修改 node_modules 或 vendor 目录下的任何文件 ## 常见任务工作流 ### 新增一个订单查询接口 1. 在 app/schemas 中定义 Pydantic 请求/响应模型 2. 在 app/services 中实现业务查询逻辑 3. 在 app/routers 中注册新路由 4. 在 tests 中补充至少两个用例：正常返回和参数非法 5. 运行 pytest tests/ 确保全部通过 ### 修复一个 Bug 1. 先运行 pytest 复现问题 2. 判断是模型层还是服务层的问题 3. 修改代码后，必须追加一个能覆盖该 Bug 的回归测试 4. 运行相关测试范围，不要求跑全量，但要保证无新失败

我写这份文件时反复调整了好几次，最后得到的经验是：用编号步骤描述工作流，比写一大段“请遵循良好的开发实践”有用得多。模型很擅长按编号步骤执行，但很难把一个抽象原则落地成具体操作。

还有一个小技巧：CLAUDE.md 里用“禁止”这个词要谨慎。如果只是一些偏好，用“优先”或“建议”。一旦写了“禁止”，模型就会把这当成硬性红线，宁可多问也不动手。这有时反而降低效率。

3.3 定义技能（Skills）：让模板具备按需触发的专业能力

技能是模板库里最值得花时间打磨的部分。一个规范的技能目录长这样：

refactor-safe/ ├── SKILL.md └── examples/ └── after-refactor-example.ts

SKILL.md 的 frontmatter 里必须有name和description。description 是这只技能能否被正确触发的关键。Claude Code 会根据用户当前的提问，与 skill 描述做语义匹配，所以描述里尽量包含触发场景、任务动词、语言或框架信息。

下面是我写的“安全重构”技能的 SKILL.md 核心内容：

--- name: refactor-safe description: 当用户要求重构代码、提取函数、拆分模块、重命名变量时使用。适合 JS/TS/Python 项目。不要用于新增功能或修复 Bug。 --- # 安全重构 ## 执行目标 在不改变代码行为的前提下，调整代码结构以提升可读性、可维护性。 ## 前置检查（必须依次完成） 1. 检查项目是否已有测试，运行一次 `npm test` 或 `pytest` 记录基线通过数 2. 如果没有测试，先向用户说明风险，等用户确认后再继续 3. 确认重构范围：只处理用户提到的模块，不顺手改无关文件 ## 重构步骤 1. 建立“重构前后对照清单”：列出涉及的文件和函数 2. 小步提交：每完成一个函数的提取/重命名，立即跑一次相关测试 3. 重构完成后再跑一次全量测试，对比基线 4. 检查 git diff，确认没有非预期的格式变更 ## 禁止事项 - 同一批次里既重构又改业务逻辑 - 重构时顺手“美化”整份文件 - 在重构过程中引入新依赖 ## 验收标准 - 前后测试结果一致或更好 - 核心函数调用关系变化不超过用户指定的范围 - 生成的提交信息里写明重构内容和测试结论

写技能时最容易犯的错是“把技能写成大纲”。加上了前置检查、禁止事项、验收标准，才是真正能指导一个 agent 完成任务的技能。我把技能文件当“带教训的教程”来写，因为 SKILL.md 的作用就是在工具犯错时给它一个清晰的边界。

3.4 提示词片段库：留给手动场景的“弹药”

不是所有场景都能靠自动匹配触发技能。有时候用户就是在终端里随口问了一句：“这个函数怎么这么慢？”我习惯准备一批 prompt 片段，按需复制黏贴。比如性能分析提示词：

请作为资深性能工程师对以下代码段做耗时分析： 1. 先用 cProfile 或 py-spy 采集现行数据，没有环境就基于静态分析评估 2. 列出耗时最高的 3 个函数，说明为什么慢 3. 给出两个优化方案：一个是不改动架构的快速优化，一个是架构层优化 4. 每种方案都要说明改动范围、预期收益、风险点 5. 在你动手前，先把你打算改的代码路径图用文字描述给我确认

这种片段有几个共同点：有专业角色设定、有明确的步骤要求、有“先确认再动手”的护栏。我把它们放在prompts/目录，都按场景命名，需要时直接复制进终端。

4. 实操要点：让模板真正好用的几个关键参数

4.1 description 写得越具体，触发越精准

Claude Code 的 skills 功能是基于语义匹配触发的。如果你把 code-review 技能的 description 写成“代码审查”，它几乎什么都不会匹配到，或者说换个方式到处乱触发。我踩过这个坑，后来把 description 改成：

当用户要求检查代码质量、发现潜在 Bug、评估代码规范合规性时使用。 适用于提交 PR 前的自检、重构前后的质量验证。 不用于日常功能开发。

改完之后，触发准确率高了很多。这里的关键是：要把技能触发的正向场景和负向排除都写清楚。就像你给同事派活，不能只说“看一下代码”，得说清楚什么时候该看、什么时候不用看。

4.2 模板里的“上下文预算”意识

每次对话都会把 CLAUDE.md 全文载入上下文，因此你写的每行字都在消耗它的“注意力”。我给自己定了一个规则：CLAUDE.md 控制在 100-200 行以内。如果内容多到超出这个范围，就会把“技能”和“提示词片段”承接一部分。

有一个真实示例：我的一个 Spring Boot 项目里，CLAUDE.md 曾经写了 320 行，覆盖了从 Maven 构建到 SonarQube 检查的所有细节。结果这个工具经常在无关问题上“过度表现”——比如我只是问一个接口参数，它把整个模块的配置都重述了一遍。精简到 150 行之后，这种情况明显减少了。

4.3 把“禁止做的事”写进模板，比事后纠正便宜得多

Claude Code 允许在过程中多次纠错，但纠错也有代价：每次纠正都要消耗来回轮次，而且它改完一个错误可能引入另一个。与其事后不断纠正，不如在模板里预先声明边界。

我的模板库有一个通用规则区，专门记录这类边界：

## 绝对不要做的事 - 不要在没有运行测试前声称“改动不会破坏现有功能” - 不要删除代码时只删了定义没删引用，改动前先 grep 一遍引用 - 不要一次性生成超过 600 行的新文件，超过要分步追加 - 不要把执行命令的输出贴回对话里当作结果，要基于文件事实判断

这些规则看着像“废话”，但对模型来说特别有效。因为它的预训练经验里，很多是“小步快跑式”的辅助操作，如果你不明确给它设限，它就容易搞出“删了定义忘了引用”这类事故。

4.4 用 settings.json 控制行为模式

除了 CLAUDE.md，Claude Code 还有各级.claude/settings.json配置文件。我常用它来做三件事：设置权限模式（比如禁止自动执行可能造成破坏的命令）、忽略某些目录、配置自定义命令别名。

{ "permissions": { "bash": { "allow": ["npm test", "pytest", "git status", "git diff", "ls"], "deny": ["rm -rf", "git push --force", "psql"] } }, "ignore_patterns": ["node_modules", ".venv", "dist", ".next"], "aliases": { "test": "pytest tests/ -v --tb=short", "lint": "ruff check ." } }

有个容易忽略的点：ignore_patterns写在 settings 里能有效减少工具的无效探索。比如项目里有个巨大的dist/目录，如果不加忽略，它可能在整理文件时把这个目录也扫进去，白白浪费整整几千个 token 的上下文。

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

我自己用下来，模板相关的问题主要集中在几个场景。下面直接给问题和对应解法。

5.1 模板看起来没被加载

现象：你改了 CLAUDE.md，但 Claude Code 似乎还在用旧规则。排查思路：

1. 看文件名大小写，必须严格叫CLAUDE.md，写成claude.md或Claude.md都不行
2. 看是否放错了目录。项目级 CLAUDE.md 要放在仓库根目录，不是src/也不是.claude/
3. 看有没有缓存。新版本 Claude Code 有会话缓存，如果长期开着同一个会话，可能需要/clear或重启新会话才能重新加载最新模板
4. 检查是不是同时存在全局和项目模板，项目模板的内容优先级高于全局，但不是合并，有些关键指令可能被覆盖

我遇到过最隐蔽的问题是：团队里某位同事在全局模板里写了一条“所有代码评审都是浪费时间”之类的规则，结果项目模板里的代码评审技能完全失效。全局和项目模板之间是“覆盖”关系，不是你想象的“拼接和补充”，所以排查模板问题时要两级文件一起看。

5.2 技能匹配不到，或老是被错误触发

如果技能文件存在但从不被触发，先检查技能目录命名是否正确。技能必须放在.claude/skills/<技能名>/SKILL.md这个路径下，而且技能名目录不能有空格。如果技能老是乱触发，多半是 description 写得过于宽泛。按我前面说的方法，把负面场景和正面场景同时写清楚，能解决绝大部分问题。

还有一个容易踩的坑：技能目录里的辅助文件（比如 example 文件、参考报告）确实会被一起打包进技能上下文，但体积不能太大。我试过在技能目录里放了一份 3MB 的参考 PDF，结果每次触发这个技能，对话延迟明显变高。技能库里尽量只放文本和少量代码示例。

5.3 模板内容太长拖慢响应

这个已经在前面说过了，但我再提供一组实操数字。我测试过不同体积的 CLAUDE.md 对首字响应速度的影响：150 行以内基本无感，300 行左右会有一点延迟但还能接受，500 行以上不仅响应慢，模型理解长文档的能力也会衰减。所以如果必要信息太多，就把一部分挪到技能里，而不是硬塞在 CLAUDE.md。

5.4 团队协作：模板更新后别人不生效

多人共用一套 claude-code-templates，最怕“我更新了模板，队友还用的是旧规则”。我现在的做法是给仓库配一个update.sh脚本，里面写清楚更新步骤：先拉代码，再执行./update.sh，脚本会帮你比对文件变更并提示是否需要重启会话。另外在CHANGELOG.md里记录每次改动，这样队友知道哪一次改动跟他们手头的工作有关。

# !/bin/bash # update.sh 示例 echo "正在备份当前全局配置..." cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d) echo "将模板库的 global/ 复制到 ~/.claude/" cp -r ./global/* ~/.claude/ echo "可选：更新项目级模板" if [ -f ./project/CLAUDE.md ]; then echo "检测到项目级模板，请手动复制到具体项目根目录" fi echo "完成。请重启 Claude Code 会话让模板生效。"

这个脚本虽然很基础，但能避免“手动复制粘贴漏项目”的问题。真正在团队里推广模板库时，脚本化和自动化是必须的，否则大家嫌麻烦就不会去更新。

6. 进阶扩展：把模板库变成你的工作流核心

模板库不只是静态的文件集合，它还可以承担不少“流程自动化”的活。我目前在做的几个扩展方向，供你参考：

第一个是给模板库加“项目初始化”技能。新建项目时，Claude Code 读取这个技能，自动批量生成 CLAUDE.md、目录结构、初始配置文件和第一个 Hello World 测试。这样团队里开新服务的成本降得很低。

第二个是“周报辅助”技能。每周五它读取我这周的 git log、提交信息，按模板生成周报草稿，我再手改一遍。这个技能不需要多复杂，关键就是描述足够准确，写“当用户提到周报、本周工作、git 提交记录时使用”。

第三个是把模板库跟 CI 结合起来。模板里规定每个项目的 CLAUDE.md 都要包含## 常用命令和## 目录职责，然后在 CI 里跑一条脚本检查这两段是否缺失，缺失就报警。这看起来有点“小题大做”，实际执行下来对保持模板质量很有帮助。

我个人做模板维护时有个体会：模板是活的，不是写一次就完事。每次用 Claude Code 做任务如果遇到它反复出错、反复纠正的环节，那就是模板需要补规则的信号。把那些“你纠正过三次以上的问题”沉淀成模板里的一条规则，比你在终端里一次次重复解释高效得多。

对于刚接触 claude-code-templates 的读者，我建议不要一开始就搞一个覆盖所有场景的大仓库。先从一个项目的一个 CLAUDE.md 开始，跑两周，把发现的问题记录下来，再慢慢演化成模板库。等你积累到三五个项目的规则时，再把公共部分抽到全局层，项目特有部分留在项目层。模板这东西，规模不重要，贴合自己的真实工作流才重要。