De ce uită AI-ul codul tău de la o zi la alta (și cum rezolvi asta)

Ai lucrat zile întregi la un proiect cu un AI coding assistant. Pe 1 se descurcă excelent. Pe 2, începi o sesiune nouă și trebuie să-i explici totul de la zero. Pe 3 sau 4, cauți prin zeci de mii de tokeni de chat ca să-ți amintești ce s-a decis cu două sesiuni în urmă.

Problema nu e doar contextul limitat. E faptul că stochezi starea proiectului în locul greșit.

De ce chat-ul nu ține loc de bază de date

Conversațiile cu AI-ul sunt bune pentru colaborare. Nu sunt bune ca sistem de evidență.

• O decizie odată trecută e greu de regăsit.
• Nu există o sursă unică de adevăr. Ce specificație urmezi acum?
• Fiecare sesiune nouă pornește de la zero.
• Contradicțiile se acumulează. Un agent decide o strategie de testare, altul o schimbă, al treilea marchează documentația ca terminată când e doar pe jumătate.

Adevărata limitare nu e capacitatea AI-ului de a scrie cod. E capacitatea lui de a înțelege ce construiești și de ce.

Soluția simplă: stochează starea în repo

În loc să ții totul în chat, pune informațiile în fișiere Markdown versionate, la fel ca și codul.

Nu un wiki. Nu un tool separat. Doar fișiere structurate, cu metadate ușoare.

Un exemplu arată cam așa:

# Project Architecture Decision

Lifecycle: active
Role: spec
Project: payment-service
Updated: 2024-01-15

Related:
- implements: charter-payment-api
- pairs-with: implementation-log-payment-core

## Overview

Folosim API-ul direct Stripe în loc de o librărie wrapper pentru că...

## Key Decisions

- Chei de idempotență pentru toate operațiunile
- Procesare async webhook cu backoff exponențial
- PII-ul nu atinge storage-ul local

Formatul e intenționat simplu. Titlu, metadate, rol, legături și conținut. Nimic mai mult.

Ce poți face cu un tool CLI

Un CLI minimal permite operațiuni clare:

• creezi înregistrări noi cu structură consistentă
• arhivezi cele terminate fără să le ștergi
• muți fișiere și actualizezi automat legăturile
• listezi tot ce e activ sau filtrat după rol
• validezi că legăturile duc la fișiere existente
• generezi un index automat

Cum schimbă asta workflow-ul cu AI

În loc să-i ceri agentului să citească tot chat-ul, îi dai o comandă:

docs list --project=payment-service --role=spec
docs check

Agentul interoghează starea proiectului în loc să o reconstruiască din mesaje. Vede ce e decis, ce e în progres, ce e blocat.

Și mai important: modifică starea prin comenzi structurate, nu prin editări directe de fișiere. Verbele (create, archive, touch) garantează că metadatele și indexul rămân consistente.

Modelul „agent proaspăt, stare cunoscută”

Când agentul pornește o sesiune nouă, primul pas e să ruleze docs list. Vede milestone-urile terminate și cel activ. Citește log-ul de implementare. Verifică specificația curentă. Apoi continuă de unde s-a oprit.

Chat-ul vechi devine irelevant. Starea stă în repo.

Cui îi pasă de asta

• Dezvoltatorilor care folosesc AI pair programming pe proiecte multi-zile
• Echipelor care rulează agenți AI ce trebuie să reia lucrul fără transfer complet de context
• Proiectelor cu CI/CD care validează coerența
• Oricui pierde șirul specificației actuale după iterații rapide

Nu înlocuiește Git sau testele. E stratul care face dezvoltarea cu AI coerentă în timp.

De ce funcționează

E banal. Folosești Markdown, Git și CLI — unelte pe care deja le știi. Validarea prinde erorile. Indexul arată clar ce e valid și ce nu. Rezultatul e un agent care nu doar „funcționează”, ci înțelege proiectul și livrează.