Make AGENTS.md a repostiroy context router

Use the Context Onion Model

And help your coding agents acquire context progressively.

The four Context Onion knowledge layersAn onion-shaped diagram with Current Task at the center, followed by System Understanding, Task Context, and Organizational Context.

Why AGENTS.md needs a routing model

  1. AGENTS.md gives agents a place to start

    A predictable place for repository-specific instructions, conventions, constraints, and guidance.

  2. But context still needs a structure

    Without a clear acquisition model, agents can still search broadly, reconstruct system behavior from code, and discover important constraints late.

  3. Context Onion provides the routing model

    Current Task System Understanding Task Context Organizational Context

    Acquire enough context for the next decision, expand only when needed, then verify.

How the routing model works

  1. Start with the Current Task

    What is being changed, and what outcome is expected?

  2. Orient with System Understanding

    Understand the relevant workflow, architecture, dependencies, and boundaries before exploring implementation.

  3. Narrow into Task Context

    Locate the relevant code, tests, configuration, callers, and nearby examples.

  4. Resolve Organizational Context when applicable

    Load the standards, RFCs, policies, and shared constraints that govern the change.

  5. Verify

    Check the result against the task, system behavior, repository constraints, and applicable organizational guidance.

Expand only when uncertainty remains.

What each knowledge layer contains

  1. Current TaskRequested behavior, success criteria, known scope, task-specific constraints.
  2. System UnderstandingArchitecture, workflows, domain model, service/component dependencies, data flow, lifecycle, ownership boundaries, design rationale.
  3. Task ContextRelevant source, tests, configuration, callers, interfaces, package dependencies, nearby examples.
  4. Organizational ContextRFCs, standards, policies, quality requirements, API conventions, security/compliance guidance, shared engineering constraints.

How to configure AGENTS.md as the router

AGENTS.md
├── Orientation
├── System-understanding routing
├── Task-context routing
├── Constraints
├── Organizational-context routing
├── Verification
└── Context-acquisition policy

Example

# Repository Guidelines

## Orientation
- System overview: `README.md`
- Architecture: `docs/architecture.md`
- Domain terminology: `docs/glossary.md`

## System-Understanding Routing
Read the architecture and workflow documentation for the affected area before changing behavior.

## Task-Context Routing
- Application code: `src/`
- Tests: `tests/`
- Configuration: `config/`
- Nearby patterns: inspect adjacent modules and callers.

## Constraints
- Follow existing conventions and interfaces.
- Keep changes scoped to the requested outcome.
- Do not commit generated output or secrets.

## Organizational-Context Routing
Apply relevant RFCs, standards, policies, and security guidance.

## Verification
Run focused tests first, then the repository's required checks.

## Context-Acquisition Policy
Start with the task. Acquire enough context for the next decision. Expand only when uncertainty remains, then verify.