Claude Code in a Microservices Setup: A Practical Guide

Claude Code works great on a single service. The moment you have ten services each in their own git repository, it stops knowing where it is.

It suggests calling the orders database from the user-service. It forgets your team uses Kafka for async events. It recommends patterns from the wrong stack. Not because Claude is bad, but because it has no map.

The fix is giving it one.

The Approach: @import from a Shared Repo

Claude Code supports importing other files inside CLAUDE.md using the @path/to/file syntax. This lets you pull shared standards from a dedicated versioned repo directly into each service’s context.

team-standards is its own git repo. Changes go through PR review. Every developer clones it once. Each service imports it at the top of its CLAUDE.md. Updates to shared standards propagate automatically on the next git pull.

File Structure

~/work/
├── team-standards/              ← own git repo, cloned once by every dev
│   ├── CLAUDE.md                ← single source of truth for shared context
│   ├── .claude/
│   │   └── commands/
│   │       ├── review.md        ← shared commands, versioned here
│   │       ├── new-service.md
│   │       └── boundary-check.md
│   └── scripts/
│       └── sync.sh              ← copies commands to ~/.claude/commands/
│
├── user-service/                ← own git repo
│   ├── .git/
│   ├── CLAUDE.md                ← starts with @../team-standards/CLAUDE.md
│   └── .claude/commands/        ← service-specific commands only
│
├── order-service/               ← own git repo
│   ├── .git/
│   ├── CLAUDE.md                ← starts with @../team-standards/CLAUDE.md
│   └── .claude/commands/
│
└── notification-service/        ← own git repo
    ├── .git/
    └── CLAUDE.md                ← starts with @../team-standards/CLAUDE.md

The only requirement: every developer clones team-standards into the same relative location. Document this as a one-time onboarding step.

team-standards/CLAUDE.md: The Shared Map

This file answers: what does the whole system look like?

# Shared Standards
- Auth: JWT validated at API gateway, services trust X-User-Id header
- All inter-service calls go through the service mesh, no direct DB access
- Tracing: OpenTelemetry on every service

# Service Registry
- user-service:         :8081  PostgreSQL, owns `users` table
- order-service:        :8082  PostgreSQL, owns `orders` table
- notification-service: :8083  Kafka consumer only, no DB

Changes here go through PR review in team-standards. Every developer gets the update on next git pull.

Per-Repo CLAUDE.md: The Rules

Each service CLAUDE.md starts with the import, then adds only what is specific to that service:

@../team-standards/CLAUDE.md

# order-service
- Node.js 22, Fastify, PostgreSQL
- Publishes: OrderPlaced, OrderCancelled → Kafka topic `order-events`
- Consumes: PaymentConfirmed ← Kafka topic `payment-events`

# What this service owns
- PostgreSQL table: orders

# What this service must NOT do
- Read from the users table directly (call user-service REST instead)
- Publish to any topic not listed above
- Call notification-service directly

The “must NOT do” block is the most valuable part. It prevents the most common class of mistakes Claude makes across service boundaries.

Shared Commands

Claude Code only auto-loads commands from the current project’s .claude/commands/. It does not follow @import for commands the way it does for CLAUDE.md. So commands in team-standards need a different distribution mechanism.

Option 1: Sync script

Put commands in team-standards/.claude/commands/, then copy them to ~/.claude/commands/ which Claude loads globally for every project:

#!/bin/bash
# team-standards/scripts/sync.sh
cp .claude/commands/* ~/.claude/commands/
echo "Claude commands synced"

Developers run this once after cloning, and again after pulling updates. Commands stay versioned in team-standards and are distributed via the script.

A boundary check command is a good example. A boundary violation is when a service crosses into another service’s territory: reading a table it does not own, calling an undocumented endpoint, or publishing to a Kafka topic not listed in its own CLAUDE.md. The command cross-references the code against the rules already written in the service’s CLAUDE.md:

<!-- team-standards/.claude/commands/boundary-check.md -->
Review $ARGUMENTS and flag any boundary violations:
- SQL queries touching a table not listed under "What this service owns"
- HTTP calls to endpoints not listed under "What this service consumes"
- Kafka publishes to topics not listed under "Publishes"
- Imports from another service's internal package

Run it as /boundary-check src/orders/OrderService.java for a focused audit on demand.

Option 2: Embed rules in team-standards/CLAUDE.md instead

For patterns that should always apply, such as reviewing service boundaries, put the rule directly in the shared CLAUDE.md as an instruction rather than a slash command. Claude follows it automatically without anyone needing to invoke it:

# Review Checklist
When asked to review code, always check:
- Does it access a database table not owned by this service?
- Does it call another service directly instead of through the service mesh?
- Are any new Kafka events documented in this repo's CLAUDE.md?

Always-on rules belong in CLAUDE.md. One-off tasks that require explicit invocation belong in commands.

Practical Habits

/clear between services. Context from one repo bleeds into the next. Always clear before switching.

Name the service in every prompt. “In order-service, add a cancellation endpoint” not just “add a cancellation endpoint”. It anchors Claude immediately.

Use --add-dir when touching two services at once.

claude --add-dir ../order-service

Claude reads across both repos in one session without losing context.

The Full Picture

Key Takeaway

A versioned team-standards repo with @import in every service gives the whole team the same shared context, reviewed like any other code and consistent from day one.