04 · 通讯协议PM 跟 Developer / Reviewer / Merger / 用户说啥、用啥格式

PM → 用户(微信/飞书)

自然语言,简短直接,分情况:

迭代启动通知(可选,任务简单时跳过)

收到 ✅ 我准备开始做"实现用户登录"。拆成 3 个 task:建表、写 API、写前端。预计 10 分钟做完。

PR 已开,请你 review

PR 开好了,请你看看:
🔗 https://github.com/netkingcode/myapp/pull/1

改了什么:
- 加了 user 表 + login API
- 前端登录页

reviewer(用 GLM-5.2)还在审,预计 3 分钟出结果。等他给完意见我再汇报。
你要先看也可以。

Reviewer 给 verdict,问要不要合

Reviewer 给了意见 ✅(approve)。

主要反馈:
- 缺 rate limiting(小问题,加个 gem 就行)
- 几个变量命名建议

要合吗?
- 选 A:合(我会让 merger 跑 squash merge)
- 选 B:先修 rate limiting 再合
- 选 C:你自己来合

需要你拍板的产品/架构问题

⚠️ Reviewer 提了一个我没权限决定的问题:

"用 bcrypt 还是 argon2 做密码 hash?目前代码用 bcrypt 但 argon2 在新 Rails 7.1 更推荐"

你怎么看?
- A:继续用 bcrypt
- B:换 argon2(让 developer 改)
- C:别的方案

PM → Developer

通过 OpenCode session 派发。任务说明模板:

任务: 实现用户登录
背景: 这是项目 myapp 的第一个迭代(iter-001-login),目前是空 Rails 项目
工作目录: ~/agent-workspace/myapp.iter-001-login  ← (worktree)
branch: feat/iter-001-login

需求:
- 用户能用 email + 密码登录
- 登录成功返回 JWT token
- 密码用 bcrypt 加密
- 加 rate limiting(每 IP 每分钟 5 次)

验收标准:
- POST /api/login 正确返回 200 + JWT 或 401
- 错误密码 5 次后该 IP 暂时被锁
- 有 RSpec 测试覆盖 happy path + 错误密码 + 限流
- README 更新说明登录 API 怎么用

技术约束:
- 用 Rails 7.1 + Devise
- 不要引入新数据库(migration 文件加在 db/migrate/)
- commit 拆成 3 个:
  - task-001: user 表 + model
  - task-002: login API + JWT
  - task-003: rate limiting + 测试

交付:
- 所有 task 完成后:
  1. 跑全套测试,贴结果
  2. push branch 到 origin
  3. gh pr create --title "实现用户登录 (PM-iter-001)" --body 见下
  4. 把 PR URL 回我

PR body 模板:
```
## 任务
PM-iter-001: 实现用户登录

## 改了什么
- ...

## 怎么测
- bundle exec rspec
- curl -X POST http://localhost:3000/api/login -d ...

## 关联
- PM iteration: iter-001-login
- tasks: task-001, task-002, task-003
```

不要:
- 不合自己的 PR
- 不直接 push 到 main
- 不改 reviewer 的评论
- 不擅自扩任务范围(需要的话反问 PM)

回我:
- PR URL
- 几个 commit 的 SHA
- 跑测试的输出
- cost 大概多少

PM → Reviewer

任务: review PR
PR: https://github.com/netkingcode/myapp/pull/1
被审: PM-iter-001 "实现用户登录"
任务说明: <跟 developer 收到的那个一样,或者 "见 .pm/iterations.json 的 iter-001">

要求:
1. 读 PR diff: gh pr diff 1 --repo netkingcode/myapp
2. 读任务说明理解"原本要做什么"
3. 跑测试验证:gh pr checkout 1 && bundle exec rspec
4. 在 PR 上留 review:
   gh pr review 1 --comment -b "..."
   (如果行级 comment 需要,先 gh api)
5. 给结构化 verdict(下面 schema)

重点看:
- 是否真的实现了需求
- 测试是否覆盖了所有验收标准
- 明显 bug / 安全问题 / 性能问题
- 命名/风格(简单提)

不要:
- 不 push、不 commit、不合
- 不做"我觉得应该用 X 库"这种主观架构建议(那是用户决策)
- 不纠结风格(除非真的很乱)

verdict 格式(放在你回复的末尾,```verdict 块里):
```verdict
{
  "verdict": "approve" | "request_changes" | "comment",
  "blockers": ["..."],         // 必须改的问题(影响合并)
  "suggestions": ["..."],      // 可改可不改的建议
  "test_verdict": "pass" | "fail" | "incomplete",
  "summary": "一句话总结"
}
```

回我:
- verdict JSON
- 给用户看的总结(2-3 句话)

PM → Merger

任务: 合并 PR
PR: https://github.com/netkingcode/myapp/pull/1
策略: squash       ← (或 merge / rebase,用户决定)

工作目录: ~/agent-workspace/myapp.iter-001-login  ← (原来的 worktree)

执行:
1. cd 到项目主目录 ~/agent-workspace/myapp
2. 确认 worktree 是 clean:git status
3. gh pr merge 1 --squash --delete-branch --repo netkingcode/myapp
4. 清理 worktree: git worktree remove ../myapp.iter-001-login
5. 验证: git log --oneline -5  (看到新 commit)
6. (如果有关联 issue:gh issue close N -c "merged in PR #1")

不要:
- 不擅自改 PR 内容
- 不合未经我明确指令的 PR

回我:
- merge commit SHA
- worktree 是否清理成功
- 如果失败,贴错误

字段约定

Verdict 详细 schema

{
  "verdict": "approve",                  // approve | request_changes | comment
  "blockers": [                          // 阻塞合并的问题
    "缺 rate limiting 中间件",
    "login API 没有错误处理(panic 风险)"
  ],
  "suggestions": [                       // 建议但不阻塞
    "变量名 current_user -> user 更清晰",
    "把 JWT 过期时间改成可配置"
  ],
  "test_verdict": "pass",                // pass | fail | incomplete
  "test_notes": "12/12 通过,覆盖了 happy path + 错误密码,但没测限流",
  "security_issues": [                   // 安全相关
    "密码 hash 用 bcrypt 强度 12,OK"
  ],
  "performance_notes": "无明显问题",
  "summary": "功能完整,测试覆盖 OK,但 rate limiting 没实现,需要补上"
}