The ten principles: locality, contracts, quarantine
The article outlines ten principles of software architecture organized into three clusters—locality, contracts, and quarantine—designed to optimize codebases for AI agents as primary readers. These principles aim to reduce re-derivation costs by making code more predictable, self-documenting, and isolated. The framework emphasizes co-locating feature-related files, using explicit contracts, and containing exceptions to improve machine readability.
- ▪The three clusters of principles—locality, contracts, and quarantine—address where code should be findable, how truth is encoded, and where exceptions are isolated.
- ▪Features should be organized in directories containing co-located implementation, test, and specification files with parallel naming for easy discovery.
- ▪Explicit import paths with extensions are preferred over path aliases to eliminate resolution steps for AI agents.
- ▪The spec.md file serves as a contract with frontmatter and verification instructions, linked to tests and implementation.
- ▪Only minimal top-level directories like bootstrap/, lib/, and config/ are allowed; all feature code must reside in feature-specific directories.
Opening excerpt (first ~120 words) tap to expand
try { if(localStorage) { let currentUser = localStorage.getItem('current_user'); if (currentUser) { currentUser = JSON.parse(currentUser); if (currentUser.id === 2185235) { document.getElementById('article-show-container').classList.add('current-user-is-article-author'); } } } } catch (e) { console.error(e); } jucelinux Posted on May 17 The ten principles: locality, contracts, quarantine #ai #claudecode #agents #architecture Grounded Code (6 Part Series) 1 Grounded Code: Your codebase has a new primary reader. And it’s paying 7.5x more. 2 The primary reader changed ... 2 more parts...
…
Excerpt limited to ~120 words for fair-use compliance. The full article is at DEV.to (Top).
Discussion
0 commentsMore from DEV.to (Top)
