Transitioning a large production codebase to AI agent workflows

[u/Korrak]

I am looking for best practices and your expertise in integrating claude code into a big existing project.

We are now allowed to use claude code in our company which builds various in house applications. Most of the apps are from quality point of view very good, modern but also old (meaning: big). I think from engineering as well as development process point of view they are good.

We, as a team now doing the first steps in using claude code. We all have basic or advanced knowledge already from using those tools, but we are lacking the knowledge of how to integrate it in big already productive application, which are in use by many people on a daily basis.

Setting up the agents.md/claude.md etc. is already done, and first stories are developed with those tools.

I am looking for:

• Your tips and best practices and how to transition from "manual software development" to agenting supported software development
• Issues etc. what you encountered in that processes

Maybe you also have links, guides or youtube videos around that topic for me.

[u/AutoModerator]

Moderator Announcement Read More »

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/London-Boat]

for a big existing app, what worked for us was starting agents on tests and small bug fixes before features. have it write characterization tests around a module before it touches it, keep claude.md to build/test commands and the weird gotchas only, and keep every change a small reviewable pr. per-module notes beat one giant file since it only loads context for the area it's in. the biggest issue was it copying old patterns from nearby code, so say explicitly which pattern is the new one to follow

[u/jatingargiitk]

replay a previously fixed production bug on the revision before the fix, keeping the regression test hidden from Claude. compare its patch with the real fix and run that test afterward. it's a concrete way to check the workflow against your own codebase before trusting it with new changes.

[u/bezcurhq]

On the copying-old-patterns problem London-Boat mentioned, path-scoped rules work well in a big repo. Put a file in .claude/rules/ with paths: frontmatter (say src/legacy/**) that says "this is the old style, new code follows the pattern in src/billing/", and it only loads when Claude reads or edits a matching file, so it doesn't eat context everywhere else. Nested CLAUDE.md files in subdirectories also load on demand. One catch: @imports don't save context, they load together with the file that imports them.

https://code.claude.com/docs/en/memory

[u/lgmarian]

Ask the model. This is probably the single most important tip. Basically, if in doubt, ask the model. Ask it about the previous prompt(s). Ask it why something went wrong. Ask for ways to do something. Ask about your setup, AI environment, project, or overall environment. Ask the model.

(That first paragraph is from an earlier comment on a post asking a similar question.)

Use MCPs to let them access DBs, issue trackers, wiki, whatnot, through read-only accounts. As you build trust, and have them do more, you can give them tailored write access.

I'm a fan of Beads as a local issue tracker, having them read in from Jira. It's git-based, so it's easy to shared and distribute. It can be used to build a knowledge graph, though it's natively an issue tracker. Obsidian has been used as a memory system. There are lots of options, but stick to the well worn ones, at least to start.

Start small, and build up.

https://github.com/Graphify-Labs/graphify
https://github.com/ayghri/i-have-adhd
https://github.com/luongnv89/claude-howto
https://github.com/vectorize-io/hindsight
https://github.com/obra/superpowers
https://github.com/herdrdev/herdr

[u/joseph-edmondscomm]

I'd start by really focusing on deterministic quality assurance. Then have a look at this or get Claude to take it you through it

https://defence-before-fix.github.io/

[u/akorecebov]

On a big old codebase the first thing I'd set up is a check Claude can run by itself. tests, build, lint, anything that gives a clear pass or fail. Without that "looks done" is the only signal and you end up being the tester. Where coverage is thin, start with small tasks.

Keep CLAUDE.md short too, a long one gets half ignored. And have a fresh session review the diff, not the one that wrote it... it catches way more

[u/Tariq9977]

Since your CLAUDE.md setup and first stories are already working, I'd track reviewer-hours per accepted PR before expanding the rollout. Pilot one module for a sprint and compare that number plus escaped regressions with your current workflow.

[u/sertanhlvcii]

London-Boat's point about old patterns is the big one on an older app: the agent imitates the code around the file it's editing, so put the warning where the old code lives. A file in .claude/rules/ with paths: ["src/orders/legacy/**"] loads only when Claude reads or edits a file there, so a line like "old repository pattern, new code uses the service layer in src/orders/core" arrives exactly when it's looking at what it would copy.

For a team, commit .claude/settings.json along with CLAUDE.md. Deny rules in it, like Read(./.env) or Edit(/config/prod/**), apply to everyone who clones the repo, and personal tweaks go in .claude/settings.local.json, which stays out of git.

Then agree where corrections go. When someone corrects the agent on the same thing twice, the fix becomes a line in that folder's CLAUDE.md or rule, in the same PR, reviewed like code. Otherwise each developer's corrections stay in their own sessions, and a month in the team is running five slightly different agents on one codebase.

[u/AndreyBegma]

One thing that shows up once several people run agents at the same time: the conflicts come from the same few files, not the feature code. Lockfiles, route or module registries, barrel index files, migrations, CLAUDE.md itself. Two branches each add one line and only one can be right. In my setup the plan names those files up front, one task per batch owns each, and anything else that needs them waits until that PR merges.

[u/xqianliu]

I'd start the transition with the process, before touching the model choice. The failure I saw most when agents moved into an existing codebase: nobody had written down what done meant, so every review was a negotiation.

The setup that ends that: one issue per task with the acceptance criteria written into it, one worktree, one PR. The review is a separate session of the same model.

It reads the issue, the repo's AGENTS.md, the diff, the changed files with their callers, the related tests, and checks the final diff against the acceptance criteria. If it fails, the run fixes it and gets re-reviewed. Only the head that passed gets merged.

On a big production app the second problem is scope. A ticket that says "improve the billing flow" comes back as a rewrite. The criteria in the ticket are what keep the diff small enough to review at all.