Engineering Principles

Purpose: Decision framework and anti-patterns for Framework projects. For specific rules, see CLAUDE.md § Critical Rules.

Anti-patterns

These are explicitly prohibited:

Anti-Pattern	Why It's Prohibited
"We'll fix it later"	Later never comes. Fix it now or don't ship it
"It works on my machine"	If it's not reproducible, it's not working
"Just copy the values manually"	Manual processes are error-prone and don't scale
"We don't need tests for this"	Untested code is untrustworthy code
"Let's add it as a TODO"	TODOs without Linear issues are graveyard markers
"Good enough for v1"	V1 sets the quality floor for everything after it
"We can always refactor"	Refactoring costs 3-10x more than doing it right

Decision framework

When choosing between approaches, use this priority order:

1. Correctness — Does it work correctly in all cases?
2. Reliability — Will it keep working without babysitting?
3. Security — Is it safe from the OWASP Top 10?
4. Maintainability — Can the next developer understand it?
5. Performance — Is it fast enough? (Not fastest possible — fast enough)
6. Developer Experience — Is the workflow pleasant?

Never optimize for a lower priority at the expense of a higher one.

Related standards

• standards/core/sdlc.md — Development lifecycle that enforces these principles
• standards/core/testing.md — Testing standards that verify correctness
• standards/core/security.md — Security standards that ensure safety
• standards/reference/environments.md — Environment management that automates deployment

---

Engineering Principles -- March 2026