从飞书PRD到代码实现的AI编程工作流

# 从飞书PRD到代码实现：一次完整的AI编程工作流复盘 最近在实践一个真实研发需求，以Codex作为主要协作工具。 需求本身规模不算大——阅读器里需实现“高光场景插卡”和“高光段落气泡”两个功能。但真正想实验的，并非这两个功能最终如何编写，而是另一件事：能否将平时处理PRD、拆解需求、编写方案、修改代码、开展验证的全过程，固化为一个稳定的AI工作流？ 不是每次都靠临场发挥与AI沟通。而是把流程打包成一个Skill，让AI明确：需求从哪里读取，读完后如何分解，何时需要停下来等我确认，何时才能真正修改代码。 真实工程场景中，问题往往不在AI不会写代码。问题在于它太急于推进。PRD没读完，它也敢猜测；需求范围未确认，它也敢动手；仓库有本地改动，它也敢继续；构建未通过，它也可能轻描淡写地说“应该没问题”。这非常危险。 因此这次想总结的，是一次从飞书PRD到代码实现的完整AI编程工作流。 图片说明：从飞书PRD链接到本地快照、需求拆解、技术方案、代码实现和QA的完整流程。 ## 一、第一步不是写代码，而是读取真实需求源头 本次会话的第一句话其实很普通。用户给了一个飞书Wiki链接，并说：“这是PRD。” 如果用普通AI编程方式，下一步大概是把PRD丢给AI，说“请根据这个需求改代码”。然后AI自动搜索代码、猜测结构、修改文件。看起来很快，但这里有一个问题：AI究竟有没有读取到真实需求源头？ 如果需求只是散落在聊天上下文里，后续每一步都会变得不可靠。它可能记错，可能遗漏，甚至可能把自己猜测的内容当作需求。 因此工作流第一件事并非进入代码仓库，而是接入飞书CLI，先将需求文档读取下来。 这一步会将飞书里的PRD拉取到本地，保存为快照和metadata。本次对应的目录结构如下： source/ — 存储PRD快照 analysis/ — 存储需求拆解和待确认问题 planning/ — 存储技术方案和任务拆解 qa/ — 存储测试用例和验收清单 output/ — 存储实现摘要和验证结果 这里最重要的不是目录是否美观。而是它将一次对话，转化为一组可回溯、可确认、可交接的本地文件。普通prompt依赖上下文记忆，而工作流依赖阶段产物。这个区别非常关键。 图片说明：需求入口来自飞书文档，工作流会先读取并保存真实需求源头。 ## 二、读完PRD之后，真正重要的是需求拆解 将PRD拉取下来后，也不能直接编写代码。因为“读到了文档”和“理解了需求”之间，还存在很大差距。 本次工作流的下一步，是产出两个文件：requirements.json 和 open-questions.md。 requirements.json 不仅仅是简单总结，而是将需求拆解为工程可处理的对象。例如明确范围、非目标、涉及的API接口、UI规则、埋点要求等。这并非为了让文档显得正式，而是为了让AI先将自己的理解暴露出来。 AI最令人困扰的一点，是它显得非常自信。它经常会把“我猜测是这样”写得像“需求就是如此”。因此需求拆解的价值，就是打开这个黑盒，让人先检查一遍：范围是否正确？非目标是否写清楚？接口字段是否猜测正确？UI规则和埋点有没有遗漏？ open-questions.md 则负责将不确定项沉淀下来。例如本次就涉及：高光插卡是否跟随书籍插图开关？icon_type = 7 是否完全以后端返回为准？点击跳转本期是否需要完整实现？高光插卡与神段评、作家插图的优先级如何安排？ 用户补充完这些信息后，AI再读取该文件，将方案收敛。这一步看似缓慢，但它解决了一个实际问题：如果需求理解有误，在此阶段修正成本很低；等代码写完再修正成本就很高。 图片说明：需求拆解、Open Questions、技术方案和验证结果均沉淀为本地文件。 ## 三、Skill不是提示词，而是一份工作说明书 本次真正起作用的，是一个名为 qm-prd-workflow 的 Skill。 以前容易把 Skill 理解为“更长、更详细的提示词”。但此次实践后发现，Skill更像一份给AI的员工手册。它不是告诉AI“你要更聪明”，而是规定：你在哪些目录工作，先读取什么，每一步产出什么文件，何时必须停下来询问人，哪些动作绝对不能自行决定。 例如这个工作流会明确项目边界：主App仓库在哪里，阅读器组件仓库在哪里，工作流产物根目录在哪里。它还会写明流程关卡：飞书PRD intake、本地快照、需求分析、Open Questions、技术方案、任务拆解、代码实现、QA和verification。同时列出禁止动作：在用户确认需求理解和技术方案之前不修改项目代码；仓库有未提交改动时停止；不要自动stash、commit、reset、clean；不要将分析文档散落到业务仓库中。 这些规则听起来并不性感，但它们恰恰是工程协作中最有价值的部分。普通prompt像临时交代一句“帮我看看这个需求”，而Skill更像给新同事的一份岗位操作指南。AI不缺少执行力，它缺少的是一套稳定的工作边界。 图片说明：SKILL.md、scripts、references和assets共同组成一套可复用的工作说明书。 ## 四、Human in the Loop不是每一步都盯着AI Human in the Loop 容易被说成空话。似乎只要流程中有人点击确认，就叫做人在环。但真正有价值的地方，不是让人每一步都盯着AI，而是将人的判断力放在最需要的位置。 本次工作流中有几个明确的停顿点。需求理解后停下来：人确认范围和非目标。Open Questions后停下来：人补充接口、UI、埋点、开关逻辑。技术方案后停下来：人确认实现方向。进入实现前停下来：如果仓库有本地改动，AI不自作主张处理，而是等人做决定。 本次 ios_qmnovel 有本地改动时，工作流没有自动stash或reset。最终用户明确表示“无须管ios_qmnovel本地改动，进入代码实现”，AI才继续，只修改qmreader。这个细节很小，但非常重要。因为AI最令人不放心的地方，就是它会擅自处理未经授权的操作。 好的工作流应该反过来：AI负责推进、记录、执行和提醒风险；人负责确认方向、补充上下文、收敛方案和承担关键决策。好的工作流不是把人从流程中移除，而是把人放在最有判断价值的位置。 ## 五、具体代码实现只是工作流的验证样例 最后，这个需求确实进入了代码实现阶段。但具体业务实现并非主角，它只是这条工作流的一个验证样例。 简而言之，最后代码层面做了以下工作：新增 YYHighlightParaView，解析 chapters.highlight 字段，支持 icon_type=7 映射 reader_a_remark_bubble_default，将高光插卡接入段末插件管理，补上插卡曝光和点击埋点。 这些实现证明了一件事：工作流不仅会写文档，它可以从飞书PRD一路走到真实代码改动。但更重要的是，它让交付结果更加可靠，产出可复用的产物，增加对代码实现的掌控，尤其是第一版代码实现的掌控，后续还可根据需要引用和分享产物。 ## 六、如果你想写一个Skill，先写边界，再写能力 本次实践之后，对 Skill 的理解变得更加具体。如果你也想将自己的重复工作固化为一个 Skill，建议先别急着写一大段提示词，而是先写边界。 可以从这些问题入手：入口是什么？是飞书链接、PRD文档、截图，还是接口说明？真实需求如何读取？能否优先接入飞书CLI、GitHub issue等，而不是仅靠聊天上下文？每一步产物放在哪里？需求要拆解成什么结构——范围、非目标、接口、UI、埋点、风险、Open Questions？哪些节点必须等人确认——需求理解、技术方案、进入实现、验证阻塞？哪些动作禁止自动执行——例如 reset、stash、commit，或者在未确认前修改业务代码？ 这些限制不是束缚AI，恰恰相反，它们是在帮助AI变得可信。一个好的 Skill 不是让AI看起来更聪明，而是让AI在重复工作中更加稳定、可控、可交付。 ## 写在最后 本次高光插卡需求本身不是重点。重点在于更清晰地看到：AI编程序要稳定下来，不能仅靠“更会提问”。它需要工作流。 接入飞书CLI，是为了让AI读取真实需求源头。需求拆解，是为了让AI先暴露自己的理解。Human in the Loop，是为了让人在关键节点做出判断。本地artifacts，是为了让过程可追溯、可交接、可复盘。 AI协作最重要的变化不是“人被移除”，而是人终于可以从重复推进中抽身出来，将注意力放到更重要的判断上。后续可以不断完善工作流skill，引入多agent协作、代码性能检测、产物归档到云端形成知识库等。