Guida introduttiva: Usare istruzioni personalizzate per allineare GitHub Copilot alle convenzioni T-SQL

Le istruzioni personalizzate consentono a GitHub Copilot di apprendere gli standard del team, affinché ogni risposta, sia in modalità Ask, in modalità agente o nei completamenti inline, rispetti le convenzioni di denominazione, formattazione e tipi di dati. Un singolo file Markdown relativo ai file .sql trasforma l'output generico di Transact-SQL (T-SQL) in un output allineato al progetto.

Tip

Le istruzioni personalizzate si applicano a ogni contesto di GitHub Copilot che corrisponde al modello glob applyTo, incluse la modalità domanda, la modalità di modifica, la modalità agente e i completamenti in linea. Configurarli una volta sola per lingua o dominio.

Messaggi chiave:

Le istruzioni personalizzate si trovano all'interno .github/instructions/<name>.instructions.md dell'area di lavoro.
La chiave applyTo front matter limita ogni file a un pattern glob, ad esempio **/*.sql.
GitHub Copilot inserisce automaticamente le istruzioni corrispondenti in ogni richiesta. Non è necessario alcun comando con slash.
In assenza di istruzioni personalizzate, GitHub Copilot usa per impostazione predefinita convenzioni generiche (PascalCase, chiavi primarie INT, senza modelli di file).

Prerequisiti

Visual Studio Code con l'estensione MSSQL installata.
Sottoscrizione attiva GitHub Copilot.
Cartella dello spazio di lavoro. Questa guida introduttiva crea nuovi file in .github/instructions/.

Che cosa sono le istruzioni personalizzate?

Le istruzioni personalizzate sono file Markdown che GitHub Copilot leggono e si applicano a ogni richiesta corrispondente a un modello GLOB. Visual Studio Code li supporta in modo nativo. L'estensione MSSQL non richiede alcuna configurazione aggiuntiva.

Ogni serio strumento di codifica di intelligenza artificiale supporta ora una versione di questo modello: cursore usa .cursorrules, OpenAI Codex usa AGENTS.md, Anthropic Claude Code usa CLAUDE.md. GitHub Copilot in Visual Studio Code usa .github/instructions/*.instructions.md. Il vantaggio è che è possibile avere più file di istruzioni associati a diversi tipi di file nello stesso repository.

Per la documentazione generale di Visual Studio Code su questa funzionalità, vedere Personalizzare le risposte dell'IA in Visual Studio Code.

Perché le istruzioni personalizzate sono importanti per T-SQL

Il moderno GitHub Copilot genera fin da subito un T-SQL notevole: NVARCHAR colonne, DATETIME2 timestamp, nomi sensati per i vincoli. Per impostazione predefinita, tuttavia, utilizza convenzioni che il tuo team potrebbe non adottare.

Senza istruzioni personalizzate, GitHub Copilot in genere:

Usa PascalCase per i nomi delle tabelle e delle colonne (UserID, CreatedAt) anziché lo stile camelCase o snake_case del team.
Usa chiavi primarie INT anziché BIGINT.
Omette i modelli di intestazione dei file, SET ANSI_NULLS ON e SET QUOTED_IDENTIFIER ON.
Ignora la qualificazione dello schema (CREATE TABLE users anziché CREATE TABLE dbo.users).
Genera vincoli con nome automatico anziché seguire il PK_tableName / FK_child_parent modello.

Nessuna di queste impostazioni predefinite è errata. Non sono i tuoi. Le istruzioni personalizzate consentono di risolvere tutto questo problema con un singolo file.

Creare un file di convenzioni T-SQL

In questo esempio viene creato un file di istruzioni che applica la denominazione camelCase, la qualificazione dello schema, le colonne di controllo e un modello di intestazione di file.

Passaggio 1: Usare GitHub Copilot per creare il file

In Visual Studio Code aprire la visualizzazione Copilot Chat GitHub.
Selezionare l'icona delle impostazioni (ingranaggio) e quindi scegliere Istruzioni e regole>Nuovo file di istruzioni.
Quando viene richiesta una posizione, selezionare .github/instructions.
Quando viene richiesto un nome file, immettere tsql-conventions.

Visual Studio Code crea .github/instructions/tsql-conventions.instructions.md con un’intestazione precompilata.

Passaggio 2: Aggiungere le convenzioni

Sostituire il contenuto predefinito con gli standard T-SQL del team. Il modello seguente illustra la denominazione, i tipi di dati, le colonne di controllo, la qualificazione dello schema, la denominazione dei vincoli e i modelli non consentiti.

---
applyTo: "**/*.sql"
---

# T-SQL conventions

## Database environment
- Local development: [!INCLUDE [sssql25-md](../../../includes/sssql25-md.md)] running in a Docker container
- Cloud / production: Azure SQL Database
- All T-SQL must be compatible with both environments

## File template
Every .sql file MUST begin with this header block:

-- ================================================================
-- Author:      <your name>
-- Created:     <YYYY-MM-DD>
-- Purpose:     <brief description>
-- ================================================================
SET ANSI_NULLS ON;
GO
SET QUOTED_IDENTIFIER ON;
GO

## T-SQL conventions
- Use camelCase for ALL identifiers: table names, column names, parameters
- Use NVARCHAR for all text columns - never VARCHAR
- Use BIGINT for all primary keys and foreign keys - never INT
- Every table MUST include these audit columns:
    createdAt  DATETIME2(7) NOT NULL DEFAULT GETUTCDATE()
    updatedAt  DATETIME2(7) NOT NULL DEFAULT GETUTCDATE()
- Always schema-qualify all objects: dbo.tableName
- Use clustered primary keys on all tables
- Foreign key column names follow the pattern: [referencedTable]Id
- Never use SELECT * - always name columns explicitly

## Constraint naming conventions
- Primary keys: PK_tableName
- Foreign keys: FK_childTable_parentTable
- Unique constraints: UQ_tableName_columnName
- Check constraints: CK_tableName_columnName
- Default constraints: DF_tableName_columnName

## What to avoid
- Do NOT generate stored procedures unless I explicitly ask for one
- Do NOT use deprecated T-SQL syntax (no *= for joins, no non-ANSI joins)
- Do NOT generate object-relational mapping (ORM) models or application code

Passaggio 3: Salvare il file

GitHub Copilot raccoglie i file di istruzioni non appena si salva. Non è previsto alcun passaggio di ricaricamento o configurazione.

Vedere il contrasto prima/dopo

Per visualizzare l'impatto delle istruzioni personalizzate, eseguire la stessa richiesta in GitHub Copilot Chat prima e dopo l'aggiunta del file.

Prima: nessuna istruzione personalizzata

In un'area di lavoro senza la cartella .github/instructions/, chiedi a GitHub Copilot:

Create a users table and a projects table for a task management app.

Output tipico:

CREATE TABLE Users (nessuna qualificazione dello schema, PascalCase)
UserID INT IDENTITY(1,1) PRIMARY KEY
Nessun blocco di intestazione del file e nessuna istruzione SET
Vincoli denominati automaticamente o incoerenti

Dopo: con istruzioni personalizzate

Nell'area di lavoro in cui è stato creato tsql-conventions.instructions.md, chiedere la stessa richiesta:

Create a users table and a projects table for a task management app.

Output previsto:

Intestazione di file completa con autore, data, scopo, , SET ANSI_NULLS ONSET QUOTED_IDENTIFIER ON
CREATE TABLE dbo.users (qualificato con schema, camelCase)
userId BIGINT IDENTITY(1,1) PRIMARY KEY
createdAt e updatedAt colonne di audit
Vincoli denominati: PK_users, UQ_users_email, FK_projects_users, DF_users_createdAt

Stesso modello, stessa richiesta, stessa GitHub Copilot. Il file delle istruzioni ha eseguito il lavoro.

Verificare che vengano applicate istruzioni personalizzate

Per verificare che GitHub Copilot stia leggendo il file di istruzioni, esaminare l'output di debug.

In Visual Studio Code selezionare Visualizza>output.
Nell'elenco a discesa del canale di output selezionare GitHub Copilot o GitHub Copilot Chat.
Invia un prompt e osserva il canale di uscita. Il payload completo della richiesta, incluse le istruzioni personalizzate, viene visualizzato nel log.

Questa vista di debug è l'origine della verità. Se l'output non contiene le istruzioni, verificare che:

Il file si trova all'indirizzo .github/instructions/<name>.instructions.md (è necessario il .instructions.md suffisso ).
Il applyTo glob corrisponde al file su cui si sta lavorando.
Il file viene salvato.

Modelli e procedure consigliate

Un file per lingua o dominio. Usare file separati per T-SQL, TypeScript, Python e così via, ognuno con il proprio applyTo glob. Non mischiare le lingue in un unico file.
Mantienilo dichiarativo. Gli elenchi puntati e le regole brevi funzionano meglio del testo in prosa. GitHub Copilot segue le istruzioni in modo più affidabile quando sono facili da scorrere.
Controllo della versione dei file. Effettua il commit .github/instructions/ nel tuo repository in modo che tutti i collaboratori ne traggano automaticamente vantaggio.
Associa alla modalità piano. Quando si usa la modalità di pianificazione per la progettazione del database, le convenzioni vengono ereditate automaticamente. Non è necessario ripeterli nel prompt.
Testare dopo le modifiche. Usare la visualizzazione di debug per verificare che le istruzioni vengano applicate ogni volta che si aggiorna il file.

Per ottimizzare e migliorare GitHub Copilot per l'estensione MSSQL, usare il modello di problema GitHub seguente per inviare commenti e suggerimenti: Commenti e suggerimenti su GitHub Copilot

Quando si inviano commenti e suggerimenti, è consigliabile includere:

Scenari testati: segnalare le aree su cui ci si è concentrati, ad esempio la creazione dello schema, la generazione di query, la sicurezza, la localizzazione.
Cosa ha funzionato bene: descrivere tutte le esperienze che si sono sentite fluide, utili o superate le aspettative.
Problemi o bug: includere eventuali problemi, incoerenze o comportamenti confusi. Screenshot o registrazioni dello schermo sono particolarmente utili.
Suggerimenti per il miglioramento: condividere idee per migliorare l'usabilità, espandere la copertura o migliorare le risposte di GitHub Copilot.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-23