Skip to content

AGENTS.md

Latest commit

 

History

History
49 lines (42 loc) · 2.49 KB

AGENTS.md

File metadata and controls

49 lines (42 loc) · 2.49 KB

AGENTS.md

Ground rules (always)

  • Be conservative, explicit, and boring.
  • When unsure, ask; don’t guess.
  • Make minimal, targeted changes; avoid refactors unless requested/necessary.
  • Preserve existing structure, conventions, and tooling.
  • Don’t add dependencies without strong justification.

TypeScript

  • Write strict, idiomatic TS; follow the repo’s tsconfig and lint rules.
  • No any (use unknown, generics, or proper types).
  • Prefer interface for public shapes; type for unions/helpers.
  • Prefer immutability (readonly, ReadonlyArray) where practical.
  • Narrow with type guards; avoid assertions and ! except as a last resort.
  • Prefer exhaustive handling (never checks) for unions.
  • Treat caught errors as unknown and narrow before use.

Node.js

  • Target the repo’s supported Node LTS (don’t assume versions; check config/docs).
  • Prefer async/await; never swallow rejections.
  • Avoid module top-level side effects (I/O, network, reading env, global mutations) unless explicitly intended.
  • Env vars: validate centrally; read at runtime (not import-time); don’t mutate in app code (tests only with scoped setup/teardown).
  • Error handling: rethrow with context; preserve cause when available; don’t throw strings.
  • Library code should not log; CLIs may log intentionally with consistent exit codes.

Testing (Vitest)

  • New logic requires tests unless truly trivial (types-only, re-exports, comments/formatting).
  • Tests must be deterministic and isolated; avoid shared mutable state.
  • Prefer behavioral tests; mock sparingly.
  • No committed .only/.skip (unless explicitly justified).
  • Bug fixes must include a regression test.
  • Avoid snapshots unless they add clear value and are stable.

Style, docs, and security

  • Follow existing formatting/lint; keep functions small and readable.
  • Prefer named exports.
  • Update docs/comments when behavior changes (comments explain “why”, not “what”).
  • Never log secrets; validate/sanitize external inputs (paths/URLs/user data).
  • Dependency adds must be justified (need, alternatives, maintenance/license/security impact).

MUST NOT

  • Change public APIs or introduce breaking changes without explicit instruction.
  • Perform stylistic rewrites or micro-optimizations.

Verify before committing

  • Typecheck + lint + tests pass.
  • New behavior has coverage (including failure paths); no unintended snapshot changes.
  • No unnecessary diff churn; no accidental top-level side effects; env usage is validated and intentional.