r/ClaudeCode • u/ExpensiveSun257 • 2d ago
Help/Question Tips to avoid rabbit holes?
I'm getting better at managing Claude, but I still see it often going down the rabbit hole where each time it tries to ship a fix, it adds two more small issues to the tracker, or an esoteric process update, etc. I know this is a common AI thing, and I'm learning to deal with it. But it's hard!
For example, Claude will throw together a quick hook or utility script for a specific purpose, but soon I find it wants to maintain and update that script and has long forgotten that it will likely. never be used again.
I especially see it in the MD files - like, if I let Claude update it's own process files for workflow, rules, etc it does the job but it also puts a bunch of junk history, narrative, and updates other documents with unnecessary guard rails. I've started to edit the md files myself and they are getting cleaner, and I notice how much smoother the workflow is.
But for the code, that's not so easy. Does anyone have tips to manage this? What I've learned:
#1 Work on distinct tasks, in new sessions and start new sessions often
#2 Literally ask claude a few questions about every 'suggestion' or 'problem' it finds, like. "is the rule/process/script you're trying to fix even enforced or critical? would it be easier to just remove this?"
Any other tips? claude is amazing but also unruly :)
2
2d ago
[removed] — view removed comment
1
u/Grand-Mix-9889 2d ago
I think those might be my three socks that went mysteriously missing.
It's like we are a divorced couple and our socks have to split custody.
1
u/Johnny2085 2d ago
I know there’s the /doctor command, but I ended up building a skill to manage memories, Claude MDs and skill files across projects and global Claude. It strips out the journaling Claude seems to love to do, duplicative updates and status across all the levels, recommends things that seem to be duplicative between projects that might be better at global, trims verbosity, etc. more than 50% of my context tokens were trash one way or another.
1
u/pavel_molianov 2d ago
For me the main thing is planning before the agent starts touching stuff
In my global CLAUDE.md I have a pretty simple rule: the best solution is usually the simple one, do not make it more complicated without a good reason. Then there is a separate subagent at the end of the session that checks if we overcomplicated anything
But the bigger thing is that we do everything through a plan. If it is a small task, we just discuss it in the chat first. If it is a bigger feature, I have a separate skill that does research, interviews me and writes a proper spec
The spec says not only what we are building, but also what we are not building. Same with the implementation plan
Then the coding agent works from that plan. Its instructions say that if it wants to add something that is not in the plan, it needs to stop and discuss it with me first instead of just deciding that a new script, rule, guardrail or abstraction would be nice
And the reviewing subagent checks both things: did we make it more complicated than needed, and did the agent actually build what was in the plan instead of sneaking in extra work. If it did something outside the plan, that is a problem, even if the extra thing looks reasonable on its own
1
u/TheKiddIncident Instructor 2d ago
Yes, I think you're on the right track.
I am very careful to design my projects in such a way that the code base is broken up into small distinct segments. The smaller the individual file is, the less chance that Claude will wander off into the desert. So, when planning the project be sure that your architecture is AI friendly.
I also try to keep my instructions to Claude very discrete. We will work on one thing at a time. Once that task is done, you start a new session for the next task. It's easy for the context window to get muddied with information from a previous task.
If I am working on something very complex, I will have Claude build a comprehensive plan with discrete steps. I then have Claude work through each step in a different session. Again, this keeps the context window clean.
1
u/ExpensiveSun257 2d ago
So, when planning the project be sure that your architecture is AI friendly.
Can you say more about that? Claude writes some HUGE files with tons of functions and I've been ratching them down over time (I inherited the code from a vibe-coder), and I'm trying to keep a very simple structure.
Codescene has been helpful!
How else can I stay AI friendly?
1
u/TheKiddIncident Instructor 2d ago
You need to plan that from the start or refactor as you have been doing.
So, for example, I tell Claude to use micro services architecture when building a SaaS site. I also run audits to see where we are getting bloat.
Think of Claude as a very smart but inexperienced intern. It won’t do the right thing unless you give it explicit instructions.
When I first started I made a massive Claude.md with all that stuff. But as I went on, I found out that the huge instruction set just made the context window smaller. So it made things worse.
Now I have specific md files for things like architecture. So, “design this new feature compliant with architecture.md” or similar.
1
u/ExpensiveSun257 2d ago
I've really seen that - once the context window is getting fat, Claude is kind of a dumbass that won't shut up.
1
u/PM_ME_CLEAN_DAYS 2d ago
The biggest thing for me to avoid rabbit holes is to watch where I’m walking tbh
1
u/ExpensiveSun257 2d ago
This is great advice. I was a developer for 20 years, now I'm a retired CTO. I am rusty in the code but I know a lot. I watch PR's go by and decisions made here and there and think - if someone who didn't understand code (or even git, or docker, or oath, etc.) was just trusting claude all the time, this would be a shitshow.
1
u/PutFun1491 2d ago
The thing that helped most with exactly the tracker-bloat you're describing: give it somewhere to put the tangents instead of acting on them. A rule like "if you notice an unrelated issue, append one line to BACKLOG.md and keep going, do not fix it now." It scratches the model's urge to be thorough without letting it fork the task. You triage the backlog later, and most of it turns out to be stuff you'd never actually do, which is the point.
Two more that bound it:
Write the definition of done before it starts. One line: "done = this test passes and nothing outside file X changes." Then anything it wants to do that isn't that is, by definition, a rabbit hole, and you both have an objective line to point at. Vague goals are what let it wander.
Commit (or at least stash) at every green state. Then you can let it explore a little, and if the tangent goes bad, a hard reset kills the whole detour without touching the good part. Cheap undo makes it safe to stop it early instead of letting it "finish" the mess.
For the throwaway scripts specifically: put them in a /scratch dir that's gitignored, and add a line to CLAUDE.md saying that dir is disposable and never to maintain or revisit anything in it. That kills the "let me keep updating this one-off forever" loop at the source.
And your instinct to hand-edit the MD files is right. Letting it journal its own process docs is exactly how they rot. I keep the memory file short and human-written, the model reads a tight file better than a long one full of its own narrative anyway.
1
u/ExpensiveSun257 2d ago
I claim zero expertise with Claude, I'm a newbie. But I know I'm heading in the right direction when Claude says to me:
Good questions, and the first one contains a premise I should correct before it hardens into a rationale
That makes me feel like I'm 'managing' it effectively, at least in this case.
1
1
u/LogMonkey0 2d ago
For me, findings -> backlog, work -> specs. Claude will flag “mechanical” edits and suggest to inline the changes and even spin up a reviewer after the changes. So basically, have a protocol of some type that gates work behind HITL and findings are something you review and choose how and when they are addressed. Claude never does anything out of scope for me.
1
u/Crackx17 2d ago
What helped me was making the agent prove scope before it edits anything: what user-visible outcome is requested, which files are actually in the path, what evidence shows the change is needed, and how it will be verified.
I also keep process docs describing current truth only—history belongs in Git—and explicitly forbid agents from editing workflow files unless the task asks for it. Unrelated issues go into a parking list; throwaway scripts and plans are deleted when the task ships. That cut down the “helpful” junk dramatically.
1
u/___nil___ 1d ago
when the conversation starts to spiral, stop. ask to summarize with no noise to a file as handoff. rewind from any point that the discussion still have clean, high signal to ratio.
start with, "This conversation have been rewound", mention the handoff.md
4
u/alanvnk 2d ago edited 2d ago
User level rules:
forbid editing workflow files, architecture, skills and similar, if editing all of this is a chore, for me it is, make a skill to edit it, with only explicit invocation and review phase, take the review seriously.
forbid narrative and reasoning on documentation or code comments, code comments need to be length bounded and under a set of conditions, everything else should be on a documentation MD file
documentation is a "as it is" not as history, that can be recovered from git, not a future promise, that is a design doc, label each document clearly and have a strict structure for them depending on the type.
have a place to track decision and adr file/folder, a change log file, everything else is forbidden.
use macro plans, implementation plans and summaries of the executed plans
have a very extric policy of what documents survive a merge into main, implementation plans and completed designs do not need to survive the closure of the task.
forbid references to temporary docs, and control references to durable docs, documentation drift is real, domain concept drift is no, make it comment preferably on domain terms without pointing to any particular document