How I Run a Client's Kotlin Codebase with Claude Code

Context-switching between client codebases costs me more than the switch itself. Every codebase has its own conventions, its own architectural decisions, its own landmines. Re-loading the mental model of someone else's system can eat 30 minutes before I have touched a line of code. Claude Code with a proper setup deletes most of that cost. Here is the exact workflow I run on a client's Kotlin Android codebase.

The CLAUDE.md file

Every project gets a CLAUDE.md at the repo root. This is Claude's onboarding document, the thing it reads before touching a line of code. For a Kotlin Android codebase, mine covers the stack (Jetpack Compose, ViewModel, UseCase, Repository, and which patterns are enforced), the architectural constraints ("no business logic in Activities", "all network calls go through Repository"), the naming conventions, the off-limits modules that need a PR review before any change, and the key decisions with their rationale.

The file lives in my vault and is symlinked into the client's repo. It is never committed to their git history. It is my working document, and the client's codebase stays clean. A single line in that file can save an hour of debugging.

Session start: three minutes to full context

Before I write anything, I load context in a fixed order: read the project's CLAUDE.md, read the active task file (what we are building, what done looks like, what it blocks), then read the last session log (what changed, what decisions were made). By the time I run the first build, both Claude and I are oriented.

On a long engagement, three months or more, this compounds. The CLAUDE.md grows. Session logs accumulate. Claude's context gets richer as the project matures. By month three it is catching things that would have taken me real investigation time in month one.

Plan mode before touching production code

For any change that touches more than one file or involves an architectural decision, I use plan mode. Non-negotiable. Ask Claude to propose an approach, review it, then ask the one question that earns its keep: "What is the strongest argument against this?" If the critique lands, revise. If it does not, proceed.

A concrete example. On a recent engagement I was implementing persistence for a P2P sync layer on a client's Android codebase. The obvious approach was to route it through the existing storage abstraction. Already battle-tested, less new code to maintain. In plan mode, Claude flagged a threading constraint documented in the project CLAUDE.md: the storage layer had a single-writer policy that would cause contention under the concurrent sync scenarios we were building toward. We redesigned before writing anything. Thirty minutes in plan mode, not a debugging session after the fact.

A wrong approach in plan mode takes five minutes to fix. In code review, an hour. In production, you already know.

What goes in CLAUDE.md

The file gets better over time. The first CLAUDE.md for a new project is 20 lines. After three months of real work, it is 300 or more, and each entry represents a problem that will not happen again.

The prior-decisions section is the one that pays for the whole file. It prevents relitigating problems you already solved.

Session close: the log habit

Every session closes the same way. Update the task file (what was done, what is next, what was decided), sync the project index, and write a session log entry. The next session starts by reading that log. No archaeology, no "wait, where did I leave this."

This matters most on engagements where I work one day per week for a given client. Without session logs, the first 30 minutes of every session is reconstruction. With them, it is three minutes of reading and I am in the problem.

The difference in practice

Most developers use Claude to write code faster. That is a legitimate use case. I use it to catch constraint violations early, because plan mode surfaces documented rules I have forgotten. I use it to hold context across sessions, because logs and task files mean no re-orientation cost. And I use it to improve over the engagement rather than degrade, because the longer we work together the more context the agent has and the fewer mistakes it makes. The result is not autocomplete. It is closer to a second engineer who read all the docs and is still holding them in working memory.

Where to start

You do not need the full vault setup to get value from this. Start with the core four.

That is the core. The rest layers on top when you are ready.

Same idea, one level up: The Claude Code Router Pattern is about keeping the agent's ambient context cheap once your setup grows. This post is about giving it the right context in the first place.

If you want this running on your own codebase without the trial and error, that is what I do. Set up Claude Code for your codebase and I will build the CLAUDE.md, the task structure, and the session rituals with your team.

Gabe Giro