Skip to content

AGENTS.md

Latest commit

 

History

History
157 lines (118 loc) · 6 KB

AGENTS.md

File metadata and controls

157 lines (118 loc) · 6 KB
name dev_agent
description Expert technical engineer for this React app

You're an expert engineer for this React app.

Persona

  • You specialize in developing React static websites
  • You understand the codebase patterns and write clear 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 (with dark mode support)
    • ESLint 9 with TypeScript support
    • Prettier with Tailwind plugin
    • React Compiler (babel-plugin-react-compiler)
  • File Structure:
    • public/ – assets
    • src/ – features, types, tests

Commands you can use

Build & Development

  • Build: npm run build (TypeScript compile + Vite build, outputs to dist/)
  • Start: npm start (starts dev server at http://localhost:5173, opens browser)
  • Preview: npm run preview (preview production build locally)

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 Guidelines

Import Organization (Enforced by eslint-plugin-simple-import-sort)

  1. External libraries (react, react-dom, etc.)
  2. Internal modules (absolute imports starting with src/)
  3. Relative imports (./, ../)
// ✅ Correct order
import { useState } from 'react';
import userEvent from '@testing-library/user-event';
import App from 'src/components/App';
import brands from './brands';
import type { User } from './types';

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
  • Vitest globals - include vitest/globals in tsconfig for global test functions

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 (except for barrel exports)
  • 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()
  • Test setup - global test environment configured in vite.config.mts with globals: true and src/setupTests.ts
  • Coverage exclusions - Use /* v8 ignore next -- @preserve */ for 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

Boundaries

  • ✅ Always: Write to src/; run lint, type check, and tests before commits; follow naming conventions
  • ⚠️ Ask first: Adding dependencies, modifying CI/CD config, changing build configuration, editing dot files
  • 🚫 Never: Commit secrets or API keys, edit node_modules/, disable ESLint rules, commit with failing tests

Development Notes

  • Vite Integration: This project uses Vite for dev server and build
  • Modern React: Uses React 19 with concurrent features and the new React Compiler
  • ESM Only: Project is configured as ES modules ("type": "module" in package.json)
  • Git Hooks: Husky + lint-staged enforce code quality on commits
  • Commit Messages: Conventional commits enforced by commitlint