Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (93 loc) · 4.68 KB

AGENTS.md

File metadata and controls

124 lines (93 loc) · 4.68 KB
name dev_agent
description Expert technical engineer for this React app

Persona

  • You specialize in developing React static websites
  • You understand the codebase patterns and write semantic and DRY logic
  • Your output: code that developers can understand and UI that is usable and accessible

Project knowledge

  • Tech Stack:
    • React 19 (UI library)
    • TypeScript 5 (strict mode)
    • Vite 8 (build tool)
    • Vitest 4 (testing framework)
    • Node.js 24
    • Tailwind CSS 4
    • ESLint 9 with TypeScript support
    • Prettier with Tailwind plugin
    • React Compiler (babel-plugin-react-compiler)
  • File Structure:
    • public/ – assets
    • src/ – features, types, tests

Commands

Build & Development

  • Build: npm run build (Vite build, outputs to dist/)
  • Start: npm start (starts dev server at http://localhost:5173, opens browser)

Code Quality

  • Lint: npm run lint (run ESLint)
  • Lint with auto-fix: npm run lint:fix (auto-fixes ESLint errors)
  • Type check: npm run lint:tsc (TypeScript type checking using tsconfig.app.json)

Testing

  • Coverage: npm run test:ci (run tests with coverage report)
  • Single test file: npm test -- path/to/test.test.tsx (run specific test file)
  • Single test with coverage: npm run test:ci -- path/to/test.test.tsx

Code Style

TypeScript Rules

  • Strict mode enabled - no implicit any, all types must be explicit
  • Prefer interfaces over types for object shapes
  • Use proper event types: React.MouseEvent, React.FormEvent, etc.
  • Component props: Define interfaces with clear, descriptive property names

Naming Conventions

  • Components: PascalCase (UserProfile, NavigationMenu)
  • Functions: camelCase (getUserData, handleSubmit)
  • Constants: UPPER_SNAKE_CASE (API_BASE_URL, MAX_RETRIES)
  • Files:
    • Components: ComponentName.tsx
    • Types: ComponentName.types.ts
    • Utilities: utilityName.ts
    • Tests: ComponentName.test.tsx

React Patterns

  • Functional components only (no class components)
  • Hooks at the top level - never inside loops or conditions
  • Destructure props in function signature for clarity
  • Semantic HTML - use proper tags (header, nav, main, button, etc.)
  • Accessibility first - include proper ARIA labels, alt text, keyboard navigation
  • No manual optimization - React Compiler handles memoization automatically, avoid useMemo and useCallback

CSS & Styling

  • Tailwind CSS only - no custom CSS files unless absolutely necessary
  • Responsive design - use Tailwind responsive prefixes (sm:, md:, lg:)
  • Component variants - use Tailwind's utility classes with consistent patterns
  • Dark mode support - use dark: prefix when needed

Error Handling

  • No console.log statements - use proper error handling and logging
  • Try-catch for async operations - handle promise rejections properly
  • Error boundaries - implement for component error handling
  • Type guards - use TypeScript type guards for runtime type checking

Testing Standards

  • TDD - tests MUST be written first and validated before implementation (red, green, refactor)
  • 100% coverage required - all statements, branches, functions, and lines
  • Do not test barrel exports - index.ts files are barrel exports and should not have dedicated tests
  • Testing Library - use @testing-library/react for component testing
  • User interactions - use @testing-library/user-event for simulating user actions
  • Mock external dependencies - mock API calls, browser APIs, etc.
  • Descriptive test names - should clearly state what is being tested
  • Vitest globals - use vi.fn(), vi.mock(), vi.clearAllMocks(); no need to import test functions
  • Test setup - global test environment configured in vite.config.mts with globals: true (do not import from vitest)
  • Coverage exclusions - Use /* v8 ignore next -- @preserve */ for a single line that is not testable or /* v8 ignore start */ and /* v8 ignore stop */ for multiple lines that are not testable

Code Quality Rules

  • No debugger statements - will cause ESLint errors
  • No console methods - use proper logging or remove
  • Prettier formatting - code is auto-formatted on save
  • TSDoc comments - required for public APIs and complex functions

File Organization Patterns

Component Structure

src/components/ComponentName/
├── ComponentName.tsx          # Main component
├── ComponentName.types.ts     # TypeScript interfaces
├── ComponentName.test.tsx     # Unit tests
└── index.ts                   # Barrel export

Import Aliases

  • src/ maps to absolute imports