AGENTS.md

1# AGENTS Guidelines for This Repository
2 
3This repository contains a Next.js application located in the root of this repository. When
4working on the project interactively with an agent (e.g. the Codex CLI) please follow
5the guidelines below so that the development experience – in particular Hot Module
6Replacement (HMR) – continues to work smoothly.
7 
8## 1. Use the Development Server, **not** `npm run build`
9 
10* **Always use `npm run dev` (or `pnpm dev`, `yarn dev`, etc.)** while iterating on the
11  application.  This starts Next.js in development mode with hot-reload enabled.
12* **Do _not_ run `npm run build` inside the agent session.**  Running the production
13  build command switches the `.next` folder to production assets which disables hot
14  reload and can leave the development server in an inconsistent state.  If a
15  production build is required, do it outside of the interactive agent workflow.
16 
17## 2. Keep Dependencies in Sync
18 
19If you add or update dependencies remember to:
20 
211. Update the appropriate lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`).
222. Re-start the development server so that Next.js picks up the changes.
23 
24## 3. Coding Conventions
25 
26* Prefer TypeScript (`.tsx`/`.ts`) for new components and utilities.
27* Co-locate component-specific styles in the same folder as the component when
28  practical.
29 
30## 4. Useful Commands Recap
31 
32| Command            | Purpose                                            |
33| ------------------ | -------------------------------------------------- |
34| `npm run dev`      | Start the Next.js dev server with HMR.             |
35| `npm run lint`     | Run ESLint checks.                                 |
36| `npm run test`     | Execute the test suite (if present).               |
37| `npm run build`    | **Production build – _do not run during agent sessions_** |
38 
39---
40 
41Following these practices ensures that the agent-assisted development workflow stays
42fast and dependable.  When in doubt, restart the dev server rather than running the
43production build.
44