Project Analyzer: L'agent che scansiona progetti per te

Nerd Level: 3/5
Project Analyzer: L'agent che scansiona progetti per te

Quando La Memoria Si Sgretola

“…ProjectFlow? Aspetta… era quello in Laravel o React? E il database era MySQL o PostgreSQL? Chi era il referente tecnico?”

10-20 progetti attivi. 50+ progetti totali negli ultimi anni.

Quando passa tempo tra una manutenzione e l’altra, la memoria si sgretola. Ti ricordi che esisteva il progetto, sai di averlo fatto tu, ma i dettagli sono annebbiati.

Nota mentale ricorrente: “Devo documentare meglio.” → Mai fatto, ovviamente.

Il Fallimento della Documentazione Manuale

Ho provato a creare README dettagliati in ogni repo. L’idea era: “Se documento tutto adesso, quando tornerò fra sei mesi avrò tutto sotto mano.”

Problemi reali:

  1. Nessuno li aggiorna (me compreso). Oggi aggiungo una feature, domani fixo un bug, dopodomani cambio lo stack di deployment. Il README? Fermo a sei mesi fa.

  2. Info sparse ovunque. Stack tecnico nella repo. Nome del cliente nelle email. Referenti negli appunti cartacei (sì, li uso ancora). Quando serve un’info, non ricordo dove l’ho scritta.

  3. Contesto tecnico e business separati. Il README parla di Laravel e MySQL, ma non dice “cliente fidelizzato da 3 anni, pagamenti regolari, alto potenziale per nuovi progetti”.

  4. Quando serve, è già obsoleto. Il cliente chiama dopo sei mesi. Apro il README: “Deployment su VPS X con IP Y”. Peccato che nel frattempo siamo migrati su un altro server.

Risultato: README fantasma, documentazione obsoleta, ogni volta ricomincio da zero.

L’Idea: Se L’AI Lo Analizzasse Per Me?

Un giorno mi sono chiesto: ma se invece di documentare manualmente, lasciassi che un’AI scansionasse il progetto e generasse la documentazione per me?

Input minimo: Nome progetto + repo GitHub + cliente

Output: Due file markdown completi:

  • database/projects/projectflow.md - Info tecnica del progetto
  • database/companies/acme-consulting.md - Info del cliente

Tempo: ~2 minuti (completamente automatico).

Mantenimento: Zero. Quando serve una versione aggiornata, lo rilancio e rigenera tutto.

Mi sono imbarcato nell’esperimento, e da allora l’ho usato su una ventina di progetti. Funziona meglio di quanto pensassi.

Come Funziona: Quattro Fonti di Informazioni

1. Repository GitHub

Il primo passo è clonare la repo in /tmp e analizzarla. Cerco:

  • Stack tecnico: Guardo la struttura delle cartelle. C’è app/Models/? Laravel. C’è src/? Probabilmente React o Vue. C’è pages/? Next.js.

  • Entità database: Leggo i models e le migrations. Quali tabelle ci sono? Come sono relazionate? Ci sono pattern interessanti (versioning, state machine, polymorphic relations)?

  • Git history: Prime e ultime commit per capire la timeline del progetto. Quanto è attivo? Chi ci ha lavorato?

Questo mi dà il contesto tecnico: cosa fa il sistema, con che tecnologie, e quanto è complesso.

2. Email Archive

Cerco tutte le email che contengono il nome del progetto o del cliente. Ho 19 anni di email importate nel brain (sì, davvero), quindi trovo praticamente tutto.

Le email mi danno:

  • Timeline della collaborazione: Kickoff a marzo 2022, feature X richiesta a giugno 2023, ultimo contatto novembre 2025.

  • Referenti principali: Chi mi scrive più spesso? Mario Rossi (CTO), Laura Bianchi (PM).

  • Tone e stile della relazione: Email formali o informali? Urgenze frequenti o ritmo rilassato?

Questo mi dà il contesto relazionale: da quanto tempo collaboriamo, chi sono le persone chiave, com’è il rapporto.

3. Web Research

Se il cliente è un’azienda, faccio una ricerca web rapida per trovare:

  • Ragione sociale completa
  • Sede e contatti
  • Settore / industry
  • LinkedIn aziendale

Questo mi dà il contesto business: cosa fa il cliente, quanto è grande, dove si trova.

4. Pattern Discovery

Mentre analizzo il codice, cerco pattern architetturali interessanti che ho usato e che potrebbero essere riutilizzabili in altri progetti.

Esempio reale: In un progetto di gestione documentale ho trovato un sistema di versioning documents con parent-child relationships. Documento 2025-123-R2 significa: anno 2025, ID originale 123, revisione 2. L’ho riutilizzato in altri tre progetti dopo averlo documentato.

Questo mi dà template riutilizzabili per il futuro.

Output: Documentazione Strutturata

L’AI genera due file markdown completi. Esempio:

File 1: database/projects/projectflow.md

---
name: ProjectFlow
client: ACME Consulting
type: gestionale
stack: Laravel, PHP, MySQL
status: produzione
repo: https://github.com/user/projectflow
started: 2022-03
last_updated: 2025-11
---

# ProjectFlow - Gestionale Progetti

**Cliente**: [[database/companies/acme-consulting|ACME Consulting]]
**Repository**: https://github.com/user/projectflow

## Overview

Sistema gestione progetti per ACME Consulting.

Funzionalità:
- Gestione clienti e progetti
- Time tracking operatori
- Fatturazione automatica
- Dashboard manager/operatore

## Stack Tecnico

**Backend**: Laravel 10, PHP 8.2, MySQL
**Frontend**: Livewire + Alpine.js
**Deployment**: GitHub Actions → VPS

## Schema Database

### Entità Principali

1. **Client** - Aziende clienti
   - Relations: projects[], invoices[]

2. **Project** - Progetti
   - client_id
   - status: draft|active|completed|archived
   - Relations: tasks[], timesheets[]

3. **Task** - Attività progetto
   - project_id, user_id
   - estimated_hours, actual_hours
   - Relations: timesheets[]

### Pattern Interessanti

**Timesheet Aggregation**: Calcolo automatico ore da timesheet giornalieri.

**Invoice Generation**: Da task completate → fattura draft.

## Timeline Sviluppo

- 2022-03: Kickoff progetto
- 2022-06: Launch MVP (clienti + progetti)
- 2023-01: Time tracking + fatturazione
- 2023-06: Dashboard avanzate
- 2025-11: Ultimo contatto (richiesta esportazione dati)

## Status Attuale

**Produzione**: Sistema stabile, ~50 utenti attivi.

**Prossime features**: Integrazione contabilità esterna (richiesta 2025-11).

File 2: database/companies/acme-consulting.md

---
name: ACME Consulting
full_name: ACME Consulting Srl
founded: 2015
industry: Consulenza IT
location: Via Roma 123, 20100 Milano
employees: 10-50
relationship: cliente
status: attivo
website: https://acme-consulting.it
---

# ACME Consulting

**Settore**: Consulenza IT e Digital Transformation
**Sede**: Milano
**Dipendenti**: ~30

## Persone di Riferimento

### Mario Rossi
**Ruolo**: CTO
**Email**: mario.rossi@acme-consulting.it
**Note**: Referente tecnico principale

### Laura Bianchi
**Ruolo**: Project Manager
**Email**: laura.bianchi@acme-consulting.it
**Note**: Coordinamento operativo

## Progetti con Noi

### ProjectFlow
**Tipo**: Gestionale progetti custom
**Status**: Produzione
**Durata**: 3+ anni (2022-presente)

## Timeline Collaborazione

- 2022-03: Primo contatto, kickoff ProjectFlow
- 2022-06: Go-live MVP
- 2023-01: Feature time tracking
- 2025-11: Richiesta integrazione contabilità

## Relationship Status

**Tipo**: Cliente fidelizzato
**Durata**: 3+ anni
**Salute**: ✅ Ottima - richieste periodiche, pagamenti regolari
**Potenziale**: Alto - interesse per nuovi progetti

Nota i wikilinks tipo [[database/companies/acme-consulting|ACME Consulting]]. Funzionano in Obsidian/Logseq, rendendo tutto navigabile.

Workflow Pratico

Comando da CLI:

analyze-project --name projectflow --repo user/projectflow --client "ACME Consulting"

Esecuzione (~2 minuti):

  1. Clone repo in /tmp
  2. Analisi README + models + migrations
  3. Cerca 50+ email “projectflow” e “ACME”
  4. Web search “ACME Consulting Milano”
  5. Genera 2 file markdown
  6. Commit automatico nel brain

Output:

✅ database/projects/projectflow.md (creato)
✅ database/companies/acme-consulting.md (creato)

Analisi completata:
- Stack: Laravel + MySQL
- Entità DB: 8 models principali
- Email trovate: 67
- Timeline: 2022-03 → 2025-11
- Referenti: Mario Rossi (CTO), Laura Bianchi (PM)

Prima vs Dopo

Prima:

  • Cliente chiama → “Aspetta, cerco appunti…”
  • 10-15 minuti per ricostruire contesto
  • Rischio di info sbagliate/obsolete
  • Ogni volta si ricomincia da zero

Dopo:

  • Cliente chiama → grep "projectflow" database/projects/
  • 30 secondi per avere tutto il contesto
  • Info sempre aggiornate (rigenero quando serve)
  • Wikilinks: progetti → aziende → persone (navigabile in Obsidian)

Bonus Imprevisto: Pattern Riutilizzabili

Analizzando 20 progetti, ho iniziato a vedere pattern ricorrenti.

Versioning documents (3 progetti):

Document
  ├─ document_id (parent)
  ├─ revision_number
  └─ code: YYYY-ID-RN

Polymorphic tasks (5 progetti):

Task
  ├─ taskable_id
  └─ taskable_type (Project|Order|...)

Role-based dashboards (7 progetti):

User
  ├─ type: admin|manager|operator
  └─ Routes: /admin/, /manager/, /operator/

Questi pattern sono diventati template riutilizzabili per nuovi progetti. Quando un cliente mi chiede “un sistema di task”, so già che probabilmente userò polymorphic tasks perché li ho già fatti 5 volte e funzionano.

Limitazioni (È Un Tool, Non Magia)

Non funziona se:

  • Repo non accessibile (serve GitHub/GitLab con SSH)
  • Email senza keyword cercabili (cliente che scrive sempre “Ciao!” senza context)
  • Azienda senza presenza online (difficile fare web research)

Non sostituisce:

  • Documentazione tecnica dettagliata (architecture docs, API specs)
  • Knowledge domain-specific (business rules complesse che conosci solo parlando col cliente)
  • Comunicazione umana (call per capire nuove esigenze)

È ottimo per:

  • Overview rapido di un progetto
  • Ricostruzione contesto dopo mesi di silenzio
  • Onboarding nuovo developer su progetto esistente
  • Pattern discovery cross-project

Estensioni Future

Cose che vorrei aggiungere (ma non ho ancora fatto):

Git History Analysis: Contributors principali, commit frequency (progetto attivo o dormiente?), branching strategy

Dependency Check: Versioni outdated (composer/npm), security vulnerabilities, license compatibility

Code Metrics: LOC, cyclomatic complexity, test coverage

API Documentation: Estrarre endpoints da routes, generare Swagger/OpenAPI draft

Compare Projects: “Quali progetti usano pattern X?”, “Stack più comune negli ultimi 2 anni?”, “Cliente medio: quante feature/anno?”

Conclusione

Il brain non è solo per immagazzinare nuove conoscenze. È anche per ricostruire ciò che già sapevi ma hai dimenticato.

Il Project Analyzer fa esattamente questo:

  1. Analizza automaticamente progetti esistenti
  2. Estrae info tecniche + business + relazionali
  3. Crea documentazione strutturata e navigabile
  4. Identifica pattern riutilizzabili

Risultato: Quando un cliente chiama dopo 6 mesi, so subito di cosa stiamo parlando.

Zero ansia. Zero tempo perso. Tutto già lì, in due file markdown.

Note: Il Project Analyzer è parte del mio sistema “Brain” (knowledge base personale). Se vuoi saperne di più sul brain system, ci sono altri post che spiegano il concept generale e i workflow pratici.