The README Trap: Why AI Coding Assistants Skip Your Docs (and 3 Fixes)

Here's a pattern that will sound familiar: you carefully write a README with architecture decisions, API conventions, and setup instructions. Then you ask your AI coding assistant to implement a feature. It generates code that contradicts half the decisions in your README because it never read the file. This isn't a Claude Code bug. It's a workflow design problem. And once you understand why it happens, the fixes are straightforward. Why the README Gets Skipped AI coding assistants operate on context. They see your current conversation, the files you've explicitly opened or referenced, and whatever system instructions are configured. They don't proactively scan your entire repository on every prompt. This is actually reasonable behavior — reading every file in a large repo before answering "fix this typo" would be wasteful. But it means architectural documents, style guides, and READMEs only get read when explicitly referenced. The result: you end up with code that works but violates c