tupingr
6992f59cd2
核心变化： - dashboard.md 替代 DASHBOARD + ROADMAP，人类+Arch AI 唯一入口 - DECISIONS.md 人类决策入口，≤3 条待决策 - .ai/tasks/ 14 个独立 task 文件（Coder 8 + Tester 6），弱模型自包含可独立执行 - 旧 today/queue 归档，每个角色启动 ≤2 个文件 - ADR-012 跨平台「高模型指挥小模型」协作架构落地 - 知识库补全：L-002~005、P-004~005、ADR-011~012 - Arch AI 上下文资源管理硬约束写入 principles.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
143 lines
5.5 KiB
Markdown
143 lines
5.5 KiB
Markdown
# 可复用模式
|
||
|
||
## 目的
|
||
|
||
记录开发过程中发现的可持续复用的模式和做法。
|
||
同样的模式出现 3 次以上时，应当记录在这里。
|
||
|
||
---
|
||
|
||
## P-001: AI 任务交接 (review/active/)
|
||
|
||
**上下文**: AI 角色之间需要传递工作成果
|
||
**问题**: 如何结构化任务交接，让任何 AI 都能接手
|
||
**方案**: 标准化 `review/active/{任务ID}/` 结构：
|
||
- `task.md` — 任务描述（Arch AI 定义）
|
||
- `acceptance.md` — 验收标准（Arch AI + Dev AI + QA AI 共同维护）
|
||
- `impact.md` — 变更影响范围（Arch AI + Dev AI 评估）
|
||
- `feedback/` — 反馈记录（QA AI 提交）
|
||
|
||
**何时用**: 每个跨 AI 角色的任务
|
||
**何时不用**: 单角色任务（如纯文档更新、配置修改）
|
||
|
||
---
|
||
|
||
## P-002: 角色工作台 (daily task board)
|
||
|
||
**上下文**: AI 每次会话需要快速进入工作状态
|
||
**问题**: 从头探索项目结构浪费时间
|
||
**方案**: `.ai/roles/{role}/today.md` 每日任务清单，AI 只需读 2 个文件（card + today）
|
||
**何时用**: 每次 AI 会话
|
||
**维护者**: Arch AI 负责分配，各 AI 自己更新完成状态
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## P-003: 模板同步 (framework sync)
|
||
|
||
**上下文**: 项目框架层（AGENTS/权限/提示词/工作流）的变化需要传播到通用模板分支
|
||
**问题**: 手动同步耗时且容易遗漏，AI 重做去敏化消耗 ~100K tokens
|
||
**方案**:
|
||
- 双分支：`main`（具体项目）+ `ai_project`（通用模板）
|
||
- `SYNC.md` 明确定义框架层/项目层文件边界
|
||
- `sync-template.sh` 自动 checkout 框架文件 + 重新应用 {{变量}}
|
||
- 框架层 ~15 个文件自动同步，project 层永久隔离
|
||
**何时用**: main 分支框架有变化时
|
||
**维护者**: Arch AI 触发，脚本执行
|
||
|
||
---
|
||
|
||
## P-004: 编排器-执行者模式 (Orchestrator-Worker)
|
||
|
||
**上下文**: AI Agent 协作中，不同任务需要不同能力的模型。高能力模型（Opus）做规划和判断，低成本模型（Sonnet/Haiku）做执行
|
||
**来源**: MegaAgent (NUS)、Claude Code Agent Swarm (Anthropic)、JiuwenSwarm (华为 openJiuwen)、Microsoft 多 Agent 参考架构
|
||
**方案**:
|
||
|
||
```
|
||
决策层 (Opus) → 意图理解、方案设计、最终验收 (~10% Token, 最贵)
|
||
调度层 (代码) → 任务路由、负载均衡、重试熔断 (确定性代码, 不用 LLM!)
|
||
执行层 (Haiku) → 专注单一原子任务 (~60% Token, 最便宜)
|
||
```
|
||
|
||
**核心原则**:
|
||
1. 按业务上下文划分 Agent（「认证流 Agent」），而非按角色（「数据库 Agent」）
|
||
2. 调度层是确定性代码——用 LLM 做调度是反模式
|
||
3. 子 Agent 的甜蜜点是只读研究/探索，并行编码效果不佳
|
||
4. 写范围严格分离——并发写任务之间不能有重叠的文件所有权
|
||
5. Agent 粒度围绕内聚能力组织——不要为「调用一个 API」建 Agent
|
||
|
||
**何时用**:
|
||
- 团队规模 ≥ 3 个 AI Agent 并行工作
|
||
- 任务可清晰分解为独立子任务，且协调成本 < 并行收益
|
||
- 有明确的模型成本优化需求
|
||
|
||
**何时不用**:
|
||
- 1 人项目——编排层就是人类 + Claude Code 本身
|
||
- 编码任务的并行化——行业共识是效果不佳
|
||
- 简单 bug 修复——分解成本 > 直接修复成本
|
||
|
||
**本项目实例** (ErrLens):
|
||
|
||
```
|
||
Arch AI: Claude Code + DeepSeek V4 Pro → 架构推理、方案设计、任务分解
|
||
Coder AI: Trae CN + GLM-4.6 → 代码生成、文件操作（单文件粒度）
|
||
Tester AI: Coze CN → 沙盒执行、自动化测试报告
|
||
|
||
通信介质: Git 仓库（唯一集成总线）
|
||
交接粒度: 单次 commit = 一个交接单元
|
||
```
|
||
|
||
**关键适配**:
|
||
- Coder AI 用的是 GLM-4.6，不能假设它有跨文件推理能力 → task 分解到单文件粒度
|
||
- 跨模块协调在 Arch AI 设计阶段完成，不在 Coder AI 执行阶段
|
||
- Tester AI 的 Coze 沙盒做真正的自动化闭环——不只是跑测试，是拉代码 → 执行 → 生成报告 → commit
|
||
|
||
---
|
||
|
||
## P-005: 跨平台任务交接协议 (Cross-Platform Task Handoff)
|
||
|
||
**上下文**: 多个 AI Agent 运行在不同平台/IDE 上，零共享上下文，Git 是唯一通信介质
|
||
**问题**: 如何让 Trae + GLM-4.6 拿到 task 后能直接开工，不需要追问「这个是什么意思」
|
||
**方案**: 每个 task 必须自包含，包含四个必填字段：
|
||
|
||
```markdown
|
||
## Task: {编号} {标题}
|
||
|
||
### 输入
|
||
- 读哪些文件（完整路径）
|
||
- 参考哪些 ADR（ADR-XXX）
|
||
- 依赖哪些上游任务（P01-XXX，已完成/产出是 X）
|
||
|
||
### 输出
|
||
- 生成/修改哪些文件（完整路径）
|
||
- 输出格式（代码/文档/配置）
|
||
- 验收方式（跑什么命令看什么结果）
|
||
|
||
### 约束
|
||
- 不碰哪些目录
|
||
- 用什么库/版本
|
||
- 遵循什么规范（code-style.md / doc-template.md）
|
||
|
||
### 参考
|
||
- ADR-XXX: 一句话说明关联性
|
||
- 相关文件: 一行说明
|
||
```
|
||
|
||
**核心原则**:
|
||
1. **零隐含上下文**：接收方不能依赖「上次聊过」，所有信息必须显式写在 task 里
|
||
2. **适配接收方能力**：给 GLM-4.6 的任务粒度 = 单文件；给 Claude 的任务可以跨 3-5 个文件
|
||
3. **Git commit 即消息**：每次 commit 是发送一次消息，接收方 pull 即收到
|
||
4. **任务与代码分离**：task 定义在 `.ai/roles/{role}/queue.md`，代码在 `projects/`，通过 Git 同步
|
||
|
||
**何时用**: 跨平台/跨模型协作
|
||
**何时不用**: 同一平台内的角色切换（直接对话即可）
|
||
|
||
---
|
||
|
||
## 反模式（避免）
|
||
|
||
- 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录
|
||
- 决策讨论散落在任务 feedback 中 → 提炼到 knowledge/decisions.md
|
||
- 大段文档内联而非链接 → 用链接 + 一句话摘要
|