Table of Contents

Torna al corso sul flusso di lavoro pratico con IA

Crea un nuovo formato di output e dimostrane il comportamento. In precedenza hai aggiunto un filtro di stato. Questo capstone parte da un laboratorio nuovo e aggiunge un rapporto JSON leggibile da un altro programma. Il nuovo requisito verifica se sai trasferire il tuo flusso di lavoro a una funzione diversa.

Obiettivo didattico: consegnerai un rapporto JSON verificato, un registro delle prove relative a fonti e strumenti e un passaggio che una nuova sessione possa comprendere.

Punti chiave

  • Un requisito separato definisce la funzione del capstone.
  • La modifica di un agente di programmazione resta nei file indicati.
  • Verifiche indipendenti determinano l’accettazione.
  • Un passaggio a una nuova sessione permette di ricostruire il risultato.

Prima di iniziare

Prerequisiti: completa le lezioni da 0 a 10, inclusi il contesto del repository, il primo compito di programmazione, MCP o l’alternativa nel browser, la delega e i cicli delimitati. La lezione 11 è facoltativa. Dedica da 90 a 120 minuti. Difficoltà intermedia.

Usa una nuova estrazione del laboratorio iniziale . Esegui python3 task_report.py tasks.json e i due test di base prima di ogni modifica. Su Windows, usa py -3 se la configurazione usa il launcher Python. Crea una base Git locale come nella configurazione del corso. Il filtro di stato della lezione 5 è assente per scelta.

Leggi docs/capstone-requirements.md, revisione 1. Richiede --format text|json. L’output testuale predefinito resta Total tasks: 4. L’output JSON contiene un totale numerico e i conteggi per ogni stato presente nei dati. Verifica una lista vuota, uno stato mancante e un formato non supportato. Non usare docs/requirements.md come riferimento per questa nuova funzione.

Scegli il percorso. Il percorso connesso usa una modifica osservata di un agente di programmazione, una vera chiamata MCP in sola lettura e un worker nativo o una sessione worker separata. Il percorso di studio usa un assistente chat per proporre codice, una fonte browser al posto di MCP e chat separate come worker simulati. Indica come «non eseguiti» i passaggi degli strumenti non disponibili. Entrambi i percorsi richiedono test locali e revisione dei file. La soluzione qui sotto contiene file completi come percorso di ripristino. Salva il primo tentativo negli appunti prima di copiare la soluzione in una nuova estrazione.

Verifica 1: Descrizione del progetto

Apri il progetto sintetico del workshop ChatGPT o Claude. Chiedi una bozza di promemoria di due frasi. Verifica le 19:00 in approved-schedule.md. Il programma del promemoria segue l’orario approvato. Il programma segue i requisiti del capstone.

Prova: registra il nome del progetto, la revisione della fonte, l’ora osservata nella bozza e ogni correzione. Non inviare il messaggio.

Verifica 2: Contesto dell’archivio

Apri il laboratorio nuovo. Crea un breve AGENTS.md che rimandi a docs/capstone-requirements.md, task_report.py, ai test e al comando di test verificato durante la configurazione. Se usi Claude Code, importa il file condiviso da CLAUDE.md. Crea un commit umano di configurazione per questi file guida e poi conferma che git status --short non mostri modifiche. L’agente di programmazione non deve fare commit della modifica alla funzione.

Prova: salva la mappa e una copia pulita delle istruzioni. Indica le chiavi JSON e il comportamento per gli input non validi della revisione 1. Se una chat precedente descrive il filtro di stato, trattala come contesto di un’attività diversa.

Verifica 3: Risorsa esterna

Percorso connesso: usa il server OpenAI Docs MCP in sola lettura tramite un client supportato. Chiedi a uno strumento MCP le indicazioni correnti per AGENTS.md. Registra il nome dello strumento, l’URL della fonte e un punto utile per il laboratorio. Rimuovi poi la connessione di esercizio.

Percorso di studio: apri in un browser la documentazione ufficiale di AGENTS.md . Registra titolo, URL e un punto utile. Indica «non eseguite» per la ricerca e l’esecuzione MCP.

Prova: una voce server configurata non dimostra che sia stata eseguita. Il percorso connesso richiede una chiamata allo strumento visibile e contenuto restituito dalla fonte.

Verifica 4: Affida una revisione

Chiedi a un worker in sola lettura di esaminare docs/capstone-requirements.md, task_report.py e i test di base. Richiedi un rapporto di massimo cinque righe che indichi controlli mancanti e percorsi dei file. Nel percorso di studio, usa una chat separata e contrassegnala come worker simulato.

Risultato atteso: i test iniziali coprono il totale e un valore JSON che non è una lista. Non coprono l’output JSON, una lista vuota, uno stato mancante o un formato non valido. Apri il file dei test e verifica il rapporto. Una breve revisione indipendente è utile perché i criteri di accettazione differiscono da quelli della lezione 5.

Prova: salva il breve rapporto e la decisione di integrazione in una frase. Conserva la trascrizione del worker fuori dal registro principale dell’attività.

Verifica 5: Richiedi il cambiamento

Fornisci a un agente di programmazione il pacchetto seguente. Nel percorso di studio, un assistente chat propone la patch e tu la applichi manualmente nel laboratorio.

Obiettivo: aggiungere --format text|json dopo il percorso JSON.
Fonte: docs/capstone-requirements.md, revisione 1.
File modificabili: task_report.py e tests/test_task_report.py.
Mantenere: Total tasks: 4 come output predefinito e tasks.json invariato.
JSON: un oggetto con total e conteggi by_status, senza altro testo su stdout.
Controlli richiesti: testo predefinito ed esplicito, JSON 4/2/2, lista vuota,
stato mancante, formato non valido e test di base.
Fermarsi se: conflitto tra fonti, test di base non correlato fallisce o modifica fuori ambito.
Rapporto: file modificati, comandi, output osservati, problema irrisolto.
Non fare commit, push, pubblicare o inviare messaggi.

Esamina il piano prima delle modifiche. La scelta dello schema è importante: total è un numero, non la stringa "4". by_status include ogni stato presente nell’input, così il rapporto comprende anche uno stato aggiunto in futuro. Mantieni la modifica nel laboratorio estratto.

Verifica 6: Prova e revisione

Esegui tu questi controlli. Su Windows, sostituisci python3 con py -3. L’ordine delle chiavi e gli spazi dell’output JSON non contano. Analizza l’output come JSON e confronta i valori tipizzati.

git status --short
git diff -- task_report.py tests/test_task_report.py
python3 -m unittest discover -s tests -v
python3 task_report.py tasks.json
python3 task_report.py tasks.json --format text
python3 task_report.py tasks.json --format json
python3 task_report.py tasks.json --format invalid

Comportamento atteso: i test passano. Entrambi i comandi testuali stampano Total tasks: 4. Il comando JSON restituisce un solo oggetto con total 4, by_status.open 2 e by_status.done 2. Un formato non valido termina con un codice diverso da zero. I test coprono anche una lista vuota e un’attività priva di status testuale. Leggi l’output di errore osservato e il codice di uscita per questi casi.

CheckpointProva di esito positivoRecupero in caso di errore
Descrizione del progettoIl promemoria riporta le 19:00Aggiorna la fonte dell’orario
Mappa del repositoryRequisito del capstone e percorsi dei test indicatiCorreggi i file guida
Risorsa esternaFonte MCP letta o alternativa browser segnalataVerifica connessione o URL
Revisione del workerControlli mancanti verificati nel fileCorreggi il rapporto del worker
Ambito dei fileSolo programma e testEsamina ogni modifica indesiderata
ComportamentoTesto, JSON, input vuoti ed errori verificatiDiagnostica una causa e riprova
PassaggioUna nuova sessione ricostruisce lo statoAggiungi la fonte o il risultato mancante

Usa una nuova estrazione per un ripristino sicuro. Salva gli appunti fuori dal laboratorio, elimina solo la copia estratta usa e getta ed estrai di nuovo lo ZIP originale. Non usare un ripristino Git generale in un repository con lavoro da conservare.

Verifica 7: Consegna a una nuova sessione

Scrivi un passaggio di meno di 180 parole fuori dalla cartella del laboratorio. Includi revisione del requisito, file modificati, comando e risultato esatti del test, output testuale e JSON, controlli degli input non validi, registro d’uso e prossima azione. Apri una nuova sessione e chiedile di identificare le chiavi JSON e dire se la funzione ha superato i controlli.

Risposta attesa: la nuova sessione nomina total e by_status, indica la revisione 1, riporta solo verifiche osservate e segnala eventuali controlli mancanti.

Soluzione e griglia di valutazione

Una implementazione valida è riportata sotto. Salva il primo blocco come task_report.py e il secondo come tests/test_task_report.py in una nuova estrazione del laboratorio. Lascia invariati tasks.json e i due file dei requisiti. Esegui i controlli del checkpoint 6. Confronta un’altra soluzione con il requisito e il comportamento osservato.

task_report.py:

"""Stampa un conteggio testuale o un riepilogo JSON delle attività del workshop."""

import argparse
import json
import sys
from collections import Counter
from pathlib import Path


def load_tasks(path: Path) -> list:
    tasks = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(tasks, list):
        raise ValueError("task data must be a list")
    for index, task in enumerate(tasks, start=1):
        if not isinstance(task, dict) or not isinstance(task.get("status"), str):
            raise ValueError(f"task {index} needs a string status")
    return tasks


def count_tasks(path: Path) -> int:
    return len(load_tasks(path))


def summarize_tasks(path: Path) -> dict:
    tasks = load_tasks(path)
    counts = Counter()
    for task in tasks:
        counts[task["status"]] += 1
    return {"total": len(tasks), "by_status": dict(sorted(counts.items()))}


def main() -> int:
    parser = argparse.ArgumentParser(description="Rapporto delle attività del workshop")
    parser.add_argument("path", type=Path, help="percorso all’elenco JSON delle attività")
    parser.add_argument("--format", choices=("text", "json"), default="text")
    args = parser.parse_args()
    try:
        if args.format == "json":
            print(json.dumps(summarize_tasks(args.path)))
        else:
            print(f"Total tasks: {count_tasks(args.path)}")
    except (OSError, ValueError) as exc:
        print(f"Error: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

tests/test_task_report.py:

"""Controlli per i rapporti testuali e JSON delle attività del workshop."""

import json
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
from sys import path as module_path

ROOT = Path(__file__).resolve().parents[1]
module_path.insert(0, str(ROOT))
from task_report import count_tasks  # noqa: E402


def run_report(path: Path, *options: str) -> subprocess.CompletedProcess:
    return subprocess.run(
        [sys.executable, str(ROOT / "task_report.py"), str(path), *options],
        capture_output=True, text=True, check=False,
    )


class TaskReportTests(unittest.TestCase):
    def test_counts_four_sample_tasks(self):
        self.assertEqual(count_tasks(ROOT / "tasks.json"), 4)

    def test_rejects_non_list_data(self):
        with tempfile.TemporaryDirectory() as directory:
            sample = Path(directory) / "invalid.json"
            sample.write_text(json.dumps({"tasks": []}), encoding="utf-8")
            with self.assertRaises(ValueError):
                count_tasks(sample)

    def test_default_and_explicit_text(self):
        for options in ((), ("--format", "text")):
            result = run_report(ROOT / "tasks.json", *options)
            self.assertEqual(result.returncode, 0)
            self.assertEqual(result.stdout.strip(), "Total tasks: 4")

    def test_json_counts_and_types(self):
        result = run_report(ROOT / "tasks.json", "--format", "json")
        self.assertEqual(result.returncode, 0)
        self.assertEqual(json.loads(result.stdout), {
            "total": 4, "by_status": {"open": 2, "done": 2},
        })

    def test_empty_list(self):
        with tempfile.TemporaryDirectory() as directory:
            sample = Path(directory) / "empty.json"
            sample.write_text("[]", encoding="utf-8")
            result = run_report(sample, "--format", "json")
            self.assertEqual(result.returncode, 0)
            self.assertEqual(json.loads(result.stdout), {
                "total": 0, "by_status": {},
            })

    def test_missing_status(self):
        with tempfile.TemporaryDirectory() as directory:
            sample = Path(directory) / "missing.json"
            sample.write_text('[{"id": 1}]', encoding="utf-8")
            for options in ((), ("--format", "json")):
                result = run_report(sample, *options)
                self.assertNotEqual(result.returncode, 0)
                self.assertIn("status", result.stderr)

    def test_invalid_format(self):
        result = run_report(ROOT / "tasks.json", "--format", "invalid")
        self.assertNotEqual(result.returncode, 0)
        self.assertIn("invalid", result.stderr)


if __name__ == "__main__":
    unittest.main()

Ripristina dopo la soluzione: salva gli appunti fuori dal laboratorio, elimina questa copia estratta ed estrai di nuovo il laboratorio iniziale originale. La nuova copia contiene i due test di base e nessuna implementazione della funzione.

Assegna un punto per ogni checkpoint della tabella sopra. Sette punti completano il percorso connesso se la voce della fonte esterna include una chiamata MCP reale e la riga del worker documenta una sessione reale. Sette punti completano il percorso di studio se la fonte è una pagina browser verificata e i passaggi degli strumenti sono indicati esplicitamente come non eseguiti. L’assenza di un controllo su comportamento, fonte o ambito dei file blocca entrambi i percorsi.

Verifica la comprensione

  1. Quale requisito controlla questa funzione? docs/capstone-requirements.md, revisione 1. Il requisito precedente sul filtro di stato appartiene alla lezione 5.
  2. Cosa prova il contratto JSON? Analizza l’output del comando, confronta valori numerici e conteggi di ogni stato, e verifica input vuoti e non validi. Un riepilogo ben scritto dell’agente non basta.

Risoluzione dei problemi

  • I test di base falliscono prima della modifica: ripristina il laboratorio dallo ZIP e ripeti la configurazione.
  • L’agente modifica un altro file: esamina il diff e ripristina solo la modifica indesiderata del laboratorio.
  • La connessione MCP non riesce: usa la fonte browser e indica il checkpoint come percorso di studio.
  • Il worker ripete un valore errato: rileggi il requisito del capstone e correggi il rapporto.
  • Il budget dei tentativi termina: conserva il registro dell’errore e chiedi a un revisore umano il passo successivo.

Passi successivi

Salva il registro delle prove completato. Per la pubblicazione avanzata in team e l’autorità tra sistemi, prosegui con il Corso sull’implementazione della collaborazione IA .

Navigazione del corso: Precedente obbligatoria: cicli delimitati , Facoltativa: valutazione degli agenti specializzati , Indice del corso .