AI Agent Instructions

Overview

This repository is a template with sensible defaults for building Tauri React apps.

Core Rules

New Sessions

• Review docs/developer/architecture-guide.md for high-level patterns
• Check docs/developer/README.md for the full documentation index
• Check git status and project structure

Development Practices

CRITICAL: Follow these strictly:

0. Use pnpm only: This project uses pnpm (locked at 10.29.1). Always use pnpm install, pnpm run, etc.
1. Read Before Editing: Always read files first to understand context
2. Follow Established Patterns: Use patterns from this file and docs/developer
3. Senior Architect Mindset: Consider performance, maintainability, testability
4. Batch Operations: Use multiple tool calls in single responses
5. Match Code Style: Follow existing formatting and patterns
6. Test Coverage: Write comprehensive tests for business logic
7. Quality Gates: Run pnpm check:all after significant changes
8. No Dev Server: Ask user to run and report back
9. No Unsolicited Commits: Only when explicitly requested
10. Documentation: Update relevant docs/developer/ files for new patterns
11. Removing files: Always use rm -f

CRITICAL: Use Tauri v2 docs only. Always use modern Rust formatting: format!("{variable}")

Architecture Patterns (CRITICAL)

State Management Onion

useState (component) → Zustand (global UI) → TanStack Query (persistent data)

Decision: Is data needed across components? → Does it persist between sessions?

Performance Pattern (CRITICAL)

// ✅ GOOD: Selector syntax - only re-renders when specific value changes
const leftSidebarVisible = useUIStore(state => state.leftSidebarVisible)

// ❌ BAD: Destructuring causes render cascades (caught by ast-grep)
const { leftSidebarVisible } = useUIStore()

// ✅ GOOD: Use getState() in callbacks for current state
const handleAction = () => {
  const { data, setData } = useStore.getState()
  setData(newData)
}

Static Analysis

• React Compiler: Handles memoization automatically - no manual useMemo/useCallback needed
• ast-grep: Enforces architecture patterns (e.g., no Zustand destructuring). See docs/developer/static-analysis.md
• Knip/jscpd: Periodic cleanup tools. Use /cleanup command (Claude Code)

Event-Driven Bridge

• Rust → React: app.emit("event-name", data) → listen("event-name", handler)
• React → Rust: Use typed commands from @/lib/tauri-bindings (tauri-specta)
• Commands: All actions flow through centralized command system

Tauri Command Pattern (tauri-specta)

// ✅ GOOD: Type-safe commands with Result handling
import { commands } from '@/lib/tauri-bindings'

const result = await commands.loadPreferences()
if (result.status === 'ok') {
  console.log(result.data.theme)
}

// ❌ BAD: String-based invoke (no type safety)
const prefs = await invoke('load_preferences')

Adding commands: See docs/developer/tauri-commands.md

Internationalization (i18n)

// ✅ GOOD: Use useTranslation hook in React components
import { useTranslation } from 'react-i18next'

function MyComponent() {
  const { t } = useTranslation()
  return <h1>{t('myFeature.title')}</h1>
}

// ✅ GOOD: Non-React contexts - bind for many calls, or use directly
import i18n from '@/i18n/config'
const t = i18n.t.bind(i18n)  // Bind once for many translations
i18n.t('key')                 // Or call directly for occasional use

• Translations: All strings in /locales/*.json
• RTL Support: Use CSS logical properties (text-start not text-left)
• Adding strings: See docs/developer/i18n-patterns.md

Documentation & Versions

• Context7 First: Always use Context7 for framework docs before WebSearch
• Version Requirements: Tauri v2.x, shadcn/ui v4.x, Tailwind v4.x, React 19.x, Zustand v5.x, Vite v7.x, Vitest v4.x

Developer Documentation

For complete patterns and detailed guidance, see docs/developer/README.md.

Key documents:

• architecture-guide.md - Mental models, security, anti-patterns
• state-management.md - State onion, getState() pattern details
• tauri-commands.md - Adding new Rust commands
• static-analysis.md - All linting tools and quality gates

Claude Code Commands & Agents

These are specific to Claude Code but documented here for context.

Commands

• /check - Check work against architecture, run pnpm check:all, suggest commit message
• /cleanup - Run static analysis (knip, jscpd, check:all), get structured recommendations
• /init - One-time template initialization

Agents

Task-focused agents that leverage separate context for focused work:

• plan-checker - Validate implementation plans against documented architecture
• docs-reviewer - Review developer docs for accuracy and codebase consistency
• userguide-reviewer - Review user guide against actual system features
• cleanup-analyzer - Analyze static analysis output (used by /cleanup)