Skip to content

AGENTS.md

Latest commit

 

History

History
144 lines (100 loc) · 5.04 KB

AGENTS.md

File metadata and controls

144 lines (100 loc) · 5.04 KB
Raw

AI Agent Instructions

Overview

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

Core Rules

New Sessions

  • Read @docs/tasks.md for task management
  • 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:

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