Skip to content

AGENTS.md

Latest commit

 

History

History
298 lines (209 loc) · 11.3 KB

AGENTS.md

File metadata and controls

298 lines (209 loc) · 11.3 KB

Repository Guidelines

Project Structure & Module Organization

  • Core application lives under app/, with App Router layouts in app/(auth)/, app/(dashboard)/.
  • Supporting UI atoms live in components/; shared hooks in hooks/, shared contexts in contexts/.
  • Configuration lives in next.config.ts, app.config.ts (if present), and config/.
  • Shared utilities and lib code are in lib/; type definitions in types/.
  • i18n locale files live under i18n/locales/ (structure must match the old project).
  • Static assets belong in public/ or assets/.
  • Tests belong in tests/ (mirror source structure when tests exist).
  • UI vs feedback: components/ui/ holds presentational, declarative UI primitives (e.g. Button, Dialog). lib/feedback/ holds global imperative APIs for toast and confirm dialogs (MessageProvider/useMessage, DialogProvider/useDialog). Use @/lib/feedback/message and @/lib/feedback/dialog for imperative feedback; use @/components/ui/* for declarative UI.

Build, Test, and Development Commands

  • pnpm dev – start the Next.js development server with hot reload.
  • pnpm build – create a production build.
  • pnpm start – run the production bundle locally.
  • pnpm lint – run ESLint.
  • pnpm test:run – run the test suite (when configured).
  • pnpm tsc --noEmit – perform a strict TypeScript type check (or rely on next build for type-checking).

Mandatory Code Quality Checks

⚠️ CRITICAL: These checks MUST pass before every commit.

Before committing any code changes, you MUST run and pass:

  1. Lockfile Sync Check: pnpm install --frozen-lockfile

    • Ensures pnpm-lock.yaml is in sync with package.json
    • MUST run pnpm install after modifying package.json and commit the updated pnpm-lock.yaml
    • CI will fail if the lockfile is out of sync.

  2. TypeScript Type Check: pnpm tsc --noEmit (or pnpm build)

    • Ensures all TypeScript types are correct.
    • Must have zero errors before committing.

  3. Lint Check: pnpm lint

    • Ensures code follows ESLint rules.
    • Fix issues before committing.

  4. Format Check (if Prettier is configured): pnpm prettier --check .

    • Ensures consistent formatting.
    • If it fails, run pnpm lint:fix or pnpm format (when available) to auto-fix.

  5. Test Coverage Check (when tests exist): Review and update tests for code changes

    • MUST review test cases when modifying code: add tests for new features, update tests for changed behavior, remove tests for removed features.
    • Run pnpm test:run to ensure all tests pass.
    • Ensure test cases accurately reflect the current implementation.

Automated Enforcement: If a pre-commit hook exists, it will run these checks. If any check fails, the commit will be blocked.

Quick Fix: If checks fail:

  1. Run pnpm install to sync lockfile (if package.json changed).
  2. Fix ESLint/Prettier issues.
  3. Address TypeScript errors manually.
  4. Review and update test cases as needed, then run pnpm test:run to verify.

Coding Style & Naming Conventions

  • Use Prettier defaults when configured; run pnpm lint:fix or pnpm format after making changes.
  • React components use functional components with TypeScript; prefer hooks and custom hooks for shared logic.
  • Component files use kebab-case (e.g. bucket-selector.tsx); reference them with PascalCase in JSX (e.g. <BucketSelector />).
  • Override shadcn primitives outside components/ui/; never edit files in that directory directly.
  • Render tabular data with the shared DataTable + useDataTable utilities unless a specific requirement makes them unsuitable.
  • Language pack files must follow the structure used in the old project; do not alter i18n layout or keys arbitrarily.

Component structure and naming

  • Directories: Group by domain/feature; use plural for domain folders (e.g. buckets/, user/, object/).
  • File names: kebab-case; do not repeat the directory name in the filename (e.g. under buckets/ use info.tsx, new-form.tsx, selector.tsx instead of bucket-info.tsx, bucket-new-form.tsx). The path already provides context.
  • Component names: PascalCase, aligned with the domain and purpose (e.g. BucketInfo, UserDropdown); component names may still include the domain when used in JSX for clarity.
  • Forms: Use consistent patterns per domain: XxxNewForm / XxxEditForm or XxxForm; files can be new-form.tsx, edit-form.tsx, form.tsx under the domain folder.
  • Placement: Components used only by one domain live in that domain folder; components reused by 3+ different domain pages may stay at root or under components/shared/ (document if so).

Testing Guidelines

  • When tests are configured, add new suites under tests/, mirroring source structure.
  • Name files *.spec.ts or *.test.ts.
  • Keep tests deterministic; mock network calls through provided hooks or context.
  • ⚠️ CRITICAL: Every code change MUST include corresponding test updates when tests exist:
    • New features: Add comprehensive test cases covering happy paths and edge cases.
    • Modified behavior: Update existing tests to reflect new implementation.
    • Removed features: Remove or update tests for deprecated/removed functionality.
    • Bug fixes: Add regression tests to prevent future occurrences.
  • Run pnpm test:run before submitting any changes.

Commit & Pull Request Guidelines

  • Follow conventional, action-oriented commit subjects (e.g. feat: add bucket selector, fix: correct object list pagination).
  • Each pull request should include: a concise summary, linked issue or task, screenshots for UI work, and testing notes.
  • Keep PRs scoped; large refactors should be coordinated in advance.
  • Commit message and PR title must be in English.
  • When a PR template exists (e.g. .github/pull_request_template.md), follow it strictly.

UI Theme Overrides

  • Apply visual tweaks (e.g. removing shadows, altering colors) at usage sites via classes such as class="shadow-none".
  • When extending shadcn components, create wrapper components (e.g. BucketSelector.tsx) instead of forking primitives.
  • Do not change base colors or theme variables defined in console-new unless explicitly required by the migration plan.

Development Guidelines

Philosophy

Core Beliefs

  • Incremental progress over big bangs – Small changes that compile and pass tests.
  • Learning from existing code – Study and plan before implementing.
  • Pragmatic over dogmatic – Adapt to project reality.
  • Clear intent over clever code – Be boring and obvious.

Simplicity Means

  • Single responsibility per function/class.
  • Avoid premature abstractions.
  • No clever tricks – choose the boring solution.
  • If you need to explain it, it’s too complex.

Process

1. Planning & Staging

Break complex work into 3–5 stages. Document in IMPLEMENTATION_PLAN.md only when explicitly requested (see Documentation Restriction):

## Stage N: [Name]

**Goal**: [Specific deliverable]
**Success Criteria**: [Testable outcomes]
**Tests**: [Specific test cases]
**Status**: [Not Started|In Progress|Complete]
  • Update status as you progress.
  • Remove the file when all stages are done.

2. Implementation Flow

  1. Understand – Study existing patterns in the codebase.
  2. Test – Write tests first (red).
  3. Implement – Minimal code to pass (green).
  4. Refactor – Clean up with tests passing.
  5. Commit – With a clear message linking to the plan.

3. When Stuck (After 3 Attempts)

CRITICAL: Maximum 3 attempts per issue, then STOP.

  1. Document what failed:

    • What you tried.
    • Specific error messages.
    • Why you think it failed.

  2. Research alternatives:

    • Find 2–3 similar implementations.
    • Note different approaches used.

  3. Question fundamentals:

    • Is this the right abstraction level?
    • Can this be split into smaller problems?
    • Is there a simpler approach entirely?

  4. Try a different angle:

    • Different library/framework feature?
    • Different architectural pattern?
    • Remove abstraction instead of adding?

Technical Standards

Architecture Principles

  • Composition over inheritance – Use dependency injection.
  • Interfaces over singletons – Enable testing and flexibility.
  • Explicit over implicit – Clear data flow and dependencies.
  • Test-driven when possible – Never disable tests; fix them.

Code Quality

  • Every commit must:

    • Compile successfully.
    • Pass all existing tests.
    • Include tests for new functionality (when tests exist).
    • Follow project formatting/linting.

  • Before committing:

    • Run formatters/linters.
    • Self-review changes.
    • Ensure commit message explains "why".

Error Handling

  • Fail fast with descriptive messages.
  • Include context for debugging.
  • Handle errors at the appropriate level.
  • Never silently swallow exceptions.

Decision Framework

When multiple valid approaches exist, choose based on:

  1. Testability – Can I easily test this?
  2. Readability – Will someone understand this in 6 months?
  3. Consistency – Does this match project patterns?
  4. Simplicity – Is this the simplest solution that works?
  5. Reversibility – How hard is it to change later?

Project Integration

Learning the Codebase

  • Find 3 similar features/components.
  • Identify common patterns and conventions.
  • Use the same libraries/utilities when possible.
  • Follow existing test patterns.

Tooling

  • Use the project’s existing build system.
  • Use the project’s test framework.
  • Use the project’s formatter/linter settings.
  • Don’t introduce new tools without strong justification.

Quality Gates

Definition of Done

  • Tests written and passing (when applicable).
  • Code follows project conventions.
  • No linter/formatter warnings.
  • Commit messages are clear.
  • Implementation matches plan.
  • No TODOs without issue numbers.

Test Guidelines

  • Test behavior, not implementation.
  • One assertion per test when possible.
  • Clear test names describing the scenario.
  • Use existing test utilities/helpers.
  • Tests should be deterministic.

Documentation Restriction

Unless explicitly requested, do not produce any summary-type, plan-type, analysis-type, or similar documentation in the project. This includes but is not limited to:

  • IMPLEMENTATION_PLAN.md, SUMMARY.md, PLAN.md, CHANGELOG.md
  • Migration summaries, progress reports, or task completion reports
  • Analysis documents (e.g. refactor analysis, page/code analysis, architecture analysis, *_ANALYSIS*.md)
  • Any document created proactively to describe or track work

Create such documents only when the user explicitly asks for them.

Important Reminders

NEVER:

  • Use --no-verify to bypass commit hooks.
  • Disable tests instead of fixing them.
  • Commit code that doesn’t compile.
  • Make assumptions – verify with existing code.
  • During migration: modify page text, add UI components, or change component positions without plan approval.

ALWAYS:

  • Commit working code incrementally.
  • Update plan documentation as you go.
  • Learn from existing implementations if exists (especially console-old).
  • Stop after 3 failed attempts and reassess.