ai_soc_sw/docs/share/phase-01/阶段复盘_基础搭建.md

Phase 1 阶段复盘：基础搭建

阶段信息

• 阶段编号：Phase 1/4
• 阶段名称：基础搭建
• 时间范围：2026-05-23 ~ 2026-05-26（4 天）
• 参与角色：人类 + Arch AI（Claude）

做了什么

Phase 1 不写一行业务代码。目标是「把骨架搭好，让 AI 知道该做什么」：

1. 信息架构重构（ADR-007）：从单体 AGENTS.md 到四层分层架构
2. PRD 编写（v0.3.0 → v0.4.0）：完整的错题本产品需求文档，含人机协同数据闭环
3. 系统架构设计（v0.3.0 → v0.4.0）：总体架构、技术选型、模块设计、数据模型
4. 旧架构合并：将早期「家庭教育小程序」的 17 份架构文档与当前设计对比，30 项决策逐项确认
5. Dev AI 工作台初始化：8 个开发任务入队，含依赖关系图

交付物：10 份文档，约 30,000 字。

关键决策

决策 1：人机协同数据闭环（ADR-009）

问题：AI OCR 对手写体的识别率不可能 100%，错误数据直接进入分析会污染整个系统。

方案：「AI 是草稿，用户是编辑。」AI 识别结果带置信度入库，用户确认/修正后才进入分析管道。每一次修正都是免费的标注数据，P02 阶段用于训练自有模型。

为什么重要：这是产品数据飞轮的核心设计。没有这个闭环，产品就是普通的拍照 OCR 工具。

决策 2：分层信息架构（ADR-007）

问题：单体 AGENTS.md 太长，AI 注意力衰减，不同角色的信息混在一起。

方案：四层结构——仪表盘（人类）→ 路线图（共享）→ 角色工作台（AI 个人）→ 知识沉淀（共享）。每个 AI 只加载自己需要的信息。

为什么重要：这是整个 AI 协作模式的基础。没有好的信息架构，AI 再多也协同不起来。

决策 3：旧架构合并

问题：之前写的「家庭教育小程序」架构文档（17 份，约 60,000 字）不能白写，但又不能简单照搬——技术栈、用户定位、学科范围全变了。

方案：逐项对比，分成「冲突」「旧有新增」「新有新增」「各有优劣」四类，30 项决策逐条确认后统一写入新架构。

为什么重要：这是第一次「AI 辅助做架构合并」的实践。30 个决策不是 AI 自己拍板的，是人类逐条确认的。这个流程本身是一个可复用的方法论。

踩过的坑

坑 1：Edit 工具字符串匹配失败

短字符串替换没问题，但一次替换多个段落时经常找不到。原因是前面的修改已经改变了文件内容，后续匹配的目标字符串已不匹配。

解法：大段落修改拆成多次小修改，每次改动后确认文件当前状态再改下一个。宁可多改几次，不要一次写一大段。

坑 2：数据飞轮第一版太天真

最初的 PRD 版本假设「AI 拍完照就能完美识别」。被指出后才意识到这是核心风险。后来整个飞轮设计推翻重写——从「AI 完美假设」变成「人机协同闭环」。

教训：架构评审中，人的经验和直觉是 AI 替代不了的。AI 擅长帮你把想法落地成文档，但不会主动挑战你的假设。

学到的东西

1. AI 协作的效率瓶颈不在 AI，在信息组织。 文档写得好，AI 输出质量就高；文档一团乱，再强的模型也白搭。
2. 人类做决策，AI 做执行，是最佳的协作模式。 30 项旧架构合并决策，AI 列出选项和优劣，人类逐条拍板，AI 写入文档——这个流程的效率远超纯人工或纯 AI。
3. 架构文档应该「分层写」。 不是一份文档覆盖所有细节，而是不同层次的文档给不同角色看。这和代码的「关注点分离」是一个道理。
4. 旧资产不要扔。 旧架构文档虽然技术栈变了，但图像处理管线、打印设计、UI 规范、测试用例都是可复用资产。关键是要有一个结构化的对比流程来提取价值。

数据

• 新增/更新文档：17 份（不含旧架构原文件）
• 总字数：约 30,000 字（PRD + 4 份架构文档 + ADR + 看板 + 分享内容）
• 架构决策记录：10 条（ADR-001 ~ ADR-010）
• 旧架构合并决策：30 项
• Dev 任务入队：8 个
• 代码行数：0（Phase 1 不写代码）

下一阶段预告

Phase 2 MVP：数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架。Dev AI 开始写代码，QA AI 启动自动化测试。