Developer shares framework for structuring AI coding agent instruction files

A developer writing for DEV Community outlined a practical method for organizing instruction files used by AI coding agents like Claude Code, after discovering their project's documentation was generating broken code. The approach categorizes content into four types: always-loaded project rules (CLAUDE.md), on-demand skill files, agent workflow definitions, and enforced hooks for non-negotiable rules. A core principle is that every fact should live in exactly one file, with others linking to it, to prevent multiple copies drifting out of sync over time. The author found real problems in their own docs, including styling patterns that produced mismatched class names and test templates that silently failed due to conflicting mock setups. They recommend validating documentation by grepping the codebase to confirm examples actually exist in practice, and running retrieval tests using a subagent given only the docs to check whether it can answer real implementation questions accurately.