Vibe Coding 体系

基于 .ai 知识库的 AI 辅助开发方法论，让 AI 真正理解你的项目，成为靠谱的编码搭档

vibe-blocks · 业务流程积木化文档体系

🧩 什么是 Vibe Coding

Vibe Coding 不是一个工具，而是一套将项目知识结构化、让 AI 能深度理解并参与开发的工作方法。

核心理念
在项目中维护一个 .ai 文件夹，用结构化的 Markdown 描述架构、服务、业务流程和编码规范。AI 读取后能像老员工一样理解项目上下文。
积木化思维
每个完整的业务流程被抽象为一块"积木"——从触发条件到最终响应，包含调用链路、时序图、异常处理、写表操作，形成可复用的知识单元。
人机协作
开发者负责设计决策和业务判断，AI 负责代码实现和模式匹配。知识库是两者之间的"共同语言"。

本质：给 AI 安装项目长期记忆

知识库的作用类似于给 AI 装上了关于你项目的"大脑"，分为两层记忆：

CLAUDE.md = 入职培训手册
告诉 AI "我们用什么技术、有什么规矩、哪些事不能做"。每次对话自动加载，确保 AI 不犯低级错误。
积木 + 服务档案 = 业务长期记忆
告诉 AI "具体业务怎么跑、代码在哪、谁调谁、数据怎么流"。AI 按需检索，不用每次全部加载。

比普通 AI 记忆更强在哪？

版本化 — 跟代码一起 git commit，代码改了知识库也改，永远不会过时
结构化 — 有 frontmatter、时序图、代码锚点，AI 能高效检索而非翻找碎片
共享的 — 不绑定某个人的对话历史，团队所有人、所有 AI 工具共用一份
可审计 — 谁改了什么、为什么改，git log 一清二楚

实战案例：知识库如何驱动 AI 编码

以下两个真实场景展示 AI 如何利用知识库，从一句需求直接产出可合并的代码。

案例一：新增订单状态
案例二：优化下单耗时

你的指令："给订单加一个 SHIPPING 配送中状态，支付成功后自动流转"

完整知识库（积木 + 服务档案）
1 轮对话~5 分钟首版即可用
定位积木索引
AI 进入 _index.md 搜索"订单"，命中 order_create.md / order_pay.md / order_refund.md 三个核心积木
获得完整业务流程
order_pay 时序图告诉 AI：支付回调里的 8 步流转都涉及哪个状态切换；references/enums.md 列出现有所有 OrderStatus 枚举值。
服务档案确认细节
order-service.md 标明订单表写入方仅有 order-service，不会有别的服务直写状态字段。
直接生成完整代码
枚举 + 状态机校验 + order_pay 积木里 step 5 之后的状态流转、order_refund 积木里允许退款的状态校验，全部一次到位。
仅项目说明（CLAUDE.md）
2-3 轮对话~15 分钟规范对但细节缺
给订单加一个 SHIPPING 配送中状态
我知道项目用 Java + Spring Cloud + BFF。订单状态应该在 order-service 的 OrderStatus 枚举里。但我需要确认：现有有哪些状态？支付回调流程里在哪一步切换状态？
现有 PENDING_PAY / PAID / CANCELLED / REFUNDED，支付回调在 PaymentService.onPaySuccess
退款的 status 校验放在哪个方法？是否影响其他服务？
RefundService.applyRefund 里校验 status=PAID
（开始写代码）
✅ 枚举位置正确
✅ 状态机校验加上了
⚠️ 但不知道 order_refund 现在允许哪些状态退款
⚠️ 不知道是否要发 MQ 通知
无任何配置
5-8 轮对话30-60 分钟多次返工
给订单加一个 SHIPPING 配送中状态
请问用什么技术栈？订单状态怎么定义？
Spring Boot + Spring Cloud，Java，order-service 里有 OrderStatus
现有有哪些状态？支付成功后是怎么流转的？
PENDING_PAY → PAID → CANCELLED/REFUNDED
支付回调在哪？
PaymentService.onPaySuccess
（写代码）
❌ 把状态切换写在 OrderController
❌ 没考虑退款时的状态校验
❌ 没发 MQ 通知
（逐条纠正...）
（第二版）
❌ 退款流程的允许状态忘记加 SHIPPING

你的指令："下单接口太慢了（P99 ~ 800ms），帮我优化一下"

完整知识库（积木 + 服务档案）
1 轮对话~5 分钟精准到行号
定位下单积木
搜索"下单"命中 order_create.md，时序图揭示完整链路：校验会员 → 批量查商品 → 锁库存 → 锁券，4 次 Feign 串行。
代码锚点直达源码
积木标注 OrderService.createOrder，AI 直接打开方法发现：会员校验和商品查询可以并行；锁库存与锁券有 try-compensate 依赖必须串行。
服务档案揭示优化空间
product-service.md 提到批量查询接口；member-service 的 get 接口可缓存。瓶颈清晰。
输出三个具体方案 + 代码
① 校验会员 + 查商品并行（CompletableFuture）省 ~150ms ② 会员等级缓存命中省 ~80ms ③ 库存锁与券锁保持串行（一致性边界）。每个方案附完整代码。
仅项目说明（CLAUDE.md）
3-4 轮对话~20 分钟方向对但不精准
下单接口太慢了，优化一下
我知道下单在 order-service。但我需要看具体代码——下单入口是哪个 Controller？
OrderService.createOrder
能贴一下这个方法的代码吗？我需要看具体调用链。
（贴代码 ~80 行）
看到 4 次串行调用。哪些步骤之间有强依赖？锁库存和锁券的顺序能否调整？
锁券失败要补偿释放库存，所以必须先锁库存再锁券
（输出方案）
✅ 方向正确：前两步并行 + 缓存
⚠️ 不知道现有缓存 key 命名
⚠️ 不确定线程池配置
无任何配置
6-10 轮对话30-60 分钟方案不落地
下单接口太慢了，优化一下
下单代码在哪个文件？涉及哪些下游服务？
order-service 的 OrderService.createOrder
能把代码贴给我看看吗？
（贴 200+ 行代码）
几个 Feign 客户端的接口能看一下吗？
（又贴几个服务的代码）
方案：
❌ 把锁库存和锁券改并行（破坏一致性）
❌ 引入新缓存框架（项目用现有方案）
❌ 不知道已有批量查询接口

三种模式核心差异

维度完整知识库仅项目说明无任何配置
对话轮次1 轮2-4 轮5-10 轮
时间成本~5 分钟15-20 分钟30-60 分钟
规范遵守自动遵守全部规范遵守已声明的规范频繁违反，需人工纠正
业务理解知道现有实现和扩展模式知道架构边界，不知道具体实现一无所知，全靠你喂
代码精度包路径、表名、枚举位置全对分层正确，细节靠猜基本靠猜，多次返工
你的角色Review 业务细节补充业务上下文当"人肉文档"
AI 角色熟悉项目的老员工读过入职手册的新人第一天的实习生

关键洞察：仅有项目说明（CLAUDE.md）解决了"规范遵守"问题——AI 不会再犯 Java 版本、分层违规这类低级错误。但它仍然不知道"具体业务怎么做"——哪些接口已经存在、数据怎么流转、异步消息怎么走。积木补齐的正是这一层：让 AI 从"知道规矩"升级到"熟悉业务"。

📈 为什么要用

对领导和开发者分别意味着什么

管理视角

3-5x
开发效率提升
新功能开发从需求到代码的时间大幅缩短，AI 能直接生成符合项目规范的代码骨架
↓70%
新人上手时间
知识库即文档，新成员通过阅读积木快速理解业务全貌，不再依赖口口相传
零流失
知识资产沉淀
核心业务逻辑、设计决策、异常处理经验全部版本化存储，人员变动不影响项目延续
↓50%
低级 Bug 率
AI 生成代码时自动遵循编码规范和异常处理模式，减少遗漏和不一致

开发者视角

告别重复劳动
CRUD、参数校验、异常处理等模式化代码由 AI 生成，你只需 review 和调整
上下文不丢失
不用每次都给 AI 解释项目背景，知识库提供持久化的项目上下文
学习加速器
通过阅读其他模块的积木，快速理解不熟悉的业务领域和技术实现

📁 知识库结构

一个 .ai 文件夹，四类核心文件，覆盖项目的方方面面

.ai/
├── OVERVIEW.md # 项目全景：技术栈、服务拓扑、部署架构
├── conventions.md # 编码规范：分层约定、命名规则、通用模式
├── CHANGELOG.md # 变更记录：积木新增/修改历史
├── blocks/ # 功能积木（核心）
│ ├── _index.md # 积木索引与分组
│ ├── _template.md # 新积木模板
│ ├── order_create.md # 示例：创建订单
│ ├── order_pay.md # 示例：订单支付
│ └── ... # 每个完整业务流程一个文件
└── services/ # 服务说明
    ├── mini-server.md # BFF 层服务职责与接口
    ├── order-service.md # 核心业务服务
    └── ...

关键设计原则：知识库跟随代码仓库版本管理，与代码同步演进。每次业务变更同步更新对应积木，保证知识库始终是"活"的。

积木文件结构

---
id: order_create
name: 创建订单
owner: order-team
services: [mini-server, order-service, member-service, product-service, promotion-service]
triggers: POST /api/mini/order
status: stable
---

## 时序图
```mermaid
sequenceDiagram
  participant C as 小程序
  participant M as mini-server
  participant O as order-service
  participant DB as MySQL
  C->>M: POST /api/mini/order
  M->>O: Feign 调用创建接口
  O->>DB: INSERT order
```

## 关键节点 # 每步的业务逻辑说明
## 异常路径 # 表格：场景 | 处理 | 返回
## 特殊说明 # 设计决策、注意事项

🔧 业务场景实战

不同开发场景下，如何配合 AI 和知识库高效工作

新增模块
修复 Bug
优化代码
重构代码

场景：需要新增一个"会员积分兑换"模块，涉及 mini-server → member-service → order-service 的跨服务调用。

参考已有积木，理解项目模式
阅读 .ai/blocks/ 中类似的积木（如 order_create），了解跨服务调用的标准模式、异常处理方式、事务边界划分。
编写新积木文档
用 vibe-blocks 一键生成积木骨架，填写 frontmatter、画时序图、列出关键节点和异常路径。这一步是"设计"，由开发者完成。
vibe-blocks new points_exchange --group 会员
让 AI 生成代码骨架
将积木文档 + conventions.md + 相关 service 文档提供给 AI，让它生成 Controller、Service、DTO、Feign Client 等代码。
Prompt: "根据 .ai/blocks/points_exchange.md 和 .ai/conventions.md，生成积分兑换功能的完整代码，遵循项目分层规范。"
Review 并补充业务细节
AI 生成的代码覆盖了标准模式，开发者补充特殊业务逻辑（如积分过期判断、并发扣减等），并更新积木文档。
更新索引和 CHANGELOG
vibe-blocks new 已经把积木自动注册到 _index.md；改动则记录到 CHANGELOG.md。

场景：线上反馈"订单支付成功后库存没扣减"，需要定位问题并修复。

通过积木定位调用链路
打开 .ai/blocks/order_pay.md，查看完整时序图，快速确认涉及哪些服务、哪些表、哪些 MQ 消息。
对照异常路径表排查
积木中的"异常路径"表格列出了已知的失败场景和处理方式，对照线上日志快速缩小排查范围。
让 AI 辅助分析
将积木文档 + 错误日志提供给 AI，让它基于完整上下文分析可能的原因。
Prompt: "根据 .ai/blocks/order_pay.md 的链路，分析以下错误日志的可能原因：[粘贴日志]"
修复并补充异常路径
修复代码后，如果是新发现的异常场景，补充到积木的异常路径表中，避免同类问题再次发生。

场景：商品详情页查询接口响应慢（P99 > 2s），需要性能优化。

查看积木了解完整数据流
通过 product_browse.md 了解查询涉及的表、关联查询、缓存策略，确认瓶颈可能在哪一层。
参考 conventions.md 中的缓存规范
项目规范中定义了 Redis 缓存的 key 命名、过期策略、更新模式（Cache-Aside），确保优化方案符合统一规范。
让 AI 生成优化方案
AI 基于积木上下文和规范，生成具体的优化代码（如添加二级缓存、优化 SQL、引入分页）。
Prompt: "根据 .ai/blocks/product_browse.md，这个查询 P99 > 2s，请基于 conventions.md 的缓存规范给出优化方案和代码。"
更新积木中的性能相关说明
在积木的"特殊说明"中记录优化策略（如"详情页走 Redis 缓存，商品变更时主动失效"），供后续维护参考。

场景：order-service 中"退款"逻辑过于臃肿，需要拆分为独立的 refund-service。

通过积木索引评估影响范围
在 _index.md 中筛选所有 services 字段含 order-service 且与退款相关的积木，明确哪些功能需要迁移。
梳理服务依赖关系
每个积木的 services 字段标明了涉及的服务，快速画出依赖图，确认拆分边界和影响面。
让 AI 生成迁移计划
将相关积木和服务文档提供给 AI，让它生成分步迁移方案，包括接口兼容、数据迁移、灰度策略。
Prompt: "以下积木需要从 order-service 迁移到新的 refund-service，请生成迁移计划：[积木列表]"
逐步迁移并同步更新知识库
每迁移一个积木，同步更新其 services 字段，新增 refund-service.md 服务文档。知识库始终反映当前架构。
验证完整性
迁移完成后，通过积木的时序图验证调用链路是否正确，确保没有遗漏的依赖。

⚖️ 传统开发 vs Vibe Coding

同样的工作，不同的效率和质量

维度传统方式Vibe Coding
新人了解业务问同事、翻代码、看零散文档，1-2 周阅读积木索引和时序图，2-3 天
新功能开发从零写代码，反复对齐规范AI 基于积木生成骨架，开发者补充业务细节
Bug 排查凭经验猜测，逐层 debug积木提供完整链路图，异常表缩小范围
知识传承口口相传，人走知识散版本化存储，与代码同步演进
代码一致性靠 Code Review 人工把关AI 自动遵循 conventions.md 规范
重构评估全局搜索 + 人工梳理依赖积木 services 字段直接标明影响范围

🚀 快速开始

用 vibe-blocks CLI 四个一键命令，5 分钟把积木体系接入你的项目

① 安装 vibe-blocks
用 pip 安装命令行工具，仅依赖 Python 3.8+ 和 click，零额外依赖。
pip install vibeblocks-cli
② 一键初始化 .ai/ 目录
自动生成 .ai/{blocks,services,references,decisions,prompts} 目录、CLAUDE.md、OVERVIEW.md、conventions.md、积木模板与索引。新项目从此具备 AI 编码上下文。
cd your-project && vibe-blocks init
③ 一键创建第一个积木
从内置模板生成新积木文件，自动注册到 _index.md 对应分组。开发者只需填写时序图和处理步骤。
vibe-blocks new order_create --name "创建订单" --services mini-server,order-service --group 订单
④ 一键生成可视化网页
解析所有积木 → 输出独立 HTML（自动推导服务拓扑 + 渲染 Mermaid 时序图），可直接在浏览器打开或部署到 GitHub Pages。
vibe-blocks build --output ./project-blocks.html
⑤ 一键刷新 CLAUDE.md
扫描项目结构识别技术栈（Java/Maven、Node/npm、Go、Python 等），把最新积木索引注入根目录 CLAUDE.md，让 Claude / Cursor 等 AI 助手自动加载完整业务上下文。
vibe-blocks claude-md

渐进式采用：不需要停下手头工作专门补文档。日常开发新功能时跑一次 vibe-blocks new，改 Bug 时补充异常路径，定期跑 vibe-blocks build 同步可视化。2-3 个迭代后知识库就能覆盖核心业务。

团队协作：把 .ai/ 目录纳入 Git 版本控制，PR 模板加入"积木更新检查项"，每次代码改动同步更新对应积木。AI 永远拿到最新上下文。

Vibe Coding 体系 · vibe-blocks · MIT License