| name | convention-over-configuration |
| description | When organizing project structure, establishing patterns, or reducing configuration overhead. Use when the user says "how should I organize this," "what's the convention," "too much config," "project structure," "naming pattern," or "standardize this." For code-level structure, see separation-of-concerns. |
| metadata | {"version":"1.0.0"} |
Convention over Configuration
Before Applying
If .agents/stack-context.md exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.
Principle
Adopt sensible defaults and consistent patterns so that decisions are made once and applied everywhere. Reserve explicit configuration for the cases that genuinely need to differ from the default.
Why This Matters in Production
Every configuration option is a decision that someone must make, document, understand, and maintain. Misconfigured systems are a top cause of production incidents — wrong environment variables, typos in YAML, conflicting settings between services.
Convention-driven systems are predictable. A new team member can look at one module and know how every other module works. There's no "well, this service does it differently because someone configured it that way 18 months ago."
Configuration should be the exception, not the default. When everything is configurable, nothing is standardized.
Rules
- Establish project conventions early and document them. File structure, naming patterns, error handling style, test organization — decide once and follow everywhere. Put these in a living document (like a CLAUDE.md or CONTRIBUTING.md).
- Use framework conventions as-is. If your framework puts routes in , models in , and tests in — follow that. Don't invent a custom layout unless the framework's conventions genuinely don't fit.
