Aggiornamenti automatici docs
Scopri come la skill /update-jamdesk di Claude Code trasforma le modifiche al codice visibili agli utenti in aggiornamenti coerenti della documentazione Jamdesk.
La skill /update-jamdesk per Claude Code analizza le modifiche al codice e genera gli aggiornamenti corrispondenti alla documentazione. Eseguila dopo aver rilasciato una funzionalità visibile agli utenti. Individua le pagine della documentazione da creare o modificare.
Cerchi consigli generali sulla scrittura con l'AI? Consulta Claude Code per la configurazione dello strumento. Consulta Scrivere con AI per indicazioni più ampie sulla scrittura della documentazione con strumenti AI.
Quando usarla
Usala quando: hai apportato modifiche visibili agli utenti a API, comandi CLI, interfaccia, opzioni di configurazione o comportamento dei componenti.
Evitala quando: si tratta di refactoring interni, modifiche solo ai test, configurazione di build/CI o interventi sulle prestazioni senza cambiamenti di comportamento.
Prerequisiti
- Claude Code installato e configurato
- Un progetto di documentazione Jamdesk con
docs.json - Opzionale: CLI Jamdesk per la verifica (
npm install -g jamdesk)
Avvio rapido
Crea un file .jamdesk-docs-path nel tuo repository di codice che punti alla documentazione:
docs_path: ../my-docsIl percorso può essere relativo (rispetto al file di configurazione) o assoluto.
Eseguila dopo aver implementato una funzionalità:
/update-jamdeskClaude analizza le modifiche e pone domande di chiarimento prima di scrivere la documentazione.
Controlla la documentazione generata. Claude la verifica con jamdesk validate e jamdesk broken-links prima del commit.
Formato del file di configurazione
Il file .jamdesk-docs-path indica a Claude dove si trova la tua documentazione.
Formato semplice con solo il percorso:
../my-docs
Formato completo con opzioni:
# Path to documentation repository
docs_path: ../my-docs
# Optional: Branch for doc updates (default: main)
docs_branch: mainLa skill cerca il file di configurazione risalendo dalla directory corrente fino alla radice di git. Collocalo nella radice del repository.
Come funziona
Claude esegue questi passaggi per /update-jamdesk:
- Individua la documentazione: trova il file di configurazione
.jamdesk-docs-path - Pone domande: chiarisce la strategia di branch, l'ambito e il contenuto
- Analizza la documentazione esistente: cerca contenuti correlati da aggiornare o estendere
- Scrive la documentazione: crea o aggiorna le pagine secondo gli standard Jamdesk, con esempi semplici prima di tutto
- Verifica il tono: controlla l'output per individuare riempitivi tipici dell'AI. Claude scrive meglio con un CLAUDE.md che definisca il tono (vedi Claude Code)
- Verifica: esegue
jamdesk validateejamdesk broken-links - Committa: prepara le modifiche e propone di committare/pushare/aprire una PR
Esegui git checkout . prima del commit per annullare tutte le modifiche.
| Scenario | Azione |
|---|---|
| Nuova funzionalità | Crea una nuova pagina |
| Modifica di comportamento | Aggiorna una pagina esistente |
| Piccola aggiunta | Aggiungi una sezione a una pagina esistente |
| Capacità rilevante | Nuova pagina autonoma |
| Deprecazione/rimozione | Aggiorna la pagina esistente + aggiungi note di 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 --preview
La modalità anteprima permette di:
- Verificare quale documentazione necessita di aggiornamenti
- Rivedere le modifiche proposte prima del commit
- Vedere l'analisi della skill senza effetti collaterali
Suggerimenti proattivi
Claude può suggerirlo dopo che hai committato modifiche al codice visibili agli utenti:
Tip: These changes affect user-facing features.
Run /update-jamdesk to update your documentation.
Appare quando:
- Hai un file di configurazione
.jamdesk-docs-path, E - Il tuo commit include file che corrispondono a pattern visibili agli utenti (API, CLI, componenti)
Installazione della skill
Installa la skill /update-jamdesk con la CLI skills:
npx skills add jamdesk/skills --skill update-jamdesk
Questo installa la skill in .claude/skills/update-jamdesk/ nel tuo progetto.
Installa 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 --list
Aggiornamento
Riesegui il comando di installazione per ottenere l'ultima versione:
npx skills add jamdesk/skills --skill update-jamdesk
Riavvia Claude Code o avvia una nuova sessione dopo l'installazione o l'aggiornamento.
Risoluzione dei problemi
Verifica che il file della skill si trovi in .claude/skills/update-jamdesk/SKILL.md. Poi riavvia la sessione di Claude Code.
Crea .jamdesk-docs-path nella radice del repository con il percorso della directory della documentazione. La skill cerca dalla directory corrente fino alla radice di git.
Installa con npm install -g jamdesk. La skill funziona anche senza di essa, ma salta la validazione automatica.
