Make the Repository Teach the Agent

Every file an agent reads influences what it predicts next. A coherent repository teaches one local answer for each recurring concept: one authoritative owner, one canonical pattern, and mechanically checked projections. The agent can infer what good looks like from an example, reuse that inference elsewhere, and spend less attention deciding which local idiom is current.

Source code has two roles in this loop. It is implementation output downstream of specifications, boundaries, and guardrails. It is also input to the next trajectory. Stop Treating Code as the Artifact describes the first relationship; code as prompts for future prompts names the second. Durable contracts shape today’s code, and today’s code becomes tomorrow’s example.

Code is part of the prompt

An agent reads source to discover business logic, adapters, state-management choices, test structure, and the way a team expresses familiar operations. In the Aakash Gupta interview, Ryan describes this directly: “the code in the repository is prompts.” Uniform structure lets context learned in one file transfer across the codebase. The agent can “more effectively cargo cult” the way a human newcomer searches for a precedent, copies it, and adapts it.

A concrete antecedent appears years before Ryan’s 2026 harness-engineering essay. In I Wrote 4,000 Lines of Code with ChatGPT in a Weekend, ChatGPT continued to mix unrelated directives when Ryan fed a combined lib.rs implementation of Ruby’s String#unpack into one prompt. He split the crate into small modules with highly regular structure and documentation. Those repeated examples let the model implement additional state-machine operations correctly on its first attempt. The same article imagined agents grounded in the local codebase, commit history, issues, and pull requests. Ryan later revisited the article and said that although the models had improved, the collaboration loop of context, constraints, iteration, and feedback felt the same.

The model already contains many plausible ways to build software. The repository prunes that latent space by selecting the team’s intended choices.

Make nonfunctional requirements recoverable

Nonfunctional requirements are quality attributes, constraints, and acceptance bars that help determine whether an outcome belongs in a system: compatibility, maintainability, accessibility, security, reliability, performance, and polish. Teams make often-unstated choices about how to interpret, prioritize, trade off, and satisfy them, including risk tolerance, acceptable shortcuts, and the organization's definition of done. They have historically carried what doing a good job means through organizational structure, social norms, hiring, onboarding, and repeated exposure to coworkers who already knew the local answer.

A general model has seen many internally coherent answers to each of these choices. An expert persona leaves the choice unresolved because expert developers can make different, locally valid decisions about the same nonfunctional requirements. A blank repository creates the same ambiguity for SDK design: https://github.com/lopopolo/harness-engineering/blob/226c8d35fb6ea3ed55467753dba6dea2b5fd5778/docs/domain-modeling/without/README.md local precedent, nothing prunes the many plausible language, interface, compatibility, and long-term-maintenance choices. The model already knows many good options; the organization must select the ones that belong in this system.

Ryan adopted a systems-level framing from the [un]prompted conference in which harness engineering gets the whole universe of nonfunctional requirements into code. The two-part context economy places those requirements where they can be retrieved into context and reduces how much context the worker needs to produce high-quality work. Making them legible and retrievable becomes a net-new function of the team, with relevant requirements delivered just in time. An early scheduler failure followed from unspecified requirements for scalable, maintainable code; writing and injecting that missing specification is the harness's purpose.

The appropriate owner depends on the requirement's maturity and scope. A blessed implementation carries dense choices about structure and taste. A disliked result can be translated into its governing nonfunctional requirement. The team can document its chosen interpretation, apply contextual judgment through reviewer policy, and enforce settled invariants with tests or lints. Architecture, types, APIs, tools, and merge gates can represent and enforce stable requirements. Examples and reviewer policy can express qualitative judgment. Versioned guidance and runbooks record changing operational requirements and the current choices for satisfying them. Each representation should point back to one semantic owner for the requirement and its local decisions, so the agent can retrieve the relevant choice without loading the entire quality bar into every prompt.

Consistency compresses context

Ryan’s instruction to make all the code the same covers structure, patterns, language, build, documentation, and skills. Consistency lowers context and instruction demand. One observability stack, command shape, and package pattern lets the agent transfer context across the repository. Each variation that expresses the same concept forces another round of discovery: which example is canonical, whether a migration is complete, and which surrounding rules must also enter attention.

The AI Native DevCon transcript develops the attention mechanism with a concrete contrast. One observability pattern lets context from one part of the repository apply elsewhere; six stacks require the agent to research which one belongs at each call site. The AI Engineer Europe talk connects that reduced attention demand to completed migrations: agents can standardize the whole repository instead of leaving two eras of code in active use.

This is productive cargo-culting. An accepted implementation embodies thousands of small decisions that would be difficult to specify. Reusing its good parts gives a new rollout a nucleation point. Canonical repetition reduces the competing instructions, migration history, and compatibility paths the agent must inspect and hold in attention. Humans receive the same benefit: the repository makes its preferred continuation obvious to a new contributor.

Examples can propagate defects as readily as they propagate good judgment. The OpenAI harness-engineering essay observes that Codex reproduces uneven or suboptimal local patterns. A half-finished migration therefore creates competing prompts, and a bad helper can spread through every package that needs similar behavior. Golden principles, shared primitives, and recurring cleanup make the example set trustworthy again.

One concept, one authoritative owner

Before creating a parser, manifest type, version constant, state representation, fixture builder, policy check, or command, find the existing owner of the concept. Extend that capability seam when necessary.

One concept can have several physical renderings while retaining one semantic owner. A version may appear in source, generated documentation, a pull request, and automation state. Generate those projections from the owner, parse them from the canonical source, or check their relationship mechanically. Stable policy—exact pinning, a cooling-off interval, or an approved dependency class—remains code even as the current version changes in a manifest.

The repository owns desired configuration and durable policy. A running service, external control plane, hardware device, or deployment system owns its live state. Tools and checks reconcile those views without copying volatile state into a second supposed source of truth.

Warning signs include:

• a second parser for a language the repository already models;
• exact tool versions copied into policy code and fixtures;
• JSON or YAML assembled from string fragments;
• commands that reimplement domain behavior;
• untyped external data flowing into internal code; and
• several defensive checks protecting the same invariant.

Each duplicate owner creates another locally plausible continuation. An agent can follow every nearby precedent faithfully and still make the repository less coherent.

Finish migrations and install the ratchet

Consistency becomes more attainable when implementation is abundant. The Production Function Changed describes enabling ESLint's no-await-in-loop rule, repairing roughly 600 violations, and adding exhaustive test coverage in one pull request. Completing the migration in one coherent change removed contradictory precedent.

Completing the migration matters as much as choosing the target. Leaving old and new patterns side by side makes both available as prompt material. A finished migration removes that ambiguity, and a ratchet turns the new pattern into durable context. Agents also make upkeep cheaper: recurring gardening can find deviations, migrate them, and feed accepted corrections back into the repository before drift compounds.

A brownfield migration can deliberately prevent the old system from supplying the easiest continuation. Ryan has described an exploratory pattern of decomposing Python packages into smaller Rust packages behind PyO3 boundaries. The language and package boundary blocks casual dependencies on the existing ball of mud, while the Rust type system makes more of the target structure enforceable. Ryan presents the brownfield pattern as exploratory evidence about deliberate discontinuity; its value depends on the migration and the boundary it creates.

The hyperbo.la build case applies this move across a real repository: one toolchain and workspace graph, explicit package owners, semantic URL and frontmatter types, one rendering path, custom structural checks, and a one-sweep content migration. The repository becomes easier for the next agent to infer because the migration leaves no competing build or content path.

Parse uncertainty at the boundary

Accept uncertainty where data enters from a real external system. Parse it once into a trusted domain type, then let internal code rely on canonical states. Repeated record checks, normalization in every function, readiness checks in every event handler, and several stale-response guards usually mean no boundary owns validity.

Parse, don’t validate supplies the earlier type-design principle: parsing should preserve the evidence that a value satisfies the program’s needs. Ryan’s later harness work turns that principle into model-facing structure with branded identifiers, unit-bearing duration types, boundary-only decoding, and AST-aware lints for escape hatches the type system cannot prevent.

Encode ownership mechanically

Commands adapt arguments, environment, and exit behavior to the typed API that owns the operation. Architecture documents name package ownership and dependency direction. Structural tests enforce those relationships. Custom diagnostics explain the governing model and point the agent toward the proper repair, so a failed check supplies the missing context at the moment it is useful.

Architecture also bounds the context needed for a change. When a subsystem has a documented, reliable interface, the agent can reason from that contract and leave most implementation detail outside active attention. Capability-shaped boundaries make the same move executable: callers depend on the capability, while the implementation behind it can change without making every consumer load the migration into context.

Fixtures should express domain conditions through typed builders and serialize only at the format boundary. Generated artifacts should have one explicit source-to-output model. Their proof may compare bytes, semantics, or a complete corpus depending on the contract; the proof thesis develops that distinction.

The architecture cases develop these mechanisms in Ryan’s homelab, Artichoke, and rand_mt.

Preserve meaningful variation

Consistency applies when several places express the same recurring concept. Prototype and production work have different nonfunctional requirements, so their patterns need not match. They are not competing answers inside one operating contract. Canonicality is local to the relevant domain and scope. Within that scope, one semantic owner can deliberately produce several representations.

Repository-specific rules should earn their carrying cost through a concrete failure class or a valuable invariant. Broad architecture establishes stable seams; local implementation remains open to the agent’s reasoning. This keeps the example set coherent without turning every design choice into centralized policy.

The result is a reinforcing loop. Canonical examples help agents make aligned changes with less context. Agents make complete migrations and continuous gardening affordable. Those changes improve the examples available to every future trajectory.