agent-messaging

Agent 消息传递

概述

Agent 间沟通不畅是大多数多 Agent 协作失效的根本原因：臃肿的上下文会淹没重点，不精确的提示词会导致错误结果，草率的交接则会丢失关键信息。

核心原则： 只提供 Agent 所需的上下文，不多不少。每条消息都应围绕接收者，而非发送者来组织。

首要原则

NO AGENT DISPATCH WITHOUT A STRUCTURED BRIEF

如果你没有整理好上下文，Agent 就会浪费 token 来揣摩你的意图。

适用场景

适用于：

• 为子 Agent 编写提示词（Agent 工具派发任务）
• 向团队成员发送消息（SendMessage）
• 向调用者或团队负责人提交结构化报告
• 在 Agent 之间交接工作（从实施者到审查者，从研究者到负责人）
• 决定应包含或排除哪些上下文

可与以下内容配合使用：

• godmode:delegated-execution — 为实施者／审查者子 Agent 设计提示词
• godmode:parallel-execution — 为并行调查设计提示词
• godmode:team-orchestration — 为团队协作设计消息

入门规范

BEFORE dispatching any agent or sending any message:

1. RECIPIENT: Who receives this? (subagent, teammate, team lead)
2. OBJECTIVE: What must they DO? (implement, investigate, review, report)
3. CONTEXT: What must they KNOW? (only what is relevant to their task)
4. DELIVERABLE: What must they RETURN? (format, content, detail level)
5. CONSTRAINTS: What must they NOT do? (scope limits, file restrictions)

Skip any step = unfocused agent, wasted tokens

子 Agent 提示词设计

精简上下文原则

无关上下文会分散子 Agent 的注意力。更多上下文不等于更好的上下文。

digraph context_decision {
    "Task follows existing pattern?" [shape=diamond];
    "Task depends on other tasks?" [shape=diamond];
    "Lean context" [shape=box style=filled fillcolor=lightgreen];
    "Full context" [shape=box];

    "Task follows existing pattern?" -> "Lean context" [label="yes - supply pattern ref"];
    "Task follows existing pattern?" -> "Task depends on other tasks?" [label="no"];
    "Task depends on other tasks?" -> "Full context" [label="yes"];
    "Task depends on other tasks?" -> "Lean context" [label="no - standalone"];
}

精简上下文（独立任务的默认方式）：

You are implementing: [1-2 sentence description]

File to modify: [exact path]
Pattern to follow: [reference to existing function/test]
What to implement: [specific requirement]
Verification: [exact command to run]

完整上下文（用于依赖其他任务或较复杂的任务）：

You are implementing Task N: [task name]

## Task Description
[FULL TEXT of task - paste it, do not make the subagent read a file]

## Context
[Where this fits, what preceded it, architectural decisions]

绝不要让子 Agent 阅读计划文件。 直接粘贴相关内容。阅读文件会浪费 token 和注意力，使其关注无关章节。

子 Agent 任务说明模板

每份子 Agent 任务说明都应包含以下部分：

部分	用途	必需
角色	Agent 要执行什么工作	是
任务	要执行的具体工作	是
上下文	理解任务所需的信息，不多不少	是
文件	要处理的确切路径	是
约束	不要做什么、范围边界	是
验证	如何确认成功	是
交付格式	要反馈什么内容	是
问题	开始前提问的许可	建议

有效与无效的任务说明

无效 — 过于含糊，缺乏结构：

Fix the tests in the auth module. They're failing.

无效 — 上下文过多：

[Paste entire 500-line plan file]
Your task is Task 7, which is about auth tests.

有效 — 结构清晰，重点明确：

You are resolving 3 failing tests in src/auth/session.test.ts.

Failures:
1. "should reject expired sessions" - expects 401, gets 200
2. "should renew valid sessions" - timeout after 5s
3. "should handle concurrent sessions" - race condition

Context: Session management was refactored in commit def456.
The validateSession() function now returns a Promise instead of sync.

Files:
- Fix: src/auth/session.test.ts
- Reference: src/auth/session-manager.ts (the refactored code)
- Do NOT modify: src/auth/session.ts (production code is correct)

Verification: npm test -- --testPathPattern=session.test

Report: Root cause per test, what you changed, test results.

团队消息设计

点对点消息

使用类型为 "message" 的 SendMessage 进行直接协作。

按以下结构组织消息：

[WHAT] - One line summary of the point
[DETAIL] - Supporting information (if needed)
[ACTION] - What you need from the recipient (if anything)

有效：

SendMessage -> backend teammate:
"The profile API needs a PUT /profile/preferences endpoint.
Frontend needs to update preferences without replacing the full profile.
Can you add this to the contract before implementing?"

无效：

SendMessage -> backend teammate:
"Hey, I was working on the frontend and I noticed we need
some changes. The profile page has this preferences feature where
users can update without replacing everything and I think we need
a new endpoint for that. What do you think? Also I noticed..."

广播与直接消息

digraph message_type {
    "Who needs this information?" [shape=diamond];
    "Entire team?" [shape=diamond];
    "broadcast (expensive)" [shape=box];
    "SendMessage to specific teammate" [shape=box style=filled fillcolor=lightgreen];

    "Who needs this information?" -> "Entire team?";
    "Entire team?" -> "broadcast (expensive)" [label="yes - convention change, critical blocker"];
    "Entire team?" -> "SendMessage to specific teammate" [label="no - most cases"];
}

仅在以下情况下广播：

• 会影响所有队友的约定或模式变更
• 导致所有工作停滞的关键阻碍
• 共享资源冲突

其他所有情况均使用直接消息（状态报告、问题、发现、协作）。

向团队负责人汇报

完成任务时，报告以下内容：

COMPLETED: [task name]
RESULT: [one-line summary]
FILES CHANGED: [list]
FINDINGS: [anything the lead or other teammates should know]
CONCERNS: [anything that might affect other tasks]

交接格式

从实施者交接给审查者

## What Was Built
[Summary - what changed and why]

## Files Changed
[Exact paths, one per line]

## Test Results
[Pass/fail counts, any notable results]

## Self-Review Notes
[Issues found and resolved during self-review]
[Remaining concerns]

## Verification Command
[Exact command to run]

从审查者交接给实施者（请求修复）

## Issues Identified
[List each issue with file:line reference]

## Priority
- Blocking: [must resolve before approval]
- Important: [should resolve]
- Suggestion: [consider for improvement]

## Scope Boundaries
[Do not refactor while fixing — stay focused]

从调查者汇报给负责人（调试／研究）

## Hypothesis Under Test
[What was being investigated]

## Evidence
- Supporting: [evidence favoring the hypothesis]
- Contradicting: [evidence against the hypothesis]

## Confidence
[High/Medium/Low with reasoning]

## Recommendation
[Next steps based on findings]

## Cross-Cutting Discoveries
[Anything that affects other investigations]

上下文管理

应包含的内容

• 确切的文件路径（始终使用绝对路径，切勿使用近似路径）
• 原样的错误消息（不要改述）
• 相关代码片段（不要提供整个文件）
• 引用时注明具体行号
• 可直接复制粘贴的验证命令
• 依赖项和前置条件

应排除的内容

• 完整的计划文件（只粘贴相关任务）
• 已完成任务的详情（除非它们是依赖项）
• 与任务无关的项目历史
• 已被否决的替代方案
• 对显而易见模式的冗长解释

上下文预算指南

Agent 类型	目标上下文	理由
实施者	任务 + 模式 + 文件	专注于构建
审核者	规范 + 差异 + 检查清单	专注于验证
调查者	假设 + 证据位置	专注于发现
Teammate 消息	所需操作 + 最少上下文	尊重对方的上下文窗口

错误升级

当 Agent 遇到无法解决的问题时：

digraph escalation {
    "Agent hits obstacle" [shape=box];
    "Can resolve independently?" [shape=diamond];
    "Resolve it" [shape=box];
    "Affects only own task?" [shape=diamond];
    "Report to lead at task completion" [shape=box];
    "Message lead immediately" [shape=box];
    "Affects other teammates?" [shape=diamond];
    "Message affected teammates" [shape=box];

    "Agent hits obstacle" -> "Can resolve independently?";
    "Can resolve independently?" -> "Resolve it" [label="yes"];
    "Can resolve independently?" -> "Affects only own task?" [label="no"];
    "Affects only own task?" -> "Report to lead at task completion" [label="yes"];
    "Affects only own task?" -> "Affects other teammates?" [label="no - blocks others"];
    "Affects other teammates?" -> "Message affected teammates" [label="yes"];
    "Affects other teammates?" -> "Message lead immediately" [label="no - requires lead decision"];
}

升级消息格式：

BLOCKED: [what is blocked]
CAUSE: [why it is blocked]
ATTEMPTED: [what was tried]
NEED: [what would unblock - decision, information, or fix]

认知陷阱

合理化说法	事实
“上下文越多总是越有帮助”	上下文越多 = 干扰越多。精简的上下文能让独立任务取得更好的结果。
“他们可以自行判断什么是相关内容”	Agent 会浪费 token 来解析无关内容。请为他们筛选上下文。
“直接阅读计划文件就行”	计划文件包含所有任务。Agent 会被其他任务分散注意力。请只粘贴相关部分。
“我会非正式地说明，不需要结构”	无结构的提示词会产生无结构的结果。请使用模板。
“简短的消息显得生硬”	简洁的消息体现了对接收者上下文窗口的尊重。
“我会汇报发现的所有内容”	汇报可采取行动的内容。发送前过滤噪声。

护栏

禁止：

• 让子 Agent 阅读计划文件（应直接粘贴内容）
• 发送无结构的提示词（如“修复测试”）
• 包含无关上下文（如“这是完整历史记录……”）
• 将广播用于常规更新
• 省略交付物格式部分（Agent 将不知道需要汇报什么）
• 未说明已尝试过什么就升级问题

必须：

• 为每个提示词设定角色、任务、上下文、约束和交付物
• 直接粘贴内容，而非引用文件
• 在实施提示词中包含验证命令
• 优先使用直接消息，而非广播
• 在每次交接中包含文件路径
• 将跨领域发现报告给受影响的相关方

集成

使用方：

• godmode:delegated-execution — 实施者和审核者提示词
• godmode:parallel-execution — 并发 Agent 提示词
• godmode:team-orchestration — 团队沟通模式

互补：

• godmode:fault-diagnosis — 调试调查报告的结构
• godmode:quality-gate — 审核请求的结构
• godmode:completion-gate — 完成报告的结构