Dezvoltare bazată pe specificații cu Claude Code: un tutorial ghidat

Ce este dezvoltarea bazată pe specificații?

Dezvoltarea bazată pe specificații este un flux de lucru construit pe trei documente, în ordine: unul care spune ce ar trebui să facă o schimbare, un plan care specifică pașii și codul scris conform planului, cu o revizuire umană între fiecare pereche.

Cele trei puncte de revizuire prin care trece o funcționalitate în dezvoltarea bazată pe specificații.

Specificația este un document scurt, scris în limbaj simplu înainte de orice cod, care spune ce ar trebui să facă o schimbare. Ia o funcționalitate precum „permite utilizatorilor să-și exporte datele”. O specificație pentru ea fixează răspunsurile pe care altfel agentul le-ar ghici. Ea listează 

• Formatele de fișiere acceptate
• Modul de livrare
• Comportamentul în timpul unui export pe jumătate terminat
• Părțile din funcționalitate lăsate intenționat pe dinafară

Iată deschiderea reală a unei specificații pe care Claude Code a scris-o pentru o schimbare workout-shape-verification într-o aplicație a mea de responsabilitate pe Telegram. Schimbarea înlocuiește un prag fragil de ritm cardiac cu o verificare a formei curbei ritmului cardiac în timp:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Planul este următorul document. El sparge specificația de mai sus în sarcini numerotate pe care agentul le poate aborda pe rând, fiecare sarcină numind un fișier, o schimbare, o ordine și un test. Dacă specificația răspunde la „ce”, planul răspunde la „în ce pași”. 

Codul vine la final, scris conform planului, câte o sarcină o dată.

Trei documente. O revizuire umană stă între fiecare pereche. Revizuiești specificația înainte să devină plan. Revizuiești planul înainte să devină cod. Revizuiești codul înainte de îmbinare.

Cum diferă dezvoltarea bazată pe specificații de modul plan

Poate ai folosit modul plan încorporat al Claude Code (apasă Shift+Tab de două ori pentru a intra) și te-ai întrebat de ce acesta este diferit. Modul plan produce un plan într-o singură tură de chat. Planul trăiește în memorie, fără o specificație salvată și fără un pas de revizuire între faze.

Dezvoltarea bazată pe specificații persistă specificația și planul ca fișiere pe disc. Fiecare trece printr-o revizuire umană înainte ca următoarea fază să înceapă, iar artefactele supraviețuiesc între sesiuni. Modul plan comprimă două faze ale dezvoltării software într-o singură tură de chat. Asta funcționează la sarcini mici și eșuează de îndată ce baza de cod crește și începe să deservească utilizatori reali.

De ce atinge un zid vibe-coding

Vibe-coding funcționează pentru prototipuri, fișiere singulare și scripturi de aruncat. Devine mai slab în aplicații reale, cu utilizatori de răspuns, și în codebase-uri mari existente. Linia bună de tras este pe la 4 fișiere. Orice schimbare care atinge atâtea fișiere are nevoie de o specificație, la fel orice refactor cu un rezultat coerent sau orice sarcină unde „ce ar trebui să facă exact asta?” este partea grea.

Eșecul are o cauză clară. Un prompt vag precum „adaugă partajare de fotografii în aplicația mea” face modelul să ghicească mii de cerințe nespuse.

Ia doar una dintre acele cerințe: preferințele de notificare. Product managerul presupune comutatoare per canal. Backendul construiește un întrerupător on/off. Frontendul presupune integrare la nivelul sistemului de operare. Patru interpretări rezonabile ale a trei cuvinte, patru produse diferite.

Fiecare pas de revizuire în dezvoltarea bazată pe specificații prinde o altă clasă de greșeli înainte să devină scumpe. Revizuirea specificației prinde extinderea necontrolată a ariei și încadrările greșite ale cauzei rădăcină. Revizuirea planului prinde implementări pe jumătate terminate și patternuri conflictuale. Revizuirea codului prinde planuri care arată bine pe hârtie, dar se rup la primul test picat.

Beneficiul este real și se acumulează treptat. Faza de specificație costă ore de scris înainte de a rula codul, iar primele câteva funcționalități par mai lente decât vibe-coding. La mine, punctul de break-even a venit pe la a patra sau a cincea funcționalitate. Atunci, specificațiile prindeau greșeli de design pe care altfel le-aș fi livrat și rescris o săptămână mai târziu.

Următoarele trei secțiuni trec prin trei abordări open-source care rulează acest flux de lucru în interiorul Claude Code. Sunt ordonate de la cea mai ușoară la cea mai strictă în structura pe care o impun.

Superpowers

Superpowers este cea mai ușoară dintre cele trei. Este cea pe care o folosesc zi de zi și cea pe care o vom acoperi în cel mai mare detaliu.

Ce este Superpowers?

Superpowers este un plugin Claude Code creat de Jesse Vincent (obra/superpowers, licență MIT), cu aproximativ 194k stele pe GitHub. 

Vine cu un set de abilități. O abilitate Claude, în Claude Code, este un fișier de instrucțiuni cu nume, pe care agentul îl încarcă la cerere pentru a urma un flux de lucru specific. Superpowers livrează abilități care îl țin pe Claude Code în bucla bazată pe specificații, în loc să-l lase să sară direct la cod.

Pagina proiectului Superpowers pe GitHub.

Cum instalezi Superpowers

Instalează-l prin marketplace-ul oficial de pluginuri al Claude Code:

/plugin install superpowers@claude-plugins-official

Un hook SessionStart încarcă automat abilitatea using-superpowers, astfel încât fluxul de lucru e activ din momentul în care începi să tastezi. (Hook-urile Claude Code sunt scripturi pe care agentul le rulează la un anumit eveniment de ciclu de viață.) Nu e nimic de conectat per proiect.

Fluxul de lucru Superpowers

După aceea, patru abilități îți gestionează munca zilnică:

Un subagent este o instanță separată de Claude Code pe care „părintele” o declanșează pentru a face muncă focalizată în propria fereastră de context. Subagenții de review din tabelul de mai sus rulează ca subagenți, deci citesc codul la rece, fără încadrarea părintelui.

Cum folosești Superpowers

Invoci cele patru abilități descriind în limbaj simplu ce vrei. Abilitatea de brainstorming aude „hai să discutăm despre această funcționalitate nouă” și pornește singură conversația de specificație. Celelalte se declanșează la fel.

Cele patru abilități Superpowers în ordine, cu cele două puncte de revizuire umană între brainstorming și writing-plans.

Walkthrough-ul de mai jos folosește aceeași funcționalitate workout-shape-verification din extrasul de specificație de mai sus.

Etapa 1: de la brainstorming la specificație

Deschid Claude Code și tastez:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Abilitatea brainstorming preia controlul și pune vreo zece întrebări înapoi, printre care:

• Ce înseamnă „forma” corectă
• Ce fluxuri de date să combinăm
• Ce facem cu sesiunile care arată corect ca formă, dar pică un prag vechi
• Dacă schimbarea ar trebui să se aplice și la Run și Ride

Aici apar două puncte de revizuire umană. Primul este revizuirea de design, unde confirm că răspunsurile pe care le-am dat se potrivesc cu ce îmi doresc. Al doilea este revizuirea specificației. Citesc fișierul pe care l-a scris Claude și îl aprob înainte să înceapă munca la plan.

Etapa 2: de la specificație la plan

Rulez abilitatea writing-plans. Ea citește specificația aprobată și scrie un fișier de plan cu patru părți:

• O definiție a ce înseamnă „Gata”
• O hartă de fișiere cu fișierele atinse
• O călătorie a utilizatorului prin traseul de demo
• O listă numerotată de sarcini cu sub-pași bifabili. 

Revizuiesc planul, contest sarcini care par în afara ordinii sau prea grosiere și aprob.

Etapa 3: de la plan la cod

Rulez subagent-driven-development. Din acest punct, bucla rulează fără mine. Pentru fiecare sarcină din plan, abilitatea:

1. Scrie un test care pică
2. Scrie codul ca să-l treacă
3. Refactorizează
4. Trimite un subagent de code review care citește diff-ul la rece

Dacă reviewerul semnalează o problemă, bucla o repară înainte să treacă la următoarea sarcină. Nu există punct de revizuire umană în această etapă. Revizuirile care contează aici sunt cele două dinainte.

Etapa 4: revizuire pe diff complet

După ce planul e gata, rulez requesting-code-review. Un subagent proaspăt citește întregul diff în raport cu specificația și planul și postează un review. Iau sugestiile înainte de merge.

Când o sarcină din plan dezvăluie o contradicție cu specificația, bucla se oprește și întreabă. Pot edita specificația (sau îl las pe Claude să o facă) și să regenerez sarcinile afectate. Cealaltă opțiune este o corecție punctuală chiar în sarcina respectivă. Superpowers nu ocolește în tăcere erorile din specificații.

Specificări și planuri reale pe disc

Iată specificația pentru funcționalitatea workout-shape-verification, deschisă într-un editor:

Fișierul de specificație așa cum ajunge pe disc după ce abilitatea de brainstorming îl scrie.

Antetul conține câmpurile Created, Status și Supersedes pe care abilitatea de brainstorming le scrie implicit. Urmează secțiunea Problem. Nimic din asta nu e cod. Fișierul continuă dincolo de captură prin secțiuni pentru soluția propusă și constrângerile privind ce ar trebui și ce nu ar trebui să atingă schimbarea.

Planul pereche se deschide cu User Journey:

Fișierul de plan pe care abilitatea writing-plans îl produce din specificația aprobată.

Călătoria parcurge traseul de demo în pași de câte cinci, numind comenzile, fișierele și argumentele exacte la fiecare pas. Sarcinile numerotate care urmează traduc fiecare pas în sub-pași bifabili pe care abilitatea subagent-driven-development îi poate parcurge.

Cele două documente se asortează astfel:

Specificația și planul, alăturate. Specificația răspunde la ce se schimbă și de ce. Planul răspunde în ce pași.

Pentru specificații și planuri mai mari, adaug un pas pe care bucla oficială nu îl are: un „red-team pass”. Înainte să semnez, pun unul sau mai mulți subagenți Opus să citească specificația la rece, căutând găuri din unghiuri diferite. Este un obicei personal, nu o funcție Superpowers. A prins destule presupuneri proaste încât să-l păstrez.

Când Superpowers nu e alegerea potrivită

Superpowers se potrivește pentru lucru solo pe un singur repo. Funcționează cel mai bine când întregul codebase încape într-o singură sesiune Claude Code și chiar vei citi o specificație de 2 pagini. Comparația detaliată este în Cum să alegi între ele mai jos. Pe scurt: Superpowers se chinuie cu funcționalități pe mai multe repo-uri și cu munca ce cere separare clară de roluri.

Un dezvoltator a surprins un al patrulea mod de eșec într-o plângere publică despre plugin: „Chiar și cele mai mici sarcini durează o veșnicie, cu Claude pornind subagenți și scriind planuri complet disproporționate. Să schimb niște CSS acum durează o veșnicie.”

Remediul este să sari peste Superpowers pentru schimbări minuscule. Abilitățile se activează doar pe triggerul de brainstorming. O editare CSS de o linie poate trece prin Claude Code fără să invoce vreodată bucla de specificație. Adevăratul mod de eșec aici este aplicarea excesivă a fluxului de lucru la sarcini care nu au nevoie de specificație.

GitHub Spec Kit

Spec Kit este alegerea când specificația trebuie să supraviețuiască oricărei sesiuni individuale Claude Code. Este și opțiunea corectă când oameni care nu deschid niciodată Claude Code trebuie să citească specificația.

Ce este GitHub spec-kit?

Spec Kit este un proiect GitHub (github/spec-kit, licență MIT), întreținut de GitHub însuși, cu peste 100k stele. Vine cu un CLI plus un flux de lucru care rulează la fel în fiecare agent principal de coding AI. Claude Code, Cursor, Aider, Cline și Roo Code sunt toate suportate. Designul neutru față de agent este ceea ce permite ca specificația să trăiască în afara Claude Code.

Pagina proiectului Spec Kit pe GitHub.

Cum instalezi GitHub spec-kit

Nu există încă un pachet oficial pe PyPI, așa că instalează CLI-ul din tagul Git cu uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Înlocuiește vX.Y.Z cu tagul versiunii curente. Pachetul este specify-cli, iar comanda pe care o înregistrează este specify.

Fluxul de lucru GitHub spec-kit

Fluxul rulează prin nouă comenzi slash pe care CLI-ul le instalează în lista de comenzi slash a agentului tău. Șase sunt nucleul buclei, trei sunt opționale pentru cazuri pe care nucleul nu le acoperă.

Separatorul dintre grupul de comenzi și verb este un punct, nu două puncte: /speckit.specify, nu /speckit:specify. 

Cele nouă comenzi slash Spec Kit: șase comenzi de bază pe „conductă” și trei opționale atașate.

Artefactele produse de aceste comenzi sunt aceeași specificație și același plan pe care le-ai văzut în secțiunea Superpowers, de asemenea scrise pe disc și urmărite de Git. Diferența este portabilitatea: artefactele Spec Kit sunt concepute să funcționeze cu orice agent de coding AI, nu doar cu Claude Code, iar fluxul de lucru este construit pentru revizuirea părților interesate prin pull request-uri GitHub, mai degrabă decât ca produs secundar al buclei unui singur instrument.

Când să folosești GitHub spec-kit

Pe un proiect solo, probabil nu vei avea nevoie de Spec Kit. Apelează la el când:

• Proiectul crește dincolo de o singură persoană
• Specificația are nevoie de revizuire de către oameni care nu deschid niciodată Claude Code
• Rulezi un agent non-Claude Code pentru o parte din muncă
• Vrei un format de specificație care trăiește în afara oricărui instrument și încă e lizibil peste luni

Metoda BMAD

Unde Spec Kit organizează artefacte, BMAD organizează oameni. Împarte fluxul de la specificație la cod în patru faze, fiecare rulată de un agent-rol cu nume.

Ce este BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, licență MIT, aproximativ 47k stele) este la versiunea 6. Acronimul, în documentația proiectului, se extinde la „Breakthrough Method for Agile AI-Driven Development”. Rulează peste Claude Code și alți agenți și se instalează ca un ecosistem de module. Instalarea implicită îți oferă un modul de bază cu șase agenți-rol, patru faze de flux de lucru și 34 sau mai multe fluxuri de lucru cu nume.

Pagina proiectului BMAD-METHOD pe GitHub.

Cum instalezi BMAD

Instalează BMAD cu Node:

npx bmad-method install

Cei șase agenți-rol sunt personae de prompt pe care utilizatorul le activează pe nume din interiorul gazdei agentului. În Claude Code, asta înseamnă să tastezi comanda de activare pe care o instalează BMAD. Verifică README-ul pentru sintaxa exactă, care se schimbă între versiuni. 

Prezentarea agenților colegi BMAD și a artefactelor

După activare, agentul preia instrucțiunile, vocea și outputurile acelui rol până când schimbi persona. Cei șase sunt:

• Mary, Analista
• Paige, Technical Writer
• John, Product Manager
• Sally, UX Designer
• Winston, Arhitectul
• Amelia, Dezvoltatoarea

Două roluri la care te-ai aștepta lipsesc în v6: nu există agent Scrum Master și nici agent QA separat. Planificarea sprintului și pregătirea poveștilor revin agentului Developer, iar generarea testelor QA este un flux de lucru pe care Developerul îl declanșează.

Setul de artefacte este mai greu decât o singură specificație. Primești:

• un product brief
• un PRD (Product Requirements Document)
• o specificație UX
• un document de arhitectură
• epic-uri împărțite în user stories (ce pot face utilizatorii după ce munca e livrată)

PRD-ul și documentul de arhitectură joacă împreună același rol ca specificația din Superpowers. Împărțirea le plasează peste doi agenți-rol și într-un format mai formal. Setul de artefacte, în ansamblu, acoperă un ciclu complet de dezvoltare software, fiecare funcționalitate moștenind context din stratul de deasupra.

Fluxul de lucru BMAD

Fluxul de lucru v6 rulează în patru faze.

Cele patru faze BMAD și agentul-rol care o rulează pe fiecare. Traseul Quick Flow sare peste primele trei faze pentru munca mică.

Faza 1, analiza, este opțională. Mary (Analyst) și Paige (Tech Writer) fac research și produc un product brief. Sari peste fază dacă știi deja ce construiești.

Faza 2, planificarea, este obligatorie. John (PM) scrie PRD-ul. Sally (UX Designer) adaugă o specificație UX când funcționalitatea are UI.

Faza 3, solutioning, este faza lui Winston. Arhitectul schițează mai întâi arhitectura, apoi John sparge cerințele în epic-uri și povești. A pune poveștile după arhitectură este o alegere v6 care le dimensionează după granițe reale de implementare. Winston rulează apoi un control de pregătire pentru implementare care se încheie cu un verdict PASS, CONCERNS sau FAIL.

Faza 4, implementarea, este locul unde Amelia (Developer) lucrează poveste cu poveste: creează povestea, o construiește și o code-review-ează. Odată terminat un epic întreg, declanșează un flux de generare de teste QA pe tot epic-ul. Aceasta este faza în care Claude Code face efectiv codingul, lucrând ca Amelia.

Pentru muncă mică, bine definită, BMAD livrează un traseu „Quick Flow” care o activează direct pe Amelia și sare peste primele trei faze. Comanda de activare este în README-ul BMAD (sintaxa exactă se schimbă între versiuni). Quick Flow nu produce PRD și nici document de arhitectură, doar o scurtă poveste și codul care o satisface. Este răspunsul la obiecția „e prea mult pentru o schimbare de buton”.

Când specificația se dovedește greșită în timpul implementării, BMAD revine prin verdictul Fazei 3 al lui Winston. Un FAIL te trimite înapoi la Faza 2 pentru a rescrie PRD-ul. Un CONCERNS continuă cu riscurile notate de Winston atașate poveștii. Împărțirea îți permite să mergi înainte la inconsistențe mici și să te oprești ferm la cele mari.

Când se justifică această complexitate

BMAD se rentează pe proiecte de lungă durată, cu utilizatori reali de deservit. Se potrivește și echipelor cu mai mulți dezvoltatori, care își predau munca între ei. Separarea pe faze și roluri trebuie să economisească mai mult timp decât costă.

Nu este potrivit pentru un proiect lateral cu o singură persoană. Pe muncă solo, împărțirea în patru faze și șase agenți este în mare parte overhead. Nu există a doua persoană în echipă pentru ca separarea rolurilor să conteze.

Cum alegi între cadrele de lucru

Trei reguli decid alegerea.

• Folosește Spec Kit dacă specificația trebuie citită de oameni care nu deschid niciodată Claude Code sau trebuie să trăiască în Git ca artefact pe termen lung.
• Dacă mai multe persoane lucrează pe roluri distincte sau un stakeholder tip PM este în buclă, folosește BMAD.
• În rest, folosește Superpowers.

Trei întrebări despre proiectul tău, patru opțiuni de framework pe cealaltă parte.

Există o a patra opțiune pe care o numește arborele de decizie: combină Spec Kit cu Superpowers. Folosește Spec Kit pentru faza de specificație astfel încât artefactele să trăiască în Git pentru revizuire cross-team. Apoi indică abilitatea subagent-driven-development din Superpowers către fișierul de plan Spec Kit într-o singură linie de configurare. Obții specificația durabilă din Spec Kit, alături de bucla de implementare strânsă din Superpowers.

Concluzie

Dezvoltarea bazată pe specificații înseamnă trei documente, în ordine. Specificația spune ce să construiești, planul spune în ce pași, iar codul urmează planul. O revizuire umană stă între fiecare pereche.

Rulează arborele de decizie de mai sus pentru a alege un framework, care, pentru majoritatea cititorilor, va indica Superpowers. Instalează-l și alege o funcționalitate pe care altfel ai face-o vibe-coding, ceva care atinge 3 până la 5 fișiere. Ruleaz-o cap-coadă prin brainstorming, specificație, plan și execuție. O rulare reală predă fluxul de lucru mai bine decât orice descriere.

Dacă vrei întâi să îți reîmprospătezi elementele de bază Claude Code, DataCamp are un tutorial practic Claude Code, un ghid de bune practici care acoperă modul plan, CLAUDE.md și TDD și un deep dive chiar în modul plan.