nxdns/AGENTS.md

AGENTS.md

Aim

nxdns: a self-hosted DNS sinkhole for a household LAN, written in Zig 0.16.0. Portfolio-grade public repo. PLAN.md is the source of truth for scope and design; specs/ holds per-milestone contracts; specs/research/ holds verified stdlib facts.

Values

We intentionally architect this code to be robust, maintainable, pragmatic — good craftsmanship and good engineering. We explicitly avoid tech debt, code smells, bad architecture decisions, and brittle implementations.

What that means in practice:

• This is a greenfield project. Breaking changes are allowed. Never keep a bad interface for compatibility; fix it at the root.
• No versioning of scope. A feature is in scope (build it completely) or out of scope (do not build it). No "v2 later", no stubs left behind.
• Fix root causes, not symptoms. Do not iterate on workarounds.
• Scope is small on purpose: household scale, two targets, few dependencies. Do not add generality nobody asked for.
• Dependencies are liabilities: stdlib first; vendored + pinned C deps (sqlite3, mbedTLS) only where the stdlib has nothing.
• Verify stdlib claims against ../zig at tag 0.16.0 — pre-0.16 knowledge is stale (std.Io migration). See specs/research/zig-0.16-api-notes.md.
• Pure core: dns/, filter/, local/, cache/ take bytes and return bytes — no Io, no sockets, no clocks hidden inside.
• Every failure mode must be visible: no silent drops, no unbounded logs, no swallowed errors. Counters + health surfaces over log spam.
• Tests are runnable acceptance criteria, not decoration. Required CI stays deterministic — no network-dependent tests in blocking jobs.
• Comments state constraints the code cannot show. No narration, no commented-out code.
• Git: GPG-signed commits (git commit -S), simple lowercase messages, no generated-by footers.