Using Claude Code on Existing Codebases

Using Claude Code on Existing Codebases: A Safe Onboarding Framework

Every Claude Code use case falls into one of two categories: code Claude Code wrote, or code it did not. For code it wrote in the same session, Claude Code has full context. It knows the architecture, the decisions made, the patterns used. For existing codebases written before Claude Code was involved, it starts with nothing.

This gap matters more than most developers realize. Claude Code is capable of reading an existing codebase and building a working model of it. But that model is only as accurate as the files it reads, and reading files is not the same as understanding years of accumulated decisions, workarounds, and institutional knowledge.

The onboarding steps below build that context methodically, starting with the lowest-risk tasks and progressing toward more complex work as trust in Claude Code’s model of the codebase is established.

Claude Code on an existing codebase is not a shortcut to instant productivity. It is a process of building accurate context. The shortcut is knowing how to build that context efficiently.

The Core Challenge

When Claude Code encounters an existing codebase for the first time, it faces specific unknowns:

• Conventions not in the code. Naming patterns, file organization rules, and code style decisions that developers follow but never documented.
• Off-limits areas. Files, modules, or patterns that should not be modified for reasons that are not obvious from the code itself (legacy third-party dependencies, client-specific customizations, known fragile integrations).
• Test infrastructure. Which test runner, which commands, what the expected coverage level is, whether integration tests require a specific environment.
• Deployment context. What environment variables must be set, what external services the code calls, what the CI pipeline does.

A Claude Code session without this context will make reasonable assumptions. Some will be correct. Others will produce changes that technically work but violate conventions, break unrelated tests, or introduce fragility in areas the developer knows are sensitive.

CLAUDE.md is where this context lives.

Step 1: Run /init

The /init command tells Claude Code to read the codebase and generate a baseline CLAUDE.md file:

/init

Claude Code reads the directory structure, key configuration files, package manifests, and a sample of the codebase. It produces a CLAUDE.md that captures:

• The project’s purpose and stack
• File structure overview
• Build and test commands it found
• Dependencies it identified

This generated CLAUDE.md is a starting point, not a finished document. It captures what Claude Code could infer from the code. It does not capture what is not in the code: the conventions, the gotchas, the off-limits areas.

Review the generated CLAUDE.md before running any meaningful task. Look for what is missing: conventions that Claude Code would not know to follow, tests it did not find, areas of the codebase it should treat as read-only.

Step 2: Supplement the Generated CLAUDE.md

Add what /init could not infer. The additions that matter most:

Code conventions:

## Code Conventions
- Use named exports only; no default exports
- Error types must extend AppError from src/errors/base.ts
- All async functions must have explicit return types
- Database queries go in src/repositories/, not in service files

Test approach:

## Testing
- Run tests: `npm test`
- Run with coverage: `npm run test:coverage`
- Target coverage: 80% for new code
- Integration tests require: `docker-compose up -d` before running
- Avoid snapshot tests; use explicit assertions

Off-limits areas:

## Do Not Modify
- src/legacy/billing/ — third-party code with custom patches; any change breaks production
- config/production.json — managed by ops; never modify in code sessions
- src/vendor/ — vendored dependencies; update via package manager only

Known fragilities:

## Known Issues
- The UserService.getByEmail() method has a race condition in tests; it is a known issue
- The webhook handler in src/integrations/stripe.ts has untested edge cases; be careful

These additions take 20 to 40 minutes the first time. They prevent hours of debugging and revert cycles on the first complex task.

Step 3: Start With Low-Risk Tasks

The first tasks on an existing codebase should be read-heavy and low-blast-radius. The goal is to validate Claude Code’s model of the codebase before trusting it with consequential changes.

Low-risk first tasks:

• Explain how the authentication flow works in this codebase.
• Write a summary of the OrderService class and its dependencies.
• Identify all the places where we call the Stripe API.

These tasks produce no code changes. They tell you how accurately Claude Code understood the codebase from what it read. If the explanations are accurate, the model is good. If they contain errors or misunderstand key relationships, fix the CLAUDE.md before proceeding to tasks that make changes.

After read-only validation, move to documentation and test writing:

• Write JSDoc comments for the PaymentService public methods.
• Write unit tests for the UserRepository class.

Test writing is ideal as a first code-producing task because the tests are self-validating: run them and see if they pass. If Claude Code produced tests that fail due to a misunderstanding of how the code works, that is valuable information about where the CLAUDE.md context is incomplete.

Step 4: Use Plan Mode for the First Several Sessions

Every task in the first three to five sessions on an unfamiliar codebase should use plan mode:

claude --plan "add a status field to the Order model and update the relevant queries"

Review the plan before approving execution. Check:

• Which files appear in the plan. Are these the files you expected? Unexpected files in the plan signal a misunderstanding of scope.
• Whether the plan touches off-limits areas. This is the plan mode safety net for any off-limits context you added to CLAUDE.md.
• Whether the sequence makes sense. A plan that modifies the schema before the migration file, or updates the application before the database, has a sequencing problem that is easier to fix in the plan than in the code.

Once Claude Code has demonstrated accurate understanding across five or six planned sessions, you can start using auto mode for well-scoped tasks. Keep plan mode for anything touching production configuration, migrations, or security logic indefinitely.

Step 5: Keep Sessions Scoped to Single Modules

The most common mistake when starting Claude Code on an existing codebase is giving it too broad a scope too soon.

Refactor the backend to improve performance is not a task. It is an invitation for Claude Code to make wide-ranging changes across the codebase based on its own assessment of what “improve performance” means. In an unfamiliar codebase, that assessment will be incomplete.

Scoped task examples:

• Refactor the getOrderHistory query in src/repositories/order.ts to add an index hint.
• Add input validation to the three POST endpoints in src/controllers/user.ts.
• Extract the email sending logic from src/services/notification.ts into its own service.

Each of these is bounded to a specific module, a specific file, or a specific set of endpoints. Claude Code’s model of the codebase only needs to be accurate for the bounded scope. As Claude Code works more in the codebase and its model improves, broader scopes become safer.

Warning Signs

These signals indicate Claude Code is operating outside the context it has and should prompt a session pause and CLAUDE.md review:

Claude Code touches files you did not expect. A task scoped to one module should rarely require changes in unrelated files. When it does, either the scope was broader than described or Claude Code has misunderstood the architecture.

Claude Code introduces unfamiliar patterns. If code appears that does not match the conventions in the codebase, Claude Code is applying its general knowledge rather than the project’s specific conventions. Add the missing conventions to CLAUDE.md.

Claude Code asks clarifying questions about basic architecture. If Claude Code is uncertain about how the authentication system works or where the database queries live, its CLAUDE.md context is incomplete.

Use --allowedTools to restrict Claude Code’s file access when you want a hard boundary:

# Only allow Claude Code to read and write files in src/services/
claude --allowedTools "Edit:src/services/**,Read:src/**" "refactor the notification service"

Safe Task Progression

Progress through stages in order. Skipping stages on an unfamiliar codebase produces the same failure pattern every time: Claude Code makes a confident-looking change that is wrong in a way that takes hours to diagnose.

Frequently Asked Questions

How long does it take to onboard Claude Code to an existing codebase?

The mechanical setup, running /init and supplementing CLAUDE.md, takes 30 to 60 minutes. The validation phase, read-only tasks and test writing that confirm the model is accurate, takes two to four sessions over two to three days. After that, Claude Code can handle medium-complexity tasks reliably. Full confidence on complex refactors typically comes after two to three weeks of incremental usage.

Should I add the entire codebase to CLAUDE.md?

No. CLAUDE.md should contain context that is not obvious from the code: conventions, off-limits areas, test infrastructure, gotchas. Claude Code reads the code itself. CLAUDE.md supplements that reading with the institutional knowledge that is not in the code. A CLAUDE.md longer than 500 lines is usually trying to compensate for context that should be in the code itself (comments, clear naming, documentation).

What if the codebase has no test suite?

This is the highest-risk scenario for Claude Code on an existing codebase. Without tests, Claude Code cannot validate whether its changes produce correct behavior. Before using Claude Code for anything beyond documentation and code explanation, build minimal test coverage for the modules you plan to work in. A focused session, write basic smoke tests for the five core API endpoints, can establish enough of a safety net to proceed.

Can Claude Code understand a codebase it did not write?

Yes, within limits. Claude Code can read code and build an accurate model of what it does. What it cannot infer is why it does it that way, what was tried before and abandoned, and which patterns are intentional conventions versus historical accidents. CLAUDE.md is the mechanism for bridging that gap. A well-maintained CLAUDE.md on an existing codebase can bring Claude Code close to the productivity level it achieves on code it wrote itself.

Ready to bring Claude Code into your existing codebase?

The safe path is methodical: run /init, supplement what it missed, validate with read-only tasks, then progress through the stages in order. Skipping steps is where teams lose hours to hard-to-diagnose problems.

Path one: onboard Claude Code yourself. Follow the five steps in this article, starting with /init and working through the safe task progression table. The Claude Code course covers the session fundamentals and CLAUDE.md patterns that make onboarding reliable.

Path two: work with Phos AI Labs. If you want a structured Claude Code onboarding plan built for your specific codebase, including CLAUDE.md setup, safe task sequencing, and team rollout, Phos AI Labs is a CCA-F certified Claude implementation partner with experience across existing codebases in multiple industries. Thirty minutes, no deck. Start here.