Make AGENTS.md a repostiroy context router

Use the Context Onion Model

And help your coding agents discover knowledge 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.

The Four Context Onion Knowledge layers.

Start with the current task. Acquire broader context only when needed.

The Gap

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.

“There is nothing so useless as doing efficiently that which should not be done at all.”

— Peter Drucker
The Route

How the routing model works

Acquire enough context for the next decision. Expand only when uncertainty remains.

  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. Inspect the Task Context

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

  4. Resolve Applicable Organizational Context

    Resolve 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.

ENOUGH CONTEXT → ACT → VERIFY

The Layers

What each knowledge layer contains

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

Configure AGENTS.md as the context router

AGENTS.md
├── Repository
├── System
├── Conventions
├── Boundaries
├── Verification
└── Context acquisition

REFERENCE PATTERN

A minimal AGENTS.md context router

# AGENTS.md

## Repository

- Runtime: Go 1.23
- Test: `go test ./...`
- Lint: `golangci-lint run`

## System

- Services live in `cmd/`, one main package per binary.
- Shared packages live in `internal/`.
- Tests sit beside source: `foo.go` → `foo_test.go`.
- Architecture: `docs/architecture.md`

## Conventions

- Prefer table-driven tests with the standard `testing` package.
- Follow the internal REST API conventions: `docs/api-rest.md`.
- Relevant standards: RFC 021, RFC 042.

## Boundaries

- Do not edit generated files in `gen/`.
- Do not introduce background jobs without updating `config.json`.

## Verification

Before finishing:

- Run `go test ./...`.
- Run `golangci-lint run`.

## Context acquisition

For behavioral or cross-component changes:

1. Understand the affected workflow before changing implementation.
2. Locate the relevant source, tests, configuration, and callers.
3. Resolve applicable standards and constraints.
4. Expand further only when uncertainty remains.

The specification

Ready to apply the model?

RFC-001 defines the full Context Onion protocol: acquisition sequence, AGENTS.md routing, nested repository behavior, verification, and adoption guidance.

Read RFC-001