chore(phase): Phase 1 收尾 — 一鸡多吃 + Dev工作台初始化 + Phase 2启动
- Phase 1 标记 100% 完成，Phase 2 标记 ACTIVE - Dev AI 工作台重写：8个任务入队 + 依赖关系图 - 一鸡多吃：6篇对外分享文章（项目缘起/框架思路/阶段复盘/3篇决策故事） - 新增 share-context Skill（内部文档→对外分享自动化） - P01 文档同步更新（需求/架构/接口定义） Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
tupingr
+81
-4
@@ -1,5 +1,82 @@
|
||||
# 项目缘起
|
||||
# 项目缘起：为什么我要做一个 AI 错题本
|
||||
|
||||
> *（待写：由 Arch AI 在 PRD 完成后撰写）*
|
||||
>
|
||||
> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。
|
||||
> 一个不会写代码的产品经理，用 AI 从零开发一个 App 的全记录。
|
||||
|
||||
---
|
||||
|
||||
## 起点：一个做了很多年的梦
|
||||
|
||||
我一直在做教育相关的事情。
|
||||
|
||||
这么多年来，我见过太多学生被同一个问题困扰：**错题整理太痛苦了**。手抄错题、自己分类、凭感觉复习——每一步都在消耗学生的耐心。而传统错题本 App 呢？拍照 OCR 识别率低、分类粗糙、推荐随机。用一个学生的话说：「花了半小时录入，得到的分析和我自己翻两页书差不多。」
|
||||
|
||||
我想做一个真正有用的错题本。但问题是：**我不会写代码。**
|
||||
|
||||
过去这个想法就只能停留在想法。直到 AI 编程工具出现了。
|
||||
|
||||
---
|
||||
|
||||
## 核心问题：AI 能写代码，但能做一个完整的产品吗？
|
||||
|
||||
2025 年底开始，AI 编程工具层出不穷。Cursor、Copilot、Claude Code——它们能帮你写函数、修 bug、甚至生成整个页面。
|
||||
|
||||
但我有一个更大的问题：**一个不会写代码的人，能不能靠 AI 从零做出一个能上线的产品？**
|
||||
|
||||
这不仅是写几段代码的问题，而是：
|
||||
|
||||
- 产品需求谁定？
|
||||
- 架构设计谁做？
|
||||
- 多个 AI 之间怎么分工？
|
||||
- AI 写的代码质量怎么保证？
|
||||
- 遇到 AI 解决不了的 bug 怎么办？
|
||||
|
||||
我决定用自己当实验品，把这个过程完整记录下来。
|
||||
|
||||
---
|
||||
|
||||
## 为什么选错题本
|
||||
|
||||
除了个人情结，还有一个技术判断：
|
||||
|
||||
**错题本是 AI 编程能力的最佳试金石。**
|
||||
|
||||
它需要：
|
||||
- 前端（小程序 UI）——考验 AI 的 UI 还原能力
|
||||
- 后端（API + 数据库）——考验 AI 的架构能力
|
||||
- AI 集成（OCR + 分类 + 推荐）——考验 AI 调用 AI 的能力
|
||||
- 图像处理（拍照增强 + 笔迹去除）——考验 AI 的算法能力
|
||||
- 数据闭环（用户修正 → 反哺训练）——考验 AI 的系统设计能力
|
||||
|
||||
能把这个项目做出来，基本上什么类型的 AI 编程任务都能覆盖了。
|
||||
|
||||
---
|
||||
|
||||
## 1 人 + 3 AI：我的协作模式
|
||||
|
||||
我给自己设计了一套「AI 团队」：
|
||||
|
||||
| 角色 | 做什么 | 权限 |
|
||||
|------|--------|------|
|
||||
| **Arch AI**（Claude） | 架构设计、PRD、技术选型、决策记录 | 读写文档 |
|
||||
| **Dev AI**（Claude + Coze） | 写代码、数据库、API、前端页面 | 读写代码 |
|
||||
| **QA AI**（Coze 沙盒） | 自动化测试、回归验证 | 只读代码 |
|
||||
|
||||
所有 AI 都听我指挥。我只负责三件事：**做决策、验结果、写分享。**
|
||||
|
||||
这套模式的核心思想是：人类决定「做什么」和「为什么」，AI 负责「怎么做」。
|
||||
|
||||
---
|
||||
|
||||
## 这个系列会记录什么
|
||||
|
||||
1. **产品从零到一**：PRD 怎么写、架构怎么设计、决策怎么做
|
||||
2. **AI 协作的真实体验**：AI 什么时候好用、什么时候翻车、怎么让 AI 配合工作
|
||||
3. **技术选型的思考**：为什么选这个不选那个，每一个选择背后的权衡
|
||||
4. **踩过的坑**：AI 写的代码跑了但不对、架构设计推翻重来、旧方案合并的痛苦
|
||||
5. **数据和思考**：每个阶段的交付物、决策记录、经验教训
|
||||
|
||||
这不是一个「AI 太强了帮我做了一切」的爽文。这是一个真实的、有成功有失败、有纠结有突破的开发记录。
|
||||
|
||||
---
|
||||
|
||||
*下一篇：[框架设计思路](01_框架设计思路.md) — 为什么传统的项目文档结构对 AI 不友好*
|
||||
|
||||
+105
-7
@@ -1,8 +1,106 @@
|
||||
# 框架设计思路
|
||||
# 框架设计思路：当文档的读者不是人类
|
||||
|
||||
> *（待写：信息架构重构稳定后撰写）*
|
||||
>
|
||||
> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。
|
||||
>
|
||||
> 对应 ADR：ADR-007
|
||||
> 背景参考：`.ai/principles.md`
|
||||
> 传统项目结构对 AI 不友好——我的信息架构是怎么一步步推到重来的。
|
||||
|
||||
---
|
||||
|
||||
## 问题的起点：AI 看不懂我的项目
|
||||
|
||||
第一次用 Claude Code 时，我兴奋地让它帮我写个功能。结果它盯着我的项目看了半天，然后开始瞎写。
|
||||
|
||||
问题不在 AI，在我的项目文档。
|
||||
|
||||
一个典型的人类项目文档是这样的：一个巨大的 README.md，里面塞了项目介绍、架构设计、API 文档、部署说明、开发规范……人类会跳着读，挑自己需要的部分。但 AI 不会跳读——它会从头到尾读完，然后在第 5000 行开始「记忆衰减」。
|
||||
|
||||
更致命的是：**不同 AI 角色需要的信息完全不同。** Dev AI 需要知道数据库表结构，不需要知道为什么 ADR-007 选了分层架构。但你把这些全混在一个文件里，AI 就只能全部消化。
|
||||
|
||||
结论：**为人类设计的文档结构，不适合 AI 协作。**
|
||||
|
||||
---
|
||||
|
||||
## 第一次尝试：从 README 到 AGENTS.md
|
||||
|
||||
我先学着社区的做法，把所有 AI 需要的信息写进一个 `AGENTS.md`。
|
||||
|
||||
一开始还行。但越写越长。PRD、架构、技术栈、目录结构、权限矩阵、ADR、Skill 定义……写到 2000 行的时候，AI 开始「忘记」前面的内容。
|
||||
|
||||
问题出在 **token 预算**。Claude 的上下文窗口约 200K token，看起来很大，但要同时装下 AGENTS.md + 当前代码文件 + 对话历史 + 输出内容，200K 很快就满了。
|
||||
|
||||
而且还有一个更隐蔽的问题：**不该看的东西 AI 也看了。** Dev AI 不需要知道 QA AI 的工作流，Arch AI 不需要知道具体代码实现。把不属于它的信息喂给它，既浪费 token，又容易干扰判断。
|
||||
|
||||
---
|
||||
|
||||
## 第二次重构：分层信息架构
|
||||
|
||||
关键洞察来自一个简单问题：**人类团队怎么分工？**
|
||||
|
||||
一个有 3 个人的团队，不会把所有信息贴在一面墙上让每个人读完。而是每人有自己的工作台，只看和自己相关的内容。跨角色共享的信息放在公共区域。
|
||||
|
||||
把这个逻辑搬到 AI 协作上：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ DASHBOARD.md │ ← 人类视角，30 秒了解全貌
|
||||
├─────────────────────────────────────────┤
|
||||
│ ROADMAP.md │ ← 人+AI 共享视野，任务看板
|
||||
├────────────────┬────────────┬───────────┤
|
||||
│ .ai/roles/ │ .ai/roles/ │ .ai/roles/ │
|
||||
│ arch/ ← Arch │ dev/ ← Dev │ qa/ ← QA │ ← 每人自己的工作台
|
||||
│ 今天干啥 │ 今天干啥 │ 今天干啥 │
|
||||
│ 任务队列 │ 任务队列 │ 测试计划 │
|
||||
├────────────────┴────────────┴───────────┤
|
||||
│ .ai/knowledge/ │ ← 共享知识库
|
||||
│ decisions.md（ADR） │
|
||||
│ journal/（开发日志） │
|
||||
├──────────────────────────────────────────┤
|
||||
│ docs/ │ ← 项目文档
|
||||
│ 01_产品需求/PRD.md │
|
||||
│ 02_系统架构/ │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
四层结构，每层有明确的 token 预算：
|
||||
|
||||
| 层 | 读者 | 内容 | token 预算 |
|
||||
|----|------|------|-----------|
|
||||
| 仪表盘 | 人类 | 30 秒全貌 | < 1K |
|
||||
| 路线图 | 人+AI | 任务看板 | < 3K |
|
||||
| 角色工作台 | 单个 AI | 今天干啥、任务详情 | < 2K |
|
||||
| 知识沉淀 | 所有 AI | ADR、经验教训 | 按需加载 |
|
||||
|
||||
**核心原则：每个 AI 启动时只加载自己那层的信息，不需要的永远不看。**
|
||||
|
||||
---
|
||||
|
||||
## Token 预算：把「省着用」变成设计原则
|
||||
|
||||
很多人觉得 token 窗口够大就不用省。但我的体验是：**省 token 不是为了省，是为了让 AI 注意力集中。**
|
||||
|
||||
给你一组对照实验：
|
||||
|
||||
```
|
||||
方案 A：把所有文档塞进 context → AI 的回复质量不稳定，后面的任务比前面的差
|
||||
方案 B：只给当前任务相关的文档 → AI 的回复质量和速度都明显更好
|
||||
```
|
||||
|
||||
原因很简单：AI 的注意力也是有限的。信息越多，它在噪音中找信号的难度越大。
|
||||
|
||||
分层架构的本质，就是**在正确的时刻，给正确的 AI，提供正确的信息量。**
|
||||
|
||||
---
|
||||
|
||||
## 「一鸡多吃」：分享层是怎么来的
|
||||
|
||||
架构稳定后，我发现一个有趣的事：我做的所有决策记录、项目文档、开发日志，天然就是很好的「对外分享素材」。
|
||||
|
||||
于是我的产出分两条线：
|
||||
- **内部线**（`.ai/`）：给 AI 看的，简短、结构化、有决策理由
|
||||
- **外部线**（`docs/share/`）：给人看的，有背景、有故事、有思考过程
|
||||
|
||||
同一份工作，两种产出。内部文档 → 去掉敏感信息 → 加上思考过程 → 对外文章。
|
||||
|
||||
这就是「一鸡多吃」——开发过程自动积累内容，阶段结束时翻译为对外语言。不需要「专门抽时间写分享」。
|
||||
|
||||
---
|
||||
|
||||
*下一篇：[Phase 1 阶段复盘](phase-01/阶段复盘_基础搭建.md) — 基础搭建阶段到底做了什么*
|
||||
|
||||
@@ -10,15 +10,17 @@
|
||||
|
||||
| 文件 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目 | 待写 |
|
||||
| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计 | 待写 |
|
||||
| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目、1 人+3 AI 协作模式 | ✅ 已完成 |
|
||||
| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计、token 预算概念 | ✅ 已完成 |
|
||||
|
||||
## 按阶段
|
||||
|
||||
| 阶段 | 复盘 | 决策故事 | 状态 |
|
||||
|------|------|----------|------|
|
||||
| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 故事](phase-01/决策故事_ADR-007.md) | 待写 |
|
||||
| Phase 2: MVP | — | — | 未开始 |
|
||||
| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 信息架构](phase-01/决策故事_ADR-007.md) | ✅ |
|
||||
| | | [ADR-009 人机协同](phase-01/决策故事_ADR-009.md) | ✅ |
|
||||
| | | [旧架构合并](phase-01/决策故事_旧架构合并.md) | ✅ |
|
||||
| Phase 2: MVP | — | — | 进行中 |
|
||||
|
||||
---
|
||||
|
||||
@@ -26,7 +28,7 @@
|
||||
|
||||
1. **不是做完再写**：开发过程中自动积累，阶段结束时翻译为对外语言
|
||||
2. **去掉内部细节**：不暴露 API 密钥、服务器地址、个人信息
|
||||
3. **加上思考过程**：不只说"做了什么"，更要说"为什么这么选"
|
||||
3. **加上思考过程**：不只说「做了什么」，更要说「为什么这么选」
|
||||
4. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解
|
||||
|
||||
## 内容来源
|
||||
|
||||
@@ -1,5 +1,75 @@
|
||||
# ADR-007 决策故事
|
||||
# ADR-007 决策故事：信息架构为什么从「大文档」变成「分层设计」
|
||||
|
||||
> 信息架构为什么从"单体文档"变成"分层设计"
|
||||
>
|
||||
> *（Phase 1 完成时撰写，基于 `.ai/knowledge/decisions.md` 中的 ADR-007 扩展）*
|
||||
## 背景
|
||||
|
||||
ErrLens 项目从一开始就确定用「1 人 + 3 AI」的协作模式——Arch AI 做架构，Dev AI 写代码，QA AI 做测试。
|
||||
|
||||
但怎么让 3 个 AI 高效协作？我最初的做法很朴素：写一个大的 AGENTS.md，把项目介绍、架构设计、开发规范、权限体系全塞进去，每个 AI 启动时都读这一份。
|
||||
|
||||
然后问题就来了。
|
||||
|
||||
---
|
||||
|
||||
## 问题：AI 记不住、看不懂、互相干扰
|
||||
|
||||
**第一个问题：记不住。**
|
||||
|
||||
AGENTS.md 写到 2000 行时，Claude 的回复开始出现明显的「失忆」——前面提到的决策，后面讨论时就忘了。原因是上下文窗口虽然号称 200K token，但越靠后的内容，AI 的关注权重越低。
|
||||
|
||||
**第二个问题：看不懂重点。**
|
||||
|
||||
AGENTS.md 里混了所有信息——PRD 摘要、架构图、API 定义、目录结构、权限矩阵、Skill 描述……Dev AI 需要在 2000 行里找到和自己相关的 200 行。人类会跳读，AI 不会——它全读完后，重点已经淹没了。
|
||||
|
||||
**第三个问题：互相干扰。**
|
||||
|
||||
一个更隐蔽的问题：Dev AI 不需要知道 QA AI 的测试流程，Arch AI 不需要知道具体的代码目录结构。把不该看的信息喂给 AI，不仅浪费 token，更容易让它「想太多」——写出过度设计或不相关的代码。
|
||||
|
||||
---
|
||||
|
||||
## 选项
|
||||
|
||||
| 选项 | 优势 | 劣势 |
|
||||
|------|------|------|
|
||||
| A: 维持单体文档 | 维护简单，改一处就行 | 越长越差，AI 协作天花板低 |
|
||||
| B: 精简 AGENTS.md | 立即可做 | 精简意味着丢掉信息，该有的细节还是要有的 |
|
||||
| C: 分层信息架构 | 每个 AI 只看自己的，token 利用率高 | 需要重新设计目录结构，上下游依赖要梳理清楚 |
|
||||
|
||||
---
|
||||
|
||||
## 思考过程
|
||||
|
||||
我一开始想走 B 路线——把 AGENTS.md 精简到 500 行以内。但很快发现不行：精简掉的内容不是「冗余」，是「必要的细节」。比如 Drizzle Schema 定义，对 Dev AI 就是刚需，你不能为了省 token 把它删了。
|
||||
|
||||
然后我想到一个类比：**人类团队怎么分工？**
|
||||
|
||||
一个有 3 个员工的团队，不会把所有信息贴在一面墙上。而是每人有独立工位，各自维护自己的待办和参考资料。共享的信息放在公共区域。
|
||||
|
||||
AI 也应该这样。
|
||||
|
||||
选项 C 的核心逻辑：
|
||||
|
||||
1. **仪表盘**（DASHBOARD.md）——给人类看，30 秒了解项目全貌，不写代码细节
|
||||
2. **路线图**（ROADMAP.md）——人+AI 共享视野，任务分配和进度跟踪
|
||||
3. **角色工作台**（`.ai/roles/{arch,dev,qa}/`）——每个 AI 自己的 today.md + queue.md，只加载自己需要的上下文
|
||||
4. **知识沉淀**（`.ai/knowledge/`）——ADR（架构决策记录）、journal（开发日志），按需加载
|
||||
|
||||
每层有 token 预算。Arch AI 启动时加载约 3K token（today + queue + decisions），Dev AI 类似。比单体 AGENTS.md 的 15K+ token 减少了 80%。
|
||||
|
||||
---
|
||||
|
||||
## 结果
|
||||
|
||||
分层后，几个明显的变化：
|
||||
|
||||
- **AI 回复质量更稳定**：不再出现「前面说了后面忘」的情况
|
||||
- **上下文切换更快**：Dev AI 启动直接读 dev/today.md，不需要从 PRD 开始消化
|
||||
- **人类管理成本降低**：DASHBOARD.md 一眼看到项目状态，不需要翻 10 个文件
|
||||
- **「一鸡多吃」变得自然**：内部分层文档 → 去掉敏感信息 → 对外分享文章，流水线化
|
||||
|
||||
如果重来一次，我会从第一天就做分层。单体文档阶段浪费了大约 1 天的 AI token 和人类审核精力。
|
||||
|
||||
---
|
||||
|
||||
## 一句话总结
|
||||
|
||||
**为 AI 设计文档和为人设计文档，是完全不同的两件事。人会跳读，AI 不会——所以你的信息架构就是 AI 的注意力分配方案。**
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# ADR-009 决策故事：当 AI 识别不完美时，产品怎么设计
|
||||
|
||||
## 背景
|
||||
|
||||
ErrLens 的核心功能是：学生拍一张错题照片 → AI 识别题目内容 → 自动归类 → 分析错误原因 → 推荐同类练习。
|
||||
|
||||
这个流程看起来很美好，但它建立在一个脆弱的假设上：**AI 能准确识别每一张照片。**
|
||||
|
||||
现实是：中小学生的手写体，潦草起来连老师都看不懂。打印体 OCR 准确率可以到 95%+，但手写体的天花板大概在 70-80%。而且不只是 OCR——学科分类、知识点标注、错误类型诊断，每一步都可能出错。
|
||||
|
||||
第一个版本的 PRD 里，我完全没考虑这个问题。数据流画得很漂亮：「拍照 → AI 识别 → 入库 → 分析 → 推荐」，仿佛 AI 不会出错。
|
||||
|
||||
直到有人问我：「万一 AI 识别错了呢？」
|
||||
|
||||
---
|
||||
|
||||
## 问题：错误数据会污染整个系统
|
||||
|
||||
如果 AI 把「二次函数顶点坐标」错标成「一次函数斜率」，会发生什么？
|
||||
|
||||
1. 错题归到错误的知识点
|
||||
2. 薄弱点分析显示「一次函数薄弱」，实际是二次函数有问题
|
||||
3. 推荐系统给了 10 道一次函数的练习——和学生的真实弱项毫无关系
|
||||
4. 学生发现推荐不准确 → 不信任产品 → 弃用
|
||||
|
||||
**一条错误数据进入分析管道，污染的是整个推荐飞轮。**
|
||||
|
||||
传统方案的思路是「提高 AI 准确率」——换更好的模型、加训练数据、调 prompt。但这条路的天花板很明显：手写体 OCR 准确率从 70% 提升到 85% 已经很难了，90% 在可见的将来都不现实。
|
||||
|
||||
而且，即使到了 90%，每 10 道错题就有 1 道是错的。100 道里有 10 道。对学生来说，10 次错误的推荐 = 再也不用了。
|
||||
|
||||
---
|
||||
|
||||
## 灵感：AI 做不好的事，让人来做
|
||||
|
||||
问题的本质是：**AI 做识别很强但不够完美，人做识别很准但太慢。**
|
||||
|
||||
那能不能结合起来？
|
||||
|
||||
我当时想到一个关键洞察：**学生本来就要看自己拍了什么。** 拍照录入的过程不是「拍完就完了」，用户本来就会确认「这张照片拍清楚了吗」「题目对吗」。这个「确认」动作，天然就是数据校验的机会。
|
||||
|
||||
于是设计了这样一个流程：
|
||||
|
||||
```
|
||||
AI 识别结果不是「答案」，是「草稿」
|
||||
↓
|
||||
每个字段带置信度（这条我有多确定）
|
||||
↓
|
||||
高置信（>90%）：绿色标记，用户看一眼就行
|
||||
中置信（70%-90%）：黄色提示，建议检查
|
||||
低置信（<70%）：红色高亮，请手动修正
|
||||
↓
|
||||
用户确认/修正后 → 入库 → 进入分析管道
|
||||
未经确认的数据 → 仅自己可见，不参与分析和推荐
|
||||
```
|
||||
|
||||
核心设计原则：**AI 是草稿，用户是编辑。分析管道只吃「干净数据」。**
|
||||
|
||||
---
|
||||
|
||||
## 隐藏收益：每一次修正都是免费的标注数据
|
||||
|
||||
做到这一步后，我发现还有一个更大的收益。
|
||||
|
||||
用户修正时，系统记录两个值：
|
||||
- `ai_value`：AI 的原始识别结果（比如标注为「二次函数顶点坐标」）
|
||||
- `user_value`：用户修正后的值（实际是「二次函数图像性质」）
|
||||
- `ai_confidence`：AI 当时对这个判断的置信度（0.72）
|
||||
|
||||
这条修正记录（CorrectionLog）就是一条**完美的标注数据**：
|
||||
|
||||
- 有原始模型输出（ai_value）
|
||||
- 有人工标注结果（user_value）
|
||||
- 有模型当时的置信度（可用于误差分析）
|
||||
|
||||
传统 AI 训练需要花钱请人标注数据。ErrLens 的标注员是用户——而且他们免费标注，甚至感谢你给了他们一个「修正」的功能。
|
||||
|
||||
P02 阶段（自研模型），这些 CorrectionLog 就是核心训练数据。产品用得越多，修正记录越多，模型越强——这是真正的数据飞轮。
|
||||
|
||||
---
|
||||
|
||||
## 结果
|
||||
|
||||
- error_items 表新增 `verification_status`（raw→reviewed→corrected→stale）和 `ai_confidence`（JSONB）
|
||||
- 新增 `correction_logs` 表，记录每一条人机修正
|
||||
- 分析/推荐查询强制加 `WHERE verification_status != 'raw'`
|
||||
- 前端 UI 设计绿/黄/红三级置信度指示
|
||||
|
||||
---
|
||||
|
||||
## 一句话总结
|
||||
|
||||
**AI 的弱点不一定是产品的弱点——如果你能设计一个把「AI 错误」变成「用户价值」的闭环。**
|
||||
@@ -0,0 +1,87 @@
|
||||
# 决策故事：当两个架构要合并——30 项决策是怎么做的
|
||||
|
||||
## 背景
|
||||
|
||||
ErrLens 不是一个从零开始的项目。
|
||||
|
||||
在正式立项之前，我已经花了几周时间写了一个叫「家庭教育小程序」的架构设计——17 份文档，约 60,000 字，覆盖了小程序端、数据库、图像处理、交互设计、UI 规范、测试方案、部署方案等方方面面。
|
||||
|
||||
唯一的问题是：那个架构是面向「小学 5-6 年级学生家长 + 仅数学」的，用的是「微信云开发 + 云函数」的技术栈。而 ErrLens 定位已经变成了「小学初中学生 + 数学英语 + 自建后端」。
|
||||
|
||||
两套架构，一个旧一个新，重叠但不兼容。旧架构不能直接复用——技术栈变了。但也不能扔掉——里面有很多经过 Spike 验证的工程方案（图像处理管线、打印设计、UI 规范）。
|
||||
|
||||
问题变成：**怎么系统地把旧架构中有价值的部分提取出来，合并到新架构里，而不是陷入无休止的细节讨论？**
|
||||
|
||||
---
|
||||
|
||||
## 方法：结构化对比，逐项决策
|
||||
|
||||
我让 Arch AI 把 17 份旧文档全部读完后，把两套架构的差异拆成 30 个独立维度，按性质分成四类：
|
||||
|
||||
### 第一类：冲突项（8 项）
|
||||
|
||||
两套设计说了不同的话，必须二选一。
|
||||
|
||||
| 示例 | 旧架构 | 新架构 | 结论 |
|
||||
|------|--------|--------|------|
|
||||
| 技术栈 | 微信云开发 | NestJS + PostgreSQL | 选新架构，因为需要 Coze 沙盒自动化测试 |
|
||||
| 目标用户 | 家长操作 | 学生本人 | 两者都要，学生和家长都可以操作 |
|
||||
| 学科范围 | 仅数学 | 数学+英语 | 新架构已锁定 |
|
||||
|
||||
### 第二类：旧有新增（9 项）
|
||||
|
||||
旧架构有但新架构缺失的有价值功能。
|
||||
|
||||
| 示例 | 旧架构设计 | 决定 |
|
||||
|------|-----------|------|
|
||||
| 错题打印 | 完整 PDF 生成+下载流程 | 纳入 MVP，P0 |
|
||||
| 图像预处理管线 | CLAHE+笔迹去除，经 Spike 验证 | 前置到 OCR 之前 |
|
||||
| UI 设计规范 | 完整规范文档，28 个图标 | 整体迁移 |
|
||||
|
||||
### 第三类：新有新增（7 项）
|
||||
|
||||
新架构创新，旧架构完全没有。直接保留，不讨论。
|
||||
|
||||
### 第四类：各有优劣（6 项）
|
||||
|
||||
两边方案各有利弊，需要权衡。
|
||||
|
||||
| 示例 | 结论 |
|
||||
|------|------|
|
||||
| 知识点编码：业务编码 vs 数字 ID | 两者并存，ID 内部关联 + code 对外暴露 |
|
||||
| 题目匹配：关键词 vs AI 语义 | 两阶段：关键词粗筛 → AI 精排 |
|
||||
|
||||
30 项决策，逐条过。人类拍板，AI 记录，一项一项写入架构文档。
|
||||
|
||||
---
|
||||
|
||||
## 思考：为什么能在一小时内完成 30 个决策？
|
||||
|
||||
如果让我一个人对着两份架构文档做合并，至少需要两天——读旧文档需要半天，对比需要一天，写合并方案再半天。
|
||||
|
||||
但 AI 可以：
|
||||
|
||||
1. **并行阅读**：17 份旧文档在 30 秒内全部读完并提取要点
|
||||
2. **结构化拆解**：自动将差异按「冲突/新增/缺失/优劣」分类
|
||||
3. **草拟选项**：每个维度列出优劣对比，方便人类判断
|
||||
4. **即时落地**：决策一旦确认，5 分钟内更新完所有相关文档
|
||||
|
||||
人类的角色非常清晰：**做判断。** AI 负责列出选项、分析利弊、写成文档——人类只需要说「同意」「不同意」或「换个方案」。
|
||||
|
||||
这个协作模式的核心是：**人类不需要被 AI 告诉该怎么做，而是让 AI 把所有信息准备好，自己做决定。**
|
||||
|
||||
---
|
||||
|
||||
## 关键收获
|
||||
|
||||
1. **分类框架是决策效率的关键。** 「冲突/新增/缺失/优劣」这个四象限让复杂对比变得可管理。下次遇到类似问题可以直接复用。
|
||||
|
||||
2. **决策粒度要适中。** 太细（每个字段风格讨论）浪费精力，太粗（「技术栈全换」一句话）埋隐患。30 项这个数量级刚好——半天做完，该覆盖的都覆盖了。
|
||||
|
||||
3. **旧资产不要扔。** 旧架构虽然技术栈变了，但设计思路、工程参数、Spike 验证结论都是真金白银的积累。要有系统的方法提取价值。
|
||||
|
||||
---
|
||||
|
||||
## 一句话总结
|
||||
|
||||
**架构合并不需要你穷尽每一个细节。把它拆成独立的决策单元，人类逐项拍板，AI 负责剩下的——这就是「人机协同」在架构设计上的应用。**
|
||||
@@ -1,3 +1,80 @@
|
||||
# Phase 1: 基础搭建 — 阶段复盘
|
||||
# Phase 1 阶段复盘：基础搭建
|
||||
|
||||
> *（Phase 1 完成时由 Arch AI 撰写，基于 `.ai/phases/phase-01-foundation/completion.md` 扩展）*
|
||||
## 阶段信息
|
||||
|
||||
- 阶段编号：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 启动自动化测试。
|
||||
|
||||
Reference in New Issue
Block a user