AI Spec-Driven Development: ghidul arhitectural complet

Agenții AI de programare scriu sute de linii în câteva secunde. Asta e partea ușoară. Partea grea vine după: să citești codul, să verifici că face ce trebuia și să păstrezi arhitectura întreagă când într-o săptămână ajung o duzină de pull request-uri scrise de agenți. Doar scriind cod mai repede nu livrezi software mai bun.

Cercetările spun același lucru, cu nuanțe. În trei experimente de teren cu 4.867 de programatori de la Microsoft, Accenture și o companie din Fortune 100, un asistent AI de programare a crescut numărul de sarcini finalizate cu 26,08%. Dar un studiu randomizat cu maintaineri open-source experimentați, care lucrau în baze de cod mari pe care le cunoșteau bine, a găsit opusul: cu unelte AI permise, sarcinile au durat cu 19% mai mult.

Câștigurile diferă și după experiență. În aceleași experimente, angajații noi și programatorii juniori și-au crescut producția cu 27–39%, iar programatorii seniori cu 8–13%.

Dezvoltarea ghidată de specificații (spec-driven development, SDD) este modul în care echipele trec de această scădere. Este și standardul de inginerie după care lucrăm la Dataforge, în proiectele clienților și la acest site. Ghidul acoperă principiile, un flux de lucru în zece faze, un șablon de specificație reutilizabil, un exemplu lucrat și metricile care îți arată dacă funcționează.

Ce este dezvoltarea ghidată de specificații?

Spec-driven development este o disciplină de inginerie care face din specificație un artefact de prim rang, versionat. Specificația poate fi citită de oameni și interpretată de unelte și se scrie înainte de cod, nu după. Într-un flux cu AI, ea este contractul executabil: îi spune agentului ce să construiască, ce constrângeri să respecte și cum va fi testat rezultatul.

Cum se compară SDD cu practicile existente

SDD nu înlocuiește TDD sau DevOps. Stă deasupra lor și leagă intenția arhitecturală de codul generat. Testele dovedesc în continuare comportamentul; specificația spune ce comportament contează și de ce.

Șase principii ale dezvoltării ghidate de specificații cu AI

Cerințe testabile

Fiecare cerință este o afirmație pe care o poți verifica, nu proză deschisă interpretării.

Constrângeri explicite

Limitele de securitate, bugetele de latență, siguranța firelor de execuție și limitele de dependențe se scriu înainte să înceapă generarea.

Loturi mici

Lucrul în loturi mici este una dintre cele șapte capabilități care, potrivit DORA, amplifică beneficiile AI. Specificațiile împart funcționalitățile în sarcini izolate, pe care un agent le poate termina și un om le poate verifica.

Trasabilitate

Cerință → afirmație din specificație → cod generat → test. Fiecare legătură poate fi urmărită în ambele sensuri.

Control uman

Agenții propun planuri și implementări; inginerii aprobă designul și integrarea.

Validare continuă

Verificările CI, testele de contract și analiza statică compară specificația cu sistemul real la fiecare schimbare.

Fluxul SDD în zece faze

În practică, SDD este un flux care alternează direcția dată de oameni cu execuția agenților. Filtrează după cine participă ca să vezi unde se duce timpul inginerilor: agentul face volumul, oamenii răspund de porți.

Specificații pe care agenții le pot folosi

O specificație bună îi dă agentului destul context ca să facă alegerile potrivite, fără să-i dicteze fiecare linie. Specifici comportamentul, contractele și constrângerile; structura internă rămâne pentru implementare și review.

Șablon reutilizabil de specificație

# Feature specification: [feature name]

## 1. Objective and context
- **Goal**: [1–2 sentences: the business or technical problem this solves]
- **Consumer**: [primary user role or calling service]

## 2. Functional requirements and acceptance criteria
- [ ] **REQ-1**: [one unambiguous statement of behaviour]
  - *AC-1.1*: Given [state], when [action], then [observable outcome].
- [ ] **REQ-2**: [next requirement]

## 3. Constraints (non-functional)
- **Performance**: [e.g. p95 latency < 200 ms at 1,000 RPS]
- **Security**: [e.g. JWT auth; RBAC enforced on the endpoint]
- **Dependencies**: [e.g. reuse the Redis cache; no new npm packages]

## 4. Contracts and data
```json
// JSON Schema or OpenAPI fragment
{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "format": "uuid" },
    "amount": { "type": "number", "minimum": 0.01 }
  },
  "required": ["order_id", "amount"]
}
```

## 5. Edge cases and errors
- **EC-1**: Duplicate submission (idempotency key).
- **EC-2**: Database timeout mid-transaction → HTTP 503 with the standard error body.

## 6. Testing
- **Unit**: > 90% coverage of domain logic.
- **Integration**: mock the payment gateway (approved, declined, timeout).

De la o cerință vagă la una măsurabilă

Cele mai multe rezultate proaste ale agenților pornesc de la o frază care sună a cerință, dar nu poate fi testată. Rescrierea adaugă patru lucruri pe care altfel agentul le-ar ghici.

Exemplu lucrat: un API de creare a comenzilor

Iată SDD pe un endpoint de backend mic, în Python cu FastAPI și Pydantic: întâi specificația, apoi testele scrise de agent pe baza ei, apoi implementarea.

Pasul 1: specificația

# Spec: order creation endpoint

## Requirements
- Endpoint: `POST /v1/orders`
- Idempotency: require the `X-Idempotency-Key` header.
- Validation: the customer must exist; the order total must be above 0.
- Responses: 201 Created, 400 Bad Request, 409 Conflict on a reused idempotency key.

Pasul 2: agentul scrie întâi testele

import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_order_success():
    headers = {"X-Idempotency-Key": "unique-uuid-1234"}
    payload = {"customer_id": "cust_888", "amount": 49.99, "items": ["item_1"]}
    response = client.post("/v1/orders", json=payload, headers=headers)
    assert response.status_code == 201
    assert "order_id" in response.json()

def test_create_order_duplicate_idempotency():
    headers = {"X-Idempotency-Key": "duplicate-uuid-5555"}
    payload = {"customer_id": "cust_888", "amount": 20.00, "items": ["item_2"]}

    # First request
    res1 = client.post("/v1/orders", json=payload, headers=headers)
    assert res1.status_code == 201

    # Same key again
    res2 = client.post("/v1/orders", json=payload, headers=headers)
    assert res2.status_code == 409
    assert res2.json()["detail"] == "Duplicate request processed"

Pasul 3: agentul scrie implementarea

from fastapi import FastAPI, Header, HTTPException, status
from pydantic import BaseModel, Field, PositiveFloat
import uuid

app = FastAPI()

# In-memory idempotency store (see the review notes below)
PROCESSED_KEYS = set()

class OrderRequest(BaseModel):
    customer_id: str = Field(..., min_length=1)
    amount: PositiveFloat
    items: list[str] = Field(..., min_length=1)

class OrderResponse(BaseModel):
    order_id: str
    status: str

@app.post("/v1/orders", status_code=status.HTTP_201_CREATED, response_model=OrderResponse)
def create_order(
    order: OrderRequest,
    x_idempotency_key: str = Header(..., alias="X-Idempotency-Key"),
):
    if x_idempotency_key in PROCESSED_KEYS:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Duplicate request processed",
        )

    PROCESSED_KEYS.add(x_idempotency_key)
    order_id = f"ord_{uuid.uuid4().hex[:8]}"
    return OrderResponse(order_id=order_id, status="confirmed")

Structura proiectului și contextul

Uneltele AI găsesc specificațiile când stau într-un loc previzibil. Ține-le în repository, lângă codul pe care îl descriu.

my-application/
├── .spec/
│   ├── ARCHITECTURE.md          # global rules and invariants
│   ├── ADRs/                    # architecture decision records
│   └── features/
│       ├── order-creation.spec.md
│       └── payment-processing.spec.md
├── docs/
│   └── openapi.yaml             # API contracts
├── src/
│   ├── domain/
│   └── api/
└── tests/
    ├── unit/
    └── integration/

Dă-le agenților acces la contextul intern

Datele interne accesibile AI-ului sunt una dintre cele șapte capabilități din modelul DORA AI Capabilities: conectarea uneltelor AI la documentația internă și la baza de cod transformă un asistent generic într-unul util. Când arhitectura și convențiile există doar în mintea oamenilor, agenții umplu golul cu cod plauzibil și redundant. Specificațiile din repository le dau lui Claude Code, Cursor sau GitHub Copilot aceeași sursă de adevăr pe care o citesc inginerii tăi.

Standardul nostru actual la Dataforge

Dezvoltarea ghidată de specificații este modul în care lucrează Dataforge astăzi: este standardul de inginerie al companiei, nu un experiment. Și acest site îl urmează. Un dosar de specificații păstrează invarianții arhitecturii ca reguli MUST: niciun text scris direct în cod, fiecare pagină are metadate și date structurate, animațiile sunt doar un plus progresiv. Fiecare schimbare care nu e trivială începe ca o specificație de schimbare numerotată, cu obiectiv, scop, criterii de acceptare și specificațiile pe care le va actualiza. Un fișier AGENTS.md trimite fiecare agent de programare la specificații înainte să atingă codul, iar o definiție scrisă a lui „gata” decide când o schimbare e terminată. Și acest articol a trecut prin același proces.

Tot așa lucrăm și la proiectele de dezvoltare software externalizate: aprobi specificația, iar prețul e fix pe fiecare etapă, raportat la ea.

Greșeli frecvente și cum le eviți

Specificațiile nu elimină toate problemele. Acestea sunt cele patru pe care le vedem cel mai des când echipele lucrează cu tot mai mulți agenți AI.

Metrici: funcționează SDD?

SDD transformă controlul calității din vânătoare de buguri la final în verificare continuă. Măsoară-l cu metricile de livrare pe care probabil le știi de la DORA, plus două care arată costul review-ului.

Ritm de livrare

Timpul de livrare a schimbărilor și frecvența lansărilor. Ajunge viteza AI în producție sau se adună la review?

Instabilitate

Rata schimbărilor eșuate și timpul de recuperare după o lansare eșuată. Provoacă incidente codul generat?

Efort de review

Comentarii și rate de aprobare pe pull request. Trece codul agenților ușor de review?

Rata de refacere

Cât de des livrezi corecturi neplanificate pentru ceva tocmai livrat.

Concluzie

Dezvoltarea ghidată de specificații transformă agenții AI din generatoare de cod rapide și imprevizibile în participanți disciplinați la fluxul de livrare. AI-ul face codul brut ieftin; de aceea designul sistemului, modelarea domeniului și judecata umană asupra compromisurilor valorează mai mult, nu mai puțin.

Scrie specificații testabile, pune fiecare schimbare prin verificări automate, păstrează loturile mici, iar curba J devine mai mică: păstrezi viteza și păstrezi codul sănătos.

Agentul scrie codul. Specificația decide ce înseamnă corect.

Dacă vrei să încerci SDD pe un proiect real fără să construiești singur procesul, programează un apel de 30 de minute. Îți arătăm o specificație dintr-un proiect de-al nostru și îți spunem sincer dacă abordarea se potrivește cu al tău.