Engineering guide

Agent-Navigable Repositories

Give coding agents and reviewers a reliable route from a task to the smallest relevant code, checks, and delivery evidence.

Published: Jul 14, 2026
Updated: Jul 14, 2026
Reading time: 12 min read

On this page

A repository is agent-navigable when a contributor 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.

Overview

Outcome

An Acme Shop agent can trace a checkout-tax task from root instructions to the correct package, run the declared checks, and hand a reviewer a reproducible result without loading the whole monorepo.

Overview

Prerequisites

Maintain a versioned root instruction file, local exceptions only where behavior differs, ownership metadata, pinned tooling, and a CI job that runs the same acceptance gate documented for contributors.

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 should not infer where this belongs from a repository dump. It needs a small route: root instructions, the checkout-api local instructions, a map, and the focused check.

Progressive repository context for ACME-1842

Task: missing country
Root AGENTS.md
Repository map
checkout-api/AGENTS.md
Focused test and handoff

The map points the agent from the task to checkout-api and its contract tests. It narrows discovery; it does not grant access to payment, infrastructure, or production systems.

Root and local instruction contract

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, and evidence format. Local instructions define only genuine differences: checkout-api's error-code compatibility, focused command, and 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.

Publish a compact repository map

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.

Acme Shop repository map

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 and imports. Loading an entire monorepo costs context and can bury the constraint that matters.

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.

Representative navigation output

[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. A useful handoff gives the selected approach, changed paths, validation, known failure, and next decision. A permanent free-form progress file in every directory can become stale context mistaken for current truth.

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.

Recovery means repairing the map or setup contract in a reviewed change, then rerunning from a clean workspace. If the task legitimately crosses a boundary, create a new contract with the second owner; do not quietly broaden local instructions.

Troubleshooting

Symptom	Likely cause	Evidence to collect	Safe recovery
Agent edits the wrong service	Map lacks entry point or ownership	Search path and task record	Add the missing map edge; restart from the base commit.
Bootstrap needs a local secret	Undeclared environment dependency	Bootstrap log and missing variable name	Replace with a test double or approved ephemeral identity.
Focused check passes, CI fails	Local command is not the acceptance gate	CI command and environment version	Document both loops; reproduce in the CI image.
Local instructions contradict root rules	Stale duplicate guidance	Both files and commit history	Resolve at the root or make the exception explicit and tested.
Handoff is too large to review	Raw logs substituted for evidence	Handoff size and CI artifact	Keep identifiers and bounded excerpts; link full access-controlled artifacts.

Authoritative references

Reduce friction in critical engineering workflows

Talk to Optimi about observable, resilient delivery paths and the architecture that supports reliable engineering systems.

Discuss delivery architecture