working-in-monorepos

Working in Monorepos

Overview

Helps Claude work effectively in monorepo environments by ensuring commands always execute from the correct location using absolute paths.

Core principle: Bash shell state is not guaranteed between commands. Always use absolute paths.

Announce at start: "I'm using the working-in-monorepos skill."

When to Use

Use this skill when:

• Repository contains multiple subprojects (ruby/, cli/, components/*, etc.)
• Commands must run from specific directories
• Working across multiple subprojects in one session

Don't use for:

• Single-project repositories
• Repositories where all commands run from root

The Iron Rule: Always Use Absolute Paths

When executing ANY command in a monorepo subproject:

✅ CORRECT:

cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec
cd /Users/josh/workspace/schemaflow/cli && npm test

❌ WRONG:

# Relative paths (assumes current directory)
cd ruby && bundle exec rspec

# No cd prefix (assumes location)
bundle exec rspec

# Chaining cd (compounds errors)
cd ruby && cd ruby && rspec

Why: You cannot rely on shell state. Absolute paths guarantee correct execution location regardless of where the shell currently is.

Constructing Absolute Paths

With .monorepo.json Config

If .monorepo.json exists at repo root:

1. Read root field for absolute repo path
2. Read subproject path from subprojects map
3. Construct: cd {root}/{path} && command

Example:

{
  "root": "/Users/josh/workspace/schemaflow",
  "subprojects": { "ruby": { "path": "ruby" } }
}

→ cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec

Without Config

Use git to find repo root, then construct absolute path:

1. First get the repo root: git rev-parse --show-toplevel
2. Use that absolute path: cd /absolute/path/to/repo/ruby && bundle exec rspec

Example workflow:

# Step 1: Get repo root
git rev-parse --show-toplevel
# Output: /Users/josh/workspace/schemaflow

# Step 2: Use absolute path in commands
cd /Users/josh/workspace/schemaflow/ruby && bundle exec rspec