A clearer repository map for coding agents

An agent can make a wrong change even when it understands the prompt. The repository may have two plausible places for the same feature, old and new patterns side by side, or instructions that describe a layout the code no longer uses. The agent has to choose before it can edit.

You cannot make every repository obvious to every tool. Make the important decisions visible: which file owns a concern, which conventions apply, where to begin, and how to check a change. That gives an agent a map and a reviewer a clear path to inspect.

Start with a real change

Choose a representative task, such as adding a settings page or changing how a project is saved. Trace the task from the user interface through routing, data access, validation, and persistence. Record the files a contributor must understand and the decisions that currently require guesswork.

Do this before reorganizing folders. A tidy tree can still hide overlapping responsibilities.

For the example settings change, the map might identify the route that renders the page, the settings component, the query or mutation that loads and saves preferences, the schema that validates them, and the test or check that covers the change. The exact paths depend on the application. The goal is to explain the paths that exist, not to impose a sample layout that does not fit.

Give each concern a clear owner

When two directories appear to own the same kind of code, a contributor has to compare both before deciding where a new file belongs. That ambiguity is costly for people and tools alike. Make ownership explicit, then use the same rule in code review and instructions.

For example, a project might keep route definitions in routes/, shared interface elements in components/, and database operations in db/. Another app may use framework conventions such as app/ for routes. Either can work. What matters is that the repository describes the actual convention and does not quietly encourage a second route system beside it.

Write down the boundary for folders that are easy to confuse. If lib/ contains business logic, say that UI components belong elsewhere. If features/ owns feature-specific components and hooks, state whether shared components live in a separate directory. The point is not to make every folder narrowly pure; it is to help the next contributor predict where a change belongs.

Prefer names that answer a question

Names should help a reader decide whether a file is relevant before opening it. useWorkspaceMembers.ts conveys more than useData.ts; settings-schema.ts is more specific than schema.ts when both names appear across a project.

Index files and barrel exports are sometimes useful, but avoid making them the only map of a large feature. Provide a clear module or route entry point and make its dependencies easy to follow.

Use established framework conventions where they fit, but document deliberate differences and show a representative file.

Make instructions match the repository

Keep repository guidance short enough to act on and specific enough to resolve a real choice. A useful instruction file can point to the framework entry point, list the canonical location for a new screen, identify the data access pattern, and state the required checks. Link to deeper documentation rather than repeating a second architecture manual at the root.

The SaaS Dashboard Kit documents its conventions in CLAUDE.md, including how to add hooks, routes, and screens. Its OpenCode guide says the kit has a root AGENTS.md that OpenCode reads, alongside CLAUDE.md and .cursorrules for other tools. The three delivered kits—SaaS Dashboard, Fitness, and Arcade—ship those instruction files and task prompts; Booking and Marketplace are not in that delivered set. Kit contents can change, so check the relevant kit documentation before relying on a file being present.

If multiple instruction files are needed for different tools, make them agree on repository facts. Avoid maintaining separate lists of paths that drift apart. Keep shared rules in one authoritative guide where possible, then use tool-specific files to point to it or add only the syntax that a tool requires.

Show the shortest useful path

Document a common change as a sequence of real files: start at the route or feature entry point, follow it to the data layer, then identify the relevant validation and check. Link directly to the files or to a small example, rather than saying only “follow the existing pattern.” When a pattern has exceptions, name them.

For a settings update, the guide might say: edit the settings route, use the existing preferences hook, validate through the shared settings schema, and run the focused check. Include only steps true for the repository; if no focused check exists, name the broader one instead of inventing a script.

Small task prompts can make repeated work easier to describe, but they are examples, not proof that an implementation is correct. A prompt should identify the intended files, preserve existing conventions, and tell the agent how to report what it changed. Review the result as code: inspect the diff, confirm that the change fits the architecture, and run the checks that apply.

Keep the map current

Repository guidance becomes a liability when it points at deleted files or describes an old migration as current. When a feature moves, update its instructions and examples in the same change. Remove abandoned implementations when they no longer serve a supported use, or label them clearly when they must remain for compatibility.

Do not delete code just to make a tree look simpler. Check whether it is imported, called by a route, used in a migration path, or required by a supported integration. Then record the ownership decision. A concise map is useful only when its paths lead to working code.

When a repository has competing patterns, choose deliberately for the next change. Migrate old code when there is a reason and a safe scope; otherwise document which pattern new work should follow and what remains legacy. This lets an agent avoid extending an obsolete path without pretending that the cleanup is already complete.

Check the result, not the promise

Test the map with a bounded task in a clean checkout or branch. Ask a coding agent to make one representative change, then review where it looked, what it edited, and whether it followed the written conventions. This checks the instructions and repository shape; it does not guarantee another prompt or model will behave the same way.

The OpenCode guide on the SaaS Dashboard describes a single test performed on 13 October 2026. It reports: “On 13 October 2026, the kit's own type-check passes in a fresh install. Our test change added no type errors.” The same guide says the page was not run in an app and that the check did not cover lint or the kit's tests. Treat that as a dated, limited report about that test—not a general result for all coding agents, projects, or future versions.

For your repository, record the tool and version, task, files changed, and checks run. If the agent chose an unexpected path, improve the map or fix the code conflict. If a reviewer could not trace a sound change, improve the explanation. Repeat when the repository or guidance changes enough to justify another check.

A practical review list

Before asking a coding agent to work in a repository, check the following:

• Is there one documented owner for the area the task changes?
• Can someone find the route, feature entry point, and data access path by following named files?
• Do project instructions match the current code and point to useful examples?
• Do tool-specific instruction files agree on paths and conventions?
• Are legacy paths clearly labeled, safely removed, or explicitly chosen for new work?
• Does the requested check exist, and does it match the kind of change being made?
• Can a reviewer understand the diff without relying on an unverified claim about speed or accuracy?

If several answers are unclear, fix the map at the point of ambiguity. You may only need to clarify an instruction, rename an unclear module, or remove a duplicate path. Avoid a broad refactor until the task trace shows that the existing structure itself prevents a clear change.

Start with one path

Pick one common task and make its route through the repository easy to explain. Then update the root guidance, feature examples, and checks so they describe the same path. Revisit the map when the code changes, and keep measured observations tied to the exact test that produced them.

For a related example of carrying a prototype into code you can inspect, read Prompt to production: one path. If you want a codebase to adapt while you work through your own structure, see Get started with OTF.

Sources

• SaaS Dashboard Kit documentation — checked 15 October 2026.
• OpenCode guide and dated SaaS Dashboard test report — checked 15 October 2026; the type-check statement above is dated 13 October 2026.

Free starter

Ship your first screen tonight — free starter in your inbox

The quickstart, the SDK repo and the live kit demos, on this screen and in your inbox.

Send the starter

No spam. Unsubscribe any time.