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构建了这个约束系统它基于以下几个关键设计原则显式化的上下文管理传统项目文档是给人看的而Vibe Project要求将文档“AI化”。这意味着所有关键信息——项目目标、技术栈选择理由、目录结构含义、编码规范、甚至团队偏好——都必须以结构清晰、易于AI解析的格式如Markdown存放在固定位置.agent/目录。这确保了AI在任何时候都能获取到一致的背景信息。规则驱动的代码生成不同的AI工具有不同的配置方式。Vibe Project为Claude Code、Cursor、Roo Code等主流工具提供了预配置的规则文件如CLAUDE.md,.cursor/rules/*.mdc。这些规则不是简单的提示词而是包含了项目特定的指令集例如“所有API响应必须使用统一的包装器”、“错误处理必须使用项目定义的AppError类”、“数据库查询必须通过Repository层”。AI在生成代码时会主动遵循这些规则。流程的自动化内嵌质量保障不应是事后检查而应融入开发流程的每一步。模板预置了Git Hooks通过Husky、Pre-commit检查、CI/CD流水线。当AI生成代码后这些自动化工具会立即进行 linting、格式化、基础测试甚至安全扫描提供即时反馈形成“AI生成 - 自动检查 - 开发者审核”的闭环。基于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.md3) 在开发第一个功能时同步更新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这个交互式脚本会引导你完成以下几件事请认真对待每一步输入项目元信息项目名称、描述、作者等。这些信息会被自动填充到package.json、pyproject.toml、README.md以及.agent/context.md的头部。这里输入的名称和描述将是AI理解你项目的第一印象。选择主AI Agent让你在Claude、Cursor、Roo等中选择一个作为主要协作对象。脚本会根据你的选择启用或高亮对应的配置文件。例如如果你主要用Cursor它会确保.cursor/rules/目录下的规则文件就位。选择示例项目询问你是否要初始化一个示例项目TypeScript API 或 Python API。对于新手我强烈建议选择“是”。这会将examples/下的对应项目代码复制到项目根目录并安装好依赖。这是一个立即可运行的、遵循了所有模板约定的起点价值远超一个空文件夹。配置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.mdcAPI设计规则这样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。复制并配置MCP设置将.mcp.json.example复制为.mcp.json。添加Server假设你有一个内部的Swagger API文档服务器你可以添加一个“filesystem”或“http” server来让AI读取这些文档。{ mcpServers: { internal-api-docs: { command: npx, args: [modelcontextprotocol/server-filesystem, /path/to/your/api-docs] } } }更新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/checkoutv4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-nodev4 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没有完全理解或“记住”架构图中各层的职责和依赖方向。解决方案强化规则在.cursor/rules/architecture.mdc中明确写入“绝对禁止在use-cases或domain/下的任何文件中导入prisma/client或任何其他数据库驱动、外部服务SDK。所有外部依赖必须通过interfaces/中定义的抽象接口进行访问。”提供反面教材在.agent/architecture.md中增加一个“反模式示例”章节展示错误的导入方式并解释其为何破坏架构。即时纠正与学习当AI再次犯错时不要直接修改代码而是将错误代码和架构规则一起发给AI要求它分析错误并给出修正方案。这个过程能强化AI对规则的理解。6.2 预提交钩子Husky失败导致无法提交问题运行git commit时pre-commit钩子执行失败如lint错误提交被阻止。排查步骤查看具体错误终端会输出失败的命令和错误信息。最常见的是ESLint或Prettier格式问题。尝试自动修复很多问题可以自动修复。在项目根目录运行npm run lint:fix # 或对应的 npm run format然后再次尝试提交。检查新增文件如果错误是关于未暂存的文件可能是因为你新增了文件但未执行git add。将文件添加后重试。临时绕过慎用如果只是临时需要提交一个中间状态比如为了测试可以使用git commit --no-verify跳过钩子。但切勿养成习惯这破坏了质量门禁的初衷。6.3 CI流水线在GitHub Actions中失败问题代码在本地测试通过但推送到GitHub后CI运行失败。排查思路失败阶段可能原因解决方案Setup / Install1. 缓存依赖版本冲突。2. 操作系统环境差异如本地是macOSCI是Linux。1. 检查package-lock.json或poetry.lock是否已提交。2. 在CI配置中指定明确的环境版本如node-version: 20.x。3. 查看Actions日志的“Set up job”和“Install dependencies”步骤输出。Lint / FormatCI环境使用了更严格的规则或不同版本的lint工具。1. 确保本地和CI使用相同的lint/format命令和配置.eslintrc.js,.prettierrc。2. 在本地运行CI的完整命令npm run lint npm run format:check。Test1. 测试依赖外部服务数据库、API而CI环境没有。2. 测试是并行的存在资源竞争或状态污染。1. 使用内存数据库如SQLite或Docker容器为测试提供隔离环境。2. 确保测试是独立的不依赖全局状态。使用jest --runInBand顺序执行测试排查问题。Build构建脚本中引用了CI环境中不存在的路径或环境变量。1. 检查package.json中的build脚本。2. 确保所有必要的环境变量在GitHub仓库的Secrets或Actions Variables中已正确设置。一个实用技巧在本地使用act工具一个运行GitHub Actions的本地运行器可以模拟CI环境提前发现大部分环境差异导致的问题。6.4 AI如Claude无法正确读取项目上下文问题在Claude Code中AI似乎忽略了CLAUDE.md或.agent/目录下的内容给出的回答很泛泛。解决方案确认文件位置和名称确保CLAUDE.md文件位于项目根目录并且名称完全正确大小写敏感。检查Claude Code会话Claude Code有时会开启一个新的“会话”新会话可能没有加载完整的项目上下文。尝试重启Claude Code或者在对话中明确指令“请完整阅读项目根目录下的CLAUDE.md文件以及.agent/目录中的所有文档然后基于此上下文回答我的问题。”精简与结构化上下文AI处理长文本时可能会丢失中间信息。确保你的CLAUDE.md和.agent/context.md结构清晰使用标题、列表和加粗突出重点。将过于详细的规范移到conventions.md在CLAUDE.md中只保留最高级别的指令和引用。使用引用在Claude Code中你可以使用符号直接引用特定文件的内容。例如“.agent/architecture.md请根据这份架构文档设计一个用户注册模块。” 这能强制AI关注指定文件。7. 效能衡量与持续演进引入Vibe Project和AI协作流程后如何衡量其效果除了主观的“感觉更快了”建议关注几个可量化的指标样板代码编写时间对比实现一个标准CRUD接口所需的时间。目标是大幅减少。代码审查往返次数统计一个Pull Request从创建到合并平均需要多少轮修改。AI生成的代码如果遵循了良好的规范应该能减少因风格、基础错误导致的审查轮次。架构一致性违规次数在CI流水线中可以增加自定义的架构检查脚本例如检查use-cases目录是否引入了基础设施层的模块。观察此类违规是否随着AI对规则熟悉而减少。开发者体验调查定期向团队成员收集反馈了解AI协作是增加了认知负担还是减少了重复劳动。模板本身也需要随着团队技术和AI工具的发展而演进。定期如每季度回顾.agent/prompts/中的提示词是否仍然有效是否需要根据新的业务领域添加新的.cursor/rules/等规则文件是否需要更新以适应新的最佳实践或框架版本CI/CD流水线是否高效有没有新的安全检查或测试工具可以集成Vibe Project不是一个一劳永逸的解决方案而是一个需要与你团队共同成长的“活”的基础设施。它的最终目标是让开发者能从繁琐的、重复性的编码劳动中解放出来更专注于创造性的架构设计、复杂的业务逻辑和极致的用户体验。当你和你的AI伙伴在这个精心设计的“工作间”里配合无间时那种流畅的“Vibe”便会自然涌现。