Ambiente, accesso e primo programma
Gli strumenti cambiano interfaccia, ma condividono lo stesso fondamento: una cartella di lavoro, file reali, un processo e credenziali da proteggere. Imparerai a leggere questo sistema prima di chiedere modifiche.
Cosa affronti, passo dopo passo
Quattro superfici, responsabilità diverse
CLI, editor, web e API non sono quattro versioni della stessa schermata. Espongono capacità e responsabilità diverse. La scelta giusta dipende da dove si trova lo stato reale e da quale prova ti serve alla fine.
La CLI lavora vicino ai file e rende visibili comandi e output. L’estensione dell’editor aggiunge contesto sulla selezione e sul progetto. Il web è adatto a ragionamenti e sessioni non legate a una singola shell. L’API abilita integrazioni programmatiche e richiede gestione esplicita di chiavi e costi.
Non esiste un’interfaccia sempre migliore. Scegli quella che espone le evidenze necessarie: per correggere un repository locale servono file e test; per discutere un’architettura può bastare un contesto documentale.
Devi capire le modifiche di Task Notes, discutere il messaggio, rivedere un file e poi generare bozze in modo ripetibile.
- Parti dalla CLI per leggere la cronologia Git e produrre l’elenco verificabile dei commit inclusi. Se ti basta una bozza locale, puoi restare qui.
- Se vuoi confrontare due strutture narrative, puoi usare il web fornendo l’elenco come contesto; non fingere però che la chat veda il repository.
- Se devi rifinire `RELEASE_NOTES.md` accanto ai file modificati, l’editor rende più semplice controllare riferimenti e nomi. Non sei obbligato a usare anche il web.
- Introduci l’API solo quando la procedura è davvero ricorrente e merita uno script. Per questa prima bozza non serve ancora: non aggiungere automazione prima di avere un lavoro ripetibile.
Risultato: Puoi risolvere il compito con una sola superficie oppure combinarne alcune. La scelta dipende dalla prova che ti serve, non dall’idea che il percorso debba attraversarle tutte.
Leggere il terminale senza paura
Nel terminale non devi indovinare una formula segreta. Devi leggere una sequenza: dove sei, quale comando hai eseguito, quale output hai ricevuto e con quale stato il processo è terminato.
Il prompt indica che la shell attende un comando. Il comando viene eseguito nella cartella corrente, produce output e termina con uno stato di successo o errore. Questi tre elementi spiegano la maggior parte dei primi problemi.
Prima di installare di nuovo tutto, controlla dove ti trovi, quali file vedi e quale versione viene trovata. Una diagnosi ordinata cambia una variabile alla volta e ripete il controllo che prima falliva.
- Controlla la cartella corrente.
- Elenca i file.
- Verifica il comando e la versione.
- Esegui il caso minimo.
- Leggi il primo errore utile.
Nella cartella Task Notes esegui `python app.py`, ma la shell risponde `command not found: python`.
- Non tocchi `app.py`: l’errore indica che la shell non ha trovato il programma chiamato `python`, quindi il file non è stato eseguito.
- Controlli `command -v python3` per vedere quale programma verrebbe avviato, poi `python3 --version`; ora conosci sia il percorso sia la versione del runtime.
- Verifichi `pwd` e `ls` per assicurarti che `app.py` sia nella cartella corrente, poi esegui `python3 app.py`.
- Annoti comando e output riuscito come baseline. Se il programma ora fallisce con un traceback, quello è un nuovo livello del problema e va letto separatamente.
Risultato: Hai corretto la causa più esterna senza reinstallare pacchetti o cambiare codice. La baseline distingue l’ambiente funzionante dai problemi dell’applicazione.
Credenziali e variabili d’ambiente
Una chiave API permette a un programma di agire e consumare risorse a tuo nome. Trattala come una password operativa: non deve diventare parte del codice, della cronologia Git o di uno screenshot condiviso.
Una chiave API è un segreto, non una preferenza. Non va inserita nel codice, nei prompt condivisi o nei commit. La shell può fornirla al processo tramite una variabile d’ambiente; un gestore di segreti è più adatto negli ambienti condivisi.
Un file locale con segreti deve essere escluso dal controllo versione. Prima di mostrare log o screenshot, verifica che non contengano token completi. Se una chiave viene esposta, cancellarla dal file non basta: deve essere revocata e sostituita.
In `client.py` trovi `api_key = "<CHIAVE_DI_TEST>"`. Il repository è locale, ma potrebbe essere condiviso in seguito.
- Interrompi l’uso della chiave e controlli se il file è già stato committato o inviato altrove; questa informazione determina se serve una revoca immediata.
- Modifichi il codice perché legga `os.environ["ANTHROPIC_API_KEY"]` e produca un errore chiaro quando la variabile manca, senza stampare il valore.
- Configuri il segreto nell’ambiente locale o nel gestore previsto e aggiungi soltanto un file di esempio con un valore vuoto.
- Esegui una ricerca nel repository e controlli diff e log pertinenti per assicurarti che nessun token completo resti negli artefatti condivisibili.
Risultato: Il programma riceve ancora la credenziale, ma il segreto non vive più nel sorgente. Se era già esposto, la rotazione chiude anche la credenziale precedente.
Il primo ciclo esecuzione–errore–correzione
Il primo errore non è una bocciatura: è la prima osservazione affidabile sul sistema. Se conservi il comando e cambi una causa per volta, il ciclo errore–correzione diventa leggibile anche senza grande esperienza di programmazione.
Un programma piccolo permette di separare l’ambiente dal problema applicativo. Crealo, eseguilo senza agente, osserva l’output e soltanto dopo chiedi una modifica. Saprai così se l’errore appartiene alla configurazione o al codice.
Quando compare un traceback, leggi dal basso: il tipo di errore e il messaggio indicano il sintomo, le righe sopra ricostruiscono il percorso. Correggi una causa per volta e riesegui lo stesso comando.
Lo script stampa `task["priorita"]`, ma l’attività creata contiene soltanto `titolo` e `completata`. Python termina con `KeyError: 'priorita'`.
- Leggi l’ultima riga del traceback: `KeyError` significa che il dizionario — un record formato da coppie chiave-valore — non possiede la chiave richiesta. Python è partito: non serve reinstallarlo.
- Risali alla prima riga del tuo file indicata nel traceback e confronti la lettura `task["priorita"]` con l’oggetto effettivamente creato.
- Decidi il comportamento atteso: per le attività vecchie la priorità deve essere `normale`; usi quindi `task.get("priorita", "normale")` e aggiungi un caso esplicito.
- Riesegui esattamente lo stesso comando e poi un secondo caso con priorità presente, verificando sia la compatibilità sia il nuovo valore.
Risultato: Il programma non si limita a evitare l’errore: possiede un comportamento definito per dati vecchi e nuovi, sostenuto da due casi osservabili.
Primo script Task Notes
Partiamo da un file autonomo che crea una singola attività.
def crea_attivita(titolo):
return {"titolo": titolo, "completata": False}
print(crea_attivita("Provare il parser"))