kana AGENTS.md

AGENTS.md

Scope and workflow

• Choose a change scope that matches the task and keep the result cohesive.
• Default to completing the task in one pass. Do not impose separate implementation, review, test, or documentation phases unless the user requests a checkpoint.
• Do not stop for routine approval. Ask for direction only when a missing choice would materially change the result, broaden the scope, or authorize a consequential action.
• Avoid unnecessary churn. For larger features or refactors, explain the important design tradeoffs and keep related changes together.
• Do not blindly follow a brittle or overly complex request. Explain the maintenance concern and suggest the simplest durable alternative.
• Before an unfamiliar or cross-module change, read docs/architecture.md and use docs/README.md to find the canonical owner; for a narrow change, read only the relevant owner document and avoid loading unrelated documentation.

Implementation

• Prefer clear names and code structure over comments.
• Add comments only for non-obvious invariants, design decisions, protocol semantics, ordering requirements, provider-specific behavior, and mutable state boundaries.
• Keep implementation comment blocks within four lines and 320 characters. Do not add comments that restate the code.
• Put longer explanations in documentation only when they describe a stable contract or design boundary that future contributors need.
• Do not add comment-check-ignore suppressions without maintainer approval.
• For imports under src, use relative imports within the same top-level src directory. Use the @/ alias only across top-level directories and prefer target barrels such as @/core or @/tools over deep aliases.

Tests

• Treat tests as evidence for behavior, not as mandatory file churn for every code edit.
• When observable behavior changes, inspect existing coverage first. Add or update tests only where the current suite does not adequately cover the changed contract or regression risk.
• Add a regression test for a bug fix when it is practical, stable, and likely to prevent recurrence.
• Do not change tests solely because implementation structure, comments, formatting, documentation, or generated references changed while behavior remained covered.
• Before adding a case, identify the lowest behavior owner and search existing coverage. Prefer strengthening or consolidating an existing case when it remains independently readable.
• Keep complete input and error matrices at the lowest owning layer. Higher-level tests should cover representative wiring and cross-module behavior instead of repeating those matrices.
• Run checks in proportion to the change. Use the full bun run check for broad, risky, or commit-ready changes.