As humans and agents read through the docs, several READMEs or other markdown files are consistently wrong or out-of-date. This can steer the LLMs into amplifying bad patterns. (garbage in, garbage out).
Examples I remember:
#790
#835
#769
This is somewhat related to code churn: it's low value to write a README for areas of the codebase that are high-churn (example: listing directory contents). It's much higher value to document low-churn, higher-level principles that change slowly (if at all).
Two approaches here:
- "stop the bleeding" one-time pass to fix all the issues (see this skill as inspiration)
- Edit CLAUDE.md to stop Claude from writing brittle things into individual README Markdown files, and treat the code as authoritative in areas where it makes sense (ie, don't AI-generate a list of files in a directory into a Markdown file).
As humans and agents read through the docs, several READMEs or other markdown files are consistently wrong or out-of-date. This can steer the LLMs into amplifying bad patterns. (garbage in, garbage out).
Examples I remember:
#790
#835
#769
This is somewhat related to code churn: it's low value to write a README for areas of the codebase that are high-churn (example: listing directory contents). It's much higher value to document low-churn, higher-level principles that change slowly (if at all).
Two approaches here: