上下文工程 · 15 · 多 Agent 协作与外部共享

渐儿
1 阅读13分钟

系列第 15 篇（终篇）。主文档见 智能体上下文工程实现.md。

14 篇讲了同一个用户的跨会话接力。这一篇讲更复杂的场景：多个 Claude 实例协作，可能是同一用户多个会话并行、不同用户共享项目、Claude 与外部系统（Linear、GitHub、Slack）交互。这里的上下文工程从"单 agent 的内部管理"扩展到"agent 系统的外部协议"。

0. 多 Agent 协作的几种拓扑

1. 父子（已讲）：
   主 agent → 子 agent → 摘要返回
   见 03 篇

2. 兄弟并行：
   主 agent → spawn N 个并行子 agent → 各自工作 → 汇总
   见 03 篇 §5

3. 跨会话同用户：
   会话 A（昨天）→ 持久化遗产 → 会话 B（今天）
   见 14 篇

4. 跨用户同项目：     ← 本篇主要讨论
   Alice 的 Claude → 团队共享物 → Bob 的 Claude

5. 异步管线：         ← 本篇主要讨论
   Claude → 写到外部系统 → 另一个 Claude 读取继续

每种拓扑下，"上下文如何在 agent 之间流动"是核心问题。

1. 共享上下文的物理载体

agent 之间不能直接共享内存（每个 Claude 实例有独立的上下文窗口）。所有协作必须通过共享的物理载体：

载体同步性持久性谁可写
Git 仓库异步（push/pull）永久任何有权限的
文件系统同步（同机器）永久同上
项目级 Memory异步（提交到 git）永久任何编辑过的
GitHub PR / Issue异步永久有权限的
Slack / IM实时一般持久频道成员
Linear / Jira异步持久有权限的
共享文档（Notion）实时（多端）持久协作者
数据库 / KV 存储实时持久API 凭据持有者

每种载体有不同的一致性语义和冲突解决方式。设计协作时必须想清楚用哪个。

2. Git 作为协作"主总线"

软件工程场景里，git 是事实上的协作主总线。多 Claude 协作大量依赖它：

2.1 Git 携带的上下文

每个 commit 携带：

  • 代码变更（实际事实）
  • Commit message（决策的 Why）
  • Author（谁做的）
  • Timestamp（什么时候）
  • Branch（哪个流派）

PR 携带：

  • 标题（一句话目标）
  • 描述（详细 Why + Test Plan）
  • Reviewer（谁参与决策）
  • Comments（讨论历史）
  • CI 状态（自动验证）

System Prompt 关于 commit message 的纪律：

"Draft a concise (1-2 sentences) commit message that focuses on the 'why' rather than the 'what'"

为什么强调 Why？因为下一个 Claude（或人）看代码 diff 已经知道 What，需要的是 Why。Commit message 是写给未来读 git 历史的人/agent 看的接力棒。

2.2 PR description 作为接棒

我对自己的 PR description 模板（System Prompt 里有）：

## Summary
<1-3 bullet points>

## Test plan
[Bulleted markdown checklist of TODOs for testing the pull request...]

为什么这个模板？

  • Summary：让 reviewer 30 秒理解
  • Test plan：让接手者知道怎么验证（也方便 reviewer 检查测试覆盖）

如果 PR 跨多次提交、多个 Claude 实例完成，每次更新 PR description 是关键的接力动作。

2.3 PR comments 的"对话痕迹"

PR 评论里的讨论是另一种共享上下文。Claude 接手时应该读：

# gh CLI 是我用得最多的工具之一
gh pr view 1234
gh api repos/foo/bar/pulls/1234/comments  # 行内评论

System Prompt 明示：

"View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments"

这把 PR 讨论纳入了上下文工程的视野。reviewer 提的问题、提交者的回应 —— 都是接手者必须读的状态。

3. 项目级 Memory 的多 Claude 共享

主文档讨论的 Memory 默认是用户级（~/.claude/.../memory/）。但项目里也可以有 Memory：

project/.claude/memory/
├── MEMORY.md
├── project_architecture.md
├── reference_dashboards.md
└── ...

提交到 git → 团队共享。所有协作的 Claude 实例都读到。

3.1 项目级 vs 用户级

类型哪个
"用户偏好"用户级（个人）
"项目用 Postgres"项目级 + git
"feedback：测试不能 mock"看团队共识。共识 → 项目级；个人偏好 → 用户级
"项目代号 P-1234"项目级

冲突时用户级覆盖项目级（特例化原则）。

3.2 多人写 Memory 的冲突

Alice 的 Claude 写了 "auth 用 OAuth"；Bob 的 Claude 写了 "auth 用 SAML"。git 合并冲突。

防御：

  • 项目级 Memory 修改要走 PR review（避免直接 push）
  • Memory 文件粒度细（一个 topic 一个文件，减少冲突面）
  • MEMORY.md 索引上简短，详情在子文件

3.3 Memory 的"作者元信息"

跨人共享时，元信息变得重要：

---
name: auth_decision
description: auth 模块技术选型记录
type: project
author: alice (via Claude session 2026-05-07)
---

OAuth2 + Auth0
**Why:** 团队 2026-05-06 会议决定，避免自建身份系统
**How to apply:** 不要回头讨论 SAML / 自建

加 author 和决策日期，让接手者知道权威性来源。

4. 外部任务系统：Linear / Jira / GitHub Issues

agent 之间的协作往往挂在 ticket 上。Claude 与外部任务系统的交互是上下文工程的重要部分。

4.1 Reference Memory 指向外部系统

---
name: bugs_tracker
description: pipeline bug 跟踪位置
type: reference
---

Pipeline bugs tracked in Linear project "INGEST"
URL: https://linear.app/team/team/proj/INGEST

When user mentions a pipeline bug, check INGEST first.

这种 reference memory 让 Claude 知道去哪里找权威信息。

4.2 Ticket 作为任务接力棒

跨人协作的长任务往往以 ticket 为载体：

  • Alice 的 Claude 创建 Linear issue
  • Bob 的 Claude 接手时读 issue（描述 + 评论）
  • 各自更新 issue 的状态和评论
  • 完成时关闭

ticket 描述比 PR description 更"长寿"，是更好的跨人接棒载体。

4.3 Ticket 的写作纪律

Claude 写 ticket 时应该：

  • Summary：一句话目标
  • Context：为什么做这个、上游需求是什么
  • Acceptance criteria：怎么算完成
  • Constraints：已知约束（性能要求、兼容性等）
  • Out of scope：不做什么（防止接手者越界）

这套结构让任何 Claude 接手都能 30 秒理解并行动。

5. 异步管线：Claude → 外部 → Claude

更复杂的拓扑：Claude A 输出到外部系统，Claude B 异步读取继续。

5.1 典型例子

Claude A（开发会话）:
  完成功能实现 → 创建 PR

GitHub Actions:
  跑 CI → 生成测试报告

Claude B（review 会话）:
  读 PR → 读 CI 结果 → 写 review 评论

Claude C（修复会话）:
  读 review 评论 → 修改代码 → push

Claude B:
  再次 review

每个 Claude 实例独立，但通过 PR 状态串起来。

5.2 异步管线的上下文设计

每个节点的 Claude 实例：

  • 入口契约：从哪里读（PR ID + 当前状态）
  • 状态判断：当前在管线哪一步
  • 产出契约：写到哪里（PR 评论、新 commit、issue 更新）
  • 触发下一步：通过状态变化让下一个 Claude 知道

这本质上是状态机 + 消息队列的设计思想，但消息总线是 GitHub / Linear。

5.3 幂等性

异步管线的关键属性：幂等。

  • 同一个 PR 被多次 review 不应重复评论
  • 同一个 issue 被多次自动化不应重复回复
  • 同一个 commit 不应被处理两次

实现：

def claude_review_pr(pr_id):
    # 检查是否已经评论过（用特殊 marker）
    comments = gh.list_pr_comments(pr_id)
    if any("<!-- claude-review-v1 -->" in c.body for c in comments):
        return "Already reviewed"

    review = generate_review(pr_id)
    gh.add_pr_comment(pr_id, f"<!-- claude-review-v1 -->\n{review}")

注释里的 HTML 注释作为幂等标记，肉眼不可见但可被 grep 到。

6. Notification 与 Status：让人类知道 agent 在做什么

多 agent 协作时，人类容易"失联"。设计良好的协作要让人类能监控。

6.1 通知策略

事件通知方式
Claude 开始重要任务Slack 消息（@相关人）
任务阻塞需要决策邮件 + Slack
任务完成PR/issue 评论（@原请求者）
CI 失败需要修Slack + GitHub notification
代码冲突需要解决同上

注意"重要"和"完成"才通知，过程不要骚扰。

6.2 Status 透明

Claude 工作时应该让人类知道当前状态。例子：

PR #123 状态:
  CI: ✅ 通过
  Claude review: 进行中（3/8 文件）
  人类 review: 等待

这种 status board 比"Claude 默默工作"对协作友好得多。

7. 权限与安全在多 Agent 中

跨 agent 协作放大了安全风险：

7.1 凭据隔离

每个 Claude 实例的凭据：

  • 用户的 Anthropic API key（Claude 调用 API）
  • 用户的 GitHub token（Claude 操作 git）
  • 用户的 Linear API key
  • ……

这些凭据不应通过 agent 间通信传递。每个 Claude 实例独立读自己环境的配置。

7.2 操作审计

跨 agent 操作应可追溯：

  • "这个 PR 是哪个用户的 Claude 创建的？"
  • "这个 commit 的真正作者？"

实现：

  • Git 配置正确的 user.name / user.email
  • Bot 操作打 prefix（"[Claude]" 或 "[claude-bot]"）
  • 关键操作记日志（参见 13 篇）

7.3 跨用户的 Memory 污染

Alice 在共享项目里写了一条 memory，Bob 的 Claude 读到。如果 Alice 的 memory 错了 → Bob 的 Claude 被误导。

防御：

  • 项目级 Memory 走 PR review
  • Memory 冲突时优先 git 历史 / 工具结果
  • 不轻信跨人的 reference memory

8. MCP server 作为共享能力

MCP（Model Context Protocol）是另一种共享机制：多个 Claude 实例可以通过同一个 MCP server 访问共享资源。

例子：

  • 内部知识库 MCP server → 所有 Claude 都能查
  • 自建任务系统 MCP server → 协作的中央调度
  • 数据库查询 MCP server → 共享数据视图

MCP 的工程意义：把"agent 之间的协作协议"沉淀成"server 提供的稳定接口"。

8.1 MCP vs Hook vs 直接共享

机制谁触发共享什么
MCP serveragent 主动调用能力（工具）
Hookharness 事件信号
直接共享（git/Memory）异步读写状态

设计协作时混用：MCP 提供工具，git 携带状态，Hook 触发自动化。

9. 协作的元信息：让 agent 知道自己在哪个上下文

跨 agent 协作时，每个 Claude 实例应该清楚自己的"角色"：

# CLAUDE.md (project level)

## Role definitions

When this project's Claude session is invoked via:
- `gh pr review` automation: act as code reviewer, focus on style + safety
- `linear-cron` job: act as triage assistant, only update ticket status
- 用户直接对话: act as developer, full capabilities

通过 CLAUDE.md 或环境变量，让 Claude 知道"我是谁、我该做什么、不该做什么"。这是多 agent 系统里角色边界的体现。

9.1 角色边界的意义

没有角色：每个 Claude 实例做"它觉得该做的" → 互相踩脚 / 重复工作 / 越界。

有角色：每个 Claude 实例知道职责范围 → 协作有秩序。

例子：

  • "Claude reviewer" 不主动 push 代码
  • "Claude dev" 不写 review 评论
  • "Claude triager" 只更新 ticket，不动代码

10. 协作的失败模式

10.1 状态不一致

Alice 的 Claude 看到的 PR 状态和 Bob 看到的不一致 → 决策冲突。

防御：每个动作前重新拉最新状态（git fetch、gh pr view）。

10.2 重复工作

两个 Claude 同时尝试修同一个 bug。

防御：

  • ticket "assigned" 字段使用强约束
  • 操作前检查"是否已有人在做"
  • 长任务用 lock（commit empty marker、claim file）

10.3 决策反复

Claude A 决定方案 X → Claude B 接手推翻为 Y → Claude C 又改回 X。

防御：

  • Decisions 写 Plan 和 commit message
  • 推翻决策必须给理由
  • 关键决策需要人类确认

10.4 角色越界

代码 review 的 Claude 自作主张推 commit。

防御：CLAUDE.md 角色定义 + 工具权限限制。

10.5 通知风暴

每个动作都通知 → 噪音淹没真正重要的事。

防御：分级 + 静音规则。

10.6 跨 Memory 污染

不同项目的 Memory 互相串。

防御：Memory 路径里包含项目标识，加载时严格按 cwd 决定。

11. 给 Agent 设计者的可迁移规则

  1. agent 之间通过共享物理载体协作：git、文件、ticket，不通过内存
  2. 每个共享载体的语义要明确：commit message 写 Why、PR description 写 Test Plan
  3. 角色边界要显式：CLAUDE.md 定义角色，不要让 agent 自由发挥
  4. 异步管线要幂等：用 marker、状态检查防重复
  5. 凭据严格隔离：不通过 agent 间通信传递
  6. 操作审计可追溯：commit author、bot prefix、日志
  7. 关键决策需要人类参与：自动化要留确认点
  8. 通知分级：重要事件才打扰人
  9. 状态实时拉取：不依赖记忆中的 PR 状态
  10. 协作协议沉淀为 MCP：稳定的协作接口比临时脚本好

12. 整个系列的一句话总结

回顾全部 16 篇文档，可以浓缩成一句话：

上下文工程不是让模型看到更多，是让模型在每一刻看到正好的那部分。

具体地：

  • 分层（主、§1）保证不同生命周期的信息分流
  • Cache（01）压低重复处理成本
  • 信任分级（02）防止注入污染决策
  • 子 agent（03）扩展上下文容量上限
  • Plan/Todo（04）管理会话内的过程性状态
  • Hooks（05）让外部世界主动给信号
  • 时间感知（06）让 agent 知道"现在"
  • 算法（07）保证拼接和压缩的不变量
  • 工具描述（08）是 prompt 的一部分
  • CLAUDE.md（09）让项目级知识进入上下文
  • 错误恢复（10）让异常成为决策输入
  • Streaming/中断（11）维护实时一致性
  • 多模态（12）扩展感知通道
  • 可观测（13）让黑盒可调试
  • 会话接力（14）跨时间连续推进任务
  • 多 Agent 协作（15）跨实例协调

每一篇都是把"信噪比最大化"这个原则放在不同维度上的展开。

13. 系列完整索引

#主题
主智能体上下文工程实现
01Prompt Cache 与成本
02注入与信任边界
03子智能体隔离
04Plan Mode 与 Todo 状态机
05Hooks 与外部信号
06知识截止与时间感知
07压缩与拼接算法
08工具描述作为上下文
09CLAUDE.md 与项目配置
10错误恢复与上下文修复
11Streaming 与中断
12多模态上下文
13可观测性与调试
14会话接力与长任务
15多 Agent 协作与外部共享（本篇）

14. 写在最后

这个系列从一份总览开始，逐渐展开成 16 份文档。覆盖了从最底层（cache 字节匹配）到最顶层（多 agent 系统协调）的所有上下文工程问题。

但即使 16 篇也不可能完整。还有一些角落没深入：

  • 模型自身的 thinking 模式（extended thinking）对上下文的特殊使用
  • 超大 context（>1M）的边际成本曲线
  • agent 蒸馏（用大 agent 训练小 agent）的上下文蒸馏
  • 多语言（非英语）任务的 prompt 适配
  • 隐私合规（GDPR）下的 Memory 管理

这些可能值得另一组文档。但作为通用 agent 的上下文工程基础，这 16 篇应该足以让一个有经验的工程师从零设计一个生产级 agent 系统。

愿你的 agent 在每一刻都看到正好的那部分。

avatar
文章
阅读
粉丝