Agent-Ready Repos for Coding Agents

Working solo, I wanted to make coding agents useful on a mature web application without lowering the bar for review. The product combined a Django backend, GraphQL API, Next.js frontend, generated client types, and deployment automation. I already understood the shape of the system. A coding agent entering the workspace for the first time did not.

The central risk was not syntax. It was plausible code in the wrong place.

An agent could make a page interactive by moving too much work into the browser. It could hand-write a GraphQL response type that matched the immediate UI but drifted from the schema. It could add an authorization check inside a resolver and miss the boundary-level permission contract that reviewers expected to see. Each decision might pass a narrow local check while weakening the architecture.

I treated that as a repository design problem. Instead of hoping every agent would infer the rules, I made the repository explain its operating contract.

_Hero image: blueprint-style repository map with CI, GraphQL, and agent checklist gates._

The project was a production-style monorepo with separate backend and frontend concerns, shared API contracts, and deployment gates. It needed to support human contributors and machine-assisted changes in the same workflow.

I did not want a special "agent path" that bypassed normal engineering judgment. I wanted a repository where a new coding session could understand the same boundaries a new engineer would learn during onboarding: where business logic belongs, how GraphQL types move through the stack, which UI surfaces may use browser-only behavior, how permissions are declared, and what must pass before a change is trusted.

That mattered because coding agents work from local context. If the nearest guidance does not describe the architecture, the agent fills the gap with a common pattern from somewhere else. In a small prototype that may be fine. In a governed product, it creates slow review cycles and subtle drift.

The repository had several rules that were easy for an agent to violate:

• Frontend route entries should stay server-first unless there is a clear reason to create a client boundary.
• GraphQL types in the frontend should come from generated output, not handwritten local interfaces.
• Backend GraphQL fields and mutations should declare permissions explicitly at the framework boundary.
• Admin behavior should stay inside the admin-oriented surface rather than leaking into shared paths.
• Public-facing IDs and backend-only IDs should stay on their side of the boundary.
• Generated artifacts should be updated by their own commands, not edited by hand.

These are not stylistic preferences. They protect data loading, authorization review, type safety, and deployment reliability. The challenge was making them visible enough that an agent could follow them before a human reviewer had to correct the same mistake.

I made the repository legible to agents through layered instructions, generated contracts, and CI.

At the root, I wrote a plain operating guide that named the workflow, safety rules, documentation expectations, verification commands, and architecture boundaries. The guide used testable language. "Prefer type safety" became a concrete rule: define GraphQL operations in the operation layer, run code generation after schema or operation changes, and import generated documents and operation-derived types.

Then I mirrored the relevant subset of those rules near the surfaces where agents would work. Backend guidance used Django and Strawberry terminology. Frontend guidance used Next.js terminology. The local guides did not compete with the root guide. They translated shared decisions into the vocabulary a contributor would see while editing.

That mirroring was important. A root document can describe the whole operating model, but an agent changing a feature page or resolver usually reads local context first. The local guide turns the general rule into an immediately usable instruction.

The strongest pattern was turning ambiguous choices into mechanical paths.

For GraphQL, the agent did not need to decide whether to invent a TypeScript interface. The path was fixed:

That workflow is slower than hand-writing a type once. It is much cheaper than letting every feature create a private version of the API schema. It also gives reviewers a simple drift signal: if the component uses fields outside the operation, the type system should complain.

For the frontend, the rule was similar. Route entries stayed server-first by default. Browser-only state, hooks, effects, and event handlers moved into colocated client components. This aligned with the Next.js model, where Server Components handle server rendering and data access by default, while the "use client" directive marks the browser-side boundary.

For authorization, backend GraphQL fields and mutations declared permission classes explicitly. Public endpoints needed an intentional explanation. Member-facing endpoints used authentication. Admin actions used named permission requirements tied to the access-control model.

The point was not that decorators or framework-level permissions are magic. The point was that authorization became searchable and reviewable at the boundary. An inline check buried inside implementation logic can still be correct, but it is harder for a coding agent or reviewer to audit consistently.

The main tradeoff was documentation duplication. The same architectural rule appeared at the root and again in app-local language. That duplication was deliberate, but it needed a maintenance rule: shared decisions start in the root guide, and local guides mirror only the rules that apply to that surface.

The second tradeoff was accepting more generated workflow steps. Code generation adds a command and can slow a small edit. It also prevents a common class of machine-authored shortcuts. In this system, generated GraphQL artifacts were treated as contracts, not convenient suggestions.

The third safeguard was CI. Backend changes triggered checks that covered dependency installation in frozen mode, Django validation, tests, production image construction, container startup, health polling, and an HTTP health check before deployment could proceed. The workflow used path filters and concurrency cancellation so it stayed focused, but it still asked whether the changed system could run in a production-shaped environment.

That mattered for agent-assisted development. A machine-authored change should not be trusted because it looks coherent in a diff. It should survive the same checks that catch integration failures for human-authored code.

The repository became easier for a first-time contributor to enter without renegotiating the operating model. The agent had fewer opportunities to make locally plausible but architecturally wrong edits. Reviewers had clearer rules to point to. CI carried more of the proof burden.

This writeup does not claim autonomous delivery metrics. The value was architectural: I created a narrower, more repeatable change path before asking agents to do more work.

• New UI work followed the server-first and client-boundary pattern.
• GraphQL changes flowed through schema-aware generated types.
• Permission requirements were visible where API behavior was exposed.
• Deployment checks treated machine-authored changes as untrusted until verified.

The same structure helps humans. Most review comments about placement, generated artifacts, authorization, and verification are really missing contract problems. Once the repository states the contract, every contributor starts from the same map.

This pattern fits teams that want coding agents to work inside an existing architecture rather than prototype around it. It is especially useful for monorepos, GraphQL applications, server-first frontend frameworks, permissioned products, and teams with deployment gates that already encode operational knowledge.

Start with one repeated review correction. Turn it into a root rule, mirror it near the code that needs it, and add a test, typecheck, codegen command, or CI gate that can catch violations. Then give a new agent a small feature slice and watch where it hesitates or improvises.

If your team is preparing a repository for coding agents, audit the boundaries that reviewers correct most often and turn them into agent-visible contracts before expanding automation.

• Workflow syntax for GitHub Actions
• Understanding GitHub Actions
• Getting Started: Server and Client Components
• Directives: use client
• How to create custom django-admin commands
• Strawberry Django integration