1. 项目概述为什么我们需要“上下文优先”的AI工程框架如果你和我一样在过去一年里深度使用了 Cursor、GitHub Copilot 这类AI编程助手那你一定经历过这种“甜蜜的烦恼”项目初期AI助手仿佛是你肚子里的蛔虫理解你的意图生成高质量的代码。但随着项目文件越来越多架构越来越复杂你会发现AI开始“失忆”和“跑偏”。昨天刚定下的API设计规范今天它生成的代码就忘了明明要求用特定的状态管理库它却给你写了个全局变量。更头疼的是当你想让新加入的同事用AI快速上手项目时他们得到的建议往往与项目既定的技术栈和架构风格格格不入。这种问题在传统的软件工程里我们靠详尽的文档、清晰的代码规范和严格的Code Review来解决。但在AI驱动的开发流程中这些“上下文”信息是缺失的。AI模型就像一个记忆力短暂、且没有经过你项目“入职培训”的新人它只能基于当前打开的几个文件和聊天历史中的只言片语来“猜”你的意图。这就是所谓的“上下文漂移”和“知识流失”——项目的核心设计决策、产品约束和架构意图并没有被系统地、结构化地灌输给AI而是散落在无数个已经关闭的聊天会话里。gbm-labs/contextFirst这个项目正是为了解决这个痛点而生的。它不是一个新工具而是一套标准化的框架和思维模式我称之为“上下文优先”的AI工程。它的核心思想非常直接将文档视为AI必须遵循的最高优先级上下文。它通过一套预定义的规则文件和文档模板强制AI在动手写代码之前先去“阅读”并理解项目的架构蓝图、产品需求和设计规范。简单说它给你的AI助手套上了“缰绳”和“导航图”让它从凭感觉乱撞的“野马”变成目标明确、纪律严明的“战马”。这套框架尤其适合中小型团队、独立开发者或者任何希望将AI编程从“有趣的玩具”提升为“可靠的生产力工具”的工程师。它不限定技术栈你可以把它丢进你的Next.js项目、Python数据分析脚本或者Rust系统工具里立刻就能建立起一套与AI协同的、可重复、可审查的工程规范。2. 核心设计思路从临时对话到结构化协作在深入具体文件之前我们需要理解contextFirst背后的设计哲学。传统的AI编程交互是线性的、临时的你有一个想法打开聊天框输入一段提示词AI生成代码你复制粘贴。这个过程高度依赖你即时的、非结构化的语言描述能力并且每一次交互都是孤立的。contextFirst试图将这个过程升级为一个循环的、结构化的协作流程。我们可以把它想象成在AI和开发者之间引入了一个“产品经理”或“技术负责人”的角色。这个角色不直接写代码而是负责提问、澄清、记录和制定规则。具体来说它的设计围绕三个核心原则展开2.1 文档即单一可信源在传统开发中我们强调代码是单一可信源。但在AI辅助开发中代码可能被AI随时重构或生成其背后的“为什么”变得模糊。因此contextFirst将结构化的文档提升为新的单一可信源。这些文档不是事后补充的说明而是AI在行动前必须查询的“宪法”。它包含了项目愿景与范围我们为什么要做这个目标用户是谁核心价值是什么领域模型与数据架构核心业务实体是什么它们如何关联用什么数据库技术栈与架构决策为什么选React而不是Vue为什么用Tailwind CSSAPI设计遵循什么规范活动中的功能规格当前正在实现的功能其具体的验收标准、UI交互和边界条件是什么AI在生成或修改任何代码前都需要“意识”到这些文档的存在并确保其输出与文档内容一致。2.2 角色驱动的AI行为你有没有遇到过你希望AI帮你设计一个数据库Schema它却开始给你写前端组件contextFirst通过.cursorrules文件为AI定义了明确的“角色”和场景化的工作流。例如当项目缺少project-brief.md时AI自动扮演“需求分析师”通过一系列问题帮你梳理项目目标。当开始一个新功能时AI扮演“解决方案架构师”引导你定义功能规格并生成active-feature.md。在修改核心模块时AI扮演“安全工程师”或“QA”主动提醒可能引入的漏洞或违反的代码规范。这种角色化设定让AI的行为从“万能助手”转变为“专业顾问”交互更加聚焦和高效。2.3 防患于未然的治理AI生成代码的“概率性”本质意味着它可能写出看似能运行但实则埋下技术债务、安全漏洞或性能隐患的代码。contextFirst将治理前置。它的规则文件里可以内置检查点例如“在创建新的API路由时必须首先检查docs/api-design.md中的认证和版本规范。”“在修改数据库模型文件后必须同步更新docs/domain-model.md。”“生成任何包含用户输入处理的代码时必须引用docs/security-guidelines.md中的XSS防护规则。”这相当于为AI的“代码生成器”加装了一个“策略执行引擎”确保输出的代码不仅在语法上正确更在架构和合规层面符合项目要求。3. 框架核心文件深度解析理解了设计思路我们来看contextFirst框架具体由哪些文件构成以及如何配置它们。整个框架非常轻量核心就是两个部分一个规则文件和一个文档模板目录。3.1.cursorrulesAI的行为宪法这个文件是框架的“大脑”它是一个针对 Cursor 编辑器优化的系统级提示词文件。但它的思想可以迁移到任何支持自定义提示词的AI编码工具上。其内容结构通常包含以下几个部分1. 核心身份与使命声明这部分定义了AI的“人设”。它会明确告知AI“在本项目中你的首要职责是维护和遵循docs/目录下的结构化上下文。代码生成必须服务于文档中定义的目标和约束。” 这设定了交互的基本基调。2. 状态检测与角色切换逻辑这是实现“魔法”的关键。文件中会包含一系列条件判断逻辑。例如- 如果 docs/project-brief.md 不存在或内容为空则进入“项目初始化”模式。在此模式下你应扮演产品负责人/需求工程师通过一系列结构化问题目标用户、核心功能、技术选型来帮助用户填充该文档。在文档完成前拒绝生成业务代码。 - 如果 docs/active-feature.md 不存在但用户提出了一个类似“我们来添加用户登录功能”的请求则切换至“功能规划”模式。引导用户明确该功能的用户故事、验收标准、API端点设计等并生成 active-feature.md。 - 如果上述文档均完备则进入“实施”模式。在此模式下生成的所有代码必须显式引用 active-feature.md 中的具体需求点并遵守 docs/ 下所有相关架构规范。3. 具体的约束与检查规则这部分是具体的“交通法规”。它会列出针对本项目的一系列硬性要求例如“所有React组件必须使用函数式组件和Hooks禁止使用Class组件。”“所有数据库查询必须使用Prisma Client禁止手写原始SQL字符串拼接。”“所有API响应必须包裹在标准格式{ success: boolean, data: any, message: string }中。”“在创建新的工具函数时必须首先检查src/utils/目录下是否已存在类似功能的函数。”4. 交互协议定义了与用户沟通的方式。例如要求AI在做出重大代码变更建议前先提供简要的解决方案概述在生成代码后自动建议需要更新的相关文档部分。实操心得编写.cursorrules时最大的陷阱是写得过于冗长和复杂。AI对长提示词的理解会衰减。我的经验是分层递进动态加载。在.cursorrules中只定义最高层的角色和状态机逻辑将具体的技术栈规范如React规则、数据库规则拆分成独立的docs/code-style.md、docs/prisma-guide.md等文件。然后在规则中简单注明“在编写前端代码时请参阅docs/code-style.md”。这样既保持了核心规则的清晰又让具体约束易于维护。3.2docs/templates上下文的蓝图docs/目录下的模板文件定义了需要被结构化的上下文信息。contextFirst提供了一套开箱即用的模板你可以根据项目特点增删改。核心模板包括project-brief.md项目简报这是项目的“出生证明”。它不应该是一篇冗长的论述而是一个结构化的问卷答案集合。模板会引导你填写项目名称与一句话描述用于快速对齐认知。目标用户与核心痛点明确为谁解决什么问题。核心功能列表用 bullet points 列出 MVP 功能。非功能性需求如性能指标、安全性要求、浏览器兼容性等。技术栈选择与理由为什么用Next.js而不是Remix为什么选PlanetScale数据库简要记录关键决策。domain-model.md领域模型这是项目的“数据结构宪法”。它用文字或图表如Mermaid语法描述核心业务实体、它们的属性以及实体间的关系。例如对于一个博客系统这里会定义User、Post、Comment等实体并说明User可以有多篇PostPost可以有多条Comment。当AI需要生成Prisma Schema或GraphQL类型时这里就是权威依据。active-feature.md活跃功能规格这是当前开发任务的“作战地图”。它是动态的一次只聚焦一个功能。模板包含功能名称与关联用户故事例如“作为已登录用户我想能编辑我的个人资料以便更新我的头像和简介。”验收标准以“Given-When-Then”格式或简单的检查列表形式列出。这是AI生成测试用例的绝佳输入。API设计如果涉及接口定义端点、方法、请求/响应体格式。UI/UX 描述或线框图链接描述关键的页面状态和交互。待办事项列表由AI或开发者维护跟踪该功能下的具体开发任务。architecture-decisions.md架构决策记录记录所有重要的、有取舍的技术决策。例如“ADR-001选择Serverless Functions而非长期运行的后端服务理由成本优化、自动扩缩容。” 这能防止未来AI或新成员质疑“当初为什么这么选”。注意事项千万不要把模板填成“毕业论文”。这些文档的核心读者是AI和未来的你或队友目的是高效传递约束信息。用关键词、列表和短句代替长段落。保持简洁和可扫描性。例如在project-brief.md的“技术栈”部分直接写“前端Next.js 14 (App Router), Tailwind CSS。后端Next.js API Routes。数据库Supabase (PostgreSQL)。ORMPrisma。” 这就足够了。4. 实战工作流从零启动一个AI协同项目理论说得再多不如亲手操作一遍。让我们以一个真实的场景——“用Next.js 14和Supabase构建一个个人书签收藏应用”为例展示contextFirst的完整工作流。4.1 初始化项目与集成contextFirst首先创建你的项目目录并初始化Next.jsnpx create-next-applatest bookmark-app --typescript --tailwind --app cd bookmark-app接下来集成contextFirst。你不需要安装任何NPM包只需从gbm-labs/contextFirst仓库复制两个东西将.cursorrules文件复制到你的项目根目录。将整个docs/templates目录复制到你的项目根目录通常重命名为docs。现在用 Cursor 打开你的项目。关键一步来了确保.cursorrules文件在Cusror的上下文中。你可以通过 Cursor 的“Add File to Context”功能手动添加或者更简单的方法是在聊天框里输入/并选择“Load .cursorrules”。你会立刻感受到AI语气和行为的转变。4.2 阶段一AI引导的需求澄清与项目简报创建此时你的docs/目录下只有模板文件没有实际内容。AI根据.cursorrules检测到了这一点会自动进入“需求工程师”模式。你可以在 Cursor 聊天框输入“嗨我们来开始构建这个书签应用。” AI的回复将不再是直接给你代码而是会这样回应“我看到你正在启动一个新项目。为了确保后续开发符合你的预期我将首先帮你建立项目上下文。我发现docs/project-brief.md尚未定义。让我们先明确几个关键问题来填充它核心用户与价值这个应用主要是给你个人用还是打算分享给朋友解决的主要痛点是什么比如替代浏览器的混乱书签栏核心功能除了基本的添加、删除、查看书签你还需要分类/标签、搜索、网页快照预览、还是分享功能技术偏好你提到用Next.js和Supabase。对于前端状态管理有计划吗比如用Zustand还是直接使用React Context对于UI组件是打算全部手写还是使用像shadcn/ui这样的组件库请简单回答我会帮你整理成结构化的文档。”你回答“就我自己用想替换Chrome书签。需要能添加链接、打标签、按标签搜索和过滤。状态管理先用React Context吧UI用shadcn/ui组件库保持美观。”AI会回复“好的理解。我已经基于你的回答创建并更新了docs/project-brief.md。[文件已创建/更新docs/project-brief.md]接下来我们需要定义数据模型。我将创建docs/domain-model.md来描述书签Bookmark和标签Tag这两个核心实体以及它们的关系。你希望书签包含哪些字段除了标题、URL、标签还需要添加时间、描述或者图标吗”经过几轮这样高效的问答AI在几分钟内就帮你生成了结构清晰、包含关键决策的project-brief.md和domain-model.md。这个过程的价值在于它迫使你在写第一行代码前就思考清楚了项目的轮廓并且这些思考被永久地、结构化地记录了下来成为后续所有AI交互的基石。4.3 阶段二在明确上下文中进行功能开发现在docs/目录下有了基础上下文。你想开发第一个核心功能“添加书签”。 你在聊天框说“现在我们来实现添加书签的功能。”AI检测到docs/active-feature.md不存在会进入“功能规划”模式“让我们先规划‘添加书签’这个功能。我将初始化docs/active-feature.md。基于已有的领域模型我建议这个功能包含一个前端表单包含URL必填、标题自动从URL获取或手动输入、描述、标签输入或选择等字段。一个API端点POST /api/bookmarks用于接收表单数据并存入Supabase。表单验证前端和后端都需要验证URL格式。你同意这个范围吗或者有其他特定的UI交互要求比如弹出式对话框还是独立页面”你确认后AI会生成详细的active-feature.md包含用户故事、验收标准、API设计草图甚至一个简单的UI组件树描述。只有在这个文件就位后AI才会开始生成实现代码。它会说“功能规格已就绪。现在开始实施。首先我将创建表单组件components/bookmark-form.tsx它会使用shadcn/ui的Form、Input、Button组件并集成react-hook-form进行表单管理。同时创建app/api/bookmarks/route.ts作为API端点处理POST请求连接Supabase Client进行插入操作。代码将严格遵循docs/domain-model.md中定义的Bookmark数据模型。”接下来生成的代码其质量和对项目意图的贴合度将远高于没有上下文引导时生成的代码。因为AI的“大脑”里已经装满了这个项目的“规章制度”。4.4 阶段三基于上下文的代码审查与迭代当功能开发到一半你想让AI帮忙优化“获取书签列表”的API使其支持按标签过滤。 你输入“帮我修改获取书签的API让它能按标签过滤。”AI不会直接去改代码。它会首先“查阅”上下文“我看到了docs/active-feature.md中当前聚焦于‘添加书签’。你提到的‘按标签过滤’是一个新的需求点。为了保持上下文的一致性我建议我们有两种处理方式如果这是对‘添加书签’功能的补充我们可以更新当前的active-feature.md在验收标准中增加过滤需求。如果这是一个独立的功能比如‘搜索与过滤书签’我们可以先完成当前功能然后为其创建一个新的active-feature.md。你倾向于哪一种另外过滤的交互形式是什么是在列表页顶部有一个标签选择器吗”这种交互本质上是在引导你进行一次微型的、与AI协作的“需求管理”和“任务拆解”。它防止了需求蔓延和上下文混乱确保每一个代码变更都有据可依。5. 高级技巧与避坑指南在实际使用contextFirst几个月后我积累了一些能极大提升体验和效率的技巧也踩过一些坑。5.1 如何定制属于你自己的.cursorrules官方的.cursorrules是一个很好的起点但每个团队和项目的规范不同必须进行定制。技巧一注入团队特有的代码风格在规则文件中加入你们团队独有的约定。例如// .cursorrules 片段 - **命名规范** - React组件文件使用PascalCase如 BookmarkForm.tsx。 - 工具函数、hooks使用camelCase如 useBookmarkData.ts。 - 常量使用UPPER_SNAKE_CASE。 - **导入顺序**严格按照“React库 - 第三方库 - 内部组件 - 工具函数 - 类型定义”的顺序组织import语句。 - **错误处理**所有异步操作必须使用try-catch包裹错误信息通过Toast组件使用 sonner 库提示用户。这样AI生成的代码从一开始就符合你们的代码风格减少了后期调整的工作量。技巧二定义“危险操作”的确认机制对于可能产生严重后果的操作设置强制确认点。例如- 当用户请求执行“删除所有数据”、“清空数据库表”、“递归删除文件夹”等操作时你必须 1. 首先明确警告用户该操作的破坏性和不可逆性。 2. 其次要求用户提供明确的、全大写的确认指令如“我确认要清空users表”。 3. 最后在生成代码时必须添加额外的注释 // DANGER: This operation is irreversible。这为AI的“行动自由”加了一道安全锁。5.2 管理文档的活力与“文档债”最大的挑战之一是文档如何与代码同步更新。contextFirst的理想状态是文档驱动开发但现实是代码会不断演化。常见问题代码变了文档没更新。我的解决方案是将文档更新作为Code Review的强制项并利用AI自动化部分更新。在.cursorrules中增加规则“当生成或修改了与docs/domain-model.md中实体相关的代码如Prisma schema、API路由后必须在聊天中提醒我可能需要更新领域模型文档。”在完成一个功能分支的开发后在提交Pull Request前可以给AI一个指令“基于src/app/api/bookmarks/route.ts和src/components/bookmark-list.tsx的当前实现请检查并更新docs/active-feature.md中的API设计和组件描述使其与实际代码一致。” AI可以很好地完成这种对比和摘要工作。技巧使用“活文档”片段对于频繁变化的细节如API响应的具体字段不必在docs/里维护一份随时会过时的副本。可以在代码中通过JSDoc或特定格式的注释来定义然后让AI在需要时从中提取。例如在API路由文件中/** * openapi * /api/bookmarks: * get: * description: 获取书签列表支持按标签过滤。 * parameters: * - name: tag * in: query * required: false * schema: * type: string * responses: * 200: * description: 成功返回书签数组。 * content: * application/json: * schema: * type: array * items: * $ref: #/components/schemas/Bookmark */ export async function GET(request: Request) { ... }然后在.cursorrules中告诉AI“当需要向开发者解释API时优先从源代码中的openapi注释块提取信息。”5.3 应对AI的“规则规避”行为有时AI为了满足用户一个模糊的请求可能会尝试“走捷径”绕过你设定的规则。现象你要求“快速给我一个登录页面”AI可能直接生成一个使用本地状态和硬编码验证的组件完全无视你文档里定义的“必须使用Supabase Auth”和“表单需用react-hook-form”的规则。应对策略规则表述要具体、负面清单明确不要说“请使用好的实践”而要说“禁止使用useState管理表单必须使用react-hook-form库”、“禁止硬编码任何API密钥或密码”。在AI生成代码后养成“规则符合性检查”的习惯简单问一句AI“请对照docs/下的架构规范检查刚刚生成的代码是否有不符合的地方” AI通常能进行有效的自检。迭代你的规则如果发现AI在某个点上频繁违规说明你的规则可能模糊或缺失。把这个点作为一个明确的条款添加到.cursorrules中。5.4 在非Cursor环境中的应用contextFirst的理念是通用的。虽然.cursorrules是针对Cursor优化的但其核心——结构化文档驱动AI开发——可以应用到任何地方。在 GitHub Copilot Chat 中你可以将docs/project-brief.md和docs/active-feature.md的核心内容浓缩成一段提示词在开启一个新对话时首先发给Copilot为整个会话设定上下文。例如“在本会话中请遵循以下项目上下文[粘贴精简后的项目简报和当前功能规格]。所有代码建议必须符合此上下文。”在 Claude Code 或 ChatGPT 中你可以创建一个“上下文初始化”文本块包含所有关键文档的链接或摘要。在每次开始复杂的编码任务前先让AI“阅读”这个上下文块。核心思想是无论工具如何变化主动地、结构化地向AI灌输项目上下文是提升AI编码产出质量和一致性的不二法门。contextFirst提供了一套现成的、可操作的方法论和模板让你能立刻开始实践这种更先进的AI工程协作模式。它不是给开发套上枷锁而是为AI这匹快马装上精准的导航仪让你们能一起跑得更快、更稳、更远。