Cum dau instrucțiuni cu adevărat unui AI să construiască softwareCum dau instrucțiuni cu adevărat unui AI să construiască softwareCum dau instrucțiuni cu adevărat unui AI să construiască software

Majoritatea dezvoltatorilor folosesc instrumentele AI de coding în același mod greșit. Deschid un chat, tastează o propoziție vagă și se așteaptă ca la celălalt capăt să iasă software funcțional. Când nu se întâmplă, dau vina pe model. Modelul nu este problema. Fluxul de lucru este. Folosesc dezvoltarea asistată de AI în producție de suficient timp cât să am un sistem, iar ideea centrală este simplă: prompting-ul are două faze distincte, și aproape nimeni nu le separă.

Faza unu este o conversație cu un model de gândire (Claude Opus 4.8, GPT-5.5) despre idee. Nu despre cod. Despre constrângeri, cazuri limită, stack-ul tău, convențiile tale, ce ar trebui și ce nu ar trebui să facă această funcționalitate. La sfârșitul acelei conversații, ceri modelului să scrie o specificație de build precisă pentru un agent de coding. Faza doi este să dai acea specificație agentului (Claude Code, Cursor) și să îl lași să planifice și să execute. Modelul de gândire este arhitectul. Agentul de coding este constructorul.

De ce un prompt vag produce terci plauzibil

Un model de limbaj va produce întotdeauna ceva. Aceasta este problema. Cere-i să "adauge o funcționalitate de bookmark" și va scrie cod, cu încredere, bazat pe orice presupuneri completează din datele sale de antrenament. Nu știe că ești pe Next.js 15 App Router, că folosești Prisma cu MySQL, că autentificarea ta este NextAuth v5, că deploy-ezi pe Hetzner via Ploi, sau că ai interzis class component-urile acum șase luni. Face presupuneri rezonabile și produce terci plauzibil: cod sintactic corect care nu se potrivește proiectului tău.

Densitatea semnalului este variabila. Fiecare constrângere pe care o omiți este o decizie pe care modelul o ia pentru tine fără știința ta. Singura soluție este să codifici contextul relevant înainte ca orice cod să fie scris, și cel mai fiabil mod de a face asta este o conversație structurată urmată de o specificație scrisă.

Faza unu: conversație cu modelul de gândire

Deschid Claude sau ChatGPT și descriu ideea în limbaj simplu. Nu un prompt. O descriere. Ce vreau să construiesc, de ce, cine o folosește, care sunt constrângerile. Cer modelului să îmi pună întrebări la rândul lui: ce ar putea merge prost? Ce cazuri limită îmi scapă? Ce ar trebui să nu facă explicit această funcționalitate? Această conversație scoate la suprafață presupuneri despre care nu știam că le fac.

Apoi îi dau modelului un meta-prompt: o instrucțiune structurată care îi spune să producă o specificație de build pentru un agent de coding, codificând stack-ul meu complet și convențiile mele. Iată meta-promptul pe care îl folosesc:

You are a senior software architect and technical writer.
I need you to turn the following idea into a precise build specification
for an AI coding agent (Claude Code / Cursor).

MY STACK:
- Next.js 15 (App Router, TypeScript, Tailwind CSS 4)
- Database: MySQL via Prisma 6. Schema in prisma/schema.prisma.
- Auth: NextAuth v5 with JWT strategy. Session helpers in src/lib/auth.ts.
- Deploy: Hetzner VPS managed by Ploi, Cloudflare CDN in front.
- No class components. No pages/ directory. No getServerSideProps.

IDEA:
[describe your feature here in plain language]

CONSTRAINTS:
- [any non-obvious edge cases, business rules, or perf requirements]

PRODUCE:
1. A one-paragraph summary of what will be built and why.
2. A list of every file that will be created or modified, with a one-line
   description of the change.
3. Numbered acceptance criteria the agent can verify by running
   'npx tsc --noEmit' and 'npm test'.
4. Any migration steps needed (Prisma schema changes, seed data, env vars).
5. Explicit out-of-scope items so the agent does not overshoot.

Output the spec in markdown. Do NOT write any code yet.

Constrângerea cheie din acel meta-prompt este "Do NOT write any code yet." Vrei ca modelul de gândire să facă muncă arhitecturală, nu implementare. Dacă începe să scrie cod, a trecut în modul greșit. Ține-l la specificație.

Faza doi: specificația agentului

Ceea ce iese din modelul de gândire este un document markdown asupra căruia agentul de coding poate acționa efectiv. Numește fiecare fișier care se va schimba, listează criterii de acceptare verificabile și precizează ce este în afara scopului. Agentul nu mai trebuie să ghicească. Iată cum arată o specificație reală pentru o funcționalitate bookmark:

# Build Spec: Bookmark Feature

## Summary
Add a per-user bookmark system so authenticated users can save posts.
Bookmarks are stored in MySQL, surfaced in a new /bookmarks page,
and toggled from individual post pages via a server action.

## Files

- prisma/schema.prisma          add Bookmark model (userId, postSlug, createdAt)
- prisma/migrations/...         generated migration, run before deploy
- src/app/bookmarks/page.tsx    new page, server component, lists user bookmarks
- src/app/actions/bookmarks.ts  server actions: toggleBookmark, getUserBookmarks
- src/components/BookmarkButton.tsx  client component, optimistic UI
- src/app/blog/[slug]/page.tsx  import and render BookmarkButton

## Acceptance Criteria

1. 'npx prisma migrate dev' runs without error on a clean dev database.
2. 'npx tsc --noEmit' passes with zero errors.
3. 'npm test' passes: unit tests for toggleBookmark cover unauthenticated
   call (must throw), duplicate toggle (idempotent remove), and success path.
4. Visiting /bookmarks as an unauthenticated user redirects to /login.
5. Clicking BookmarkButton on a post toggles the filled/outline icon
   without a full page reload (optimistic update via useOptimistic).

## Out of Scope
- Bookmark folders or tags.
- Public bookmark lists.
- Any change to the existing post rendering pipeline.

Observă că criteriile de acceptare sunt verificabile de mașină. Agentul poate rula npx tsc --noEmit și npm test și poate obține un pass sau un fail. Nu trebuie să facă judecăți subiective despre dacă funcționalitatea este gata. Specificația definește gata.

• Fiecare fișier listat îi dă agentului o limită de scope. Știe ce să atingă și ce să lase în pace.
• Secțiunea din afara scopului este la fel de importantă ca secțiunea în scope. Împiedică agentul să adauge funcționalități nesolicitate.
• Pasul de migrare este explicit. Agentul nu va ghici modificările de bază de date.
• Criteriile de acceptare care fac referire la comenzi reale îi dau agentului o buclă de auto-verificare.

Memorie markdown: fișierul AGENTS.md

Iată un fapt despre agenții AI de coding pe care cei mai mulți oameni îl învață pe calea grea: nu au memorie între sesiuni. Agentul care ți-a construit middleware-ul de autentificare săptămâna trecută nu știe astăzi că există. Fără context persistent, va inventa un alt pattern, va încălca convențiile tale de denumire, sau va importa o bibliotecă pe care ai interzis-o.

Soluția este un fișier AGENTS.md la rădăcina proiectului. Aceasta nu este documentație pentru oameni. Este memoria de lucru a agentului, încărcată la începutul fiecărei sesiuni. Codifică stack-ul tău, convențiile tale, comenzile de rulat și pattern-urile de evitat. Deoarece trăiește în repository și este versionat, rămâne actualizat pe măsură ce proiectul evoluează.

Iată un AGENTS.md minimal pentru stack-ul meu tipic Next.js:

# AGENTS.md - Stack and Conventions

## Stack
- Next.js 15, App Router only. No pages/ directory.
- TypeScript strict mode. No 'any'. Use 'unknown' and narrow.
- Tailwind CSS 4 for styling. No inline style props.
- Prisma 6 with MySQL. Schema: prisma/schema.prisma.
- NextAuth v5 - session helpers in src/lib/auth.ts. Do not re-implement auth.
- Deploy: Ploi on Hetzner, Cloudflare in front.

## Conventions
- Server components by default. Add 'use client' only when necessary.
- Server actions in src/app/actions/. One file per domain (bookmarks.ts, etc.).
- Shared UI in src/components/. Page-specific UI co-located with the page.
- Tests in __tests__/ next to the file under test.

## Commands
  npm run dev          start dev server
  npm run build        production build
  npm test             run vitest
  npx tsc --noEmit     type-check only

## Do NOT
- Use getServerSideProps, getStaticProps, or pages/api routes.
- Import server-only modules in client components.
- Use process.env directly in components - use src/lib/config.ts.

Odată ce acel fișier există, nu mai retastezi niciodată stack-ul tău agentului. Meta-promptul pe care îl folosesc pentru a genera specificații face referire directă la el: când descriu stack-ul meu în conversația cu modelul de gândire, actualizez AGENTS.md în același timp. Cele două documente rămân sincronizate. Modelul de gândire folosește stack-ul pentru a scrie o specificație corectă. Agentul de coding citește AGENTS.md pentru a o executa corect.

Verificarea rezultatului într-un pas separat

După ce agentul livrează implementarea, nu cere aceleiași sesiuni să o verifice. Contextul este părtinitor: are un model al a ceea ce a intenționat să scrie, iar acel model îl va face să treacă cu vederea ceea ce a scris de fapt. Pornește o sesiune nouă, încarcă AGENTS.md, încarcă diff-ul și dă agentului un prompt de verificare: revizuiește modificările față de AGENTS.md, raportează încălcări, teste lipsă, erori de tip și bug-uri logice, nu sugera îmbunătățiri.

Contextul proaspăt citește ceea ce este cu adevărat acolo. Nu are nicio atașare față de intenția sesiunii anterioare. Combinat cu criteriile de acceptare verificabile de mașină din specificație, această abordare în două treceri prinde majoritatea problemelor înainte de a ajunge la revizuire.

Bucla completă

Pune totul împreună: ai o conversație cu un model de gândire despre idee, produci o specificație de build folosind meta-promptul, dai specificația agentului de coding împreună cu AGENTS.md, agentul construiește și se auto-verifică față de criteriile de acceptare, apoi rulezi o trecere de verificare separată într-o sesiune proaspătă. Cinci pași, fiecare cu un input și output clar.

Aceasta este mai lentă decât să tastezi o singură linie într-o fereastră de chat. Este mai rapidă decât să depanezi cod pe care agentul l-a scris bazat pe presupuneri greșite, să lupți cu erori de tip pe care specificația le-ar fi prins, și să explici echipei tale de ce funcționalitatea bookmark stochează starea într-un Context provider în loc de o server action.

1. 01Conversație cu modelul de gândire: descrie ideea, scoate la suprafață constrângerile și cazurile limită.
2. 02Meta-prompt: cere modelului de gândire să producă o specificație de build pentru agentul de coding.
3. 03Revizuirea specificației: iterează pe specificație până când criteriile de acceptare sunt verificabile de mașină.
4. 04Execuția agentului: dă specificația și AGENTS.md agentului de coding.
5. 05Trecere de verificare separată: sesiune proaspătă, AGENTS.md, diff, prompt de verificare.

Modelul de gândire face muncă arhitecturală. Agentul de coding face muncă de implementare. Tu faci muncă de judecată: să decizi când specificația este bună, când implementarea este acceptabilă, când să iterezi și când să livrezi. Acea diviziune a muncii este ceea ce face acest sistem fiabil.