How to Make a Complex Repository Legible to AI Coding Agents: A World-Class AGENTS.md Playbook

Most teams think their AI coding problem is a model problem. They believe the key variable is whether they chose Codex, Claude, Gemini, or some future system with a larger context window and better benchmark numbers. That sounds reasonable until the agents touch a real production repository.

In practice, the decisive variable is usually not raw model quality. It is repository legibility. If the codebase is structurally ambiguous, instruction sources conflict, verification is vague, and ownership boundaries are hidden inside tribal memory, even very capable agents will drift, overreach, or make brittle changes.

This is why so many teams get disappointing results from AI-assisted development. They spend time tuning prompts while leaving the working environment fundamentally opaque. They hand the model a large codebase and hope competence will compensate for poor operational design. Sometimes it does, briefly. Usually it does not.

The stronger frame is managerial and architectural, not purely prompt-oriented: a world-class agent structure is an operating model for making a codebase understandable, routable, and safe. It tells an agent what the repository is, where the task belongs, what rules are global, what rules are local, what must be verified, and which risks are not negotiable.

That is what makes the WordSuit repository interesting. Its instruction system is not a collection of clever prompt files. It is a coherent production design for how multiple coding agents should behave inside a multilingual game monorepo with an admin platform, payments, content pipelines, Storybook contracts, release tooling, and region-specific business realities.

This article is a case study in that operating model. The goal is not to fetishize markdown files. The goal is to show how to make a complex repository legible to AI coding agents in a way that scales across tools, teams, and risk levels.

Why Most AI Agent Strategies Fail in Real Repositories

The first generation of AI coding advice was obsessed with prompting. That made sense when the main question was whether these tools could write code at all. The next generation of the problem is different. The question is not whether an agent can produce syntax. The question is whether it can behave safely and coherently inside a living software system.

A production repository is not a blank canvas. It contains hidden contracts, stale docs, implicit ownership rules, high-risk surfaces, generated artifacts, release constraints, and long-lived architecture decisions. When those signals are not made explicit, agents are forced to infer policy from incomplete evidence. That is where drift begins.

The predictable failure modes are operational, not magical: agents edit the wrong layer, duplicate an existing pattern, skip the right verification step, touch a risky subsystem without understanding the blast radius, or hand back changes that look fine locally but violate the actual contract of the repository.

• Context drift: The agent reads broad top-level docs but misses the tighter rule set that governs the exact directory it is changing.
• Wrong-file edits: Without explicit ownership and architecture notes, the agent changes a nearby component instead of the real source of truth.
• Unsafe simplification: High-risk workflows such as payments, admin mutations, or entitlement logic are “cleaned up” in ways that break invariants.
• Verification theater: A broad test command is mentioned somewhere, but the narrowest useful proof for the changed surface is never clearly prescribed.
• Tool fragmentation: Different agent files diverge over time, so Codex, Claude, and Gemini receive slightly different operational truth.

None of these problems are solved by telling the model to “be careful.” They are solved by designing the repository so the right context appears at the right depth, the right owner is obvious, and the right verification path is specific enough to execute.

Why WordSuit Is a Meaningful Case Study

WordSuit is exactly the kind of repository that exposes whether an agent structure is real or decorative. It is not a toy frontend, a single-service API, or a staged demo designed to make AI assistance look easy. It is a multi-surface product system with enough moving parts that sloppy repository guidance would become expensive quickly.

At the center is a player-facing game client that spans web, iOS, and Android, supports RTL and multilingual behavior, and uses Storybook as part of the design and handoff contract. Alongside that sits a separate admin application with its own architecture, data-fetching patterns, route wrappers, and client-side access conventions. Around both are payments and monetization flows, content and image pipelines, release tooling, and region-specific launch requirements.

• A game client surface: runtime orchestration, shared design system primitives, state slices, screen controllers, stories, and browser flows.
• A separate admin surface: an internal operating console for support, content, monetization, localization, and system workflows.
• High-risk commerce paths: payments, purchase verification, entitlements, queueing, and server-owned truth for grants and currency.
• Operational pipelines: content validation, build tooling, asset generation, and release processes that can silently affect multiple surfaces.
• Market-specific constraints: Iran-market requirements, localization realities, and regional platform behavior that cannot be treated as optional edge cases.

That complexity matters because it justifies the system. WordSuit does not use AGENTS.md because it is fashionable. It uses a layered instruction model because the repository is genuinely large enough, risky enough, and cross-functional enough that agents need routing, scoping, and contracts to behave well.

Just as important, the system is unusually coherent. The root AGENTS.md acts as the canonical source of truth. CLAUDE.md and GEMINI.md stay thin and compatibility-focused. Nested guides exist where the codebase actually changes shape. Specialist briefs map to concrete file ownership and risk boundaries. And operational docs are treated as live contracts rather than aspirational documentation.

Principle 1: Create One Canonical Instruction Source

The most important design choice is also the simplest: choose one canonical repository instruction format and make everything else point toward it. In WordSuit, that role belongs to AGENTS.md. The root file is not a manifesto. It is an operational control surface.

That matters because instruction sprawl is one of the fastest ways to degrade agent reliability. When different files become competing sources of truth, the team loses the ability to reason about what the agent was actually told. A canonical root document solves this by concentrating the durable repository contract in one place.

A strong root AGENTS.md should answer six questions quickly: what this repository is, which surfaces matter, which docs must be read first, which commands are relevant, which risks are non-negotiable, and how work should be routed.

• Project model: Describe the products inside the repo, not just the language stack. Agents need to know whether they are looking at one app, a monorepo, or multiple first-class products.
• Read-first contract: Name the docs that define architecture, testing, feature shape, design system behavior, or launch constraints.
• Main areas: Map the major directories to the systems they own so the agent can locate the likely source of truth.
• Exact commands: Concrete build, test, Storybook, admin, validation, and governance commands are much more valuable than vague reminders to verify.
• High-risk constraints: State where the repository cannot tolerate improvisation, such as server-owned economy logic, privileged admin mutations, or moderation-sensitive systems.
• Team model: Explain how ownership should be chosen, when delegation makes sense, and why file boundaries matter more than persona preference.

WordSuit’s root file does all of this with unusual discipline. It names the two first-class products inside the repo. It points agents to architecture, design system, testing, and feature-addition docs. It enumerates commands for game, admin, validation, and governance work. It states non-negotiables for payments, admin privilege, gameplay adjacency, and social systems. And it explains how to route tasks through a specialist roster without turning the root guide into biography theater.

What does not belong in the root guide

• Long persona narratives: Agents do not need fictional backstories. They need ownership boundaries, expectations, and handoff rules.
• Area-specific edge cases: If a rule only matters in payments or gameplay, it should live near that surface rather than bloating the root file.
• Generic style platitudes: “Write clean code” is not a repository instruction. “Use the existing shared query hooks in admin/src/lib/queries” is.
• Contradictory leftovers: A canonical file loses its value when stale rules remain after architecture or process changes.

The root file should feel like a routing table and safety contract, not a prompt dump. Its job is to orient the agent, constrain the most dangerous mistakes, and point the work toward the right local instructions.

Principle 2: Keep CLAUDE.md and GEMINI.md Thin

Cross-tool compatibility is not a side concern anymore. Many teams use more than one coding agent across the same repository. The wrong way to handle that reality is to let each tool accumulate its own evolving version of the project contract.

WordSuit does the opposite. CLAUDE.md is a compatibility shim that imports or points to AGENTS.md, adds only the small amount of Claude-specific guidance that matters, and explicitly tells Claude to route work through the same ownership structure. GEMINI.md does the same job from the Gemini side. The result is that the shared operating model stays centralized while tool-specific notes remain lightweight.

This is a subtle but powerful best practice: use tool-specific files for compatibility, not for truth. The minute CLAUDE.md and GEMINI.md become parallel operating manuals, the repository begins teaching different agents different habits.

• Keep the shim short: Point to the canonical root file first, then add only the compatibility notes that are genuinely tool-specific.
• Preserve the same routing model: If AGENTS.md says tasks are routed by file ownership and nearest scope, your shim should reinforce that rather than invent a different decision system.
• Avoid duplicate long-form instructions: Every duplicated paragraph becomes a future drift vector.
• Use tool files to preserve handoff fidelity: WordSuit’s Claude shim explicitly preserves modified files, verification run, open decisions, and approved constraints during summarization.

The broader lesson is organizational. Multi-agent repos do not become safer by multiplying instruction volume. They become safer when the shared truth is unified and the compatibility layers remain honest about their narrow purpose.

Principle 3: Let Context Follow File Ownership

The next design move is where many repositories either become elegant or collapse into noise: localize the sharper rules so they appear only when the agent is close to the code that needs them. WordSuit does this with nested AGENTS.md files in places such as src, gameplay, payments, admin, and tools.

This is not duplication of the root guide. It is scoped refinement. The root file says what the repo is and how work should be routed. The nested guides explain what changes inside that surface should preserve, what patterns already exist there, and how verification should narrow once the area is known.

• The client guide under src/: reinforces screen orchestration, store boundaries, Storybook expectations, localization, RTL, shared patterns, and doc updates for client contract changes.
• The gameplay guide: sharpens expectations around board runtime, controller/store patterns, performance, onboarding adjacency, and cross-surface gameplay implications.
• The payments guide: states that server truth owns entitlements and grants, emphasizes idempotency and reconnect safety, and reminds the agent to audit adjacent admin and callback behavior.
• The admin guide: frames the admin app as an internal operating system, pushes agents toward shared query hooks and wrappers, and keeps tests behavior-focused.
• The tooling guide: centers determinism, idempotency, and explicit source-of-truth handling for scripts and generated outputs.

The governing idea is simple: broad context should load everywhere, but sharp rules should load only where they are relevant. That keeps the startup context lean while still making local behavior precise.

The real design rule for nested guides

1. Create a nested guide when the local surface has distinct failure modes: payments, admin, or asset tooling often justify sharper local instructions because the risks and patterns truly differ.
2. Keep the local guide about preservation, not repetition: its job is to explain what must remain true inside that slice, not to restate the entire repository manual.
3. Tie the guide to real file boundaries: the closer the guide sits to the owned code, the easier it is for agents to inherit the right context automatically.
4. Specify local verification: a scoped guide should make the narrowest useful proof obvious for that domain.
5. Let specificity win: if the root and the local guide differ, the more local operational reality should govern the files in that area.

This pattern is one reason WordSuit feels mature. The instruction system is not centralized to the point of vagueness, and it is not fragmented to the point of inconsistency. It is layered.

Principle 4: Route by System Ownership, Not Agent Theater

Specialist layers are often where agent setups become gimmicky. Teams create elaborate personas with clever names, but the personas are disconnected from repository reality. The result is superficial theater: a “payments expert” who owns no explicit files, a “frontend stylist” whose remit overlaps with three others, or a “reviewer” with no verification contract.

WordSuit’s specialist layer is stronger because it stays operational. The roster names owners such as Mina for game runtime, Leyla for design system and Storybook, Parisa for the admin platform, Arash for backend contracts and commerce, and Nima for Iran-market realities. More important than the names, each specialist maps to concrete repo boundaries, expected behaviors, and handoff style.

That is the right abstraction. A specialist is not a personality. It is a bounded working agreement about which files, contracts, and risks a given owner is expected to understand.

• Use when: State the kinds of changes that justify routing to that owner.
• Owns: List the actual files or modules under that owner’s primary responsibility.
• Expects: Capture the invariants the owner protects, such as idempotent grants, shared query usage, or server/client boundaries.
• Handoff style: Tell the owner what a useful result must contain, including changed contracts, verification commands, or untested edge cases.

Notice what this model accomplishes. It lowers routing ambiguity, reduces overlap, and makes delegation accountable. It also gives the root guide a cleaner job: choose the right owner, preserve the scope, and require proof.

This is especially important in multi-agent environments. The team model in WordSuit explicitly warns against swarming small tasks with overlapping owners and prefers one primary owner per area unless write scopes are disjoint or a read-only analysis can help another owner finish faster. That is good operational design, not prompt ornament.

Principle 5: Treat Docs as Operational Contracts

One of the most overlooked features of a strong agent structure is what sits outside the agent files themselves. In WordSuit, core docs such as architecture, testing, and feature-shape guides are not decorative background reading. They are live contracts that explain how work is supposed to be added, tested, and handed over.

That difference is huge. If your docs are stale essays, agents will ignore them or, worse, trust them when they should not. If your docs are operational contracts, they become part of the routing and verification system. WordSuit’s docs do this well. The architecture doc explains how the system is organized. The feature guide tells contributors how to choose the right state home and what every feature should ship with. The testing contract says what belongs in Vitest, what belongs in Playwright, and what Storybook is responsible for.

• Architecture contracts: Explain where orchestration begins, where persistent state lives, which surfaces are shared, and how the major systems relate.
• Feature-shape contracts: Define the standard layout of a new feature, the expected controller/component split, and the required handoff package.
• Testing contracts: Make it clear which behavior belongs in fast unit-style tests, which needs browser coverage, and which belongs in Storybook as the design system contract.
• Design and admin reference contracts: Keep shared presentation rules and internal workspace conventions legible so agents do not invent parallel UI architecture.

If you want agents to preserve system behavior, you have to write down what the system considers “done.” That is what operational docs provide. They turn future judgment calls into present repository knowledge.

This is also where Storybook becomes strategically important. WordSuit treats Storybook as part of the product contract rather than optional polish. That matters because reusable UI and screen states need a visible home where agents and humans can both understand what a shared surface is supposed to look like. If you leave that implicit, agents will happily make local markup changes that erode the shared system over time.

Principle 6: Put Verification Inside the Instruction System

A repository becomes dramatically safer the moment verification stops being tribal knowledge. Many teams still treat testing as an external step that a careful engineer is supposed to infer after making changes. In an agentic workflow, that is too loose. The repository itself needs to say what proof belongs to which change.

WordSuit does this at multiple levels. The root guide tells agents to start with the narrowest useful check. It then gives examples for targeted game tests, admin typechecks, Storybook builds, end-to-end flows, content validation, docs consistency, and governance checks. The nested guides sharpen those expectations further for their local surfaces.

This is a very important maturity signal: verification is not only a CI concern. It is part of the prompt architecture of the repository. When you make the proof path explicit, you reduce two common failures at once: under-testing and over-testing.

• For focused client logic: run the narrowest relevant Vitest path first.
• For shared UI contract changes: run Storybook builds because the change is part of a reusable surface, not only a local screen.
• For admin shell or shared admin behavior: typecheck the admin app and run the most focused relevant tests.
• For flows that cross screens, storage, or browser boundaries: use Playwright instead of pretending a local unit test is enough.
• For content or tooling changes: use validation and governance commands that check the integrity of derived systems and docs.

The testing contract amplifies this further by defining where behavior belongs. Pure logic and selectors go in Vitest. Real user journeys go in Playwright. Shared surfaces and meaningful states belong in Storybook. That is not just a testing preference. It is a way of helping agents choose the right proof without rethinking the whole verification philosophy each time.

What a good verification section sounds like

1. Name the narrowest command first: do not make “run everything” the default when the change is local.
2. Tie proof to the changed surface: admin route changes need admin checks; content pipeline changes need validation; shared component changes need story coverage.
3. Call out adjacent audits when necessary: payments work often needs a callback or admin surface audit, not just a local adapter test.
4. Make failure meaningful: governance checks should fail when docs drift, dead exports linger, or a contract surface stops matching reality.

A world-class agent structure does not merely say “please verify.” It teaches the repository to state what proof counts.

Principle 7: Encode Real Risk Surfaces and Market Constraints

The most impressive part of WordSuit’s instruction system may be that it refuses to pretend all code is equally safe. The guides explicitly name the domains where shortcuts are unacceptable. Payments and entitlements are server-owned truth. Admin routes that mutate privileged data should use shared wrappers. Gameplay changes can affect onboarding, rewards, retention loops, and live events. Social systems have both player-facing and moderation implications. Iran-market requirements are product reality, not an afterthought.

This matters because many AI coding failures come from flattening risk. When an agent sees the whole repo as a uniform editing surface, it optimizes for local neatness instead of system correctness. High-risk instructions prevent that by telling the agent where it must preserve invariants rather than improvise.

• Server-owned truth in commerce: never allow client-only granting paths for currency, items, or entitlements.
• Shared wrappers in privileged surfaces: admin mutation routes should inherit auth, capability, and audit expectations instead of inventing ad hoc guards.
• Adjacency awareness in gameplay: a “small” runtime change may affect onboarding, offers, economy, or live events.
• Trust-and-safety awareness in social features: teams, chat, moderation, and leaderboard systems span player experience and internal operations.
• Regional product realism: launch profile and market-specific behavior should be treated as first-class engineering constraints.

This is one of the clearest differences between a toy agent setup and a production one. Toy setups talk about coding style. Production setups talk about failure modes, authority boundaries, and business realities.

If your repository contains pricing logic, compliance requirements, regulated workflows, moderation surfaces, or market-specific launch behavior, those conditions must appear in the instruction system. Agents cannot protect what the repository never names.

Principle 8: Add Governance That Catches Drift

Even good agent structures decay unless the repository enforces them. This is where WordSuit’s governance scripts are especially notable. The project does not rely only on humans to remember whether the docs still match the codebase. It includes checks that verify the continued integrity of key contract assumptions.

For example, the docs-consistency flow checks for required docs and validates that important documents reference one another. The governance check catches dead-code cleanup issues and unused exported symbols in critical client surfaces. The result is that the repository can push back when the written operating model drifts away from reality.

• Fail when required docs disappear: a missing architecture, testing, or feature contract should not be silently tolerated.
• Fail when counts and facts go stale: if the architecture doc says the store has one shape and the code now has another, the repo should tell you.
• Fail on hygiene regressions in contract surfaces: governance is strongest when it protects the places agents rely on for routing and clarity.
• Protect handoff quality: a drift check is not bureaucracy when it preserves the accuracy of the instructions the next agent will read.

This is where many teams stop too early. They write good instructions once, then assume the job is done. In reality, a world-class agent structure needs the same thing any operational system needs: feedback loops that keep the contract current.

The practical outcome is important. Governance reduces the probability that agents will trust stale docs, preserve dead patterns, or copy assumptions that no longer describe the codebase.

A Step-by-Step Blueprint for Building a World-Class Agent Structure

If you wanted to build this style of repository from scratch, the right sequence is not mysterious. It is simply more disciplined than most teams expect. The key is to build the system in dependency order so later layers sit on a clear foundation.

1. Map the repository before you write instructions: list the products, major directories, risk surfaces, generated artifacts, and ownership boundaries. Without that inventory, your guide will collapse into generalities.
2. Write one canonical root file: cover project shape, read-first docs, main commands, high-risk constraints, and the routing model. Keep it concrete and durable.
3. Add thin compatibility shims for other tools: use CLAUDE.md, GEMINI.md, or equivalent files only to point back to the canonical truth and add the minimum tool-specific context.
4. Create nested guides only where the local system truly changes: payments, admin, gameplay runtime, data tooling, or other high-complexity areas often justify their own scoped instructions.
5. Turn docs into explicit operational contracts: architecture, testing, design system, feature-addition, and release docs should define how work is supposed to happen, not merely describe it.
6. Define specialists around file ownership and risk, not charisma: make each owner’s files, expectations, and handoff shape explicit.
7. Attach verification to surfaces: teach the repository which proof belongs to which kind of change so agents can verify correctly without guessing.
8. Add governance that keeps the system honest: stale docs, dead exports, and broken contract assumptions should fail fast before they become invisible agent debt.

Notice what this blueprint does not include near the beginning: custom agent personalities, giant prompt templates, or a sprawling directory of speculative specialist roles. Those are downstream optimizations. They only work well after the repository has been made legible.

What good looks like after ninety days

• New tasks route faster: agents and humans find the likely source of truth with less wandering and fewer wrong-file edits.
• High-risk changes become safer: payments, admin mutations, and launch-sensitive flows carry clearer local rules and proof requirements.
• Onboarding improves: new contributors can become productive without relying on one person’s memory of how the repo “really works.”
• Docs stop feeling ornamental: because they are referenced in routing and governance, they stay closer to operational reality.
• Agent output becomes more predictable: not because the model got smarter overnight, but because the environment became easier to reason about.

That is the real promise of a world-class agent structure. It improves the repository for humans and machines at the same time.

What Most Teams Get Wrong

• They treat AGENTS.md like a marketing page: a repository guide should not read like positioning copy about “AI-powered development excellence.”
• They duplicate instructions across tools: parallel truth sources guarantee drift.
• They centralize everything: one enormous root file is almost always a sign that the local surfaces are under-described.
• They over-specialize too early: specialist agents without clear file ownership produce more ambiguity, not less.
• They ignore verification design: an agent structure without proof rules is an instruction system without a safety net.
• They leave risk implicit: if the repo never names the dangerous surfaces, agents will optimize for convenience.
• They never add governance: without drift checks, even a good system becomes stale and eventually misleading.

The recurring pattern behind all these mistakes is the same: teams over-invest in the appearance of agent sophistication and under-invest in the operating clarity of the repository.

Questions Teams Will Ask

What should go in AGENTS.md?

Put the repository contract in it: project shape, read-first docs, key commands, high-risk constraints, routing rules, and a map of area guides. Do not use it as a dumping ground for every local edge case. The root file should orient the work and point the agent toward the sharper local rules.

Do I need CLAUDE.md if I already have AGENTS.md?

If you use Claude Code, yes, but keep it thin. Claude officially reads CLAUDE.md, while Codex officially supports AGENTS.md. The best pattern is to keep AGENTS.md canonical and let CLAUDE.md import or point to it, then add only the small amount of Claude-specific context you truly need.

When should I create nested AGENTS.md files?

Create them when a directory has distinct patterns, risks, or verification logic that the root guide cannot explain without becoming bloated. Payments, gameplay runtime, admin platforms, tooling pipelines, and regulated or high-risk subsystems are common examples.

How do I prevent conflicting instructions between files?

Use a clear hierarchy and review it periodically. Keep the root file durable and broad. Keep local files narrow and surface-specific. Remove duplicate rules from shims. Add governance where possible. And when two instructions do conflict, let the file closest to the governed code win for that surface.

How should I organize specialists or subagents?

Organize them by ownership boundaries, not by vague skill adjectives. A strong specialist brief says when to use that owner, which files they own, what invariants they protect, and what a useful handoff must contain. If you cannot name the files and risks, the specialist probably is not well defined yet.

How do I handle payments, admin tools, and other high-risk domains?

Name them directly in the instruction system. Give them scoped guides. State non-negotiables such as server-owned truth, privilege wrappers, moderation implications, or compliance requirements. Then attach the exact verification and adjacent audits those surfaces require.

How do I know the system is actually working?

Look for practical signals: fewer wrong-file edits, faster routing, better handoff quality, more reliable verification, less repeated clarification in chat, and fewer cases where a reviewer has to restate a repository rule the agent should already know. Over time, onboarding speed and safer high-risk changes are usually the clearest qualitative indicators.

Will this structure work across Codex, Claude, and Gemini?

Yes, if you separate canonical truth from tool compatibility. Keep the shared operating model in one durable place, then let each tool-specific file point back to it. That is exactly why WordSuit’s combination of AGENTS.md, thin CLAUDE.md and GEMINI.md shims, and scoped local guides is so strong.

The Strategic Point

The strongest repositories will not be the ones with the cleverest prompts. They will be the ones that make architecture, ownership, proof, and risk legible enough that capable agents can behave like responsible teammates instead of talented guessers.

That is why this is a management and systems design problem before it is a prompting problem. A world-class agent structure aligns repository truth, local context, ownership routing, contract docs, and verification so that intelligence has something stable to operate on.

WordSuit is compelling not because it has markdown files with agent names in them. It is compelling because the whole repository behaves like an operating system for safe AI-assisted development. There is a canonical source of truth. Context follows ownership. Specialists map to real boundaries. Docs define contracts. Verification is explicit. Market constraints are first-class. Governance keeps the system honest.

That is the pattern worth copying. Not the aesthetics of AGENTS.md. The operating model behind it.