multi-session-dev

---
name: multi-session-dev
description: 用多个 AI 编码会话（Claude Code、claude.ai、Codex 等）并行开发一个或多个仓库时的分工与交接做法：一个管理会话做决策和集成，几个开发会话各在自己的分支和 worktree 里实现、验收、交付，子代理做短调研和审查，云端会话在用户不在时推进。管：什么时候自己做、派子代理还是开新会话；派工前查写入边界、共享契约和版本号、桌面端口数据目录这类只有一份的资源、有几件事在等用户；任务简报；按改动挑验收证据（静态检查、截图或录屏、真机）；结束报告第一句和换会话交接；管理会话核对 Git 再报告、推送前合远端、不替别的会话越过权限；本地和云端怎么分；CI 分钟数；新项目的项目档案和起步模板。只要用户说「开子会话」「开一条开发线」「派个任务」「同步一下进度」「主 session / 管理会话」「worktree」「subagent 还是独立 session」「几个 Claude 怎么分工」「谁来合并、谁推送」「云端会话」「交接」「多 agent 开发」，或者在给新项目定协作方式，就用这个 skill。Also use for English requests about running several coding-agent sessions in parallel, worktree-per-task workflows, task briefs, handoffs, or who merges and pushes.
---

# Multi-Session Dev：几个 AI 会话一起开发

> **会话负责思考和执行，worktree 负责隔离，文件负责共享状态，Git 和 PR 负责交付和验收。**
> 会话随时可以重建；任务定义、接口契约、提交和测试证据必须不依赖任何一个会话的记忆而存在。

正文和具体工具无关。某个工具怎么开会话、派子代理、开 worktree，看 `references/tools.md`。

## 0. 先读项目档案

每个项目要有一份**项目档案**：分支流程、谁能验收、合并、推送；worktree 怎么开；哪些资源只有一份；快速检查是什么；验收分几档；云端走哪条分支；哪些事只有用户能做。它通常就是仓库指令文件（`CLAUDE.md`、`AGENTS.md`）里的一节。

- 有档案：照档案做，本 skill 只补档案没写的。**项目规则优先于本 skill。**
- 没有：和用户一起按 `references/project-profile.md` 填一份，放进仓库指令文件。新项目可以用 `scripts/init_project.py` 拷入起步模板（见 §10）。

## 1. 角色

| 角色 | 是谁 | 做什么 | 不做什么 |
|---|---|---|---|
| 用户 | 人 | 定方向和优先级，验收，做只有本人能做的事（登录、授权、付款、填密码、看真机） | |
| 管理会话 | 一个长期开着的顶层会话 | 拆任务、写简报、开开发会话；核对它们的结果再告诉用户；协调共享契约和合入顺序；按档案推送、开 PR、发布；处理 CI 失败 | 不写成块的功能代码；不替别的会话越过权限确认 |
| 开发会话 | 每个任务一个顶层会话，有自己的分支和 worktree | 设计、实现、验证；按档案找验收人；按档案合入或提 PR；交付确认后清理 worktree；写结束报告 | 不改简报写入边界以外的文件；不擅自改共享契约 |
| 云端会话 | 在云端运行的开发会话 | 同开发会话，但只碰得到远端仓库和 CI | 不碰本地数据、桌面、真机 |
| 子代理 | 会话里派出的一次性助手 | 调研、读代码、补测试、审查一个 diff，交回摘要 | 不长期负责模块；审查者只报问题不改代码 |

谁合入、谁推送有两种常见配置，档案里选一种写明：

- **A. 集成者合入**（走 PR 的团队项目）：开发会话提 PR，管理会话或人工审查后合并。
- **B. 开发会话合入、管理会话推送**（单人、本地集成分支）：开发会话拿到用户的明确验收后，先把最新集成分支合进自己的分支，验证，再合入本地集成分支；管理会话统一推远端、开发布 PR。

## 2. 谁来做

| 工作 | 交给 |
|---|---|
| 几次工具调用能完成；回答问题；读一段代码；推送；小修 | 当前会话自己做 |
| 这一轮就要结果的调研、日志分析、审查一个 diff、补一组测试 | 子代理 |
| 能独立交付、要跨多轮、有自己的验收 | 新的开发会话 |
| 用户不在、不需要真机、CI 能查 | 云端会话 |
| 需要真机、本机数据、特定系统或用户当场判断 | 本地开发会话，等用户在的时候 |

不要把流程建立在多层子代理嵌套上。各工具对嵌套的支持不一样；开发会话可以再开开发会话时，照样按本节判断，并告诉管理会话。

## 3. 派工前检查

每派一个会写代码的任务，过一遍这四项。任何一项不过，就重新切分、定顺序，或者合成一条线：

1. **写入边界。** 列出这个任务写哪些文件、不碰哪些（Allowed Scope）。和正在进行的任务有重叠，就不并行。
2. **只能串行的东西。** 共享契约（接口定义、协议、插件 API）、版本号、依赖锁文件、入口文件、数据迁移。并行任务都要动时，指定一个负责人，其他人等它合入。**谁开始改契约，先把对方最新的合进来**，本地和云端之间也一样。
3. **只有一份的运行资源。** 桌面上运行的应用实例、开发端口、数据目录、共享的依赖目录、缓存、构建产物、测试设备。写明谁在占用、用哪个分支和数据配置、什么时候还。默认的占用者是用户日常使用的那个实例。
4. **用户的注意力。** 数一数有几件事在等用户：验收、选择、亲手操作。达到约 3 件时，先汇总或处理已有的，再决定要不要继续派工。

并行数量：有互相独立的任务时，可以从 2 条开发线起步；只有一件事就只开一条。四项检查都过时可以更多；真正的上限通常是用户能同时照看的待验收数，不是机器。

## 4. 任务简报

开开发会话时写一份简报，模板见 `references/templates.md`。必须有：

- 目标和验收条件；
- 仓库、基线分支、写入边界；
- 涉及的共享契约、依赖、运行环境；
- 验收方式（见 §6），能用截图或录屏的写明；
- **需要用户亲手做的步骤**（登录、许可、付款、密码、下载确认），让开发会话一开始就一次问完；
- 谁验收、谁合入、谁推送，交接写在哪。

已有 issue 或任务文档时，简报指向它，只补缺的字段。

## 5. 开发会话怎么做

1. 用项目的 worktree 脚本开分支（没有就用通用方式），核对实际分支和基线提交。
2. 实现，并跑项目档案定义的**快速检查**。项目有静态检查（lint、类型检查等）时，快速检查应包含它们；只改文档时检查文档本身。
3. **改了共享类型、接口或版本号：** 跑所有用到它的地方的测试，包括另一个仓库里的消费者（比如插件的测试替身要补上新成员）。只跑「相关测试」不够。
4. 按 §6 拿验收证据，交给档案规定的验收人（用户本人、审查者或 PR 审批）。没有获得档案要求的批准，不合入。
5. 按档案同步目标分支（merge 或 rebase），再验证，再按档案集成：自己合入（配置 B），或提 PR 等集成者合（配置 A）。
6. 确认要交付的提交已经在集成分支或远端 PR 上、验收证据能从仓库或 PR 里找到之后，再按档案清理 worktree（先处理目录链接一类共享的东西）。PR 还要改、或本地还留着验收用的东西时，先不清理，在结束报告里写明。
7. 写结束报告，第一句见 §7。

## 6. 按改动挑验收证据

| 档位 | 什么时候够用 | 例子 |
|---|---|---|
| 静态检查和自动测试 | 逻辑、数据、协议改动 | lint、类型检查、单元测试、进程级测试 |
| 无头截图或录屏 | 布局、文字、样式、动画、角色动作，能从画面判断对错 | 无头浏览器加假宿主渲染页面，逐帧录 GIF，前后对比 |
| 真机运行 | 系统窗口行为（透明、穿透、置顶、托盘）、设备交互、计时、声音、真实服务的登录 | 从分支启动应用，让用户操作 |
| 发布环境 | 安装、升级、打包后启动、多种显示配置 | 用安装包在干净环境装一次 |

- 先问「这个改动能不能用截图或录屏验收」：能的话就不占用桌面实例。
- 每项结果写成 `PASS`、`FAIL`、`未运行` 或 `不适用`，附命令或步骤、环境和受检提交。
- 基线变了、解过冲突或之后又有改动：补跑受影响的检查。
- CI 不可用时：在本地跑能跑的检查，**分开写清**「本地跑过的」和「远端没跑的」，以及哪些失败是本机特有的。**本地结果不能代替项目的合并门禁**：按档案等 CI 恢复，或者走档案里事先定好的替代流程。

## 7. 结束报告和交接

**结束报告的第一句**固定写三件事，给接手的人或管理会话看：

```text
<仓库>/<分支> @ <提交>｜<已合入 / 已推送 / 都没有>｜<在等谁、等什么；没有就写下一步>
```

后面再写细节：做了什么、验证结果（按 §6 的格式）、没做的和风险。小任务凭这份报告和 Git 就能恢复，不另写交接。

**需要持久交接的情况：** 挂起、换会话、跨机器、等很久的验收、依赖后续会话。在接手方能访问的**一个**地方写（任务文档的交接小节、PR 描述或项目约定的续接文件），内容见 `references/templates.md`。先找已有记录、更新同一处，不要每条小改动都新建文件。合入后，把交接并进任务文档或删掉。

**接手的顺序：** 项目指令 → 任务入口 → 最新交接 → Git 现场（`git status`、worktree 列表、分支差异、远端状态）。交接写的是「当时以为」，Git 才是「现在」；两者不符时以 Git 为准，并在报告里说明。

记录各放各的地方，不要同一件事写五遍：

| 内容 | 放在 |
|---|---|
| 设计、决定、验收清单 | 任务文档（唯一来源） |
| 当前状态 | 结束报告 + Git |
| 跨项目经验 | 用户的经验库 |
| 不在代码里的项目约定 | 项目记忆或仓库指令 |

## 8. 管理会话守则

1. **子会话的报告不是证据。** 告诉用户「完成」之前，先看 Git：提交在不在、是否已合入、worktree 是否清理、PR 状态。
2. **推送前先按档案同步远端的新内容**；多个会话等着合入时，先定顺序，后合入的那个重新核对基线。
3. 判断合并会不会冲突、要在运行中的实例所在目录合并时：**先在临时 worktree 里真合一次**、跑检查，再写入集成分支。旧版工具的冲突模拟不可靠；在运行中实例的目录里解冲突，会把冲突标记热更新进程序。
4. **不替别的会话越过权限。** 它被拦下的安装、登录、付款，交还给用户本人批准。
5. 转告用户时，把「等你的」和「仅通知」分开，同类的问题合成一次问。
6. CI 失败：先找出是哪个提交引入的，以及为什么本地没拦住；修复走分支，不直接在集成分支上改。
7. 自己不做长任务。超过几十次工具调用的，开开发会话。

## 9. 本地、云端、用户不在时

| 环境 | 适合 | 不适合 |
|---|---|---|
| 本地会话 | 真机、真实数据、特定系统、用户当场验收 | 用户不在时等验收的事 |
| 云端会话 | 纯代码、文档、测试、CI 能查的东西 | 需要本地数据、桌面、模型、真机的验证 |
| 远程遥控本地会话 | 用户在外面回答选择题、批准 | 看真机效果 |

- 云端会话推到哪条分支按档案：每个任务一条分支、各开一个 PR；或者推到一条常驻分支、攒一个常开的集成 PR。**开始前先把集成分支的最新内容同步进来**（merge 还是 rebase 按档案）。
- 用常开集成 PR 时，按任务分小节写描述，每节写明怎么验收、能不能用截图验收，让用户回来后逐节看。
- 云端的验证主要靠 CI。频繁推送时，可以按成本少跑完整检查，例如草稿不跑、留手动触发、由负责合并的一方在合并前触发。**采用前先核对项目的门禁**：草稿、普通 PR、进发布分支的 PR 分别要求哪些检查，被跳过的检查会不会被当成通过。细节见 `references/ci-cost.md`。

## 10. 新项目起步

最少只要：一份带项目档案的仓库指令文件、管理会话、2 条开发线、CI、需要时的审查子代理。`scripts/init_project.py <项目目录>` 会拷入：

- `PROJECT.md`：仓库指令文件的骨架，含项目档案一节（按工具改名为 `CLAUDE.md` 或 `AGENTS.md`，已有的就把这一节并进去）；
- `docs/tasks/TASK-000-template.md`、`docs/contracts/CONTRACT-000-template.md`；
- `PLAN.md`：任务多到难以定位时才用的索引，可以删掉。

已存在的文件不会覆盖。审查、调研子代理的定义因工具而异，见 `references/tools.md`。

**不要过度设计。** 任务索引、交接文件、专门的集成角色、自动编排器，都等真正出了问题（冲突频繁、审查漏 bug、接手接不上、调度成了瓶颈）再针对那一环加。

## 参考文件

- `references/templates.md`：任务简报、结束报告、持久交接、各会话的开场指令。
- `references/project-profile.md`：项目档案要回答的问题和一份填好的例子。
- `references/ci-cost.md`：私有仓库 CI 分钟数怎么省。
- `references/tools.md`：Claude Code、claude.ai、Codex 各自怎么开会话、派子代理、开 worktree。
- `references/pitfalls.md`：实际出过的问题和对应做法。

## 来源与维护

- **来源**：[Cirra](https://github.com/RedCarpG/cirra-deskpet)（桌面应用主线、插件仓库、语音服务三个仓库，2026-10 至 2026-11）与 [ChroniQ](https://github.com/RedCarpG/ChroniQ) 的多会话开发实践；Claude 与 Codex 对这份 skill 的三轮评审（评审记录未公开）；作者在 claude.ai 上的 `multi-session-dev` 早期草案（被本版替换）；作者经验库里的 `multi-session-pr-workflow` 一篇（私人仓库）。
- **源头**：本仓库 [`RedCarpG/redcarpg-skills`](https://github.com/RedCarpG/redcarpg-skills/tree/main/skills/multi-session-dev) 的 `skills/multi-session-dev/`。各 agent 的 skills 目录和 claude.ai 上的都是安装出来的副本，不要直接改副本。
- **怎么改**：
  - 在本仓库改，`node scripts/validate.mjs` 通过后提交；`manifest.json` 的版本按 semver 加，发版打 tag `multi-session-dev-v<版本>`，再重装各处副本。
  - 正文保持和工具无关：工具相关的写进 `references/tools.md`；项目专属的规则不进本 skill，写进那个项目的档案。
  - 改了做法或坑，同步改私人仓库里的 `multi-session-pr-workflow` 经验。
  - 改了 `scripts/init_project.py`，按六种情况重测：空目录；已有文件的目录连跑两次；只有脚本、没有模板；`docs/tasks` 是文件；`PLAN.md` 是目录；生成的文件里没有断链。
- **更新记录**：
  - 2026-11-12（Cirra）：合并 claude.ai 草案与 Codex 的 `development-coordination` 试用稿；加入项目档案、两种合入配置、派工前四项检查、用户注意力上限、验收分档、结束报告第一句、管理会话守则、本地和云端分工、CI 成本。
  - 2026-11-12（Codex 复核后）：本地检查不能代替合并门禁，省 CI 前先核对门禁；审查子代理只给真正只读的工具；验收、同步、云端分支、快速检查都改由项目档案决定；交付确认后再清理 worktree；初始化脚本先校验再写入；CI 测量改用作业时间，加自托管 runner 的信任边界；PLAN 模板不再带断链。
  - 2026-11-12：1.0.0 收进 redcarpg-skills，「来源与维护」改为指向本仓库。

• README.md 3 KB
• SKILL.md 16 KB
• manifest.json 1 KB
• assets/templates/PLAN.md 1 KB
• assets/templates/PROJECT.md 2 KB
• assets/templates/docs/contracts/CONTRACT-000-template.md 1 KB
• assets/templates/docs/tasks/TASK-000-template.md 1 KB
• references/ci-cost.md 4 KB
• references/pitfalls.md 4 KB
• references/project-profile.md 4 KB
• references/templates.md 4 KB
• references/tools.md 3 KB
• scripts/init_project.py 3 KB