本技能提供使用 Claude Code 设计多智能体系统的架构模式，核心目标是编排大量子智能体时避免上下文溢出。
一、岗位描述法：写智能体代码前，先像招聘一样撰写人类岗位描述，明确职责、所需技能、成功指标与升级条件，再逐项翻译为架构元素（职责→工作流，技能→工具权限，成功指标→输出模式，升级条件→错误处理，入职材料→技能/手册）。
二、共享文件夹模式：当 10 个以上子智能体同时返回详细报告时，编排者上下文会过载。做法是子智能体把报告写入 .claude/workspace/{phase}/{name}.md，只返回状态与路径，下游智能体直接读取上一阶段输出，编排者只读 manifest 而非完整报告，从而保持上下文精简、避免摘要传递中的信号丢失。
三、手册模式：以单一手册按章节组织，子智能体始终读基础章节，再按任务读相关领域章节，替代大量碎片化微技能，降低脆弱性与维护负担。
四、上下文预算策略：共享文件夹用于 5 个以上子智能体及相互依赖场景；上下文代理用于返回冗长结果的研究型智能体；清单文件用于编排者只需状态；分块执行用于串行阶段。架构决策树按智能体数量（1-3 直接编排、4-10 共享文件夹、10+ 分阶段加清单）与是否需直接通信来选型。
五、共享状态变更安全：多个智能体可能推进同一工作项状态，写前需三步守卫——重读最新状态、校验前置条件、以单次原子操作写入；不匹配则中止并记录冲突。以 GitHub 标签为例，应合并为一次 gh issue edit {id} --remove-label {old} --add-label {new}，避免两次调用间出现中间态窗口。
六、反模式：斜杠命令作编排、编排者转发全部上下文、每个微任务一个技能、子智能体返回完整报告，分别对应改用子智能体、共享文件夹、手册章节、仅返回路径。
演进路径通常为：斜杠命令 → 编排者加子智能体 → 共享文件夹 → 手册整合。当工作者需直接互相通信而非仅回报编排者时，应改用 Agent Teams（共享任务列表、智能体间消息、独立上下文窗口），其完整设置与编排模式参见 agent-teams 技能。