How many different apps do you use in your work? I'm guessing more than a few. Who doesn't have fragmented data spread across multiple systems and applications, and a challenge coordinating things across them? One app for bookkeeping, a different app for emails, another for keeping track of your work, maybe another for actually doing your work.
In my business, I think we probably take this to an extreme - we're not just managing one or two things, we have dozens of different client sites we're managing across a bunch of different platforms, and several different kinds of work, even, from maintenance/updates to new feature development to re-theming sites or building out new platforms.
We have 3 different systems that can track issues. We have our own chat platform, with a bot that attempts to keep things synchronized. We have deployment and testing pipelines to ensure quality through all sorts of change. We have two different monitoring systems, so if one goes down we know it -- and they can also monitor different kinds of things. We have multiple backup systems, and all this spread across multiple cloud providers.
There is no single system that can do everything for us! But we highly value self-hosting our platform, and making use of open source software for... reasons.
And now, in 2026, we have half a dozen code repositories with custom stuff to make it all work, and with coding agents, when we want to make improvements, it often involves code in 2 or 3 different repositories -- how do we use coding agents effectively?
The old way (Circa 2025)
Up until a week ago, I had a flat directory structure containing all my projects -- everything in a "git" directory, one layer deep. When I wanted to add new functionality, I would pick what I thought was the primary project that should "own" the new feature, and started work there. I would point the agent to other related directories, and it would make changes to those, but it always felt a bit disconnected - and it seemed like the agents were always working in the dark, making changes without the full picture. So when I decided to add composer audits to our nightly checks, I couldn't decide where to start -- was this something to add to the Matrix bot, or the CI/CD pipelines? It needed both -- and how best to make an agent aware of both code bases?
So I asked Claude how best to handle this. The answer? Group them all into a single directory, each project its own subdirectory. And thus, "Argo" was born -- the overarching project containing all our internal tools and repositories.
Really the only thing Argo has, aside from the child projects, are instructions for agents and a roadmap.
The new way: Argo
Claude Code, at least, looks for CLAUDE.md files in the current directory, and every parent directory, so organizing repositories this way provides valuable context -- while allowing sub-agents to focus on particular tasks at hand, without needing to keep all of the broader context loaded. In this way, agents are a lot like humans -- when you're focused on a specific task, you need to put blinders on and ignore what's not relevant -- but when you're coding, there are so many other areas you need to pay attention to.
Claude Code isn't the only coding assistant I use -- I really like Opencode. It's a much nicer interface to work in, showing context much better, color-highlighting as it goes, and it makes a lot of different models available. So for Opencode, I'm also providing an AGENTS.md file, which is just a symlink to the CLAUDE.md file. And I'm repeating this in every child repository, with repository-specific information.
Context Markers - making the invisible visible
One of the ongoing frustrations with AI coding tools is that you can't tell what the agent has actually loaded. Did it read the ground rules? Is it operating in the right context for this sub-repo? When something goes wrong, "did it read the file?" is often the first question.
The pattern I borrowed from Lada Kesseler's Augmented Coding Patterns solves this by making context visible: ask the agent to start every response with a specific character or emoji that proves it read the relevant file.
The root CLAUDE.md for Argo starts responses with ⚓. Each sub-repo stacks its own marker:
carina/→ ⚓ ⭐pipelines/→ ⚓ 🔧watney/→ ⚓ 🤖
If I ask a question and the response starts with just ⚓, I know the agent loaded root context but not the sub-repo file. If it starts with the stacked pair, both loaded. If neither appears, something is wrong with how the session started.
This sounds like a small thing. In practice it's surprisingly useful — especially in longer sessions where context can degrade, or when an agent picks up a task partway through and may not have walked the full directory tree.
Right now, Claude Code does seem to use these effectively -- with Opencode it seems a bit less consistent, I'm still experimenting to see if this varies by model, or is getting skipped by the Oh-My-OpenAgent setup I'm using.
What This Pattern Actually Solves
The core problem with multi-repo AI development is that agents are excellent within a bounded context and unreliable across invisible boundaries. A context marker doesn't fix that — but it makes the boundary visible. You stop guessing "does it know about Watney?" and start seeing it confirmed at the top of every response.
The parent CLAUDE.md also serves a different purpose than the per-repo files. The per-repo files describe how — implementation patterns, commands, local conventions. The root file describes why things are split the way they are and what the cross-cutting rules are. Don't add Matrix messaging logic to pipeline scripts. Carina is the source of truth; don't build parallel lists elsewhere. These are the rules that a specialist in one repo might not think to follow — and the ones most likely to cause hard-to-debug problems when violated.
The Practical Result
Most of the work described in the previous post — the security advisory pipeline, the clean-prod job, the Bosun CLI — was built with Claude Code operating inside this structure. The cross-repo context meant fewer "wait, where does this output go?" corrections mid-session. The markers meant I could see at a glance when a session had loaded the right context versus when I needed to re-establish it.
It's not a dramatic workflow revolution. It's more like good project documentation that also happens to be machine-readable. Which, given that we're now routinely working with agents that read documentation the way humans used to — selectively, imperfectly, but genuinely — turns out to be the same investment.
We're carrying this same pattern into our accessibility tooling — automated testing, checklist summaries, and a new Drupal-based remediation tracker, all getting the same parent-directory treatment.
If you're wrestling with fragmented tooling of your own, whether for dev ops, accessibility, or anything in between, get in touch — this is the kind of problem we enjoy.
Add new comment