Claude Code in a Monorepo

Claude Code in a Monorepo is Total Ventures' approach to providing AI agents with precise, up-to-date context by embedding `CLAUDE.md` files within each package and a project-level `AGENT_MAP`.

What it is

This pattern involves two core components within a monorepo structure. First, a `CLAUDE.md` file is placed at the root of each individual package (e.g., `apps/my-app/CLAUDE.md`, `packages/ui-components/CLAUDE.md`). This file serves as a dedicated, concise instruction set and architectural overview for that specific package. It details its purpose, key dependencies, common patterns, and any specific coding conventions. Second, an `AGENT_MAP` (e.g., `AGENT_MAP.json`) resides at the monorepo root. This central configuration maps various AI agents (e.g., `CodeReviewer`, `FeatureImplementer`) to their specific roles, available tools, and, critically, the relevant `CLAUDE.md` files or directories they should reference for a given task. When an AI agent is invoked, a pre-processing step collects the necessary `CLAUDE.md` content and injects it into the agent's prompt context, ensuring it operates with highly specific, current codebase knowledge.

Why it matters

For a small team or solo operator managing a portfolio of products, maintaining consistency and accelerating development cycles is paramount. This approach significantly enhances contextual accuracy for AI agents, reducing the incidence of hallucinations and improving the quality of generated code. Agents operate with package-specific knowledge, which is crucial in a monorepo where global context can be overwhelming. This leads to greater efficiency, as less time is spent correcting agent output, and iteration on code tasks is faster. It also promotes consistency, helping enforce architectural patterns and coding standards across disparate packages, even when different agents are at work. Furthermore, the `CLAUDE.md` files act as living documentation, updated alongside the code, which is invaluable for long-term maintainability and onboarding, whether for humans or agents. This structured context is particularly beneficial for projects leveraging Programmatic SEO, where a monorepo might house numerous small services or content engines that need consistent development.

How TV applies it

Total Ventures utilizes a Turborepo-based monorepo, with frontends deployed on Vercel and backend functions managed via Firebase. Within this structure, every `apps/` directory (for Next.js or Astro projects) and `packages/` directory (for shared UI components, utility functions, or shared types) contains its own `CLAUDE.md`. Our root `AGENT_MAP.json` defines agents like `CodeReviewer`, `FeatureImplementer`, and `BugFixer`. Each agent's entry specifies which `CLAUDE.md` files (or patterns) it should ingest for its assigned tasks. For instance, our `CodeReviewer` agent might ingest all `CLAUDE.md` files associated with changed files in a pull request, alongside the monorepo's root `CLAUDE.md`. A `FeatureImplementer` tasked with adding a new component to `totalformula1-web` would receive context from `apps/totalformula1-web/CLAUDE.md` and relevant `packages/ui/CLAUDE.md`. This setup is integrated into our CI/CD pipeline. Before an agent executes a task, a script dynamically collects the appropriate `CLAUDE.md` content and injects it into the LLM's prompt. This systematic approach has proven effective in accelerating development, especially when working on new content engines or iterating on features that directly impact our Content Velocity Measurement efforts.

Common failure modes

The primary risk with this pattern is outdated `CLAUDE.md` content. If the documentation doesn't accurately reflect the current codebase, agents will generate incorrect or deprecated solutions, negating the benefits. Maintaining discipline to update these files alongside code changes is critical. Another pitfall is over-contextualization; providing too much `CLAUDE.md` content can hit token limits, dilute the agent's focus, or introduce irrelevant noise. Conversely, under-contextualization leads to generic or incorrect output. Striking the right balance through careful curation in the `AGENT_MAP` is key. Ambiguous or poorly written instructions within `CLAUDE.md` files themselves can also lead to misinterpretations by agents, resulting in suboptimal output. Finally, a lack of automated tooling to collect and inject the relevant context makes this process a manual burden, prone to human error and inconsistency, which can hinder efforts like SEO Content Gap Analysis where agent accuracy is vital.