You need a better harness. LLMs are significantly better at this than humans. Add it as a step in your LLM process and your documentation will always be up to date.
It encodes context it needs into doc comments and regular comments that make them in insufferable to read and so verbose because the comments contain info on other parts of the code base (that might have changed since that comment was written) but were useful to the model for its implementation. I have so far found no way to stop claude from doing this. It will sometimes do it with hand holding but the moment a task takes a slightly large amount of context its back to the word barf.
This is certainly a problem with out-of-the-box usage. But easily overcome.
Spend time updating your harness. This is not a hard problem to solve and there are many helpful guides out there.
We basically took our documented (human) SDLC process and applied it to the relevant harness hooks. Since our SDLC docs talked about what good comments looked like and what to avoid, we basically had the direction for the tools. Opus 5 did throw us a loop and increase the verbosity and decrease usefulness of the text, but refining our documentation cleared that hurdle within about a day.
