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???
The proliferation of prose is maddening
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???
The proliferation of prose is maddening