A tökéletes AI fejlesztői ügynök szabályrendszer megtervezése (AGENTS.md)
Eleged van abból, hogy az AI kódoló ügynökök engedély nélküli csomagokat telepítenek, újra feltalálják az API struktúrákat, 10 üzenet után elfelejtik a projekt konvencióit, vagy hibás adatbázis-migrációkat hoznak létre? Tanuld meg, hogyan építhetsz olyan determinisztikus szabályrendszereket, amelyek vezető mérnöki (lead architect) precizitással irányítják az ügynököket bármilyen technológiai környezetben.
Elmélet: Az ügynökirányítás kognitív alapjai
1.1 Az alapvető paradigmaváltás
A hatékony szabályok megírásához meg kell különböztetnünk a fejlesztői AI három evolúciós generációját. Sok fejlesztő tévesen egyszerű csevegőbotként kezeli az autonóm kódoló ügynököket, ami folyamatos frusztrációhoz vezet:
| Generáció | Paradigma | Eszközök | Működési mechanizmus | Elsődleges hibaforrás |
|---|---|---|---|---|
| 1. Generáció | Soron belüli kódkiegészítés | Copilot Tab | 1–5 sort jósol meg a közvetlen környező forráskód alapján. | Szintaktikai elírások, rossz változónevek. |
| 2. Generáció | Csevegőablakos asszisztens | ChatGPT, Claude Web | A fejlesztő kódrészleteket másol a chatbe, majd a választ visszamásolja. | Elavult kontextus; manuális integráció szükséges az ember részéről. |
| 3. Generáció | Autonóm Ügynökök | Antigravity, Cursor, Claude Code, Cline | Közvetlen terminál végrehajtás, fájlolvasás és -írás, fordítóprogram ellenőrzések, valamint többlépéses ügynök-ciklusok valódi eszközhasználattal. | Architekturális elsodródás, függőség-szennyezés, csendes törő módosítások. |
1.2 Az ügynök-hallucináció három halálos bűne
AGENTS.md) az 1. üzenetben lefektetett szabályokat a 12. üzenetre a kontextus-entrópia miatt a modell elfelejti.
1.3 A "Magyarázd el a MIÉRT-et" Szabály (LLM Kognitív Pszichológia)
A hagyományos fejlesztésben a vezetők gyakran száraz parancsokat adnak, mint például: "Minden URL végére tegyél perjelet." Az LLM-ek esetében azonban a technikai indoklást tartalmazó szabályok betartási aránya több mint háromszorosa a dogmatikus parancsokénak. A működési mechanizmus megmagyarázása aktiválja a hibamegelőzéssel kapcsolatos neurális figyelmi fejeket:
Rossz Szabály (Dogmatikus Parancs)
Mindig tegyél lezáró perjelet minden API URL végére mind a backend útvonalakon, mind a frontend kérésekben.
Miért bukik el: Az LLM felületes formázási preferenciaként kezeli. Egy bonyolultabb refaktorálás során rendszeresen elhagyja.
Tökéletes Szabály (Technikai Indoklással)
Minden backend URL útvonalnak és kliensoldali kérésnek kötelezően lezáró perjelet ('/') kell tartalmaznia. A záró perjel elhagyása miatt a Django HTTP 301 átirányítást ad ki (APPEND_SLASH=True), ami eldobja a POST/PUT/DELETE kérések törzsét (payload), és üres GET kéréssé alakítja azokat.
Miért működik: A transformer figyelem összekapcsolja a "záró perjelet" a "HTTP 301 POST adatvesztés" megelőzésével. A modell proaktívan ellenőrzi minden kiadott URL-jét.
1.4 Token-Ökonómia: Információsűrűség vs. Felfújás
Soha ne másold be a teljes vállalati wikit vagy 5000 sornyi API specifikációt az ügynök szabályfájljába. A kontextusablak túlterhelése felhígítja a figyelmet és rontja a modell következtetési képességét.
Hogyan működnek a szabályok a különböző fejlesztői környezetekben (IDE)
A modern AI-alapú fejlesztői környezetek (IDE) eltérő felderítési útvonalakat, hatóköri mechanizmusokat és prioritási szinteket alkalmaznak a szabályfájlokra. Ezen mechanizmusok ismerete biztosítja, hogy a fejlesztőcsapatod zökkenőmentesen működjön együtt, függetlenül attól, hogy az egyes mérnökök melyik eszközt részesítik előnyben.
| IDE / Eszköz | Cél szabályfájl | Hatóköri mechanizmus | Végrehajtási képesség | Szabály prioritása |
|---|---|---|---|---|
| Google Antigravity | .agents/AGENTS.md.agents/rules/*.md |
Globális munkaterület + igény szerinti skills/ |
Teljes homokozó terminál + MCP + fájlműveletek | Szigorú felhasználói szabályok (a legmagasabb prioritás az alapértelmezések felett) |
| Cursor | .cursor/rules/*.mdc(régi: .cursorrules) |
Glob minták (pl. globs: backend/**/*.py) |
Terminál Agent Mód | A felhasználói szabályok felülbírálják az alapértelmezett ügynökutasításokat |
| Windsurf (Codeium) | .windsurfrules |
Projekt gyökérkönyvtára | Cascade következtetési motor | Közvetlenül beillesztve a Cascade jegyzettömb kontextusába |
| Claude Code (Anthropic) | CLAUDE.md |
Projekt gyökérkönyvtára | Autonóm Bash CLI eszköz | Munkamenet-indítási kontextus inicializáció |
| GitHub Copilot | .github/copilot-instructions.md |
Repozitórium gyökérkönyvtára | Chat & Workspace kiterjesztések | Csevegési prompt-kontextus kiegészítés |
| Cline / Roo Code | .clinerules |
Mód-alapú (Code, Architect, Ask) | VS Code munkaterület végrehajtás | Rendszerprompt injektálás |
2.2 Univerzális, Kereszt-IDE Harmonizáció
Valós mérnökcsapatokban egyes fejlesztők Antigravity-t, mások Cursort, megint mások Claude Code-ot használnak. Az 5 különálló szabályfájl karbantartása helyett tartsd a .agents/AGENTS.md (vagy gyökérbeli AGENTS.md) fájlt kanonikus egyetlen hiteles forrásként (SSOT), és hozz létre rá szimbolikus linkeket (symlink) a többi eszköz számára:
# Futtasd a projekt gyökérkönyvtárából
mkdir -p .cursor/rules && ln -sf ../.agents/AGENTS.md .cursor/rules/AGENTS.mdc
ln -sf .agents/AGENTS.md .windsurfrules
ln -sf .agents/AGENTS.md CLAUDE.md
mkdir -p .github && ln -sf ../.agents/AGENTS.md .github/copilot-instructions.mdElőkészületek: Az elengedhetetlen tervrajzok és minták
Egy AI ügynök nem képes igazodni az elvárásaidhoz, ha azok csak a fejedben léteznek. Amikor egy ügynök kénytelen maga kitalálni a felületek elrendezését, a lapozási paramétereket vagy a hibakezelést, középszerű, sablonos megoldásokat fog generálni. Mielőtt megírnád a szabályrendszert, készítsd elő ezeket a konkrét elemeket:
Adj az ügynöknek pontos design referenciákat és URL-eket, hogy értse az elvárt vizuális minőséget:
Helyezz el valódi, működő HTML/Vue/React sablonokat egy admin_template/ vagy blueprints/ mappában. Amikor a szabályod azt mondja, hogy "Használd az admin_template táblázat mintát", az ügynök közvetlenül ezt a struktúrát olvassa és másolja:
<!-- Éles Táblázat Komponens Tervrajz -->
<div class="card overflow-hidden">
<!-- Műveleti sáv: Keresés, Szűrők és Új Létrehozása -->
<div class="p-4 border-b border-light-grey flex flex-col md:flex-row items-center justify-between gap-4 bg-white">
<div class="relative w-full md:w-80">
<i class="fa-solid fa-magnifying-glass absolute left-3 top-1/2 -translate-y-1/2 text-prep-grey"></i>
<input type="text" v-model="searchQuery" @input="debouncedSearch" placeholder="Keresés név, kód alapján..." class="input-field pl-9">
</div>
<div class="flex items-center gap-3 w-full md:w-auto justify-end">
<button @click="navigateToCreate" class="btn-primary">
<i class="fa-solid fa-plus mr-1"></i> Új Elem Hozzáadása
</button>
</div>
</div>
<!-- Táblázat felépítése -->
<div class="overflow-x-auto">
<table class="w-full text-left border-collapse text-sm">
<thead class="bg-off-white text-xs uppercase font-semibold text-prep-grey border-b border-light-grey">
<tr>
<th class="py-3 px-4 cursor-pointer" @click="sortBy('name')">
Név <i :class="sortOrder === 'asc' ? 'fa-sort-up' : 'fa-sort-down'" class="fa-solid text-forti-black ml-1"></i>
</th>
<th class="py-3 px-4">Státusz</th>
<th class="py-3 px-4">Módosítva</th>
<th class="py-3 px-4 text-right">Műveletek</th>
</tr>
</thead>
<tbody class="divide-y divide-light-grey">
<tr v-if="isLoading">
<td colspan="4" class="py-12 text-center text-prep-grey">
<i class="fa-solid fa-spinner fa-spin mr-2"></i> Elemek betöltése folyamatban...
</td>
</tr>
<tr v-else-if="items.length === 0">
<td colspan="4" class="py-12 text-center text-prep-grey">Nincs találat.</td>
</tr>
<tr v-else v-for="item in items" :key="item.id" class="hover:bg-off-white/50 transition-colors">
<td class="py-3 px-4 font-medium text-forti-black cursor-pointer hover:underline hover:text-prep-green" @click="editItem(item.id)">
{{ item.name }}
</td>
<td class="py-3 px-4">
<span class="bg-success/10 text-success ring-1 ring-inset ring-success/20 px-2 py-0.5 rounded text-xs font-medium">
{{ item.status }}
</span>
</td>
<td class="py-3 px-4 text-prep-grey">{{ formatDate(item.updated_at) }}</td>
<td class="py-3 px-4 text-right space-x-3">
<button @click="editItem(item.id)" class="text-prep-grey hover:text-prep-green" title="Szerkesztés"><i class="fa-solid fa-pen"></i></button>
<button @click="confirmDelete(item.id)" class="text-prep-grey hover:text-danger" title="Törlés"><i class="fa-solid fa-trash"></i></button>
</td>
</tr>
</tbody>
</table>
</div>
</div>Építsd be a működő lapozási (pagination) és szűrési segédfüggvényeidet közvetlenül a szabályokba vagy a hivatkozási mappádba:
from django.core.paginator import Paginator
def paginate_queryset(queryset, request, per_page=50):
try:
page_num = int(request.GET.get('page', 1))
except (ValueError, TypeError):
page_num = 1
paginator = Paginator(queryset, per_page)
page_obj = paginator.get_page(page_num)
return page_obj, {
'total_pages': paginator.num_pages,
'current_page': page_obj.number,
'total_items': paginator.count,
'per_page': per_page
}export interface PaginationMeta {
totalPages: number;
currentPage: number;
totalItems: number;
perPage: number;
}
export function parsePaginationParams(query: Record<string, any>, defaultPerPage = 50) {
const page = Math.max(1, parseInt(query.page) || 1);
const perPage = Math.min(100, Math.max(1, parseInt(query.perPage) || defaultPerPage));
const skip = (page - 1) * perPage;
return { page, perPage, skip };
}Határozd meg a pontos mintát az aszinkron mentési gombokhoz, hogy az ügynök sose hagyja védetlenül az űrlapokat a gyors, ismételt kattintásokkal szemben (in-flight request guard):
<!-- Vue 3 Minta -->
<button
type="submit"
:disabled="isSubmitting"
class="btn-primary flex items-center justify-center min-w-[120px]">
<i v-if="isSubmitting" class="fa-solid fa-spinner fa-spin mr-2"></i>
<span>{{ isSubmitting ? 'Mentés folyamatban...' : 'Módosítások mentése' }}</span>
</button>Rajzold meg egyértelműen a repozitóriumod könyvtárstruktúráját. Egy olyan ügynök, amely ismeri a pontos mappahierarchiát, soha nem hoz létre felesleges fájlokat az engedélyezett könyvtárakon (whitelist) kívül, és tiszteli a környezeti változókat:
project_root/
├── frontend/ # Kliensalkalmazás (Vue/React/Vite)
├── backend/ # Kiszolgálóalkalmazás (Django/FastAPI/Express)
├── doc/ # Architektúra dokumentáció és codebase_index.md
├── .agents/ # AGENTS.md, szabályok, sablonok és útmutatók
├── .env.example # Tisztított minta az összes szükséges környezeti változóval
└── requirements.txt # Vagy package.json lockfile-ok (szigorúan szinkronizálva)15 lépéses strukturált kérdéssor a szabályrendszer felépítéséhez
A testreszabott szabályrendszer felépítéséhez járd végig ezt a 15 lépést sorban. Minden lépésnél válaszold meg a vezérlő kérdéseket, ismerd meg a kihagyás technikai következményeit, és másold be a mellékelt prompt sablont az AI ügynöködbe. Minden lépés az AGENTS.md egy-egy dedikált fejezetét hozza létre:
1. Lépés Projektstruktúra, Gyökérkönyvtár-higiénia és Függőségek
Vezérlő kérdések: Melyek a KIZÁRÓLAGOSAN engedélyezett gyökérmappák? Hol fut a virtuális környezet (venv) vagy a csomagkezelő? Hogyan szinkronizálódnak a függőségek a helyi gép és az éles szerver között? Készüljön-e automatikus indítószkript?
scripts/, temp/, test-results/) szemetelnek a gyökérbe. Szigorú lockfile-szinkronizáció nélkül pedig helyileg telepítenek csomagokat anélkül, hogy a lockfile-ba rögzítenék őket, azonnal elrontva a buildet az éles környezetben.
Éppen a fejlesztői ügynök szabályrendszerem (AGENTS.md) "Projektstruktúra és Függőségkezelési Szabályok" fejezetét készítem.
Íme a projekt paraméterei:
- Backend: [pl. Django a backend/ mappában / FastAPI / Express / Rails]
- Frontend: [pl. Vue 3 + Vite a frontend/ mappában / Next.js / SvelteKit / nincs]
- Engedélyezett Gyökérmappák: [Listázd az engedélyezett mappákat, pl. frontend/, backend/, venv/, doc/ KIZÁRÓLAG]
- Gyökérfájlok: [pl. requirements.txt, .env, .env.example]
- Függőségkezelés: [pl. python virtualenv a venv/ mappában szigorú requirements.txt frissítéssel; frontend npm install helyileg a frontend/ mappában]
- Élesítési Architektúra: [pl. SFTP feltöltés előre fordított dist/ mappával és közvetlen virtualenv python futtatással; VAGY Docker konténerek; VAGY Vercel/Netlify]
- Indítószkript: [pl. Mindig hozz létre shell szkriptet a lépésekkel: venv aktiválása, makemigrations, migrate, runserver]
Írj egy tömör, professzionális markdown szabályzatot a "Magyarázd el a Miért-et" elv alapján. Térj ki a gyökérkönyvtár tisztán tartására és a lockfile-szinkronizáció kényszerítésére.2. Lépés Környezeti Konfigurációs Stratégia (Fejlesztői vs. Éles)
Vezérlő kérdések: Hogyan épülnek fel a környezeti változók? Külön .env fájl van a fejlesztéshez és a termeléshez? Hogyan oldja fel a frontend az API alap URL-címét a különböző környezetekben? Hol tárolódnak a titkos kulcsok, az adatbázis-jelszavak, az engedélyezett hostok és a CORS források?
http://localhost:8000 címet a frontend forráskódba, vagy titkos API kulcsokat kommitol a gitbe, ami súlyos biztonsági incidenst okoz.
Készítsd el az AGENTS.md "Környezeti Változók és Konfigurációs Szabályok" fejezetét.
Paraméterek:
- .env fájlok: [pl. .env fejlesztéshez, .env.production éleshez, szigorúan kitöltött .env.example a repozitóriumban]
- Frontend API cím feloldása: [pl. relatív /api/ útvonalak fordított proxyval; vagy VITE_API_URL változó]
- Biztonsági szabály: Titkos kulcsot, jelszót, tokent forráskódba beégetni szigorúan TILOS.
- Kötelező változók listája backend és frontend oldalon.3. Lépés Backend Architektúra, Felhasználói Modellek és Többszintű RBAC
Vezérlő kérdések: Használtok-e harmadik féltől származó burkolókat (mint a DRF), vagy natív ORM és keretrendszer nézeteket? Milyen adatbázist használtok fejlesztéskor vs élesben? Hogyan épül fel a szerepkör-alapú hozzáférés-vezérlés (RBAC)? Szüksége van-e a felhasználói modellnek finomhangolt jogosultsági mezőkre?
Készítsd el az AGENTS.md "Backend Architektúra és Felhasználói Jogosultságok" fejezetét.
Technológiai paraméterek:
- Keretrendszer: [pl. Django Vanilla DRF nélkül / Express TypeScript / FastAPI / Rails]
- Tiltott Könyvtárak: [pl. Szigorúan TILOS a Django REST Framework / TILOS a Passport.js]
- Fejlesztői Adatbázis: [pl. SQLite]
- Egyedi Felhasználói Modell: [pl. AbstractUser-ből származtatva, egy JSONField típusú `menu_access` mezővel a finomhangolt többszintű jogosultságokhoz: modulok, almodulok, fülek és műveletek (megtekintés, létrehozás, szerkesztés, törlés, exportálás)]
- Jogosultságkezelés: Adminisztrációs felület építésekor mindig biztosíts egy dedikált Jogosultságkezelő modult, ahol a szuperfelhasználók finomhangolhatják a jogokat modulok, almodulok és műveletek szintjén.
- Hidratációs Végpont: Hozz létre egy `/users/me/` végpontot, amely visszaadja a hitelesített felhasználót, a szuperfelhasználói státuszt és a jogosultsági mátrixot.
- Autentikációs Dekorátor: Tiltsd meg a HTML-átirányításos dekorátorokat; követelj meg egyedi dekorátort, amely hitelesítés hiányában 401 JSON választ ad.4. Lépés API Szerződések, Lapozás és Szabványosított JSON Válaszformátumok
Vezérlő kérdések: Melyek a pontos szabványosított JSON válaszburkolók lista, létrehozás, frissítés, törlés és hiba válaszok esetén? Van-e újrafelhasználható lapozási (pagination) segédfüggvényetek? Hány elem jelenik meg oldalanként alapértelmezetten? Hogyan történik a keresési lekérdezések és rendezési mezők engedélyezési listázása?
{data: [...]}, mások {results: [...]}, megint mások sima tömböket használnak. Ez inkonzisztenssé teszi a frontend feldolgozást és futásidejű hibákhoz vezet.
Készítsd el az AGENTS.md "API Szerződések, Lapozás és Szabványosított JSON Válaszformátumok" fejezetét.
Követelmények:
1. Szabványos JSON Burkolók:
- Lista: `{'<entitások>': adatok, 'pagination': lapozási_metaadat}`
- Létrehozás: `{'id': obj.id, 'detail': '... sikeresen létrehozva.'}`, státusz 201
- Módosítás: `{'detail': '... sikeresen frissítve.'}`, státusz 200
- Törlés: `{'detail': '... sikeresen törölve.'}`, státusz 200
- Hiba: `{'error': 'Hibaüzenet szövege'}`, státusz 400/401/403/404
2. Újrafelhasználható Lapozási Segédfüggvény: [pl. Készíts egy segédet a backend/utils/pagination.py fájlban, amely page_obj-t és metaadat szótárat ad vissza; alapértelmezetten 50 elem/oldal]
3. Biztonságos Lekérdezésszűrés: Mindig engedélyezési listával (whitelist) ellenőrizd az érvényes `sort_by` mezőket az .order_by() hívása előtt az SQL injection megelőzésére. Használj Q objektumokat többmezős kereséshez.
Mellékelj konkrét mintakódot a lapozási segédfüggvényhez.5. Lépés Lezáró Perjelek, Atomikus Tranzakciók és Dátumkezelési Szabványok
Vezérlő kérdések: Mi a lezáró perjel (trailing slash) konvenciótok? Mikor kell az adatbázis-módosításokat atomikus tranzakciókba csomagolni? Hogyan szerializálódnak a dátumok és időpontok az API határokon? Szükség van-e árva fájlok takarítására a törölt modellrekordok után?
Készítsd el az AGENTS.md "Adatintegritás, URL Konvenciók és Dátumkezelési Szabványok" fejezetét.
Követelmények:
1. Kötelező Lezáró Perjelek: Minden backend URL útvonalnak ÉS minden kliensoldali API hívásnak kötelezően lezáró perjellel kell végződnie. Magyarázd el, hogy a szerver [pl. Django] hiányuk esetén HTTP 301 átirányítást ad ki, ami eldobja a POST/PUT/DELETE kérések törzsét és GET-re váltja őket.
2. Atomikus Tranzakciók: Kötelezővé kell tenni a [pl. transaction.atomic / adatbázis tranzakciók] használatát minden olyan nézetben vagy szervizben, amely több táblába ír vagy fájlfeltöltést végez adatbázis-műveletek mellett.
3. Dátum- és Időszabvány: UTC ISO 8601 szabványú sztringek minden API határon (USE_TZ=True, tárolás UTC-ben, szerializálás isoformat-tal).
4. Árva Médiafájlok Takarítása: Fájl- vagy képmezővel rendelkező modellrekord törlésekor a fizikai fájlt is törölni kell a lemezről signallal vagy egyedi delete() felülírással.
5. Migrációs Biztonság: [pl. Az ügynök soha nem futtathat makemigrations vagy migrate parancsot; kizárólag a manage.py check futtatása engedélyezett]6. Lépés Autentikáció, CSRF Védelem és API Kliens Konfiguráció
Vezérlő kérdések: Hogyan hitelesíti a frontend magát a backend felé? Session-alapú hitelesítést használtok CSRF tokenekkel, vagy JWT-t, vagy Firebase-t? Hogyan szerzi be az SPA a CSRF cookie-t a kezdeti betöltéskor? Van-e központosított HTTP kliens (mint az Axios) interceptorokkal?
withCredentials: true értéket és a CSRF token fejléceket a HTTP kliensben. Minden módosító kérés 403 Forbidden hibával elbukik, és az ügynök végső elkeseredésében teljesen kikapcsolja a CSRF védelmet, óriási biztonsági rést hozva létre.
Készítsd el az AGENTS.md "Autentikáció, CSRF Védelem és API Kliens Konfiguráció" fejezetét.
Paraméterek:
1. Hitelesítési Stratégia: [pl. Django munkamenet-alapú hitelesítés HTTP-only cookie-kal / Firebase Auth összekapcsolva a Django AbstractUser modellel / JWT frissítő tokenekkel]
2. CSRF Kézfogás: [pl. Hozz létre egy pehelysúlyú @ensure_csrf_cookie végpontot a users/csrf/ címen, hogy az SPA érvényes CSRF cookie-t szerezhessen az alkalmazás indításakor]
3. Központi HTTP Kliens: [pl. Hozd létre a frontend/src/axios.js fájlt a következő konfigurációval:
- withCredentials: true
- xsrfCookieName: 'csrftoken'
- xsrfHeaderName: 'X-CSRFToken'
- Interceptor a CSRF token csatolására a cookie-kból
- Automatikus kézfogási hívás a users/csrf/ végpontra indításkor]
4. Média URL Feloldás: [pl. Készíts egy getMediaUrl(path) segédfüggvényt, amely a /media/ útvonalakat teljes URL-re oldja fel fejlesztésben és relatív útvonalra élesben]
5. Kötelező Lezáró Perjelek Minden Kérésnél: Ismételd meg, hogy minden Axios végpontnak kötelező lezáró perjelet tartalmaznia.7. Lépés Design Rendszer Tokenek, Tipográfia és Segédosztályok
Vezérlő kérdések: Melyek a pontos design tokenjeitek – márkaszemléletű színek, semleges árnyalatok, státuszszínek, betűkészletek? Milyen újrafelhasználható UI segédosztályokat (.card, .btn-primary, .input-field) kell minden komponensnek használnia? Tailwind CSS-t vagy natív CSS-t használtok?
#333 az egyik fájlban, #1a1a1a a másikban, text-gray-800 a harmadikban. Az eredmény egy kaotikus felület, ami úgy néz ki, mintha 10 különböző fejlesztő készítette volna. A szabályozott tokenek garantálják a vizuális egységet.
Készítsd el az AGENTS.md "Design Rendszer Tokenek és Általános Osztályok" fejezetét.
A Design Rendszerem:
1. Színpaletta:
- Elsődleges sötét/szövegszín: [pl. forti-black (#030302)]
- Márka/kiemelő szín: [pl. prep-green (#6B6C62)]
- Másodlagos semleges színek: [sorold fel a semleges színeket]
- Hátterek és szegélyek: [sorold fel a háttér és szegély színeket]
- Státuszszínek: siker (#3A7D44), figyelmeztetés (#D4A843), veszély (#C4392A), infó (#4A6FA5)
2. Tipográfia: [pl. Inter (font-sans) a kenyérszöveghez, Outfit (font-heading) a címsorokhoz]
3. CSS Keretrendszer: [pl. Tailwind CSS kiterjesztett konfigurációval / Vanilla CSS egyedi változókkal]
4. Segédosztályok (Utility Classes): Definiáld ezeket az @layer components alatt:
- .card: [pontos osztálylista]
- .btn-primary: [pontos osztálylista hover, focus és átmenet állapotokkal]
- .btn-secondary: [pontos osztálylista]
- .input-field: [pontos osztálylista]
- .sticky-header: [pontos osztálylista]
Mellékeld a pontos tailwind.config.js színkiterjesztést és a style.css @layer components kódját.8. Lépés Elrendezés, Oldalsáv Navigáció és Mobil Reszponzivitás
Vezérlő kérdések: Milyen az alkalmazás vázelrendezése (oldalsáv + fő tartalom)? Mi szerepel az oldalsáv fejlécében, a navigációs linkekben és a felhasználói profil láblécében? Hogyan szűrődnek dinamikusan a linkek a felhasználói jogosultságok alapján? Hogyan működik a mobil drawer?
Készítsd el az AGENTS.md "Elrendezés és Navigáció" fejezetét.
Paraméterek:
1. Alkalmazás Váz (App Shell): [pl. AdminLayout.vue rögzített oldalsávval és görgethető fő tartalmi területtel]
2. Oldalsáv Struktúrája:
- Fejléc: [pl. Márkázott logó fejléc sötét háttérrel]
- Navigációs Linkek: [pl. Dinamikus linkek aktív állapot jelzővel, szűrve a felhasználói menu_access jogosultságok és az is_superuser szerint]
- Felhasználói Lábléc: [pl. Monogramos avatár, rövidített név/e-mail, dedikált kijelentkezés gomb kiemelt veszély-stílussal]
3. Mobil Kihúzható Menü (Drawer): [pl. Hamburger ikon rögzítve a bal felső sarokban, háttér-sötétítés (backdrop), balról becsúszó fiók]
4. Ikonok: [pl. KIZÁRÓLAG FontAwesome Free ikonok. Emojik használata szigorúan TILOS a felületen.]
5. Jogosultsági Szűrés: A navigációs elemeket kötelezően dinamikusan kell szűrni a bejelentkezett felhasználó jogosultsági mátrixa alapján.9. Lépés Táblázatok, Keresés, Rendezés és Állapottartás
Vezérlő kérdések: Hogyan kezelik az adattáblázatok a keresést, a szűrést és a debounced (késleltetett) valós idejű keresést? Hogyan valósul meg az oszloprendezés? Hogyan alkalmaztok reaktív állapotkezelést, hogy a táblázat állapota megmaradjon a szerkesztési oldalra navigáláskor és visszatéréskor? Milyenek a betöltési és üres állapotok?
Készítsd el az AGENTS.md "Táblázatok, Listák és Állapottartás" fejezetét.
Paraméterek:
1. Keresés: Valós idejű, 300 ms-mal debounced keresőmező, amely gépeléskor automatikusan visszaállítja a lapozást az 1. oldalra.
2. Lapozás: [pl. Alapértelmezetten 50 elem oldalanként]
3. Oszloprendezés: Kattintható oszlopfejlécek egyértelmű rendezési ikonokkal (aktív vs. inaktív állapot). Alapértelmezett rendezés: név mező szerint növekvő.
4. Táblázat Állapottartás: [pl. Pinia/Zustand store használata az aktuális oldal, keresőkifejezés és rendezés mentésére táblánként, így a szerkesztésről visszatérve a pozíció megmarad]
5. Kattintható Entitásnevek: A sor elsődleges azonosítója/neve mindig kattintható link legyen a szerkesztőoldalra.
6. Műveleti Ikonok: Szabványos soronkénti műveletek: szerkesztés (fa-pen, hover zöld), törlés (fa-trash, hover piros), megtekintés (fa-eye).
7. Státuszjelvények: [pl. Finom színezésű háttér belső kerettel: bg-success/10 text-success ring-1 ring-inset ring-success/20]
8. Betöltési Állapot: [pl. Spinner + "Elemek betöltése folyamatban..." az összes oszlopot átívelve]
9. Üres Állapot: [pl. "Nincs találat." az összes oszlopot átívelve]
10. Sorkijelölés Lebegtetéskor: Finom hover állapot finom színátmenettel.10. Lépés Űrlapok, Szerkesztőfelületek és Szabványos Fejléc-Kártyák
Vezérlő kérdések: A többmezős szerkesztésnek mindig dedikált oldalt kell-e használnia modális ablakok helyett? Mi a szabványos fejléc-kártya elrendezés minden űrlapoldalon (vissza gomb, cím, automatikus mentés jelvény, műveleti gombok)? Hogyan csoportosulnak az űrlapmezők szekciókba? Milyen a reszponzív rácselrendezés?
Készítsd el az AGENTS.md "Űrlapok, Szerkesztők és Szabványos Fejléc-Kártyák" fejezetét.
Követelmények:
1. Modális Ablak Tilalom: Egynél több mezőt tartalmazó szerkesztőfelületeknél soha ne használj felugró ablakot. Mindig dedikált nézetet/oldalt kell használni.
2. Szabványos Fejléc-Kártya: Minden űrlap/szerkesztő oldalnak tartalmaznia kell:
- Kerekített vissza gombot [pl. w-9 h-9 lekerekített kör alakú gomb ring stílussal]
- Oldalcímet (címsor betűtípus, félkövér) és leíró alcímet
- Mentési státuszjelvényt a szerkesztőfelületeken: elmentve (zöld), mentés folyamatban (spinner), nem mentett változtatások (borostyán), hiba (piros)
- Elsődleges műveleti gombokat a jobb oldalon elhelyezve
3. Szekciókra Bontás: Csoportosítsd az űrlapmezőket különálló kártyapanelekbe nagybetűs, ritkított szekciófejlécekkel.
4. Reszponzív Elrendezés: [pl. 2-oszlopos beviteli terület + 1-oszlopos oldalsáv a metaadatokhoz nagy képernyőn (grid-cols-1 lg:grid-cols-3)]
5. Egyedi Választó Komponensek: [pl. A natív HTML select elemek használata tilos; kötelező a design tokenekhez illeszkedő, egyedi stílusú dropdown komponensek használata]11. Lépés Értesítések, Párbeszédablak-tilalmak és In-Flight Védelmek
Vezérlő kérdések: Használhatja-e az ügynök az alert(), confirm() vagy prompt() böngészős funkciókat? Milyen értesítési rendszert használjunk a siker/hiba visszajelzésekhez? Hogyan védjük ki a dupla beküldést az űrlapgombokon?
alert(), confirm()) az ügynökök leggyakoribb rövidítései. Nem szabhatók testre, blokkolják az egész böngésző szálat, rendkívül amatőr hatást keltenek, és lehetetlen őket automatizáltan tesztelni. In-flight kérésvédelmek nélkül pedig a mentés gombra történő gyors kattintgatás duplikált sorokat generál az adatbázisban.
Készítsd el az AGENTS.md "Értesítések, Párbeszédablak-tilalmak és In-Flight Kérésvédelmek" fejezetét.
Paraméterek:
1. Böngészős Dialógus Tilalom: Soha ne használj natív böngészős ablakokat (alert(), confirm(), prompt()). Mindig építs egyedi komponenseket.
2. Értesítési Rendszer: Implementálj toast értesítési rendszert a felhasználók tájékoztatására siker, hiba és figyelmeztetés eseményekről.
3. Megerősítő Modálisok: Mindig egyedi stílusú megerősítő ablakot használj destruktív műveleteknél (törlés, elvetés).
4. In-Flight Kérésvédelmek: Minden olyan gombnak, amely aszinkron adatbázis-módosítást indít (űrlap beküldés, törlés, státuszváltás):
- Kötődnie kell egy isSubmitting/isLoading reaktív állapothoz
- Letiltottnak kell lennie a kérés futása alatt (:disabled="isSubmitting")
- Pörgő ikont kell megjelenítenie (fa-spinner fa-spin)
- Meg kell akadályoznia a duplikált mentést a gyors kattintgatásból vagy ismételt Enter leütésből
Mellékeld a pontos kódmintát az in-flight védett gombkomponenshez.12. Lépés Képfeltöltés, Kereső-Választó Komponensek és Görgethető Konténerek
Vezérlő kérdések: Hogyan működjenek a képfeltöltő komponensek (húzd-és-ejtsd, bélyegkép-galéria, átrendezés, alapértelmezett kép kiválasztása)? Hogyan működjenek a kereső-választó komponensek kapcsolódó entitások hozzárendelésekor végtelen görgetéssel? Legyen-e alsó elhalványuló színátmenet a görgethető dobozokon?
<input type="file"> mezőt készít előnézet, húzás és kliensoldali átméretezés nélkül – aminek következtében 8 MB-os nyers képek kerülnek a szerverre. Kereső-választó szabályok nélkül pedig egy egyszerű lenyíló listát használ, amely megfagy 1000+ elemnél.
Készítsd el az AGENTS.md "Képfeltöltés, Kereső-Választó és Görgethető Konténerek" fejezetét.
Követelmények:
1. Képfeltöltő Komponens:
- Támogassa mind az egyedi, mind a többszörös képfeltöltést a modul igényei szerint
- Húzd-és-ejtsd (Drag and drop) terület rejtett eredeti file inputtal
- Bélyegkép-galéria a feltöltő zóna felett: alapértelmezett kép beállítása, átrendezés, törlés, megtekintés
- Ha az alapértelmezett képet törlik, automatikusan állítson be egy újat
- Feltöltéskor méretezze át a képet maximum [pl. 1500x1500px]-re az eredeti képarány megőrzésével
2. Kereső-Választó Komponensek:
- Dedikált keresőkomponens valós idejű keresőmezővel a kulcsfontosságú tulajdonságok alapján szűrve
- Görgethető terület [pl. egyszerre 20 elemet megjelenítve] végtelen görgetéssel (infinite scroll)
3. Görgethető Konténerek:
- Minden túlcsorduló (overflow scroll) konténernek alsó elhalványuló színátmenettel kell rendelkeznie, amely eltűnik a doboz aljára görgetve
- [pl. Vue-ban használj @scroll eseményfigyelőt és dinamikus osztályokat a görgetési pozíció alapján]13. Lépés Router Védőkorlátok, Auth Szinkronizáció és Mobil Webapp
Vezérlő kérdések: Hogyan védi a frontend navigációs guard a hitelesített útvonalakat? Hogyan szinkronizálódik a kezdeti felhasználói állapot az útvonal kiértékelése előtt? Hogyan készítsük fel az appot mobil webappként iOS és Android rendszereken? Központosított legyen-e a dátumformázás?
Készítsd el az AGENTS.md "Router Védőkorlátok, Auth Szinkronizáció és Mobil Webapp" fejezetét.
Követelmények:
1. Navigációs Védőkorlátok: [pl. Implementálj router.beforeEach guardot, amely szorosan együttműködik az auth store-ral:
- Ellenőrizze, hogy a felhasználói auth inicializálva van-e (authStore.isInitialized)
- Ha még nincs, várja meg a /users/me/ választ az útvonaljogosultságok kiértékelése előtt
- A meta: { requiresAuth: true, permission: '...' } beállítású útvonalaknak ellenőrizniük kell az authot és a jogosultságokat
- Jogosulatlan hozzáférés esetén átirányítás a Hozzáférés Megtagadva vagy az Irányítópult nézetre]
2. Komponens Architektúra: [pl. Mindig bontsd a modulokat a lehető legtöbb újrafelhasználható komponensre]
3. Mobil Webapp: Mindig készítsd fel a projektet iOS/Android webapp használatra (viewport meta, érintés-optimalizációk, webmanifest).
4. Dátum- és Időmegjelenítés: [pl. A dátumokat kizárólag a megjelenítési rétegen formázd központosított utils.js segédfüggvényekkel, amelyek az UTC-t a helyi időzónára alakítják az Intl.DateTimeFormat használatával. Backend felé küldéskor mindig konvertáld UTC ISO 8601 formátumra.]14. Lépés Integrációk: AI, Fizetés, E-mail és Külső Szolgáltatások
Vezérlő kérdések: Melyik AI szolgáltatót használjátok generatív funkciókhoz? Milyen fizetésfeldolgozót? Hogyan van konfigurálva az e-mail küldés? A modellazonosítók környezeti változókban vannak, vagy a forráskódba vannak égetve? Mindig ellenőrizze az ügynök a legfrissebb fejlesztői dokumentációt a kódolás előtt?
.env helyett, ami lehetetlenné teszi a modellek cseréjét kód-újratelepítés nélkül.
Készítsd el az AGENTS.md "Integrációk és Külső Szolgáltatások" fejezetét.
Szabályok:
1. AI Funkciók: [pl. Mindig a Google Gemini modellt használd. Mindig keresd meg a modell hivatalos fejlesztői dokumentációját a fejlesztés megkezdése előtt. A modellazonosítókat a .env-ben kell tárolni, soha nem égethetők be.]
2. Fizetés: [pl. Mindig Stripe-ot használj, ha fizetési vagy előfizetéses funkcionalitásra van szükség.]
3. E-mail: [pl. Konfiguráld az SMTP-t környezeti változók segítségével ésszerű alapértelmezésekkel. Mellékelj példa .env beállításokat: EMAIL_HOST, EMAIL_PORT, EMAIL_USE_TLS, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, DEFAULT_FROM_EMAIL, SITE_HOST]
4. Autentikáció: [pl. Mindig kérdezd meg a fejlesztőt, hogy natív Django session-alapú bejelentkezést vagy Firebase Auth-ot szeretne. Ha Firebase, kösd össze a natív AbstractUser modellel.]
Mellékelj konkrét .env mintablokkokat és settings.py integrációs kódot az e-mailhez.15. Lépés Verziókezelés, Tesztelési Határok, Dokumentáció és Élesítés
Vezérlő kérdések: Kommitolhat-e az ügynök automatikusan a gitbe? Milyen tesztelési CLI parancsokat futtathat az ügynök? Miért tilos az automatizált böngészős tesztelés? Hol tárolódik a dokumentáció? Hogyan dokumentáljuk az élesítést? Készüljön-e beépített súgórendszer?
git commit és git push parancsokat futtatnak, tucatnyi értelmetlen kommitot szemetelve a repozitóriumba, és potenciálisan félkész, hibás kódot tolva élesbe. Böngészős teszttilalom nélkül pedig végtelen ciklusban lefagyó headless böngészőket indítanak. Pontos élesítési dokumentáció nélkül az adatbázis és a média mappák jogosultsági hibákkal leállnak a szerveren.
Készítsd el az AGENTS.md "Verziókezelés, Tesztelési Határok, Dokumentáció és Élesítés" fejezetét.
Szabályok:
1. Git Verziókezelés:
- Kezdeti Beállítás: [pl. git init, első commit létrehozása, publikálás privát GitHub repóba]
- Folyamatos Fejlesztés: [pl. SOHA ne kommitolj vagy pusholj automatikusan a kezdeti beállítás után. A verziókezelést a humán fejlesztő irányítja.]
- Gitignore: [pl. Mindig tartalmazza a /media/, **/migrations/* (kivéve __init__.py), venv/, .env elemeket]
2. Tesztelési Határok:
- Böngészős Tesztelés: SZIGORÚAN TILOS. Nincs Playwright, Puppeteer, Selenium vagy headless böngésző. A vizuális ellenőrzést a humán fejlesztő végzi.
- CLI Ellenőrzések: [pl. Engedélyezett és ajánlott: manage.py check, manage.py test, eslint, tsc --noEmit]
- Seed Szkriptek: Valódi szerviz metódusokat és API végpontokat kell meghívniuk, nem közvetlen nyers adatbázis-beszúrásokat.
3. Dokumentáció:
- Helye: [pl. Kizárólag a doc/ mappában]
- Kódbázis Index: [pl. Mindig konzultálj a doc/codebase_index.md fájllal új kód írása előtt]
- Frissítések: [pl. Frissítsd a dokumentációt jelentős rendszerarchitekturális változásoknál]
4. Élesítési Útmutató:
- [pl. Részletezd az SFTP folyamatot, ahol a frontend dist/ helyileg fordul és töltődik fel. Mellékelj Apache/Nginx konfigurációt, tulajdonosi jogosultságokat az SQLite-hoz, média mappához és a .env-hez.]
5. Súgórendszer: [pl. Építs statikus HTML súgórendszert a frontend/public/help/ mappában környezetérzékeny HelpTooltip komponensekkel a fejlesztés záró szakaszában.]Hogyan verifikáld és stresszteszteld a szabályrendszeredet
5.1 Statikus Verifikáció: Az Ellenérdekelt Felülvizsgáló Prompt
Mielőtt éles projektre engednéd a szabályrendszert, add át egy csúcsmodellnek (pl. Gemini 1.5 Pro vagy Claude 3.5 Sonnet) ezzel a szigorú ellenérdekelt audittal, hogy feltárd az ellentmondásokat, kétértelműségeket és a hiányzó védőkorlátokat:
Vezető Szoftverarchitekt és AI Prompt Mérnök vagy, aki autonóm fejlesztői ügynökök irányítására specializálódott.
Elemezd ezt a fejlesztői ügynök szabályrendszer tervezetet (AGENTS.md) rendkívüli szigorral és kritikai szemlélettel:
1. Ellentmondások: Vannak-e egymásnak feszülő utasítások a különböző fejezetekben?
2. Kétértelműségek: Hol használtam pontatlan mellékneveket ("tiszta", "modern", "megfelelő", "optimális") anélkül, hogy konkrét technikai invariánst vagy mérőszámot adtam volna meg?
3. Vakfoltok és Hiányzó Védőkorlátok: Milyen kritikus fejlesztési hibaforrások (pl. race condition-ök, migrációs zárolások, válasz envelope hibák, titkos kulcs szivárgások) hiányoznak?
4. Token-hatékonyság: Mely mondatok tartalmaznak felesleges sallangot, amelyet tömöríteni kell a figyelmi súly javítása érdekében?
5. Indoklások erőssége: Vannak-e dogmatikus parancsok technikai "Miért" magyarázat nélkül?
Íme a szabálytervezetem:
[IDE MÁSOLD BE AZ AGENTS.MD TERVEZETET]5.2 Az Empirikus Tűzpróba Teszt
Egy szabályrendszer végső bizonyítéka a gyakorlati megvalósítás. Hozz létre egy új git ágat, és kérj meg egy ügynököt egy teljes, nem-triviális CRUD modul megvalósítására:
Valósíts meg egy teljes "Raktári Készletkezelő" modult:
1. Backend modell: Termék (cikkszám, név, kategória, készlet_mennyiség, egységár, státusz, kép).
2. Backend API: Lista lapozással, kereséssel, rendezéssel; Létrehozás; Módosítás; Törlés; Részletek.
3. Frontend Táblázat: Termékek megjelenítése kereséssel, rendezéssel, státuszjelvényekkel és műveleti ikonokkal.
4. Frontend Űrlap: Dedikált szerkesztőoldal termék létrehozására és módosítására képfeltöltéssel.
Kövesd szigorúan az AGENTS.md összes előírását.5.3 A 10 Pontos Megfelelőségi Értékelőlap
Értékeld az ügynök által leadott kódot az alábbi ellenőrzőlistán. Bármely hiba azt jelzi, hogy a szabályrendszer adott pontján pontosítás szükséges:
| # | Ellenőrzési pont | Sikeres teljesülés | Hiba / Szabálysértés |
|---|---|---|---|
| 1 | Mappahigiénia | A fájlok kizárólag az engedélyezett mappákban jöttek létre. | Létrehozott temp/, scripts/ vagy gyökérmappás szemetet. |
| 2 | Migrációs biztonság | Ellenőrzést futtatott; NEM hozott létre önkényes migrációt a gitben. | Új migrációs fájlokat generált jóváhagyás nélkül. |
| 3 | Lezáró perjelek | Minden backend útvonal és kliens kérés / jellel végződik. |
axios.post('/api/products') (hiányzó lezáró perjel). |
| 4 | Autentikáció | Egyedi @api_login_required-t használt (401 JSON). |
Alapértelmezett @login_required-t használt (302 HTML átirányítás). |
| 5 | JSON Szignatúra | Megfelelt a {'products': [...], 'pagination': ...} formátumnak. |
Egyszerű tömböt vagy `{data: [...]}`-t adott vissza. |
| 6 | Atomikus Integritás | Több táblás írásokat transaction.atomic-ba zárta. |
Sima mentések tranzakciós visszagörgetési védelem nélkül. |
| 7 | Nincs UI Emoji | Kizárólag FontAwesome Free ikonokat használt. | 📦 vagy ✅ emojit tett a gombokra vagy a feliratokba. |
| 8 | Egyedi Dropdown | Egyedi stílusú választó komponenst használt. | A böngésző natív <select> elemét használta. |
| 9 | Dedikált Szerkesztő | Dedikált oldalra navigált szabványos fejléc-kártyával. | Felugró modális ablakot nyitott a sokmezős szerkesztéshez. |
| 10 | In-Flight Védelem | Mentés gomb letiltva spinnerrel a kérés futása alatt. | A gombra többször rá lehetett kattintani, duplikálva az adatot. |
5.4 A "Hibából Szabály" Megerősítési Ciklus
AGENTS.md-be, és kommitold. Idővel a szabályrendszered áthatolhatatlan immunrendszerré fejlődik, amely pontosan a csapatod szabványaihoz igazodik.