Shared vs Private Context

In multi-agent systems, context falls into two categories: shared context that multiple agents need (project conventions, type definitions, architectural patterns) and private context that only one agent needs (implementation details of its specific module, test fixtures for its tests). The distinction matters because shared context is duplicated across every agent that uses it, multiplying token consumption, while private context is loaded only once.

AGENTS.md is inherently shared context — every agent in the project loads it. This makes AGENTS.md the right place for cross-cutting concerns: naming conventions, error handling patterns, coding style, forbidden patterns. Directory-scoped AGENTS.md files create semi-private context — only agents working in that directory load those rules. Use this layering to push module-specific context down to directory scope, keeping the root AGENTS.md lean and universally relevant.

For programmatic orchestration with the Agents SDK, context partitioning is explicit. Each agent's instructions field is its private context. Shared context goes in a shared configuration file that all agents reference. Hand-off messages carry transitional context — just enough for the receiving agent to continue. The goal is always the same: minimize duplication, maximize relevance, and keep each agent's effective context window as open as possible for reasoning.