Aggiornamenti doc automatici
Sincronizza la documentazione con il codice usando la skill /update-jamdesk per Claude Code e aggiornala quando implementi funzionalità.
La skill /update-jamdesk per Claude Code monitora le modifiche al codice e genera aggiornamenti della documentazione corrispondenti. Dopo aver rilasciato una funzionalità rivolta agli utenti, esegui la skill: individuerà le pagine della documentazione da creare o modificare.
Cerchi consigli generali sulla scrittura con l'AI? Questa pagina illustra la skill /update-jamdesk per gli aggiornamenti automatici della documentazione. Per configurare lo strumento, consulta Claude Code. Per indicazioni più ampie sull'uso degli strumenti di AI per scrivere la documentazione, consulta Scrivere con l'AI.
Quando usarla
Usala quando: hai apportato modifiche rivolte agli utenti ad API, comandi CLI, interfaccia utente, opzioni di configurazione o comportamento dei componenti.
Saltala quando: si tratta di refactoring interni, modifiche solo ai test, configurazione di build/CI o interventi sulle prestazioni senza cambiamenti del comportamento. Queste modifiche non richiedono documentazione rivolta agli utenti.
Prerequisiti
- Claude Code installato e configurato
- Un progetto di documentazione Jamdesk con
docs.json - Facoltativo: Jamdesk CLI per la verifica (
npm install -g jamdesk)
Avvio rapido
Crea un file .jamdesk-docs-path nel repository del codice, indicando il percorso della documentazione:
docs_path: ../my-docsIl percorso può essere relativo (rispetto al file di configurazione) o assoluto.
Dopo aver implementato una funzionalità, esegui:
/update-jamdeskClaude analizzerà le modifiche e porrà domande di chiarimento prima di scrivere la documentazione.
Esamina la documentazione generata, quindi Claude la verificherà con jamdesk validate e jamdesk broken-links prima di eseguire il commit.
Formato del file di configurazione
Il file .jamdesk-docs-path indica a Claude dove si trova la documentazione.
Formato semplice: solo il percorso:
../my-docsFormato completo: con opzioni:
# Path to documentation repository
docs_path: ../my-docs
# Optional: Branch for doc updates (default: main)
docs_branch: mainIl file di configurazione viene individuato risalendo dalla directory corrente fino alla root git. Per ottenere risultati ottimali, inseriscilo nella root del repository.
Come funziona
Quando esegui /update-jamdesk, Claude:
- Individua la documentazione: trova il file di configurazione
.jamdesk-docs-path - Pone domande: chiarisce la strategia per i branch, l'ambito e i contenuti
- Analizza la documentazione esistente: cerca contenuti correlati da aggiornare o ampliare
- Scrive la documentazione: crea o aggiorna le pagine seguendo gli standard Jamdesk, iniziando da esempi semplici
- Esamina lo stile: controlla che l'output non contenga riempitivi tipici dell'AI. Claude scrive meglio con un file CLAUDE.md che definisce lo stile (consulta Claude Code)
- Verifica: esegue
jamdesk validateejamdesk broken-links - Esegue il commit: prepara le modifiche e offre di eseguire commit, push o creare una PR
Non ti piacciono le modifiche? Esegui git checkout . prima del commit per annullare tutte le modifiche.
| Scenario | Azione |
|---|---|
| Nuova funzionalità | Crea una nuova pagina |
| Modifica del comportamento | Aggiorna la pagina esistente |
| Piccola aggiunta | Aggiunge una sezione alla pagina esistente |
| Funzionalità importante | Crea una nuova pagina autonoma |
| Deprecazione/rimozione | Aggiorna la pagina esistente e aggiunge note sulla migrazione |
Esempio di sessione
User: I just added a webhook feature. Can you document it?
Claude: I'm using the update-jamdesk skill to update your documentation.
Found .jamdesk-docs-path: ../customer-docs
How should I handle changes to the docs repository?
1. Create a new feature branch (recommended)
2. Update directly on main
3. Use current branch
User: 1
Claude: Based on the webhook implementation, I plan to:
- Create: webhooks/overview.mdx
- Update: getting-started.mdx (add link)
Any changes to this plan?
User: Looks good
Claude: [Creates documentation...]
✓ jamdesk validate passed
✓ jamdesk broken-links passed
Commit these changes?Modalità anteprima
Esegui con --preview per vedere cosa cambierebbe senza apportare modifiche:
/update-jamdesk --previewLa modalità anteprima consente di:
- controllare quale documentazione deve essere aggiornata
- esaminare le modifiche proposte prima di eseguire il commit
- visualizzare l'analisi della skill senza effetti collaterali
Suggerimenti proattivi
Dopo aver eseguito il commit di modifiche al codice rivolte agli utenti, Claude potrebbe suggerire:
Tip: These changes affect user-facing features.
Run /update-jamdesk to update your documentation.Questo messaggio viene visualizzato quando:
- hai un file di configurazione
.jamdesk-docs-path, e - il commit include file che corrispondono a pattern rivolti agli utenti (API, CLI, componenti)
Installazione della skill
Installa la skill /update-jamdesk usando la CLI skills:
npx skills add jamdesk/skills --skill update-jamdeskLa skill viene installata in .claude/skills/update-jamdesk/ nel progetto.
Installa la skill nella directory del progetto corrente:
npx skills add jamdesk/skills --skill update-jamdeskLa skill è disponibile quando lavori in questo progetto.
Elencare le skill disponibili
Visualizza tutte le skill Jamdesk:
npx skills add jamdesk/skills --listAggiornamento
Esegui nuovamente il comando di installazione per ottenere la versione più recente:
npx skills add jamdesk/skills --skill update-jamdeskDopo l'installazione o l'aggiornamento, riavvia Claude Code o avvia una nuova sessione perché le modifiche abbiano effetto.
Risoluzione dei problemi
Assicurati che il file della skill si trovi in .claude/skills/update-jamdesk/SKILL.md, quindi riavvia la sessione di Claude Code.
Crea .jamdesk-docs-path nella root del repository, indicando il percorso della directory della documentazione. La skill cerca dalla directory corrente fino alla root git.
Installa con npm install -g jamdesk. La skill funzionerà anche senza, ma non eseguirà la validazione automatica.