dev-conventions

Development Conventions

General rules that apply across all projects. Read and follow before making any code change.

Tradeoff: These rules bias toward caution over speed. For trivial tasks, use judgment.

Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

Reuse Before Creating

• Before adding a component, helper, constant, service, or utility: search the codebase first
• If an equivalent already exists, import and reuse it
• Extend existing components with props or small local composition before creating variants
• Only add a helper, service, or shared constant when logic is reused across files or clearly belongs to an existing shared module
• If logic is local to one screen or form, keep it as a private local helper: do not extract prematurely

No Duplication

• Shared business logic belongs in the project's shared service or domain layer
• Shared UI belongs in the project's shared widget or component layer
• Shared constants belong in the relevant domain file: not scattered per file
• Do not create a variant of something that already exists: parameterize or extend instead

When you spot duplication, apply the matching pattern:

Signal	Pattern
Same logic in 2+ places	Extract function / Extract module
Same logic with minor variation	Parameterize: add argument instead of copying
Same group of values always together	Introduce value object or struct
Same multi-step process repeated	Extract class or service
Same conditional type-switching	Replace with polymorphism or strategy
Same object built ad-hoc everywhere	Factory or builder function
Same config value hardcoded in N places	Named constant or config key
Same validation rule written per handler	Extract to single validator
Same error mapping repeated per handler	Extract to shared mapper
Same test setup repeated per file	Extract to shared factory or fixture