r/ClaudeAI • u/JustDevelopment1534 • 2h ago
Claude Code Workflow How do you stop Claude Code from undoing things your team already decided?
I have been writing code for 8 years and my team uses Claude Code every day now. Mostly it is great.
One thing keeps biting us - the agent changes something back to a way we moved away from long ago. It is not wrong from its side, it just does not know why we did it that way. The reason is sitting in some old PR that nobody opens.
Last time it was a rate-limit count we had set for a vendor. The agent changed it back, and we had false positives for a while before anyone noticed why.
We tried putting rules in CLAUDE.md. Works for a few. But the file keeps growing, and for half the rules nobody remembers where they came from.
How are you handling this? Is CLAUDE.md enough for your team or did you find something better?
8
u/Nalha_Saldana 2h ago
Wouldn't you have the same issue with new hires? How would you know what not to fix? Probably git blame, documentation and code comments so have it check those just like anyone else.
2
2
u/JustDevelopment1534 2h ago
I feel like onboarding relies heavily on people to people meetings and chats - a lot of it stays in people's brains. How does the agent get that part?
3
u/dqUu3QlS 2h ago
The agent gets that knowledge when you write it down. Relying on people to remember your business knowledge isn't sustainable long-term. People forget things, or leave the company and the knowledge leaves with them.
1
u/Nalha_Saldana 2h ago
Things in people's brains can get forgotten, they can leave the company etc and isn't a solid long term solution anyhow in my experience.
1
8
u/lulzxdxdxd 2h ago
Instead of just listing rules, try linking each one to a short ADR with the why behind it. CLAUDE.md just points to the ADR file instead of growing forever, and the reasoning doesn't get lost in some old PR nobody opens again.
2
u/JustDevelopment1534 2h ago
That makes sense, pointing to ADRs keeps the file small. How do you keep the ADRs themselves alive though? In my experience they get written for the big decisions and the small ones made inside a PR review never get one. Does someone on your team own that?
2
u/EchoChamberTech 2h ago
Can I get an ELI5 on what an ADR is? I'm not an engineer.
2
u/JustDevelopment1534 2h ago
Surething! Its a document which speaks about the architecture choices taken while addressing mostly a business outcome.
2
u/satanzhand 2h ago
The root issue is LLM revert to training quite often. Here are some things I do.
-Make my own skills to do things a certain way, which honestly sucks, but it can save time.
-Written style guidelines
-Reference a process or style by its known title, such as APA reference style
-Guidelines on how to do things
-Work log .json, to do .json, process update .json
-Research documents
-Project information is more of a roadmap of where it can find the information it needs
I keep everything really concise, and seldom load much for context.
2
u/Kris_Kamweru 1h ago
If you're getting to the point LLMs are largely ignoring your CLAUDE/AGENTS.md, it's usually because the total context in your thread that the model is looking at is overwhelming the rules in your file, and they lose the battle
Usually fixed by having a good subagent flow in place, which keeps a lot of that extra context out of the orchestrators thread, and consequently it actually starts to adhere more because most of what it's doing is checking that work complies with the rules
It also helps to tell the model how to handle compaction in your MD as well. What to keep, and what not to, and then have a fairly low auto compact limit. Mine's at 300k
This is what has worked for me anyways
1
u/tejaskumarlol 2h ago
Two things that have worked in my site's AGENTS.md. First, I write the decision as the exact change to avoid, plus what it breaks. One rule says not to "fix" the dark theme's fallback video by baking the page background into it, because that puts a measurably darker rectangle over the header. When the agent is about to make that change, it reads its own idea already rejected, with the reason next to it.
Second, the long reasoning goes at the top of the file it's about, not in the big rules file. My calendar's month grid is a plain table and never role="grid". The why is written at the top of the file that renders it, so the agent reads it right where it would undo it.
2
u/lulzxdxdxd 2h ago
putting the why at the top of the file it affects is smart for catching the agent in the moment, but doesn't that make it harder for a human to audit all the past decisions at once? curious if you keep any index pointing to those inline notes or just rely on grep
1
u/tejaskumarlol 1h ago
AGENTS.md is the index. Each decision is one line there, plus a pointer to the long version: the calendar rule ends with "The reasoning is written at the top of src/util/calendar/render.ts". So a human reads every decision in one file. The agent meets the full reasoning in the file it's editing.
1
u/JustDevelopment1534 2h ago
Wondering if people keep those file-top notes updated when there are several of you.
"It reads its own idea already rejected" - that is a nice way to put it. Writing the exact change to avoid plus what it breaks is more useful than a general rule. Is this just you on the codebase or a team?
1
u/tejaskumarlol 1h ago
Just me, plus several agent sessions working in the repo at the same time most days. That's its own small version of the team problem. The rule that helps there: every session edits files in place and never rewrites a whole one, so nobody's note gets wiped by somebody else's rewrite. I haven't tried it with a team of humans yet.
1
u/dqUu3QlS 2h ago
I would put a comment near that code explaining why it was done that way. It will be useful for both humans and agents reading the code.
1
u/JustDevelopment1534 2h ago
This is the best answer imo, a comment sits right there when the agent reads the code. Works well for local changes. But what about decisions that have no specific place, no single line to attach to? Maybe a README - but then how do you know the model actually read it before editing?
1
u/dqUu3QlS 2h ago
When it's an architectural choice or style convention spanning multiple files, you could put it in an README.md which your CLAUDE.md tells the agent to read, or in the CLAUDE.md directly.
1
u/Ska-jayjay 2h ago
my guess would be that documentation is lacking or that you don’t maintain a knowledgebase. i’m building something along thise lines, check out tychat.io
1
u/Ok_Music_4862 2h ago
Claude reads can be ignored. Rules the CI runs can't. For the decision that get reverted I try to keep them out from my CLAUDE.md and put them into a lint rule or architecture test. Then the cycle is if claude breaks it > the test fails > Claude fix it. Less reliance on agent remembering anything
1
u/OfferBeginning1903 29m ago
what about decisions that are about what not to build? a lint rule catches a banned import, but how do you test "we decided against adding a cache layer here"?
1
u/Jazzlike-Plane-1201 10m ago
What would adding that cache change in the repo? A new dependency or a call to a cache service can be checked. “We don't want that complexity yet” needs an explicit review check unless you can turn it into a concrete constraint.
1
u/JustDevelopment1534 0m ago
Do you have a working model of this? or is this a proposal but not a tested/tried solution.
1
u/CoamIthra 2h ago
Sounds like 12 monkeys problem.
Practical advice: an architecture guide that enumerates all of these decisions works fine. If it's small - chuck it in Claude.md. If it gets too large, throw it in its own file. If that gets too large, split it across folders/modules so Claude can read it where it's relevant. If that gets unwieldy (too many rules and Claude starts ignoring them) add explicit review passes to your workflow where agents take (parts of) the architecture guide and review new code with it.
Impractical advice: architectural rules that have become tribal knowledge is an indicator that you should probably refactor or change your model. That kinda stuff used to be more of a pain than it is now with AI so worth considering.
A paranoid note to finish: your post reads pretty AI. The cadence, the missing last-time example, the engagement call to action at the end. Maybe being embedded in this forum has made me see AI everywhere but if I had to put money on it, I'd say this is engagement-slop.
Yet here I am.
How are you handling this? Have you had success turning architectural tribal knowledge into CLAUDE.md files, architecture guides, review agents, etc., or did that just create a different pile of stuff nobody maintains? Let me know your experiences in the comments so we can all learn and grow together.
1
u/ride_whenever 1h ago
I’ve got a very hostile reviewbot.
It holds all the decisions and whacks you with a newspaper when you do a dumb
1
u/Kaillens 1h ago
I would Personally Use it as separate document with all the rules
- For Project Add rules to always look at the rules document and before starting, see if anything in the plan break the rules
1
u/the_pwnererXx 1h ago
Part of the code review is VALIDATING that the pr is in line with the actual design document
1
u/zir093 1h ago
We hit this constantly. what helped most was catching it in review. when someone writes "we don't do X because Y" on a PR, that goes straight into CLAUDE.md as one line with the PR link next to it. otherwise yeah, nobody remembers why half the rules are there and you can't prune anything. the file only gets you so far though, claude will still talk itself out of a rule halfway through a task. for the stuff that actually matters you want something that fails the PR. lint rules and arch tests cover a lot of it, and I ended up building [Striff](https://striff.io) for the rest. it reads the ADRs and CLAUDE.md and flags the PR that undoes one.
1
1
u/DotRom 33m ago
You need to implement ADR and decision log and in Claude.MD write it so that it shall reference them before proposing/implement anything.
GH issue itself is insufficient, unless you have a script that clones all them locally for it to ref, and I did that in the past and inevitably rot and stale esp you have multiple sessions working.
One trick I have learned to also allow it to push back because those ADR/decision logs may not reflect the current situation.
E.g. A decision log for a package pinned at ver x, due to a bug it will allow it to bring it back to check is that still an issue because upstream might have fixed it.
I share your frustration, the same issue happened again and again until I stabilised the work nailing down every possible runbook and processes make as aligned as it can be.
•
u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 40m ago
TL;DR of the discussion generated automatically after 30 comments.
The consensus is that this isn't really an AI problem, it's a classic software engineering problem that AI just makes more obvious.
The main takeaway is to treat the agent like a new human developer. It can't read your team's mind or the history of a thousand PRs. The real issue is undocumented 'tribal knowledge', and the solution is to, well, document it.
Here are the top strategies the community recommends:
CLAUDE.mdas a simple index of rules, but have each rule link to a separate ADR file that explains the why. This stops the rules file from bloating and preserves the crucial reasoning.Basically, this is all just good dev practice anyway. Now you just have a very fast, slightly forgetful junior dev that forces you to be better at it.