Agent-Navigable Repositories

Published

Jul 14, 2026

Updated

Jul 15, 2026

Reading time

9 min read

A repository is agent-navigable when a contributor — human or automated — can discover its operating rules, locate the relevant subsystem, run the right validation, and leave a reviewable change without hidden tribal knowledge. This is not prose optimization for a model; it makes delivery constraints explicit and executable for people, CI, and agents alike.

The discipline matters most at the scale a managed edge-orchestration layer runs at, where dozens of services share one delivery surface and an unfindable boundary is traffic nobody is watching. Optimi holds its own repositories to that bar: Performance, Security, and Visibility work is only as trustworthy as the path an agent took to produce it.

What makes agent-navigable repositories work

Agent-navigable repositories build on an existing convention, not a new file format: most coding-agent products read a plain-Markdown instruction file — commonly AGENTS.md — at the repository root and in nested directories, closest file winning on conflict. There are no required fields, which is why discipline matters more than syntax: discoverable rules, a route to the right subsystem in one or two hops, a runnable check that matches CI, and a reviewable handoff instead of a transcript to replay.

Research comparing developer-written and AI-generated instruction files found they are not interchangeable: hand-written files produced a modest, measurable gain in task success, while auto-generated ones that mostly restated the README made agents explore more and spend more tokens without finishing faster or more reliably than agents given no context at all. The lesson: a map earns its place only if a human owner reviewed it and it tells an agent something the source tree can't already show.

Make the Acme Shop route discoverable

The shared scenario is ACME-1842: checkout-api must reject a missing cart country before calculating tax. The agent shouldn't infer where this belongs from a repository dump — it needs a small route: root instructions, local instructions, a map, and the focused check.

root:
baseline: "bun run test:checkout"
acceptance: "bun run ci:checkout"
restricted_paths: ["infra/**", "services/payments/**", ".env*"]
handoff: "task ID, base SHA, changed paths, checks, unresolved risk"
services/checkout-api:
owner: "commerce-platform"
focused_check: "bun run test:checkout -- tax"
compatibility: "preserve TAX_* error codes"
data_rule: "synthetic fixtures only"

Root instructions define repository-wide rules: clean baseline, package manager, restricted paths, security handling, evidence format. Local instructions define only genuine differences: checkout-api's error-code compatibility, focused command, owner review. Link to deeper documents rather than duplicating volatile architecture detail.

Prompt guidance can tell an agent to read both files; enforcement belongs elsewhere. The sandbox limits filesystem and network authority, and CI applies path, test, and review gates — a local instruction file saying "do not edit payments" does not technically prevent an edit, it only tells a well-behaved agent where the line is.

Publish a compact repository map for agents

An architecture map should identify deployable services, primary entry points, owners, data boundaries, and commands. It is a map, not an encyclopedia. Stable directory names and ownership metadata remain useful across IDEs, CI, and agent tools.

services:
checkout-api:
  entry: services/checkout-api/src/server.ts
  tests: services/checkout-api/tests
  owns: "cart validation and tax quote contract"
  depends_on: "tax-provider adapter"
payments-api:
  owner: "payments"
  boundary: "no checkout-api writes"
platform:
path: infra/
change_rule: "separate reviewed task"

Keep generated files, lockfiles, vendored code, and secret-bearing paths out of default retrieval. An agent should start with the task and map, then use targeted search. Loading an entire monorepo costs context and can bury the constraint that matters.

Resist letting the map grow into an encyclopedia — record only what the source tree can't already tell an agent. commerce-platform's loyalty-service addition was one entry, one owner, one dependency edge, not a rewrite.

Layer coding agent context without duplicating docs

A single root file works until a monorepo has more than a few owners, then it's too vague for one package and too specific for the others. Most agent tooling has converged on nested files instead, closest file winning on conflict. checkout-api and payments-api both carry local files; showing the effective, merged coding agent context for a given path removes the guesswork:

resolve services/payments-api/webhook.ts
1. root AGENTS.md                  -> baseline, restricted_paths
2. services/payments-api/AGENTS.md -> owner=payments, no cross-service writes
effective: { baseline: "bun run test:checkout", owner: "payments" }

Two failure modes follow: a local file can silently contradict the root instead of narrowing it, unnoticed until an audit; and a temporary override can outlive its purpose because nothing forces it to expire. Treat an override like a feature flag, and apply the same non-redundancy rule: a nested file earns its place by stating only what differs.

Make the baseline and handoff reproducible

Declare the runtime, package manager, formatter, compiler, test runner, and required services. Record the base commit, lockfile state, image or runtime version, and command. A clean baseline lets the agent distinguish its failure from an existing one.

[ACME-1842] read: AGENTS.md -> services/checkout-api/AGENTS.md
[ACME-1842] map: checkout-api owner=commerce-platform
[ACME-1842] baseline: bun run test:checkout -- tax -> PASS (12 tests)
[ACME-1842] scope: services/checkout-api/** only
[ACME-1842] handoff: base=4e91c2a checks=focused-pass risk=none

Store durable state in the issue, branch, pull request, CI artifacts, and a concise handoff: selected approach, changed paths, validation, known failure, next decision. A permanent free-form progress file in every directory becomes stale context mistaken for current truth.

Validate navigation and recover from gaps

• Positive validation: a fresh workspace locates checkout-api from the root map, passes the baseline, and runs the documented focused check without an undocumented service.
• Negative validation: a task that attempts services/payments-api/** is directed to that owner's path and is rejected by the task path policy when not in scope.
• Failure validation: remove the declared tax-provider test double. The run should report the missing prerequisite and stop with the command and base SHA, not invent a production credential or silently skip the test.
• Drift validation: periodically review the map and instruction files against what exists — commerce-platform learned this when loyalty-service's test command changed and its local file didn't.

Recovery means repairing the map or setup contract in a reviewed change, then rerunning from a clean workspace. If a task legitimately crosses a boundary, create a new contract with the second owner instead of broadening local instructions: ACME-1843 needed a field from checkout-api for payments-api's reconciliation, so the owners added a versioned event-contract entry rather than a cross-service write.

Troubleshooting

Related guides

• Build the coding-agent harness
• Constrain coding-agent sandboxes
• Scale agent-first delivery

Authoritative references

• OpenAI: Harness engineering: leveraging Codex in an agent-first world, February 11, 2026
• Anthropic: Effective harnesses for long-running agents
• Anthropic: Effective context engineering for AI agents
• AGENTS.md: an open format for coding agents
• Gloaguen et al.: Evaluating AGENTS.md, February 12, 2026
• OWASP Top 10 for LLM and GenAI