claude-agent/docs/flux-dezvoltare.md

Fluxul de lucru pentru cereri de dezvoltare

Regula, pe scurt: planifici cu Opus, execuți cu Sonnet, actualizezi TODO.md. Se aplică oricărei cereri de dezvoltare venite prin puntea Discord, indiferent de proiectul atins.

Ce e „cerere de dezvoltare"

Orice ți se cere să schimbi: funcționalitate nouă, refactorizare, reparare de bug, schimbare de configurație sau de infrastructură, script nou, migrare.

Nu intră aici, și nu au nevoie de plan: întrebări („cum merge X?", „ce e în fișierul Y?"), diagnostice fără modificare, citit loguri, verificat starea unui serviciu, o corectură de o linie pe care utilizatorul a formulat-o deja exact.

Mărimea sarcinii nu e un criteriu. „E doar un script", „e o singură funcție", „știu deja exact ce am de făcut" — nu sunt motive să sari peste plan. Criteriul e unul singur: schimbi ceva? Dacă da, planul se face. Dacă ești în dubiu, planifică. Un plan în plus costă câteva secunde; o execuție greșită pe infrastructura de producție costă mult mai mult.

Singurul caz în care poți sări peste plan la o schimbare este când utilizatorul spune explicit să nu planifici („fă direct", „fără plan").

Pasul 1 — Planifică, pe Opus

Firele Discord rulează pe Sonnet (MODEL_DEFAULT). Nu schimba modelul firului ca să planifici — nu poți, și oricum ar reporni procesul. În loc de asta, delegă planificarea unui subagent pe Opus, din sesiunea curentă:

Agent(
  subagent_type: "Plan",
  model:         "opus",
  description:   "Planifică <cerința>",
  prompt:        "<cerința completă, plus contextul pe care îl știi deja: fișierele
                  relevante, ce ai găsit citind, constrângerile din CLAUDE.md>"
)

Așa obții exact ce a cerut utilizatorul — gândirea pe Opus, execuția pe Sonnet — fără niciun /model și fără repornirea sesiunii.

Înainte de a chema subagentul, citește TODO.md: poate lucrul e deja început, blocat, sau abandonat deliberat, iar planul trebuie să pornească de acolo. Dă-i subagentului contextul pe care îl ai deja — el pornește fără istoricul firului.

Pasul 2 — Postează planul în fir

Rezumă planul în fir înainte de a atinge ceva: pașii, fișierele, ce verifici la final. Scurt — pașii, nu eseul.

Apoi execută. Nu aștepta aprobare pentru pași obișnuiți; utilizatorul poate interveni oricând, un mesaj trimis în timpul turului ajunge la tine ca steering. Cere confirmare explicită doar pentru ce e ireversibil sau are efect în afară: ștergere de date, restart de servicii cu clienți live, pct/qm/zfs destroy, orice ajunge la un client.

Pasul 3 — Execută, pe Sonnet

Execuția o faci tu, în sesiunea firului, care e deja pe Sonnet. Nu delega execuția înapoi unui subagent Opus — ăsta e exact lucrul pe care regula vrea să-l evite.

Termină toată cerința, nu doar partea ușoară. Rulează testele proiectului dacă există (python3 -m pytest -q pentru puntea Discord) și spune rezultatul real, inclusiv când pică.

Pasul 4 — Actualizează TODO.md

La finalul oricărei cereri de dezvoltare, actualizează TODO.md:

1. Mută intrarea în secțiunea potrivită (🟡 În lucru → ✅ Gata, sau ⛔ Blocate dacă te-ai oprit în ceva ce depinde de altcineva).
2. Completează câmpurile: Unde (căi de fișiere), ce face, ce ai verificat, Actualizat/Terminat cu data absolută (nu „azi", nu „ieri").
3. Adaugă o linie în Jurnal, prima, în formatul AAAA-LL-ZZ — <stare> <nume>.
4. Dacă lucrul e nou și nu era în listă, creează intrarea — inclusiv când îl termini într-un singur tur; registrul e util doar dacă e complet.
5. Dacă rămâne ceva neterminat, lasă intrarea în 🟡 În lucru cu următorul pas scris explicit — firul următor pornește fără conversația asta și ăla e tot ce va ști.

TODO.md e în repo-ul claude-agent; comite-l odată cu restul lucrului.

De ce așa

• Opus planifică mai bine, Sonnet execută mai ieftin. Un plan prost costă mai mult decât diferența de model.
• Sesiunile Discord sunt per fir. Un fir nou nu vede conversația din alt fir, deci ce nu e scris în TODO.md, în memorie sau în documentație e pierdut.
• Planul postat în fir e singurul moment ieftin de intervenție. După ce ai scris în /workspace/romfastsql sau ai atins un container, corectura e mai scumpă.