AGENTS.md

philosophy

• FP over OOP when it makes sense; composability over inheritance
• clean, DRY, YAGNI, KISS — no exceptions
• early returns over nested conditionals
• immutability by default; mutate only when you must
• single responsibility — functions do one thing well
• pure functions preferred; isolate side effects at the edges
• DRY but not prematurely abstracted (rule of three)
• small modules over god files — if you're scrolling, split
• typed/explicit errors over thrown exceptions (Result, union returns)
• fail fast at boundaries, recover gracefully inside
• type safety always (TypeScript > JS, Rust > C)
• self-documenting names — no x, temp, data
• never comment if code is simple
• test behavior, not implementation; no test without a reason
• don't optimize prematurely, but don't be naively slow — measure first
• minimize dependencies; vet what you add
• assume every line gets scrutinized by the HN crowd

execution

• do what was asked — nothing more, nothing less
• never create files unless necessary; prefer editing existing ones
• never proactively create docs/READMEs unless explicitly asked
• if requirements are unclear, ask; otherwise, execute
• double-check your work
• never run browser tests, smake tests unless explicitly asked by the user.
• be concise in output but thorough in reasoning
• no sycophantic openers or closing fluff.

before writing code

• understand the problem fully before touching code
• research existing solutions, prior art, and ecosystem conventions
• read relevant source files before editing — don't assume structure
• plan the approach; if it's non-trivial, outline it first
• identify edge cases upfront, not after the PR review

architecture

• organize code by feature first, then the architecture
• each layer contains the code its responsible for only. ex. HTTP parses the request, calls underlying layers, throws HTTP errors, return response.
• apply these boundaries consistently to new code and move misplaced code when touching it; do not introduce a second folder convention beside the existing one

tools

• for node version management use fnm
• for python virtual env use uv

git

• use conventional commit format
• commit title: hn-style, imperative, ≤50 chars; no body unless reviewer can't infer the "why" from the diff
• pr description: max 4 lines, one short sentence each, no ai-slop
• pr structure (always):
  • What: one sentence
  • Why: one sentence
  • How: one sentence (omit if obvious from diff)
  • Notes: risks, follow-ups, or breaking changes (omit if none)