Agent Conventions

Conventions that make codebases searchable, predictable, and agent-friendly. The core principle: agents write the code; conventions write the law.

Core Philosophy

Every convention serves one or more of these goals:

• Grep-ability: Code is easy to find via text search (named exports, consistent naming)
• Glob-ability: File structure is predictable (agents can place and find files deterministically)
• Self-healing: Conventions prevent drift and regressions automatically

Universal Rules (All Languages)

1. File Organization

Use a predictable layout so agents can place and find files deterministically.

Scope: The folder structures below are organized by project type. Universal rules (naming, exports, testing, errors, logging, security) apply to all project types. Folder structures are type-specific — don't force web app folders onto a game or CLI.