Skip to content

Commit 36eb0e7

Browse files
xcodeassociatedxcodeassociated
committed
Add project guidelines and development conventions (AGENTS.md)
1 parent 0cbb7d8 commit 36eb0e7

1 file changed

Lines changed: 212 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
# AGENTS.md – Guidelines for Automated Agents
3+
---
4+
5+
## 📋 Table of Contents
6+
7+
1. [Project Overview](#project-overview)
8+
2. [Common Development Commands](#common-development-commands)
9+
- [Running a Single Test](#running-a-single-test)
10+
3. [Code‑Style & Conventions](#code‑style--conventions)
11+
- [Formatting (Prettier)](#formatting-prettier)
12+
- [Imports & Path Aliases](#imports--path‑aliases)
13+
- [TypeScript Rules](#typescript-rules)
14+
- [Naming Conventions](#naming-conventions)
15+
- [Error Handling](#error-handling)
16+
- [React & JSX Guidelines](#react--jsx-guidelines)
17+
- [Redux Toolkit Patterns](#redux‑toolkit-patterns)
18+
- [Apollo GraphQL Usage](#apollo‑graphql-usage)
19+
- [Testing Practices (Vitest & RTL)](#testing-practices-vitest--rtl)
20+
4. [Linting & CI Details](#linting--ci-details)
21+
5. [Cursor / Copilot Rules (if any)](#cursor--copilot-rules-if-any)
22+
6. [Helpful References for Agents](#helpful-references-for-agents)
23+
24+
---
25+
26+
## Project Overview
27+
28+
- **Tech Stack**: React 18, TypeScript, Vite, Tailwind CSS, Redux Toolkit (with persistence), Apollo Client, Keycloak, i18next.
29+
- **Package Manager**: `npm` / `bun`. All scripts are defined in `package.json` and are **compatible with `bun run <script>`**.
30+
- **Path Alias**: `@/*` resolves to `src/*` (defined in `vite.config.ts` & `tsconfig.json`).
31+
- **Code Generation**: GraphQL types & hooks are generated via `npm run generate:graphql`.
32+
- **Testing**: Vitest + React Testing Library + MSW for API mocking.
33+
- **Formatting**: Prettier with `prettier-plugin-tailwindcss` (installed but configuration falls back to defaults).
34+
35+
---
36+
37+
## Common Development Commands
38+
39+
| Command | Description |
40+
| -------------------------- | ------------------------------------------------------------------- |
41+
| `bun run dev` | Starts Vite dev server (default port 3000). |
42+
| `bun run build` | Type‑checks (`tsc -b`) then produces production bundle. |
43+
| `bun run preview` | Serves the production build locally (`vite preview`). |
44+
| `bun run prod` | Serves built assets with `serve -s dist`. |
45+
| `bun run lint` | Runs ESLint with `--max-warnings 0` – any warning fails the CI. |
46+
| `bun run test` | Executes **all** Vitest tests in CI mode (`--run`). |
47+
| `bun run test:ui` | Opens Vitest UI for interactive debugging. |
48+
| `bun run coverage` | Generates coverage report (`--coverage`). |
49+
| `bun run generate:graphql` | Re‑generates GraphQL hooks/types from `src/graphql/schema.graphql`. |
50+
51+
### Running a Single Test
52+
53+
Agents often need to run or debug a specific test file. Use any of the following patterns:
54+
55+
```bash
56+
# Run a specific file (absolute or relative to repo root)
57+
bun run test -- src/components/Button.test.tsx
58+
# Run tests matching a test name / regex pattern
59+
bun run test -- -t "Button renders correctly"
60+
# Run only tests in a focused file (Vitest `--run` + `--watch` optional)
61+
bun run test -- src/pages/dashboard/Dashboard.test.ts --run
62+
```
63+
64+
**Tip:** The double‑dash `--` separates the npm script arguments from the script itself.
65+
66+
---
67+
68+
## Code‑Style & Conventions
69+
70+
All agents should respect the linting rules defined in `.eslintrc.cjs`. The following conventions are **enforced** (or strongly recommended) by that config and the project's overall philosophy.
71+
72+
### Formatting (Prettier)
73+
74+
- Use **2‑space indentation** (Prettier default).
75+
- **Trailing commas** where valid (objects, arrays, function parameters).
76+
- **Single‑quotes** for strings, **double‑quotes** only when the string contains a single‑quote.
77+
- **Semi‑colons** are required (`semi: true`).
78+
- **Tailwind ordering**: thanks to `prettier-plugin-tailwindcss`, class names are automatically sorted alphabetically.
79+
- Run `npm run lint` (which runs ESLint with Prettier integration) before committing.
80+
81+
### Imports & Path Aliases
82+
83+
1. **Group order** – separate with a blank line:
84+
85+
```ts
86+
// 1️⃣ External packages
87+
import React from 'react'
88+
import { useQuery } from '@apollo/client'
89+
90+
// 2️⃣ Internal absolute imports (using @ alias)
91+
import { Button } from '@/components/ui/Button'
92+
import { useAppDispatch } from '@/store/hooks'
93+
94+
// 3️⃣ Relative imports for sibling files
95+
import type { Props } from './MyComponent.types'
96+
import './MyComponent.css'
97+
```
98+
99+
2. **Side‑effect only imports** (`import './polyfills';`) should appear **after** external imports but **before** internal imports.
100+
3. **Alphabetical within groups**.
101+
4. **Avoid wildcard imports** (`import * as Foo from ...`) unless you need the whole namespace.
102+
5. **Prefer named imports** over default when the exported module provides multiple members.
103+
104+
### TypeScript Rules
105+
106+
- **`noImplicitAny`** and **`strict`** are enabled – never use `any`; prefer `unknown` or a precise type.
107+
- **Explicit return types** for exported functions and React components.
108+
- **Prefer `interface`** for object shapes that are extended; use `type` for unions, primitives, or tuples.
109+
- **Readonly** for props and state objects that never change (`Readonly<T>` or `as const`).
110+
- **Utility Types** (`Partial`, `Pick`, `Omit`) should be used sparingly – keep them readable.
111+
- **Zod** is the validation library; always validate external data (`safeParse`) before using it.
112+
- **Enums** only for a **closed set of string literals** that need runtime values; otherwise use union string literals.
113+
114+
### Naming Conventions
115+
116+
| Entity | Convention | Example |
117+
| -------------------- | ------------------------------------------------------------------ | --------------------------------- |
118+
| Components | **PascalCase** (+ optional `Component` suffix) | `UserCard`, `SettingsModal` |
119+
| Props types | PascalCase ending in `Props` | `UserCardProps` |
120+
| Hooks | `use` prefix + **camelCase** | `useAuth`, `useFetchUsers` |
121+
| Redux slices | `camelCase` slice name, file `sliceNameSlice.ts` | `counterSlice` |
122+
| Actions / thunks | `camelCase` prefixed with verb | `fetchUserById` |
123+
| Constants / env vars | **SCREAMING_SNAKE_CASE** (env vars start with `VITE_`) | `VITE_APP_BACKEND_URL` |
124+
| Files & directories | **kebab-case** (except React component files which use PascalCase) | `user-profile/`, `login-form.tsx` |
125+
126+
### Error Handling
127+
128+
- **Async functions**: `try { … } catch (err) { /* handle */ }` – re‑throw only if the caller can do something useful.
129+
- **Network / GraphQL errors**: map to user‑friendly messages; never expose raw stack traces.
130+
- **Zod validation**: use `result.success ? result.data : handleError(result.error)`.
131+
- **React error boundaries**: provide a fallback UI for unexpected render errors.
132+
- **Redux Toolkit**: `createAsyncThunk` automatically provides `rejected` action payload – keep error messages concise.
133+
134+
### React & JSX Guidelines
135+
136+
- **Functional components only** – no class components.
137+
- **Hook Rules**: call hooks at the top level, never inside conditions or loops.
138+
- **Destructure props** directly in the function signature when possible.
139+
- **JSX Props**: boolean props omitted when true (`<Button disabled />`).
140+
- **Conditional rendering**: use `&&` for simple cases, ternary for two alternatives, avoid nested ternaries.
141+
- **Memoization**: `useMemo` for expensive calculations, `useCallback` for stable callbacks passed to children.
142+
- **Styling**: Tailwind classes **only** – no custom CSS unless required for animations.
143+
- **ARIA**: ensure accessible attributes (`aria-label`, `role`, etc.) are present on interactive elements.
144+
145+
### Redux Toolkit Patterns
146+
147+
```ts
148+
// store/store.ts – typed hooks
149+
export const useAppDispatch = () => useDispatch<AppDispatch>()
150+
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector
151+
```
152+
153+
- **Slices** should be kept small – one slice per domain.
154+
- **Immer** is used automatically; mutate state directly in reducers.
155+
- **Async logic** lives in `createAsyncThunk`; keep reducers pure.
156+
- **Selectors** are memoized with `createSelector` when derived data is expensive.
157+
158+
### Apollo GraphQL Usage
159+
160+
- **Generated hooks** (`useGetUserQuery`, `useUpdateUserMutation`) are the only way to interact with the API.
161+
- **Error/Loading** handling pattern:
162+
```tsx
163+
const { data, loading, error } = useGetUserQuery({ variables: { id } })
164+
if (loading) return <Spinner />
165+
if (error) return <ErrorMessage error={error} />
166+
// render UI with data
167+
```
168+
- **Cache updates**: use `refetchQueries` or the `update` function for mutations that affect the cache.
169+
- **Authentication**: token is injected via Apollo `authLink` – never manually attach `Authorization` header in components.
170+
171+
### Testing Practices (Vitest & RTL)
172+
173+
- **File naming**: `ComponentName.test.tsx` placed alongside the component or in `__tests__/`.
174+
- **Test runner**: `bun run test` (CI) or `bun run test:ui` for debugging.
175+
- **Render**: use `render(<Component …/>)` from `@testing-library/react`.
176+
- **Assertions**: prefer `expect(element).toBeInTheDocument()` and `toHaveAttribute`.
177+
- **Mocking**: use **MSW** for network calls; define handlers in `src/mocks/handlers.ts`.
178+
- **Coverage**: aim for **≥ 90 %** on new/changed code; `bun run coverage` will output the report.
179+
- **Selective test runs**: use `.only` or the `-t` flag (see _Running a Single Test_ above).
180+
181+
---
182+
183+
## Linting & CI Details
184+
185+
- The **ESLint** config extends `eslint:recommended`, `@typescript-eslint/recommended`, and `plugin:react-hooks/recommended`.
186+
- **Prettier** is enforced via `eslint-config-prettier` – any formatting deviation is reported as an ESLint error.
187+
- **`npm run lint`** fails on **any warning** (`--max-warnings 0`).
188+
- CI (GitHub Actions) runs `npm ci && npm run lint && npm run test && npm run coverage`.
189+
- No `--fix` flag is used in CI – agents must commit correctly formatted code.
190+
191+
---
192+
193+
## Cursor / Copilot Rules (if any)
194+
195+
The repository does **not** contain a `.cursor/` directory or a `.github/copilot-instructions.md` file, so there are no additional cursor‑specific or Copilot‑specific guidelines to enforce.
196+
197+
---
198+
199+
## Helpful References for Agents
200+
201+
- **Vite Guide** – https://vitejs.dev/guide/
202+
- **Vitest Docs** – https://vitest.dev/guide/
203+
- **React Hook Rules** – https://reactjs.org/docs/hooks-rules.html
204+
- **Redux Toolkit FAQ** – https://redux-toolkit.js.org/faq
205+
- **Apollo Client Docs** – https://www.apollographql.com/docs/react/
206+
- **Zod Handbook** – https://zod.dev/
207+
- **Tailwind CSS** – https://tailwindcss.com/docs
208+
- **Prettier Plugin TailwindCSS** – https://github.com/tailwindlabs/prettier-plugin-tailwindcss
209+
210+
---
211+
212+
_End of file – agents should keep this document up to date as the project evolves._

0 commit comments

Comments
 (0)