As I read (and appreciate) your documentation tips, I don’t even think they have to be labeled as AI-specific! ‘CLAUDE.md’ seems likely it could just as be ‘CONVENTIONS.md’, and comments to ‘AI’ could just as be comments to ‘READER’. :) Certainly I would appreciate comments like that when reading _any_ codebase, especially as an unfamiliar contributor.
Not the OP, but in practice, the comments that tend to help Claude tend to be very different from what helps humans. With humans, I'll generally focus on the why.
Our style guide for humans is about 100 lines long, with lines like "Add a ! to the end of a function name if and only if it mutates one of its inputs". Our style guide for Claude is ~500 lines long, and equivalent sections have to include many examples like "do this, don't do this" to work.
