1. 项目概述当AI助手开始“失控”我们需要一个“导航员”如果你和我一样已经深度依赖像 Cursor、GitHub Copilot 这样的AI编程助手那你一定经历过这种“甜蜜的烦恼”项目初期AI助手聪明得像个天才能精准理解你的意图生成漂亮的代码。但随着项目规模扩大代码库越来越复杂你会发现AI开始“胡言乱语”——它可能忘记了三天前你定下的架构规范开始用你不喜欢的状态管理库或者在一个微服务项目里突然给单体应用写起了数据库连接池。更糟的是当你想让新加入的同事用AI快速上手时他们得到的是一堆风格混乱、架构矛盾的代码建议。这就是典型的“上下文漂移”Context Drift。AI的“记忆”是短暂且碎片化的它没有项目级的长期记忆能力。我们与AI的每一次对话都像是一次全新的邂逅它无法主动回忆起上一次对话中我们共同定下的那些重要决策。contextFirst这个框架就是为了解决这个问题而生的。它的核心理念很简单却非常有力将文档视为AI必须遵循的“上下文宪法”。它不是另一个让你手动写文档的工具。恰恰相反它的“魔法”在于它训练你的AI助手通过.cursorrules系统指令来扮演一个“需求工程师”或“解决方案架构师”的角色。当你提出一个模糊的需求时AI不会立刻开始编码而是会先“采访”你将你的口头描述自动转化为结构化的文档如项目简报、领域模型并将这些文档作为后续所有代码生成的绝对依据。这相当于给你的AI助手安装了一个“导航系统”确保它始终行驶在你设定的产品与架构路线上不会迷路或跑偏。2. 核心设计思路从“即兴对话”到“引导式工程”传统的AI编码是“即兴对话”模式你提问它回答你再追问它再补充。这个过程高度依赖你即时的、可能不完整的提示词缺乏系统性和可追溯性。contextFirst旨在将这种模式升级为“引导式工程”。2.1 核心问题拆解框架的设计直指AI辅助开发中的几个核心痛点上下文丢失与架构漂移AI没有项目级的持久化记忆。重要的架构决策为什么选GraphQL而非REST为什么用Zustand而不是Redux Toolkit如果只存在于某次聊天记录中那么下次对话或换一个AI会话时这些决策就消失了。AI会基于它当时看到的代码片段和你的新提示做出可能违背最初设计的决定。缺乏治理与审查AI生成代码是概率性的它可能会巧妙地绕过团队约定的代码规范、安全实践或性能要求。如果没有一个前置的检查机制低质量或不符合规范的代码就会悄无声息地进入代码库形成“技术债的按需生成”。角色与责任模糊在一个功能开发中谁负责向AI描述产品需求谁负责确保架构一致性是产品经理、开发者还是架构师通常这个责任是模糊的导致AI得到的指令不完整、有歧义。知识资产无法沉淀最有价值的讨论和决策过程都淹没在私人的、临时的聊天记录里。当项目交接、新人加入或需要复盘时这些知识无法被有效检索和继承。2.2 解决方案文档即上下文规则即守卫contextFirst的解决方案可以概括为两个核心原则文档即上下文Documentation as Context所有重要的非代码决策——产品目标、用户故事、架构图、API设计、数据模型、验收标准——都必须被结构化为Markdown文档存放在项目的docs/目录下。这些文档不是给人“看”的纪念品而是给AI“读”的强制性输入。规则即守卫Rules as Guards项目根目录下的.cursorrules文件是一个强大的系统提示词Prompt。它定义了AI在本次项目会话中必须扮演的角色如“首席解决方案架构师”并规定了硬性规则“在生成任何代码之前必须首先检查相关的docs/文档。如果文档缺失或过时必须引导用户先创建或更新文档。”这套机制建立了一个安全层。AI从被动的代码生成器转变为主动的、受约束的工程伙伴。它会在你跑偏时提醒你在你遗漏时提问你确保每一个代码块的产出都建立在坚实且已达成共识的文档基础之上。3. 框架核心组件详解与实操配置理解了理念我们来看看这个框架具体由什么构成。它极其轻量核心就是两个部分一个规则文件和一个文档模板目录。3.1.cursorrules定义AI的行为宪法这个文件是框架的大脑。它本质上是一个写给AI特别是Cursor编辑器看的、高度结构化的系统指令集。你需要把它放在项目的根目录。它的内容决定了AI如何与你互动。一个基础的.cursorrules文件可能包含以下部分# .cursorrules - Context-First Engineering Protocol **ROLE MISSION** You are the **Solution Architect** for this project. Your primary goal is to ensure all code generated aligns perfectly with the documented architectural intent and product requirements. You are guardrails, not just a code generator. **CORE PRINCIPLES** 1. **Context-First Principle**: BEFORE generating any code, you MUST check the /docs directory for relevant context. This includes project-brief.md, domain-model.md, active-feature.md, etc. 2. **Documentation-Driven Development**: If context is missing or unclear, you MUST pause coding and interview the user to create/update the necessary documentation. 3. **Governance Enforcement**: All code must adhere to the patterns, libraries, and standards implied or stated in the docs. Flag any potential deviations. **WORKFLOWS** - **New Feature Request**: When the user says “let‘s build X” or “add a feature for Y”: 1. Check if an active-feature.md exists. If not, create it using the template in /docs/templates/. 2. Guide the user through filling out the feature brief: Goal, User Stories, Acceptance Criteria, Technical Considerations. 3. Only after the feature brief is agreed upon, proceed to implement. - **Code Review Refactoring**: When asked to modify existing code: 1. Cross-reference the changes with domain-model.md and api-spec.md. 2. Ensure changes do not break established data flows or contracts. 3. Suggest updates to documentation if the code change represents an evolution of design. **INTERVIEW PROTOCOL** When documentation is lacking, ask structured questions: - For **Project Brief**: “Who is the primary user? What is the core job-to-be-done? What are the key technical constraints?” - For **Domain Model**: “What are the core entities? What are their relationships and key attributes?” - For **API Design**: “Is this a public or internal API? What are the resource endpoints and expected payloads?” **TONE STYLE** Be professional, proactive, and Socratic. Ask clarifying questions. Assume the user has deep product knowledge but may need help articulating it structurally.关键配置解析与心得角色定义ROLE MISSION这里把AI定位为“解决方案架构师”这很关键。这赋予了它一定的权威性和责任让它敢于对你用户说“不”或提出质疑。你也可以根据项目阶段定义为“需求分析师”、“安全审计员”或“测试工程师”。核心原则CORE PRINCIPLES第一条是铁律。我习惯把它加粗强调。这直接建立了“文档优先”的强制流程。工作流WORKFLOWS这里预定义了交互模式。例如“新功能请求”工作流强制了一个从需求文档到代码的管道。这避免了开发者直接跳入代码细节而忽略了整体设计。采访协议INTERVIEW PROTOCOL这是框架“魔法”的体现。当AI发现文档缺失时它不应该呆呆地等待而应该主动引导。这里提供的问题模板能帮助AI进行高效、结构化的需求采集。我的经验是根据你的团队常用术语定制这些问题效果会更好。比如如果你的团队用“Epic”和“Story”就把“User Stories”换成更具体的“请描述一个具体的用户故事格式为‘作为…我希望…以便于…’”。3.2docs/templates结构化知识的蓝图docs/目录下存放着所有项目上下文文档。而templates/子目录里的模板文件是AI用来自动生成这些文档的“填空题”试卷。常见的模板包括project-brief.md.template: 项目总体蓝图。domain-model.md.template: 数据实体与关系。active-feature.md.template: 当前正在开发的功能规格。api-spec.md.template: API接口设计。tech-decision-log.md.template: 关键技术选型记录。每个模板都是带有占位符和引导性问题的Markdown文件。例如一个极简的project-brief.md.template可能长这样# Project Brief: {{Project Name}} ## 1. 一句话目标 用一句话描述这个项目要解决的核心问题。 *(例如为小型电商店主提供一个无需代码即可上架和管理商品的移动应用。)* ## 2. 核心用户与场景 * **主要用户是谁** (例如个体店主、网课讲师) * **他们在什么场景下使用** (例如在仓库用手机盘点库存在通勤路上回复客户咨询) ## 3. 关键成功指标 (KPIs) * [ ] 指标1 (例如用户能在3分钟内完成商品上架) * [ ] 指标2 (例如应用启动时间小于2秒) ## 4. 技术栈与约束 * **前端** (例如React Native - 因需跨iOS/Android) * **后端** (例如Supabase - 因需快速原型开发且包含Auth/DB) * **关键约束** (例如必须支持离线操作因为用户网络可能不稳定)当AI根据.cursorrules启动“采访”时它会读取这个模板将{{Project Name}}这类占位符替换成它从对话中提取的信息并用模板中的问题如“主要用户是谁”来引导你对话最终生成一份完整的project-brief.md。实操心得模板的颗粒度是关键。一开始不要设计得过于复杂否则采访过程会很长让人失去耐心。从最核心的3-5个问题开始。随着项目推进再和AI一起迭代模板增加诸如“非功能需求”、“部署环境”、“监控告警”等章节。模板本身也是项目知识的一部分应该被版本化管理。4. 完整工作流实战从零构建一个任务管理应用让我们通过一个完整的例子看看contextFirst如何在实际项目中运转。假设我们要用 Next.js 和 Supabase 构建一个个人任务管理应用。4.1 初始化与首次对话安装框架在你的空项目根目录复制.cursorrules文件和docs/文件夹。打开 Cursor确保当前工作区包含这些新文件。开启魔法在 Cursor Chat 中输入“嗨我们来用 Next.js 和 Supabase 构建一个个人任务管理应用。”此时AI由于.cursorrules的存在不会直接去创建next.config.js。它会首先检查docs/目录。AI扮演解决方案架构师“我看到您正在启动一个新项目。我已经初始化了docs/project-brief.md文件。在我们开始写代码之前我需要先明确一些范围。这个应用的主要用户就是您自己吗除了任务的基本CRUD创建、读取、更新、删除您还需要其他功能吗比如任务分类、截止日期提醒、或者团队协作”你“就我自己用。需要任务分类工作、个人要有截止日期和优先级高、中、低。不需要协作。”AI“明白。我已经根据您的输入更新了项目简报。接下来我们需要定义数据模型。我会为您创建docs/domain-model.md。”[文件已创建docs/domain-model.md]AI 生成了包含User,Task,Category等实体的初步领域模型并标注了关系一个用户有多个任务一个任务属于一个分类。AI“基于这个模型我建议使用 Supabase 的 PostgreSQL。我将创建tasks和categories表。这是初始的SQL方案您看可以吗”[它展示了一段建表SQL其中包含字段id, title, description, priority, due_date, is_complete, user_id, category_id等]。你“可以再加一个created_at时间戳吧。”AI“好的已更新。现在我们可以开始实施第一个功能了。您想先从‘创建任务’的页面开始还是先搭建身份认证登录/注册”4.2 功能开发中的持续引导你“先从身份认证开始吧用 Supabase Auth。”AI“好的。在编码之前按照我们的流程我需要创建或确认docs/active-feature.md来描述‘用户认证’这个功能。我来草拟一下。”[文件已创建/更新docs/active-feature.md]内容节选功能目标实现用户通过邮箱/密码注册和登录。用户故事作为独立用户我希望能够注册一个账户并登录以便我的任务数据可以安全地私有化存储。验收标准提供注册页面邮箱、密码、确认密码。提供登录页面。登录后导航栏显示用户邮箱和登出按钮。未登录用户访问/app路由时被重定向到登录页。技术考量使用supabase/ssr包实现服务端渲染友好的认证流程。AI“这是功能的简要描述。确认无误后我将开始实现 Next.js 路由、Supabase 客户端配置以及相关的UI组件。”在整个编码过程中AI会持续引用domain-model.md确保它创建的users表结构与模型一致和active-feature.md确保它实现的功能点覆盖了所有验收标准。如果你中途说“再加一个‘用GitHub登录’的选项”AI会首先停下来要求你先更新active-feature.md中的验收标准和技术考量部分然后再去修改代码。4.3 应对需求变更与架构守护几天后你决定添加“任务评论”功能。你“给任务加个评论功能吧用户可以对自己任务添加备注。”AI“收到。我需要先更新领域模型添加一个Comment实体它与Task是多对一关系。同时我们需要创建新的docs/active-feature.md或更新当前的。请确认以下问题1. 评论是否需要富文本如加粗2. 评论是否可以编辑或删除3. 是否需要显示评论时间”在你回答后AI更新了domain-model.md创建了新的active-feature.md然后才开始生成comments表的迁移脚本和前端组件代码。这个过程强制进行了设计思考避免了“先写代码后补设计”导致的返工。5. 常见问题、排查技巧与进阶玩法在实际使用中你可能会遇到一些疑问或挑战。以下是我踩过坑后总结的经验。5.1 常见问题速查表问题现象可能原因解决方案AI完全忽略.cursorrules直接生成代码。1. Cursor 未正确加载项目根目录的规则文件。2. 规则文件语法有误AI无法解析。1. 在 Cursor 中确保打开了包含.cursorrules的项目文件夹而非单个文件。2. 检查.cursorrules格式确保是纯文本无特殊编码错误。可以尝试先写一个简单的规则如“每次回复前都说‘明白了’”测试是否生效。AI不断重复询问文档中已明确的信息。1. AI的上下文窗口限制未能有效读取长文档。2. 文档结构不够清晰AI定位信息困难。1. 在.cursorrules中指示AI关注特定文件的具体章节。例如“关于数据模型请重点参考docs/domain-model.md的‘核心实体’部分。”2. 优化文档结构使用清晰的标题## ###和列表避免大段散文。采访过程过于冗长影响开发效率。初始模板问题太多、太细。简化docs/templates/下的模板文件。只保留最核心、决定技术方案的问题。细节可以在开发过程中由AI通过提问自然补充到文档里。团队其他成员不习惯或不愿意使用。流程改变了原有习惯感觉“麻烦”。自上而下推行在团队站会中演示一次完整流程展示其如何避免后期重构和沟通成本。强调价值这不是增加负担而是将前期必要的设计讨论结构化、资产化。可以先在小型、绿色的新项目上试点。5.2 进阶技巧与自定义分阶段的规则集你可以准备多个.cursorrules文件如.cursorrules.architect侧重设计、.cursorrules.developer侧重实现、.cursorrules.refactor侧重重构。在不同工作阶段重命名或切换使用的规则文件让AI扮演不同专精的角色。集成现有文档体系如果你的团队已经有成熟的 RFCRequest for Comments流程或 ADRArchitecture Decision Record模板可以直接将这些模板放入docs/templates/。让AI按照你们既有的规范来引导讨论和生成文档无缝接入现有工作流。用于代码审查将.cursorrules的内容提炼成代码审查要点让AI在生成代码后自动对照文档进行一轮“自查”。例如“检查生成的API路由路径是否符合api-spec.md中的命名约定使用kebab-case。”知识库问答当项目文档齐全后你可以直接向AI提问关于项目本身的问题如“我们当初为什么选择使用TanStack Query而不是SWR” AI能够从tech-decision-log.md中直接找到记录并回答你成为项目的活字典。最后一点个人体会使用contextFirst最大的转变不是工具层面的而是思维层面的。它迫使你、你的团队和AI在键盘敲下第一行代码之前先进行思考、对齐和记录。一开始可能会觉得有点“慢”但这种“慢”恰恰是为了避免日后数天甚至数周的“乱”和“返工”。它把AI从一个可能引入混乱的“黑盒助手”变成了一个促进规范、沉淀知识的“协作伙伴”。对于严肃的软件工程项目来说这套方法论的价值会随着项目复杂度和团队规模的提升而愈发凸显。