Comment by giancarlostoro
7 days ago
> The biggest usecase for AGENTS.md files is domain knowledge that the model is not aware of and cannot instantly infer from the project. That is gained slowly over time from seeing the agents struggle due to this deficiency.
This. I have Claude write about the codebase because I get tired of it grepping files constantly. I rather it just know “these files are for x, these files have y methods” and I even have it breakdown larger files so it fits the entire context window several times over.
Funnily enough this makes it easier for humans to parse.
My pet peeve with AI is that it tends to work better in codebase where humans do well and for the same reason.
Large orchestration package without any tests that relies on a bunch of microservices to work? Claude Code will be as confused as our SDEs.
This in turns lead to broader effort to refactor our antiquated packages in the name of "making it compatible with AI" which actually means compatible with humans.
In my opinion it’s not just compatible with AI its code that now fits in your head. Lots of famous “we can rewrite it later” remarks throughout my career… Well the AI can rewrite it, and now you can understand it.
Always make it write out a plan, write out unit tests that match the codebase as-is, and if adjusted are only changed in how they call the code in the future, giving you confidence that the rewrite didn't break core logic.
Why is that a pet peeve, though? Seems like a win/win.