OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Golden Rules

• When unsure about implementation details, requirements, or business logic, ALWAYS consult the developer rather than making assumptions.
• We optimize for maintainability over cleverness. When in doubt, choose the boring solution.

Plan & Review

Before starting work

• Always start with planning the work unless requested not to do it. After getting the plan, never present it in the chat, write it to .claude/tasks/TASK_NAME.md instead.
• The plan should be a detailed implementation plan and the reasoning behind them, as well as tasks broken down.
• If the task requires external knowledge or certain package, also research to get latest knowledge (Use Task tool for research).
• Don't over plan it, always think MVP.
• Once you write the plan, firstly ask me to review it. Do not start implementation until I approve the plan.

While implementing

• You should update the plan in .claude/tasks/TASK_NAME.md as you work.
• After you complete tasks in .claude/tasks/TASK_NAME.md, you should update and append detailed descriptions of the changes you made, so following tasks can be easily hand over to other engineers.
• In case of lint errors/warnings, use pnpm lint --fix to resolve them.

Scanning Repository

• Use Only Referenced Files: Analyze, generate code, or match patterns using only files explicitly mentioned in the user's prompt. [Important]
• Locate Anchors First: Before scanning, check for existing AIDEV-* anchors in relevant subdirectories. [Important]
• No Broad Scans: Avoid scanning unreferenced files unless the user explicitly permits it.
• Handle Insufficient Information: If referenced files lack context, state: "Insufficient information in provided files." Suggest specific files or details needed, e.g., "Please provide 'src/features/auth/[file_name]' or clarify expected behavior."

Essential Commands

Essential Commands

• pnpm dev - Start development server on port 5173
• pnpm lint - Run ESLint with flat config
• pnpm lint --fix - Run ESLint and fix linting errors/warnings
• pnpm test - Run all tests (unit + storybook)
• pnpm test:unit - Run unit tests only
• pnpm test:storybook - Run storybook tests only
• pnpm test:coverage - Run tests with coverage report
• pnpm storybook - Start Storybook development server on port 6006

CI Commands

• pnpm test:unit:ci - Run unit tests with coverage and reports for CI
• pnpm test:storybook:ci - Run storybook tests with coverage and reports for CI

Package Manager

This project uses PNPM as the package manager. Always use pnpm commands, not npm or yarn.

Architecture Overview

This is a React SPA built with Vite using feature slice based architecture with clean architecture principles.

Core Technologies

• React 19 with TypeScript
• Vite 7 for build tooling
• React Query (TanStack Query) for data fetching
• React Router 7 for routing
• i18next for internationalization
• MSW 2 for API mocking
• Vitest 3 for testing
• Storybook 9 for component development
• Zustand for state management
• Chakra UI for components

Project Structure

src/
├── app/           # App-level configuration (App.tsx, Providers.tsx)
├── features/      # Feature modules using feature slice architecture
│   ├── auth/      # Authentication feature
│   ├── carts/     # Shopping cart feature
│   ├── products/  # Product catalog feature
├── lib/           # Shared libraries and utilities
│   ├── api/       # Centralized API layer (queries, commands, DTOs)
│   ├── components/ # Reusable UI components
│   ├── http/      # HTTP client and error handling
│   ├── i18n/      # Internationalization setup
│   ├── router/    # Routing utilities
│   └── theme/     # Theme configuration
├── pages/         # Route-level page components composing feature components & logic
└── test-lib/      # Testing utilities and fixtures

Feature Architecture

Each feature follows feature slice architecture patterns with three layers:

• presentation/ - UI components, UI-wise hooks
• application/ - Business logic, state management, logic-wise hooks
• infrastructure/ - Data fetching, external APIs, contracts, DTOs
• types/ - Type definitions

Key Patterns

• Co-location - Related files (component + story + test) are grouped together
• MSW handlers - API mocking is centralized in test-lib/handlers/
• Fixture pattern - Test data generation in test-lib/fixtures/
• Strong typing - Comprehensive TypeScript usage with branded types
• Component Composition: Features export composed components for pages to use,
• Centralized API - All API logic consolidated in src/lib/api/ with endpoint-based organization

Path Resolution

• Uses @/* path mapping for clean imports from src/
• Example: import { Button } from '@/shared/components/button'

Testing Strategy

• Unit tests - .test.ts / .test.tsx files alongside source code
• Storybook tests - .stories.tsx files alongside components
• MSW integration - Mocked APIs for both development and testing
• Coverage reporting - Istanbul coverage with LCOV reports

State Management

• Zustand stores - For complex local state (auth, modals, etc.)
• React Query - For server state and caching
• React state - For simple component state

Routing

• File-based routing - Pages in src/pages/ with corresponding loaders
• Strong typing - Route paths defined in lib/router/routes.ts
• Lazy loading - Components loaded on demand with error boundaries

Error Handling

• Using react-error-boundary for unexpected components runtime errors

Build Optimization

• Lazy loading and code splitting based on react-router
• Using direct imports instead of default

Code Style and Patterns

Code Style

• Formatting: Prettier with 80-char lines
• Imports: sorted with eslint-plugin-import
• Components, providers: PascalCase, co-located with their tests PascalCase.stories
• Hooks, functions, classes, contexts: kebab-case, co-located with their tests kebab-case.test

Anchor comments

Add specially formatted comments throughout the codebase, where appropriate, for yourself as inline knowledge that can be easily grepped for.

• Use AIDEV-NOTE:, AIDEV-TODO:, or AIDEV-QUESTION: (all-caps prefix) for comments aimed at AI and developers.
• Keep them concise (≤ 120 chars).
• Before scanning files, always first try to grep for existing anchors AIDEV-* in prompt's referenced files or relevant files/subdirectories. [Important]
• Update relevant anchors when modifying associated code.
• Do not remove AIDEV-NOTEs without explicit human instruction.
• Make sure to add relevant anchor comments, whenever a file or piece of code is:
  • too complex, or
  • very important, or
  • confusing, or
  • could have a bug

Code Standards

General

• Preserve the original structure and formatting of the user's input.
• Always follow the existing structure and formatting of referenced files.
• Do not add comments to code unless explicitly requested. If needed, focus on better var/function names instead.
• Always use async/await for async code.
• Always use try/catch blocks for async operations.

Typescript

• If TypeScript inference can do the job, use it instead of explicit types.
• Follow functional programming principles where possible, especially prefer immutability and pure functions.
• Prefer type over interface unless the user explicitly requests an interface.
• Use optional chaining (?.) and nullish coalescing (??) operators for safe property access if needed.
• Avoid using any type. If necessary, use unknown instead.

React

• Use functional components with hooks.
• If a complicated useEffect is generated, create a custom hook instead.
• Always prefix custom hooks with use
• Keep components small and focused.
• Try to separate JSX and custom styles from logic.
• When editing/adding styles, look for available API of Chakra UI.

Testing Discipline

⚠️ MANDATORY: When writing or modifying tests, you MUST follow all rules from the frontend-testing skill. These docs contain comprehensive testing guidelines including the 6 most important rules (the-test-anatomy.md), test structure, assertions, mocking, and DOM testing patterns. Violations should be reported by bullet number.

Test Case Scenarios Preference

• Focus on business logic and domain requirements, not implementation details
• Test meaningful scenarios that could realistically occur in production
• Keep test scenarios focused on single responsibilities
• Avoid redundant edge cases like:
  • Empty arrays when "not found" is already tested
  • undefined collections when the type system prevents this
  • Multiple variations of the same error condition
• Prioritize tests for:
  • Happy path scenarios with realistic data
  • Error conditions that users might encounter
  • Edge cases that affect business logic (not just code coverage)
• Each test should verify distinct behavior, not just different ways to trigger the same code path

Testing

Use the frontend testing skill for any code editing, whether big or small. This project has a strict, opinionated, and regulated testing workflow that should never be discarded — specifically, follow the Double Gate 🌉 principle in every plan.

When using the test skill and the test planner - pass it the folder that is used to plan tasks so it can reuse it and put inside also the test context