De ce Wingin' It nu mai funcționează cu AI-ul

Imaginați-vă următorul scenariu: aveți o funcționalitate clară în minte. Deschideți asistentul AI preferat, tastați rapid o cerere, și priviți cum rescrie încrezător jumătate din codebase. O oră mai târziu, vă uitați la un PR care rezolvă o problemă pe care nu tocmai intenționați să o rezolvați, într-un mod care strică lucruri pe care nu aveați de gând să le afectați.

Vă sună familiar? Nu sunteți singurul. Pe măsură ce agenții AI au evoluat de la simpli răspunsitori la editori de cod, mulți dezvoltatori descoperă că aceeași abordare informală care funcționează cu chatbot-urile nu mai este suficientă când e vorba de repository-uri reale.

Soluția nu stă în prompt-uri mai detaliate. Stă într-o schimbare fundamentală a modului în care gândim documentele pe care le trimitem acestor agenți.

Prompts vs. Specificații: O Distincție Esențială

Iată adevărul despre prompts: sunt optimizate pentru a porni un task. Sunt excelente pentru explicații rapide, scripturi de unica folosință și conversații exploratorii. Un prompt trăiește într-o sesiune de chat, poate folosi prescurtări, și adesea prespune context pe care doar autorul îl înțelege.

Funcționează bine când pui întrebări.

Dar când un agent AI urmează să editeze cod partajat, să ruleze comenzi terminal, și să producă branch-uri pe care colegii le vor revizui? Prompt-ul tău casual devine un task formal. Și task-urile formale au nevoie de mai mult decât formulări frumoase — au nevoie de contextul potrivit, limite clare, exemple concrete și criterii de validare.

Aici intervin specificațiile.

O specificație nu este un prompt mai arătos. Este un document structurat care capturează ce problemă rezolvi, ce comportament trebuie să se schimbe, ce trebuie să rămână la fel, și cum vei ști dacă munca a reușit. Spre deosebire de un prompt care dispare după ce agentul începe lucrul, specificația rămâne vizibilă pe tot parcursul workflow-ului — ghidând agentul, informând reviewerii, și ajutând viitorii maintaineri să înțeleagă de ce s-au luat anumite decizii.

Ce conține o specificație bună pentru agenți AI

Nu ai nevoie de un document de 20 de pagini. Ai nevoie de cinci elemente cheie:

1. Context: De ce apare acest task? Ce problemă de utilizator sau tech debt îl motivează? Ce constrângeri există în codebase pe care agentul ar trebui să le înțeleagă?

2. Comportament de schimbat: Ce funcționalitate specifică trebuie modificată, adăugată sau eliminată? Fii concret — "utilizatorii trebuie să primească notificări email când X se întâmplă" este mai bine decât "îmbunătățește sistemul de notificări."

3. Constrângeri de păstrat: Ce nu trebuie să se schimbe absolut? Ce funcționalități existente, contracte de API sau caracteristici de performanță trebuie să rămână intacte?

4. Exemple de corectitudine: Scenarii concrete care demonstrează ce înseamnă "bine". Formatul Given/When/Then funcționează bine aici, dar chiar și câteva cazuri de test explicite ajută agentul să înțeleagă așteptările tale.

5. Criterii de validare: Cum va ști un reviewer dacă munca e completă? Ce ar trebui să inspecteze? Ce întrebări ar trebui să-și pună?

Acest framework ar trebui să-ți pară familiar dacă ai lucrat cu scenarii BDD, șabloane de issue-uri cu criterii de acceptare, sau documente de design. Formatul specific contează mai puțin decât să ai informația potrivită într-o formă partajabilă și revizibilă.

Unde își găsesc specificațiile locul în workflow

Unul dintre cele mai bune lucruri despre specificații este flexibilitatea lor. Nu trebuie neapărat să fie documente separate care te încetinesc. O specificație poate trăi oriunde are sens pentru echipa ta:

• Un issue GitHub cu criterii de acceptare explicite
• O descriere de PR care numește comportamentul schimbat
• Un scenariu BDD în fișierele de feature
• O notă de design ușoară înainte de implementare
• Unelte precum OpenSpec sau GitHub Spec Kit care formalizează acest pattern

Cheia este să faci contextul și criteriile de revizuire vizibile și persistente. Specificația ta nu ar trebui să dispară când se încheie sesiunea de chat. Ar trebui să călătorească împreună cu munca, oferind colegilor ceva concret de evaluat.

Stratul de Assignment: Separând Intenția de Execuție

Iată unde lucrurile devin cu adevărat interesante.

Cele mai puternice specificații funcționează ca mici contracte de comportament. Separă trei întrebări distincte:

1. Ce comportament trebuie să se schimbe? (Cerința)
2. Ce constrângeri sau exemple definesc corectitudinea? (Criteriile de acceptare)
3. Ce cale de implementare pare potrivită acum? (Abordarea tehnică)

Aceste întrebări sunt conectate, dar nu ar trebui să se amestece într-un blob de instrucțiuni.

De ce contează asta pentru agenții AI? Pentru că atunci când amesteci prea devreme intenția cu implementarea, agentul poate optimiza pentru lucrul greșit. Ar putea urma cu sfințenie un detaliu de implementare sugerat în timp ce pierde comportamentul exact de care aveai nevoie. Sau ar putea produce cod tehnic interesant dar care nu rezolvă problema declarată.

Un strat de assignment menține cerința stabilă în timp ce permite implementării să evolueze. Pe măsură ce agentul citește codebase-ul, descoperă complicații și rafinează abordarea, specificația rămâne punctul de referință: "Munca asta satisface cerința?"

Asta e deosebit de valoros pentru codebase-uri existente. Majoritatea muncii de inginerie nu e greenfield — modifici comportament care deja există. O specificație bună spune: iată comportamentul curent, și iată ce trebuie să se schimbe. Reviewerii nu trebuie să-și reconstruiască mental intenția din detaliile implementării.

Făcând Schimbarea

Dacă ești obișnuit să tratezi agenții AI ca motoare de căutare supraalimentate, asta ar putea părea overthinking. Dar consideră alternativa: modificări necontrolate ale codului partajat, PR-uri greu de revizuit, și muncă care nu se potrivește exact cu ce ai imaginat.

Schimbarea către colaborarea AI ghidată de specificații nu este despre birocrație. Este despre a oferi atât oamenilor cât și mașinilor claritatea de care au nevoie pentru a lucra eficient împreună.

Începe mic. Data viitoare când ești pe punctul de a trimite un agent AI într-un repository, oprește-te cinci minute să notezi contextul, schimbarea de comportament și criteriile de succes. Pune asta undeva vizibil — chiar dacă e doar în descrierea PR-ului.

Viitorul tău sine (și colegii tăi) îți vor mulțumi.

Concluzia: Agenții AI de coding sunt colaboratori puternici. Tratează-i ca atare. Dă-le un brief corect, și vei primi muncă care merită revizuită.