One Entry Point for Your Coding Agent: Organizing Multi-Repo, Multi-Product Context

I work on several products at once. One of them has twenty repositories: microservices, infrastructure, a config repo. A typical task touches three or four repos, and every time I opened a new session with a coding agent, I started with the same routine: explaining which services exist, who calls whom, where the configs are, what the product even does. Session over — explain it all again.

For a while I survived on temporary instruction files: I'd write one per task or per epic and drag it from session to session. But when several people work on the same epic, those files also need careful updating, and for a new task I often ended up feeding the agent a mix of several old instructions at once. It worked, but it was clumsy.

I looked around for how others solve this and found no established approach. Everyone has something home-made: some have CLAUDE.md files in half of their repos, quietly going stale; some have skills and MCP configs copy-pasted across ten projects; notes and temporary files are scattered everywhere. There is simply no standard for organizing agent context across many repositories and products.

So I built my own and packaged it as an open template: agent-workspace. Below is how it works, why it works, and answers to the questions I got when I showed it to colleagues.

The idea

One directory — a single entry point for the agent. Everything lives inside it: all the organizations, products and repositories you work with. The agent always starts from the root.

Context is built in layers — four levels of CLAUDE.md files, four levels of abstraction:

• Workspace — base rules for the agent's behavior, not tied to any company.
• Organization — briefly, what the business is and what matters to it (a startup and a big company set different priorities), plus company conventions: commit style, shared infrastructure. Personal projects are just one more "organization".
• Product — what the product is, which repositories it consists of, and how they relate to each other.
• Repository — the low-level details: structure, build, run, gotchas. This file lives inside the repo itself and travels with it.

There is one key rule: every fact lives on exactly one level. How microservices are connected - product level; the build command — repo level. Nothing is duplicated, so nothing has to go stale in two places at once.

Everything machine-specific — local ports, personal dev tokens — goes into CLAUDE.local.md. It is created only at the repository level, next to that repo's CLAUDE.md: the shared file is usually maintained by the team, while the local file is your personal layer of details on top of it, never committed to git.

Besides the levels, the root holds helper directories and a single .claude with all the skills, commands and agents — they work everywhere under the root. The basic structure looks like this:

agent-workspace/
├── CLAUDE.md            # workspace level: base agent rules
├── .claude/             # skills, commands, agents — one set for everything
├── .mcp.json            # MCP servers config
├── org_1/
│   ├── CLAUDE.md        # organization level
│   └── product_1/
│       ├── CLAUDE.md    # product level
│       ├── repo_1/      # a regular git repository
│       │   └── CLAUDE.md   # repository level — lives inside the repo itself
│       └── repo_2/
├── org_2/
│   ├── CLAUDE.md
│   └── ...
├── private/             # personal projects — one more "organization"
├── workflow/            # notes on tasks and work in progress
│   ├── task/
│   │   ├── TASK-123/    # one directory per task: status, notes, artifacts
│   │   └── TASK-456/
│   └── notes/
├── tools/               # small helper scripts
├── TMP/                 # drafts, reports, scripts and other temporary files
└── archive/             # retired and outdated stuff

What it looks like on a real task

Take a product — let's call it Hamsterflow — where a task touches three microservices out of eight repositories. The agent starts from the workspace root and:

1. Reads the root CLAUDE.md — behavior rules.
2. Goes down into the organization directory and reads its CLAUDE.md — company context and conventions.
3. Goes into the product directory and reads the product CLAUDE.md — now it knows all the product's repositories and how they are connected, and understands which three the task will touch.
4. Enters those three repositories and reads their CLAUDE.md files.

That's it. It didn't scan the neighboring products, didn't touch my notes or personal repos — even though all of that sits in the same directory. It read only the chain along the task path.

The chain gives knowledge about the product, but not about the task itself. For that, the workspace has a dedicated place — workflow/task/<ticket-number>/: a working file with the current status, what's done, where we're heading, and links to fresh docs for the task (the docs themselves go into the same directory; if they live in Confluence — just links). At the start of a session I simply feed this file to the agent — and it instantly knows not only the product, but also where we stopped yesterday.

The starting context after all this is about 27k tokens (not counting the system prompt, tools and MCP), and the agent already knows everything about the product that I usually had to explain. For comparison: without the structure, "figure out how things work here" on the same three services eats 60–120k — the agent immediately starts scanning the projects in depth. With the structure, most of that is already written in the CLAUDE.md files, and when the code does need to be read, the relevant files are found much faster: the modules and key classes are already named in the chain it has read. And this repeats every session, not just once.

An important caveat, to be honest: token-wise this is not always a win. When you know exactly what to fix and where, a narrow prompt pointing at a specific file will save far more than any structure — there's no reason to read the CLAUDE.md chain at all. The win shows up on cross-project tasks, where you can't get anywhere without the picture of how things connect — and the win is first of all in developer time: the agent is up to speed from the first minute, and you don't retell the same story every day.

Keeping it from rotting

The main disease of any docs written for an agent: they quietly go stale. The template treats this with two things.

Every CLAUDE.md carries a date stamp of its last update. And there are two dedicated skills: one creates the files with a fixed structure for each level, the other refreshes an existing file — it takes the date stamp, looks at the commits and code since that date (and the company docs, if Jira/Confluence is connected), removes what's outdated, adds what's new, updates the stamp. You can ask an agent to "update the doc" without any skill — but the skill strictly defines the rules: what counts as the source of truth, what goes on which level, what should not be written at all. The update becomes predictable, instead of a lottery that produces junk and degrades with every iteration.

workspace-manager

The template ships with an agent that manages this structure. You start it with /init_workspace_manager; it asks what you have and sets everything up itself: creates organizations and products, integrates existing repositories — from a local path or a GitHub/GitLab URL. A local repo it copies rather than moves — together with IDE settings and local env files, so the copy runs right away and the original stays intact until you've checked everything.

For every repo it checks whether a CLAUDE.md exists, offers to create or refresh it, and decides (or asks) which product the repository belongs to. The whole move takes an evening.

Its scope is the workspace itself: set up the structure, integrate repositories, keep the CLAUDE.md files and settings up to date. Actual coding tasks you do in regular sessions, without it.

What about teams

The most common question: "isn't this a dictatorship — the whole team has to adopt your structure?" No. Synchronization works in three layers:

• Repository-level CLAUDE.md — shared. It lives in the repo itself, gets pushed and maintained by the team, like a README. It works for everyone, whether they use a workspace or not.
• Workspace, organization and product levels — yours, personal. A colleague can build their own workspace or not build one at all — nothing breaks for you either way.
• Skills, commands, agents — everything in .claude — no need to copy them across twenty microservices. You create a separate repository per product, set up as a plugin marketplace — the official Claude Code mechanism for sharing this stuff. Everyone pulls what they need; updates come with a single command. A plugin enabled at the workspace root works for any product under it.

Context: fears and numbers

"The agent will end up with a giant context, it will crawl everything anyway." In practice — no: reading follows the task path, the rest of the tree is never touched. And there is no indexing that would crawl the whole tree: Claude Code doesn't build an index of the codebase at all — it searches the code on the fly, as needed.

"Skills in the root will bloat the context." Also no: only the name and a short description of each skill get into the context automatically. The full instruction is loaded only when the skill is actually used. MCP servers are worse — they carry descriptions of all their tools and can easily eat 20–30k tokens in total. So the ones you don't need for the current work should be turned off, not left running all at once.

Context degradation on large contexts is worth remembering, but what matters is where it comes from. Modern strong models handle sheer volume reasonably well; what hurts them much more is thematically fragmented context — when different topics and tasks are mixed together and half the content has nothing to do with the current work. Layered reading protects exactly against that: only the chain along the task path gets into the context, and everything in it is about what you're working on right now.

Security

I'll state the obvious, but I can't skip it: working this way, the model sees a lot about your products — architecture, service relationships, code. For me it's simple: corporate accounts, the company has set the rules, customer data never reaches the model. Check how it is on your side — before the move, not after.

One more thing: when a couple of companies and your personal projects sit side by side in one entry point, the agent can accidentally pick up something you never meant to share with the model. Whatever doesn't fit the rules — just don't put it in the workspace.

And basic hygiene: secrets don't belong in CLAUDE.md on any level. Personal dev tokens go into the gitignored CLAUDE.local.md; tokens in the MCP config come from environment variables.

About the Claude coupling

The files are called CLAUDE.md because Claude Code reads them by default — I work in it, and for the first version I chose what's guaranteed to work. If you're on Cursor or another tool that follows the AGENTS.md standard — workspace-manager will offer, during the first setup, to rename all the files and rewrite every mention. To be honest: I haven't tested yet how other agents behave with this structure.

Try it

1. Clone the template and open it in Claude Code.
2. Run /init_workspace_manager — it will walk you through the setup and the integration of your repositories.
3. Delete the org_1/org_2 mock skeletons once you have real content (the agent will offer to).

The template will keep evolving — new skills, commands, agents, improvements to existing ones. For that there's the workspace-update skill: it compares your workspace against the source repository (the template version recorded in your workspace is the baseline), shows what changed, and after your confirmation pulls the updates in — without touching your content: organizations, products and notes stay as they were.

I'm curious how others solve this — if you organize multi-repo context for your agent differently, tell me about it.

By Vladislav, edited with Claude