The Repo Is the Context: Why Agents Don’t Need History

Short summary

Coding agents should prioritize reading the current repository state—schema, APIs, tests, config—over historical documentation. While ADRs and specs help humans understand why systems evolved, agents editing present systems face drift risk when facts exist in multiple places. The solution: encode architectural rules structurally using ESLint, TypeScript, and package.json exports, so documentation points to sources of truth instead of restating them.

• •Agents need current system state, not historical evolution paths
• •Documentation drift occurs when facts exist in multiple places without conflict markers
• •Encode rules structurally (config, linting, exports) rather than in prose to prevent drift

Generated with AI, which can make mistakes.