InstructionsPer prima cosa, dobbiamo dire a Copilot che la documentazione non è opzionale e dove si trova. Crea (o aggiorna) il file .github/copilot-instructions.md nella root:
# Documentation Rules
- Every time a public API, environment variable, or architectural component is modified, the documentation must be updated.
- ROOT/README.md: Technical overview and setup instructions.
- ROOT/doc/: Architectural decisions and deep dives.
- ROOT/doc/manual/: End-user functionality.
- Formatting: Use GitHub Flavored Markdown.
- Language: Italian for reasoning, English for code/technical terms.
Prompt File per il Sync (.prompt)Invece di scrivere ogni volta lunghe istruzioni in chat, creiamo un template di "Sync". Crea un file chiamato .github/prompts/sync-docs.prompt:
---
title: Sync Documentation
description: Analizza le modifiche recenti al codice e aggiorna README e Manuale.
---
Act as a Technical Writer and Architect.
1. Analyze the changes in the current workspace (git diff or recent commits).
2. If there are new dependencies, update the "Requisiti" section in ROOT/README.md.
3. If there are new features, update the corresponding files in ROOT/doc/manual/.
4. If there is a change in logic, create or update a markdown file in ROOT/doc/ explaining the "Why".
5. Present the changes as a diff so I can review them before applying.
Context: #workspace
Come usarlo: Nella chat di VS Code, ti basterà scrivere / (se configurato) o richiamare il prompt file per avviare la procedura di scansione e aggiornamento.
Hooks (Automazione Proattiva)Questa è la parte più avanzata. Gli Hooks possono essere configurati per attivarsi in determinati momenti.
Puoi creare un task in .vscode/tasks.json che interroga Copilot tramite CLI o script per verificare se la documentazione è allineata.
Puoi usare uno script di pre-commit che "chiede" a Copilot (tramite gh copilot CLI se installata) di verificare se i cambiamenti nel codice riflettono cambiamenti nei file .md.
Se non vuoi usare la CLI, puoi simulare un "Human-in-the-loop Hook":
@doc-check.@doc-check check sync. L'agente confronterà lo stage di git con la cartella doc/.Se la tua documentazione è molto vasta, Copilot potrebbe perdere pezzi di contesto. Qui entra in gioco l'MCP Server.
doc/.manual/, trovando esattamente il paragrafo che deve essere aggiornato senza che tu debba dirgli quale file aprire.Ecco come dovresti operare quotidianamente per massimizzare l'abbonamento Pro+:
@workspace /sync-docs (usando il prompt file creato al punto 2).README.md e per i file in doc/manual/.code + docs.Se un file del manuale supera le 500 righe, chiedi a Copilot di usare la sua Skill di scomposizione:
"@workspace split ROOT/doc/manual/guide.md into sub-modules by feature and update the table of contents."
Questo mantiene la documentazione modulare proprio come il tuo codice C++/Python.