Reference Repository

Give a coding agent a separate exemplar repository to study, so it can transfer conventions without copying blindly.

Also known as: Exemplar Repository, Cross-Repository Reference, Reference Implementation.

You have probably given an agent an instruction like “make this work like our billing service” or “copy the shape of the old migration, but adapt it to the new stack.” That instruction is more than a pointer to code. It says the shortest useful specification is an existing system. A Reference Repository makes the move explicit: the agent studies a known-good codebase, extracts the transferable rule, and writes a different change in the target repository.

Understand This First

• Context Engineering — the broader discipline of deciding what the agent should see.
• Codebase Map — how an agent orients itself inside one repository.
• Worktree Isolation — why the reference must stay outside the target checkout.
• Copy-Paste Programming — the trap this pattern has to avoid.

Context

At the agentic level, a Reference Repository is an external codebase, exemplar project, or working implementation that an agent studies while changing a different target repository. The reference might be an internal service that already solved the same workflow, an older version of the product, a migration that handled one framework, or a small sample app that captures the architecture you want.

This pattern shows up when prose would underspecify the change. A written requirement can say “match the audit logging convention,” but the real convention may live across five handlers, a test fixture, a schema helper, and a deploy-time configuration file. A human would open the old service and look around. The agent needs permission and a safe path to do the same.

The reference isn’t a dependency. It isn’t vendored code. It isn’t a package the target imports. It is an example the agent reads, extracts from, and then leaves behind.

Problem

How do you help an agent transfer a working design from one codebase to another without letting it paste the old code into the new system?

The naive prompt is too thin: “follow the pattern from service A.” The agent may not know where service A is, which files matter, or which parts of the pattern are accidental. The opposite move, dumping a whole repository into context, is expensive and noisy. The agent reads too much and still may not know which facts are load-bearing.

The deeper failure is imitation without judgment. Agents are good mimics. If you hand them a working implementation without boundaries, they can duplicate names, comments, helper shapes, and hidden assumptions that do not belong in the target. You wanted transfer. You got copy-paste programming at scale.

Forces

• Examples carry tacit knowledge. File layout, error handling, tests, and naming rules are often clearer in code than in prose.
• Repositories are too large to paste whole. The reference has to be discoverable without filling the context window.
• Similarity is partial. The reference and target share a pattern, not every constraint.
• Copying is tempting. The fastest path for an agent is often to duplicate the visible example.
• Licensing and secrets still matter. A reference repository may contain code the target is not allowed to inherit.

Solution

Give the agent a separate reference repository, then constrain what it may extract from it. Treat the reference as bounded context: a source for conventions, workflow shape, schema examples, test patterns, and migration logic. Keep it physically outside the target worktree so the agent cannot accidentally stage reference files or import from them.

Start by naming the role of the reference. Don’t say “use this repo” and stop. Say what the agent should learn from it:

• the request/response shape,
• the test fixture pattern,
• the migration sequence,
• the authorization boundary,
• the error-handling convention,
• or the build/deploy wiring.

Then name what it must not do. It shouldn’t copy business-specific constants, customer data, credentials, proprietary comments, internal names that do not apply, or code whose license does not permit reuse. If a small snippet is allowed, say so explicitly and require attribution or review where your organization needs it.

The usual workflow is simple:

1. Clone or mount the reference outside the target checkout.
2. Ask the agent to inspect only the files that illustrate the pattern.
3. Have it summarize the transferable rule in plain language.
4. Make the target change from that rule, not from pasted code.
5. Validate against the target repository’s tests, types, and conventions.

This turns the reference into an input to judgment, not a source of unreviewed code. The target repository remains the source of truth. The reference helps the agent decide what good looks like, but the target’s tests and reviewers decide whether the new code belongs.

How It Plays Out

A platform team is migrating six internal services from one job framework to another. The first service has already been migrated and reviewed. For the second service, the developer clones the first service into /tmp/reference-job-migration and tells the agent: “Study how the reference changed job registration, retry policy, and tests. Do not copy service-specific names or constants. Summarize the migration rule, then apply the equivalent change here.” The agent reads three reference files, writes the target patch, and runs the target tests. Review focuses on whether the migration rule transferred, not whether the code came from the right neighborhood.

A team building a new admin UI wants it to match the accessibility and error-handling behavior of an older console. The reference app uses the same design system, but it has different routes and data types. The agent inspects the reference form components, learns how validation messages and focus recovery are wired, then implements the new form in the target app. It copies no JSX wholesale because the prompt named the transferable rule: behavior and conventions, not markup.

A weaker version fails in a familiar way. A developer points an agent at a sample repository and says, “do it like this.” The agent imports helper names that do not exist in the target, copies a permissive test fixture that bypasses auth, and preserves a stale comment from the sample. The patch looks coherent until review reveals that the example’s assumptions were never true for the target. The team tightens the prompt: inspect, extract, summarize, adapt, verify.

Consequences

Benefits. A Reference Repository gives the agent richer context than a prose spec can carry. It works well for migrations, product-line variants, service families, UI patterns, and generated-code cleanup where the important knowledge is distributed across several files. It also improves review: the agent can state the rule it extracted, and the reviewer can compare that rule against both repositories.

Liabilities. The reference can mislead. If it is stale, over-specialized, or built under different constraints, the agent may transfer the wrong thing. The workflow also adds setup cost: the reference has to be cloned, mounted, indexed, or otherwise made readable. Unless the prompt is explicit, the agent may treat imitation as permission to duplicate code.

Use this pattern when the reference teaches a real recurring shape. Skip it when the task only needs one small example from inside the target repository. When the reference is useful, make the boundary visible: what to learn, what to ignore, where the reference lives, and which target-side checks prove the adaptation worked.

Related Articles