AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• app/ hosts Next.js routes, layouts, and server actions for the web UI.
• components/, hooks/, store/, and utils/ group reusable UI pieces, custom hooks, Zustand stores, and shared helpers.
• services/, api-client/, and server/ encapsulate API integrations, background jobs, and Hono handlers; keep external calls here.
• public/ stores static assets, while docs/ and schema/ capture product and API documentation.
• Tests and fixtures live under test/; mirror the runtime folder structure when adding coverage.

Build, Test, and Development Commands

• npm run dev boots the local Next.js app on port 3200; use npm run dev:restart when you need a clean background process.
• npm run build compiles the production bundle, and npm start serves the build output.
• npm run lint runs ESLint with the Next.js config; npm run lintfix chains Prettier and ESLint for autofixes.
• npm test, npm run test:watch, and npm run test:ui execute Vitest in batch, watch, or UI mode.
• Use npm run generate:dummy-screenshots or npm run prepare:dummy-images to refresh design placeholders referenced in demos.

Coding Style & Naming Conventions

• TypeScript and modern React patterns are expected; default to server components unless client interactivity is required.
• Formatting is enforced by Prettier (2-space indentation, single quotes, trailing commas) and ESLint; run lint before committing.
• Name React components and Zustand stores in PascalCase, hooks with the use prefix, and internal helpers in camelCase.
• Keep import paths absolute via the @ alias rather than deep relative chains, and group CSS or Tailwind utilities near their components.

Testing Guidelines

• Write unit and integration specs with Vitest; locate files beside the code (*.test.ts[x]) or under test/ mirroring the module path.
• Mock external services through helpers in services/ to avoid real network calls, and assert both success and error flows.
• Run npm test plus npm run lint before pushing; add snapshots only when the UI surface is stable.

Commit & Pull Request Guidelines

• Follow Conventional Commits (feat:, fix:, chore:) as in the git log; include localization context when touching Japanese copy.
• Each pull request should link the relevant issue, describe behavior changes, note required environment updates, and attach UI screenshots or recordings.
• Confirm CI passes locally (npm run lint, npm test, npm run build) and mention any skipped checks or follow-up tasks in the description.

Configuration Tips

• Secrets live in .env.local; never commit credentials or API tokens—consult api-config.json for expected keys.
• Update documentation in docs/ when endpoints or flows change, and surface breaking environment changes in the pull request summary.