Skip to content

AGENTS.MD

Latest commit

 

History

History
59 lines (50 loc) · 2.86 KB

AGENTS.MD

File metadata and controls

59 lines (50 loc) · 2.86 KB
Raw

AGENTS.MD

Demo project: React + NestJS (TypeORM) monorepo. Coding challenge.

Structure

  • backend/ — NestJS + TypeORM + PostgreSQL (port 3000)
  • frontend/ — React + Vite + Redux Toolkit + shadcn/ui (port 5173)
  • docker-compose.yml — Postgres 17 (port 5432, db: demo, user: postgres/postgres)

Docs

  • Start: read relevant docs/*.md before coding.
  • Follow read_when hints; update docs when behavior/API changes.

Workflow

  • Commits: Conventional Commits (feat|fix|refactor|build|ci|chore|docs|style|perf|test).
  • Files < 500 LOC; split when approaching limit.
  • Fix root cause, not band-aid.
  • Before handoff: run npm run verify (full lint + typecheck + test).

Multi-Agent (single-branch workflow)

  • Before editing: run git pull --rebase && git status && git diff to see other agents' changes.
  • After editing: commit immediately (small, atomic). Do not batch unrelated changes.
  • Unrecognized changes in the working tree: assume another agent made them. Do not revert or undo -- keep going and focus on your task. If they cause a conflict, stop and ask the user.
  • Destructive git ops (reset --hard, clean, push --force) are forbidden unless explicitly requested.
  • No git stash -- if you need to context-switch, commit to a WIP branch.
  • Before handoff: run npm run verify (full lint + typecheck + test).
  • Read the relevant docs/*.md before touching backend or frontend code. Follow read_when hints.
  • Update docs when you change behavior or APIs. Do not ship without updating docs.
  • Files must stay under 500 LOC. Split proactively.

Backend (NestJS)

  • Read docs/backend.md when working on API/entities/services.
  • Entities go in backend/src/<module>/entities/.
  • DTOs go in backend/src/<module>/dto/.
  • One module per domain concept; each module owns its controller, service, entities.
  • Use ConfigService for all env vars; never hardcode.
  • synchronize: true is fine for this demo; never in prod.

Frontend (React)

  • Read docs/frontend.md when working on UI/state/components.
  • Components: frontend/src/components/ (shared), frontend/src/features/<name>/ (feature-scoped).
  • State: Redux Toolkit slices in frontend/src/features/<name>/.
  • UI: shadcn/ui components in frontend/src/components/ui/.
  • API calls: RTK Query or async thunks; keep fetch logic out of components.
  • Path alias: @/ maps to frontend/src/.

Stack Versions

  • Node 20+, TypeScript, PostgreSQL 17.
  • Backend: NestJS 11, TypeORM, @nestjs/config.
  • Frontend: React 19, Vite 6, Redux Toolkit, shadcn/ui, Tailwind CSS.

Commands

  • Postgres: docker compose up -d
  • Backend: cd backend && npm run start:dev
  • Frontend: cd frontend && npm run dev
  • Backend tests: cd backend && npm test
  • Frontend lint: cd frontend && npm run lint
  • Full gate: npm run verify (run before every commit/handoff)
  • Docs overview: sh scripts/docs-list.sh — run at session start.