Tomas Mirchev
457fbc669c
- Add CLAUDE.md with development standards - Remove docs/architecture.md and docs/flows.md (obsoleted by redesign spec) - Track docs/code-review.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.2 KiB
Development Standards
General
-
Fix the root cause, not the symptom. Do not add defaults, fallbacks, conditional wrappers, or runtime workarounds to cope with a broken upstream flow. If a value is missing, fix the source that provides it. If a dependency isn't ready, fix the ordering.
-
No speculative abstraction. Do not add overrides, toggles, or configurable escape hatches for scenarios that do not exist yet. If a new requirement appears, add the abstraction then.
-
Fail loudly at the boundary. When a value reaches an unexpected state, throw or surface the error immediately. A loud failure with a clear trace is more useful than a silent fallback that hides the bug and lets it propagate further.
-
Direct access over defensive wrapping. Access values directly. Do not add null-coalescing chains, fallback guards, or default-dict patterns for values that are always expected to be present.
-
One canonical form. Keep a single representation for each concept -- one source of truth for constants, one naming convention per domain, no conversion layers between equivalent forms.
-
Explicit over implicit. Write values and behaviour directly rather than generating or inferring them when the intent is small and stable. Clarity at the call site matters more than cleverness at the definition.
-
Reuse existing mechanisms. Do not introduce local duplicates of something already shared without a clear reason. Prefer extending what exists.
-
No empty files or placeholders. Every file committed should serve a purpose.
-
Exhaustive over defensive. When branching on a finite set of known values, handle every case explicitly. The compiler should enforce completeness -- not runtime guards or catch-all defaults.
-
Infer intent from context. Resolve ambiguity against existing conventions and adjacent code first. If uncertainty remains, ask before changing behaviour.
-
Refactors are collaborative. Discuss direction first, implement once agreed. Prefer small directed phases over broad rewrites.
-
During implementation, audit the upstream flow. Report any bug, mismatch, or unexpected result found -- even if it is outside the immediate scope.