再看问题，为什么大部分 Vibecoding 不可持续

AI 写代码很快。但“AI 写完的代码能稳定跑在生产环境”是另一回事。常见的失败模式：

1. 需求漂移AI 在第 轮对话时已经忘了第 轮的需求细节，开始自己“脑补”。
2. 架构腐蚀AI 为了快速实现功能，直接在 API 层写 SQL、跳过 Service 层、引入循环依赖。
3. 验证缺失AI 说“改好了”，但天后发现破坏了另一个模块的分层约束。
4. 上下文断裂token 窗口耗尽后下一个 AI 实例从基础开始，重复劳动。

本质矛盾AI 的强项是“快速生成”，弱项是“保持一致性的约束”。而软件工程的本质恰恰是“在约束下持续演进”。老实说，

这篇文章的主要命题是：如何用工程手段把 AI 的快速生成能力关进约束的笼子。让它每一次输出都可验证、可修复、可接力。

方法论全景的观点是，三阶段门禁流水线

贯穿全文的案例：archiving 数据归档网站

这篇文章以 archiving 项目为贯穿案例。该项目是一个客户服务数据归档与智能分类网站，技术栈为 Python + FastAPI + PostgreSQL + Redis。前端 React + Vite + TypeScript。

说到主要业务流程。

1. 从企微会话存档拉取客户服务聊天记录，定时任务批量同步。
2. 多媒体内容自动提取：音频 ASR 转写、文档解析、压缩包递归解压。
3. LLM 智能分块分类，将对话归类到预设业务标签程序。
4. 人工审核编辑后归档，支持全文检索与批量导出。

项目从基础开始严格遵循 AGENTS.md 分层架构，plan/ 和 task/ 目录即为这篇文章方法论的主要产物。

PRD.md ──→ ──→ ──→ ──→ 可交付代码
│ ▲ │ ▲ │ ▲ ▼
│ ▼ │ ▼ │ ▼
│ 人工审核 人工审核 CI 自愈循环
│

每个阶段的输出是下一阶段的唯一输入，且必须通过门禁才能流转。这不是“建议”，而是通过文件状态机强制执行的硬约束。

工具定位

文件状态机

每个 plan/ 和 task/ 文件头部携带 YAML front matter：

---
至于status，draft | in_review | approved | implementedreviewer: "审核人"
last_update:
dependencies:
plan_refs:
---

• draft → in_review: 作者提交审核。
• in_review → approved: 人工审核通过。
• approved → implemented;Vibecoding 完成 + CI 全绿。

This is an irreversible directed graph: once a document is approved it cannot be altered arbitrarily—any change requires creating a new task rar than revising plan.

Plan 阶段：把模糊需求变成可执行的设计

为什么需要四份文档?

• 传统开发中，一个需求讨论会可能产出半页白板笔记。AI 拿着这个去写代码，大概率会写出“看起来对但实际不对”的东西。
• Plan 阶段强制产出四份结构化文档，每份回答一个不可跳过的问题。
  • design.md 程序怎么做？模块边界在哪，AI 在 API 层写业务逻辑，破坏分层。话说回来，
  • 同名字段在不同表类型不一致。会导致 JOIN 报错，
  • 入参出参长什么样？前端调不通，需要反复返工。
  • test.md 怎么证明功能是对的？话说回来，改了 A 模块，却悄悄坏了 B 模块。

案例这方面，archiving 项目的 Plan 产出

• 以 archiving 项目为例，四份文档产出的内容：

• design.md 节选——主要处理链路：

  "企微会话存档 " -> 定时任务拉取 -> 原始消息存储 -> 消息组包 -> MQ -> 使用者解析落库
  - 音频 : ASR 转写 -> 文本内容提取
  - 文档 : 文档解析 -> 文本内容提取
  - 压缩包 : 解压 -> 递归处理内层文件
  LLm 智能分块分类 -> content_block
  人工审核/编辑 -> 确认归档"
  "
  '
  '
  '
  '
  '
  '
  '
  '

  ' ' ' ' ' ' ' ' ' '

• db.md 节选——状态字段约定：
  • 'WAIT'的观点是。待处理 '
  • 'DOING': 处理中'
  • 'DONE'/'SUCCESS': 完成 '
  • 从'FAIL'来看，失败 '
  • 'SKIP'这方面，跳过/无需处理 '

  '

• api.md 节选——待开发接口契约：

  POST /api/v1//update_content_block_info 请求:
  {content_block_id:str,update_content:str}
  至于返回，{ code:,message:"success",data:true }
  至于校验，order_chat_block_id 非空,update_content 非空'
  '

  '

• test.md 节选——验收用例： 正常修改内容 返回 true order_chat_block_id为空时返回失败 update_content为空时返回失败 不存在 block 返回 false' '

如何从 PRD 生成 Plan?

 




  ，说起来，"PRD直接映射": 功能需求 → design 流程+api 接口；



  ，"现有代码库参考": 已有 models/目录 → db.md 表结构；不过，已有 main.py → api.md 路由清单；



  ，"工程经验补充": 并发一致性、状态补偿、幂等设计等非功能需求 → 补充到 design.md；