How clear repository conventions help AI coding agents avoid costly mistakes

AI coding agents can produce plausible-looking code changes that still violate architecture boundaries, duplicate components, or skip critical checks when repository conventions are unclear. The proposed solution is not better prompts but a codebase whose structure, ownership rules, and checks are explicitly documented and testable. Each directory should carry a defined ownership rule — for example, routes handle transport, services handle product logic, and data layers handle persistence — so any violation is easy to spot during review. A root README should list real, working commands for installation, testing, linting, and migrations, along with prerequisites, rather than generic or aspirational documentation. When boundaries are legible and each layer has a single reason to change, agents and human contributors alike can locate the right starting point quickly and limit the scope of any modification.