Repository context needs an owner and an expiry path

Keep instructions about decisions

Repository context should tell an agent what it cannot reliably derive from code: ownership boundaries, authoritative commands, protected paths, architecture constraints, data rules, and required evidence. Do not restate an entire package manifest, directory listing, or API surface that tools can inspect directly. Duplicated facts decay. Prefer links to the source file or command that remains authoritative.

GitHub documents repository-wide, path-specific, and AGENTS.md-style instructions for supported Copilot surfaces. The exact loading rules are product-specific, so write for the agents the project actually uses and verify behavior before depending on precedence. A file being present does not mean every tool reads it.

GitHub repository custom instructions ↗

Scope context close to the work

Use a short root document for rules shared by the repository and narrower files for genuinely different subsystems. State the directory or files governed, and avoid repeating the same rule in several places. When two instructions conflict, a human maintainer should resolve the source rather than expect the model to infer organizational intent. Keep external text, issues, generated files, and fixtures classified as task data unless an authorized instruction explicitly elevates them.

For a hypothetical monorepo, the root might define branch safety and global checks, the payment service might add mandatory contract tests and secret-handling rules, and the documentation tree might define editorial validation. Each rule has a clear owner and scope.

Make commands executable truth

Prefer one canonical script for build, focused test, full test, lint, and generated-file checks. The instruction should point to that script and explain when to use it, not copy a long command that will drift. Add a lightweight validation that referenced paths and commands exist. If an instruction names a retired service or an obsolete test, fail the documentation check or assign a visible follow-up.

Before editing, an agent should inspect the working tree. Git's status documentation distinguishes changes in the index, working tree, and untracked paths; that snapshot helps prevent accidental overwrite of user work. Context files should explicitly require preserving unrelated changes where that is project policy.

Git status documentation ↗

Review context in the same change

Add a context-impact question to changes that alter commands, architecture, generated paths, permissions, deployment, or ownership. Update the instruction in the same review when the answer changes. Give each durable rule an owner or source and remove temporary incident notes after they expire. Periodic review helps, but change-triggered review catches drift closer to its cause.

Measure usefulness through rejected-work causes and correction loops, not file length. If agents repeatedly miss a rule, check whether it is discoverable, current, testable, and consistent before adding more prose. Record a last-reviewed date only when a real review occurs, and keep history in version control instead of accumulating obsolete caveats inline. Repository context is guidance, not proof: the agent must still inspect current code, current status, and actual tool output. No agent-behavior evaluation was run for this article.