← Voltar aos guias

Claude Code Monorepo Setup: Advanced Configuration

Claude Code becomes much more useful in a large monorepo when it understands repository boundaries, build conventions, ownership rules, and the cost of loading unnecessary context. The goal is not to give it every document at once. The goal is to create a predictable operating environment where it can inspect the right package, modify only approved files, and verify changes with the correct commands.

1. Put the launch point and instructions in the right places

Run Claude Code from the monorepo root for cross-package work. Keep a root CLAUDE.md with short, durable rules: the package manager, workspace commands, supported runtime versions, test expectations, generated-file policy, and dependency boundaries. Avoid turning this file into a full architecture encyclopedia; every extra paragraph consumes context on routine tasks.

Add narrower instruction files inside major workspaces, such as apps/web/CLAUDE.md or packages/auth/CLAUDE.md. Claude Code can use the closest relevant guidance when working in that directory. This layered approach is particularly effective when frontend, backend, infrastructure, and shared-library teams follow different validation commands.

2. Make repository navigation explicit

Large repositories often contain similarly named files, vendored code, build output, and generated clients. Document the important directories and exclusions in the root instructions. Tell Claude which folders are source, which are generated, and which must never be edited manually.

Give it a small command map rather than a long narrative. For example, state that package discovery uses the workspace manifest, type checking uses the root task runner, and a focused test can be run from a package directory. Mention whether the repository uses Turborepo, Nx, Bazel, Pants, or plain package-manager workspaces. This lets Claude choose targeted commands instead of rebuilding the entire tree.

3. Use settings files to control risk

Keep shared configuration in .claude/settings.json and personal experiments in .claude/settings.local.json, if supported by your team workflow. Use permissions to allow harmless inspection and standard validation commands while requiring approval for destructive operations, broad file deletion, database changes, or publishing commands.

Do not grant blanket permission to every shell command. A safer pattern is to approve common read-only tools and repository scripts, then review unusual commands interactively. Also keep secrets out of CLAUDE.md and settings files. Claude may need instructions for obtaining credentials, but it should not receive committed tokens, production connection strings, or copied environment files.

4. Configure hooks for consistent verification

Hooks can enforce lightweight checks after edits or before a final response. In a monorepo, prefer targeted formatting, linting, and type checks based on changed packages rather than running the entire CI pipeline after every file edit. Existing scripts can calculate affected projects from Git state, which reduces both latency and API-driven iteration.

Use hooks to catch formatting and obvious validation errors, not to replace CI. A hook that takes ten minutes on every change encourages users to disable it. Keep expensive integration tests as an explicit final step and document the command Claude should run when the change crosses package boundaries.

5. Keep context focused during long sessions

Start with a narrow request and name the relevant package or service. Ask Claude to inspect the dependency graph before editing shared code. For a large refactor, split the work into discovery, implementation, and verification sessions. Summarize decisions in a temporary plan or issue rather than repeatedly pasting the entire design into chat.

Use Git worktrees for parallel Claude sessions. Each session then has an isolated branch and working directory, which prevents one agent from confusing uncommitted changes with another task. This is especially useful for simultaneous dependency upgrades and feature development.

6. Connect only high-value tools

MCP servers can provide issue trackers, documentation, databases, or internal search, but every connection expands the available context and permission surface. Add only tools that Claude needs for the current team workflow. Prefer read-only access for discovery, and create separate write-capable tools for operations that require deliberate approval.

7. Lower model costs without sacrificing quality

For routine navigation, small edits, and test explanations, use a fast, economical model. Reserve Opus for difficult architecture decisions, cross-package migrations, and debugging that requires deeper reasoning. Claude Code can be pointed at an Anthropic-compatible relay by setting ANTHROPIC_BASE_URL=https://api.59api.com and the authentication variable required by your 59API account, then selecting the available Claude model in your normal Claude Code workflow. Never place the API key in the repository or shell history.

59API is a practical low-cost option because it provides pay-as-you-go access to native-quality Claude models, including Opus, Sonnet, Haiku, and Fable, without requiring a costly fixed subscription. It is compatible with Claude Code and also supports GPT workflows through its API. If you want to reduce experimentation costs, sign up for 59API, check its current model pricing, and use the referral rebate where available.

8. Diagnose failures systematically

When Claude makes an incorrect change, first check whether the relevant CLAUDE.md was visible from its working directory. Next inspect the exact command it ran, the package boundary it inferred, and whether generated files obscured the real source. For API errors, verify the base URL, token variable, selected model, and account balance before changing repository configuration. This separation makes it much easier to tell a context problem from a build problem or a relay configuration problem.