Agents.md #

Language Rules #

• All source code, comments, documentation, and new user-facing text must use en_US.
• Web UI text must route through i18n (web/src/lib/i18n/messages/); keep key structures aligned across locales (especially en-us.ts and zh-hans.ts). Never hardcode strings in Svelte components.
• Assistant conversations with the user use zh_Hans by default (concise, natural language). Use en_US only when necessary.
• Code comments: English only, explain why (never how).

General Preferences #

• Code style: functional-first, composition over inheritance, avoid OOP in TS/JS.
• New features: reuse/refactor existing code first — never pile on new code.
• Always follow KISS + DRY: smallest viable solution.
• When writing code, strictly follow ai-coding-discipline rules.
• Bad design? Refactor small issues immediately; for larger ones, add TODO + clear explanation.
• Architecture & design:
  • Start from first principles: clarify what is truly required before deciding how.
  • Avoid XY problems — validate the real issue and proactively suggest better alternatives.
  • Solve root causes, never workarounds. Refactor architecture if it no longer supports the need.
  • Immediately question unreasonable requirements or directions (no flattery, no blind agreement).
  • Reference ddia-principles and software-design-philosophy.
  • Tech choices: always recommend current industry best practices. Research first if unsure.

Communication Rules #

• Never silently make product, architecture, or public-API decisions.
• If anything is ambiguous, changes behavior/scope/structure, or has meaningful tradeoffs, ask the user before proceeding.
• Surface blockers, conflicts, or multiple reasonable paths clearly and ask for confirmation.

Implementation Rules #

• Prefer the smallest correct change.
• Keep early milestones narrow and end-to-end.
• Assume technical users. No excessive fault-tolerance or defensive UX unless explicitly required.
• Breaking changes are acceptable if they simplify the system.
• NEVER bypass GPG signing.
• Reuse existing i18n keys/namespaces before adding new ones.

When To Ask The User #

Ask before proceeding if any of the following is true:

• Requirement is ambiguous
• Decision affects public interfaces or naming
• Schema/protocol not fixed.
• Conflicts with existing work
• Multiple reasonable approaches with meaningful tradeoffs

UI Component Library #

• Web UI MUST use shadcn-svelte components (located in web/src/lib/components/ui/).
• Add new components with: cd web && deno run -A npm:shadcn-svelte@latest add <component-name>

Svelte 5 Syntax Requirements #

All components must use runes mode:

• Props: let { name, count = 0 }: { name: string; count?: number } = $props();
• State: let count = $state(0);
• Derived: let doubled = $derived(count * 2);
• Effects: $effect(() => { ... });
• Two-way binding: let { value = $bindable() } = $props();
• Events: onclick (not on:click)
• Slots: {@render children?.()}
• Rest props: ...restProps
• Always type props with TypeScript interfaces.