# 可复用模式

## 目的

记录开发过程中发现的可持续复用的模式和做法。
同样的模式出现 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
- 大段文档内联而非链接 → 用链接 + 一句话摘要