main_frontend/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a Bun-powered Next.js frontend using Feature-Sliced Design. Route files live in app/; keep the root pages/ directory because Next.js build compatibility depends on it. Product code is organized under src/ by layer: src/pages, src/widgets, src/features, src/entities, and src/shared. Static assets belong in public/; shared source assets live in src/shared/assets/. End-to-end tests and support code are in tests/e2e/, with shared test assets in tests/assets/.

Build, Test, and Development Commands

• bun install installs dependencies from bun.lock.
• bun dev or bun run dev starts the Next.js development server.
• bun run build creates a production Next.js build.
• bun run start serves the production build.
• bun run lint runs the configured lint pipeline; keep lint:es and lint:prettier scripts aligned if you edit package.json.
• bunx jest runs unit tests configured by jest.config.ts.
• bun run test:e2e runs headed Playwright tests against the mock API.
• bun run test:integration runs headed Playwright tests whose filenames include .integration..
• bun run gen:api-types regenerates API types using .env.production.

Coding Style & Naming Conventions

Use TypeScript and React function components. Prettier is configured for tabs, double quotes, no semicolons, and trailing commas. SCSS modules follow Component.module.scss; component folders usually expose Component.tsx, Component.d.ts, and index.ts. Hooks use useName.ts naming. Prefer imports through aliases such as @shared/*, @features/*, and @widgets/*. Respect FSD boundaries: lower layers must not import upper layers.

Testing Guidelines

Unit tests use Jest with jsdom and usually live beside source files as *.test.ts or *.test.tsx. Playwright specs live under tests/e2e/specs/, grouped by domain such as auth/, project/, silence/, and upload/. Name mocked-flow specs *.spec.ts and real-backend flows *.integration.spec.ts. Keep reusable fixtures in tests/e2e/fixtures/ and helper servers/config in tests/e2e/support/.

Commit & Pull Request Guidelines

Recent history mostly uses short Conventional Commit-style messages, for example feat: add ..., fix: include ..., and chore: .... Prefer that format, with an imperative, lower-case summary. Pull requests should describe the user-visible change, list test commands run, link related issues, and include screenshots or recordings for UI changes.

Agent-Specific Instructions

When answering library, framework, SDK, API, CLI, or cloud-service questions, fetch current docs with Context7 before responding. Do not use Context7 for ordinary refactors, business-logic debugging, or code review.

Local project skills live in .agents/skills/. When a task matches one of these skills, open its SKILL.md and follow the workflow before changing code:

• chrome-testing: use for visual or browser testing, UI regression checks, screenshots, and local Chrome automation.
• composition-patterns: use when writing, reviewing, or refactoring React component APIs with boolean mode props, render slots, prop drilling, compound components, providers, or React 19 ref/context composition concerns.
• feature-sliced-design: use when deciding where code belongs in FSD layers, shaping slices and public APIs, placing assets, checking import boundaries, resolving cross-imports, or integrating framework patterns with FSD.
• kimi: use before making web design decisions or designs overall, including UI direction, redesigns, layout, typography, color, spacing, interaction states, responsive behavior, screenshots, mockups, landing pages, dashboards, and frontend visual critique. Kimi can use the agent-browser skill for browser inspection, screenshots, and visual QA when rendered UI matters.
• react-best-practices: use when working on React or Next.js components, App Router pages, Server Actions, data fetching, bundle size, render performance, hydration, or UI responsiveness.
• typescript-best-practices: use when touching TypeScript code that needs modern TS 5.x type safety, strictness, discriminated unions, satisfies, unknown, or safer type modeling.