Grimoire

Ghid operator pentru software-development

4 min read

Ghid operator pentru software-development

Ce face

software-development este skill-ul umbrelă pentru lucru disciplinat pe cod: debugging, fix-uri test-first, lifecycle GitHub PR, commit-uri, CI triage, pregătire pentru review și igienă de release/merge.

Îl folosești când vrei o intervenție tehnică dusă până la capăt, nu o ghiceală cu diff: problema este înțeleasă, eroarea este reprodusă, cauza este izolată, patch-ul este minim, verificarea pornește de la cel mai mic test relevant și se extinde doar cât trebuie.

Legea de fier este:

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Nu se aplică plasturi peste simptome. Întâi se citește eroarea complet, se reproduce, se verifică schimbările recente, se caută exemple funcționale, se urmărește data flow-ul upstream și abia apoi se schimbă cod.

Când îmi folosește

Folosește software-development pentru:

  • bug-uri, test failures, build failures, regresii, probleme de performanță sau integrare;
  • cereri de implementare care trebuie duse prin branch, commit, PR, CI sau merge;
  • PR creation, PR updates, code-review prep, conventional commits și release hygiene;
  • CI failures unde trebuie citite logurile și diagnosticate cauzele;
  • daemoni, cron jobs, launchd jobs sau event-bus producers cu failures repetate;
  • workspace/repo structure risk review.

Este potrivit mai ales pentru schimbări care par mici. Fix-urile „evidente” sunt locul unde bug-urile se întorc cu dinți noi.

Cum îl invoc / declanșez

Declanșatorii naturali sunt cereri de tipul:

  • repară bug-ul acesta;
  • investighează de ce pică testele;
  • fă fix-ul și pregătește PR-ul;
  • uită-te la CI failure;
  • verifică dacă PR-ul e gata de review;
  • analizează structura repo-ului și riscurile;
  • diagnostichează daemonul sau event-bus failure-ul;
  • fă doar planul, în mod read-only / PROPOSE ONLY / no restart.

Pentru GitHub lifecycle, sunt necesare un repo git cu remote GitHub și autentificare prin gh auth status sau GITHUB_TOKEN. Când gh este disponibil și autentificat, se preferă gh; altfel se folosesc git plus GitHub REST/GraphQL cu token disponibil. Nu se inventează autentificare, remote, PR sau status CI.

Exemplu practic

Ai un test care pică după o schimbare recentă.

Fluxul corect:

  1. Se citește eroarea completă.
  2. Se reproduce failure-ul cu cel mai mic test relevant.
  3. Se inspectează schimbările recente și boundary evidence.
  4. Se urmărește data flow-ul upstream.
  5. Se caută exemple funcționale similare.
  6. Se formulează o singură ipoteză.
  7. Se testează o singură variabilă.
  8. Se creează sau identifică un regression check.
  9. Se fixează cauza, nu simptomul.
  10. Se rulează testul mic, apoi verificări mai largi.
  11. Dacă este cerut GitHub flow: branch, commit, push, PR, CI loop.

Secvență tipică pentru branch și commit:

git fetch origin
git checkout main && git pull origin main
git checkout -b fix/short-description
# edit with file tools, then verify
git add <files>
git commit -m "fix: short description"
git push -u origin HEAD

Cu gh, PR-ul poate fi creat astfel:

gh pr create --title "fix: short description" --body-file .github/PULL_REQUEST_TEMPLATE.md

CI loop: se citesc checks/statuses, se citesc logurile eșuate, se diagnostichează prin același proces, se împinge un fix focalizat și se reverifică. După trei ipoteze eșuate, se oprește și se escaladează arhitectura problemei.

Output / unde aterizează

Output-ul poate fi: diagnostic, patch aplicat, rezultate de teste, commit, PR, CI status, merge executat când este cerut și permis, sau plan read-only.

Pentru cod, se folosesc file tools precum read_file, search_files, patch, write_file. Pentru teste, git, build-uri și CI se folosește terminal. Pentru GitHub, rezultatele trebuie susținute de output real: comandă rulată, status citit, log inspectat, PR creat, CI verificat sau merge confirmat.

Nu se pretinde că un PR, commit, CI result sau merge s-a întâmplat fără dovadă din comandă.

Pentru mai multe ghiduri, vezi All guides.

Limite / gotchas

Nu acceptă „quick fix now, investigate later” ca metodă. Nu se fac mai multe schimbări înainte de rerularea check-ului eșuat. Nu se propun fix-uri înainte de tracing. Nu se sare peste regression test doar pentru că problema „pare simplă”.

În PROPOSE ONLY, read-only sau no restart, limita este dură: se inspectează și se redactează plan, fără modificări, fără clear state, fără restart și fără repair commands.

La daemon și event-bus diagnosis, se pornește de la event records exacte, nu de la sumarul dashboardului: source, event_type, severity, timestamp, exit code, elapsed seconds, group, timeout/coalescing flags și consumed_by. Se citește atât scriptul daemonului, cât și wrapper-ul sau scheduler-ul. Dacă mai multe scripturi pot publica sub aceeași sursă, se identifică writer-ul real înainte de root cause.

La workspace risk review, întâi se face inventar: directoare, fișiere, extensii, fișiere mari, dependency markers, README/agent context, git boundary/status/ignore behavior. Secretele și conținutul credentialelor nu se citesc; se pot semnala doar nume de foldere sau fișiere suspecte.

Graph View