Skip to content

Seeding Agent Context: Breadcrumbs in Code

Seed breadcrumbs — files, comments, and markers — that agents discover during exploration and use to shape their behavior.

Also known as

Providing Context to Agents, Context Priming, Breadcrumbs in Code. Seeding embeds contextual hints directly in the codebase for agents to discover during exploration. For the general technique of loading relevant context before a task, see Context Priming.

Why seeding works

Agents explore codebases by reading files. What they find shapes what they do. Seeded context is persistent: it influences every session that touches that codebase region, shifting context management from a per-session concern to codebase hygiene.

The durability spectrum

Breadcrumbs vary in how reliably they influence agent behavior.

graph TD
    A["Mechanical enforcement<br>(linters, tests, CI)"] -->|highest durability| B["Structured context files<br>(AGENTS.md, CLAUDE.md, .claude/rules/)"]
    B --> C["Type annotations<br>and interfaces"]
    C --> D["Example files and<br>reference implementations"]
    D --> E["Inline decision comments"]
    E -->|lowest durability| F["TODO / FIXME markers"]

Mechanical enforcement outperforms written guidelines: the agent encounters the constraint at the point of violation and the error message becomes context for the next attempt (Lavaee).

Techniques

Directory-scoped context files

The AGENTS.md open standard defines a dedicated file for agent context, adopted by 60k+ projects and 25+ platforms (agents.md). Agents read the nearest AGENTS.md in the directory tree; subdirectory files override project-level instructions.

Claude Code uses CLAUDE.md files with the same scoping. The .claude/rules/ directory adds path-scoped rules for matching files (for example, src/api/**/*.ts).

Progressive disclosure over monoliths

A lean entry-point file (~100 lines) pointing to structured subdirectories outperforms a monolithic instruction file. The repository functions as agent memory, and anything not in context does not exist (Lavaee, "OpenAI Agent-First Codebase Learnings"; see also progressive disclosure for agent definitions).

Inline decision comments

Comments explaining why a decision was made prevent agents from reverting it. Without such a comment, a refactoring agent has no signal the choice is intentional:

// We use optimistic updates here rather than waiting for the server response.
// Reverting to pessimistic updates caused noticeable UI lag in user testing.

TODO and FIXME markers

Placing a TODO or FIXME at the exact location ensures the agent encounters it when editing nearby code, though whether agents treat these as actionable items varies by tool.

Type annotations

Complete type signatures eliminate agent guesswork about return types, parameter shapes, and nullability.

Example files and pattern replication

Agents pattern-match against existing code. A well-written reference implementation communicates conventions more precisely than prose. But agents replicate good and bad patterns alike; poor examples compound drift, a dynamic known as pattern replication risk (Lavaee).

Progress files as breadcrumbs

Long-running agents maintain progress files (for example, todo.md) that subsequent sessions read to get oriented instead of rediscovering the codebase from scratch (Anthropic). Manus uses a continuously updated todo.md as a goal recitation mechanism (Manus).

What to seed versus what to prompt

Seed in the codebase Prompt interactively
Stable conventions and constraints Task-specific requirements
Architectural decisions and rationale What you are building now
Known issues and TODOs Session priorities and scope
Type annotations and interfaces One-off instructions
Progress files for multi-session work Session corrections

Seed durable information; prompt session-specific intent. See Discoverable vs Non-Discoverable Context for the boundary.

Some tools expose a deliberate interactive channel for injecting context mid-session. Claude Code's ! shell escape runs a bash command inline and, as of v2.1.186, feeds the output back to the model for a response by default. A respondToBashCommands: false toggle injects the output as context only instead — a human-in-the-loop way to prime a session with live command output rather than codebase breadcrumbs (Claude Code changelog).

When this backfires

  • Stale breadcrumbs: an AGENTS.md that no longer reflects the codebase misleads the agent. It acts on false premises with high confidence, and stale seeding is worse than no seeding.
  • Pattern replication: agents replicate existing code indiscriminately (pattern replication risk). A single poor reference implementation propagates the anti-pattern across every new file; mechanical enforcement is the only reliable safeguard.
  • Conflicting scopes: nested context files with contradictory instructions cause agents to apply the wrong scope, which is unpredictable and difficult to debug.

Seeding suits stable, long-lived codebases. For short-lived projects, the maintenance overhead may exceed the benefit.

Even accurate seeding is not free. A controlled study found that repository-level context files often reduce coding-agent task success versus no context while raising inference cost by over 20%. Broad architectural overviews can pull agents into unbounded exploration, and LLM-generated files fare worst, with human-curated ones giving only modest gains (Gloaguen et al., "Evaluating AGENTS.md"). Seed lean, specific, hand-written context rather than generated bulk.

FAQ

What should be seeded in the codebase rather than prompted?

Seed durable information: stable conventions and constraints, architectural decisions and their rationale, known issues and TODOs, type annotations and interfaces, and progress files for multi-session work. Prompt session-specific intent instead: task requirements, what you are building now, session priorities and scope, one-off instructions, and corrections. The dividing line is durability.

Does adding an AGENTS.md always improve agent performance?

No. A controlled study found repository-level context files often reduce coding-agent task success versus no context while raising inference cost by over 20%; broad architectural overviews can pull agents into unbounded exploration, and LLM-generated files fare worst, with human-curated ones giving only modest gains (Gloaguen et al.). Seed lean, specific, hand-written context.

What goes wrong with nested context files?

Contradictory instructions across scopes make agents apply the wrong scope, which is unpredictable and difficult to debug. Staleness compounds it: a context file that no longer reflects the codebase leads the agent to act on false premises with high confidence, and stale seeding is worse than no seeding at all.

Key Takeaways

  • Mechanical enforcement is the most durable seeding form: agents cannot ignore a failing check the way they can skip a written guideline.
  • The nearest AGENTS.md/CLAUDE.md wins: subdirectory files override project-level instructions, so scope conventions to the directory they apply to.
  • A single poor reference implementation propagates its anti-pattern across every new file agents write. Audit examples before pointing agents at them, or back them with mechanical enforcement.
  • Progress files persist where chat history does not: write task state to a file like todo.md so the next session picks up instead of rediscovering it.
  • Keep the top-level entry-point file to about 100 lines and link out to structured subdirectories. A monolithic instruction file underperforms it.

Example

A Python monorepo with a data-pipeline package uses multiple techniques together:

The project-level AGENTS.md (repo root) lists the packages and where conventions live:

# Project: data-platform

## Structure
- `pipelines/` — ETL jobs. See `pipelines/AGENTS.md` for conventions.
- `api/` — FastAPI service. See `api/AGENTS.md` for conventions.
- `shared/` — shared utilities imported by both packages.

## Global rules
- All new modules require type annotations.
- Do not modify `shared/schema.py` without updating `docs/schema-changelog.md`.

The package-level pipelines/AGENTS.md scopes the package conventions:

# Pipelines package

## Conventions
- Use `BaseTransform` as the base class for all transform steps.
- Each pipeline has a corresponding test in `tests/pipelines/`.
- Airflow DAG definitions live in `dags/`; do not put business logic there.

## Known constraints
- `ingest_raw.py` uses synchronous S3 calls intentionally — async caused
  throttling issues with the bucket policy. Do not convert to async.

An inline decision comment in pipelines/ingest_raw.py:

# Synchronous S3 client is intentional. Async caused throttling errors
# under the bucket policy in prod (see AGENTS.md — Known constraints).
# TODO: revisit if bucket policy is updated to allow concurrent requests.
s3 = boto3.client("s3")

A typed function signature leaves no ambiguity for the agent:

def fetch_records(
    bucket: str,
    prefix: str,
    since: datetime,
) -> list[dict[str, Any]]:
    ...

An agent editing ingest_raw.py reads the package AGENTS.md, encounters the decision comment, sees the TODO, and understands the typed interface, all without session-level prompting.

Sources

Established — multiple independent sources Last reviewed: 2026-06-24