Project Genesis：AI编程助手项目脚手架框架，标准化开发流程

1. 项目概述：一个为AI编程助手设计的项目脚手架框架

如果你和我一样，经常使用Claude Code、Cursor这类AI编程助手来启动新项目，那你肯定也经历过那种“开局一张嘴，内容全靠编”的尴尬。每次新建一个项目，都得从头开始向AI解释：我们的技术栈是什么、代码规范怎么写、项目结构怎么安排、甚至CI/CD流程怎么配置。这个过程不仅重复，而且容易遗漏关键信息，导致AI生成的代码前后不一致，或者干脆跑偏。

Project Genesis Framework（项目创世框架）就是为了解决这个痛点而生的。它本质上是一个高度结构化、可复用的“项目启动清单”，专门设计给AI助手（尤其是Claude Code）使用。你不需要再在每次新项目开始时，手忙脚乱地组织语言，只需要把这个框架文档丢给Claude，它就会像一个经验丰富的技术负责人兼架构师，引导你走过从想法到可运行代码库的完整流程。

这个框架的核心价值在于“标准化”和“自动化”项目初始化。它预设了10个阶段（最新版已扩展到11个），覆盖了从产品需求探索、技术决策、项目脚手架搭建，到为AI助手配置专属开发工具和上下文的全部环节。最终，它会为你生成一个包含多达44个产物的完整项目基础，从战略文档到一行行可执行的配置代码，一应俱全。这特别适合独立开发者、小团队或者需要快速验证想法的场景，它能将项目冷启动的时间从几天压缩到几小时，并且确保产出物的质量基线。

2. 框架核心设计哲学与工作流拆解

2.1 “计划彻底，自信构建，持续迭代”的设计哲学

这个框架的基石是一句非常务实的原则：Plan thoroughly, build confidently, iterate continuously.（计划彻底，自信构建，持续迭代）。这听起来像是老生常谈，但框架通过具体的流程和产出物，将这句口号变成了可执行的步骤。

“计划彻底”体现在哪里？它强制你在写第一行代码之前，先完成Phase 0到Phase 2。Phase 0是一系列深入的“项目问诊”问题，覆盖产品、技术、流程和设计四个维度。比如，它会问你“核心用户是谁？他们最大的痛点是什么？”、“项目上线后，你如何衡量成功？”。这些问题逼迫你跳出技术细节，先想清楚商业和产品逻辑。紧接着的Phase 1会生成PRD（产品需求文档）、EDD（工程设计文档）和一个“约束与边界案例登记册”。这个登记册是我认为非常精妙的设计，它要求你提前识别并记录下所有已知的技术限制、业务规则的边界情况，这能极大减少开发后期因需求模糊导致的返工。

“自信构建”的支撑是什么？答案是Phase 3到Phase 5。框架不是给你一个空文件夹，而是生成一个完整的、生产就绪的项目脚手架（Monorepo结构）、服务样板代码、以及CI/CD工作流文件。更重要的是，它会生成一个名为CLAUDE.md的“AI开发主指南”。这个文件长达16个部分，详细规定了代码风格、提交规范、测试策略、部署流程等一切Claude需要遵守的规则。有了这个“宪法”，AI在生成代码时就有了明确的依据，开发者也能对产出的代码质量有基本的信心，因为规则是前置且一致的。

“持续迭代”如何保障？这通过Phase 6到Phase 10来实现。框架不仅生成静态配置，还创建了一套动态的“AI开发工具”。例如，它预设了多个“子代理”（Subagents），分别专注于前端、API、安全、文档等特定领域。当你在开发中遇到相应问题时，可以直接调用这些专家代理。同时，它还配置了诸如/commit、/update-docs这样的“斜杠命令”，让日常开发任务变得像聊天一样简单。Phase 9的MCP（模型上下文协议）配置，则将外部工具（如数据库、GitHub、云平台）的能力直接接入AI的工作流，使得迭代过程更加顺畅和自动化。

2.2 标准工作流：与AI协作的十一步舞曲

使用这个框架的流程极其简单，但每一步都设计得很有章法。下面是我根据官方指南和实践经验总结的标准操作流程：

1. 获取框架：首先，你需要获取Project_Genesis_Framework.md这个主文档。通常是从其GitHub仓库克隆或下载。
2. 启动对话：在一个新的Claude Code对话中，将整个框架文档作为附件上传或直接粘贴进去。
3. 输入启动提示：紧接着，粘贴框架提供的标准启动提示词，并在[Describe your project...]部分用一两句话描述你的项目想法。这个提示词的关键在于最后一句：“按阶段引导我完成框架。先问我那些摄入问题，然后按顺序生成每个产物。不要跳过任何阶段。” 这明确设定了AI的行为模式，防止它急于求成或自行跳过重要步骤。
4. 跟随引导：接下来，你只需要像回答一位资深产品经理和技术顾问的提问一样，与Claude互动。它会从Phase 0的问题开始，逐一询问。你的回答越详细，后续生成的产物就越精准。
5. 审查与微调：AI每生成一个产物（比如PRD初稿），你都需要仔细审查，并提出修改意见。这是一个协作过程，框架提供的是结构和问题，而具体的业务逻辑和细节需要你这位领域专家来填充和确认。
6. 进入下一阶段：确认当前阶段的产出物无误后，指示Claude进入下一个阶段。它会基于之前所有已确认的信息，生成下一批更具体的产物（如技术选型、数据库Schema）。
7. 最终验收：当所有11个阶段完成后，你会得到一个包含完整文档、配置、代码结构和AI工具链的项目仓库。此时，你可以运行Final Assembly阶段的验证脚本，检查所有必需文件是否就位。

注意：整个过程中，你扮演的是“决策者”和“领域专家”的角色，而Claude扮演的是“执行者”和“框架引导者”。不要指望AI能读懂你的心思，清晰、具体的沟通是成功的关键。例如，当被问到技术选型时，不要只说“用最新的”，而是说明“我们需要快速迭代，且团队熟悉React，因此前端选择Next.js；后端需要强类型和成熟生态，因此选择TypeScript + Node.js + Express”。

3. 核心产物深度解析：从战略到代码的完整链条

3.1 战略与设计文档：为项目奠定认知基线

很多人轻视文档，认为在敏捷开发中“可以工作的软件高于详尽的文档”。但Genesis框架认为，清晰、轻量级的文档是“可以工作的软件”的前提，尤其是在AI辅助开发中。AI没有上下文，文档就是它的上下文。

PRD与EDD：产品与工程的对话桥梁Phase 1生成的PRD和EDD，并不是几十页的Word文档，而是结构化的Markdown文件。PRD聚焦于“做什么”和“为什么”，通常包含：

• 问题陈述：我们要解决的核心痛点。
• 用户画像与场景：谁会用？在什么情况下用？
• 核心功能列表：用用户故事（User Story）的格式描述，如“作为用户，我可以…以便于…”。
• 非功能性需求：性能、安全性、可用性等方面的要求。

EDD则聚焦于“怎么做”，是PRD的技术回应，包含：

• 系统架构图：高层次组件及其关系。
• 技术选型理由：为什么选A而不选B？这里需要你给出有说服力的理由，AI会将其记录在案，供未来团队成员（包括未来的你）查阅。
• 数据流设计：关键业务数据如何在系统中流动。

约束与边界案例登记册：主动管理风险这是我最欣赏的一个设计。它要求你在项目伊始，就主动识别并记录下所有已知的“坑”。例如：

• “用户密码重置邮件必须在5分钟内发出，使用第三方服务SendGrid，需考虑其API速率限制和失败重试机制。”
• “支付回调接口必须处理重复通知和网络超时，保证幂等性。”
• “在欧盟地区，用户数据存储必须符合GDPR，因此用户表需要增加data_region字段和right_to_be_forgotten标记。”

这个登记册会随着项目进展不断更新，它不仅是开发 checklist，更是与AI沟通的绝佳上下文。当AI在编写相关代码时，你可以提醒它：“参考约束登记册第3条”，它就能理解背后的业务逻辑和风险点。

3.2 CLAUDE.md：AI开发者的“项目宪法”

如果说其他文档是给人看的，那么CLAUDE.md就是专门给AI看的“操作手册”或“项目宪法”。它的质量直接决定了AI协作的效率和代码质量。Genesis框架生成的CLAUDE.md通常包含以下核心章节：

1. 项目概览：快速回顾项目目标和技术栈。
2. 开发环境设置：如何安装依赖、设置环境变量、启动服务。
3. 代码风格与规范：缩进、命名约定（如变量用camelCase，组件用PascalCase）、导入顺序、文件组织规则。
4. 提交信息规范：强制使用Conventional Commits格式（如feat(auth): add login with OAuth），并可能链接到自动生成CHANGELOG的脚本。
5. 测试策略：单元测试、集成测试、E2E测试分别放在哪里，用什么框架（Jest, Cypress），覆盖率要求是多少。
6. API设计规范：RESTful端点命名规则、请求/响应格式、错误码定义。
7. 安全守则：SQL注入防护、XSS过滤、敏感信息（API密钥）处理规范。
8. 部署流程：如何构建、打包，部署到哪个环境（Staging/Production），回滚步骤。

一个具体的例子：在代码规范部分，它不会只说“保持代码整洁”，而是会明确规定：

## 代码规范 - **命名**：组件使用 `PascalCase`（如 `UserProfile.tsx`），工具函数使用 `camelCase`（如 `formatDate`）。 - **导入顺序**：1. 第三方库 2. 绝对路径别名导入 3. 相对路径导入。每组之间空一行。 - **React组件**：优先使用函数组件和Hooks。使用 `React.memo` 包装性能敏感的子组件。 - **错误处理**：所有异步操作必须使用 `try/catch` 包裹，并记录到Sentry（见环境变量 `NEXT_PUBLIC_SENTRY_DSN`）。

有了这样一份详尽的“宪法”，Claude在编写每一行代码时都有了明确的依据，极大减少了因风格不一致导致的代码审查返工。

3.3 子代理与斜杠命令：将AI能力模块化与场景化

这是Genesis框架将AI从“通用助手”转变为“专业团队”的关键。

子代理：你的专属专家团队框架预定义了多个标准子代理，每个都像一个专注于某个领域的工程师：

• api代理：当你需要创建新的REST端点或GraphQL resolver时，调用它。它会确保遵循项目定义的API规范，自动生成输入验证、错误处理和Swagger文档注释。
• security代理：在编写涉及用户输入、身份验证或数据处理的代码时，可以请它进行安全检查。它会提示你“这里需要参数校验”或“这个数据库查询有SQL注入风险，建议使用参数化查询”。
• docs代理：专门负责更新ARCHITECTURE.md或代码中的JSDoc注释。你完成一个功能模块后，可以让它为你生成或更新设计文档。

你还可以根据项目需求自定义代理。比如，做一个电商项目，你可以创建一个payment代理，它的知识库专门包含Stripe/Braintree的集成模式、处理退款、处理webhook的最佳实践。当需要处理支付相关逻辑时，直接召唤这位“支付专家”。

斜杠命令：提升日常开发效率这些命令将高频、格式化的操作封装成一键指令：

• /commit：分析你的代码变更，自动生成符合Conventional Commits规范的提交信息。你只需确认或微调即可。
• /update-docs：自动识别代码变动（如新增了API接口），并提示你更新哪些文档（README.md,API.md），甚至可以帮你起草更新内容。
• /deploy-check：在部署前运行，它会模拟检查环境变量是否齐全、数据库迁移是否就绪、测试是否通过等，给出一个部署准备度报告。

这些工具的意义在于，它们将开发者的意图（“我想提交代码”、“我想更新文档”）直接转化为精准、规范的动作，省去了中间繁琐的描述和格式调整时间。

4. 多智能体支持与MCP集成：构建开放的AI工具生态

4.1 Phase 11：打破AI助手的围墙花园

Genesis框架最初为Claude Code设计，但Phase 11的“多智能体支持”使其价值倍增。它意识到，开发者可能使用不同的AI编程工具（Cursor, GitHub Copilot, Windsurf等），每个工具都有其独特的配置方式和优势。与其为每个工具维护一套独立的配置，不如建立一个“单一事实来源”。

核心创新：UNIVERSAL_SPEC.mdPhase 11会在项目根目录创建一个core/UNIVERSAL_SPEC.md文件。这个文件用一种中立的、人类可读的格式，定义了项目的所有元信息：技术栈、代码规范、项目结构、工作流等。它不依赖于任何特定的AI工具语法。

适配器模式：翻译官的角色然后，框架为每个支持的AI工具（Cursor, Copilot, Windsurf, Aider等）生成一个“适配器”文件，存放在adapters/[agent-name]/目录下。这个适配器的唯一职责，就是将UNIVERSAL_SPEC.md中的通用规则，“翻译”成该AI工具能理解的原生配置格式。

例如：

• 对于Cursor，适配器会生成一系列.cursor/rules/*.mdc文件，每个文件对应一个特定的编码规则或上下文范围。
• 对于GitHub Copilot，适配器会生成.github/copilot-instructions.md，这是一个供Copilot读取的集中式指令文件。
• 对于Aider，适配器会生成.aider.conf.yml和一个CONVENTIONS.md文件，指导Aider如何进行代码变更和提交。

这种做法带来了巨大的灵活性。你可以用Claude Code做宏观设计和文档生成，用Cursor进行深度代码编辑和重构，用Copilot在IDE里获得行级代码补全。所有工具都基于同一套项目规范工作，确保了体验的一致性。

4.2 MCP配置：为AI插上连接现实世界的翅膀

MCP（Model Context Protocol）是Anthropic推出的一种协议，允许AI模型安全、结构化地访问外部工具和数据源。Genesis框架的Phase 9详细规划了如何为项目集成MCP。

MCP的价值：没有MCP，AI助手就像一个与世隔绝的智者，它只能基于你提供的文本和代码进行推理。有了MCP，它可以：

• 通过filesystemMCP直接读写项目文件，无需你手动复制粘贴。
• 通过githubMCP查看issue、拉取代码、甚至创建PR。
• 通过postgresMCP查询数据库当前状态，帮你调试数据问题。
• 通过fetchMCP调用外部API，获取实时数据。

框架的实践：Genesis框架不仅列出可用的MCP，还为每个推荐的MCP提供了“使用场景”和“配置示例”。例如，对于线性（linear）MCP：

• 何时使用：当你在进行冲刺计划、需要创建或更新任务时。
• 配置示例：它会提供一个mcp-config.json的代码片段，展示如何配置API密钥和默认团队ID。
• 触发场景：“Claude，查看我们当前冲刺中状态为‘进行中’的任务。” 配置了MCP后，Claude可以直接调用Linear API并返回结果。

框架按技术栈对MCP进行了分类（核心、数据库、Web、移动端、云、领域），这帮助开发者根据项目类型快速选取必要的工具。对于一个全栈Web应用，你可能会配置github、postgres、playwright（用于E2E测试）和vercel（用于部署）这几个MCP，从而让AI助手具备从代码管理、数据操作、测试到部署的全流程辅助能力。

5. 实战应用：以构建一个SaaS Web应用为例

让我们以一个具体的场景——构建一个B2B SaaS Web应用（技术栈：Next.js + Postgres + Vercel）为例，走一遍Genesis框架的核心应用流程，看看它如何落地。

5.1 阶段0-2：从模糊想法到清晰蓝图

首先，我将框架文档和项目描述（“一个面向中小企业的内部任务管理SaaS，支持团队协作、任务看板和报告功能”）交给Claude。

Phase 0 - 项目问诊： Claude开始提问，这些问题非常关键：

• 产品维度：“你的核心用户是中小企业中的什么角色？（经理、普通员工）”、“与Asana或Trello相比，你的差异化优势是什么？”
• 技术维度：“你预计的初始用户规模是多少？这对数据库选型有何影响？”、“是否需要实时协作功能（如同时编辑）？这会影响你选择WebSocket还是长轮询。”
• 流程维度：“你计划采用怎样的发布节奏？（每周迭代？每月发布？）”、“代码管理和CI/CD工具有偏好吗？”
• 设计维度：“你有现有的设计系统或品牌规范吗？”、“对移动端适配的要求是什么？”

我的回答越具体，后续方向就越明确。我回答：“核心用户是团队经理和成员，差异化在于深度集成国内常用的办公软件（如钉钉）。初始用户预计1000团队以内。需要基础的通知实时性，但无需同时编辑。我们使用GitHub Actions做CI/CD，每周进行迭代。”

Phase 1 - 战略文档生成： 基于我的回答，Claude生成了PRD初稿。我审查并调整了用户故事，将“集成钉钉”作为第一个版本的核心亮点。在EDD中，Claude建议了Next.js (App Router) + Prisma + PostgreSQL的技术栈，并给出了理由：Next.js利于SEO和快速开发，Prisma提供类型安全的数据库访问。我同意了这一方案。

Phase 2 - 技术基础： Claude开始输出具体的技术决策文档和数据库Schema。Schema设计非常详细，包含了User、Team、Project、Task、Comment等表，并定义了关系（一对多、多对多）。它还生成了.env.example文件，列出了所有需要的环境变量，如DATABASE_URL、NEXTAUTH_SECRET、DINGTALK_APP_KEY等。

5.2 阶段3-5：搭建可运行的项目骨架

Phase 3 - 项目结构： Claude运行命令，创建了一个完整的Monorepo结构（使用Turborepo或Nx作为示例）。目录结构清晰：

packages/ ├── api/ (Next.js API routes + Prisma) ├── web/ (Next.js frontend) ├── ui/ (共享的React组件库) └── eslint-config/ (共享的代码规范配置)

它生成了docker-compose.yml用于本地启动PostgreSQL，package.json中预置了开发、构建、测试的脚本，以及GitHub Actions工作流文件，实现了在推送到main分支时自动运行测试并部署到Vercel的预览环境。

Phase 4 - CLAUDE.md： 生成了超过2000字的详细指南。其中特别针对我们的项目做了定制：

• 在“API设计规范”中，规定所有API路由放在/packages/api/app/api/下，遵循RESTful风格，并使用zod进行请求验证。
• 在“安全守则”中，强调所有用户输入必须经过zod校验，密码必须使用bcrypt哈希存储，环境变量必须通过@t3-oss/env-nextjs进行类型安全加载。
• 在“测试策略”中，规定前端用Vitest和Testing Library，API用Jest和Supertest，E2E用Playwright。

Phase 5 - 活文档： 生成了ARCHITECTURE.md，用文字和图（Mermaid格式，但根据要求我们这里不展示）描述了前后端数据流。CHANGELOG.md和PROJECT_STATUS.md模板也已就位，后者连接到了一个简单的仪表板想法，用于追踪功能完成度。

5.3 阶段6-10：注入AI超级能力

Phase 6 & 7 - 插件与斜杠命令： Claude为我们的SaaS项目创建了自定义插件。例如，一个dingtalk-integration插件，里面包含了钉钉API授权、消息卡片构建、回调处理的最佳实践代码片段。斜杠命令/new-endpoint被配置为：当触发时，会自动在正确位置创建API文件，并插入包含验证、错误处理和基础Swagger注释的样板代码。

Phase 8 - 子代理： 除了标准代理，我们创建了一个reporting子代理。它的知识库专门关于如何用Chart.js或Recharts构建数据可视化，如何高效聚合数据库中的任务数据以生成团队效率报告。

Phase 9 - MCP配置： 在mcp-config.json中，我们配置了：

• github：用于管理issue和PR。
• postgres：允许Claude直接运行查询，验证数据模型或调试。
• vercel：让Claude可以查看部署状态或触发重新部署。
• linear：将项目管理和开发流程连接起来。

Phase 10 - 最终组装： Claude运行一个验证脚本，检查所有44个预设产物是否已生成并位置正确。最后，它生成了一个“第一个提示词模板”：

我现在已经完成了项目Genesis初始化。项目是一个基于Next.js + Prisma + PostgreSQL的任务管理SaaS，需要集成钉钉。 请基于已生成的`CLAUDE.md`和架构文档，开始实现用户认证模块。首先，请使用NextAuth.js配置基于邮箱/密码和钉钉OAuth的登录。请遵循项目的代码规范和安全守则。

至此，一个功能齐全、文档完备、AI就绪的项目脚手架已经搭建完毕，我可以立刻基于这个高质量的基础开始编码。

6. 注意事项、常见问题与避坑指南

在实际使用Genesis框架和类似AI辅助开发流程中，我积累了一些重要的心得和踩过的坑，希望能帮助你更顺畅地使用。

6.1 关键注意事项：人与AI的权责划分

1. 你始终是负责人，AI是执行者：框架再强大，AI也只是工具。最重要的技术决策、业务逻辑判断和最终的质量把关必须由你完成。不要盲目接受AI的第一个方案，尤其是涉及架构选型和安全问题时。多问“为什么选择这个？”。
2. 细节决定成败：在回答Phase 0的问题时，尽可能具体。“需要高性能”是模糊的，“需要支持100个并发用户，API响应时间P95 < 200ms”是具体的。具体的输入才能产生具体、可用的输出。
3. 定期更新“活文档”：ARCHITECTURE.md和CLAUDE.md不是一次性产物。当你在开发过程中做出重大调整（比如换了状态管理库），一定要及时更新这些文档。否则，AI和未来的你都会基于过时的上下文工作，导致混乱。
4. 子代理和MCP的配置要适度：不要一开始就配置所有MCP和创建大量子代理。根据项目实际需要逐步添加。过多的配置会增加维护成本，也可能在AI的上下文窗口中挤占更重要的项目代码信息。

6.2 常见问题与排查技巧

Q1：AI生成的代码或配置有错误怎么办？A：这非常常见。首先，不要慌张。检查错误信息，并回溯到生成该代码的上下文。通常有两个原因：一是你之前的描述有歧义，二是AI对某个库的最新API不熟悉。解决方法：1) 向AI清晰地指出错误，并提供错误日志；2) 如果涉及外部库，可以提示AI“请参考[库名]官方文档的最新版本”；3) 对于复杂逻辑，可以要求AI“分步实现，并解释每一步的目的”，这样更容易定位问题。

Q2：框架流程太死板，我想跳过某个阶段可以吗？A：框架的流程是建议性的最佳实践，但你有绝对控制权。如果你对某个领域非常熟悉（比如你已经决定了要用特定的云服务），你可以直接告诉Claude：“我们跳过Phase 2中关于云服务选型的部分，直接使用AWS。请基于这个决定继续后续阶段。” 框架的价值在于提供 checklist，而不是束缚你。

Q3：在多智能体环境下，如何保持配置同步？A：这是Phase 11要解决的核心问题。务必以core/UNIVERSAL_SPEC.md为唯一真相源。当你修改项目规范时（比如改变了代码缩进规则），只修改这个文件。然后，运行框架提供的（或自己编写的）适配器生成脚本，重新为各个AI工具生成原生配置。可以把这个脚本加入到package.json的postinstall或husky的pre-commit钩子中，确保配置自动同步。

Q4：生成的CLAUDE.md过于冗长，影响AI上下文窗口怎么办？A：这是一个有效的担忧。解决方案是模块化。不要把所有内容堆在一个文件里。可以将CLAUDE.md作为索引，将详细规范拆分到不同文件：

• docs/conventions/code-style.md
• docs/conventions/api-guide.md
• docs/conventions/git-workflow.md然后在CLAUDE.md中用简短摘要和链接引用它们。同时，利用AI工具的“范围化”配置功能（如Cursor的.cursor/rules），将只在特定目录下生效的规则放在对应的子规则文件中，减少主上下文的负载。

Q5：如何评估这个框架带来的实际效率提升？A：不要只看启动时间。建立一个简单的度量标准：对比使用框架前后，在实现一个标准功能（如“用户注册登录”）时，你所花费的“沟通成本”（向AI解释需求、纠正偏差的次数）和“返工成本”（因规范不明导致的代码重构）。通常，前期投入的几小时在框架配置上，会在第一个核心功能开发中就能收回成本，因为AI一次生成正确的概率大大提高了。