Structuring Context for AI Agents

AI coding agents — Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, and others — need context about your codebase to help effectively. Without structured context, agents waste time exploring the repository, miss critical architectural decisions, and produce suggestions that violate project conventions.

This is especially true during modernization, where the codebase has hidden dependencies, undocumented business rules, and legacy patterns that are easy to break.

The Context Problem

When an agent encounters a project for the first time, it has two options:

Explore — Read files across the codebase, run searches, piece together an understanding. This is slow, expensive (in tokens and time), and often incomplete.
Read structured context — Load pre-written documentation that explains the project. This is fast, cheap, and accurate.

The difference in cost is substantial:

Approach	Typical Token Cost	When to Use
Read AGENTS.md	200-1,500 tokens	Always first
Read manifest.json	~200 tokens	Discover available context
Read a specific JSON file	200-1,000 tokens	When manifest points to it
Code search (grep/glob)	1,000-3,000 tokens	Pattern matching
Full codebase exploration	50,000-100,000 tokens	Last resort only

Structured context is 50-100x cheaper than exploration. Invest the time to write it once, and every agent session benefits.

Context Discovery Hierarchy

Agents should find information in a predictable order. This hierarchy is widely supported across AI coding tools:

1. Agent config files       .claude/, .cursor/, .github/copilot/
2. Root AGENTS.md           Human-readable project guide
3. .agents/ directory       Machine-readable structured context (JSON)
4. Standard files           package.json, docker-compose.yml, README.md
5. Code search              Grep, glob for pattern matching
6. Full exploration         Last resort — expensive

Each level provides progressively more detail. Most questions should be answered by levels 1-3 without ever reaching level 5.

AGENTS.md Convention

AGENTS.md is a convention adopted by most AI coding CLI tools. Place one at your repository root. The file is auto-discovered by Claude Code, Codex CLI, Gemini CLI, and others.

What to Include

A well-structured AGENTS.md includes these sections:

Section	Purpose
Overview	Brief description of what the project does and its current state
Quick Commands	Build, test, lint commands (most frequently used by agents)
Architecture	System structure, key modules, how they interact
Conventions	Naming patterns, file organization, error handling approach
Forbidden Patterns	Things agents should NOT do, legacy patterns to avoid
Modernization Context	Pointer to `.agents/modernization/` files

Guidelines for writing effective AGENTS.md:

Keep it under 400 lines. Agents have context limits. A 1,000-line AGENTS.md wastes tokens on information the agent may not need for the current task.
Put quick commands at the top. These are the most frequently used section. Agents need to know how to build, test, and lint.
Include forbidden patterns. Agents are helpful but not omniscient. Explicitly state what they should avoid — this prevents the most common mistakes.
Update when architecture changes. Stale context is worse than no context. When you restructure modules, change conventions, or deprecate APIs, update AGENTS.md.

The `.agents/` Directory

For structured, machine-readable context, use an .agents/ directory with JSON files. This is complementary to AGENTS.md — the Markdown file is for humans (and agents reading prose), while JSON files are for programmatic access.

.agents/
├── manifest.json         # Entry point: lists all context files
├── architecture.json     # System structure, layers, components
├── domains.json          # Bounded contexts, business areas
├── workflows.json        # Step-by-step procedures
├── navigation.json       # Key file paths, entry points
└── testing.json          # Test suite index and coverage

manifest.json

The manifest is the entry point. Agents read it first, then load only the files relevant to the current task.

{
  "version": "1.0.0",
  "project": "MyProject",
  "contextFiles": [
    { "file": "../AGENTS.md", "purpose": "Human-readable agent guide" },
    { "file": "architecture.json", "purpose": "System layers and components" },
    { "file": "domains.json", "purpose": "Bounded contexts and boundaries" },
    { "file": "workflows.json", "purpose": "Common development workflows" },
    { "file": "testing.json", "purpose": "Test suite locations and commands" }
  ]
}

This enables progressive disclosure — the agent reads the manifest (200 tokens), identifies which file answers the question, and reads only that file (200-1,000 tokens). Without a manifest, the agent would read everything or resort to exploration.

ModernizeSpec Integration

ModernizeSpec extends the .agents/ pattern specifically for modernization projects. The spec files live in .agents/modernization/:

.agents/
├── manifest.json                # General project context
├── architecture.json
├── modernization/
│   ├── manifest.json            # ModernizeSpec metadata
│   ├── domains.json             # DDD bounded context map
│   ├── complexity.json          # Hotspot scoring
│   ├── extraction-plan.json     # Migration sequencing
│   ├── parity-tests.json        # Behavioral verification
│   └── migration-state.json     # Progress tracking

When an agent detects .agents/modernization/manifest.json, it loads the modernization context. This gives the agent immediate understanding of:

Which bounded contexts exist and how they couple
Where complexity hotspots are
What the migration sequence is
Which parity tests must pass before cutover

See the Integration Overview for detailed setup instructions.

Practical Guidelines

Be Specific About Boundaries

“Do not modify files in src/legacy/” is more useful than “be careful with legacy code.” Agents follow concrete instructions better than vague guidance.

Include Test Commands

Agents need to verify their work. If your test commands require special flags, environment variables, or setup steps, document them prominently.

Document Dependencies

If a service requires Docker containers, environment variables, or external APIs, list them. Agents cannot infer what they cannot see.

Update Regularly

Context that was accurate last month may be misleading today. Treat AGENTS.md and .agents/ files as living documents — update them when the project changes.

What to Include vs. What to Omit

Include	Omit
Build, test, lint commands	Detailed deployment procedures
Architecture overview (layers, modules)	Complete API documentation (use OpenAPI)
Naming conventions and patterns	Individual function documentation (use JSDoc)
Forbidden patterns and gotchas	Historical design decisions (use ADRs)
Migration status and boundaries	Meeting notes or project management details
Key file paths and entry points	Every file in the repository

The goal is enough context to work effectively, not comprehensive documentation. An agent that knows the project structure, conventions, test commands, and forbidden patterns can figure out the rest from the code itself.

Multi-Agent Considerations

When multiple AI agents work on the same project (e.g., one for code generation, another for review), consistent context prevents conflicts:

Single source of truth — One AGENTS.md, not per-agent copies
Shared conventions — All agents follow the same naming, testing, and architecture patterns
File ownership — If agents work in parallel, document which modules belong to which workflow
State awareness — Use migration-state.json so agents know what has been migrated and what remains

Checklist

Before considering your project “agent-ready,” verify:

Item	Status
AGENTS.md at repository root	Required
Quick commands section (build, test, lint)	Required
Architecture overview	Required
Forbidden patterns listed	Recommended
`.agents/manifest.json`	Recommended
`.agents/modernization/` (if modernizing)	Recommended
Context under 400 lines (AGENTS.md)	Recommended
Updated within last 30 days	Recommended