One weekend in November 2025, I was working across three repositories in Visual Studio Code. RagBot was my multi-LLM chatbot, with a Python command-line interface and Streamlit UI, conversation history, custom personas, and a choice of OpenAI, Anthropic, Google, and other model providers. Its successor, RaGenie, used FastAPI and React for an agentic assistant designed to augment human capabilities through retrieval-augmented generation. Both consumed workspace configurations, instructions, and knowledge from a private repository called ragbot-data. RagBot was production-ready; RaGenie was still under development. I planned to keep developing both.
Claude Code helped me trace a distinction that mattered to a schema change: RagBot read the configurations directly from the filesystem, while RaGenie mounted the data read-only through Docker and re-indexed it into a vector database. Updating the source would reach those consumers differently. I call the practice of directing AI-assisted work across these related repositories polyrepo synthesis: synthesis coding applied across a whole system, with human architectural authority guiding the work.
Map the producer and each consumer
| Repository | What it owned | How a change reached the application |
|---|---|---|
| ragbot-data | Workspace definitions, instructions, procedures, and reference datasets | Changed source files such as workspaces/config.yaml |
| RagBot | Chatbot loading and presentation | Direct reads in src/helpers.py, followed by rendering in ragbot_streamlit.py |
| RaGenie | Retrieval and agent behavior | A read-only Docker mount, a file-change watcher, and re-indexing into Qdrant |
The shared data used a WHO/HOW/WHAT organization:
ragbot-data/
└── workspaces/
├── instructions/ # WHO: identity and persona
├── runbooks/ # HOW: procedures, later organized as Agent Skills
└── datasets/ # WHAT: reference knowledge
The hub owns the shared format. Consumers should not rewrite that source to make their own implementation pass. That ownership rule matters when an assistant proposes a convenient change in the repository already open in its terminal.
For a new workspace type, I want the change plan to identify the schema owner, every reader, and any derived data that needs refreshing. A direct reader may fail immediately on a renamed field. An indexed consumer may continue serving an old value. The second failure can remain invisible if verification stops at the source file.
Recognize the repository relationship
| Arrangement | Concrete example | Coordination work |
|---|---|---|
| Hub and consumers | Configuration or knowledge used by several applications | Identify the source owner, reader contracts, and refresh behavior |
| Product family | RagBot's Python/Streamlit interface and RaGenie's FastAPI/React implementation | Compare useful ideas, such as caching or UI behavior, against each product's constraints |
| Stack slice | Frontend, backend, shared types, and infrastructure | Trace a feature through API, client, and deployment changes; include model retraining when the feature requires it |
| Services with shared contracts | Services communicating through APIs or queues | Locate the authoritative OpenAPI, protobuf, or JSON Schema contract and check each producer-consumer pair |
| Monorepo extraction | A module becoming a separately released repository | Replace implicit source-tree dependencies with explicit interfaces, ownership, and release requirements |
| ML pipeline | Notebooks, training, serving, model artifacts, and evaluation data | Verify the transition from exploration to production, including the artifact and dataset versions used |
A caching approach in RagBot may be worth trying in RaGenie's API; an interaction in RaGenie's React frontend may inform RagBot's Streamlit UI. Separate Terraform or Pulumi repositories may add deployment work even when an application's own tests pass. If contracts are duplicated across services, decide which copy governs a change and how the others are checked.
The architectural decisions stay explicit as the workspace grows. My synthesis engineering framework describes that accountability across a team; the working arrangement here puts it into repository instructions and executable checks.
Set up the editor and the agent separately
September 2026 update: The setup commands below follow current Claude Code documentation. The downloadable exercise adds a worked example of direct and indexed consumption.
The downloadable exercise models three repository roles in separate folders, with Python consumers, source data, instruction files and a VS Code workspace.
polyrepo-example/
├── polyrepo.code-workspace
├── workspace-inventory.local.example.md
├── demo.py
├── test_consumers.py
├── shared-config/
│ ├── CLAUDE.md
│ ├── contract.py
│ └── versions/
│ ├── v1.json
│ └── v2.json
├── direct-app/
│ ├── CLAUDE.md
│ └── reader.py
└── indexed-app/
├── CLAUDE.md
└── search.py
Keep polyrepo.code-workspace beside those three folders. Its paths are relative to that file:
{
"folders": [
{ "path": "shared-config", "name": "Shared contract (synthetic)" },
{ "path": "direct-app", "name": "Direct consumer" },
{ "path": "indexed-app", "name": "Indexed consumer" }
],
"settings": {
"files.exclude": {
"**/__pycache__": true,
"**/.git": true
}
}
}
In VS Code, use File → Open Workspace to open the file, or add folders through File → Add Folder to Workspace and save the result. VS Code's multi-root workspace documentation explains relative paths and folder labels. Labels help distinguish roots; files.exclude hides entries in the editor. Neither makes private data safe to disclose or grants an agent permission to use it.
Claude Code's filesystem access and instruction loading need their own setup. Anthropic's CLI reference documents --add-dir for access to additional working directories. Its memory documentation says that additional directories' CLAUDE.md files do not load by default. The environment variable below enables that loading.
With the standalone Claude Code CLI installed, open VS Code's integrated terminal at the extracted example's root and use this Bash/Zsh procedure:
cd direct-app
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 \
claude --add-dir ../shared-config ../indexed-app
The standalone installation matters: Anthropic's VS Code documentation distinguishes the extension's bundled CLI from the claude command available in a terminal.
Claude Code also loads CLAUDE.md and CLAUDE.local.md from the working directory and its ancestors; descendant instruction files load when it reads files in those directories. In the launched session, inspect /context under Memory files to check which instructions loaded. Then ask it to read the producer and both consumers, citing the relevant files. Loaded instructions describe intended behavior; the implementation still needs inspection.
Give each repository useful instructions
Each repository's instructions contribute to a context mesh: connected documentation of the system's architecture and cross-repository relationships. The architect supplies the unified vision; the instructions record how each repository fits.
A public project's CLAUDE.md should explain its architecture, commands, contribution conventions, and interfaces in terms another contributor can use. Machine paths, private repository locations, and access notes belong in a private workspace inventory. The download includes a synthetic inventory example; read your real inventory explicitly when preparing a session. Its filename alone is not an instruction-loading mechanism.
The example's inventory gives the three repositories a shared map:
| Folder relative to this file | Role | Change responsibility |
| --- | --- | --- |
| shared-config | Authoritative schema and example source | Format and validation |
| direct-app | Reads source on every invocation | Displayed output |
| indexed-app | Builds and reads derived data | Refresh and query validation |
For your own workspace, record each repository's location, what it owns, and how its consumers use it. Cross-reference those relationships in the repositories' instruction files, and update the inventory when a repository or interface changes.
For personal project instructions that should stay out of source control, Claude Code documents CLAUDE.local.md; add it to .gitignore. Keep private material out of public files even when it would make your own setup more convenient.
# Shared workspace contract
Own the source format, versioned examples and reference parser in contract.py.
Current consumers use schema 2: schema_version, workspace_id and display_name.
The retained v1 example and explicit schema=1 calls demonstrate a rejected transition.
Do not change either source example to make a consumer test pass.
Direct consumers reread the source. Indexed consumers must rebuild derived records
after a source change, then verify the source digest and displayed label.
Run the integration checks from the extracted example's root directory with
python3 -m unittest -v test_consumers.py.
# Direct consumer
reader.py reads the source supplied on its command line for every call.
Current behavior requires schema 2 and returns display_name.
The schema=1 option is retained solely for the documented negative example.
Shared format validation belongs to the shared contract; presentation belongs here.
After an interface change, check the indexed consumer as well as this reader.
From the extracted example's root directory, run python3 -m unittest -v test_consumers.py.
# Indexed consumer
search.py builds and reads a derived JSON index. Current builds require schema 2.
A query must reject an index derived from different source bytes and a record
whose workspace_id or display_name differs from the current source.
Build to a new filename. Do not overwrite existing files or symlink targets.
legacy_snapshot_label deliberately omits freshness validation for the demonstration.
It is not the accepted query implementation.
From the extracted example's root directory, run python3 -m unittest -v test_consumers.py.
Instructions guide the assistant. A read-only mount, repository permissions, and executable checks do different jobs. Writing “don't modify the source” in an instruction file does not enforce that restriction.
For an open source tool that operates on other projects, document the tool's general behavior in its own repository. Before changing a target project, inspect that project's instructions and structure. Put a rule about where the target stores its schemas in the target's documentation, where its maintainers can keep it accurate.
Run a change through both consumers
The exercise uses one JSON record and a local JSON index to make the difference between direct and indexed consumption visible.
The first source has a name field:
{
"schema_version": 1,
"workspace_id": "demo",
"name": "Morning notes"
}
The changed source uses display_name and a new value:
{
"schema_version": 2,
"workspace_id": "demo",
"display_name": "Evening notes"
}
The shared reference parser validates the source format. The direct consumer reads it for each call. The indexed consumer builds a record with a hash of the source bytes, then compares that record with the current source when queried. The sibling imports in this download are a development fixture, not a production package-distribution design.
From the extracted example's root, run:
python3 demo.py
python3 -m unittest -v test_consumers.py
The driver creates its own temporary files and walks through the transition:
v1: both consumers display Morning notes
v2: old direct reader rejects the new schema
v2: updated direct reader displays Evening notes; old index still says Morning notes
v2: freshness check rejects the old index
PASS: rebuilt index and direct consumer agree on Evening notes
Updating the source and the direct reader leaves the indexed application serving the old label. A successful parser test in the direct application's repository would not establish that the indexed consumer had refreshed.
The indexed query's check includes both provenance and the visible record:
if index["source_sha256"] != digest:
raise StaleIndexError("index was built from different source bytes")
if index["workspace_id"] != workspace["workspace_id"] or index["display_name"] != workspace["display_name"]:
raise ContractError("indexed record does not match source")
return index["display_name"]
The digest is a coarse freshness marker. Even a whitespace edit requires a rebuild. It does not authenticate the source. Comparing the record as well catches the exercise's case of an edited label with an unchanged digest.
Now deliberately omit the rebuild:
python3 demo.py --skip-reindex
That command exits with status 1 and reports FAIL: release check rejected stale indexed output. The rejection is the expected result. The accepted path rebuilds to a new index file and checks that both consumers display Evening notes.
All 20 local tests passed with Python 3.12.3. They include stale data, the wrong schema, a changed indexed label, invalid input, and preservation of an existing index or symlink target. The separate no-rebuild command failed as intended.
Decide where shared code belongs
A cross-repository assistant also needs to know which repository should own new behavior. I maintained a media analytics platform with a shared core, an external API, and an ingestion pipeline:
media-graph-core/
└── src/
├── types/ # Types used across services
├── utils/ # Shared utilities
└── validators/ # Shared validation
media-graph-api/
└── src/
├── routes/
└── services/
└── date-formatter.ts # External-response formatting
media-graph-ingest/
└── src/
├── parsers/
└── transforms/
└── date-normalizer.ts # Ingestion normalization
“Add a date parsing utility” leaves an architectural decision unresolved. A parser required by both services belongs in the shared core. Formatting an API response belongs in the API. Normalizing a particular input source belongs in ingestion. The current working directory cannot settle that decision.
An assistant may put the function in the repository it is already editing. That can leave duplicated parsing behavior, with a bug fixed in one consumer and still present in another. The review should ask where the behavior is needed and what interface its consumers will share.
For the API repository, an ownership section could say:
## Ownership
This repository owns external API routes and response formatting.
Before adding a utility, identify its consumers.
- Logic required across services belongs in media-graph-core.
- External-response formatting belongs here.
- Input-source normalization belongs in media-graph-ingest.
Check the core's existing types, date utilities, validators and error types
before creating a second implementation. If ownership remains unclear,
record the alternatives and resolve the decision before implementation.
The shared library needs the corresponding instructions: identify its consumers, check existing utilities, define the public types, implement the behavior, and export it through index.ts when that is the library's entry point. Test the affected consumers against the changed interface. A shared location only helps if each consumer uses it.
Coordinate the change and the release
For a cross-repository feature, I use a change plan that names the source change, each consumer change, the checks, and the release sequence. Defining the new schema comes first in the design; deploying it first is a separate decision.
In the three-folder exercise, switching the source to schema 2 makes an unmodified schema-1 reader fail. Updating the consumers to read schema 2 still leaves the derived index unfinished. Before a real release, decide whether the rollout tolerates a mixed-version interval or requires a coordinated cutover. Test the combinations that will actually exist during that interval, and include a way to recognize and recover from a failed refresh.
Version bumps and related release tags make the changes traceable. They don't make separate deployments atomic. For the historical RagBot/RaGenie arrangement, the plan needed to account for application versions, Docker configuration where affected, and the indexed data. An assistant can draft release notes from those changes; someone still has to verify the running consumers.
I keep Git operations explicit about their target repository. Wrong-directory warnings have saved me from wrong-repository commits. After moving into the intended checkout, check pwd, git rev-parse --show-toplevel, git remote -v, and the diff before staging. The editor's active tab is a poor substitute for the terminal's working directory.
A useful investigation request names the trace and the expected evidence:
Read the shared schema and each consumer's loading path. Identify where the value reaches the user, whether it is cached or indexed, and what must change after the field rename. Cite the files and propose a check for each path before editing.
For the RagBot flow, that meant following workspaces/config.yaml through src/helpers.py to ragbot_streamlit.py. For the indexed consumer, it meant checking the refresh and the query result.
Keep the map accurate
Concise instructions should point to the relevant architecture, interfaces, and commands. An inventory of everything the assistant could read adds work for every session. Keep detailed, task-specific material near the component that owns it and load it when needed.
Different repository conventions can be legitimate. In that setup, RagBot used Python type hints; RaGenie used Pydantic models and TypeScript in its frontend. The instructions should scope those choices to the code they govern. Resolve actual contradictions, such as two repositories claiming authority over the same schema.
Update the dependency map when a service, consumer, or data path changes. In my workflow, the corresponding instruction changes travel with the implementation. A previous session's explanation needs to be checked against the current files before it guides another change.
The most useful cross-repository question is often: “Where does this value end up?” In the exercise, the direct reader's answer changed while the indexed reader's answer did not. Following the value all the way to both outputs tells you what remains to be done.
The architectural advantage
I now think at the level of systems. Claude Code helps me navigate architectural relationships that would otherwise require holding too much context in my head.
As I wrote in my earlier piece on synthesis coding workflows, the compounding context advantage is real. CLAUDE.md files encode institutional knowledge. Keeping those files accurate gives later sessions a record of what we have learned and which decisions govern the work. The investment in setting up proper context pays dividends across future work.
If you've used vibe coding for rapid prototyping — and I do, for weekend projects and quick experiments — you know how liberating it feels to describe what you want and let the AI handle it. Polyrepo synthesis brings that same collaborative power to production systems, with the discipline required when changes span multiple repositories, teams, and deployment pipelines.
Modern software lives across multiple repositories. The engineers who master polyrepo synthesis — who can coordinate AI assistance across distributed systems while maintaining human architectural authority — will build the next generation of production software.
Build the CLAUDE.md context mesh once, maintain it as your architecture evolves, and watch your productivity multiply across your codebase.