Customization

Make it yours: principles, profiles, custom instructions, configuration hierarchy.

The Two-Layer Model

Every project gets two layers of guardrails. Layer 1 is your non-negotiable standards — the rules every project gets whether they ask or not. Layer 2 is your project's specific ambitions — the coverage targets, latency SLAs, and domain rules that make this project different from the last one.

If Layer 2 conflicts with Layer 1, Layer 2 wins for that specific project. Example: Layer 1 says "TDD for business logic" → Layer 2 says "TDD for ALL code" → Layer 2 applies.

Project Principles

Principles declare what your project believes — non-negotiable commitments about technology, architecture, and quality. They're checked automatically during Steps 1, 2, and 5.

1. Open Copilot Chat → Agent Mode
2. Attach .github/prompts/project-principles.prompt.md
3. Choose your path: A) Interview, B) Starter set for your stack, or C) Discover from codebase
4. The prompt generates docs/plans/PROJECT-PRINCIPLES.md

## Technology Commitments
- PostgreSQL for all persistence — no MongoDB, no SQLite in production
- All services communicate via gRPC — no REST between internal services

## Architecture Commitments
- All data access goes through repositories — no direct SQL in services
- Background jobs use BackgroundService + PeriodicTimer — no Hangfire

## Quality Commitments
- 90% test coverage on business logic — non-negotiable
- No secrets in code — ever. Use IConfiguration + Key Vault

Project Profile

The profile tells the AI how to write code — generated from an interview about your standards:

1. Attach .github/prompts/project-profile.prompt.md
2. Answer questions about testing, performance, security, domain rules
3. The prompt generates .github/instructions/project-profile.instructions.md

Editing copilot-instructions.md

This is the master config file — loaded every session, for every file. Keep it focused:

• Project overview — what your app does, who it's for (2–3 sentences)
• Tech stack — specific versions, frameworks, libraries
• Architecture — how layers are organized, key patterns
• Quick commands — build, test, lint, run dev

Writing Custom Instruction Files

Create a new .instructions.md file in .github/instructions/ with YAML frontmatter:

---
description: Billing domain rules — Stripe integration, invoice generation
applyTo: "**/billing/**,**/invoices/**,**/payments/**"
---

# Billing Domain Rules

- All money amounts stored as `decimal(18,4)` — never `float`
- Use Stripe SDK v45+ — never raw HTTP calls
- Every payment mutation must be idempotent (use idempotency keys)
- Invoice PDFs generated async via background service
- All billing events published to `billing.*` topic

When you edit src/billing/InvoiceService.cs, this file loads automatically alongside the universal baseline.

applyTo Pattern Reference

Customizing Agents

Agent definitions live in .github/agents/. Each is a Markdown file with YAML frontmatter that declares the agent's role, tool restrictions, and expertise:

---
name: "billing-reviewer"
description: "Audit billing code for Stripe compliance and financial accuracy"
tools: ["read_file", "grep_search", "semantic_search"]
---

Agents are read-only — they can search and read but can't edit files. This makes them safe to run as independent auditors. To create a new agent, copy an existing one and modify the expertise section.

Customizing Skills

Skills are multi-step procedures in .github/skills/*/SKILL.md. Each skill defines steps, validation gates, and expected outputs. Every skill follows the Skill Blueprint format — including Temper Guards, Warning Signs, and Exit Proof sections. To create a custom skill:

1. Create a directory: .github/skills/my-workflow/
2. Add SKILL.md with steps, gates, and description
3. Invoke with /my-workflow in Copilot Chat

Configuration Hierarchy

Three levels of configuration, from team-wide to personal:

Personal preferences override team config for the individual developer. Editor settings control VS Code behavior (agent mode enabled, prompt files, etc.).

📄 Full reference: CUSTOMIZATION.md