What the AI knows
Project instructions, code conventions, architecture patterns, and the key commands of your repository.
Five cascading layers, from copilot-instructions.md to prompt files. A technical briefing on how GitHub Copilot assembles context, how precedence works, and how to design a configuration stack your whole team inherits.
Modern AI assistants read a hierarchy of files to assemble the context behind every single response.
What the AI knows
Project instructions, code conventions, architecture patterns, and the key commands of your repository.
What the AI can do
Allowed tools, access limits, and the security guardrails that keep agents inside the lines.
How the AI behaves
Scoped rules per area, the personality of specialized agents, response tone and format.
Teams end up with duplicated instructions, conflicting rules, or an AI that ignores critical conventions because the right file was never created.
body { }
.container { }
#hero { }
copilot-instructions.md
.instructions.md
*.agent.md · SKILL.md
A child layer ADDS, it never contradicts. If the global file says "use TypeScript", a scoped file cannot say "use JavaScript". Specificity complements, it never overrides.
A deep dive into each file type, with real content, real locations, and the activation rule of each one.
copilot-instructions.md is the global brain of the repository.# Project: E-Commerce Platform ## Tech Stack - Next.js 14 with App Router - TypeScript strict mode - Prisma ORM with PostgreSQL ## Conventions - kebab-case for file names - PascalCase for React components - All API routes in app/api/ - Tests: Vitest, run with npm test ## Architecture - Feature-based folder structure - Server components by default
.github/copilot-instructions.md
Automatic in every GitHub Copilot session. Always active, no frontmatter needed.
The single most impactful file you can create. It sets the tone for every interaction with your project.
.instructions.md applies rules only where the glob matches..github/instructions/*.instructions.md
The applyTo frontmatter holds a glob pattern. Rules load only when a file in context matches it.
Different parts of the project need different rules: React rules for components, API rules for routes, test rules for specs.
--- applyTo: "src/components/**/*.tsx" --- # React Component Rules - Functional components with hooks - TypeScript interfaces for all props - JSDoc comments on public props - Tailwind for styling, no CSS modules - Unit tests in __tests__/ folder - Components must stay under 200 lines
*.agent.md defines specialized personas with their own tools.--- description: "Security code reviewer" tools: [codeql, semgrep, gh-advanced-security] --- # Security Reviewer Agent You are a security code reviewer. Analyze: - SQL injection vulnerabilities - XSS attack vectors - Authentication bypass risks Always provide: - Severity (Critical/High/Medium/Low) - OWASP category reference - Remediation code example
A name, a description, and a unique behavior the model adopts when the agent is active.
An explicit allowlist of tools the agent may call. Everything else is off the table.
Focus on one area or task type. The active agent narrows the context to its own domain.
Custom agents (.agent.md) substituem os antigos chat modes: persona, allowlist de ferramentas e handoffs encadeados. Em planos Business e Enterprise, definições podem ser compartilhadas no nível da organização: todo repo herda os mesmos especialistas.
SKILL.md packages a complete domain, not just rules..github/skills/<name>/SKILL.md
Rules plus workflows plus templates plus quality checklists. The structure forces completeness.
Instructions are simple scoped rules. Skills are complete domain packages. Reach for a skill when the domain is complex.
--- name: "REST API Design" globs: ["src/api/**/*.ts", "src/routes/**/*.ts"] alwaysApply: false --- # REST API Design Skill ## Rules - Plural nouns: /users, not /user - Version APIs: /api/v1/resources - Cursor-based pagination ## Workflow 1. Define resource schema 2. Route handlers 3. Validation middleware 4. Integration tests ## Quality checklist - [ ] Proper status codes on all endpoints - [ ] Input validation on POST and PUT - [ ] OpenAPI docs generated
.prompt.md turns repeated requests into reusable templates.--- mode: "agent" description: "Create a new React component" variables: - name: "componentName" - name: "type" # page, layout, widget --- Create a React component called {{componentName}}. Type: {{type}} Steps: 1. Create the file in src/components/ 2. Add the TypeScript props interface 3. Add a unit test in __tests__/ 4. Export from the barrel index.ts
mode: "agent" lets GitHub Copilot execute actions, create files, run tests. mode: "edit" only suggests changes.
Double braces mark dynamic parameters. GitHub Copilot prompts for the values before executing.
Ephemeral by design. A prompt file runs once per invocation and does not persist in context.
Validate names and frontmatter against the official GitHub Copilot customization documentation. Conventions evolve fast.
Doado pela OpenAI à Agentic AI Foundation (Linux Foundation) em dez 2025, junto com MCP e goose. O VS Code lê AGENTS.md como instrução sempre ativa lado a lado com o copilot-instructions.md: um é o padrão aberto multi-ferramenta, o outro é o canal específico do GitHub Copilot.
// servers que o agente pode usar { "servers": { "github": { "url": "https://api.githubcopilot.com/mcp/" }, "postgres": { "command": "npx", "args": ["-y", "@mcp/postgres"] } } }
Model Context Protocol: spec 2025-11-25 (async tasks, extensões, elicitation) e governança na Agentic AI Foundation desde dez 2025. Para a hierarquia, a regra é a mesma das outras camadas: declare no repo, versione em Git, e o time inteiro herda as mesmas conexões.
A lição operacional: nomes de arquivo e frontmatter mudam em ciclos de meses. Trate a doc oficial de customização como fonte de verdade, agende uma revisão trimestral da stack, e renomeie .chatmode.md para .agent.md no próximo ciclo.
The seven-step algorithm GitHub Copilot runs to assemble context, and the precedence rules that resolve conflicts.
copilot-instructions.md
Load the global repository context first, in every session.
files in context
Identify which files are part of the current conversation.
*.instructions.md
Apply every instruction file whose glob matches those files.
*.agent.md
Load the definition of the active agent, when one is invoked.
SKILL.md
Activate skills by glob match or alwaysApply: true.
*.prompt.md
Expand the prompt template with its variables, when invoked.
.mcp.json
Aggregate the available MCP connections into the final context.
No pull request, o agente de code review usa o copilot-instructions.md da base. Regras novas na feature branch só valem depois do merge. É proposital: a branch não reescreve as próprias regras de revisão.
As sugestões inline enquanto você digita são um sistema separado: não leem copilot-instructions.md nem instructions files. A hierarquia governa o chat e os agentes, não o autocomplete.
Todo instructions file cujo glob bate entra junto, em união. Não existe override nem precedência entre eles. Se duas regras conflitam, as duas chegam ao modelo. Resolver conflito é trabalho seu, não do GitHub Copilot.
O frontmatter excludeAgent opta um agente para fora de um instructions file: a regra de segurança que é perfeita no code review e verbosa demais no chat fica só onde ajuda.
Comportamentos documentados na doc oficial de customização do VS Code e do GitHub Copilot. Vale colar este slide no canal do time: cada item aqui já custou uma tarde de debugging em algum lugar.
More specific rules complement the generic ones and prevail in practice when both touch the same point.
.instructions.md > copilot-instructions.md
Layers accumulate, they never replace each other. The final context carries all of them.
folder rule + global rule = both
An active agent narrows the context to its own domain, tools, and identity.
security agent focuses on vulnerabilities
Prompt files run on demand and do not persist. One invocation, one expansion.
template runs once per invocation
Estimativas típicas por camada, para formar intuição de ordem de grandeza. O ponto: configuração também é contexto pago por request. Curadoria vale dinheiro.
A conta: 800 tokens de contexto repetido, vezes 40 chats, vezes 20 devs, vezes 20 dias úteis. A hierarquia transforma esses 32 milhões de tokens repetidos em arquivos versionados, carregados uma vez, herdados por todos.
O ganho real não é o token, é a consistência. Quando o conhecimento mora no repo, o agente fica bom no primeiro dia de um dev novo, não no terceiro mês.
Cinco alavancas, um princípio: o contexto certo, no momento certo, pago uma vez. Curadoria não é estética, é a linha de FinOps que ninguém olha.
Each file answers one question. No 500-line catch-all document.
GitHub Copilot assembles the right context for each file you edit. No manual wiring.
The whole stack lives in git. Config changes go through pull requests like any other code.
Regra de bolso: comece sempre pelo nível mais alto que ainda é verdadeiro. Conhecimento que vale para tudo sobe; conhecimento que vale para um caso desce. Duplicação entre níveis é o cheiro de que a pergunta errada foi respondida.
The stack and conventions came from copilot-instructions.md without anyone pasting them.
The API rules activated because the target path matched the applyTo glob.
The REST design skill brought workflows and checklists, not just rules.
Three enterprise scenarios, the measured impact, and the do or do not list that keeps the stack healthy.
Global instructions define the stack, three scoped instruction files cover components, API and tests, a security agent scans every PR, and a compliance skill encodes the financial domain.
One global architecture file, separate scoped instructions per service (cart, payments, inventory), a migration-expert agent for the legacy code, and shared skills for event sourcing and CQRS.
An organizational template every repo inherits, teams add their own scoped rules without conflicts, shared skills ship from a central repository, and standardized prompts cover common operations.
Figures observed in enterprise adoptions of this pattern. Treat them as direction, and validate against your own baseline.
Todo o conhecimento do time despejado no copilot-instructions.md. Paga o custo em toda request, enterra o crítico no meio do irrelevante, e ninguém revisa. Quebre em camadas: o slide da árvore de decisão é o mapa.
O /init gera um bom rascunho, mas rascunho gerado documenta o óbvio e omite o tácito. Sem um dono que corta o redundante a cada trimestre, o arquivo vira ruído pago por request.
"Use TypeScript strict" no global, no instructions de API e na skill. Como tudo empilha em união, a regra chega três vezes, e quando o time muda de opinião, alguém esquece uma cópia. Cada regra mora em exatamente um nível.
Token de API no instructions file, URL de produção no prompt file. Esses arquivos vão para o Git e para o contexto do modelo. Segredo fica em vault; configuração de ambiente fica em mcp.json com inputs, nunca hardcoded.
Os quatro saem de revisões de stack reais. O padrão comum: tratar configuração de agente como documentação, quando ela é código, com custo por execução, dono e ciclo de revisão.
Put everything in copilot-instructions.md. A 500-line file becomes noise and the model loses focus.
Split into layers: global, scoped, agents, skills. Each file short, focused, and easy to review.
Write contradictory rules between layers, like global saying CSS Modules and a scoped file saying Tailwind.
Make layers complement each other. If global defines Tailwind, the scoped file adds specific Tailwind rules.
Dump complex domain knowledge into flat instructions with no structure, no workflow, no checklist.
Use SKILL.md for complex domains: rules plus workflows plus templates plus checklists. Structure ensures completeness.
Config automates patterns that used to rely on human review.
New devs produce consistent code from day one, guided by config.
Uniform patterns across every repo and team in the organization.
Automatic rules prevent common mistakes before the commit.
Ranges observed across enterprise adoptions. Your baseline defines your numbers: measure before and after.
Os arquivos são o que você escreve. A memória é o que o GitHub Copilot aprende sozinho, e lembra entre sessões.
O que o GitHub Copilot descobre do código
Convenções, decisões de arquitetura, comandos de build, dependências entre arquivos. Criados por quem tem write access, disponíveis a todo o time, presos àquele repo.
Como você gosta de trabalhar
Estilo de comunicação, stack preferida, convenções de commit. Seguem você entre repositórios, sem afetar os outros. Em Business e Enterprise, sob governança do admin.
Public preview, jan 2026, ativada por padrão em Pro e Pro+ desde março. Disponível em coding agent, code review e CLI. O que um agente aprende, outro usa.
Cada fato carrega citações. O GitHub Copilot confere contra a branch atual antes de aplicar. Stale nunca entra.
Fato não usado some sozinho. O timer reseta a cada uso validado. Nada de lixo acumulado.
Fato de um repo nunca vaza para outro. Privacidade e segurança por desenho.
A regra de bolso: deixe a memória descobrir, depois gradue o que se repete para um arquivo. Se o GitHub Copilot reaprende a mesma coisa toda semana, isso é sinal de que falta uma instruction.
"Sempre cheque ISafeAreaView e ISafeAreaView2 juntos" reaparece toda semana, vira instruction.
Sem graduação, o aprendizado valioso expira em 28 dias. Com graduação, o repo acumula conhecimento permanente.
Memória e arquivo não competem, se completam. A memória é o rascunho que o agente escreve sozinho. O arquivo é a versão que você decide tornar lei.
Building the future of software development with AI and Agentic DevOps.
# 1. Create the structure $ mkdir -p .github/instructions \ .github/agents .github/skills .github/prompts # 2. Start with the global brain $ touch .github/copilot-instructions.md stack, conventions, key commands. Short. # 3. Add one scoped rule where pain lives $ touch .github/instructions/api.instructions.md applyTo glob + the rules for that area only