1. 项目概述为什么你的AI编程助手需要“起飞前检查”如果你和我一样已经深度使用过Claude Code、Cursor、GitHub Copilot这类AI编程助手那你一定经历过这种场景你刚描述完一个需求比如“给这个用户模型加个邮箱验证字段”AI助手几乎在下一秒就开始噼里啪啦地生成代码。速度快吗快。但结果对吗很多时候它生成的代码要么忽略了项目里已有的验证逻辑库要么创建了重复的字段甚至可能因为没理解清楚“验证”指的是前端表单验证还是后端数据校验而写出完全跑偏的代码。最后你不得不花更多时间向它解释上下文、指出错误、让它重写一来二去所谓的“效率工具”反而成了“返工制造机”。这就是chitinhq/preflight这个项目要解决的核心痛点。Preflight起飞前检查是一个轻量级的、基于提示词的通用协议它强制要求任何AI编程助手在动笔写代码之前必须完成五个阶段的设计思考流程。你可以把它理解为一套嵌入到AI工作流中的“标准操作程序”。它的目标不是取代AI的创造力而是规范它的工作方式从“拿到需求就开干”的莽撞模式转变为“先设计后实施”的工程师思维。我最初接触这个项目时以为它又是一个复杂的、需要接入API的框架。但实际用下来才发现它的设计极其巧妙和轻量没有运行时依赖不需要API密钥本质上就是一组结构化的提示词文件。你只需要根据自己使用的AI助手如Claude Code、Cursor、Copilot等将对应的配置文件放到项目指定目录这套“设计优先”的协议就生效了。AI助手在响应你的需求时会自动遵循Orient定向、Clarify澄清、Approach方案设计、Confirm确认、Execute执行这五个阶段来工作。简单来说Preflight解决的是“AI编码代理一上来就写代码”的坏习惯。它通过一个协议让AI先花时间理解上下文、明确需求、设计多种方案并和你确认最后才进入编码阶段。这能显著减少因误解需求或忽略现有代码而导致的返工提升代码质量和开发效率。无论你是独立开发者还是团队中希望统一AI助手工作规范的Tech Lead这套方法都值得你花十分钟了解一下并集成到自己的工作流中。2. Preflight协议核心五阶段工作法深度解析Preflight协议的精髓完全体现在其强制性的五个阶段里。这五个阶段模拟了资深工程师接到需求后的思考路径将原本黑盒的、跳跃式的AI生成过程变成了一个透明、可预测、可协作的流程。我们来逐一拆解每个阶段的设计意图、具体行为以及它如何在实际对话中体现。2.1 第一阶段Orient定向—— 先看地图再找路核心目标让AI助手在动手前先充分理解它所处的“环境”。这就像你被空投到一个陌生城市完成一项任务明智的做法绝不是立刻开始跑而是先打开地图搞清楚自己在哪、周围有什么、任务目标的大致方位。AI的具体行为自动读取相关文件AI会基于你的任务描述智能定位并读取项目中可能相关的源代码文件。例如如果你要求“修改用户登录逻辑”它会自动去查看auth/目录下的控制器、模型、路由文件。查阅文档如果项目中有README.md、ARCHITECTURE.md或相关的API文档AI会优先阅读这些材料以理解项目的整体架构、技术栈和约定。检查近期变更AI会查看git log或相关文件的近期修改历史了解该模块最近的改动动态避免提出与最新方向背道而驰的方案。为什么这个阶段至关重要很多AI生成的代码之所以“不合群”根本原因就是缺乏上下文。我曾让一个助手添加一个“评论点赞”功能它直接创建了一个新的likes表。但实际上项目里早已有一个通用的reactions表来处理所有点赞、收藏等行为只是它叫user_reactions。因为没有经历Orient阶段AI完全是在盲人摸象。有了这个阶段AI会首先报告“我已查看项目发现存在user_reactions表其reaction_type字段包含‘like’相关的模型是Reaction控制器逻辑在api/reactions_controller.rb中。” 基于这个认知它后续的方案设计就会合理得多。实操心得Orient阶段的效果高度依赖于你的项目结构清晰度和命名规范性。一个结构混乱、命名随意的项目AI也可能“迷路”。因此保持清晰的目录结构和有意义的文件命名本身就是对AI助手的一种友好。2.2 第二阶段Clarify澄清—— 把模糊的需求变清晰核心目标主动挖掘需求背后的细节、边界条件和成功标准。产品经理或用户给出的需求描述往往是模糊的、不完整的甚至存在隐含条件。这个阶段就是让AI扮演一个“追问者”的角色。AI的具体行为提出开放式问题AI会针对任务描述中的模糊点、歧义点进行提问。例如对于“优化图片上传速度”它可能会问“‘优化’的具体目标是什么是希望将平均上传时间从2秒降低到500毫秒还是支持更大的单文件上传”明确约束条件AI会主动询问技术或业务约束。例如“这个功能有上线时间要求吗”“是否需要向后兼容旧的API版本”“服务器是否有内存或存储限制”定义成功标准AI会试图和你一起确认怎样才算这个任务“完成了”且“做对了”。例如“成功标准是用户在前端能看到上传进度条并且控制台日志显示处理时间缩短30%对吗”为什么这个阶段能避免返工“澄清”是防止需求理解偏差的第一道防线。我遇到过最典型的例子是需求是“导出用户数据为Excel”。如果没有澄清AI可能直接生成一个简单的CSV导出。但通过提问AI了解到用户需要的是带有多工作表、单元格合并和公式的复杂Excel报表这完全改变了技术方案需要引入pandas或openpyxl库而不是简单的CSV写入。在编码前发现这种根本性的差异节省的是推倒重来的时间。2.3 第三阶段Approach方案设计—— 提供选择题而非判断题核心目标针对澄清后的需求设计多个可行的技术方案并分析其利弊最后给出推荐。这改变了AI传统上“给一个方案就开干”的模式让你从“被动接受者”变为“决策者”。AI的具体行为提出2-3个备选方案AI会构思不同的实现路径。例如实现一个缓存功能方案A可能是使用内存缓存如Redis方案B可能是使用数据库缓存方案C可能是利用HTTP缓存头。分析权衡Trade-offs针对每个方案AI会列出其优点、缺点和适用场景。比如“方案ARedis性能极高但引入了新的外部依赖需要额外运维。方案B数据库无需新服务但性能受数据库IO限制且可能增加主库压力。”给出明确推荐基于项目上下文如现有技术栈、性能要求、团队熟悉度AI会推荐一个它认为最合适的方案并说明理由。这个阶段的价值在于“可控的多样性”。它不会用海量方案淹没你而是提供有限但经过思考的选项。这不仅能帮助你做出更优的技术决策还能让你了解AI的思考过程学习到不同方案背后的权衡逻辑。很多时候AI推荐的方案可能不是你最初想的但其理由比如“与现有认证库集成度更高”往往能说服你。2.4 第四阶段Confirm确认—— 最后的拍板核心目标在执行任何代码修改之前获得你对最终计划的明确批准。这是将潜在错误扼杀在摇篮里的最后一步。AI的具体行为呈现最终计划AI会汇总前三个阶段的结果形成一个清晰的、可执行的开发计划。这个计划通常包括要修改/创建哪些文件、大致的代码结构、使用的关键库/API、以及如何测试。等待明确指令AI会明确表示“以下是我的计划在我开始编写代码之前请确认这个计划是否正确或者指出需要调整的地方。” 此时它不会生成任何代码。根据反馈调整如果你对计划有疑问或修改意见AI会在Confirm阶段内与你继续讨论更新计划直到你明确说“好的开始吧”或“执行”。“确认”阶段是心理上的安全网。它创造了一个短暂的停顿让你有机会审视整个方案。很多时候正是在这个“最终看一眼”的时刻你会发现一些之前忽略的细节比如“哦这个改动会不会影响到另一个正在运行的后台任务” 此时叫停成本为零。2.5 第五阶段Execute执行—— 专注地编写代码核心目标在前期充分设计和确认的基础上高效、准确地生成代码。AI的具体行为基于确认的计划编码AI会严格按照Confirm阶段定下的方案来生成代码不再天马行空。生成更相关、更准确的代码由于经过了Orient阶段AI对代码库非常熟悉由于经过了Clarify和Approach阶段它深刻理解了需求和约束。因此它生成的代码“一次性正确率”会高很多。可能包含解释性注释生成的代码中可能会包含简要注释说明为何选择此实现方式这与之前哪个方案的权衡有关。一个关键原则Phases 1-4 不产生任何代码变更。这是Preflight协议的硬性规定。在前四个阶段AI只被允许阅读、提问、设计和讨论。这强制了“先思考后行动”的纪律彻底杜绝了边想边写、写到一半发现不对又推倒重来的浪费。3. 如何为你的AI助手集成Preflight协议Preflight的另一个巧妙之处在于其极简的集成方式。它不要求你安装复杂的SDK或修改AI助手的核心而是利用几乎所有现代AI编码助手都支持的“自定义指令”或“上下文文件”功能。下面我将以几个主流的助手为例手把手带你完成集成。3.1 通用安装方法一键脚本对于大多数用户最快捷的方式是使用项目提供的安装脚本。它会自动检测你系统上安装了哪些AI助手驱动并为你配置好对应的Preflight文件。打开你的终端执行以下命令bash (curl -fsSL https://raw.githubusercontent.com/chitinhq/preflight/main/install.sh)这个脚本会检查你的项目目录或常用配置路径。识别出你正在使用的AI助手如通过检查.cursor、.claude等目录是否存在。将对应的Preflight协议文件复制到正确的位置。如果你只想为某个特定的助手安装也可以指定驱动bash (curl -fsSL https://raw.githubusercontent.com/chitinhq/preflight/main/install.sh) --driver claude-code3.2 手动安装与配置详解如果你想更清楚地了解原理或者安装脚本不适用于你的环境手动安装也非常简单。本质上就是复制一个文本文件。以下是针对不同助手的详细配置表助手驱动需复制的源文件目标位置与操作Claude Codedrivers/claude-code/preflight.md复制到项目根目录的.claude/commands/preflight.md。如果.claude目录不存在需要先创建。Cursordrivers/cursor/.cursor/rules/preflight.mdc复制到项目根目录的.cursor/rules/preflight.mdc。Cursor的.cursor/rules目录用于存放行为规则文件。GitHub Copilotdrivers/copilot/.github/copilot-instructions.md追加内容到你项目根目录的.github/copilot-instructions.md文件末尾。如果该文件不存在直接创建并将内容粘贴进去。Goosedrivers/goose/.goosehints追加内容到你项目根目录或用户主目录的.goosehints文件末尾。Codex (OpenAI)drivers/codex/AGENTS.md追加内容到你项目相关配置目录的AGENTS.md文件末尾。Gemini CLIdrivers/gemini/GEMINI.md追加内容到你Gemini CLI配置指定的GEMINI.md文件末尾。操作步骤与验证克隆或下载Preflight仓库git clone https://github.com/chitinhq/preflight.git或者直接下载ZIP包。定位驱动文件进入解压后的preflight/drivers/目录找到你所用助手对应的文件夹。放置配置文件根据上表将文件复制或内容追加到目标位置。关键点对于Copilot、Goose等需要“追加”的请务必不要覆盖原文件原文件里可能有你其他的自定义指令。验证生效重启你的AI编码助手或重启IDE然后在一个项目中尝试提出一个稍复杂的任务例如“请为这个React组件添加错误处理”。如果Preflight生效你应该看到AI助手首先开始分析现有组件代码Orient然后可能会问你关于错误类型和UI反馈形式的问题Clarify而不是直接生成try...catch代码块。注意事项Preflight协议是项目级别的配置。这意味着你可以为不同的项目设置不同的规则。例如在一个快速原型项目中你可能觉得Preflight过于繁琐那么只需不在那个项目中放置配置文件即可。这种灵活性让你可以精细控制AI助手在不同场景下的行为。3.3 协议如何工作提示词工程的魅力你可能好奇一个简单的文本文件如何能改变AI的行为这背后是提示词工程的力量。Preflight文件本质上是一段精心编写的“系统提示词”或“指令”。它利用了AI模型对前置指令的高度服从性。以Claude Code的preflight.md为例其核心内容是一段清晰的指令告诉AI“当你收到编程任务时你必须严格按以下五个阶段执行…”。由于这个文件被放置在Claude Code读取的指令目录中它会在每次会话开始时被加载成为AI模型行为的基础约束。这种方式的优势是无侵入、零开销。它不修改任何AI助手的二进制文件不引入新的运行时完全依赖于AI平台已有的自定义能力。这也意味着它的兼容性非常好只要AI助手支持自定义指令理论上就可以支持Preflight。4. 实战案例从“翻车”到“丝滑”的体验对比理论说得再多不如看实际效果。我选取了两个日常开发中常见的任务对比了在没有Preflight和有Preflight的情况下AI助手的不同表现。你可以清晰地看到后者如何一步步引导出更稳健的结果。4.1 案例一修复一个“简单”的Bug任务描述“用户报告说个人资料页的头像上传后不显示。”没有Preflight时典型“翻车”场景AI行为立刻开始编写代码。它可能会直接去修改前端头像组件的src属性绑定逻辑或者去修改后端的某个API路由。潜在问题AI没有先去查看现有的头像上传和显示逻辑。实际上问题可能出在1文件上传后存储路径错误2CDN缓存未刷新3前端组件读取的URL字段名不对比如后端返回avatar_url前端却用profile_pic。AI的“修复”可能完全不对症甚至引入新问题。结果你需要打断它告诉它“不对不是这里”然后手动引导它去检查存储服务配置浪费了时间和对话轮次。启用Preflight后“丝滑”修复OrientAI首先报告“正在检查个人资料页相关文件。已读取ProfilePage.jsx、userApi.js、UserController.rb以及最近的git提交记录。发现头像URL由/api/users/{id}/avatar接口提供。”ClarifyAI提问“为了准确定位问题我需要知道a) 不显示是全部用户还是个别用户b) 上传时控制台或服务器日志是否有报错c) 是根本加载不出图像还是显示默认占位图”Approach基于你的回答假设是“全部用户不显示无报错显示破损图标”AI提出方案“可能原因A接口返回的URL格式不正确。方案检查后端avatar接口的序列化逻辑。可能原因B前端组件处理响应数据有误。方案检查前端网络请求和img标签的src设置。我推荐先从后端接口调试开始因为前端破损图标通常意味着src为空或无效。”ConfirmAI总结“计划1. 首先检查UserController#avatar方法的返回值。2. 在浏览器开发者工具中查看该接口的实际响应。3. 根据结果决定修复后端数据还是前端解析。确认无误后我将开始检查代码。”Execute在你确认后AI开始检查代码并可能迅速发现“找到问题后端avatar_url方法在用户未上传头像时返回了nil但前端未处理此情况导致src为空。建议修复在后端确保始终返回一个默认头像URL。” 然后生成相应的修复代码。整个流程逻辑清晰AI像是一个有条理的搭档带着你一起排查问题而不是一个乱撞的无头苍蝇。4.2 案例二实现一个“复杂”的新功能任务描述“我们需要一个功能让管理员可以批量导出选中用户的订单数据为CSV。”没有Preflight时容易“跑偏”的场景AI行为很可能立即开始编写一个后台任务或API端点涉及查询数据库、组装CSV、提供下载链接。它可能会选择一个它熟悉的CSV库。潜在问题它可能忽略了1现有项目是否已有通用的“数据导出”抽象层或服务类2订单数据关联很多用户、商品、物流导出范围是什么3是否有性能考量一次导出1万个订单4CSV文件是即时生成下载还是异步生成后通知管理员忽略这些点代码可能无法集成或性能极差。启用Preflight后结构化设计OrientAI扫描项目后报告“项目使用Rails框架已存在ExportService基类和AsyncJob模块。订单模型是Order关联User、Product、Shipment。最近有关于后台任务使用Sidekiq的提交。”ClarifyAI提出关键问题“a) 导出字段需要哪些仅订单基础信息还是包含关联的用户名、商品名b) 数据量级如何是否需要分页或异步处理c) 导出后文件如何交付通过邮件发送链接还是在管理后台直接下载d) 是否有现有的管理员权限检查需要复用”ApproachAI设计方案“方案A在现有ExportService上扩展创建OrderExportService生成CSV通过Active Job异步处理结果存储在S3邮件通知。方案B创建一个新的API端点即时生成CSV文件流式下载简单但可能超时。方案C利用已有的报表工具Blazer来配置。推荐方案A因为它复用现有异步模式和存储服务更稳健适合大数据量且与项目架构一致。”ConfirmAI呈现详细计划“1. 创建app/services/order_export_service.rb继承ExportService。2. 定义fields方法指定导出列。3. 创建app/jobs/order_export_job.rb。4. 在管理员控制器添加触发端点调用Job。5. 在管理界面添加‘批量导出’按钮。请确认字段列表和交付方式邮件。”Execute在你确认字段列表例如订单ID、金额、状态、用户名、创建时间后AI开始生成高度贴合项目现状的代码直接继承了已有的基类使用了正确的Sidekiq队列名称并复用了邮件通知模板。这个案例展示了Preflight如何引导AI从“写代码”上升到“做设计”产出方案不仅功能正确而且与项目现有架构和模式无缝集成。5. 高级技巧与疑难问题排查将Preflight集成到日常工作流后你可能会遇到一些具体问题或想进一步优化体验。以下是我在实际使用中总结的一些技巧和常见问题的解决方法。5.1 如何调整协议的“严格度”Preflight协议默认是“全量”执行的即使是一个很小的任务比如改个错别字也会走完五个阶段。这有时可能显得“杀鸡用牛刀”。项目设计者考虑到了这一点提出了“Scales down, never off可缩减永不离场”的原则。对于微小任务每个阶段可以缩短为一句话。例如Orient“查看README.md中的项目名。”Clarify“确认是将‘Aplication’改为‘Application’吗”Approach“直接进行全局查找替换。”Confirm“计划在README.md第5行进行修改。确认”Execute执行修改。这样既保持了纪律又不会过度繁琐。自定义调整你可以直接编辑你项目中的Preflight配置文件如.cursor/rules/preflight.mdc。例如如果你觉得Approach阶段对于简单任务总是提出过于明显的方案你可以修改提示词增加一条判断逻辑“如果任务极其简单且方案唯一则可以直接在Confirm阶段陈述唯一方案无需列出多个。”但请注意修改协议文件需要一定的提示词工程知识且可能影响效果建议先备份原文件。5.2 常见问题与解决方案速查表问题现象可能原因解决方案AI助手完全忽略Preflight流程直接写代码。1. 配置文件未放在正确位置。2. AI助手未加载或识别该配置文件。3. 某些助手需要重启IDE或重新打开项目。1. 严格按照第3部分的路径表检查文件位置和名称。2. 对于Cursor检查设置中是否启用了自定义规则。3. 重启你的代码编辑器或AI助手插件。Preflight流程走完了但AI生成的代码仍然不符合预期。1.Orient阶段读取的上下文不足。2.Clarify阶段你的回答可能不够精确。3. 项目本身代码或架构非常复杂/混乱。1. 在任务描述中提供更精确的文件路径或背景。2. 在Clarify阶段尽可能给出具体、量化的回答。3. 考虑将大任务拆分成多个有明确边界的小任务分次执行。感觉Preflight让对话变得冗长拖慢了简单任务的进度。对非常直观、简单的任务如重命名变量完整五阶段可能确实多余。尝试使用更简洁的任务描述并接受AI在微缩版五阶段下的快速响应。或者对于明确知道只需一行修改的任务可以暂时关闭该项目的Preflight配置。如何为团队统一配置Preflight每个成员手动配置容易不一致。将Preflight配置文件如.cursor/rules/preflight.mdc、.github/copilot-instructions.md纳入项目的版本控制如git。这样所有克隆项目的团队成员都会自动获得相同的AI行为规范。这是团队统一开发助手标准的最佳实践。AI在Approach阶段提出的方案都很糟糕。AI的解决方案质量受限于其模型知识和项目上下文理解。在Confirm阶段明确否定它的方案并提出你的方向。例如“这些方案都不好我倾向于使用我们之前封装过的XUtils库来处理。请基于这个方向重新制定计划。” Preflight流程是引导最终决策权在你。5.3 与现有工作流的结合Preflight并不是一个孤立的工具它可以很好地与你现有的开发流程结合与Ticketing系统如Jira, GitHub Issues结合你可以将完整的任务描述甚至包含验收标准复制到AI对话中。Preflight的Clarify阶段会帮你细化这些需求Confirm阶段产生的计划甚至可以反过来更新Ticket作为实现方案文档。与代码审查Code Review结合由于Preflight要求AI先理解现有代码Orient并设计可集成的方案Approach它生成的代码往往更符合项目规范更容易通过代码审查减少了“风格不符”、“重复造轮子”等常见评论。作为新成员的项目引导对于刚加入项目的新开发者即使他不主动使用AI让他通过阅读项目中的Preflight配置文件也能快速了解团队期望的“问题解决框架”——先理解、再澄清、多方案比较、确认后执行。这是一种潜移默化的工程文化培养。Preflight协议代表了一种理念的转变我们不再将AI助手视为一个神秘的代码生成黑盒而是将其塑造为一个遵循良好工程实践的可协作伙伴。它通过一套简单的规则将人类工程师的审慎思维注入到AI的工作流程中最终收获的是更高的代码质量、更少的沟通返工和更可预测的开发结果。花一点时间配置它你可能会发现你的AI助手突然变得“聪明”和“靠谱”了许多。