edit | blame | history | raw

X-已废除：团队协作规范（Working Agreement）

废除日期：2026-05-29
废除原因：本文档创建于 2026-05-23，包含旧阶段、旧路径、旧 App Store / 私有 API 风险口径，已与当前 Boss 裁决和 Round0 项目管理要求不一致。
当前依据：PROJECT.md、GLOSSARY.md、02-P/AGENTS.md、02-P/Round0/Round0-Todo.md、03-O/README.md。
本文仅保留为历史材料，不作为当前角色边界、流程、风险或验收依据。

v1.0 | 2026-05-23
参考：Atlassian Team Playbook / Basecamp Shape Up / Amazon Working Backwards

1. 角色定义

1.1 各岗位详情

Boss（产品 Owner）
- 扮演者: 你
- 职责: 最高裁决、设计评审、表现层最终验收
- 输入: 用户需求、产品方向
- 输出: 决策确认、设计评审意见、验收通过/打回
- 阻塞条件: 方案不清晰、信息不足
- 禁区: 不进代码细节、不写 Spec

PO（产品总监）
- 扮演者: PO
- 职责: 产品方向、产品裁决、PRD 总纲、最终效果验收
- 输入: Boss 的方向决策、用户需求、产品反馈
- 输出: 产品裁决、PRD 总纲、验收意见
- 阻塞条件: 产品方向未确认、需求冲突未裁决
- 禁区: 不写代码、不替研发做技术路线决策

PM（产品经理）
- 扮演者: PM1号
- 职责: 把 PO 的方向拆成具体 PRD / Round Spec / 验收口径
- 输入: PO 的产品方向、Boss 的裁决、设计/研发/QA 反馈
- 输出: PRD、Round Spec、验收标准、产品说明
- 阻塞条件: 产品目标、范围、不做项或验收标准不清
- 禁区: 不写代码、不负责排期和跨部门调度

CoS（总经理助理）
- 扮演者: CoS
- 职责: 项目管理、排期、WBS、里程碑、跨部门协作、跟进与留痕
- 输入: Boss / PO / PM / CTO / UID / QA 的协作需求
- 输出: 排期、WBS、里程碑、协作事件、项目文档和跟进记录
- 阻塞条件: 责任人不清、输入材料不清、跨部门协作未回执
- 禁区: 不写代码、不替产品拍需求、不替架构拍技术路线

架构师
- 扮演者: CTO / 架构师
- 职责: 审查方案完整性/兼容性/可执行性，敲定后才能给 Dev
- 输入: Round Spec + 架构方案草稿
- 输出: 共识确认 + 方案终稿
- 阻塞条件: 方案不完备、边界条件未覆盖
- 禁区: 不写代码、不写 Spec

Dev（开发者）
- 扮演者: Codex
- 职责: 所有代码实现（Swift/Shell/脚本）、单元测试、代码自查
- 输入: 架构师共识确认 + 方案终稿
- 输出: git commit、build 产物（.app）
- 阻塞条件: 架构方案未定、测试不过
- 禁区: 不做架构决策、不跳过代码审核员

代码审核员
- 扮演者: Codex（子角色）
- 职责: 逐行审查代码质量，边界/错误/规范
- 输入: git commit（已完成自查）
- 输出: 审查通过打回+意见
- 阻塞条件: 代码有未修复问题
- 禁区: 不替 Dev 改代码、不改方案

QA（质量保证）
- 扮演者: QAD / QA
- 职责: 拆测试用例、边界条件、回归验证、一票否决权
- 输入: 审核通过的代码
- 输出: 回归报告（全绿/打回）
- 阻塞条件: 回归未全绿、测试覆盖不完整
- 禁区: 不改需求不改代码

2. 三思而后行

所有人的工作原则：先设计/规划，后执行。

  • 不允许"先做再说"——写代码前必须有方案，改配置前必须有预期
  • 程序员尤其需要遵守，不得在没方案的情况下直接开干
  • 规划投入与执行复杂度成正比 — 小修小补快速过方案，大工程必须充分设计

2.1 程序员设计要求

不得一个人埋头设计方案。 设计方案时至少拉两个人：
- 本人（主设计师）
- 2 位架构师参与方案研讨（三位一起评审，确保方案质量）
- 方案达成共识后，才能开始写代码

2.2 代码交付三重门

程序员提交流程，三步走完才能丢出去验收：

① 代码自查 ──→ ② 代码审核员审查 ──→ ③ QA 自动化测试 ──→ 进入验收

第 ① 步：代码自查
- 提交前，程序员逐行回顾自己的代码
- 自查清单：边界条件是否处理？错误路径是否覆盖？Swift 命名规范是否符合？

第 ② 步：代码审核员审查
- 找另一位非本人的开发者（或架构师）做 code review
- 两人一起查完问题，确认无遗留才进入下一步
- 审核员有权打回

第 ③ 步：QA 自动化测试
- 必须有自动化测试覆盖新功能（单元测试 + 集成测试）
- 回归测试必须全绿
- 手动测试不做主流程验证，只做边缘场景补充

三步缺一不可。 任何一步没做完，不许丢给验收人。

3. 岗位衔接流程

核心逻辑：每个岗位做自己的事 → 把明确的产出交给下一个岗位 → 下一个岗位在认可的基础上继续推进（不踩活）。

完整衔接链条

PO（方向/决策）──── （只有表现层变更才走这一步）
  │ 口头/文字确认
  ▼
PM（写 Spec + 搭架构方案）
  │ 02-P/rounds/round-N.md
  ▼
架构师 ×2（审查方案）
  │ 共识确认
  ▼
Dev（Codex 实现代码）
  ├── ① 代码自查
  ├── ② 代码审核员审查
  ├── ③ QA 自动化测试
  │
  ▼
┌───分叉口───
│
├─ 代码层变更（基础设施/Service/ViewModel 等）
│   ├── QA 关卡 ← 终点
│   └── PM 确认 Build + Test 通过
│
└─ 表现层变更（UI/交互/用户可见功能）
    ├── QA 关卡
    ├── PM 打包 .app
    └── PO 最终验收（实测）

各衔接节点的交付物

# 从 到 交付物 接过之后干什么
① PO PM 方向决策/设计评审意见 PM 写进 Round Spec，确保可追溯
② PM 架构师×2 Round Spec + 架构方案草稿 审查方案完整性、兼容性、可执行性；敲定后才能给 Dev
③ 架构师×2 Dev 共识确认 + 方案终稿 Dev 严格按方案实现，不自行变更架构
④ Dev 代码审核员 git commit（已完成自查） 逐行审查，确认边界/错误/规范，有权打回
⑤ 代码审核员 QA 审核通过的代码 跑自动化测试，回归全绿 → 放行；发现 bug → 退回 Dev
⑥a QA PM 回归报告（全绿） 代码层变更到此结束，PM 确认存档
⑥b QA PO 回归报告 + 打包 .app 表现层变更继续走，PO 实测验收

关键规则

  • 不跨级送达：Dev 不能跳过 QA 直接丢出去
  • 不被跳过：Architect 没审查的方案不能给 Dev
  • 不欠债过节点：本节点发现的问题，本节点处理完再往前走
  • 衔接 ≠ 推锅：接过交付物后，在信任基础上继续，不推翻重来（参见不踩活规则）

3.1 不踩活规则

踩活定义：接手任务时不信任上游交付，直接推翻重来。
不踩活 = 认可交付 → 在其基础上推进 → 只在必要时协商修正。

  • Codex 提交的代码，PM 不修改 — 发现 bug 走 issue → 排期 → 下个 Round 让 Codex 修
  • QA 发现的 bug 不跳过 — PM 不能以"这个我知道"放行，必须记录等修复
  • 用户方向 不擅自变更 — 不能因"我觉得更好的方案"绕开用户决策
  • Round 内产出 不在 Round 外修改 — Codex 本轮写的代码，PM 不能在本轮外补改

4. 任务分解（WBS）

Phase 0 — 概念闭环（✅）

P0.1~P0.7 产品规划、技术可行性、原型、测试用例、PM 体系 — 全部完成

Phase 1 — 核心框架

P1.1~P1.7 脚手架、Space Lane + App Lane + Fall UI、Space Lane/App Lane/瀑布、窗口数据层、编辑模式开关

Phase 2 — 编辑交互

P2.1~P2.6 6+1宫格拖拽、勾选排列、升降级逻辑、两层编辑流程、自动保存、分割线微调

Phase 3 — 方案系统

P3.1~P3.6 数据模型+持久化、保存/加载/管理UI、恢复报告、显示器不匹配平铺

Phase 4 — 精调与发布

P4.1~P4.6 动画优化、多显示器测试、边缘情况、图标、本地化、App Store 提审

5. 里程碑

里程碑 时间 交付物
M0 概念闭环 ✅ 产品规划+原型+测试用例+PM体系
M1 原型可见 D+5 Phase 1（Space Lane + App Lane + Fall UI+勾选排列+窗口执行）
M2 编辑可用 D+12 Phase 2（完整编辑交互）
M3 方案就绪 D+18 Phase 3（方案保存/恢复）
M4 发布就绪 D+25 Phase 4（Beta+提审）

6. 风险登记册

# 风险 P I 应对
R01 Space 创建无公开 API 高 高 先用 AppleScript 模拟，后期调研 CGS。不可行→用户手动创建，Aligner 只读
R02 AX API 跨 Space 移动可靠性 中 高 原型 POC 验证。不足→window level + frame 模拟
R03 Split View tile API 限制 中 中 AX API 手动调 frame + 窗口重叠法（2-3px）
R04 多显示器复杂度 中 中 开发标配双显示器测试
R05 大量窗口性能 低 中 骨架屏方案 + Lazy Loading
R06 macOS 版本兼容 低 低 只支持 macOS 26+
R07 App Store 审核拒绝 低 高 不使用私有 API，标准权限引导流程

7. Git 策略

  • 主分支 main，功能分支 feat/xx，修复 fix/xx，重构 refactor/xx
  • 禁止直接 push main
  • 分支完成后 PR → 审查 → 合并
  • commit 前缀：[feat] [fix] [refactor] [chore] [docs]

8. 决策日志（关键记录）

日期 决策 理由
05-21 编辑模式不自动清空 用户自主控制
05-21 方案加载智能合并 避免误关已有窗口
05-21 骨架屏替代截图 零负载、视觉统一
05-22 不做内容深度（浏览器生态） 不伸手到别人的领域
05-23 多显示器跨屏混排+字母前缀 Space Lane 不分组，前缀自然标识
05-23 Space Lane/App Lane 高度固定无分割线 Space Lane / App Lane 固定，瀑布吃剩余
05-23 App Shelf 永远单行 类比 macOS Dock
05-23 架构：MVVM+AppState Store，骨架屏，AX API+Frame重叠法 三位架构师共识
05-23 Round 5a 开始提取 LayoutExecutionService + DataService + ViewModel 层 消除 AppState 上帝对象
05-23 退出编辑后可拖分割线方案（NSWindow overlay 透明层） 三位架构师合议 D+E+F，~5.5天，不关SIP，零静止消耗
05-23 PO 只验收表现层，代码层变更在 QA 关卡结束 PO不进代码细节
05-23 三区域术语定稿：Space Lane / App Lane / Fall 统一术语表

9. 测试策略

层次 内容 工具
单元测试 数据模型、编号逻辑、TileCalculator XCTest
集成测试 AX API 操作 XCTest + 实机
UI 测试 交互流程 XCUITest
手动测试 多显示器、边缘情况 手工
QA 门神 每 Round 回归全绿 → 才放行

10. QA 测试范围

权限说明： 公司给团队的操作权限很高（操作电脑、查看屏幕、浏览器操作、高级管理账号），QA 必须充分利用，不得把测试工作推给 PO。

  • 范围要足够多 — 覆盖正常路径、异常路径、边界条件、竞态条件
  • 场景要足够真实 — 真实窗口、真实应用、真实显示器配置，不用 mock 数据测 UI
  • 能自动化全部自动化 — XCTest/XCUITest，手动只做探索性测试

每 Round QA 必测清单

维度 必测项
正常主流程 3 轮完整操作（进入→编排→应用→退出）
窗口数量边界 0 窗口、1 窗口、大量窗口（>20）
多显示器 单屏/双屏/三屏；不同分辨率混接
权限 拒绝权限后行为、中途撤销权限
并发 操作中窗口被关闭/新建
重入 编辑中再次进入编辑、编辑中应用退出
持久化 方案保存后修改→恢复→结果一致

11. 安全网

场景 处理
Build 失败 退回 Dev，QA 不计轮次
测试未全绿 退回 Dev，QA 不计轮次
PM 越权改代码 用户 git revert → Codex 重新覆盖
Codex session 丢失 用户找 session ID → PM 重调度
方向分歧 PM 写分析 → 用户决策 → 记入日志

本文档由 PM 维护，活文档。