企业官网建设流程全解析

1. 从“AI编码助手”到“AI编码伙伴”的认知跃迁

如果你和我一样，每天都在和Cursor、Claude Code、GitHub Copilot这些AI编码工具打交道，那你一定经历过这样的场景：你满怀期待地输入一个需求，比如“帮我写一个用户登录的API接口”，AI助手确实能“唰”地一下生成一大段代码。但仔细一看，它可能用了你不喜欢的fetch而不是axios，或者把错误处理写成了你团队规范里明令禁止的try-catch嵌套地狱，又或者它生成的JSDoc注释风格和你项目里现有的完全不一样。你不得不花大量时间去修改、调整、纠正，感觉AI不是在帮你，而是在给你制造“技术债”。

这就是当前LLM编码助手的核心痛点：它们很聪明，但缺乏“上下文”和“一致性”。它们像是一个对每个项目都一视同仁的“通用程序员”，而不是一个深度理解你当前项目历史、团队习惯和个人偏好的“专属搭档”。Andrej Karpathy提出的“Skills”概念，以及围绕CLAUDE.md文件展开的实践，正是为了解决这个根本性问题。这不仅仅是创建一个配置文件，而是一种思维模式的转变——从被动地接受AI的“通用输出”，转变为主动地、系统性地“训练”和“引导”AI，让它真正成为你工作流中高效、可靠的一环。

简单来说，CLAUDE.md（或者类似的.cursorrules、agents.md）文件，就是你为AI编码助手编写的“入职培训手册”和“项目工作指南”。它不再是一个可有可无的提示词备忘录，而是一个结构化的、版本可控的、与项目代码库深度绑定的“元数据”层。通过它，你可以一次性解决四大顽疾：代码风格不一致、技术栈选择混乱、项目上下文缺失、以及复杂任务拆解能力不足。接下来，我将结合我过去几个月在多个真实项目中实践CLAUDE.md的经验，为你拆解如何构建一个真正有效的“技能文件”，让你手中的AI工具完成从“助手”到“伙伴”的质变。

2. 四大顽疾深度剖析：你的AI助手为何“不听话”

在动手编写CLAUDE.md之前，我们必须先清晰地诊断问题。只有理解了“病根”，才能开出有效的“药方”。这四大顽疾并非孤立存在，它们相互关联，共同导致了AI编码的低效。

2.1 顽疾一：代码风格与规范的“精神分裂”

这是最直观、也最令人头疼的问题。AI模型在训练时学习了海量的开源代码，这些代码来自成千上万个不同风格、不同规范的项目。因此，当它为你生成代码时，其风格是随机的、不可预测的。

• 具体表现：
  • 命名规范混乱：一会儿是camelCase，一会儿是snake_case，甚至可能出现PascalCase的变量名。
  • 缩进与空格：是2个空格、4个空格还是Tab？单行结尾是否保留分号？这些基础格式在AI的输出中经常摇摆不定。
  • 导入语句风格：是使用import * as还是具名导入？第三方库和内部模块的导入顺序如何？
  • 错误处理模式：是用Promise.catch、async/await配合try-catch，还是自定义错误类？错误信息格式是什么？
  • 注释与文档：JSDoc/TSDoc的格式、函数注释的详细程度、是否包含@param和@returns标签，这些都可能不一致。

注意：这不仅仅是美观问题。在一个团队项目中，不一致的代码风格会严重降低代码的可读性和可维护性，增加Code Review的负担，甚至可能引入隐藏的Bug（比如因缩进错误导致的逻辑错误）。

2.2 顽疾二：技术栈与依赖选择的“随机漫步”

AI模型知道很多技术，但它不知道“你的项目”用什么技术。这导致它在解决具体问题时，可能会选择一个你项目里根本不存在的库，或者一个已被淘汰的旧版本API。

• 具体表现：
  • HTTP客户端：你项目里明明统一用axios，它却给你生成fetch或request的代码。
  • 状态管理：你在用Zustand，它可能推荐你使用Redux Toolkit甚至MobX。
  • 日期处理：你规定使用day.js，它可能写出moment或原生Date的代码。
  • UI组件库：你基于Ant Design开发，它生成的示例代码可能用了Material-UI的组件。
  • 数据库ORM：你用的是Prisma，它可能生成一段TypeORM或Sequelize的查询。

这种“随机推荐”不仅需要你手动替换，更危险的是，它可能引入不兼容的依赖或过时的模式，破坏项目架构的纯净性。

2.3 顽疾三：项目特定上下文的“记忆缺失”

这是当前AI编码工具最大的能力边界。AI没有长期记忆，它对你正在工作的这个特定项目的了解，仅限于你当前打开的这几个文件（以及有限的上下文窗口）。它不知道：

• 项目的整体架构：比如你的src目录下是怎么组织的？是feature-based还是layer-based？
• 已存在的工具函数和常量：比如项目里已经有一个封装好的apiClient、一个formatCurrency工具函数、或者一组定义好的ERROR_CODES常量。AI很可能会重复造轮子。
• 业务领域的特定逻辑：比如你的电商项目里，“订单状态”有哪几种？从“待支付”到“已完成”的完整状态机是怎样的？这些业务规则AI无从知晓。
• 团队的内部约定：比如所有API响应必须包裹在{ code, data, message }的结构里，或者日志必须使用特定的Logger类输出。

没有这些上下文，AI生成的代码就像是无根之木，无法与现有代码库无缝集成。

2.4 顽疾四：复杂任务拆解的“能力断层”

对于简单的、原子性的任务（如“写一个排序函数”），AI表现优异。但一旦你提出一个复杂的、多步骤的、需要设计思维的任务（如“为我们的用户管理系统添加一个带分页和搜索的列表页，并集成权限控制”），AI就容易“懵圈”。

• 具体表现：
  • 遗漏关键步骤：可能只生成了UI组件，忘了写对应的API接口调用逻辑。
  • 逻辑顺序错乱：先处理了数据渲染，后才去考虑数据获取和状态初始化。
  • 缺乏设计考量：不会主动考虑组件复用、状态提升、性能优化（如防抖搜索）等问题。
  • 无法关联已有代码：不知道应该去复用项目中已有的PaginatedTable组件和usePermission钩子。

这导致开发者需要花费大量精力去“管理”AI，为它拆解任务、纠正方向，反而增加了认知负荷。

3. CLAUDE.md 文件构建实战：从骨架到灵魂

理解了问题，我们就可以开始构建解决方案——CLAUDE.md文件。这个文件应该放在你项目的根目录，与README.md同等重要。它不是一成不变的，而应该随着项目的发展而迭代。下面是一个由浅入深、层层递进的构建指南。

3.1 第一层：基础规范与风格（立规矩）

这是CLAUDE.md的基石，目的是解决“顽疾一”。你需要明确地告诉AI，在这个项目里，代码应该长什么样。

# 项目编码规范与技能 (CLAUDE.md) ## 1. 代码风格与格式化 - **语言**: TypeScript (严格模式) - **缩进**: 2个空格，禁止使用Tab。 - **字符串**: 统一使用单引号（'）. - **分号**: 行尾必须加分号。 - **命名**: - 变量/函数: `camelCase` - 类/类型/接口: `PascalCase` - 常量: `UPPER_SNAKE_CASE` - 私有成员: 前缀下划线 `_privateMethod` - **导入顺序**: 1. 第三方库 (如 `react`, `axios`) 2. 项目内部绝对路径导入 (如 `@/utils`, `@/components`) 3. 相对路径导入 (如 `./styles`, `../types`) 每类之间用一个空行分隔。 - **注释**: - 公共函数、类、复杂逻辑必须使用JSDoc/TSDoc格式注释。 - 单行注释使用 `//`。 - 避免无意义的注释，注释应解释“为什么”而不是“是什么”。 ## 2. 项目结构与架构 - 本项目采用 **“特性文件夹(Feature-based)”** 结构。 - `src/features/` 下每个文件夹代表一个核心业务特性（如 `auth`, `dashboard`, `orders`）。 - 每个特性文件夹内通常包含：`components/`, `hooks/`, `utils/`, `types.ts`, `api.ts`。 - 共享的组件、工具、类型放在 `src/shared/` 目录下。

这个部分相当于给AI一本《员工手册》，让它从第一天起就按照你的规矩来写代码。

3.2 第二层：技术栈与依赖声明（给武器）

这部分针对“顽疾二”，明确项目的技术选型，让AI在建议和生成代码时，从正确的“工具箱”里选取工具。

## 3. 技术栈与核心依赖 **前端框架**: React 18 (函数组件 + Hooks) **状态管理**: Zustand (简单场景) / React Query (服务器状态) **路由**: React Router v6 **HTTP客户端**: Axios (已封装为 `@/lib/api-client`) **UI组件库**: Ant Design v5，主题已自定义。 **表单处理**: React Hook Form + Zod (用于验证) **工具库**: - 日期: `day.js` - 工具函数: `lodash-es` (按需导入) - 图标: `@ant-design/icons` **禁止使用的模式/库**: - 避免使用 `class` 组件，除非有特殊需求。 - 禁止直接使用 `fetch`，必须通过封装的 `api-client`。 - 禁止使用 `moment.js`，统一使用 `day.js`。

通过这份“武器清单”，AI在建议“如何发送请求”时，就会直接给出使用axios和你的api-client的代码，而不是fetch。

3.3 第三层：项目特定上下文与约定（注入灵魂）

这是CLAUDE.md最具价值的部分，也是解决“顽疾三”的关键。你需要把AI当成一个新加入项目的资深工程师，把那些“只可意会”的团队知识明确化。

## 4. 项目特定上下文与约定 ### 4.1 核心业务概念 - **用户系统**: 用户角色分为 `admin`, `editor`, `viewer`。权限基于角色。 - **订单状态流**: `PENDING` -> `PAID` -> `PROCESSING` -> `SHIPPED` -> `DELIVERED` / `CANCELLED`。状态不可逆。 - **API响应格式**: 所有后端API返回统一格式: `{ code: number, data: T, message: string }`。`code === 200` 表示成功。 - **错误处理**: 使用项目统一的 `AppError` 类。前端通过 `api-client` 拦截，将非200状态码统一转换为 `AppError` 抛出。 ### 4.2 已封装的工具与组件 - **`useAuth()`**: Hook，返回 `{ user, login, logout, hasPermission }`。 - **`useApi()`**: Hook，基于React Query，用于调用GET类API，自动处理加载和错误状态。 - **`apiClient`**: 位于 `@/lib/api-client`，已配置基础URL、请求拦截器（添加Token）、响应拦截器（处理统一错误格式）。 - **`PaginatedTable`**: 位于 `@/shared/components`，已集成Ant Design Table、分页和搜索框。**需要列表页时，优先考虑复用此组件**。 - **`formatCurrency(amount: number)`**: 位于 `@/shared/utils`，用于格式化金额显示。 ### 4.3 文件与代码模板 **新建React组件模板**: ```typescript import React from 'react'; import { SomeAntdComponent } from 'antd'; import { useSomeHook } from '@/hooks/...'; interface ComponentNameProps { // 定义Props } export const ComponentName: React.FC<ComponentNameProps> = ({ ...props }) => { // 逻辑区 const { data, isLoading } = useSomeHook(); if (isLoading) return <Spin />; if (!data) return null; // 渲染区 return ( <div> <SomeAntdComponent data={data} /> </div> ); };

这部分信息是动态的，你需要定期维护和更新。当团队新增了一个好用的`useDebounce`钩子，或者封装了一个通用的`UploadImage`组件时，记得把它们加到`CLAUDE.md`里。这样，AI下次生成涉及防抖或图片上传的代码时，就会直接引用这些现有资产，而不是重新发明轮子。 ### 3.4 第四层：复杂任务拆解指南与工作流（授予兵法） 这部分旨在提升AI解决复杂问题的能力，应对“顽疾四”。你不是在让它“生成代码”，而是在教它“如何思考”这个项目里的任务。 ```markdown ## 5. 复杂任务拆解指南 当需要实现一个包含前后端的完整功能时（例如“用户管理列表页”），请遵循以下工作流思考： 1. **后端优先 (API Contract First)**: - 首先，思考这个功能需要哪些**新的API端点**？通常是 `GET /api/users` (列表+搜索+分页)、`PUT /api/users/:id` (编辑)、`DELETE /api/users/:id` (删除)。 - 为每个端点定义清晰的**请求参数**、**响应体类型**（TypeScript Interface）。这应该是你首先生成的代码。 2. **状态与数据流设计**: - 确定前端需要管理哪些**状态**？列表数据、分页参数、搜索关键词、选中行。 - 思考状态应该放在哪里？局部状态（`useState`）、全局状态（Zustand）、还是服务器缓存（React Query）？**对于从API获取的列表数据，优先使用React Query (`useQuery`, `useMutation`)**。 3. **UI组件结构**: - 拆解UI由哪些部分组成？通常包括：搜索栏、按钮组（新增、批量操作）、数据表格、分页器。 - **优先复用现有组件**：搜索栏可以用`<Input.Search>`，表格**必须优先尝试使用 `PaginatedTable` 组件**。 4. **集成与连接**: - 将API调用（使用`apiClient`或`useApi` Hook）与UI事件（搜索、翻页）连接起来。 - 将获取到的数据（通过React Query）传递给表格组件。 - 添加操作按钮（编辑、删除）的事件处理函数，里面调用对应的API Mutation。 **示例任务提示词**: 不要只说：“创建一个用户管理页面”。 应该说：“请遵循我们的任务拆解指南，为用户管理功能创建一个列表页。需要包含搜索（按姓名、邮箱）、分页、表格展示（列：ID、姓名、邮箱、角色、创建时间、操作），以及编辑和删除单条记录的按钮。请先定义所需的API接口类型，然后设计前端组件和数据流，最后生成代码。注意复用 `PaginatedTable` 组件和 `useApi` Hook。”

通过提供这样的“思考框架”，你极大地提升了AI处理复杂需求的成功率。它不再是从零开始“蒙”，而是按照你设定的、符合项目最佳实践的路径去执行。

4. 超越CLAUDE.md：多工具协同与技能生态

CLAUDE.md是一个伟大的起点，但现实中的开发环境往往是多工具并行的。你可能在VSCode里用Cursor写业务代码，在浏览器里用Claude Code审查代码片段，在终端里用llm命令生成脚本。如何让“技能”在不同工具间共享和同步？

4.1 工具特定文件的适配与转换

不同的AI工具有自己约定的配置文件，但其核心思想是相通的。

• Cursor: 使用.cursorrules文件。其内容与CLAUDE.md高度相似，你可以将核心的“规范”、“技术栈”、“上下文”部分直接复制过去。Cursor可能更强调一些编辑器特定的指令，比如代码补全的偏好。
• Claude Code (及类似扩展): 通常直接读取项目根目录的claude.md或CLAUDE.md。这就是我们正在构建的标准。
• Windsurf / Bloop 等: 这些较新的IDE原生AI助手，往往支持更丰富的配置，甚至允许你为不同文件类型（如.tsx,.py）定义不同的规则。你可以在CLAUDE.md的基础上，为它们创建更细化的windsurf.json或bloop.config.js文件。

实践建议：以CLAUDE.md作为“单一事实来源”（Single Source of Truth）。它是人类和所有AI工具共同参考的主文档。然后，为每个工具创建一个极简的适配文件，例如.cursorrules里只写一行：

# 请完整阅读并严格遵守项目根目录下的 `CLAUDE.md` 文件中的所有规范与约定。

或者，写一个简单的脚本，将CLAUDE.md的核心章节自动同步到各个工具所需的配置格式中。

4.2 技能文件的版本控制与团队共享

CLAUDE.md是项目资产，理应纳入 Git 版本控制。这带来了几个好处：

1. 历史追溯：可以看到编码规范的演变过程。
2. 团队一致性：所有团队成员拉取代码后，立即获得最新的AI编码指南，确保团队输出统一。
3. 分支特定规则：你甚至可以为长期存在的特性分支（如feat/ai-experiments）创建略微不同的CLAUDE.md，用于探索新的技术栈或模式，而不会影响主分支。

在团队中推广时，可以将其作为“新人上手必备文档”的一部分。新成员在阅读README.md了解项目概况后，紧接着就应该阅读CLAUDE.md，了解如何高效地利用AI助手进行开发。

4.3 动态上下文与“运行时”技能注入

CLAUDE.md是静态的、项目级的配置。但在实际编码会话中，你经常需要提供更动态、更具体的上下文。这就是“会话级提示词”或“运行时技能注入”的用武之地。

例如，当你正在修改一个与“支付”相关的模块时，你可以在对话开始时对AI说： “我们现在正在src/features/payment目录下工作。请特别注意，本模块的API错误码定义在src/features/payment/constants/errors.ts中，支付状态枚举在src/shared/types/payment.ts里。接下来关于支付的所有讨论，请优先引用这些现有定义。”

这种“动态上下文”与静态的CLAUDE.md相结合，形成了“战略+战术”的完美配合。CLAUDE.md提供战略方向和通用规则，而会话提示词提供战术层面的具体情报。

5. 实战避坑：让CLAUDE.md真正生效的五个关键

构建一个漂亮的CLAUDE.md文件只是第一步。让它持续、稳定地发挥作用，需要一些技巧和坚持。以下是我在多个项目中总结出的关键经验。

5.1 精准度与冗余度的平衡

CLAUDE.md不是越详细越好。过于冗长的文件，AI可能无法有效吸收全部信息（受上下文窗口限制），开发者维护起来也困难。

• 该详细的地方：项目独有的、反直觉的约定必须详细。比如你的API错误码1001代表“业务逻辑冲突”，这必须写清楚。比如你的项目因为历史原因必须使用一个特殊的日期格式YYYY/MM/DD，这必须强调。
• 该简洁的地方：通用、行业通行的规范可以引用外部标准。比如你可以写“ESLint规则遵循项目中的.eslintrc.js配置文件”，而不必把每条规则都列出来。代码风格可以写“使用Prettier，配置见.prettierrc”。

5.2 积极维护与迭代

CLAUDE.md是一个活文档。它必须随着项目成长而成长。

• 设立更新触发器：
  • 技术栈升级：从React 17升级到18，从Webpack迁移到Vite，必须更新。
  • 新增核心工具/组件：封装了一个好用的usePaginationHook，或者引入了一个新的UI库，必须更新。
  • 踩了“AI坑”：当AI因为不了解某个上下文而反复生成错误代码时，这就是更新CLAUDE.md的最佳时机。把这次踩坑得到的经验固化下来。
• 版本化与回顾：在重要的项目里程碑，可以回顾一下CLAUDE.md，看看哪些规则已经过时，哪些新的最佳实践需要加入。

5.3 处理AI的“遗忘”与“固执”

即使有了CLAUDE.md，AI有时也会“忘记”规则或表现出奇怪的“固执”。

• “遗忘”时：温和地提醒它。例如：“请参考我们CLAUDE.md第3.2节关于HTTP客户端的规定，这里应该使用apiClient而不是fetch。” 通常它会立刻纠正。
• “固执”时：如果AI坚持一个错误的模式，尝试重启会话。新的会话会重新读取CLAUDE.md，往往能解决问题。也可以检查你的描述是否有歧义。
• 终极武器：示例的力量：对于AI难以理解的复杂模式，在CLAUDE.md中提供一个完整的、可运行的代码示例，比千言万语的描述都管用。比如展示一个“标准的数据列表页组件”的完整代码，AI会更好地模仿。

5.4 与现有工具链的集成

不要让你的CLAUDE.md成为孤岛。它应该与你现有的开发工具链协同工作。

• ESLint / Prettier：CLAUDE.md中的风格规则应该与这些工具的配置保持一致。AI生成符合CLAUDE.md的代码，提交前用ESLint/Prettier自动格式化，形成一个完美闭环。
• TypeScript / JSDoc：鼓励AI生成强类型的代码和完整的JSDoc注释，这不仅能提升代码质量，其注释本身也能成为AI理解代码上下文的重要来源。
• Git Hooks：你甚至可以创建一个Git预提交钩子（pre-commit hook），检查AI生成的新代码是否明显违反了CLAUDE.md中的核心禁令（比如是否误用了禁止的库）。

5.5 度量与反馈：如何知道它真的有用？

最后，你需要一些方法来评估CLAUDE.md的投资回报率。

• 主观感受：你和你的团队是否感觉和AI协作更顺畅了？需要手动纠正AI代码的次数是否显著下降？
• 客观指标（如果可能）：
  • 代码审查评论减少：针对“风格不一致”、“用了错误的技术栈”这类问题的评论是否变少了？
  • AI生成代码的接受率：直接使用AI生成的代码块而不修改的比例是否提高了？
  • 任务完成速度：对于熟悉的功能模块，从描述到获得可用的初版代码的时间是否缩短了？

我个人最深的体会是，自从系统化地使用CLAUDE.md后，最大的变化不是AI犯的错变少了，而是沟通成本急剧降低。我不再需要反复地向AI解释“我们项目里是怎么做的”，而是可以直奔主题，讨论更深层次的逻辑和架构问题。它从一个需要我不断纠正的“实习生”，变成了一个能理解项目语境、可以并肩作战的“同事”。这个转变，才是CLAUDE.md这类“技能文件”带来的真正价值。它不是在约束AI，而是在赋能它，最终赋能的是我们开发者自己。