Ho trovato oltre 30 repository GitHub utili e ho smesso di perderne traccia (Claude + Obsidian, Guida completa)

Segno un repository, lo clono, lo faccio funzionare a metà e passo al problema successivo. Tre mesi dopo ritrovo la stessa cartella e non ricordo perché l'avevo presa, se l'ho mai usata davvero, o se ho clonato lo stesso tipo di strumento due volte con nomi diversi. Con più di trenta repository, la cosa smette di essere uno scherzo e inizia a costare tempo reale.

Perché un README per repository non basta?

Un README ti dice per cosa l'ha costruito l'autore. Non dice nulla sul perché tu l'abbia preso, se lo stai effettivamente usando, o se hai già altri tre strumenti che fanno esattamente lo stesso lavoro.

Questa è la parte che nessuno scrive, perché nessuno la scrive per repository che non sono i suoi. Cloni qualcosa di utile, lo fai funzionare una volta, e il contesto del perché sparisce nel momento in cui chiudi il terminale. Moltiplicalo per 30 repository nella stessa cartella e ottieni un cimitero che hai paura di ripulire, perché non sei sicuro di cosa sia essenziale e cosa sia zavorra.

Niente di tutto questo appare in un singolo README. Appare solo quando qualcosa legge attraverso tutto ciò che hai raccolto, con una cadenza regolare, senza che tu debba ricordarti di controllare.

Cosa otterrai?

Un vault, due cartelle:

1found-tools-vault/
2├── notes/                  # una nota markdown per ogni repository preso
3│   ├── some-scraper-tool.md
4│   ├── some-telegram-lib.md
5│   └── ...
6└── memory/
7    └── PORTFOLIO.md         # qui scrivono le quattro scansioni incrociate

Markdown semplice su disco. Aprilo in Obsidian, o visualizzalo dal terminale. Nessun database, niente che tu non possa leggere da solo.

Come si configura?

Su Mac o Linux:

1mkdir -p ~/found-tools-vault/notes ~/found-tools-vault/memory

Su Windows, PowerShell:

1New-Item -ItemType Directory -Force -Path "$HOME\found-tools-vault\notes","$HOME\found-tools-vault\memory"

Punta il Ciclo 1 e il Ciclo 2, qui sotto, verso questa cartella e la configurazione è fatta. Tutto ciò che segue è quello che dici a Claude di fare al suo interno.

Lo stack: gli stessi tre elementi, ma puntati al codice degli altri?

Il vault. Una cartella Obsidian, una nota per ogni strumento che hai clonato, più una cartella per le scansioni incrociate.

La fonte. Ogni repository nella tua cartella dei cloni, che tu lo usi quotidianamente o che ne abbia dimenticato l'esistenza.

Il cervello. Claude, suddiviso per compito. Il modello economico legge il repository e il suo README. Sonnet fa le valutazioni: è un duplicato di qualcos'altro che hai già preso, e vale davvero lo spazio su disco?

Ciclo 1: una nota per strumento, scritta da Claude, non da te?

Importante, prima di eseguire questo su qualsiasi cosa reale:

• Non lasciare mai che questo ciclo invii codice, installi dipendenze o esegua qualsiasi cosa dallo strumento stesso. Sola lettura, sempre.
• why_i_grabbed_it viene compilato dai tuoi appunti, commit o utilizzo altrove nei tuoi progetti, non indovinato dal README del repository stesso.
• Se non riesci a capire se stai usando uno strumento, scrivi la nota con stato: unclear invece di saltarlo.

1TRIGGER:   nuovo repository clonato nella cartella, o una volta al giorno
2PASSI:
3  1. Leggi il repository: README, package.json / requirements.txt, data
4     dell'ultimo commit upstream e controlla se è referenziato da qualche
5     parte nei tuoi altri progetti (import, configurazioni, script)
6  2. Scrivi o aggiorna notes/<nome-repository>.md con:
7       ---
8       repo:
9       what_it_does:
10       why_i_grabbed_it:
11       last_upstream_commit:
12       referenced_in_my_projects: []
13       status: in-use | shelved | duplicate | unclear
14       ---
15       ## Cosa fa effettivamente
16       ## Perché l'ho preso
17       ## Lo sto effettivamente usando
18VERIFICA:  ogni campo compilato, "referenced_in_my_projects" controllato
19           rispetto all'uso reale, non presunto
20FERMATA:   verifica superata, o 2 tentativi, poi segnala per revisione manuale

Questo da solo vale la pena di essere costruito anche senza il Ciclo 2. La prima volta che ne leggi 30 di fila, la metà ti sorprenderà, perché ti eri dimenticato di usare lo strumento, o perché non lo hai mai fatto.

Una nota di strumento generata, accanto alla cartella del clone effettivo che descrive. Questo è il contesto che altrimenti non scriveresti mai.

Che aspetto hanno 30 repository trovati una volta che il Ciclo 1 è stato eseguito?

Un elenco che Claude rigenera ogni volta che cloni qualcosa di nuovo, preso direttamente dalle note:

• github.com/author/scrape-lite - in uso, ultimo commit upstream 2 giorni fa, referenziato in: progetto feed-reader
• github.com/author/tg-bot-kit - in uso, ultimo commit upstream 5 giorni fa, referenziato in: due dei miei bot
• github.com/author/quick-scheduler - accantonato, ultimo commit upstream 41 giorni fa, referenziato in: nessuno
• github.com/author/api-wrapper-x - in uso, ultimo commit upstream 1 giorno fa, referenziato in: un progetto
• github.com/author/rss-to-json - duplicato, ultimo commit upstream 3 giorni fa, referenziato in: nessuno (stesso lavoro di scrape-lite)
• github.com/author/cheap-queue - in uso, ultimo commit upstream 6 ore fa, referenziato in: due progetti
• github.com/author/webhook-relay-lib - accantonato, ultimo commit upstream 96 giorni fa, referenziato in: nessuno
• github.com/author/simple-cache - in uso, ultimo commit upstream 2 giorni fa, referenziato in: tre progetti
• github.com/author/old-scraper - abbandonato upstream, ultimo commit upstream 340 giorni fa, referenziato in: nessuno
• github.com/author/notify-me - incerto, ultimo commit upstream 12 giorni fa, referenziato in: non sicuro
• github.com/author/token-utils - in uso, ultimo commit upstream 1 giorno fa, referenziato in: un progetto
• github.com/author/quick-parser - duplicato, ultimo commit upstream 8 giorni fa, referenziato in: nessuno (stesso lavoro di rss-to-json)
• github.com/author/tiny-orm - accantonato, ultimo commit upstream 55 giorni fa, referenziato in: nessuno
• github.com/author/rate-limiter - in uso, ultimo commit upstream 3 giorni fa, referenziato in: due progetti
• github.com/author/config-loader - in uso, ultimo commit upstream 4 giorni fa, referenziato in: la maggior parte dei miei progetti
• github.com/author/legacy-fetch - abbandonato upstream, ultimo commit upstream 400+ giorni fa, referenziato in: nessuno
• github.com/author/env-check - in uso, ultimo commit upstream 9 giorni fa, referenziato in: un progetto
• github.com/author/pretty-logs - accantonato, ultimo commit upstream 70 giorni fa, referenziato in: nessuno
• github.com/author/proxy-list - incerto, ultimo commit upstream 20 giorni fa, referenziato in: non sicuro
• github.com/author/backoff-lib - in uso, ultimo commit upstream 6 giorni fa, referenziato in: due progetti
• github.com/author/dead-simple-db - accantonato, ultimo commit upstream 88 giorni fa, referenziato in: nessuno
• github.com/author/quick-hash - in uso, ultimo commit upstream 1 giorno fa, referenziato in: un progetto
• github.com/author/retry-wrapper - duplicato, ultimo commit upstream 14 giorni fa, referenziato in: nessuno (stesso lavoro di backoff-lib)
• github.com/author/format-time - in uso, ultimo commit upstream 2 giorni fa, referenziato in: la maggior parte dei miei progetti
• github.com/author/quick-mailer - accantonato, ultimo commit upstream 50 giorni fa, referenziato in: nessuno
• github.com/author/health-check-lib - in uso, ultimo commit upstream 5 giorni fa, referenziato in: due progetti
• github.com/author/dotenv-plus - in uso, ultimo commit upstream 3 giorni fa, referenziato in: la maggior parte dei miei progetti
• github.com/author/simple-lock - incerto, ultimo commit upstream 30 giorni fa, referenziato in: non sicuro
• github.com/author/old-notify - abbandonato upstream, ultimo commit upstream 500+ giorni fa, referenziato in: nessuno
• github.com/author/tiny-scheduler - duplicato, ultimo commit upstream 18 giorni fa, referenziato in: nessuno (stesso lavoro di quick-scheduler)

(i nomi sopra sono segnaposto, illustrano la forma dell'elenco, non gli strumenti reali)

Trenta righe non sono nulla da leggere manualmente. È anche abbastanza per notare che hai tre librerie di logica di retry separate che fanno lo stesso lavoro, e che uno dei repository da cui dipendi effettivamente non ha un commit upstream da più di un anno.

La vista grafo del vault una volta che esistono tutte le 30 note: ogni strumento come nodo, i duplicati e i repository con scopo condiviso raggruppati in cluster visibili.

Ciclo 2: le scansioni che funzionano solo dopo aver raccolto 30+ strumenti?

Il README di un singolo strumento non può dirti questo. Solo qualcosa che legge attraverso tutto ciò che hai preso può farlo.

1TRIGGER:   ogni 12 ore
2PASSI:
3  Passaggio 1, effettivamente accantonato:
4    segnala qualsiasi repository con stato: in uso ma non referenziato in nessuno
5    dei tuoi progetti per 30+ giorni, ricontrolla nei tuoi repository
6    per l'uso reale, non per supposizioni
7  Passaggio 2, strumenti duplicati:
8    confronta "cosa fa effettivamente" in tutte le note, raggruppa qualsiasi cosa
9    risolva lo stesso problema, confermato da nomi di funzione corrispondenti
10    o scopo corrispondente, non solo descrizioni dal suono simile
11  Passaggio 3, rischio upstream:
12    segnala qualsiasi strumento da cui dipendi il cui ultimo commit upstream
13    risale a 120+ giorni fa, così sai quali dipendenze potrebbero diventare
14    obsolete senza preavviso
15  Passaggio 4, la lettura onesta:
16    una riga per strumento sul fatto che meriti lo spazio su disco e il
17    sovraccarico mentale di ricordare che esiste, senza attenuanti
18VERIFICA:    ogni passaggio scrive in memory/PORTFOLIO.md, i raggruppamenti del
19             Passaggio 2 supportati da una funzione o scopo condiviso effettivo
20FERMATA:     tutti e quattro i passaggi completati, o un passaggio fallisce e viene
21             registrato, mai saltato silenziosamente

Il Passaggio 3 è quello che cambia davvero il tuo modo di lavorare. Non ti rendi conto di dipendere da tre strumenti i cui manutentori sono spariti un anno fa, finché non è in un elenco davanti a te.

Una tabella dei rischi generata dal Passaggio 3: strumenti che stai effettivamente usando, ordinati da quanto tempo è passato dall'ultima modifica del loro progetto upstream.

Prova prima la versione manuale?

Stessa regola di sempre. Non programmare nulla che non hai prima provato manualmente.

1Lavorerai in un ciclo finché il compito non soddisfa lo standard.
2
3COMPITO:
4Leggi ogni cartella del repository in [percorso]. Per ognuna, annota cosa fa,
5perché l'avevi presa originariamente, se lo stai ancora effettivamente usando,
6e quanto tempo è passato dall'ultimo commit del progetto upstream. Poi
7confronta tutti i repository: trova duplicati e qualsiasi cosa da cui dipendi
8che è diventata silenziosa upstream.
9
10CRITERI DI SUCCESSO (rigorosi, nessun passaggio facile):
11- ogni "duplicato" è supportato da una funzione o scopo effettivamente
12  corrispondente, non da descrizioni dal suono simile
13- ogni repository "accantonato" include i giorni da quando lo hai referenziato
14  l'ultima volta in qualsiasi parte dei tuoi progetti
15- il rischio upstream si basa su date di commit reali, non su supposizioni
16
17PROTOCOLLO DEL CICLO, ripeti ad ogni turno:
181. PIANIFICA  - indica il singolo passo successivo
192. ESIGUI     - produci o migliora l'output
203. VERIFICA   - assegna un punteggio 1-10 per ogni criterio, sii brutalmente onesto
214. DECIDI     - se ogni criterio è 8+, scrivi "FINAL" e fermati
22
23REGOLE:
24- Non dichiararlo mai finito finché ogni criterio non è 8+
25- Non farmi domande, fai un'ipotesi sensata e continua
26
27Inizia. Esegui il ciclo fino a FINAL.

Se l'elenco dei duplicati o l'elenco dei rischi upstream ti sorprende, merita una programmazione. Se conferma solo ciò che già sapevi, non automatizzarlo ancora.

L'ordine che funziona davvero?

Fai funzionare il Ciclo 1 finché ogni repository clonato non ha una nota reale, non un segnaposto.

Lascialo riposare per una o due settimane. Ogni nuovo strumento che prendi avrà automaticamente una nota da quel momento in poi.

Solo allora attiva il Ciclo 2. Le scansioni di duplicati e rischio upstream necessitano di abbastanza note per scontrarsi effettivamente.

Programmalo per ultimo, dopo averlo visto funzionare pulito manualmente almeno due volte.

Quanto costa?

Il Ciclo 1 viene eseguito per ogni nuovo clone, quindi scala con quanto prendi effettivamente, non con una pianificazione fissa. La maggior parte delle settimane sono una manciata di chiamate al modello economico.

Il Ciclo 2 viene eseguito due volte al giorno su oltre 30 note. Sposta il Passaggio 1 e il Passaggio 3 sul modello economico; sono ricerche, non valutazioni. Tieni il Passaggio 2 e il Passaggio 4 su Sonnet, poiché individuare un vero duplicato e dare una lettura onesta richiedono entrambi un modello che possa effettivamente ragionare su ciò che sta confrontando. Diviso in questo modo, due esecuzioni al giorno su una collezione di 30 repository costa meno del tempo che impiegheresti a fare lo stesso audit manualmente una volta.

L'unica cosa da ricordare?

Un README ti dice cosa fa uno strumento. Questo ti dice quali dei 30 strumenti che hai trovato stai effettivamente usando, quali si stanno silenziosamente duplicando a vicenda e quali stai usando e nessuno mantiene più.

Il valore non è mai stato in una singola nota di strumento. È nel fatto che nulla di ciò che hai raccolto può marcire silenziosamente, duplicarsi silenziosamente o diventare silenziosamente non mantenuto senza che qualcosa lo scriva dove lo vedrai effettivamente.

Costruisci prima il Ciclo 1. Lascialo funzionare per due o tre settimane prima di toccare il Ciclo 2. Le scansioni di duplicati e rischio upstream sono inutili con cinque repository. Iniziano a ripagarsi da soli dopo la ventina.

Se vuoi altre analisi come questa, ne pubblico una ogni due giorni su Telegram e X. Entrambi gratuiti.

X - https://x.com/gippp69

Telegram - https://t.me/GipArcAI