Engineering Dart Systems
Before writing any Dart/Flutter code, run this mental checklist:
- Understand — What problem, what success criteria, what's ambiguous?
- Inspect — Read
pubspec.yaml,analysis_options.yaml, folder structure, existing patterns. - Research — Confirm APIs/packages against official docs for the actual SDK/package versions in use.
- Plan — Smallest architecture that satisfies requirements; break into tasks.
- Implement — Idiomatic, typed, null-safe, consistent with existing conventions.
- Verify —
dart format/dart analyze/dart test(or Flutter equivalents) — actually run them. - Review — Self-review like a PR reviewer; refactor only what's relevant.
- Report — State what changed, why, what was verified, what's unresolved.
Never skip straight to step 5.
Progress:
- [ ] Phase 1: Clarify requirements, success criteria, edge cases, risks
- [ ] Phase 2: Explore existing project (structure, SDK/deps, architecture, conventions, tests, lints)
- [ ] Phase 3: Research unfamiliar APIs/packages against official sources; compare alternatives
- [ ] Phase 4: Design simplest sufficient architecture + task breakdown
- [ ] Phase 5: Implement idiomatic Dart, matching existing patterns
- [ ] Phase 6: Write/run tests + static analysis, verify actual output
- [ ] Phase 7: Self-review as senior reviewer; refactor only what's touched
- [ ] Phase 8: Document decisions + deliver completion report
Phase 1 — Understand the Requirements
- Separate functional vs. non-functional requirements (performance, security, maintainability).
- Surface ambiguities explicitly; ask only when the information genuinely can't be discovered.
- Define acceptance criteria before any design discussion.
Phase 2 — Explore Before Touching Anything
Inspect, in order: pubspec.yaml (SDK + deps), analysis_options.yaml, directory layout, state management/DI approach, existing error handling/logging style, test structure/coverage, naming conventions. Match what exists — don't introduce a competing pattern without strong justification.
Phase 3 — Research, Don't Guess
When facing an unfamiliar API, package, or framework behavior:
- Check official Dart/Flutter docs, the package's own docs/changelog/source on pub.dev or GitHub — matched to the project's actual installed version.
- Never assume a tutorial or cached knowledge is still accurate; verify against the real version.
- If genuinely uncertain after research, say so explicitly instead of presenting a guess as fact.
- For consequential decisions, briefly compare 2–3 alternatives on: compatibility, maintenance activity, dependency weight, fit with existing architecture.
Phase 4 — Design Then Plan
- Pick the simplest architecture that satisfies real requirements — don't impose Clean Architecture/DDD/BLoC on a 3-file script, and don't under-architect a system meant to scale.
- Apply SOLID only where it earns its complexity.
- Define clear boundaries (business logic vs. infrastructure), identify reusable pieces, enumerate failure/edge cases.
- Write a task list with: what, affected files, dependencies between tasks, tests needed.
Phase 5 — Implement
Follow Effective Dart baseline:
- Sound null safety, strong typing, no uncontrolled
dynamic. final/constby default; immutability where it reduces state-bug risk.- Small, single-responsibility functions/classes; no god objects.
- Explicit error handling (typed exceptions/Result types) — never silent
catch (_) {}. - Meaningful names, no magic numbers/strings.
- Doc comments on public APIs, not comments restating the obvious.
- Only use language/SDK features actually supported by the project's SDK constraint.
Phase 6 — Verify (Actually Run These)
Bashdart format --output=none --set-exit-if-changed . dart analyze # or: flutter analyze dart test # or: flutter test
Report only verified outcomes. If a command can't be run in the current environment, say so — never claim a result you didn't observe.
Phase 7 — Senior-Level Self-Review
Ask: Is this the simplest correct solution? Is every abstraction earning its keep? Are names clear? Can this be tested in isolation? Are edge cases and failure paths handled? Does it match existing architecture? Would another engineer maintain this easily? Refactor only what you touched — don't drive-by refactor unrelated code.
Phase 8 — Document & Report
Completion report must include: what was implemented, why this approach, files touched, new dependencies (with justification), tests + actual results, known limitations, suggested next steps. Flag anything requiring human approval (destructive ops, architectural changes, security-sensitive decisions) before doing it.
Example 1:
Input: "Add a retry mechanism to our Dio HTTP client for 5xx errors."
Output: Inspects existing dio interceptor setup → confirms dio version supports InterceptorsWrapper retry pattern via docs → adds a focused RetryInterceptor class (exponential backoff, max attempts configurable) consistent with existing interceptor file layout → adds unit tests for: success-after-retry, max-retries-exceeded, non-5xx-not-retried → runs dart analyze/dart test, reports actual pass/fail output, notes it did not add a new HTTP package since dio already supports this.
Example 2:
Input: "Build offline-first caching for the product catalog."
Output: Checks for existing persistence (none found) → researches drift vs hive vs plain shared_preferences against project needs (structured queries needed → favors drift) → proposes architecture: ProductLocalDataSource + ProductRepository merging remote/local with cache-invalidation policy → flags the new dependency (drift + build_runner) and its justification before adding it → implements, tests cache-hit/miss/stale scenarios, runs checks, reports results and migration notes.
- Prefer the project's existing state management/DI/architecture over personal preference.
- Treat every new dependency as a cost — justify it against what's already available.
- Write tests for behavior and edge cases, not implementation details.
- Distinguish clearly, in reports, between "verified by running" and "expected based on docs."
- For irreversible/destructive/security-sensitive actions, pause and request confirmation.
- Keep architecture proportional to actual project complexity — don't over-engineer small utilities.
- Writing code before reading
pubspec.yaml/analysis_options.yamland existing patterns. - Introducing a new state-management/architecture pattern because it's trendy, not because it's needed.
- Inventing APIs/package capabilities instead of verifying against the real installed version.
- Claiming tests/analysis passed without actually executing them.
- Silent
catchblocks or swallowed errors "to make it compile." - Refactoring unrelated code while delivering an unrelated feature.
- Over-abstracting small problems into layered architectures nobody asked for.