Instruction Files & Agents
The guardrail system: what each file covers, when it activates, and how agents review your code.
How Auto-Loading Works
Each instruction file has an applyTo glob pattern in its YAML frontmatter. When you edit a file matching that pattern, the instruction auto-loads into the AI's context. No manual action needed, it's the difference between drowning the AI in every rule you have and having the right guidance whisper only when it's relevant. (For full details on writing your own applyTo patterns, see Chapter 9.)
---
description: Security best practices, input validation, auth, secrets
applyTo: "**/auth/**,**/security/**,**/middleware/**"
---
# Security Rules
- Parameterized queries only, never string interpolation in SQL
- Input validation at system boundaries
- No secrets in code, use environment variables or secret managers
...A Concrete Scenario
Say you ask Copilot Chat to make a change to src/auth/token-validator.cs. Here's what auto-loads, and why each one matters:
| File that loads | Why it matched | What it whispers to the AI |
|---|---|---|
architecture-principles.instructions.md | Universal, applyTo: "**" | Stop! Before writing code, ask the 5 architecture questions. Don't bypass scope, don't skip tests. |
security.instructions.md | Path matched **/auth/** | Parameterized queries only. No secrets in code. Validate inputs at every boundary. OWASP Top 10 defense patterns. |
auth.instructions.md | Path matched **/auth/** | JWT/OIDC patterns, token expiry rules, RBAC enforcement, multi-tenant isolation guards. |
testing.instructions.md | Universal, applyTo: "**" | Tests required for new behavior. Use the project's test framework. Cover edge cases (expired token, tampered signature). |
The AI now has 4 focused instruction files in its context, not 17. If you switch to editing src/db/UserRepository.cs, security stays loaded but auth swaps out for database.instructions.md. The right rules whisper at the right time, without you doing anything.
Below is the full catalog: which files exist, what each covers, and which patterns trigger them.
Universal Files (All Presets)
These four files ship with every preset, they form the universal baseline:
| File | applyTo | Purpose |
|---|---|---|
architecture-principles | ** | 5 questions before coding, 4-layer architecture, separation of concerns |
git-workflow | ** | Conventional commits, push reminders, version-aware messaging |
ai-plan-hardening-runbook | docs/plans/** | Quick-reference when editing plan files |
status-reporting | docs/plans/**, .forge/** | Standard output templates for orchestration updates |
Domain Instruction Files (Per Preset)
Each preset installs 17 domain-specific instruction files. They auto-load based on what you're editing:
| File | Domain | Loads When Editing |
|---|---|---|
api-patterns | REST conventions, pagination, error responses | Controllers, routes, endpoints |
auth | JWT/OIDC, RBAC (role-based access control), multi-tenant isolation | Auth modules, middleware |
caching | Redis, in-memory cache, TTL strategies | Cache services, config |
database | ORM/query patterns, migrations, connections | Repositories, SQL, models |
dapr | Dapr sidecar patterns, pub/sub, state management | Dapr config, service invocation |
deploy | Dockerfiles, health checks, container optimization | Dockerfiles, compose, k8s |
errorhandling | Exception hierarchy, ProblemDetails (RFC 7807 standard JSON error responses), error boundaries | Error handlers, middleware |
graphql | Schema design, resolvers, query patterns, Hot Chocolate / Apollo | GraphQL types, resolvers |
messaging | Pub/sub, job queues, event-driven patterns | Event handlers, message consumers |
multi-environment | Dev/staging/prod config, environment detection | Config files, env setup |
naming | Naming conventions, file organization, namespace rules | All code files |
observability | OpenTelemetry, structured logging, metrics | Logging, tracing, health |
performance | Hot/cold path analysis, allocation reduction | Performance-critical code |
security | Input validation, secret management, CORS | Auth, security, middleware |
testing | Unit tests, integration tests, test containers | Test files |
version | Semantic versioning, commit-driven bumps | Version files, changelogs |
project-principles | Activates when PROJECT-PRINCIPLES.md exists | Plan files, reviews |
frontend.instructions.md for React/Vue patterns. The azure-iac preset replaces several app-specific files with Bicep/Terraform equivalents.
Every instruction file includes Temper Guards (shortcut prevention tables) and Warning Signs (observable anti-patterns). These help agents avoid common quality erosion and help reviewers detect violations.
📄 Full reference: capabilities, Multi-Agent Setup — GitHub Copilot