Agent Systems · core
Repository Instruction Topology
Repository-wide and path-local instructions, precedence, ownership boundaries, and concise executable guidance for coding agents.
Mental model
Instructions form a scoped configuration tree. Broad rules establish invariants, nearer files refine behavior for a subtree, and direct task intent supplies the leaf-level objective. A useful instruction is discoverable, non-contradictory, and paired with the command or artifact that proves compliance.
How to study Repository Instruction Topology
Begin by restating the mental model in your own words, then connect it to a concrete system you have built or operated. Name the mechanism, the constraint it addresses, and the trade-off it introduces. Use GitHub Docs — Adding repository custom instructions, OpenAI — Harness engineering to check details, but close the source before writing your explanation. Retrieval is the learning step; rereading is only preparation.
Next, compare Repository Instruction Topology with Coding Agent Systems, Agent Scope Control, Repository Intelligence. Ask what changes in correctness, latency, resource use, operability, and failure recovery. Complete Build a scoped repository instruction map and preserve the command, input, output, and one failed attempt as evidence. Finish by explaining the idea without jargon to someone who has not studied the track.
Proof of understanding
- Explain the mechanism from first principles and identify the state it reads or changes.
- Give one situation where the concept is the right choice and one where it is not.
- Predict a realistic failure mode before running the drill, then compare the prediction with evidence.
- Connect the result to a roadmap or build artifact instead of treating the concept as isolated trivia.
Where it matters
AGENTS.md hierarchies, repository custom instructions, package-local conventions, generated-code boundaries, and task-specific runbooks.
Common mistakes
- Putting every rule in one root document until relevant guidance is buried
- Repeating the same rule at multiple scopes and letting copies drift
- Writing preferences that cannot be checked while omitting the actual validation command
Learn from primary sources
Practice and explain it back
Build a scoped repository instruction map
Implement instructionMap() for a repository with a root AGENTS.md and a packages/api/AGENTS.md. Return {root, api, precedence, checks}. root must contain exactly three concise repository-wide invariants. api must contain exactly two API-only refinements and must not repeat a root rule. precedence must explain in at least eight words that nearer instructions refine broader instructions without silently overriding direct task intent. checks must list two runnable validation commands.
Expected evidence: A non-duplicative instruction tree with explicit precedence and executable checks.
Open the interactive drill →Review prompts
- A repository has a root instruction file and a stricter one inside packages/payments. What belongs at each level, and how should an agent resolve them for a payment-file edit?
Build evidence
Build a Complete Coding-Agent Harness
Build a repository-local harness that can take one bounded engineering task from initialization through implementation, verification, durable handoff, and explicit termination without relying on hidden machine state or chat memory.
- A fresh isolated workspace can bootstrap and prove readiness from repository-local commands
- Instruction scopes, allowed edit roots, capabilities, budgets, and escalation triggers are explicit and mechanically inspectable
- The run persists goal, progress, evidence, blockers, and the next safe action across a forced restart
- A checker gathers independent evidence and can reject an unsupported maker claim
- The lifecycle terminates only as complete, blocked, failed, cancelled, or escalated with durable evidence
Automate and Evaluate a Maker-Checker Loop
Automate a bounded loop in which a maker attempts one task, an independent checker evaluates explicit acceptance criteria, failures return actionable evidence, and the orchestrator stops on success, escalation, cancellation, or budget exhaustion. Compare it with a baseline harness on a frozen task suite.
- Maker and checker roles have separate inputs and the checker ignores unsupported self-reported success
- The loop has explicit goal, task and retry budgets, durable state, and semantic termination criteria
- A frozen evaluation suite measures success, unsafe actions, cost, latency, retries, and human interventions
- At least one component ablation isolates whether instructions, tools, verification, or retry policy caused the observed change
- Release or rejection follows a declared multi-objective gate rather than pass rate alone