klai: Instructions file for Claude Code

Klai — Agent Operating Rules

Model-neutral rules for every agent in this monorepo (Codex, Claude, or other). Codex reads this file natively. Claude reads it via @AGENTS.md in CLAUDE.md. A nested AGENTS.md closer to the file you edit overrides anything here.

Enforcement note: Claude runs Stop/PreToolUse hooks that mechanically enforce some of these rules. Codex runs no such hooks — under Codex these rules are self-enforced only. Treat them as MUST, not as suggestions. Codex-specific notes: .agents/codex/README.md.

Prime directive — autonomy on execution, strictness on claims

• Keep going. Do not ask permission to proceed, to push approved work, or to move to the next step. Stop only for (a) a real decision the user must make, or (b) a failing guard: CI red, test failure, or unverifiable external state.
• You may NOT claim "fixed / done / deployed" without evidence per claim. "Looks correct" / "should work" / "reviewed the code" is not evidence — it scores zero. Prove it, don't assert it.
• If the user asks to ship, merge, push, or get work live on main, do not stop at an open PR. Either get the intended commit reachable from origin/main and verify main CI/deploy/E2E/live health, or report the exact blocker. Production host-specific proof steps live in the private klai-infra runbook docs/runbooks/ship-public-klai-to-main.md.

Always-on engineering discipline

• data-before-code — Trace real logs / DB / runtime before fixing. No guessing, no stacked patches. For production: query VictoriaLogs by request_id:<uuid>. One root cause confirmed by data = one fix.
• measure, then scope — Data that shows a wider problem than the reported bug goes into the report as a backlog item with the numbers. It does not widen this change. One ticket, one cause, one fix.
• fail loudly — No silent fallback on external-provider drift. Unknown external state = raise an error, or name the condition under which the change fails and what you would see. No "best-effort success" when the core mutation failed. (Database-layer RLS defense-in-depth is deliberate and stays — this rule is about app-layer shims, not the DB security model.)
• minimal changes — Only what was asked. No drive-by refactors, reformatting, or "improvements" to untouched files.
• clean over clever, no parallel old+new — Remove the code your change replaces in the SAME change: no dead fields, no commented-out blocks, no old and new flow living side by side. Clean solutions over defensive clutter. (This is about removing what you replaced — not editing untouched files; it composes with "minimal changes", it does not contradict it.)
• scale the answer to the problem — Lead with the simplest solution that works (the 5-minute fix if one exists); escalate to a bigger design only when the problem demands it. No SPEC for something that affects 1–5 people. Report what you deliberately left out as a decision: what, why, and when it must still happen.
• ship the better path by default — When a change makes the product better, it goes live for every customer at once. No improvement behind a flag that is off by default, no separate test widget or tenant to prove it first. Build the measurement alongside (logs, counters, an eval you can run), measure on real traffic, and adjust from there. What still gates a rollout is safety, not measurement: a fail-closed direction, a security boundary, a migration order.
• production knowledge data is rewritten only with approval per run — A re-ingest, rebuild_kb, a backfill with --execute, a crawl start or a deferred enrichment job on production never runs on an agent's own initiative and never as a step inside a measurement or driver script. The order is fixed: unit tests on the operation, a dry run on production that only counts and shows the first changes, the user's yes for that one run in his own words, one knowledge base as a trial with a measurement after it, then the rest. On 2026-10-24 a full rebuild of a customer's largest knowledge base (2,422 documents) was chained behind a measurement round without asking; it was stopped after 21 documents. A setting that derives from stored text (aliases, product labels, sparse vectors, embeddings) is applied as a payload-and-vector patch on the affected chunks, never by redoing the model work of the whole knowledge base.
• verify-changes-landed — Before reporting done: git diff --stat (right files?), service health/logs (running new code?), and a Playwright click-through for any UI change (real user flow works?).
• search broadly when changing a default/name — grep every consumer, all case variants (kebab, snake, camel, Pascal, SCREAMING_SNAKE). Defaults have unbounded blast radius.
• no plausible assumptions — Do not infer message.sources, Zitadel password policy, streaming chunks, BFF cookies, OIDC flows, or performance paths from intuition. Require evidence from code, tests, logs, docs, or an explicit user confirmation.
• verify vendored contracts on the bump — Bumping a pinned image or a network SDK is not done until something exercised the contract you rely on against the NEW version. Two rules learned the hard way, both in August 2026: read the installed source or the running container, never the schema (docling-serve's OpenAPI types task_status as a six-value enum the server can only ever answer with four of, and trusting it produced the wrong fix); and record the verified version in a test, not in a docstring — a docstring goes stale in silence, a test goes red. A mocked unit test asserting "we sent the right shape" proves nothing about whether the dependency still accepts that shape: crawl4ai 0.9 started answering 400 to a field we had always sent, every authenticated crawl broke for weeks, and the whole suite stayed green.