企业官网建设流程全解析

1. 为什么值得花时间把 Claude Code 配置这件事搞透

很多人第一次接触 Claude Code，是把它当成一个“终端里的聊天框”来用的——问一句答一句，跟网页版没什么区别。但真正把它用起来的人会发现，这东西的价值根本不在对话本身，而在于它能不能读懂你的项目、能不能按你的规矩干活、能不能嵌进你现有的开发流程里。这三件事，全都依赖配置。

我自己的经历比较典型。最开始装完 Claude Code，随便在项目根目录跑了一下，让它改个函数，结果它把整个文件重写了一遍，风格跟我原来的代码完全不搭。后来才知道，它默认会去读项目根目录的CLAUDE.md，而我根本没建这个文件。再后来接触到 Skills 和 Slash Commands，才发现原来可以把“每次都要重复交代的规矩”固化下来，变成它自动遵守的上下文。这个过程踩了不少坑，也攒了一些经验，正好借这篇把 Claude Code 的配置体系从头到尾捋一遍。

这篇内容适合三类人：一是刚装好 Claude Code、还在摸索怎么让它“听话”的新手；二是已经能用但觉得效率上不去、想把它接进 CI/CD 和团队协作流程的中级用户；三是想自己写 Skills、做定制化能力扩展的进阶玩家。我会从配置文件的组织方式讲起，到 CLAUDE.md 怎么写、Skills 怎么装和怎么自己造、Slash Commands 怎么省事、CI 里怎么跑，最后给一份常见问题速查表。全程按我实际操作的顺序来，能直接抄的地方我会把命令和配置贴出来。

需要先说明一点：Claude Code 的安装和账号可用性在不同地区、不同网络环境下情况不一样，官方也有明确的支持范围说明。这部分我不展开，你按官方文档确认自己能用之后再往下看配置。下面的内容全部基于“已经能正常启动 Claude Code”这个前提。

2. 配置文件到底放在哪：三层结构先搞清楚

2.1 全局配置、项目配置、会话配置的分工

Claude Code 的配置不是一个大文件搞定，而是分层的。理解这个分层，后面所有操作都不会乱。我把它归纳成三层：

• 全局层：放在用户主目录下，影响你这台机器上所有的 Claude Code 会话。适合放个人偏好，比如你习惯用的模型、默认的权限策略、你个人的通用指令。
• 项目层：放在项目根目录，跟着代码仓库走。适合放这个项目特有的规矩，比如技术栈、目录结构约定、代码风格、禁止改动的文件。这一层是团队协作的核心，因为它能进版本控制。
• 会话层：临时生效的，比如你在某次对话里用 Slash Command 切换了模式，或者临时授权了某个操作。关掉就没了。

为什么要这么分？因为“个人习惯”和“项目规矩”是两回事。你把项目规矩写进全局配置，换个项目就冲突；你把个人偏好写进项目配置，同事拉下来一脸懵。分层的意义就是让该共享的共享、该私有的私有。

2.2 全局配置的实际位置和内容

全局配置一般在用户主目录下的配置目录里。以类 Unix 系统为例，通常在~/.claude/这个路径下（具体文件名以你安装的版本为准，可以用claude config相关命令查看当前生效的路径）。这个目录里常见的有：

• 全局的指令文件，相当于对所有项目生效的“系统提示”
• 权限相关的设置，比如哪些命令允许自动执行、哪些必须每次确认
• 模型和 API 相关的偏好

我个人的做法是：全局层只放两样东西——我的通用编码偏好（比如“注释用中文”“提交信息用约定式提交格式”），以及权限白名单（比如允许它自动跑git status、ls、cat这类只读命令）。其余一律下沉到项目层。这样换项目时不会带着上一个项目的包袱。

注意：全局配置里的权限白名单要克制。我一开始图省事，把rm、git push这类也加进去了，结果有一次它自作主张清理文件，差点把没提交的改动删掉。只读命令可以放开，写操作和网络操作建议保留确认。

2.3 项目配置为什么必须进版本控制

项目层的配置，核心就是根目录那个CLAUDE.md，外加可能的.claude/目录（放项目级的 Skills、Commands、权限设置）。这些东西一定要提交到 Git。

理由很直接：团队里每个人拉下代码，Claude Code 的行为应该是一致的。如果只在你本地有效，那同事用起来就是另一套行为，代码评审时会出现“为什么你的 AI 改出来的风格和我的不一样”这种扯皮。把项目配置进版本控制，等于给整个团队的 AI 助手定了同一本“员工手册”。

我现在的习惯是，新建项目第一件事不是写代码，而是先写CLAUDE.md。哪怕只有几行，也比没有强。后面随着项目演进再逐步补充。

3. CLAUDE.md 怎么写才算真正有用

3.1 它到底在什么时候被读取

CLAUDE.md是 Claude Code 的项目记忆文件。它在会话启动时被读取，作为上下文注入。也就是说，你在里面写的东西，相当于每次对话开始前都自动跟它说了一遍。这就解释了为什么它这么重要——你不想每次重复交代的事，全放这里。

它的读取是有层级的。除了项目根目录，子目录里也可以放CLAUDE.md，当 Claude Code 处理那个子目录的文件时，会额外读取对应的文件。这个机制很适合 monorepo：根目录放全局约定，各个子包目录放自己特有的说明。

3.2 一份能直接用的 CLAUDE.md 模板

下面这份是我在多个项目里迭代出来的结构，你可以直接拿去改：

# 项目说明 ## 技术栈 - 语言：TypeScript 5.x - 框架：React 18 + Vite - 包管理：pnpm - 测试：Vitest + Testing Library ## 目录结构 - src/components：通用组件，每个组件一个目录 - src/pages：页面级组件 - src/hooks：自定义 hooks - src/utils：纯函数工具 ## 代码规范 - 组件用函数式，不用 class - 样式用 CSS Modules，不用内联样式 - 所有导出用命名导出，不用 default export - 注释用中文，只在逻辑复杂处写 ## 常用命令 - 安装依赖：pnpm install - 启动开发：pnpm dev - 跑测试：pnpm test - 类型检查：pnpm typecheck ## 禁止事项 - 不要修改 src/generated 下的文件，那是自动生成的 - 不要动 package.json 里的依赖版本，需要升级先问我 - 提交前必须跑通 pnpm test 和 pnpm typecheck

这份模板的关键在于：它把“我每次都要解释一遍的东西”全部前置了。技术栈、目录约定、命令、禁区，四块写清楚，Claude Code 的行为立刻就不一样了。

3.3 写 CLAUDE.md 的几个反直觉经验

第一，不要写太长。我一开始恨不得把整个架构文档塞进去，结果发现上下文被占满，真正跟当前任务相关的信息反而被稀释。现在我的原则是：只写“不写它就会犯错”的内容。能靠代码本身看出来的，不写。

第二，用命令式，不用描述式。写“项目使用 pnpm”不如写“安装依赖用 pnpm install，不要用 npm”。前者是描述，后者是指令。Claude Code 对指令的响应明显更好。

第三，禁区要具体到路径。写“不要改配置文件”太模糊，它会猜。写“不要修改src/generated/和*.lock文件”就明确多了。我踩过的坑就是它把 lock 文件重排了一遍，导致 diff 巨大。

第四，定期清理。项目演进后，有些约定过时了，留在CLAUDE.md里会误导它。我一般每个迭代回顾一次，把不再适用的条目删掉。

提示：如果你不确定某条规矩该不该写，先观察它是否犯过这个错。犯过就写，没犯过就先不写。这样能保持文件精简。

4. Skills 体系：从安装到自建

4.1 Skills 是什么，和普通指令有什么区别

Skills 是 Claude Code 里一个能力扩展机制。你可以把它理解成“可插拔的技能包”——每个 Skill 封装了一类特定任务的知识和流程，需要的时候被调用。它和CLAUDE.md的区别在于：CLAUDE.md是常驻上下文，Skills 是按需加载。

这个区别很关键。CLAUDE.md写多了会占上下文，而 Skills 只在相关任务出现时才被激活，不占日常对话的空间。所以我的分工是：通用规矩放CLAUDE.md，专项能力做成 Skills。

举个例子，我经常要做 LaTeX 排版。如果把这套知识写进CLAUDE.md，那写前端代码时它也占着位置。做成一个 LaTeX Skill，只在我说“帮我排版这篇论文”时才加载，就干净多了。

4.2 安装现成 Skills 的几种途径

Skills 的来源主要有几类：

• 官方或社区维护的技能库：一些公开的仓库会提供常用 Skills，比如前端开发、文档处理、数据分析等方向。
• 团队内部共享：把团队沉淀的 Skills 放在内部仓库，成员按需拉取。
• 自己编写：针对自己的高频任务定制。

安装方式通常是把手动下载的 Skill 目录放到指定位置。以项目级为例，一般放在项目根目录的.claude/skills/下；全局级则放在用户配置目录的对应位置。具体路径以你所用版本的文档为准，可以用claude的相关子命令查看当前加载了哪些 Skills。

手动安装 GitHub 上的 Skill 的通用流程是：找到 Skill 仓库，克隆或下载，把 Skill 目录（通常包含一个描述文件和若干资源文件）放到 Skills 目录下，然后重启会话或触发重新加载。放对位置后，可以用命令列出当前可用的 Skills 来验证。

注意：不同来源的 Skills 质量参差不齐。安装前先看它的描述文件和实际内容，确认它做的事是你想要的。我装过一个号称“自动重构”的 Skill，结果它的策略是把所有函数拆成单行，完全不能用。装之前扫一眼实现，能省很多事。

4.3 自己写一个 Skill 的完整流程

自己写 Skill 其实不难，核心是把“你脑子里的一套流程”翻译成结构化的文件。一个 Skill 通常包含：

• 一个描述文件，说明这个 Skill 叫什么、什么时候用、怎么用
• 具体的指令内容，告诉 Claude Code 执行这类任务时的步骤和注意事项
• 可选的辅助资源，比如模板、示例、参考文档

我拿“LaTeX 排版”这个场景走一遍。首先明确触发条件：当用户要求排版论文、生成 tex 文件、处理参考文献时启用。然后写指令内容，包括：文档类选择（article / report）、中文支持怎么配、公式和图表的标准写法、参考文献用 BibTeX 还是 biblatex、常见编译错误的处理。最后附一个模板文件作为参考。

写 Skill 的几个要点：

• 触发条件要写清楚。不写清楚，它要么不激活，要么乱激活。
• 步骤要可执行。别写“注意排版美观”这种虚的，写“行距用 1.5 倍，段前段后 0.5em”。
• 给出正反例。告诉它什么是对的、什么是错的，比只描述正确做法有效得多。
• 控制篇幅。Skill 也是要占上下文的，别写成一本教科书。

4.4 Skills 的组织和复用策略

当 Skills 多起来之后，组织就成了问题。我的做法是按“领域”分目录，比如frontend/、docs/、data/、modeling/。每个领域下放相关的 Skills。这样查找和复用都方便。

复用方面，我强烈建议把团队共用的 Skills 放进项目仓库或内部共享库。个人临时用的放全局。这样既保证团队一致，又不影响个人实验。我见过有团队把 Skills 当代码一样做版本管理、写变更记录，效果很好——本质上它就是你团队工作流的一部分。

5. Slash Commands：把高频操作变成一条命令

5.1 Slash Commands 解决的是什么问题

有些操作你每天要重复很多次，比如“跑测试并修复失败用例”“按规范生成提交信息”“检查当前改动有没有违反项目约定”。每次都用自然语言描述一遍，既费事又不稳定——描述稍有不同，结果就可能不一样。

Slash Commands 就是把这些高频操作固化成命令。输入/命令名，它就按预设的流程执行。好处是：快、一致、可共享。团队里定义好一套 Commands，所有人的操作方式就统一了。

5.2 定义和使用一个自定义 Command

自定义 Command 一般以文件形式存在，放在项目或全局的 commands 目录下。文件名就是命令名，文件内容是执行逻辑。举个我常用的例子，一个“提交前检查”命令：

--- description: 提交前跑完整检查流程 --- 请按以下步骤执行： 1. 运行 pnpm typecheck，如果有类型错误，逐个修复 2. 运行 pnpm test，如果有失败用例，分析原因并修复 3. 运行 pnpm lint，自动修复可修复的问题 4. 检查 git diff，确认没有误改 generated 目录和 lock 文件 5. 如果全部通过，用约定式提交格式生成一条提交信息 任何一步失败都要停下来告诉我，不要跳过。

保存为precommit.md后，输入/precommit就能触发。这个命令把我每次提交前的检查流程完全固化了，省了大量重复描述。

5.3 参数化和组合使用

Slash Commands 可以接受参数，这让它更灵活。比如一个“新建组件”的命令，可以接收组件名作为参数，然后按项目规范生成目录结构、组件文件、样式文件、测试文件。

组合使用是指把多个 Command 串起来。比如/precommit里可以调用/typecheck和/test。这样每个小命令单独可用，组合起来又是完整流程。我现在的项目里，Commands 已经形成了一套小体系，新人拉下代码就能用，不用问“提交前要做什么”。

提示：Command 的命名要直观。/precommit比/pc好，/newcomponent比/nc好。团队协作时，可读性比省那几个字符重要。

6. 把 Claude Code 接进 CI/CD 流程

6.1 为什么要在 CI 里用 Claude Code

CI 里用 Claude Code，主要解决两类问题：一是自动化的代码审查和修复建议，二是重复性的维护任务。比如每次 MR 提交后，自动跑一遍规范检查，把违反项目约定的地方标出来；或者定期扫描依赖更新、生成变更说明。

但要清醒一点：CI 里的 AI 操作必须是只读或低风险的。让它在 CI 里自动改代码并提交，风险太大。我的原则是：CI 里只做分析和建议，改动由人来确认。

6.2 在 GitLab CI 里跑 Claude Code 的基本配置

下面是一个 GitLab CI 的示例配置，思路是在流水线里跑一个检查任务：

stages: - review ai-review: stage: review image: node:20 before_script: - npm install -g @anthropic-ai/claude-code script: - claude --print "检查本次改动的代码是否符合 CLAUDE.md 中的规范，列出问题清单" > review-report.txt - cat review-report.txt artifacts: paths: - review-report.txt rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"

这个配置的关键点：用--print模式让它在非交互环境下输出结果，把结果存成 artifact 供人查看。注意这里需要配置好相应的访问凭据，具体方式按官方文档来。

6.3 CI 环境下的注意事项

第一，凭据管理。CI 里用到的访问凭据要放在 CI 的变量里，不要硬编码在配置文件中。这是基本安全要求。

第二，超时控制。AI 调用可能比较慢，要给任务设置合理的超时时间，避免流水线卡死。

第三，成本控制。CI 里每次 MR 都跑一遍，调用量会累积。建议只在关键分支或特定条件下触发，比如只对目标分支为 main 的 MR 跑。

第四，结果处理。AI 的输出是建议，不是判决。不要让它直接阻断流水线，除非你非常确定它的判断可靠。我现在的做法是把结果作为评论发到 MR 上，由人决定是否采纳。

第五，环境一致性。CI 里的 Claude Code 版本、Skills、Commands 要和本地尽量一致，否则行为会有差异。把项目级配置进版本控制，CI 里拉下来就能用，这点前面强调过。

7. 常见问题与排查速查表

7.1 配置不生效怎么办

这是最常见的问题。排查顺序如下：

我的经验是，九成的“不生效”都是路径或文件名问题。先确认文件放对了地方，再怀疑其他。

7.2 上下文被占满、响应变慢

如果发现响应变慢、它开始“忘事”，多半是上下文被占满了。原因通常是CLAUDE.md写太长，或者加载了太多 Skills。

解决办法：精简CLAUDE.md，只留必要内容；把专项能力从CLAUDE.md移到 Skills；定期清理不再使用的 Skills 和 Commands。我一般保持CLAUDE.md在 100 行以内，超过就考虑拆分。

7.3 它改代码的风格和项目不一致

这通常是CLAUDE.md里规范写得不具体。把“代码要整洁”改成具体的规则，比如“函数不超过 50 行”“变量用 camelCase”“导入按字母排序”。规则越具体，它越容易遵守。

另一个办法是给它看例子。在CLAUDE.md里贴一段符合规范的代码作为参考，比纯文字描述有效。

7.4 权限相关的困扰

它老是问你要不要执行某个命令，很烦；或者它自作主张执行了危险操作，很吓人。这两个问题的解法都在权限配置里。

把只读命令加进白名单，减少打扰。把写操作和网络操作保留确认，保证安全。这个平衡点需要根据你的项目调整。我的建议是宁可多确认几次，也不要放开危险操作。

7.5 团队协作时的配置同步

团队里每个人的 Claude Code 行为不一致，多半是配置没同步。解决办法：项目级配置全部进版本控制，包括CLAUDE.md、.claude/下的 Skills 和 Commands。新人拉下代码后，按 README 里的说明做一次初始化即可。

我还会在项目 README 里加一节“AI 助手配置说明”，告诉新人怎么装、怎么用、有哪些约定。这样能省掉大量口头沟通。

8. 我踩过的几个坑和对应的解法

第一个坑是过度依赖全局配置。我一开始把所有东西都写在全局，结果换项目时各种冲突。后来改成全局只放个人偏好，项目相关全部下沉，问题就没了。这个教训是：配置的归属要跟着“作用范围”走，不要图省事全堆一处。

第二个坑是Skills 装太多。有段时间我看到 Skill 就装，结果上下文被大量不常用的 Skill 占着，响应变慢，还经常激活错误的 Skill。后来我做了一次大清理，只留真正高频使用的，其余按需临时装。清爽了很多。

第三个坑是CI 里让 AI 自动改代码。我试过让 CI 自动修复 lint 问题并提交，结果有一次它改错了逻辑，还直接推上去了，回滚花了不少时间。从那以后，CI 里只做分析和建议，改动一律人工确认。这个边界一定要守住。

第四个坑是CLAUDE.md 写成文档。我一开始把它当架构文档写，又长又全，结果它反而抓不住重点。后来改成“只写不写就会犯错的内容”，用命令式短句，效果好很多。文件短了，它的遵守度反而高了。

第五个坑是忽略版本差异。Claude Code 更新比较快，配置格式和命令有时会变。我有次按旧文档配的，怎么都不生效，后来发现是新版本改了路径。现在的习惯是，配置出问题先查当前版本的文档，别想当然。

9. 关于配置这件事的一点个人体会

配置 Claude Code 这件事，本质上不是“调参数”，而是“把你的工作方式翻译给它听”。你越清楚自己的项目规矩、越能把规矩写具体，它就越像一个靠谱的同事；你越含糊、越指望它自己猜，它就越容易给你添乱。

我现在维护的几套配置，都是经过反复迭代的。每次它犯错，我就想：这个错能不能通过改配置避免？能，就加一条规则或做一个 Skill。这样积累下来，配置越来越贴合实际，重复沟通越来越少。这个过程没有终点，但每迭代一次，效率就上一个台阶。

如果你刚开始，别想着一次配到位。先把CLAUDE.md建起来，写清楚技术栈和禁区；然后把你最烦的重复操作做成一个 Slash Command；再挑一个高频专项任务做成 Skill。这三步走完，你就能明显感觉到差别。剩下的，边用边补。