企业官网建设流程全解析

1. 项目概述：Vibe Project，一个为AI时代重构的开发起点

如果你和我一样，在过去一年里深度使用了Claude Code、Cursor或者GitHub Copilot，那你一定经历过这种“冰火两重天”的体验：一方面，AI助手确实能帮你快速生成代码片段，解决一些琐碎问题；但另一方面，当你试图让它理解一个复杂的企业级项目上下文、遵循特定的代码规范、或者完成一个需要多步协作的任务时，它给出的答案往往南辕北辙，甚至会把项目结构搞得一团糟。问题的核心在于，AI Agent缺乏一个稳定、一致且富含信息的“工作环境”。我们开发者有IDE配置、有项目文档、有团队约定，但AI每次对话都像一张白纸，需要我们反复进行“上下文灌输”。

这就是Vibe Project要解决的根本问题。它不是一个框架，也不是一个库，而是一个专为与AI Agent协同工作而设计的、企业级开发环境模板。你可以把它理解为一个“AI就绪”的项目脚手架。它的核心思想是“Vibe Coding”——将开发者的意图（Vibe）与AI强大的实现能力相结合，通过一套标准化的环境配置（包括项目结构、编码规则、上下文文档和自动化流程），让AI从项目伊始就能在正确的轨道上运行，从而将协作效率最大化。

简单来说，使用Vibe Project，你相当于为你的AI伙伴配备了一份详尽的“新员工入职手册”和一个“标准化工具箱”。无论是启动一个全新的TypeScript后端服务，还是一个Python数据管道，你都可以基于这个模板快速初始化，并确保Claude、Cursor等AI工具从一开始就理解你的技术栈、架构决策和代码风格，生成出符合预期的、高质量的代码。这对于追求代码一致性、可维护性的团队，以及希望将AI深度集成到开发流程中的个人开发者而言，价值巨大。

2. 核心设计理念与架构解析

2.1 “Vibe Coding”方法论：从意图到实现的桥梁

“Vibe Coding”这个词听起来有点玄乎，但其内核非常务实。它描述了一种新的开发范式：开发者专注于定义“做什么”（业务逻辑、架构设计、接口规范），而将“怎么做”（具体的代码实现、样板代码编写、错误处理）更多地委托给AI。然而，这种委托不是无条件的，它需要一个强大的“约束系统”来保证输出的质量。

Vibe Project构建了这个约束系统，它基于以下几个关键设计原则：

1. 显式化的上下文管理：传统项目文档是给人看的，而Vibe Project要求将文档“AI化”。这意味着所有关键信息——项目目标、技术栈选择理由、目录结构含义、编码规范、甚至团队偏好——都必须以结构清晰、易于AI解析的格式（如Markdown）存放在固定位置（.agent/目录）。这确保了AI在任何时候都能获取到一致的背景信息。
2. 规则驱动的代码生成：不同的AI工具有不同的配置方式。Vibe Project为Claude Code、Cursor、Roo Code等主流工具提供了预配置的规则文件（如CLAUDE.md,.cursor/rules/*.mdc）。这些规则不是简单的提示词，而是包含了项目特定的指令集，例如：“所有API响应必须使用统一的包装器”、“错误处理必须使用项目定义的AppError类”、“数据库查询必须通过Repository层”。AI在生成代码时会主动遵循这些规则。
3. 流程的自动化内嵌：质量保障不应是事后检查，而应融入开发流程的每一步。模板预置了Git Hooks（通过Husky）、Pre-commit检查、CI/CD流水线。当AI生成代码后，这些自动化工具会立即进行 linting、格式化、基础测试甚至安全扫描，提供即时反馈，形成“AI生成 -> 自动检查 -> 开发者审核”的闭环。
4. 基于Clean Architecture的示例：模板提供的TypeScript和Python示例项目都采用了Clean Architecture（干净架构）。这并非偶然，而是因为这种强调依赖关系、关注点分离的架构模式，其层次和边界非常清晰，特别适合用自然语言向AI描述（“请在use_cases目录下创建一个处理用户注册的用例”），也更容易被AI理解和正确实现。

2.2 项目结构深度解读：每一部分为何如此设计

Vibe Project的目录结构是其设计思想的直观体现。我们来逐一拆解核心目录的用意：

vibe-project-template/ ├── 🤖 AI Agent 설정/ # 不同AI工具的“驱动程序” ├── 📂 .agent/ # AI的“大脑”与“知识库” ├── 📂 .github/ # 团队协作与自动化“中枢” ├── 📂 .vscode/ # 统一开发体验“控制台” ├── 📂 docs/ # 面向人与AI的“双重文档” └── 📂 examples/ # 可运行的“设计蓝图”

• AI Agent 설정(AI Agent配置)：这是与具体AI工具交互的接口层。CLAUDE.md是给Claude Code的“总说明书”；.cursor/rules/下的.mdc文件是Cursor的“行为准则”。你应该根据团队主要使用的AI工具，优先完善对应的配置文件。例如，在CLAUDE.md中，你可以用非常直白的语言写明：“本项目的首要原则是类型安全，任何any类型的使用都必须经过显式注释和批准。”
• .agent/目录：这是整个模板的灵魂，是AI的专属工作区。
  • context.md: 项目全景图。应包含项目简介、核心价值、用户故事、非功能性需求（性能、安全目标）。这是AI理解项目“为什么存在”的起点。
  • architecture.md: 技术蓝图。详细说明采用的架构（如Clean Architecture），包含清晰的依赖关系图（用文字描述）、各层（Entities, Use Cases, Interfaces等）的职责，以及核心的数据流。
  • conventions.md: 代码宪法。这里要极其详细：命名规范（函数用驼峰还是下划线？）、文件组织规则、注释要求（是否需要JSDoc/类型注解？）、导入语句顺序、错误处理模式等。越细致，AI生成的代码风格就越统一。
  • prompts/: 可复用的“技能包”。将常用的复杂任务模板化，如“进行安全代码审查”、“为这个类生成单元测试”。这能保证每次执行同类任务的质量稳定性。
  • skills/和subagents/: 用于定义更复杂的AI行为，可以指示AI在特定场景下扮演特定角色（如“安全专家”、“数据库优化顾问”），进行更深度的专项分析。
• .github/目录：定义了项目的协作规则和质量门禁。预置的12个工作流（Workflows）覆盖了从代码提交、PR审查到安全扫描、自动发布的完整CI/CD链条。特别是“Claude PR Review”工作流，能自动调用AI对PR进行代码审查，是“人机协同评审”的实践。
• .vscode/目录：确保团队每个成员（包括AI，如果它基于VS Code）都使用相同的编辑器设置、扩展和代码片段，消除环境差异导致的“在我机器上是好的”问题。
• examples/目录：这不是简单的Demo，而是最佳实践的参考实现。当你不知道如何向AI描述“Clean Architecture在Python中具体怎么写”时，可以直接让AI参考examples/python-api/里的代码。这是“演示胜过千言万语”的绝佳实践。

实操心得：不要试图一次性完善所有文件。正确的做法是：1) 基于模板创建新项目；2) 立即根据你的第一个需求修改.agent/context.md和conventions.md；3) 在开发第一个功能时，同步更新architecture.md和相关的prompts。让文档与代码共同演进，而不是负担。

3. 从零开始：初始化与个性化配置实战

3.1 环境准备与模板克隆

开始之前，你需要确保本地有Git，并且拥有一个GitHub账号。Node.js或Python环境取决于你选择哪个示例项目，初期非必须。

创建你的项目仓库是最关键的一步。强烈推荐使用GitHub的“Use this template”功能，而不是直接Fork。因为Fork会保留与原模板仓库的关联，而“Use this template”会创建一个完全独立的新仓库，干净利落。

# 方法一：使用GitHub CLI（最快最推荐） # 首先安装GitHub CLI并登录 (gh auth login) gh repo create my-awesome-service --template jhl-labs/vibe-project --clone --private cd my-awesome-service

执行上述命令后，你就拥有了一个名为my-awesome-service的私有仓库，其初始内容与Vibe Project模板完全一致，但历史记录是全新的。

3.2 运行初始化脚本：交互式定制你的项目

进入项目根目录，你会看到一个关键的脚本：scripts/init-project.sh。运行它，这是你第一次与项目“对话”进行定制。

# 给予执行权限（首次运行） chmod +x ./scripts/init-project.sh # 运行初始化向导 ./scripts/init-project.sh

这个交互式脚本会引导你完成以下几件事，请认真对待每一步：

1. 输入项目元信息：项目名称、描述、作者等。这些信息会被自动填充到package.json、pyproject.toml、README.md以及.agent/context.md的头部。这里输入的名称和描述，将是AI理解你项目的第一印象。
2. 选择主AI Agent：让你在Claude、Cursor、Roo等中选择一个作为主要协作对象。脚本会根据你的选择，启用或高亮对应的配置文件。例如，如果你主要用Cursor，它会确保.cursor/rules/目录下的规则文件就位。
3. 选择示例项目：询问你是否要初始化一个示例项目（TypeScript API 或 Python API）。对于新手，我强烈建议选择“是”。这会将examples/下的对应项目代码复制到项目根目录，并安装好依赖。这是一个立即可运行的、遵循了所有模板约定的起点，价值远超一个空文件夹。
4. 配置MCP（可选）：Model Context Protocol是Anthropic推出的一种让AI模型安全访问外部工具和数据源的协议。如果你计划让Claude访问内部数据库文档、Jira API等，可以在此进行初步设置。初期可以跳过。

初始化完成后，你的项目目录已经从一个通用模板，转变为一个为你量身定制的、包含可运行代码的起点了。

3.3 核心配置文件的个性化改造

初始化脚本做了基础工作，但要让AI真正成为你的“灵魂搭档”，你必须亲手打磨几个核心配置文件。这是最关键的一步。

首先，编辑.agent/context.md。打开这个文件，把里面通用的描述替换成你项目的真实情况。例如：

# 项目上下文：电商订单履约中心 ## 核心目标 构建一个高可靠、可扩展的微服务，负责处理从用户支付成功到商品出库的全部履约流程，日均处理订单目标100万笔。 ## 核心用户故事 1. 作为订单系统，我需要调用履约中心API创建履约任务，并实时获取状态。 2. 作为仓库管理系统，我需要接收履约中心下发的拣货、打包指令。 3. 作为客服人员，我需要查询任意订单的详细履约路径和异常原因。 ## 技术栈选型理由 - **核心语言：TypeScript**：团队熟悉，类型系统有助于在复杂业务流程中减少运行时错误。 - **Web框架：NestJS**：内置的依赖注入、模块化设计完美契合Clean Architecture，且生态成熟。 - **数据库：PostgreSQL**：事务可靠性强，JSONB类型适合存储灵活的履约事件流。 - **消息队列：RabbitMQ**：用于与仓库系统等外部服务解耦，保证任务最终一致性。

接着，细化.agent/conventions.md。这里的规定越明确，AI的“发挥空间”就越可控。

## 代码风格 - **命名**：变量/函数使用 camelCase，类使用 PascalCase，常量使用 UPPER_SNAKE_CASE。 - **类型**：禁止使用 `any`。所有函数参数和返回值必须有显式类型。使用 `unknown` 替代 `any` 进行类型安全转换。 - **错误处理**：所有业务错误必须抛出 `AppError` 类的实例（参见 `src/common/errors/app-error.ts`）。HTTP控制器层负责捕获并转换为标准错误响应。 - **异步操作**：统一使用 `async/await`，禁止使用 `.then().catch()` 链式语法。 - **导入顺序**：1. 第三方库，2. 内部模块，3. 相对路径导入。每组之间空一行。

然后，配置你的主AI工具规则。如果你用Cursor，编辑.cursor/rules/general.mdc：

- 当你为这个项目生成或修改代码时，请始终遵循 `/agent/conventions.md` 中的规范。 - 项目采用Clean Architecture。请确保： - 业务逻辑只存在于 `use-cases/` 和 `entities/` 目录。 - 外部依赖（如数据库、API客户端）必须通过 `interfaces/` 中的接口定义，并在 `infrastructure/` 中实现。 - `presentation/` 层（如控制器）应非常薄，仅负责HTTP请求/响应转换。 - 在实现新功能前，请先询问是否需要更新 `architecture.md` 中的设计。

注意事项：不要把所有规则都堆在一个文件里。.cursor/rules/目录支持多个.mdc文件，你可以按领域拆分，例如database.mdc（数据库操作规则）、api.mdc（API设计规则），这样AI在处理特定任务时能更精准地应用规则。

4. 实战演练：与AI协作开发一个API端点

现在，让我们进入实战。假设我们基于TypeScript示例项目，需要添加一个“查询订单履约状态”的API端点。

第一步：为AI提供清晰的任务上下文。在IDE中（以Cursor为例），我直接打开AI聊天面板，输入：

请参考 .agent/context.md 和 .agent/architecture.md，在现有的Clean Architecture项目中，实现一个查询订单履约状态的API端点。 需求详情： - 路径：GET /fulfillment/orders/:orderId/status - 需要从数据库（使用Prisma）中查询订单的当前状态和关键事件时间戳。 - 响应格式需遵循项目约定的统一包装格式：{ success: boolean, data: T, error?: string }。 - 请确保错误处理使用 AppError。 - 请先给出实现方案，包括需要修改或创建哪些文件，然后再生成代码。

第二步：审查AI的方案并引导。AI可能会回复一个方案，例如创建GetOrderFulfillmentStatusUseCase、更新FulfillmentOrder实体、在FulfillmentController中添加新路由等。这时，你可以根据它的方案进行微调：

方案基本正确。但请注意： 1. 订单实体（Order）已经在 `src/domain/entities/order.entity.ts` 中存在，请直接使用，无需新建。 2. 数据库查询逻辑应放在 `src/infrastructure/repositories/prisma-order.repository.ts` 中的 `findById` 方法里。如果该方法不存在，请先创建它。 3. 请先实现Prisma Repository中的 `findById` 方法，然后再实现Use Case和Controller。

第三步：分步生成并审查代码。你可以要求AI分步生成代码。例如，先让它生成Repository层的新方法。生成后，立即运行已有的测试（npm test）和lint检查（npm run lint），利用预置的自动化流程快速反馈。通过后，再继续生成Use Case和Controller的代码。

第四步：利用预置的Prompt模板进行代码审查。代码生成完毕后，不要直接提交。你可以使用模板提供的code-review.mdprompt进行AI自查。在Cursor中，可以这样引用：

请根据 .agent/prompts/code-review.md 中的审查清单，对刚生成的 `src/use-cases/get-order-fulfillment-status.use-case.ts` 文件进行审查，指出潜在问题。

AI会基于预设的审查要点（如边界条件、错误处理、架构符合度等）给出反馈。根据反馈进行修改，形成一个“AI生成 -> AI审查 -> 人工确认”的高质量循环。

第五步：提交与自动化流水线。当你使用git commit时，Husky会触发pre-commit钩子，自动运行代码格式化（Prettier）、lint检查（ESLint）和秘密信息扫描。这保证了提交到仓库的代码基本质量。随后，当你推送分支并创建Pull Request时，.github/workflows/下的CI流水线会被触发，运行完整的测试套件，而“Claude PR Review”工作流甚至会调用Claude AI对你的PR进行二次审查，生成评论。

实操心得：与AI协作的最佳模式是“飞行员与自动驾驶”。你是飞行员，掌握方向和最终决策；AI是自动驾驶，处理稳定的、规则明确的飞行操作（编写样板代码、实现既定逻辑、编写测试）。永远不要将架构设计、关键算法或核心业务逻辑的决策完全交给AI，你的角色是引导和审核。

5. 高级技巧与深度定制指南

5.1 构建你自己的Prompt库

模板提供了14个基础Prompt，但真正的威力在于你根据项目特定领域进行扩展。在.agent/prompts/目录下创建你自己的Prompt文件。

例如，为电商项目创建一个prompts/calculate-shipping.md：

## 提示词：计算运费 **角色**：你是一名电商物流领域的专家。 **上下文**：本项目需要根据用户地址、商品重量和体积、配送时效要求计算运费。物流规则定义在 `src/domain/services/shipping-rules.service.ts` 中。 **任务**：请实现或修改运费计算逻辑。 **约束条件**： 1. 必须优先读取项目配置的“免邮门槛”和“首重价格”。 2. 必须支持“普通快递”、“次日达”、“隔日达”三种配送方式的价格计算。 3. 所有计算必须考虑货币单位（人民币），结果保留两位小数。 4. 必须编写对应的单元测试，覆盖：免邮情况、超重分段计价、不同配送方式、无效地址等边界案例。 **输出要求**：请先给出修改哪些文件的计划，然后生成具体的代码变更。对于复杂逻辑，请用注释说明计算步骤。

当需要修改运费逻辑时，你只需对AI说：“请参考.agent/prompts/calculate-shipping.md来优化我们的运费计算模块。” AI就会以专家的身份，在既定约束下工作。

5.2 利用MCP连接外部知识

对于企业项目，AI往往需要访问内部知识库、API文档或数据库Schema。通过配置MCP，你可以安全地将这些上下文提供给Claude等AI。

1. 复制并配置MCP设置：将.mcp.json.example复制为.mcp.json。
2. 添加Server：假设你有一个内部的Swagger API文档服务器，你可以添加一个“filesystem”或“http” server来让AI读取这些文档。

   { "mcpServers": { "internal-api-docs": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/path/to/your/api-docs"] } } }

3. 更新AI上下文：在CLAUDE.md或.agent/context.md中注明：“关于订单系统的详细API规范，请参考通过MCP连接的internal-api-docs。” 这样，当AI在处理相关任务时，就能主动查询这些外部文档，生成更准确的接口调用代码。

5.3 优化GitHub Actions工作流

模板预置了12个工作流，你可能不需要全部。根据项目阶段进行剪裁：

• 早期原型阶段：保留ci.yml（基础构建测试）和security-scan.yml即可，关闭deploy.yml等部署流程。
• 生产项目：需要仔细配置claude-pr-review.yml，设置合适的触发条件（如仅针对特定分支或文件路径），并为其分配足够的权限令牌。同时，可以启用issue-triage.yml，让AI自动为新增的Issue打标签（如bug、feature、documentation），提升项目管理效率。

一个常见的定制点是修改ci.yml中的测试矩阵。如果你的项目需要支持多版本Node.js/Python，可以这样配置：

jobs: test: strategy: matrix: node-version: [18.x, 20.x] os: [ubuntu-latest, windows-latest] runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - run: npm ci - run: npm test

这样可以确保代码在不同环境下都能正常运行。

6. 常见问题与故障排除实录

在实际使用Vibe Project模板的过程中，你可能会遇到一些典型问题。以下是我和社区成员踩过的一些坑及解决方案。

6.1 AI生成代码不符合架构规范

问题：AI在use-cases目录下直接导入了prisma客户端，违反了Clean Architecture的依赖规则（用例层不应依赖具体基础设施）。

根因：AI没有完全理解或“记住”架构图中各层的职责和依赖方向。

解决方案：

1. 强化规则：在.cursor/rules/architecture.mdc中明确写入：“绝对禁止在use-cases或domain/下的任何文件中导入@prisma/client或任何其他数据库驱动、外部服务SDK。所有外部依赖必须通过interfaces/中定义的抽象接口进行访问。”
2. 提供反面教材：在.agent/architecture.md中增加一个“反模式示例”章节，展示错误的导入方式，并解释其为何破坏架构。
3. 即时纠正与学习：当AI再次犯错时，不要直接修改代码，而是将错误代码和架构规则一起发给AI，要求它分析错误并给出修正方案。这个过程能强化AI对规则的理解。

6.2 预提交钩子（Husky）失败导致无法提交

问题：运行git commit时，pre-commit钩子执行失败（如lint错误），提交被阻止。

排查步骤：

1. 查看具体错误：终端会输出失败的命令和错误信息。最常见的是ESLint或Prettier格式问题。
2. 尝试自动修复：很多问题可以自动修复。在项目根目录运行：

   npm run lint:fix # 或对应的 `npm run format`

   然后再次尝试提交。
3. 检查新增文件：如果错误是关于未暂存的文件，可能是因为你新增了文件但未执行git add。将文件添加后重试。
4. 临时绕过（慎用）：如果只是临时需要提交一个中间状态（比如为了测试），可以使用git commit --no-verify跳过钩子。但切勿养成习惯，这破坏了质量门禁的初衷。

6.3 CI流水线在GitHub Actions中失败

问题：代码在本地测试通过，但推送到GitHub后CI运行失败。

排查思路：

一个实用技巧：在本地使用act工具（一个运行GitHub Actions的本地运行器）可以模拟CI环境，提前发现大部分环境差异导致的问题。

6.4 AI（如Claude）无法正确读取项目上下文

问题：在Claude Code中，AI似乎忽略了CLAUDE.md或.agent/目录下的内容，给出的回答很泛泛。

解决方案：

1. 确认文件位置和名称：确保CLAUDE.md文件位于项目根目录，并且名称完全正确（大小写敏感）。
2. 检查Claude Code会话：Claude Code有时会开启一个新的“会话”，新会话可能没有加载完整的项目上下文。尝试重启Claude Code，或者在对话中明确指令：“请完整阅读项目根目录下的CLAUDE.md文件以及.agent/目录中的所有文档，然后基于此上下文回答我的问题。”
3. 精简与结构化上下文：AI处理长文本时可能会丢失中间信息。确保你的CLAUDE.md和.agent/context.md结构清晰，使用标题、列表和加粗突出重点。将过于详细的规范移到conventions.md，在CLAUDE.md中只保留最高级别的指令和引用。
4. 使用@引用：在Claude Code中，你可以使用@符号直接引用特定文件的内容。例如：“@.agent/architecture.md请根据这份架构文档，设计一个用户注册模块。” 这能强制AI关注指定文件。

7. 效能衡量与持续演进

引入Vibe Project和AI协作流程后，如何衡量其效果？除了主观的“感觉更快了”，建议关注几个可量化的指标：

1. 样板代码编写时间：对比实现一个标准CRUD接口所需的时间。目标是大幅减少。
2. 代码审查往返次数：统计一个Pull Request从创建到合并，平均需要多少轮修改。AI生成的代码如果遵循了良好的规范，应该能减少因风格、基础错误导致的审查轮次。
3. 架构一致性违规次数：在CI流水线中，可以增加自定义的架构检查脚本（例如，检查use-cases目录是否引入了基础设施层的模块）。观察此类违规是否随着AI对规则熟悉而减少。
4. 开发者体验调查：定期向团队成员收集反馈，了解AI协作是增加了认知负担还是减少了重复劳动。

模板本身也需要随着团队技术和AI工具的发展而演进。定期（如每季度）回顾：

• .agent/prompts/中的提示词是否仍然有效？是否需要根据新的业务领域添加新的？
• .cursor/rules/等规则文件是否需要更新以适应新的最佳实践或框架版本？
• CI/CD流水线是否高效？有没有新的安全检查或测试工具可以集成？

Vibe Project不是一个一劳永逸的解决方案，而是一个需要与你团队共同成长的“活”的基础设施。它的最终目标，是让开发者能从繁琐的、重复性的编码劳动中解放出来，更专注于创造性的架构设计、复杂的业务逻辑和极致的用户体验。当你和你的AI伙伴在这个精心设计的“工作间”里配合无间时，那种流畅的“Vibe”便会自然涌现。