diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md new file mode 100644 index 0000000..f4a3fc5 --- /dev/null +++ b/.agent/AGENTS.md @@ -0,0 +1,362 @@ +# AGENTS.md — AI Agent Szabályok és Irányelvek + +> **[CRITICAL SYSTEM DIRECTIVE FOR AI]** +> Mielőtt BÁRMILYEN feladatba belekezdesz, KÖTELEZŐ elolvasnod a `.agent/steering/` mappa összes fájlját! +> Ezek elolvasása nélkül ne írj és ne módosíts kódot! + +> Ez a fájl az elsődleges referencia minden AI-agent számára, amely ezen a projekten dolgozik. +> **Minden agent köteles ezt elolvasni és betartani mielőtt bármilyen munkát végez.** + +--- + +## 1. Projekt identitás + +- **Projekt neve**: websitedev (mozdIT Bt. weboldal) +- **Plane workspace**: `developments` (pm.llmdev.mozdit.hu) +- **Plane projekt**: `WebSite Dev` — azonosító: `MITHOME`, ID: `643f7055-1237-4912-912f-99ec49fd0f0e` +- **Típus**: Marketing weboldal fejlesztési projekt +- **Elsődleges nyelv**: Magyar (kommunikáció, weboldal tartalom, dokumentáció), Angol (kód, kommentek, commit üzenetek) +- **Célplatform**: Web (browser-first, mobile-responsive) +- **Fő könyvtár**: `proto/` — itt fut a Next.js alkalmazás + +--- + +## 2. Steering Documents + +A `.agent/steering/` mappában YAML frontmatterrel ellátott automatikusan betöltődő szabálydokumentumok találhatók: + +- **`development-rules.md`**: Kódolási és workflow szabályok (mindig aktív) +- **`architecture.md`**: Rendszerszintű tervezési elvek (mindig aktív) +- **`testing.md`**: Tesztelési stratégiák (`tests/**` fájloknál aktív) + +--- + +## 3. Alapelvek (Mandatory Principles) + +### 3.1 Kód minőség + +- Mindig olvass el minden érintett fájlt MIELŐTT módosítasz +- Soha ne törölj meglévő kódot anélkül, hogy megértenéd annak célját +- Minden változtatás legyen **minimális, célzott és indokolt** +- Ha bizonytalan vagy, kérdezz — ne találgass + +### 3.2 Konzisztencia + +- Kövess minden meglevő konvenciót, amit a kódbázisban találsz +- Ne vezess be új dependency-t jóváhagyás nélkül +- Az etablirozott naming convention-t kövesd következetesen + +### 3.3 Dokumentáció + +- Minden új funkció, API endpoint kapjon dokumentációt +- Komplex logikát `// WHY:` / `// DECISION:` / `// TRADEOFF:` jelölőkkel láss el +- Változtatások után frissítsd az érintett `.md` fájlokat és a `TODO.md`-t + +### 3.4 Biztonság + +- Soha ne commitolj secrets-t, API key-eket, jelszavakat +- Minden user input legyen validálva és sanitálva +- HTTPS mindenhol, HTTP redirect mindenhol + +### 3.5 Plane szinkronizáció utáni kötelező lépések + +> **KÖTELEZŐ szabály**: Minden feladat státuszváltás után: + +1. **Plane frissítése** — ticket státusz váltás (vagy `node plane-sync.js`) +2. **`TODO.md` frissítése** — lokális szinkronban tartás +3. **Git commit & push** — az összes módosított fájllal + +**Commit message formátum:** +``` +sync: update Plane issues + TODO [leírás] +``` + +--- + +## 4. Projekt struktúra + +``` +websitedev/ +├── proto/ # Fő Next.js alkalmazás (itt futtatsd a parancsokat!) +│ ├── src/ +│ │ ├── app/ # Next.js App Router (pages és API routes) +│ │ ├── components/ # React komponensek (Header, Footer, ThemeProvider) +│ │ ├── content/ # JSON tartalom-kezelő rendszer +│ │ ├── lib/ # Utility könyvtárak (MongoDB, Logger, Site Config) +│ │ ├── config/ # Statikus site konfiguráció +│ │ └── types/ # TypeScript típusdefiníciók +│ └── public/ # Statikus fájlok +├── docs/ # Projekt dokumentáció (Magyar) +├── .agent/ # AI keretrendszer (NE módosítsd véletlenül) +│ ├── steering/ # Auto-betöltődő szabályok +│ ├── workflows/ # Slash command workflow-ok +│ └── references/ # Ellenőrzőlisták +├── scripts/ # Szinkronizáló és reporting scriptek +├── TODO.md # Feladat követés (Linear tükörképe) +└── linear-sync.js # Linear szinkronizáló script +``` + +### Forbidden zones + +- `.env` fájlokat SOHA ne commitolj +- `node_modules/`, `.next/`, `dist/`, `build/` — csak `.gitignore`-ban + +--- + +## 5. Git konvenciók + +### Branch naming + +``` +feature/[rövid-leírás] → Új funkciók +fix/[bug-leírás] → Hibajavítások +hotfix/[kritikus-leírás] → Kritikus produkciós javítások +refactor/[terület] → Refaktorálás +docs/[terület] → Csak dokumentáció +chore/[feladat] → Build, deps, tooling +``` + +### Commit message formátum (Conventional Commits) + +``` +(): + +[opcionális részletes leírás] + +[opcionális: Closes ZEE-123] +``` + +**Típusok**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf` + +### Példák + +``` +feat(contact): add rate limiting to contact form API +fix(nav): hamburger menu not closing on mobile +docs(readme): update deployment instructions +``` + +--- + +## 6. Kódolási szabványok + +### Általános + +- Max line length: **120 karakter** +- Indentáció: **2 space** (soha tab) +- Trailing whitespace: **tilos** +- Fájl végén: **egy newline** + +### Naming conventions + +``` +fájlok: kebab-case.ts / PascalCase.tsx (komponensek) +komponensek: PascalCase +függvények: camelCase +konstansok: UPPER_SNAKE_CASE +CSS osztályok: kebab-case +adatbázis: snake_case (gyűjtemény nevek) +API endpoint: /kebab-case/:param +boolean: is/has/can prefix (pl. isActive, hasPermission) +``` + +### JavaScript/TypeScript + +- `const`/`let` — soha `var` +- Arrow functions preferált +- Async/await — soha callback hell +- Early return pattern +- Explicit error handling — soha silent failures + +### Fájlméret korlátok + +- **Soft limit**: 250–300 sor per fájl +- **Hard limit**: 400 sor +- Függvény max: **50 sor** (SRP: egy függvény = egy dolog) + +--- + +## 7. API konvenciók + +### Response formátum + +```json +{ + "success": true, + "data": { ... }, + "meta": { + "timestamp": "2026-01-01T00:00:00Z", + "version": "1.0" + } +} +``` + +### Error response + +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "Human-readable message", + "details": [ ... ] + } +} +``` + +### HTTP státusz kódok + +- `200` — Sikeres GET +- `201` — Sikeres POST (létrehozás) +- `204` — Sikeres DELETE (nincs body) +- `400` — Kliens hiba (validáció) +- `401` — Nem hitelesített +- `403` — Nem jogosult +- `404` — Nem található +- `500` — Szerver hiba + +--- + +## 8. Tesztelési elvek + +### Prioritás + +1. **Unit tesztek** — Pure functions, utilities, business logic +2. **Integration tesztek** — API endpoint-ok, DB műveletek +3. **E2E tesztek** — Kritikus user flow-ok + +### Coverage elvárás + +- Üzleti logika: **>80%** +- Utility függvények: **>90%** +- API endpoint-ok: minden happy path + fő error case-ek + +### Futtatás (`proto/` mappából) + +```bash +npm test # unit tesztek +npm run test:coverage # lefedettség riport +npm run test:browser # browser integration +npm run test:integration # Docker integration +npm run test:all # teljes suite +``` + +--- + +## 9. Intent Capture (Kódkomment konvenciók) + +Komplex logikánál kötelező strukturált kommenteket használni: + +```typescript +// WHY: +// DECISION: +// TRADEOFF: +``` + +**Mikor kötelező:** +- Architektúrális döntésnél +- Nem nyilvánvaló logikánál (pl. fire-and-forget pattern) +- Ismert trade-off esetén +- Ha az alternatívák nem egyértelműek + +--- + +## 10. Performance elvek + +- Képek: mindig optimalizált formátumban (WebP, AVIF), Next.js `` komponenssel +- Bundle size: figyelj, lazy loading ahol lehetséges +- API válaszidő cél: **<200ms** p95 +- Lighthouse score cél: **≥90** minden kategóriában + +--- + +## 11. Workflow-ok + +Az `.agent/workflows/` mappában találhatók az elérhető slash command workflow-ok: + +| Parancs | Leírás | +| --- | --- | +| `/new-feature` | Új funkció fejlesztési folyamata | +| `/fix-bug` | Hibajavítás folyamata | +| `/review` | Kód review checklist | +| `/deploy` | Deployment folyamata | + +--- + +## 12. References + +Az `.agent/references/` mappában gyorsan alkalmazható ellenőrzőlisták: + +| Reference | Terület | +| --- | --- | +| `accessibility-checklist.md` | WCAG 2.1 AA — minden UI komponens és oldal esetén | + +--- + +## 13. Context Engineering + +### Kontextus mennyiség +- Cél: **<2000 sor** legyen egyszerre aktív kontextusban +- Csak a jelenlegi task szempontjából releváns fájlokat töltsd be + +### Red Flag-ek (ha ilyeneket tapasztalsz) +- Az agent nem létező API-t vagy importot talál ki → kontextus hiány +- Output eltér a projekt konvencióitól → steering fájl nincs betöltve +- Minőség romlik ahogy a conversation hosszabb lesz → kontextus tömörítés kell + +--- + +## 14. Modellválasztás (Model Selection) + +### MCP műveletek — mindig gazdaságos modell + +Az MCP eszközök (Plane issue kezelés, Git műveletek, fájlrendszer lekérdezések) **nem igényelnek erős gondolkodást** — ezekhez mindig a leggazdaságosabb elérhető modellt kell használni: + +| Feladat típusa | Ajánlott modell | +| --- | --- | +| Plane issue létrehozás/frissítés | Claude Haiku / Gemini Flash | +| Git műveletek (commit, push, status) | Claude Haiku / Gemini Flash | +| Fájl olvasás, könyvtár listázás | Claude Haiku / Gemini Flash | +| TODO.md szinkronizáció | Claude Haiku / Gemini Flash | +| **Architektúra, kódírás, tervezés** | **Erősebb modell (Sonnet, Pro)** | +| **Komplex debugging, refaktorálás** | **Erősebb modell (Sonnet, Pro)** | + +### Alapelv + +> Az MCP hívások strukturált, determinisztikus műveletek — nem kreatív gondolkodást igényelnek. A drágább modell kapacitását tartsd fenn a tényleges fejlesztési feladatokra. + +--- + +## 14. Mikor kérdezz, mikor cselekedj? + +### Cselekedj önállóan ha: + +- A feladat egyértelműen leírja mit kell tenni +- Konvenciókat követsz (lásd fent) +- Kis, izolált változtatást teszel +- Bug fix, amit teljes biztonsággal azonosítottál + +### Kérdezz előbb ha: + +- Architektúrát kell megváltoztatni +- Új külső dependency-t vezetnél be +- A megoldás több lehetséges irányba mutat +- Biztonsági implikációk merülnek fel +- Production adatot érintenél + +--- + +## 15. Source-Driven Development + +Framework-specifikus kódnál ne emlékezetből dolgozz — a dokumentációt olvasd. + +### Forrás-hierarchia (csökkenő megbízhatóság) +1. **Hivatalos dokumentáció** (nextjs.org, react.dev, mongoosejs.com, stb.) +2. **Hivatalos blog / changelog** (breaking changes, migration guide-ok) +3. **Web szabványok** (MDN, web.dev) + +**Soha ne elsődleges forrásként:** Stack Overflow, tutorialok, AI összefoglalók. + +--- + +*Utoljára frissítve: 2026-04-26 | Verzió: 1.0.0 — Szintetizálva a tipruc AGENTS.md (v1.3.0) és a websitedev CLAUDE.md alapján* diff --git a/.agent/references/accessibility-checklist.md b/.agent/references/accessibility-checklist.md new file mode 100644 index 0000000..fc73ec4 --- /dev/null +++ b/.agent/references/accessibility-checklist.md @@ -0,0 +1,81 @@ +# Accessibility Checklist (WCAG 2.1 AA) + +Minden böngészős felület esetén kötelező ellenőrzőlista. +Az accessibility jogi követelmény és mérnöki minőségi standard. +Cél: **Lighthouse accessibility score ≥90** minden deploy előtt. + +--- + +## Keyboard és navigáció + +- [ ] Minden interaktív elem elérhető Tab-bal +- [ ] Látható focus indikátor minden fókuszálható elemen (`:focus-visible`) +- [ ] Nincs keyboard trap (el lehet navigálni minden elemről) +- [ ] Skip-to-content link az oldal tetején (hosszú nav esetén) +- [ ] Mobil hamburger menü: Escape bezárja, fókusz visszatér + +## Screen reader támogatás + +- [ ] Képek: alt text (informatív képeknél), üres alt dekoratív képeknél (`alt=""`) +- [ ] Form input-ok: minden inputhoz tartozik látható `