Mantenere la documentazione sincronizzata con la tua base di codice

Scenario 1: Documentazione iniziale del progetto

Hai ereditato un repository con documentazione minima. I nuovi membri del team faticano a capire la base di codice e devi creare rapidamente una documentazione completa.

Configurare il tuo workspace

1. Apri il repository in IBM Bob IDE.
2. Apri l'interfaccia di chat di Bob: Option + Command + B (macOS) o Ctrl + Alt + B (Windows)

Generare contesto leggibile dall'IA con /init

Il primo passo è dare a Bob conoscenza del tuo progetto. Passa alla modalità Agent ed esegui:

/init

Bob scansiona il tuo repository e genera:

• AGENTS.md nella radice del repository (contesto principale del progetto)
• .bob/rules-code/AGENTS-code.md (contesto specifico della modalità Agent)
• .bob/rules-plan/AGENTS-plan.md (contesto specifico della modalità Plan)
• .bob/rules-ask/AGENTS-ask.md (contesto specifico della modalità Ask)

Questi file contengono:

• Struttura del codice e directory chiave
• Stack tecnologico e dipendenze
• Comandi di build, test e lint
• Pattern di codice e convenzioni

Perché è importante: Questi file AGENTS.md fungono da basi di conoscenza che Bob referenzia in ogni conversazione. Invece di rianalizzare l'intera base di codice ogni volta, Bob ha un contesto persistente sul tuo progetto.

Rivedere il contesto generato

Apri AGENTS.md e rivedi cosa ha scoperto Bob:

cat AGENTS.md

Vedrai un riepilogo strutturato del tuo progetto. Se Bob ha mancato dettagli importanti (regole di business, convenzioni di deployment, pratiche del team), modifica AGENTS.md per aggiungerli. Questo file è pensato per essere personalizzato.

Creare una modalità Docs Architect

Crea ora una modalità personalizzata che genera documentazione orientata agli utenti. Questa modalità userà il contesto AGENTS.md per creare documentazione per gli esseri umani, non per l'IA.

1. Clicca sull'icona settings nel pannello di Bob per aprire le impostazioni.
2. Seleziona la scheda Modes.
3. Clicca sull'icona + per creare una nuova modalità.
4. Compila i seguenti valori:

Per il campo Mode-specific Custom Instructions, copia e incolla quanto segue:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

Clicca su Salva.

Bob crea un file custom_modes.yaml in .bob che contiene la configurazione della modalità Docs Architect. Puoi modificare questo file direttamente per apportare modifiche future.

Generare la documentazione iniziale

Passa alla modalità Docs Architect e scrivi:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob genera file di documentazione. Rivedili per verificarne l'accuratezza, apporta modifiche, poi fai commit:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

Risultato: Sei passato da documentazione minima a docs completa in minuti, non ore.

Scenario 2: Documentare una nuova funzionalità

Hai appena implementato una nuova funzionalità. Il codice funziona, ma il tuo README, la guida per i contributori e i docs API descrivono ancora il vecchio stato del progetto. Questo è il punto più comune in cui la documentazione rimane indietro — la funzionalità è terminata, ma i docs non sono stati aggiornati.

Ecco come colmare questo divario usando Bob.

Scrivere la funzionalità con l'aiuto di Bob

Durante lo sviluppo, passa alla modalità Agent in modo che Bob possa aiutare con l'implementazione. Poiché Bob ha già il contesto del progetto dal /init eseguito nello Scenario 1, capisce la struttura del codice, le dipendenze e le convenzioni — rendendo i suoi suggerimenti più rilevanti che partire da zero.

Scrivi la funzionalità come faresti normalmente, usando Bob per il completamento del codice, il refactoring o per fare domande sulla base di codice esistente.

Rieseguire /init per aggiornare il contesto IA

Una volta implementata la funzionalità, il contesto di Bob è obsoleto — è stato generato prima che esistesse il tuo nuovo codice. Aggiornalo:

/init

Bob rianalizza il repository e aggiorna AGENTS.md per riflettere cosa è cambiato — nuovi moduli, dipendenze aggiornate e tutti i nuovi pattern di codice che rileva.

Conferma che l'aggiornamento ha catturato le tue modifiche:

git diff AGENTS.md .bob/

Se il diff mostra la tua nuova funzionalità, Bob è pronto a generare documentazione accurata. Se manca qualcosa di importante, modifica AGENTS.md manualmente prima di continuare.

Generare la documentazione per la nuova funzionalità

Ora passa alla modalità Docs Architect. Poiché hai appena aggiornato AGENTS.md, Bob ha un'immagine precisa della nuova funzionalità e può generare documentazione che riflette l'implementazione reale — non un'ipotesi.

Chiedi a Bob cosa deve essere aggiornato:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

Rivedi la documentazione generata per verificarne l'accuratezza — controlla che gli esempi di codice corrispondano alla tua implementazione — poi fai commit di tutto insieme:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

Risultato: La tua funzionalità e la sua documentazione vengono sviluppate insieme e committate nella stessa pull request.

Scenario 3: Revisione del codice con controlli di documentazione

Un membro del team invia una pull request che aggiunge un nuovo endpoint API. Devi assicurarti che la documentazione sia aggiornata.

Rivedere le modifiche al codice

git diff main feature-branch

Vedi nuovi endpoint API ma nessun aggiornamento della documentazione.

Verificare se /init è stato eseguito

git diff main feature-branch -- AGENTS.md .bob/

Se non ci sono modifiche a AGENTS.md, lo sviluppatore non ha eseguito /init. Chiedigli di:

1. Eseguire /init per aggiornare il contesto IA
2. Usare Docs Architect per aggiornare i docs orientati agli utenti

Generare la documentazione mancante

Se stai rivedendo la PR, puoi generare la documentazione tu stesso:

git checkout feature-branch

In Bob, esegui /init, poi passa alla modalità Docs Architect:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

Fai commit degli aggiornamenti della documentazione:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

Risultato: La documentazione fa parte del tuo processo di revisione del codice, non un pensiero secondario.

Scenario 4: Onboarding di un nuovo membro del team

Un nuovo sviluppatore si unisce al tuo team. Ha bisogno di capire rapidamente la base di codice.

Fargli eseguire /init

Il nuovo sviluppatore clona il repository ed esegue:

/init

Bob genera nuovi file AGENTS.md che riflettono lo stato attuale della base di codice. Il nuovo sviluppatore può ora:

1. Leggere AGENTS.md per capire la struttura del progetto
2. Leggere README.md per le istruzioni di avvio
3. Leggere CONTRIBUTING.md per il workflow di sviluppo

Usare la modalità Ask per l'esplorazione

Il nuovo sviluppatore può usare la modalità Ask di Bob per esplorare la base di codice:

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

Bob risponde usando il contesto di AGENTS.md e il codice sorgente reale.

Generare docs di onboarding personalizzati

Se il tuo progetto manca di documentazione di onboarding, usa Docs Architect:

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

Risultato: I nuovi membri del team possono mettersi al passo in ore invece che in giorni.

Scenario 5: Mantenere la documentazione nel tempo

Il tuo progetto è in sviluppo da mesi. Il codice è cambiato significativamente e la documentazione sta iniziando a divergere.

Rilevare la divergenza della documentazione

Esegui /init per vedere cosa è cambiato:

/init

Rivedi il diff:

git diff AGENTS.md .bob/

Le grandi modifiche indicano un'evoluzione significativa del codice. Questo è il segnale che la documentazione orientata agli utenti necessita di aggiornamenti.

Aggiornare la documentazione sistematicamente

Usa Docs Architect per aggiornare la documentazione:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

Stabilire un programma di manutenzione

Aggiungi gli aggiornamenti della documentazione al tuo workflow regolare:

• Mensile: Eseguire /init e rivedere le modifiche
• Prima dei rilasci: Aggiornare tutta la documentazione
• Dopo refactoring importanti: Rigenerare la documentazione interessata
• Nelle revisioni del codice: Verificare se /init è stato eseguito e se i docs sono stati aggiornati

Automatizzare il rilevamento della divergenza (avanzato)

Per i team che vogliono applicare l'igiene della documentazione in CI, aggiungi un controllo di pull request che verifichi che AGENTS.md e .bob/ siano aggiornati. Il controllo eseguirebbe /init sulla branch, poi fallirebbe se l'output differisce da quello che è stato committato — segnalando che lo sviluppatore ha dimenticato di aggiornare il contesto IA prima di aprire la PR. Abbina questo alla checklist del template PR dalla sezione delle best practice per rendere gli aggiornamenti della documentazione una parte obbligatoria del tuo processo di revisione.

Risultato: La documentazione rimane sincronizzata con il codice attraverso la manutenzione regolare.