← Retour aux guides

Claude Code for Large Monorepos: A Lean Setup

Configuring Claude Code for a large monorepo starts with three decisions: where sessions launch, which instructions load, and what files the agent should read. Smaller, relevant context helps control token consumption and reduces distractions. This quick-start uses an example repository containing packages/api, packages/web, and packages/shared. ([code.claude.com](https://code.claude.com/docs/en/large-codebases))

1. Choose a predictable launch directory

Start with claude at the repository root for cross-package changes. Root instructions load immediately; nested CLAUDE.md files load on demand. For isolated API work, launch from packages/api instead: Claude loads that directory’s instructions plus ancestor instructions. ([code.claude.com](https://code.claude.com/docs/en/large-codebases))

For the simplest team rollout, standardize on root launches first. Shared .claude/settings.json files are not inherited from parent directories like CLAUDE.md files, so launching from a package can change which project settings apply. Document your launch convention before troubleshooting apparently ignored permissions. ([code.claude.com](https://code.claude.com/docs/en/settings))

2. Split instructions by responsibility

Commit a short root CLAUDE.md containing repository-wide requirements. Add package-specific files for local conventions rather than stuffing every subsystem’s documentation into the root. Keep instructions concrete and verifiable; Anthropic recommends targeting fewer than 200 lines per file. ([code.claude.com](https://code.claude.com/docs/en/memory))

• Root: record the package manager, dependency-boundary rules, and commands developers must run before submitting changes.
• packages/api/CLAUDE.md: explain test fixtures, migration policy, and how to regenerate API clients.
• packages/web/CLAUDE.md: specify component conventions, accessibility checks, and frontend test commands.

For a pnpm workspace, an example instruction is: “Run pnpm --filter @acme/api test after API changes.” Replace the example package name and script with actual package.json entries.

3. Configure permissions without disabling safeguards

For root-launched sessions, merge this example into .claude/settings.json, preserving existing keys:

{"permissions":{"deny":["Read(./**/.env)","Read(./**/.env.*)","Read(./**/dist/**/*)","Read(./**/vendor/**/*)"]}}

These rules restrict matching file reads. Do not mistake CLAUDE.md instructions or a .claudeignore file for access controls: instructions are advisory, and .claudeignore has no effect. Review permission prompts instead of disabling them globally. ([code.claude.com](https://code.claude.com/docs/en/permissions))

Read restrictions are not a complete sandbox for arbitrary subprocesses. Keep production credentials outside the checkout and use your organization’s approved isolation controls for sensitive work. ([code.claude.com](https://code.claude.com/docs/en/large-codebases))

4. Add sibling packages deliberately

If you launch inside packages/api and need shared-library access, run claude --add-dir ../shared. Access and instruction loading are separate: to load that additional directory’s CLAUDE.md and rules too, use CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared. From the repository root, sibling packages already fall within the working tree. ([code.claude.com](https://code.claude.com/docs/en/large-codebases))

5. Connect 59API for cost-conscious usage

59API is a low-cost, pay-as-you-go relay compatible with Claude Code, Codex, and OpenAI SDKs. It advertises native official-quality models without downgrading, making it worth evaluating for recurring development workloads. Compare current model rates and cache billing against your actual usage rather than assuming every request costs the same. ([59api.com](https://59api.com/blog/custom-ai-cli-base-urls-claude-code-and-codex-fixes-4161?utm_source=openai))

For macOS or Linux, its homepage documents bearer-token configuration. Run these commands in the terminal that will launch Claude Code:

• export ANTHROPIC_BASE_URL='https://api.59api.com'
• export ANTHROPIC_AUTH_TOKEN='YOUR_59API_KEY'
• claude

Use your real key, resolve competing credentials before testing, and never commit secrets. Select an exact model identifier supported by your account. 59API also offers a referral rebate; if this setup fits your workflow, consider signing up and testing one small task first. ([59api.com](https://59api.com/))

6. Validate with one bounded change

Try: “Inspect packages/api and packages/shared. Propose a plan for fixing the pagination bug. Change only necessary files, run the API test script, and report any untested consumers.” Check the diff and test output yourself before expanding the task.

Run /context to inspect loaded instructions, and /clear between unrelated tasks. Verify charges in the relay dashboard: Claude Code’s locally calculated cost estimate can differ from provider billing. ([code.claude.com](https://code.claude.com/docs/en/large-codebases))

Tarifs · Docs