tupingr
473f61b4cc
- 废弃 ADR-008 双分支+shell脚本方案（ai_project分支已过时） - 新增 project-init Skill：export（脱敏导出） + init（初始化新项目）双模式 - 保留 SYNC.md（框架/项目边界）+ TEMPLATE.yaml（变量定义） - L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本 - 3 文件替代 4文件+1分支，零维护成本 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
112 lines
8.7 KiB
Markdown
112 lines
8.7 KiB
Markdown
# 经验教训
|
||
|
||
## 目的
|
||
|
||
记录开发过程中学到的东西。每条记录包含：
|
||
- 上下文（我们在做什么）
|
||
- 问题（出了什么问题/什么让我们意外）
|
||
- 教训（学到了什么）
|
||
- 行动（因此改变了什么）
|
||
|
||
---
|
||
|
||
## L-001: 单体 AGENTS.md 浪费 AI 上下文
|
||
|
||
**日期**: 2026-05-25
|
||
**上下文**: 项目启动阶段，每次 AI 会话都需要读 AGENTS.md 来了解角色和权限
|
||
**问题**: AGENTS.md 239 行，约 80% 内容与当前 AI 角色无关。AI 有效上下文被大量无关信息占据
|
||
**教训**: 为人类设计的文档结构不适用于 AI 的信息获取模式。AI 需要"最少必要信息"，而不是"全局完整视图"
|
||
**行动**: 重构为分层信息架构：角色工作台 → 阶段上下文 → 知识沉淀。AI 只需读 2 个小文件即可开工
|
||
|
||
---
|
||
|
||
## L-002: 角色边界划分是 AI Agent 协作的反模式
|
||
|
||
**日期**: 2026-05-26
|
||
**上下文**: Phase 1 收尾后，重新审视「1 人 + 3 AI」的 Arch/Dev/QA 角色划分架构。调研了 2025-2026 年业界最新实践（MegaAgent、Claude Code Agent Swarm、Devin、JiuwenSwarm、Microsoft 多 Agent 参考架构等）
|
||
**问题**:
|
||
- 按角色边界（Arch/Dev/QA）划分 Agent 导致协调成本急剧上升，Token 消耗是单体的 3-10 倍
|
||
- Arch AI 承担了过多职责：架构设计 + 任务分配 + 文档维护 + 看板更新，成为单点瓶颈
|
||
- `.ai/` 目录膨胀到 47 个文件，但 Phase 2 代码一行还没写——架构本身成了负担
|
||
- Anthropic 和 Cognition（Devin）都承认：并行 Agent 在编码领域的实际收益有限，隐性决策冲突和整合成本往往超过并行收益
|
||
**教训**:
|
||
1. **按业务上下文划分，而非按角色划分**。正确的做法是「用户认证流 Agent」拥有路由+数据库+前端组件，「错题录入流 Agent」拥有拍照+图像处理+入库——每个 Agent 拥有完成任务所需的全部上下文
|
||
2. **架构规模应与项目阶段匹配**。Phase 1 只有需求+设计，不需要 47 个配置文件。应该在需要时渐进式添加，而非提前搭建「完整」架构
|
||
3. **调度层应该是确定性代码，而非 LLM**。用 LLM 做任务路由和状态更新是反模式——不稳定、成本高。这些应该用脚本/CI/工作流引擎实现
|
||
4. **子 Agent 的甜蜜点是只读研究，而非并行编码**。隔离上下文中做信息收集然后压缩回传——这是验证最有效的模式
|
||
5. **「高模型指挥小模型」的方向是对的，但规模要匹配**。1 人项目的「编排层」就是人类+Claude Code 本身，不需要额外的编排 Agent
|
||
**行动**:
|
||
- 启动 `.ai/` 配置精简审计，目标砍到 20 个文件以内
|
||
- Arch AI 的 today.md 和 queue.md 合并，消除重复
|
||
- Phase 3 前评估是否引入正式模型分层（Opus 做判断 → Sonnet/Haiku 做执行）
|
||
- 当前阶段保留角色划分但降低形式化程度，实际工作由 Claude Code 子 Agent 机制承载
|
||
|
||
---
|
||
|
||
## L-003: 知识库「生产者」流程缺失
|
||
|
||
**日期**: 2026-05-26
|
||
**上下文**: 一次关于 Agent 架构的深度讨论产生了有价值的洞察（L-002 + ADR-011 + P-004），但发现把这些洞察写入知识库的动作没有 formalized 流程
|
||
**问题**: `share-context` Skill 覆盖了知识库的「消费者」侧（.ai/knowledge/ → docs/share/），但「生产者」侧（开发讨论 → .ai/knowledge/）是断的。有价值的想法和教训可能因为没人记得写而丢失
|
||
**教训**: 一条完整的信息流水线需要两端都 formalized：摄入端（什么时候写、写到哪里、怎么写）和输出端（什么时候翻译、翻译成什么）。目前只有输出端
|
||
**行动**:
|
||
- 更新 `share-context` Skill，增加「反向检查」步骤：每次执行时先检查是否有未入库的讨论/想法
|
||
- 建立触发条件：当讨论产生「可复用的判断」「反直觉的发现」「被验证的错误方向」时，主动记录
|
||
|
||
---
|
||
|
||
## L-005: Arch AI 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策
|
||
|
||
**日期**: 2026-05-26
|
||
**上下文**: 持续数小时的高强度架构讨论（ADR-011、ADR-012、信息架构升级），Arch AI 的上下文窗口承载了全部对话历史
|
||
**问题**: 复杂任务容易让人想「一口气做完」，但 Arch AI 的上下文窗口有限。做一半触发自动压缩 → 前面的讨论、决策细节、已排除的选项全部丢失 → 后续判断基于不完整记忆 → 决策质量崩盘
|
||
**教训**:
|
||
1. **上下文不是无限的**。每次对话都是消耗品，越长的讨论越容易触发压缩
|
||
2. **决策即记录**。每个判断产生后立即写入 knowledge/，不留在对话里。对话是易失的，文件是持久的
|
||
3. **主动 checkpoint 优于被动压缩**。感觉吃力时主动收尾（commit + push），开新会话继续——带着干净记忆比带着残缺记忆强
|
||
4. **拆分到可提交粒度**。大任务拆成独立子任务，每个子任务结束后 commit。即使后续会话压缩，已完成的部分已经落地
|
||
**行动**:
|
||
- 写入 `.ai/principles.md` 作为 Arch AI 硬约束
|
||
- 任务前评估上下文余量
|
||
- 接近窗口上限时执行主动收尾协议：已完成 → commit → 告知人类进展 → 建议开新会话
|
||
|
||
---
|
||
|
||
## L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
|
||
|
||
**日期**: 2026-05-26
|
||
**上下文**: ADR-008 的「双分支 + sync-template.sh」模板同步方案，在新架构升级后 ai_project 分支严重过时。用户要求把脱敏模板价值提取到 main，放弃独立分支
|
||
**问题**:
|
||
- `sync-template.sh` 硬编码了旧架构的文件列表（DASHBOARD.md / ROADMAP.md / today.md / queue.md），框架一升级脚本就过时
|
||
- 维护一个独立 Git 分支的成本 > 收益：需要手动切换分支、跑脚本、处理冲突
|
||
- Shell 脚本的设计假设是「人类或 CI 执行」，但实际场景是 AI 执行。AI 不需要可执行脚本——AI 需要清晰的规格
|
||
**教训**:
|
||
1. **「用什么执行」决定「用什么描述」**。人/CI 执行 → 写脚本。AI 执行 → 写 Skill（语义描述 + 约束 + 边界定义）。Skill 描述「方法」，不会因文件路径变化而过时
|
||
2. **边界定义文件是长期资产，执行脚本是短期负债**。SYNC.md 定义了什么属于框架、什么属于项目——这个定义独立于任何执行方式。脚本绑定了执行方式，框架一变就废
|
||
3. **让 Git 做版本管理，让 Skill 做逻辑执行**。不需要为「脱敏」这个逻辑维护一个独立分支，Skill 从当前 main 实时执行脱敏，永远不过时
|
||
4. **3 文件 > 4 文件 + 1 分支**。新方案：SYNC.md + TEMPLATE.yaml + Skill。旧方案：SYNC.md + TEMPLATE.yaml + sync-template.sh + init.sh + ai_project 分支
|
||
**行动**:
|
||
- ADR-008 标记废弃，新增 ADR-013
|
||
- 废弃 sync-template.sh、init.sh、ai_project 分支
|
||
- 保留并更新 SYNC.md（框架/项目边界），新增 TEMPLATE.yaml（变量定义），新增 project-init Skill
|
||
|
||
---
|
||
|
||
## L-004: 跨平台 AI 协作下，文档是唯一的通信协议
|
||
|
||
**日期**: 2026-05-26
|
||
**上下文**: 澄清了实际的三平台配置——Arch AI (Claude Code + DeepSeek V4 Pro)、Coder AI (Trae CN + GLM-4.6)、Tester AI (Coze CN)。之前的设计假设所有角色在同一个 AI 平台内切换，这一假设被推翻
|
||
**问题**:
|
||
- 之前的架构分析得出了「精简文档」的结论（ADR-011），但这个结论基于错误的前提——以为所有 AI 共享同一个上下文空间
|
||
- 实际场景中，三个平台的 AI 之间**零共享上下文**。Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么，Coze 沙盒不会知道架构设计的动机
|
||
- 如果把文档精简了，Coder AI 拿到的 task 就会缺失关键上下文，GLM-4.6 又没有能力自行推断
|
||
**教训**:
|
||
1. **架构结论绑定于部署拓扑**。同一个设计，在「单平台多角色切换」和「跨平台多 Agent 协作」下是完全不同的东西。先搞清楚运行环境，再做架构决策
|
||
2. **跨平台协作中，Git 仓库不是存储，是通信介质**。每个 commit 是一次消息传递，每个文件是一份消息体。消息必须自包含，接收方不能依赖「上次聊过」
|
||
3. **任务交接密度必须适配接收方模型能力**。GLM-4.6 不是 Claude——不能给一个需要跨 5 个文件推理的任务。每个 task 应该是单文件或强内聚的 2-3 个文件
|
||
4. **低能力模型不是劣势，是约束**。只能处理小范围任务 → 强迫架构设计更清晰 → 反而减少 bug。这就是「限制产生创造力」
|
||
**行动**:
|
||
- 修正 ADR-011 的结论：不做精简，改为「重定位」——架构文档从内部备忘录升级为跨平台交接协议（ADR-012）
|
||
- Task 模板增加四个必填字段：输入、输出、约束、参考 ADR
|
||
- Dev queue.md 的每个任务需独立可读，不依赖前后文
|