STANDARDS.md

October 10, 2025 · View on GitHub

Problem definition → small, safe change → change review → refactor — repeat the loop.

Mandatory Rules

  • Before changing anything, read the relevant files end to end, including all call/reference paths.
  • Keep tasks, commits, and PRs small.
  • If you make assumptions, record them in the Issue/PR/ADR.
  • Never commit or log secrets; validate all inputs and encode/normalize outputs.
  • Avoid premature abstraction and use intention-revealing names.
  • Compare at least two options before deciding.

Mindset

  • Think like a senior engineer.
  • Don’t jump in on guesses or rush to conclusions.
  • Always evaluate multiple approaches; write one line each for pros/cons/risks, then choose the simplest solution.

Code & File Reference Rules

  • Read files thoroughly from start to finish (no partial reads).
  • Before changing code, locate and read definitions, references, call sites, related tests, docs/config/flags.
  • Do not change code without having read the entire file.
  • Before modifying a symbol, run a global search to understand pre/postconditions and leave a 1–3 line impact note.

Required Coding Rules

  • Before coding, write a Problem 1-Pager: Context / Problem / Goal / Non-Goals / Constraints.
  • Enforce limits: file ≤ 300 LOC, function ≤ 50 LOC, parameters ≤ 5, cyclomatic complexity ≤ 10. If exceeded, split/refactor.
  • Prefer explicit code; no hidden “magic.”
  • Follow DRY, but avoid premature abstraction.
  • Isolate side effects (I/O, network, global state) at the boundary layer.
  • Catch only specific exceptions and present clear user-facing messages.
  • Use structured logging and do not log sensitive data (propagate request/correlation IDs when possible).
  • Account for time zones and DST.

Testing Rules

  • New code requires new tests; bug fixes must include a regression test (write it to fail first).
  • Tests must be deterministic and independent; replace external systems with fakes/contract tests.
  • Include ≥1 happy path and ≥1 failure path in e2e tests.
  • Proactively assess risks from concurrency/locks/retries (duplication, deadlocks, etc.).

Security Rules

  • Never leave secrets in code/logs/tickets.
  • Validate, normalize, and encode inputs; use parameterized operations.
  • Apply the Principle of Least Privilege.

Clean Code Rules

  • Use intention-revealing names.
  • Each function should do one thing.
  • Keep side effects at the boundary.
  • Prefer guard clauses first.
  • Symbolize constants (no hardcoding).
  • Structure code as Input → Process → Return.
  • Report failures with specific errors/messages.
  • Make tests serve as usage examples; include boundary and failure cases.

Anti-Pattern Rules

  • Don't modify code without reading the whole context.
  • Don't expose secrets.
  • Don't ignore failures or warnings.
  • Don't introduce unjustified optimization or abstraction.
  • Don't overuse broad exceptions.

Commit Convention Rules

  • Follow @commitlint/config-conventional specification (https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional).
  • Format: <type>[optional scope]: <description>.
  • Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.
  • Type must be lowercase and non-empty.
  • Subject must not be empty, not end with period (.), and avoid sentence-case/start-case/pascal-case/upper-case.
  • Header max length: 100 characters.
  • Body and footer require leading blank line, max line length: 100 characters.
  • Breaking changes: use BREAKING CHANGE: in footer with blank line before it.
  • Examples:
    • ✅ fix: resolve memory leak in user service
    • ✅ feat(auth): add OAuth2 integration
    • ❌ Fix: Some Message. (wrong case, ends with period)
    • ❌ random: some change (invalid type)