2026-06-08-架构先行-用AI对话式完成产品定义到技术架构

架构先行：用AI对话式完成产品定义到技术架构

Vibe Coding不是让AI乱写代码，而是先让AI帮你做架构设计。本文揭秘CLAUDE.md如何作为"项目大脑"驱动整个开发过程，以及如何用对话式方式完成从产品愿景到数据库Schema的完整架构设计。

一、CLAUDE.md：项目的大脑

在Vibe Coding中，CLAUDE.md是最关键的角色。它不是一个简单的README，而是整个项目的单一真相源（Single Source of Truth）。

为什么需要CLAUDE.md？

想象一个场景：你让AI帮你开发一个知识管理工具。如果每次对话都是从零开始，AI会：

• 忘记上次的技术决策
• 重复已经废弃的方案
• 不知道哪些模块已完成、哪些待开发
• 无法保证代码风格的一致性

CLAUDE.md解决了这个问题。它是AI在每次对话开始时都会读取的"项目上下文"，相当于给AI装了一个持久化的"记忆"。

CLAUDE.md的核心结构

1. 重要原则（核心要求） ← 项目红线，AI不可违反 2. 项目开发强制规范 ← 代码质量标准 3. 核心工作流 ← 探索→规划→实现→提交 4. 通用编码规范 ← 全语言统一规则 5. 项目概述 ← 一句话定位 6. 技术栈 ← 精确到版本号 7. 核心特性 ← 功能清单 8. 项目结构 ← 目录树 9. 项目相关设计文件 ← 20+篇文档索引 10. 已知问题 & 优化状态 ← 30个问题追踪表

关键设计：第9节"项目相关设计文件"是一个索引表，列出了20+篇设计文档的路径、用途和适用场景。这让AI在需要深入某个模块时，能精确定位到对应的文档。

CLAUDE.md的三个核心作用

作用一：架构记忆

## 技术栈 - 框架：Tauri 2 + Rust（单进程双击即用） - 前端：React 18 + TypeScript + TailwindCSS 4 - 数据库：SQLite（rusqlite 0.31 bundled，FTS5全文搜索，WAL模式） - 向量存储：BLOB嵌入 + Rust原生余弦相似度 - LLM：qwen3.5:4b（本地）+ api.enterprise.com/gpu/llm-397b（远程397B MoE）

这些技术决策一旦确定，就写入CLAUDE.md。后续所有开发都以这些决策为准，AI不会擅自更换技术栈。

作用二：状态追踪

| # | 问题 | 优先级 | 状态 | |----|---------------------------|--------|---------| | 1 | Layout.tsx 过重（~800行） | P0 | ✅ 已完成 | | 13 | CJK BM25 AND查询过严 | Bug | ✅ 已修复 | | 29 | PPT逐页提取方案 | Feature | ❌ 已取消 |

30个问题及其状态的完整追踪表，确保AI始终了解项目的当前状态，不会重复处理已解决的问题。

作用三：变更记录

## 远程LLM模型支持 — 已完成 改动文件：client.rs、settings_cmd.rs、qa.rs、service.rs... 模型选型结论：397B非推理模型替代某27B推理模型（504超时问题）

每次重大变更都会记录到CLAUDE.md，形成完整的变更历史。

二、产品定义阶段：对话式设计

Vibe Coding的产品定义不是一个人闭门造车，而是通过与AI的对话式迭代完成的。

第一步：明确产品愿景

“构建一个完全基于本地运行的AI驱动知识管理工具，帮助用户从文档导入→素材提取→摘要生成→学习问答→智能问答，形成完整的知识管理闭环。”

这个愿景明确了三个关键决策：

1. 本地运行：数据隐私优先，不联网
2. AI驱动：核心处理流程依赖LLM
3. 知识闭环：不是简单的文件管理，而是"输入→提炼→巩固→检索"的完整链路

第二步：定义目标用户

用户画像： - 知识工作者：需要处理大量文档，快速提炼核心信息 - 个人学习者：希望系统化管理学习资料，通过问答巩固理解

第三步：核心功能拆解

通过对话将产品愿景拆解为可实现的功能模块：

文件导入（多选批量） ↓ 文档分类（16类规则引擎） ↓ AI素材提取（5类：case/data/method/framework/conclusion） ↓ AI摘要生成（基于素材聚合） ↓ AI问答生成（4维度：概念/方法/应用/洞察） ↓ RAG智能问答（多轮对话+来源引用）

踩坑记录：最初设计时把"文件监听/自动扫描"作为核心功能。实施后发现它会导致不需要的自动导入，最终在lib.rs中注释掉约200行代码将其禁用。这个教训说明：在产品定义阶段就要想清楚哪些功能是必要的，哪些是"有了更好"的。

三、技术方案设计：分层架构

架构设计是Vibe Coding中人主导AI辅助的核心环节。我定义了清晰的分层架构，AI在这个框架内实现细节。

模块架构

┌─────────────────────────────────────────────────────┐ │ React 前端 │ │ ┌──────────┐ ┌──────────┐ ┌─────────────────────┐ │ │ │ 文件列表 │ │ 文件详情 │ │ 知识问答 │ │ │ └────┬─────┘ └────┬─────┘ └─────────┬───────────┘ │ │ ┌────▼────────────▼─────────────────▼───────────┐ │ │ │ api.ts (invoke 封装层) │ │ │ └───────────────────┬───────────────────────────┘ │ ├──────────────────────┼──────────────────────────────┤ │ Tauri Bridge (ipc) │ ├──────────────────────┼──────────────────────────────┤ │ Rust 后端 │ │ ┌──────────┐ ┌─────┴─────┐ ┌────────────────┐ │ │ │ commands │ │ pipeline │ │ ai_service │ │ │ │ 52命令 │ │ 4阶段处理 │ │ Ollama客户端 │ │ │ └────┬─────┘ └─────┬─────┘ └───────┬────────┘ │ │ ┌────▼──────────────▼────────────────▼────────┐ │ │ │ db (rusqlite + FTS5) │ │ │ │ files │ materials │ embeddings │ questions │ │ │ └─────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘

模块职责划分

commands层（API网关）：

• 52个Tauri命令，10个模块
• 只做参数校验和调用转发，不包含业务逻辑
• 对应前端api.ts的33个函数

pipeline层（业务核心）：

• 4阶段处理：解析→素材提取→摘要→问答
• 状态机驱动，支持中断恢复
• 每个阶段独立，可单独触发

ai_service层（AI集成）：

• OllamaManager：进程管理（启动/停止/状态检测）
• AiClient：HTTP客户端（chat/embed/extract/summary）
• OllamaSession：RAII生命周期管理
• ResourceMonitor：CPU/内存检测，延迟后台AI任务

db层（数据持久化）：

• 13个文件，覆盖所有业务表
• FTS5全文搜索 + BLOB向量存储
• WAL模式，读写不阻塞

关键设计决策

决策一：commands层零业务逻辑

// commands/qa.rs — 只做转发pubasyncfnqa_ask(app:AppHandle,state:State<'_,AppState>,body:QaRequest)->Result<QaResponse,String>{letunderstanding=ifai.provider()=="openai"{None// 远程模式跳过LLM意图理解}else{ai.understand_query(&body.question)?// 本地模式启用};// 检索、上下文构建、LLM调用全部在service层QaService::ask(&conn,&ai,&body,understanding,body.kb_id)}

好处：前端可以直接映射到后端API，接口契约清晰。

决策二：Pipeline状态与文件状态分离

-- 文件主状态status: pending → processing → ready-- 素材子状态material_status: pending → extracting → extracted/error-- 摘要子状态summary_status: pending → generating → generated-- 问答子状态question_status: pending → generating → generated/failed

好处：每个子任务独立追踪，中断恢复时可以精确续传。

四、数据库设计：13个迁移文件的演进

数据库不是一次性设计完成的，而是随着功能迭代逐步演进。

迁移时间线

001_init.sql ← 核心表：files, file_contents, embeddings, FTS5 002_settings.sql ← 用户设置表 003_file_relations.sql ← 文件关联 004_questions.sql ← 问答表 005_materials.sql ← 素材表（AI提取的结构化知识） 006_status_tracking.sql ← Pipeline状态追踪列 007_qa_conversations.sql ← QA会话表 008_retry_count.sql ← 重试计数（解决扫描PDF无限重试） 009_materials_fts.sql ← 素材级FTS5搜索（支持CJK字符级分词） 010_indexes.sql ← 性能索引 011_is_table_content.sql ← 表格内容标记 012_knowledge_bases.sql ← 子知识库 013_reset_embeddings.sql ← 嵌入向量重置

踩坑记录：008_retry_count.sql差点导致应用崩溃。列在调试时已手动添加，但迁移文件再次尝试ALTER TABLE ADD COLUMN，SQLite不支持ADD COLUMN IF NOT EXISTS，迁移框架ROLLBACK后应用启动失败。修复方案：迁移SQL改为SELECT 1;空操作，仅作为版本标记。

核心表设计

-- 文件表：元数据引用，不复制文件本身CREATETABLEfiles(idINTEGERPRIMARYKEY,pathTEXTNOTNULL,filenameTEXTNOTNULL,doc_typeTEXT,-- 16类分类statusTEXTDEFAULT'pending',material_statusTEXT,-- 素材提取状态summary_statusTEXT,-- 摘要状态question_statusTEXT,-- 问答状态summaryTEXT,-- AI生成摘要kb_idINTEGER,-- 子知识库归属...);-- 素材表：AI提取的结构化知识单元CREATETABLEmaterials(idINTEGERPRIMARYKEY,file_idINTEGERREFERENCESfiles(id),contentTEXTNOTNULL,content_typeTEXT,-- case/data/method/framework/conclusiontags_jsonTEXT,-- 行业标签confidenceREAL,-- AI置信度...);-- FTS5虚拟表：素材级全文搜索CREATEVIRTUALTABLEmaterials_ftsUSINGfts5(content,content='materials',content_rowid='material_id');

五、API接口设计：52个命令的分层组织

52个Tauri命令按功能域组织为10个模块：

commands/ ├── files.rs ← 文件导入/列表/删除（4个命令） ├── material.rs ← 素材操作（3个命令） ├── summary.rs ← 摘要操作（2个命令） ├── question.rs ← 问答操作（4个命令） ├── qa.rs ← RAG问答（2个命令） ├── search.rs ← 搜索（3个命令） ├── knowledge.rs ← 知识图谱（10个命令，未编译） ├── dashboard.rs ← 仪表盘（4个命令，未编译） ├── kb.rs ← 子知识库（4个命令） ├── settings_cmd.rs ← 设置（5个命令） ├── classification.rs ← 分类（3个命令） └── library.rs ← 文件库管理（4个命令）

设计原则：

1. 每个模块对应一个前端页面/功能
2. 命令粒度适中：一个操作一个命令，不过度拆分
3. 参数校验在commands层完成，下游只处理已验证数据

六、设计文档体系：20+篇文档的作用

在整个开发过程中，我维护了20+篇设计文档，每篇文档有明确的用途：

关键经验：这些文档不是"写完就放"的。每完成一个优化或修复一个Bug，对应的文档会同步更新。CLAUDE.md作为索引，确保AI能快速定位到需要的文档。

总结与互动

本文展示了Vibe Coding中"先设计后编码"的方法论。核心理念是：

1. 文档先行：产品定义→技术方案→API设计→数据库Schema，全部文档化后再动手写代码
2. CLAUDE.md作为项目大脑：架构记忆、决策记录、状态追踪的单一真相源
3. 增量演进：数据库13个迁移文件，设计文档20+篇，随功能迭代逐步完善

下一篇，我们将深入核心技术实现——Rust后端的4阶段AI处理Pipeline，看看状态机设计、Prompt工程、错误处理等关键实现细节。

💬讨论话题：

1. 你在项目中是否使用过类似的"项目大脑"文档？效果如何？
2. 对于"文档先行"的开发方式，你觉得最大的挑战是什么？
3. 分层架构中，commands层零业务逻辑的实践，你在项目中如何处理？

👍 觉得有用请点赞收藏，关注我获取更多Vibe Coding实战内容！