Last updated: March 16, 2026

Monorepos with multiple services present unique challenges for AI coding assistants. When your project spans dozens of services, shared packages, and interconnected dependencies, a well-crafted CLAUDE.md file becomes essential for getting useful responses from AI tools. This guide shows you how to structure your CLAUDE.md file so AI understands your monorepo’s architecture and provides accurate, context-aware assistance.

Table of Contents

Why Monorepos Need Special CLAUDE.md Treatment

In a monorepo containing multiple services, AI tools face several challenges that single-repo projects don’t encounter. The AI needs to understand which service it’s working in, what shared dependencies exist, and how services communicate with each other. Without this context, AI might suggest code that conflicts with your architectural patterns or reinvents solutions already available in shared packages.

A generic CLAUDE.md file works fine for simple projects. But monorepos require explicit documentation of your project structure, service boundaries, and team conventions. The goal is to help AI make decisions that align with your existing codebase rather than generating generic solutions.

Prerequisites

Before you begin, make sure you have the following ready:

Step 1: Structuring Your Monorepo CLAUDE.md

Define Your Directory Structure First

Start by documenting the root-level organization of your monorepo. This gives AI an immediate mental map of where things live.

### Step 2: Project Structure

/

├── apps/ # Deployable services

│ ├── api-gateway/ # Main API entry point

│ ├── user-service/ # User management

│ ├── payment-service/ # Payment processing

│ └── notification-service/ # Email and push notifications

├── packages/ # Shared libraries

│ ├── shared-utils/ # Common utilities

│ ├── database/ # ORM and migrations

│ └── types/ # TypeScript type definitions

└── tools/ # Build and deployment scripts


Include a brief description of each service's responsibility. This helps AI understand the boundaries between services and avoid cross-service contamination in code generation.

### Document Service Dependencies Explicitly

Monorepos often have complex dependency graphs. AI needs to know which services depend on which packages and how services communicate.

```markdown
### Step 3: Service Dependencies

- api-gateway: Depends on user-service, payment-service; uses shared-utils, database, types

- user-service: Uses database, types; communicates via REST to payment-service

- payment-service: Uses database, types; publishes events to notification-service

- notification-service: Consumes events from payment-service; uses types

### Step 4: Communication Patterns

- Services communicate via HTTP REST APIs

- Events are published through internal message queue

- Database access is restricted to respective service packages only

This explicit documentation prevents AI from importing packages across service boundaries or creating circular dependencies.

Step 5: Defining Shared Code Boundaries

Shared packages in monorepos require special attention. Document what lives in shared packages and when to use them versus when to create service-specific code.

### Step 6: Shared Packages Usage

### shared-utils

Use for: Logging helpers, date formatting, validation utilities

Do NOT use for: Business logic, database operations, service-specific concerns

### database

Use for: All database connections, ORM setup, migration running

Do NOT create: New database connections within services; always import from database package

### types

Use for: All TypeScript interfaces and types used across services

Do NOT duplicate: Types that already exist in packages/types

This prevents the common monorepo problem of duplicated utilities and inconsistent type definitions across services.

Step 7: Coding Conventions for Monorepo Context

Import Path Conventions

Document how imports should be structured in your monorepo:

// Correct - using path aliases

import { UserService } from '@company/user-service';

import { formatDate } from '@company/shared-utils';

import { User } from '@company/types';

// Avoid - relative paths across service boundaries

import { User } from '../../../packages/types';

Service-Specific Configuration

Each service in your monorepo likely has specific configuration requirements. Document these patterns:

### Step 8: Service Configuration

Each service follows the same configuration pattern:

- Configuration lives in `config/service-name.ts`

- Environment variables are validated at startup

- Default values are never hardcoded; always use config files

- Secrets are loaded from environment, never committed to repository

Step 9: Commands and Scripts

Document the monorepo-specific commands developers use regularly:

### Step 10: Available Commands

```bash
# Build all services
npm run build:all

# Build specific service
npm run build:api-gateway

# Run tests for single service
npm test -- --filter=user-service

# Run tests across all services
npm test:all

# Lint with service awareness
npm run lint -- --scope=user-service

Step 11: Handling Cross-Service Changes

One of the hardest things for AI to get right in monorepos is understanding the scope of changes. Document your workflow:

### Step 12: Change Guidelines

1. **Single service changes**: Can be made independently; ensure tests pass
2. **Shared package changes**: Require updating version in all dependent services; run full test suite
3. **Database schema changes**: Must include migration files; coordinate with affected services
4. **API changes**: Update OpenAPI specs in types package; version endpoints appropriately

This helps AI understand the ripple effects of its suggestions and avoid making changes that break other services.

Step 13: Test Strategy Documentation

Monorepos typically have complex testing requirements. Make sure your CLAUDE.md explains your testing philosophy:

## Testing Requirements

- Unit tests live alongside source files: `src/utils.ts` → `src/utils.test.ts`
- Integration tests live in `tests/integration/`
- Each service has its own test suite
- Shared package changes require running all dependent service tests
- Minimum coverage threshold: 80%

Best Practices Summary

A well-structured monorepo CLAUDE.md file should answer these questions for any AI:

  1. Where is the code I’m working on located? (Directory structure)

  2. What does this service depend on? (Service dependencies)

  3. What shared resources can I use? (Shared packages)

  4. How should I import things? (Import conventions)

  5. What commands are available? (Build, test, deploy)

  6. What are the boundaries of my change? (Service isolation)

Keep your CLAUDE.md updated as your monorepo evolves. When you add a new service or change your dependency structure, update the documentation. An outdated CLAUDE.md file is worse than no file at all because it gives AI false confidence in its understanding of your project.

The investment in maintaining a CLAUDE.md pays dividends in reduced AI hallucination, faster development cycles, and more accurate code generation across your entire monorepo team.

Troubleshooting

Configuration changes not taking effect

Restart the relevant service or application after making changes. Some settings require a full system reboot. Verify the configuration file path is correct and the syntax is valid.

Permission denied errors

Run the command with sudo for system-level operations, or check that your user account has the necessary permissions. On macOS, you may need to grant terminal access in System Settings > Privacy & Security.

Connection or network-related failures

Check your internet connection and firewall settings. If using a VPN, try disconnecting temporarily to isolate the issue. Verify that the target server or service is accessible from your network.

Frequently Asked Questions

How long does it take to write effective claude md file for monorepo?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Can I adapt this for a different tech stack?

Yes, the underlying concepts transfer to other stacks, though the specific implementation details will differ. Look for equivalent libraries and patterns in your target stack. The architecture and workflow design remain similar even when the syntax changes.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.

Built by theluckystrike — More at zovo.one