企业官网建设流程全解析

开篇先说实话：这个标题“claude-code-templates”乍一看平平无奇，但真正用Claude Code写过几天代码的人，都会意识到“模板”这两个字才是撬动效率的核心杠杆。我自己最初用Claude Code时，就是裸奔状态——没有CLAUDE.md、没有命令别名、没有子代理，每次对话前都要重复交代项目背景、代码规范、测试命令，AI还是时不时给出风格割裂的修改。后来我把常用配置沉淀成一套模板仓库，体验完全不一样：新项目接入从半小时缩短到三分钟，团队新成员上手就能让AI按统一规范工作，AI改代码的“乱来”概率也大幅下降。

这篇文章不是讲Claude Code的基础安装和聊天技巧，而是围绕这套模板工程，拆解它背后的设计思路、核心配置项的语法与作用、完整的搭建流程，以及我在实践中踩过的坑。适合三类人看：正在用Claude Code但觉得AI输出不够稳定的开发者，想给团队建立统一AI协作规范的工程负责人，以及想深度定制CLAUDE.md、子代理、命令别名这些高级功能的进阶用户。内容会偏实战，直接给可复制的代码片段和目录结构。

1. 为什么Claude Code需要一套模板体系

1.1 裸奔状态下的真实痛点

先还原一个很常见的场景：你打开终端，输入claude，然后跟AI说“帮我看看这个项目的登录模块，重构一下”。Claude Code确实能读代码、能改代码，但它对你的项目一无所知——不知道你用React还是Vue，不知道你的测试框架是Vitest还是Jest，不知道你的目录命名习惯，不知道哪些文件是自动生成的不能动。于是它开始“自由发挥”，按照它训练数据里最通用的方式来改代码。

结果就是：改出来的代码能跑，但风格跟你的项目完全不像；它可能动了一个你明确说了“不要碰”的配置文件；它理解错了你的构建脚本，用了错误的命令跑测试。这些问题不是Claude Code能力不行，而是缺少约束和前置信息。你当然可以在每次对话里把这些信息重新说一遍，但对话一长、上下文一挤，它还是会忘。

模板体系干的就是这件事：把项目的背景知识、规则约束、常用命令、任务流程，提前固化到配置文件中。每次启动Claude Code，它自动加载这些信息，就像新员工入职第一天拿到一本员工手册，而不是靠带教人每天口头重复。

1.2 模板体系的三个层级

我把一套完整的Claude Code模板拆成三个层级，分别解决不同粒度的问题：

• 项目级规范（CLAUDE.md）：描述这个项目是什么、技术栈是什么、目录怎么组织、代码风格是什么、有哪些禁忌。这是AI在项目里工作的“宪法”，优先级最高。
• 命令级封装（命令别名和斜杠命令）：把“跑测试”“lint”“提交commit”这类高频操作封装成固定指令。AI不用反复猜测命令格式，你也省去每次手动执行的麻烦。
• 任务级分工（子代理与技能）：针对“代码评审”“安全审计”“写测试用例”这类复杂任务，定义专门的子代理。让AI先进入特定角色，再执行任务，输出质量会稳定很多。

这三个层级不是互相替代的关系，而是叠加生效的。CLAUDE.md管全局，命令别名管操作，子代理管任务类型。缺了任何一个，模板体系都是不完整的。

2. 模板工程的核心设计与配置语法

2.1 目录结构：从零搭一个模板仓库

我维护的模板仓库目录结构大致长这样：

claude-code-templates/ ├── README.md ├── project-templates/ │ ├── frontend-react/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── commands/ │ │ │ │ ├── test.md │ │ │ │ ├── lint.md │ │ │ │ └── commit.md │ │ │ └── agents/ │ │ │ └── code-review.md │ │ └── .claude/settings.json │ ├── backend-python/ │ │ └── ... │ └── fullstack-next/ │ └── ... ├── shared/ │ ├── agents/ │ │ ├── debugger.md │ │ └── security-auditor.md │ └── command-templates/ │ └── ... └── scripts/ └── init_project.sh

每个子目录对应一种典型项目类型，复制到目标项目根目录就能用。shared/里放的是跨项目通用的子代理和命令模板，避免重复维护。scripts/init_project.sh是一个初始化脚本，自动化完成复制和替换占位符的工作。

注意：不同版本对CLAUDE.md的解析优先级有细微差别，如果项目里同时存在根目录和子目录的CLAUDE.md，建议以根目录为主、子目录为辅，避免多个CLAUDE.md互相冲突。

2.2 CLAUDE.md的正确写法

CLAUDE.md不是越长越好，也不是把项目文档整个抄进去。它需要的是“AI能直接执行”的高密度信息。我的经验是分成五个区块：项目概览、技术栈、目录结构、编码规范、执行命令和工作流。

一个前端React项目的CLAUDE.md示例：

# 项目概览 这是一个面向中小商户的POS收银系统前端，使用React 18 + TypeScript。 主要业务模块：商品管理、订单结算、会员营销、数据报表。 UI组件库使用Ant Design 5，样式方案为CSS Modules。 # 技术栈约束 - 框架: React 18，函数组件 + Hooks，禁止使用class组件。 - 语言: TypeScript strict模式，禁止使用any。 - 状态管理: Zustand，不使用Redux。 - 数据请求: React Query + Axios，API层统一封装在src/services。 - 测试: Vitest + React Testing Library，禁止使用Jest。 # 目录结构 src/ components/ 通用业务组件，按domain分子目录 pages/ 页面级路由组件 services/ API请求封装，禁止在组件内直接写fetch stores/ Zustand store定义 hooks/ 自定义Hooks utils/ 纯函数工具库 styles/ 全局样式、CSS变量 # 编码规范 - 组件命名使用PascalCase，文件名与组件名保持一致。 - CSS变量在styles/variables.css中定义，禁止在组件内写死颜色值。 - 所有表单必须有校验规则，错误信息使用中文。 - 禁止修改src/__generated__目录下的任何文件，这是代码生成器输出。 # 常用命令 - 安装依赖: npm install - 启动开发服务: npm run dev - 运行测试: npm run test -- --run - 类型检查: npm run typecheck - 构建生产包: npm run build

这五块内容里，最容易忽略的是“禁止事项”。AI对“不要做什么”的遵守程度，往往比对“要做什么”更高，因为约束条件越明确，搜索空间越小。比如“禁止修改生成目录”“禁止用Redux”“禁止在组件里直接写fetch”，这些规则能直接拦住AI最常见的越界行为。

2.3 命令别名与斜杠命令的封装思路

命令别名的作用是给AI提供一套固定的“操作按钮”。CLAUDE.md里写了“运行测试用npm run test”，AI也许能记住，但每次对话你都要重新确认。改成命令别名后，一个/test就搞定，而且AI会严格按别名里的步骤来执行。

在项目根目录的.claude/commands/test.md里写：

--- description: 运行项目完整测试套件 argument-hint: 可指定单个测试文件路径，如 /test src/utils/format.ts --- 执行以下步骤： 1. 如果项目根目录存在package-lock.json或pnpm-lock.yaml，使用pnpm安装依赖（若已安装可跳过）。 2. 运行 pnpm run typecheck，若有类型错误先修复。 3. 运行 pnpm run test -- --run，执行全量测试。 4. 若测试失败，优先检查最近的代码变更，定位到具体组件，修复后重新执行。 5. 测试全部通过后，用一个简短表格汇报：测试用例总数、通过数、失败数、修复的文件列表。

注意命令文件头部用了YAML front matter，description是斜杠命令菜单里显示的文字，argument-hint提示用户可以跟参数。这样/test就能被自动补全，输入/的时候会弹出命令列表。

封装的思路不是简单地把命令字符串写死，而是把“执行命令 + 处理失败 + 汇报结果”的完整流程写进去。这样AI执行/test的时候，不是一个动作，而是一个完整的任务闭环。

2.4 子代理：按任务分配专属AI角色

子代理是Claude Code里比较高级的功能，本质上是在配置文件中预先定义一组系统提示词，告诉AI“遇到这类任务时，切换到特定的角色、风格和流程”。代码评审在软件开发中极其重要，但让通用的Claude Code直接做评审，效果往往一般——它不够严格，容易放过问题，也容易在没有全局视角的情况下乱提意见。

在.claude/agents/code-review.md里，我的模板长这样：

--- name: 代码评审员 description: 对当前代码变更进行严格、全面的评审，重点找bug、设计缺陷和安全隐患 tools: Read, Grep, Glob --- 你是一名资深代码评审员，参与过大型商业项目的code review。你的目标是找出变更中的真实问题，而不是给出泛泛的赞美。 评审流程： 1. 先读取当前分支的git diff，理解改动的全部内容。 2. 定位每个改动文件，读取相关的上下文代码，确认改动是否完整。 3. 按以下维度逐项检查： - 逻辑正确性：边界条件、空值处理、异步竞态、状态更新是否遗漏。 - 类型安全：是否有隐式any、类型断言是否合理、是否绕过类型检查。 - 性能问题：循环内是否有重复计算、是否触发了不必要的重渲染。 - 安全风险：用户输入是否经过校验、是否有XSS/SQL注入隐患。 - 代码风格：命名是否规范、是否有死代码、是否违反项目约定。 4. 输出评审报告，按严重程度排序：阻塞级、建议级、可选级。 5. 每个问题必须给出：文件路径、行号、问题描述、修改建议。禁止笼统地写“代码质量有待提高”。 特别提醒： - 不要建议大规模重构，除非当前改动存在明确的架构缺陷。 - 不要只夸优点不说问题，评审的价值在于发现问题。 - 如果某个文件没有实质性问题，可以跳过，不用每个文件都评论。

子代理和普通对话的区别在于：它会严格遵守name和description里定义的角色，并且优先使用声明过的tools。比如这个评审员不声明Write工具，意味着它默认不会直接改代码，只输出评审报告，避免了“评审时顺手改了一堆东西”的失控情况。

3. 实操过程：从模板仓库到项目落地

3.1 初始化脚本的设计与实现

模板仓库光有一堆md文件还不行，直接复制会有问题——每个项目的项目名、包管理器、端口号不一样。所以需要一个初始化脚本，负责把模板里的占位符替换成真实项目信息。

我常用的脚本片段长这样：

#!/usr/bin/env bash # init_project.sh - 把模板复制到目标项目并替换占位符 set -euo pipefail TEMPLATE_DIR="$(dirname "$0")/../project-templates/frontend-react" TARGET_DIR="${1:-.}" if [ ! -d "$TARGET_DIR" ]; then echo "错误: 目标目录 $TARGET_DIR 不存在" exit 1 fi # 1. 复制模板文件到目标项目 cp -r "$TEMPLATE_DIR"/. "$TARGET_DIR"/ # 2. 询问项目关键信息 read -p "项目显示名称（用于README和CLAUDE.md）:" PROJECT_NAME read -p "包管理器 (pnpm/npm/yarn):" PKG_MANAGER read -p "开发端口: " DEV_PORT # 3. 替换占位符 find "$TARGET_DIR/.claude" -type f -name "*.md" -exec sed -i \ -e "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" \ -e "s/{{PKG_MANAGER}}/$PKG_MANAGER/g" \ -e "s/{{DEV_PORT}}/$DEV_PORT/g" {} + # 4. 检查目标项目是否已有CLAUDE.md，避免覆盖用户自定义内容 if [ -f "$TARGET_DIR/CLAUDE.md" ] && [ ! -f "$TARGET_DIR/CLAUDE.md.bak" ]; then cp "$TARGET_DIR/CLAUDE.md" "$TARGET_DIR/CLAUDE.md.bak" echo "已存在CLAUDE.md，原文件备份为CLAUDE.md.bak" fi echo "初始化完成。建议先打开CLAUDE.md，按项目实际情况Adjust内容。"

这个脚本做的事情其实不复杂：复制模板、交互式收集配置、批量替换占位符、保护已有文件。但有一个细节值得注意：备份已有CLAUDE.md。因为很多项目可能之前已经有了一份简单的CLAUDE.md，直接覆盖会把原有信息丢掉，备份是最稳妥的做法。

提示：不要用脚本一次性做太多事。初始化脚本只负责“复制+替换+备份”这三件事，至于安装依赖、初始化git仓库这些操作，建议手动执行，避免脚本报错后留下一个半初始化状态的项目。

3.2 核心模板文件逐个拆解

接下来把每个核心模板文件到底写了什么、为什么这么写，逐个过一遍。

CLAUDE.md的“禁止事项”设计

前面给了一个示例，这里再展开讲讲“禁止事项”的写法。很多人的CLAUDE.md只写“项目技术栈是什么、目录结构是什么”，不写“不能做什么”，这会导致AI在一些灰色地带反复试探。比如“不要修改docs/目录下的文件，这些是自动生成的API文档”“不要移除任何已存在的commented-out代码，除非用户明确要求”“不要在生产代码中留下console.log”。这些规则看着琐碎，但每一条都来自真实事故：AI清理过自动生成文件、删过注释掉的兼容代码、在提交前加过调试输出。把这些事故写成规则，是模板迭代的主要来源。

命令别名的格式细节

命令别名的文件格式有几点容易被忽略：

• 文件名里的连字符和空格会被转成斜杠命令名，例如code-review.md对应的命令是/code-review，建议全部用小写加连字符，避免输入麻烦。
• front matter里的description字段最好控制在50字以内，太长会在命令列表中截断。
• 如果命令需要用户提供参数，记得写argument-hint，并且在大纲里用{{argument_hint}}这样的占位符引用用户输入。

子代理文件的YAML front matter注意事项

子代理文件开头的name字段决定了AI自报身份时用的名字，tools字段则严格限制能用哪些工具。一个常见误区是以为tools写得多就好——不是的，工具越多，AI的选择负担越重，越容易跑偏。我的经验是：让子代理“会读不会写”，把修改动作交回主线程。这样既保证了上下文连贯，也便于主线程统一协调。

3.3 版本管理与模板迭代策略

模板仓库本身要用git管理，这是废话，但怎么管理是有讲究的。我的策略是：

• 模板仓库不追踪任何具体项目的业务代码，只存放“去掉业务内容后的骨架”。
• 使用分支来区分模板的大版本，比如v1-react-spa、v1-node-api、v2-react-spa。因为技术栈演进很快，隔一两个月CLAUDE.md里的最佳实践可能就变了，分支可以隔离这些变化。
• 每次从模板生成项目后，如果发现CLAUDE.md有写得不准的地方，先改模板仓库，再同步到已生成的项目里，而不是反着来。因为已生成的项目是你当前的工作现场，容易夹带业务判断，不适合作为规则沉淀的源头。

模板迭代还有个很实用的来源：Claude Code本身的升级日志。官方文档每个版本都会列出行为变化、新配置项、废弃的旧语法，我会挑跟模板相关的更新，同步到模板仓库里。比如某次升级后，settings.json里新增了permissions字段可以更细粒度地控制文件读写权限，这个信息如果不及时同步，模板里的旧设置就会失效。

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

4.1 AI忽略CLAUDE.md中的规则怎么办

这是被问得最多的一个问题：CLAUDE.md里明明写好了“不要用class组件”，AI还是生成了class组件。原因有几个，逐一排查：

• 上下文被用户指令覆盖：如果对话中途你说了“这里直接用class组件实现一下”，AI会优先听从最近的明确指令，这是正常的指令优先级逻辑。解决办法是别跟CLAUDE.md的规则冲突，或者在冲突时明确说明“这次破例”。
• CLAUDE.md太长被截断：Claude Code对包含CLAUDE.md在内的上下文有窗口限制，如果CLAUDE.md超过几千字，AI可能在处理具体任务时把它挤出了有效注意力范围。解决方法是精简规则，把最重要的5条放在文件最前面，次要规则放到子目录里的CLAUDE.md中，按场景加载。
• 规则写得太抽象：对比“遵守项目编码规范”和“组件文件统一使用PascalCase命名，禁止使用默认导出”，后者显然更容易被执行。规则必须落到“看到什么、做什么”的粒度，而不是“要专业”这类形容词。

4.2 加载模板后AI反而变笨了，怎么定位

有些情况下，挂载了CLAUDE.md和一堆子代理后，AI的回答反而变得顾此失彼、反应迟钝。这种时候要按层级做减法排查：

1. 先临时删掉.claude/agents目录下的所有子代理文件，重启会话看是否恢复正常。
2. 再注释掉命令别名文件里的所有front matter，只保留正文，看影响是否还在。
3. 最后精简CLAUDE.md，从完整版缩减到只有项目概览和命令两节，再逐步加回其他内容。

这个“逐层删减法”是排查性能劣化的最直接路径。我自己遇到过一次：某个子代理文件里写了一个良性但冗长的“输出报告格式”模板，导致AI每次响应都要先生成一大段没用的格式头，看起来就是变笨了。删掉那段冗余描述后，响应速度明显改善。

4.3 多项目共用模板文件丢失的问题

如果多个项目的.claude/目录是直接复制出来的，一旦模板仓库更新，旧项目不会自动同步。时间一长，各项目的配置会漂移得厉害。解决方案是：不要用复制，用符号链接或同步脚本。

我现在的做法是在每个项目里放一个.claude-sync.yml，记录这个项目引用了哪个版本的模板。然后写一个同步脚本，在模板仓库更新后，跑一遍就能按清单把变更推送到各项目。这样既保留了项目本地化的修改（同步时会跳过项目里user-modified文件），又能跟上模板的更新节奏。

5. 从工具效率到团队协作：模板的延伸价值

5.1 模板是团队知识的外化载体

聊到这里，已经不只是技术问题了。很多人以为CLAUDE.md是写给AI看的，但我用了大半年后的体会是：它首先是一份极其精炼的团队知识文档。过去新人入职要花一周读代码、记规范、熟悉工作流，现在一份写好的CLAUDE.md就能让AI在几分钟内按照同样的规范行动。这背后其实是把团队里那些“隐性知识”——比如“报表模块的接口字段不能轻易改，会波及下游”“这个目录下的组件已经废弃，别用了”——全部显性化，写进模板里。

对于技术负责人来说，值得专门花一个下午把CLAUDE.md从“个人备忘录”升级成“团队共识”，并且让模板进入Code Review的流程：每次改模板，都像改代码一样提交PR、做评审。这样模板就是团队最重要的资产之一。

5.2 实测过的几个高价值扩展方向

模板体系稳定之后，我尝试过几个扩展方向，都建议有条件的朋友试一试：

• 按任务类型定制评审子代理：除了代码评审，还可以定义“安全审计员”“SQL优化师”“无障碍检查员”等子代理。把Expertise固化到子代理里，需要时调用，比临时在对话里描述“你扮演一个安全专家”要可靠得多。
• 把模板和CI流程联动：很多团队已经用Claude Code做自动修复和代码生成。把模板作为CI里跑Claude Code任务的基础配置，就能实现“PR里让AI按团队规范自动检查并修复”这样的流水线能力。
• 跨项目共享公共规则：维护一份shared/目录，把几条核心安全规则（比如“禁止把API密钥写入代码”“禁止使用不安全的随机数生成器”）放到那里，然后让所有项目的CLAUDE.md通过引用方式引入。这样团队安全策略的更新，改一处就生效所有项目。

5.3 关于“AI是否真的需要模板”的思考

最后想聊一个观念层面的问题。早期我也有过“Claude Code这么聪明，为什么要用模板限制它”的疑问。实际用下来的结论恰恰相反：模板不是限制，而是给AI搭建了一个落脚点。它让AI不是每次都在混乱中猜你的意图，而是站在一个由你精心搭建的“规则地基”上工作。聪明的AI需要的是明确的边界和上下文，而不是无限的自由。

我自己维护这套模板仓库的时间越长，越觉得它像一个“定制化的AI工作台”。每踩一个坑，就往模板里加一条规则；每发现一个高效用法，就封装成一个命令或子代理。模板不只是初始化的那一刻起作用，它是伴随项目和团队持续生长的活文档。

最后再分享一个小技巧：给模板加一个CHANGELOG.md，记录每一次改动的原因是“修了什么bug”“新增了什么规则”“哪个AI行为模式发生了变化”。这份日志不仅对你自己有追溯价值，对团队其他成员理解“为什么模板会这样写”非常有帮助。毕竟AI协作的新范式下，维护好这套配置，远比每次对话前临时叮嘱AI一堆要求更高效，也更靠谱。