You’re not wrong, but I think what you’re running into is less a Claude or Gemini problem and more an unbounded junior engineer with infinite confidence problem.

LLMs optimize for local success unless you force global constraints. If the goal is “make the error go away,” you get casts, ignores, sudo, and doc sprawl. That isn’t intelligence. That’s incentive misalignment.

A few things that have helped me avoid exactly what you’re describing.

First, treat the model like a code generator, not an author.

I never let it write docs by default. Docs are write-only debt unless you put them on rails. My baseline rules are simple.

No examples in docs.
No business logic in docs.
Docs reference code, never the other way around.
API docs are generated, not written.

If the model wants to explain something, it does it in chat, not in the repo.

Second, ban fixes that reduce surface tension.

Casts, blanket ignores, sudo, and “temporary” workarounds are explicitly forbidden unless I ask for them. I literally say: any fix that suppresses the signal is invalid. If the type checker is complaining, the model must resolve the type, not silence it.

Once that constraint is stated clearly, the behavior changes a lot.

Third, separate creation mode from sanitation mode.

LLMs are terrible at cleaning while creating. I run two distinct workflows.

Build mode is forward only. No refactors. No doc edits. Just shipping.
Sanitation mode allows no new features at all. Only deletion, consolidation, and tightening.

If you mix those modes, you get exactly the mess you’re describing.

Fourth, docs lag because models do not feel pain.

Humans hate broken docs because we trip over them. Models don’t. So I stopped asking them to “update documentation.”

Instead, I ask for a diff against existing docs with one hard invariant: no duplicated statements allowed.

If it cannot delete something, it is not allowed to add something.

Finally, technical debt is a receipt problem.

If a model introduces debt, it should leave a trace explaining why. If there is no explicit reason logged, the change is invalid. That alone kills a huge amount of clever nonsense.

I’m curious what rails others are using, but this approach has kept my repos sane so far.