Miért nem elég a "ráérő" megközelítés az AI-val

Képzeld el: van egy clear feature az agyadban. Beütsz egy gyors kérést a kedvenc AI coding assistantodba, és nézed, ahogy magabiztosan átírja a kódbázisod felét. Egy óra múlva egy PR előtt találod magad, ami egy olyan problémát old meg, amit nem is akartál megoldani — miközben szétbont mindent, amit nem akartál.

Ismerősen hangzik? Nem vagy egyedül. Ahogy az AI coding agentek fejlődtek a kérdés-válaszoló chatbotokból valódi code editorokká, sok fejlesztő döbbent rá: ugyanaz a laza prompting stílus, ami a chatbottal működött, csődöt mond, amikor valódi repók forognak kockán.

A megoldás nem a részletesebb promptok. A probléma gyökere mélyebb: meg kell változtatnunk, hogyan gondolkodunk azokról a dokumentumokról, amiket ezeknek az agenteknek küldünk.

Promptok kontra specifikációk: Mi a különbség?

A promptok lényege a munka beindítása. Szuperek gyors magyarázatokhoz, egyszer használatos scriptelekhez, felfedező beszélgetésekhez. A prompt egy chat sessionben él, használhat rövidítéseket, és gyakran csak a szerző számára egyértelmű kontextust feltételez.

Ez működik, amikor csak kérdezel valamit.

De amikor egy AI agent kódot fog szerkeszteni, terminál parancsokat futtatni, és brancheket létrehozni, amiket a csapattársak fognak reviewolni? A te laza promptod egy feladattá válik. És a feladatokhoz nem elég a szép megfogalmazás — kell a megfelelő kontextus, egyértelmű határok, konkrét példák és validációs kritériumok.

Itt jön képbe a specifikáció.

A spec nem egy csinosabb prompt. Egy strukturált dokumentum, ami rögzíti: milyen problémát oldunk meg, milyen viselkedésnek kell változnia, mi maradjon változatlanul, és honnan tudjuk, hogy sikeres volt-e a munka. Míg a prompt eltűnik, ahogy az agent elkezd dolgozni, a spec végig látható marad — irányítja az agentet, segíti a reviewerokat, és megmagyarázza a jövőbeli maintainereknek, miért születtek bizonyos döntések.

Mire kell figyelni egy jó AI-Agent specben

Nem kell 20 oldalas dokumentumot írnod. Öt kulcselem elegendő:

1. Kontextus: Miért történik ez a feladat? Milyen user probléma vagy technical debt indokolja? Milyen megszorítások vannak a kódbázisban, amit az agentnek tudnia kell?

2. Melyik viselkedés változzon: Konkrétan milyen funkcionalitást módosítunk, adunk hozzá vagy törölünk? Legyél konkrét — „a userek kapjanak email értesítést, amikor X történik" jobb, mint „javítsuk a notification rendszert."

3. Megtartandó megszorítások: Mi az, ami semmi esetre sem változhat? Milyen meglévő funkcionalitás, API contractok vagy perfomancia jellemzők maradjanak érintetlenek?

4. Példák a helyes működésre: Konkrét scenariók, amik megmutatják, mit jelent a jó. A Given/When/Then formátum jól működik, de már néhány explicit test case is segít az agentnek megérteni az elvárásaidat.

5. Validációs kritériumok: Honnan tudja a reviewer, hogy kész van-e a munka? Mit vizsgáljon meg? Milyen kérdéseket tegyen fel?

Ha ismerősen hangzik, az nem véletlen: ez hasonlít a behavior-driven development (BDD) scenariókhoz, az issue template-ek acceptance criteria-jához vagy a design dokumentumokhoz. A konkrét formátum kevésbé számít, mint az, hogy a megfelelő információ megosztható és reviewolható legyen.

Hol helyezkedjenek el a specifikációk a workflow-ban?

Az egyik legjobb dolog a specifikációkban a rugalmasságuk. Nem kell külön dokumentumoknak lenniük, amik lassítanak. A spec bárhol élhet, ami a csapatodnak смысл:

• Egy GitHub issue explicit acceptance criteria-val
• Egy PR description, ami megnevezi a változó viselkedést
• Egy BDD scenario a feature fájljaidban
• Egy lightweight design note implementáció előtt
• Olyan eszközök, mint az OpenSpec vagy a GitHub Spec Kit, amik formalizálják ezt a mintát

A lényeg: a kontextus és a review kritériumok legyenek láthatóak és perzisztensek. A specifikációd ne tűnjön el, amikor a chat session véget ér. Kísérje a munkát, adjon a csapattársaknak valami konkrétumot az értékeléshez.

Az Assignment Layer: A szándék és a végrehajtás szétválasztása

Itt válik igazán érdekessé.

A legerősebb specifikációk úgy viselkednek, mint kis viselkedési contractok. Három különálló kérdést választanak szét:

1. Milyen viselkedésnek kell változnia? (A követelmény)
2. Milyen megszorítások vagy példák definiálják a helyes működést? (Az acceptance criteria)
3. Milyen implementációs út tűnik most megfelelőnek? (A technikai megközelítés)

Ezek a kérdések összefüggnek, de nem szabad egyetlen instructió-halommá esniük.

Miért fontos ez az AI coding agenteknél? Mert amikor túl korán kevered a szándékot és az implementációt, az agent rossz irányba optimalizálhat. Lehet, hogy lelkesen követ egy javasolt implementációs részletet, miközben nem érti meg a valódi viselkedést, amire szükséged volt. Vagy olyan kódot produkál, ami technikailag érdekes, de nem oldja meg a megfogalmazott problémát.

Az assignment layer stabilan tartja a követelményt, miközben az implementáció fejlődhet. Ahogy az agent megismeri a kódbázist, felfedezi a komplikációkat és finomítja a megközelítését, a specifikáció marad a mérce: „A munka kielégíti ezt?"

Ez különösen értékes meglévő kódbázisoknál. A legtöbb engineering munka nem greenfield — meglévő viselkedést módosítasz. Egy jó spec mondja: ez a jelenlegi viselkedés, és ez az, ami változnia kell. A reviewereknek nem kell mentalisan rekonstruálniuk a szándékodat az implementációs részletekből.

Eltolni a paradigmát

Ha hozzá vagy szokva, hogy az AI coding agenteket úgy kezeld, mint túlbonyolított keresőmotorokat, ez overkillnek tűnhet. De gondolj az alternatívára: ellenőrizetlen változások a megosztott kódban, PR-ok, amiket nehéz reviewolni, és munka, ami nem egészen azt oldja meg, amit elképzeltél.

Az átállás a specifikáció-vezérelt AI együttműködésre nem bürokrácia. Arról szól, hogy mind a humánoknak, mind a gépeknek megadjuk a klaritást, amire szükségük van a hatékony közös munkához.

Kezdd kicsiben. Legközelebb, mielőtt egy AI coding agentet bevetsz egy repository-ba, állj meg öt percre, és írd le a kontextust, a viselkedésváltozást és a sikerkritériumokat. Rakd valahova látható helyre — még ha csak a PR descriptionben van is.

A jövőbeli énod (és a csapattársaid) megköszönik.

A lényeg: Az AI coding agentek hatalmas collaboratorok. Kezeld őket úgy, mint collaboratorokat. Adj nekik egy rendes briefet, és olyasmit kapsz vissza, amit érdemes reviewolni.