I have this problem even in codebases. Claude will work on something, and add detailed comments in which it extrapolates the from the design and confidently states intentions and decisions which aren't actually grounded in reality. Then, later sessions suffer when it reads back those hallucinations and treats them as canonical.

Delete the comments: I’ve gone on a tear with these recently because they’re nothing but trouble.

The absolute least worst outcome is they chew up your token budget. But what tends to happen, and this is much more serious, is they poison future work and make further modification of the codebase more burdensome and error prone.

I've been whittling my way towards having Claude write zero comments in code. They're pretty much never helpful.

We have this in our harness markdown:

```

## Comments

Use comments extremely sparingly. Most comments should be at the request of the user. When something warrants a comment, keep it to one or two lines: what the code does and why it's necessary. No background narrative, no replaying the investigation or failure mode, nothing a test name or the commit message already says. Applies to specs too. If a comment needs a paragraph, make the code clearer instead.

```

The comments Claude was leaving got absolutely out of control. Just lines and lines of LLM drivel that was barely intelligible and not remotely relevant to what a code comment should be used for.

I've had codex delete useful (albeit not directly relevant or perhaps messy wip notes) comments, even though I explicitly have it in my agents.md not to delete comments, and ask for permission if it thinks it should.

It deleted the comments, and when I asked why it did that even though I expressedly asked it not to, it responded that me prompting it in the first place explicit permission. I have no idea if that's the actual reason or just some post-hoc explanation.

But I genuinely don't think it's possible to just have these things be completely, 100%, indpenedent and also solve deep problems that need to also be understood by people in a people-based organization context.

My approach is to keep the comments only with a references. My LLM based projects always have the decision log where are my decisions while working on the features are stored with the date. I found this useful to actually trace why something is in the codebase. It's much easier for both me and the LLM to navigate through the big projects where I spent months and dozens of full night sessions executing my plans with --dangerously-skip-permissions. In the morning I was answering all the model questions and iterating like that. Honestly, try that.

Probably good to establish canonical spec documents up front that it can use and maintain as an independent reference?

Anthropic hopes you just eventually give up and become completely dependent on Claude. Toss in 10 (or more) other developers with way less discipline and you will become dissillusioned with Claude's overengineered, incomprehensible, technosalad and your demise is pretty much guaranteed.

[dead]

[flagged]