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>
43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# 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.
|