Documentation Is Not an Agent Guardrail

Documentation alone is insufficient as a safety mechanism for AI agent-written code. While skills and architecture guides provide useful context, they are advisory — agents can read rules and still violate them. The post argues for a layered approach: explicit architecture (Redux-style state, pure reducers, sagas, thin components) makes wrong code structurally hard to place; executable guardrails (ESLint rules, CI checks, import boundary scripts, type checks) enforce mechanical boundaries after code is written; documentation explains the 'why'; and human review handles judgment calls. Concrete examples show how seemingly working code — API calls in components, non-serializable state, reducer mutations, cross-feature internal imports — creates architectural debt that scripts can catch cheaply. The key insight is that agent-friendly codebases favor verbosity that exposes intent over concise implicit reactive patterns, because explicit architecture gives agents searchable, testable, enforceable handles.