Please for the love of god, quit generating markdown files (especially having the LLM generate the file, because if it could generate it, it doesn't need it), quit generating "decision" docs, and stop having more comments than code.
> Please for the love of god, quit generating markdown files (especially having the LLM generate the file, because if it could generate it, it doesn't need it), quit generating "decision" docs, and stop having more comments than code.
I agree with all of this. But I disagree that code alone is enough to understand the why.
Yeah, I'm being a little extreme here and conflating a couple things.
You absolutely need some documentation. Like I originally said, I still do keep a claude/agents.md too, they're just stripped down A LOT.
Human maintained knowledge base and documentation is good. Not even 100% human maintained, just make sure human eyes are reading it before you commit it! And if it's said in code it doesn't need to also be said in the docs, that's how they get stale and you get drift. This is causing LLMs problems.
The docs you don't need are big decision docs that keep getting appended to, multiple long lived markdown files, and verbose comments (I literally saw multiple MRs today with more lines of comments than lines of code, as bad as one file that had a single line changed but then 5 paragraphs of mostly unrelated details, overly specific details, and just plain claude slop). This stuff isn't helping.
And the one issue I'm mainly conflating this with are all the skills/plugins/etc that people are making thinking it's making their claude better. Like the super-powers repo that's been floating around for months, that thing is trash, you don't need it. Maybe you did before (I still don't really think so) but you especially don't need it now.
One guy is talking about running tests and parsing json with claude... but why would you even do that? Just make deterministic tools and then you run those for your testing.
Again, something else I'm seeing, someone wedging claude into ci/cd and then having claude use skills that run linters and trivy. Why is that not just in ci/CD???
When it's not, there are commit messages.
Please for the love of god, quit generating markdown files (especially having the LLM generate the file, because if it could generate it, it doesn't need it), quit generating "decision" docs, and stop having more comments than code.