架构先行用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 - 数据库SQLiterusqlite 0.31 bundledFTS5全文搜索WAL模式 - 向量存储BLOB嵌入 Rust原生余弦相似度 - LLMqwen3.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驱动知识管理工具帮助用户从文档导入→素材提取→摘要生成→学习问答→智能问答形成完整的知识管理闭环。”这个愿景明确了三个关键决策本地运行数据隐私优先不联网AI驱动核心处理流程依赖LLM知识闭环不是简单的文件管理而是输入→提炼→巩固→检索的完整链路第二步定义目标用户用户画像 - 知识工作者需要处理大量文档快速提炼核心信息 - 个人学习者希望系统化管理学习资料通过问答巩固理解第三步核心功能拆解通过对话将产品愿景拆解为可实现的功能模块文件导入多选批量 ↓ 文档分类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进程管理启动/停止/状态检测AiClientHTTP客户端chat/embed/extract/summaryOllamaSessionRAII生命周期管理ResourceMonitorCPU/内存检测延迟后台AI任务db层数据持久化13个文件覆盖所有业务表FTS5全文搜索 BLOB向量存储WAL模式读写不阻塞关键设计决策决策一commands层零业务逻辑// commands/qa.rs — 只做转发pubasyncfnqa_ask(app:AppHandle,state:State_,AppState,body:QaRequest)-ResultQaResponse,String{letunderstandingifai.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 COLUMNSQLite不支持ADD COLUMN IF NOT EXISTS迁移框架ROLLBACK后应用启动失败。修复方案迁移SQL改为SELECT 1;空操作仅作为版本标记。核心表设计-- 文件表元数据引用不复制文件本身CREATETABLEfiles(idINTEGERPRIMARYKEY,pathTEXTNOTNULL,filenameTEXTNOTNULL,doc_typeTEXT,-- 16类分类statusTEXTDEFAULTpending,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,contentmaterials,content_rowidmaterial_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个命令设计原则每个模块对应一个前端页面/功能命令粒度适中一个操作一个命令不过度拆分参数校验在commands层完成下游只处理已验证数据六、设计文档体系20篇文档的作用在整个开发过程中我维护了20篇设计文档每篇文档有明确的用途文档类型示例作用产品架构说明文档.md整体架构、模块设计、数据流数据库设计数据库Schema设计.md21个业务表DDL、ER图API接口API接口文档.md52个命令的完整签名优化方案项目优化方案.mdP0-P2三批优化任务质量优化素材与问答质量优化方案.md8项质量优化故障排查故障排查记录.md30个问题根因与修复检索优化QA检索精度优化方案.mdP0-P2六项检索优化发布清单发布工作清单.md必须/应该/锦上添花关键经验这些文档不是写完就放的。每完成一个优化或修复一个Bug对应的文档会同步更新。CLAUDE.md作为索引确保AI能快速定位到需要的文档。总结与互动本文展示了Vibe Coding中先设计后编码的方法论。核心理念是文档先行产品定义→技术方案→API设计→数据库Schema全部文档化后再动手写代码CLAUDE.md作为项目大脑架构记忆、决策记录、状态追踪的单一真相源增量演进数据库13个迁移文件设计文档20篇随功能迭代逐步完善下一篇我们将深入核心技术实现——Rust后端的4阶段AI处理Pipeline看看状态机设计、Prompt工程、错误处理等关键实现细节。讨论话题你在项目中是否使用过类似的项目大脑文档效果如何对于文档先行的开发方式你觉得最大的挑战是什么分层架构中commands层零业务逻辑的实践你在项目中如何处理 觉得有用请点赞收藏关注我获取更多Vibe Coding实战内容