Skip to content

AGENTS.md

Latest commit

 

History

History
311 lines (216 loc) · 12.3 KB

AGENTS.md

File metadata and controls

311 lines (216 loc) · 12.3 KB
Raw

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

  • Node version requirement: Before running pnpm commands (especially checks/tests), run nvm use v22 in this repository.

  • 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

  • For every Console UI, interaction, settings, form, dialog, table, responsive-layout, or visual-review change, read and follow skills/rustfs-console-design-guide/SKILL.md before editing. Use skills/ui-audit/SKILL.md as the audit workflow and the Console design guide as the source of design decisions.
  • 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.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Keep this block, including in commits. It is part of the project's agent setup, maintained by next dev for every agent that works here. If it appears as an uncommitted change, that is intentional — commit it as-is. Do not remove it to clean up a diff; it will be regenerated.