Documenti di progetto

TCAF non si affida alla memoria di una singola chat per ricordare come funziona un progetto. Usa documentazione posseduta dal progetto come evidenza persistente, che modelli e strumenti differenti possono ispezionare di nuovo.

Questi documenti non sono copie del framework. Descrivono il progetto target e rimangono al suo interno perché fanno parte dello stato ingegneristico corrente.

Le istruzioni del framework vivono nel runtime TCAF installato. La verità del progetto vive nel progetto target.

Perché i ruoli canonici sono importanti

Un progetto può già contenere README, note architetturali, ADR, issue tracker, runbook e documenti di prodotto. TCAF non dovrebbe duplicarli automaticamente.

Il project manifest associa ruoli canonici ai percorsi autorevoli reali. Il ruolo indica quale informazione serve a TCAF; il manifest indica dove si trova quell’informazione nel progetto specifico.

Per esempio, il backlog ufficiale può essere:

• un file Markdown nel repository;
• GitHub Issues;
• un altro tracker esterno;
• richieste dirette del developer in un progetto leggero.

TCAF registra la fonte invece di imporre un secondo backlog.

Ruoli comuni dei documenti di progetto

I nomi dei file possono variare, ma un progetto adottato o avviato normalmente richiede i ruoli seguenti.

Project brief

Descrive scopo del progetto, utenti, obiettivi correnti, confini e contesto importante.

Dovrebbe distinguere fatti confermati e aspirazioni, evitando di trasformare un brief sintetico in una specifica di prodotto inventata.

Architecture

Descrive l’architettura realmente esistente:

• applicazioni e servizi;
• moduli principali;
• flussi dati e integrazioni;
• tecnologie in uso;
• confini di runtime o deploy;
• vincoli architetturali importanti.

Non dovrebbe sostituire il sistema corrente con un’architettura ideale, a meno che il documento la identifichi esplicitamente come proposta.

Capability baseline

Registra cosa il software può fare oggi, quali limitazioni esistono e cosa è soltanto pianificato.

Una baseline utile distingue:

• capability implementata e sostenuta da evidenze;
• implementata con limitazioni note;
• non disponibile;
• proposta o pianificata;
• incerta e da validare.

Questo evita che nomi di file, mockup o roadmap vengano confusi con feature funzionanti.

Project rules

Raccoglie regole ingegneristiche specifiche del repository che un agente deve rispettare.

Esempi:

• aspettative preservation-first;
• architettura locale e convenzioni di naming;
• riuso obbligatorio di utility, guard e servizi;
• modifiche vietate a dipendenze o infrastruttura;
• aspettative di test;
• gestione dei file generati;
• sicurezza Git e confini di review.

Queste regole dovrebbero essere concise e specifiche del progetto. Le istruzioni generali TCAF restano nel runtime del framework.

AI workflow

Spiega come il lavoro assistito dall’AI viene trasportato e revisionato nel progetto.

Può identificare:

• adapter attivo o strumenti supportati;
• review gate;
• modalità di approvazione dei contratti;
• chi esegue i controlli manuali;
• come vengono preservate le modifiche del developer;
• se commit o aggiornamenti del tracker richiedono approvazione separata;
• limitazioni specifiche dello strumento.

Regole di naming o fonte dei task

Definisce come vengono identificati i task e da dove arriva il lavoro autorevole.

Può descrivere identificativi del backlog, riferimenti alle issue, convenzioni per richieste dirette e modalità di registrazione dei follow-up.

Project manifest

Associa i ruoli canonici a percorsi e fatti operativi reali del progetto.

Può registrare:

• root delle applicazioni;
• percorsi frontend, backend e condivisi;
• documenti canonici;
• fonte dei task;
• comandi pertinenti di test, typecheck o build;
• comandi non disponibili;
• note su adapter o workflow;
• regole target specifiche del progetto.

Il manifest deve riflettere percorsi e strumenti esistenti, non quelli desiderati.

Riutilizzare i documenti esistenti

L’adozione inizia osservando ciò che è già presente.

Quando un documento esistente è autorevole e adeguato, il manifest dovrebbe referenziarlo. TCAF dovrebbe creare un nuovo documento canonico soltanto quando il ruolo necessario manca, è frammentato o non può essere dedotto in sicurezza dalle fonti correnti.

Non riscrivere documentazione storica soltanto per uniformarne la formattazione.

I documenti sono evidenze, non decorazione

Un documento generato non è corretto perché è dettagliato. Il developer deve verificare che rappresenti fedelmente il progetto.

Durante la review dell’adozione controlla:

• I percorsi elencati esistono?
• I comandi esistono davvero e funzionano nel contesto dichiarato?
• L’architettura descrive il sistema corrente?
• Le feature pianificate sono separate da quelle implementate?
• Limitazioni e incognite sono visibili?
• La fonte ufficiale dei task è corretta?
• Documenti esistenti e modifiche del developer sono stati preservati?
• L’adozione ha evitato modifiche al codice applicativo?

La validazione strutturale può confermare che ruoli e percorsi rispettano lo schema. Non può dimostrare che ogni frase sia fattualmente corretta.

Separare stato corrente e stato desiderato

Molti documenti di progetto mescolano ciò che esiste con ciò che il team desidera costruire. TCAF dovrebbe etichettare chiaramente la differenza.

Categorie utili:

• stato corrente;
• stato desiderato;
• decisione confermata;
• proposta;
• domanda aperta;
• contesto storico.

Questa distinzione è particolarmente importante nel bootstrap greenfield e quando si pianifica da un’analisi o roadmap.

Aggiornare i documenti di progetto

L’implementazione non autorizza automaticamente l’aggiornamento della documentazione.

Dopo che il developer ha accettato il lavoro, una fase di riconciliazione può aggiornare:

• capability baseline;
• stato del backlog o della issue;
• architettura quando è stata accettata una modifica architetturale reale;
• project manifest quando cambiano percorsi o comandi;
• project rules quando viene adottata esplicitamente una nuova regola.

L’aggiornamento deve descrivere realtà accettata. Non deve segnare come completato lavoro estraneo o riscrivere la storia.

Documenti e indipendenza dal modello

Poiché le evidenze di progetto sono conservate in file ordinari o fonti esterne dichiarate, un nuovo modello o strumento può riprendere ispezionando lo stesso stato.

Questo riduce la dipendenza da:

• memoria privata della chat;
• formato di regole di un singolo vendor;
• un solo workspace editor;
• riepilogo precedente di un agente;
• assunzioni ricostruite soltanto dal codice.

L’indipendenza dal modello non è quindi soltanto una caratteristica degli adapter. Dipende dal mantenimento di evidenze durevoli e veritiere.

Quando il progetto usa una modalità più leggera

Progetti piccoli o già documentati possono non richiedere un insieme esteso di file. TCAF può associare fonti esistenti e creare soltanto le evidenze minime mancanti necessarie per lavorare in sicurezza.

Minimum-first richiede comunque informazioni sufficienti per rispondere:

• Qual è il target?
• Cosa esiste oggi?
• Quali regole devono essere preservate?
• Da dove arriva il lavoro?
• Come viene verificato e revisionato il risultato?

L’obiettivo non è produrre molta documentazione. È mantenere continuità affidabile.