# Repository context for coding agents

> A practical guide to instructions, knowledge routes, operational playbooks, and evidence.

By RepoChicken. This guide explains the method behind the proposed audit service. It makes no promise of improved agent performance.

## What is repository context?

Repository context is the information an agent can use to interpret and change a codebase: instructions, source files, architecture decisions, setup commands, tests, and domain knowledge. The existence of a document does not establish that an agent found, loaded, or followed it.

## Agent instructions

An instruction file such as AGENTS.md communicates repository-wide constraints and routes readers to deeper material. Which files apply depends on the chosen tool and configuration. Verify that environment rather than assuming a filename guarantees discovery.

Keep routing and durable rules concise. If a runtime changes, revise the relevant operational playbook and remove contradictory instructions wherever they remain.

## Knowledge routes

A documentation index links focused topics so a reader can find relevant detail. Useful topics include architecture boundaries, business rules, and workflow procedures. Work with the documentation your team already maintains; no new format or platform is required.

## Repository context audit checklist

1. **Fix the scope.** Record the repository commit, chosen coding-agent setup, and workflows being inspected.
2. **Map the instructions.** Locate entry points such as AGENTS.md and tool-specific configuration. Check which directories and tasks each instruction applies to in the agreed environment.
3. **Compare guidance with code.** Check setup and test commands, architecture descriptions, and conventions against the actual configuration. Do not execute commands without permission.
4. **Trace missing or conflicting context.** Follow documentation links, identify contradictions, and distinguish missing knowledge from instructions that are merely long.
5. **Write verifiable findings.** Include the source file, snapshot, consequence, confidence, recommended correction, and an acceptance check. Label untested behavior as a validation gap.
6. **Agree the handoff.** Prioritize changes and identify an owner. Treat implementation and repeated agent task evaluation as separately scoped work.

For example, a stale test command is a documentation defect if it disagrees with the repository configuration. Whether correcting it improves agent task completion remains a separate question requiring controlled trials.

## Workflow playbooks

A playbook should state the environment, commands, expected result, and limits on what the operator may change. For a port conflict, identify the owner before deciding whether to reuse your own container or select another port.

The RepoChicken sample found guidance to stop an unidentified port owner. Its correction added an ownership check and an explicit alternate port. No service interruption was observed during the audit.

## What makes a finding actionable?

An actionable finding names a fixed repository snapshot, exact evidence, consequence, confidence, recommendation, and acceptance check. A possible failure should be labeled a hypothesis until it is observed.

The sample audit found internal documentation packaged into the public nginx image. Its acceptance check is concrete: public pages load while internal guidance returns HTTP 404 after a rebuild. This is an observed publication-boundary correction, not a coding-agent productivity result.

## Audit versus implementation versus evaluation

An audit inspects evidence and recommends changes. Implementation changes the repository. Evaluation tests resulting behavior with fixed tasks and controlled conditions. These are separate activities and should be scoped explicitly.

A before/after evaluation should hold the task, agent configuration, and environment constant where possible, repeat runs, and record failures and inconclusive outcomes. Byte counts and one successful task are not sufficient evidence of a performance gain.

## Related material

- [Proposed audit and scope](/index.md)
- [First-party demonstration report](/sample-audit.md)
- [Human-readable guide](/repository-context)