Copilot'a Projeyi Öğretmek: copilot-instructions.md, *.instructions.md ve applyTo, AGENTS.md ve Reusable Prompt Dosyaları

Sürüm notu: Bu yazıdaki dosyalar ve kodlar Bookstore reposunda .NET 10 ile denenmiştir; talimat kaynaklarının listesi GitHub Copilot CLI 1.0.112'nin copilot instruction list komutuyla, oturum açılmadan alınmıştır. Hangi yüzeyin hangi dosyayı okuduğu bilgisi 15 Kasım 2026'da docs.github.com, Visual Studio 2026 18.12 sürüm notları ve Visual Studio Code (VS Code) 1.146 dokümanlarından alınmıştır; talimatların bir Copilot cevabına etkisi bu yazıda denenmemiştir.

Önce Tahmin Et

Ekip, sitedeki serilerin ortak örnek uygulaması Bookstore (bir online kitapçı) için Copilot talimatlarını yazdı; .NET dosyalarına uygulanan talimatta "var yerine açık tip kullan" kuralı var. Aynı repoda Claude Code kullanan bir geliştirici kök dizine kendi notlarıyla bir CLAUDE.md ekliyor ve içine tek satır yazıyor: "Use var everywhere."

Tahminin ne? Copilot bu iki dosyadan hangisini okur? İkisini birden okursa hangisi kazanır? Cevabın bir kısmını Copilot CLI'ın kendi çıktısıyla göreceğiz.

Talimat Katmanları

Üçüncü yazıda context'i her soruda yeniden kurduk. Projenin değişmeyen bilgisi (build ve test komutları, mimari kurallar, isimlendirme) her sohbette yeniden anlatılmamalı; Copilot bunu dosyalardan okuyor. 15 Kasım 2026 itibarıyla katmanlar şunlar:

Repository geneli talimat: .github/copilot-instructions.md. Repo bağlamındaki her isteğe eklenir; düz Markdown, biçimi serbest.

Path'e bağlı talimat: .github/instructions/ altında, adı .instructions.md ile biten dosyalar. Başındaki frontmatter'da applyTo glob'u hangi dosyalarda geçerli olduğunu söyler; virgülle birden fazla glob verilebilir. Glob'lar talimat dosyasının klasörüne göre değil, repo köküne göre yazılır. GitHub.com'da cloud agent ve code review bu dosyaları okur; excludeAgent alanı "code-review" ya da "cloud-agent" değeriyle dosyayı bu ikisinden birinden saklar. Eşleşen bir path talimatı ile repo geneli talimat birlikte kullanılır.

Agent talimatları: AGENTS.md repo içinde istenen klasöre konabilir; Copilot bir dosya üzerinde çalışırken dizin ağacında en yakın AGENTS.md önceliklidir. Kök dizindeki tek bir CLAUDE.md ya da GEMINI.md de agent talimatı olarak okunur.

Kişisel ve organization talimatları: Copilot CLI ve VS Code'un Copilot harness'ı kişisel talimatları ~/.copilot/copilot-instructions.md'den, Visual Studio %USERPROFILE%/copilot-instructions.md'den okuyor. Organization sahipleri de GitHub'da bütün repolara uygulanan talimat tanımlayabiliyor. GitHub.com'da öncelik kişisel, sonra repository, sonra organization; ama üçü de modele gönderiliyor. VS Code dokümanı ise açıkça söylüyor: bütün harness'lara uyan bir öncelik kuralı yok, Copilot uygun talimatları birleştiriyor.

AGENTS.md kavramını ve neden tek kaynak olarak seçtiğimizi AI Destekli Geliştirme serisinin ikinci yazısında anlatmıştık. Bu yazı, o kararın Copilot'taki uygulaması.

Hangi Yüzey Hangi Dosyayı Okuyor

Asıl karışıklık burada. GitHub'ın "custom instructions support" tablosuna göre (15 Kasım 2026):

Bu tablo IDE'lerin sürüm notlarının gerisinde kalabiliyor. Visual Studio 2026 18.12'nin 10 Kasım 2026 tarihli sürüm notları, yeni Copilot Chat deneyiminin solution kökündeki AGENTS.md'yi ve organization talimatlarını kullandığını söylüyor; VS Code'un kendi dokümanı da Copilot harness'ında kullanıcı düzeyindeki ~/.copilot talimatlarını sayıyor. Code review için de iki not: review, talimatları pull request'in head branch'inden okuyor ve GitHub.com'daki code review REVIEW.md dosyasını da talimat olarak kabul ediyor. Review'a özel talimatlar sekizinci yazının konusu.

Tablodan çıkan pratik sonuç: AGENTS.md'yi okumayan yüzeyler hâlâ var (GitHub.com Chat, IDE'lerdeki code review, eski Chat deneyimleri). Kuralları yalnız AGENTS.md'ye yazarsan bu yüzeyler onları görmez; yalnız copilot-instructions.md'ye yazarsan Claude Code ve Codex görmez.

Bookstore'un Talimatları

Kararımız şu oldu: kurallar tek yerde, kök dizindeki AGENTS.md'de yazılıyor; copilot-instructions.md o bölümün birebir kopyasını taşıyor ve kopyanın ayrılmasını bir script engelliyor. Kök AGENTS.md:

# Bookstore

Online bookstore used as the shared example of the mertozen.com series.
.NET 10 Web API in `src/Bookstore.Api`, xUnit v3 integration tests in `tests/Bookstore.Api.Tests`,
Angular 22 client in `web/bookstore-web` (see its own AGENTS.md).

## Commands

- Build: `dotnet build`
- Test: `dotnet test` (needs SQL Server; connection string `ConnectionStrings__BookstoreDb`, see README.md)
- New migration: `dotnet ef migrations add <Name> --project src/Bookstore.Api --output-dir Data/Migrations`

## Rules

<!-- rules:start -->
- Modules live in folders under `src/Bookstore.Api` (Catalog, Ordering, Inventory, Institutional); one SQL schema per module.
- A module never reads another module's tables; it calls that module's service (`ICatalogService`, `IInventoryService`).
- Money is `decimal`, currency `TRY`; round line totals with `MidpointRounding.AwayFromZero`.
- Times are UTC (`TimeProvider`, `DateTime` in UTC).
- Endpoints return `TypedResults` and ProblemDetails for errors; no exceptions for expected outcomes.
- Every behavior change comes with a test; never weaken or delete an existing assertion to make a test pass.
- Never commit secrets or connection strings; use user-secrets or environment variables.
<!-- rules:end -->

.github/copilot-instructions.md yalnız komutları ve aynı kural bloğunu içeriyor:

# Copilot instructions for Bookstore

Build with `dotnet build`, test with `dotnet test`; the Angular client is in `web/bookstore-web` (`npm test`).
These rules are a copy of the Rules section in AGENTS.md for Copilot surfaces that do not read AGENTS.md.
Edit AGENTS.md first; `dotnet run eng/check-instructions.cs` fails when the two copies differ.

<!-- rules:start -->
- Modules live in folders under `src/Bookstore.Api` (Catalog, Ordering, Inventory, Institutional); one SQL schema per module.
- A module never reads another module's tables; it calls that module's service (`ICatalogService`, `IInventoryService`).
- Money is `decimal`, currency `TRY`; round line totals with `MidpointRounding.AwayFromZero`.
- Times are UTC (`TimeProvider`, `DateTime` in UTC).
- Endpoints return `TypedResults` and ProblemDetails for errors; no exceptions for expected outcomes.
- Every behavior change comes with a test; never weaken or delete an existing assertion to make a test pass.
- Never commit secrets or connection strings; use user-secrets or environment variables.
<!-- rules:end -->

Path'e bağlı iki talimat dosyası, .NET ve Angular kurallarını yalnız ilgili dosyalara taşıyor. Böylece Angular component'i üzerinde çalışırken Entity Framework Core (EF Core) kuralları context'i doldurmuyor:

---
applyTo: "src/**/*.cs,tests/**/*.cs"
---

- C# 14 on .NET 10: file-scoped namespaces, primary constructors, collection expressions, explicit types instead of `var` (except anonymous types).
- EF Core configuration goes in an `IEntityTypeConfiguration<T>` class next to the entity, with `ToTable("<Name>", "<schema>")`, `HasMaxLength` on every string and `HasPrecision` on every `decimal`.
- Read-only queries use `AsNoTracking()` and project to a record with `Select`; do not return entities from endpoints.
- Pass `CancellationToken` to every async EF Core and HTTP call.
- Integration tests use `BookstoreApiFactory` and `TestContext.Current.CancellationToken`; name tests as sentences (`Placing_an_order_reserves_stock`).

---
applyTo: "web/bookstore-web/src/**/*.ts,web/bookstore-web/src/**/*.html"
---

- Standalone components with `inject()`; templates use `@if` and `@for` with `track`.
- Keep component state in signals; derive values with `computed` instead of methods called from the template.
- Show money with the `currency: 'TRY' : 'symbol-narrow'` pipe.
- Specs use Vitest globals (`describe`, `it`, `expect`) with `TestBed`; mock HTTP with `provideHttpClientTesting`.

Üçüncü dosya yalnız review için: excludeAgent: "cloud-agent" onu cloud agent'tan saklıyor, code review ise okuyor. Bu kurallar kod yazan agent'a değil, değişikliği okuyan reviewer'a yönelik:

---
applyTo: "**"
excludeAgent: "cloud-agent"
---

When reviewing a pull request in this repository, check these first:

- A query inside a loop, or `Include` chains that load more than the endpoint returns.
- A new `decimal` property without `HasPrecision`, or a new string without `HasMaxLength`.
- A migration that drops or renames a column without a data step.
- A changed or deleted assertion in `tests/`; ask why the expected value changed.
- In Angular, a subscription without cleanup or state kept outside signals.

Son olarak Angular istemcisinin kendi klasöründe ikinci bir AGENTS.md var: npm komutları ve signal kuralları. Agent web/bookstore-web altında çalışırken en yakın dosya bu.

Talimatları Kontrol Etmek

Talimat dosyaları kod gibi bozulur: bir klasör taşınır ve applyTo hiçbir dosyayla eşleşmez, biri AGENTS.md'yi günceller ama kopyayı unutur. İkisi de sessiz hatadır; Copilot hata vermez, talimatı uygulamaz. Bunun için repoya bir kontrol script'i ekledik:

#:property PublishAot=false
// Copilot talimat ve prompt dosyalarını kontrol eder: frontmatter, applyTo glob'ları, AGENTS.md kopyası, boyut.
// Repo kökünden çalıştır: dotnet run eng/check-instructions.cs
using System.Diagnostics;
using System.Text.RegularExpressions;

const int AlwaysLoadedBudget = 8_000;   // kendi koyduğumuz karakter bütçesi, Copilot'un bir limiti değil
List<string> errors = [];

ProcessStartInfo git = new("git", "ls-files") { RedirectStandardOutput = true };
using Process process = Process.Start(git)!;
string[] tracked = (await process.StandardOutput.ReadToEndAsync()).Split('\n', StringSplitOptions.RemoveEmptyEntries);
await process.WaitForExitAsync();

foreach (string file in tracked.Where(f => f.StartsWith(".github/instructions/") && f.EndsWith(".instructions.md")))
{
    Dictionary<string, string> meta = Frontmatter(file);
    if (!meta.TryGetValue("applyTo", out string? applyTo))
    {
        errors.Add($"{file}: no applyTo, the file is never applied automatically");
        continue;
    }
    foreach (string glob in applyTo.Split(',', StringSplitOptions.TrimEntries))
    {
        int matches = tracked.Count(f => GlobToRegex(glob).IsMatch(f));
        Console.WriteLine($"{file}: applyTo {glob} -> {matches} files");
        if (matches == 0)
        {
            errors.Add($"{file}: applyTo '{glob}' matches no tracked file");
        }
    }
    if (meta.TryGetValue("excludeAgent", out string? agent) && agent is not ("code-review" or "cloud-agent"))
    {
        errors.Add($"{file}: excludeAgent must be code-review or cloud-agent, not '{agent}'");
    }
}

foreach (string file in tracked.Where(f => f.StartsWith(".github/prompts/") && f.EndsWith(".prompt.md")))
{
    Dictionary<string, string> meta = Frontmatter(file);
    Console.WriteLine($"{file}: /{meta.GetValueOrDefault("name", Path.GetFileName(file).Replace(".prompt.md", ""))} (agent: {meta.GetValueOrDefault("agent", "current")})");
    if (!meta.ContainsKey("description"))
    {
        errors.Add($"{file}: description is missing");
    }
}

string agentsRules = Rules("AGENTS.md");
string copilotRules = Rules(".github/copilot-instructions.md");
if (agentsRules != copilotRules)
{
    errors.Add(".github/copilot-instructions.md: rules differ from AGENTS.md, copy the Rules section again");
}

long alwaysLoaded = new FileInfo("AGENTS.md").Length + new FileInfo(".github/copilot-instructions.md").Length;
Console.WriteLine($"Always loaded (AGENTS.md + copilot-instructions.md): {alwaysLoaded:N0} characters, budget {AlwaysLoadedBudget:N0}");
if (alwaysLoaded > AlwaysLoadedBudget)
{
    errors.Add($"always-loaded instructions are {alwaysLoaded:N0} characters, over the {AlwaysLoadedBudget:N0} budget");
}

foreach (string error in errors)
{
    Console.Error.WriteLine($"error: {error}");
}
Console.WriteLine(errors.Count == 0 ? "OK" : $"{errors.Count} error(s)");
return errors.Count == 0 ? 0 : 1;

static Dictionary<string, string> Frontmatter(string path)
{
    string[] lines = File.ReadAllLines(path);
    Dictionary<string, string> values = [];
    if (lines.Length == 0 || lines[0] != "---")
    {
        return values;
    }
    foreach (string line in lines.Skip(1).TakeWhile(l => l != "---"))
    {
        int colon = line.IndexOf(':');
        if (colon > 0)
        {
            values[line[..colon].Trim()] = line[(colon + 1)..].Trim().Trim('"', '\'');
        }
    }
    return values;
}

static string Rules(string path)
{
    Match match = Regex.Match(File.ReadAllText(path), "<!-- rules:start -->(.*?)<!-- rules:end -->", RegexOptions.Singleline);
    return match.Success ? match.Groups[1].Value.Trim() : "";
}

// "**" klasörler arasında eşleşir, "*" ve "?" tek bir path parçasının içinde kalır.
static Regex GlobToRegex(string glob) =>
    new("^" + Regex.Escape(glob)
        .Replace(@"\*\*/", "(.*/)?")
        .Replace(@"\*\*", ".*")
        .Replace(@"\*", "[^/]*")
        .Replace(@"\?", "[^/]") + "$");

$ dotnet run eng/check-instructions.cs
.github/instructions/angular.instructions.md: applyTo web/bookstore-web/src/**/*.ts -> 10 files
.github/instructions/angular.instructions.md: applyTo web/bookstore-web/src/**/*.html -> 5 files
.github/instructions/code-review.instructions.md: applyTo ** -> 90 files
.github/instructions/dotnet.instructions.md: applyTo src/**/*.cs -> 29 files
.github/instructions/dotnet.instructions.md: applyTo tests/**/*.cs -> 5 files
.github/prompts/add-migration.prompt.md: /add-migration (agent: agent)
.github/prompts/new-endpoint.prompt.md: /new-endpoint (agent: agent)
Always loaded (AGENTS.md + copilot-instructions.md): 2,334 characters, budget 8,000
OK

Script'i iki yaygın hatayla denedik: angular.instructions.md'deki HTML glob'unu talimat dosyasının bulunduğu yere göre düşünüp src/app/**/*.html yazdık ve AGENTS.md'deki bir kuralı değiştirip kopyayı güncellemedik:

$ dotnet run eng/check-instructions.cs
.github/instructions/angular.instructions.md: applyTo web/bookstore-web/src/**/*.ts -> 10 files
.github/instructions/angular.instructions.md: applyTo src/app/**/*.html -> 0 files
.github/instructions/code-review.instructions.md: applyTo ** -> 90 files
.github/instructions/dotnet.instructions.md: applyTo src/**/*.cs -> 29 files
.github/instructions/dotnet.instructions.md: applyTo tests/**/*.cs -> 5 files
.github/prompts/add-migration.prompt.md: /add-migration (agent: agent)
.github/prompts/new-endpoint.prompt.md: /new-endpoint (agent: agent)
Always loaded (AGENTS.md + copilot-instructions.md): 2,346 characters, budget 8,000
error: .github/instructions/angular.instructions.md: applyTo 'src/app/**/*.html' matches no tracked file
error: .github/copilot-instructions.md: rules differ from AGENTS.md, copy the Rules section again
2 error(s)

İlk hata, glob'ların repo köküne göre yazıldığını hatırlatıyor: src/app/** Bookstore'da hiçbir dosyayla eşleşmiyor. Bu kontrol CI'da çalışınca, Copilot'un sessizce uygulamadığı bir talimat pull request aşamasında yakalanıyor.

İkinci kontrol aracı Copilot CLI'ın kendisi: copilot instruction list, bir oturumun hangi talimat kaynaklarını yükleyeceğini login gerektirmeden listeliyor. Bookstore'un kökünde ve Angular klasöründe:

$ copilot instruction list
Repository instructions:
  • .github/copilot-instructions.md
      from .github/copilot-instructions.md
  • AGENTS.md
      from AGENTS.md
  • angular.instructions.md
      from .github/instructions/angular.instructions.md
  • dotnet.instructions.md
      from .github/instructions/dotnet.instructions.md

$ cd web/bookstore-web
$ copilot instruction list
Repository instructions:
  • .github/copilot-instructions.md
      from .github/copilot-instructions.md
  • AGENTS.md
      from AGENTS.md
  • angular.instructions.md
      from .github/instructions/angular.instructions.md
  • dotnet.instructions.md
      from .github/instructions/dotnet.instructions.md

Working directory instructions:
  • AGENTS.md
      from web/bookstore-web/AGENTS.md

İki şey dikkat çekiyor. Angular klasöründe iç içe AGENTS.md "Working directory instructions" olarak ayrıca yükleniyor. Ve code-review.instructions.md listede yok: CLI 1.0.112 excludeAgent: "cloud-agent" değerli dosyayı kendisi için de dışarıda bırakıyor. Değeri "code-review" yaptığımızda ya da alanı sildiğimizde dosya listeye girdi. Bu davranışı dokümanda bulamadık, CLI'da gözlemledik; review'a özel bir dosyanın kod yazan agent'lara girmemesi zaten istediğimiz şey. --json seçeneği ise her kaynağın applyTo listesini de gösteriyor; virgülle yazdığımız iki glob ayrı ayrı okunmuş.

Şimdi Önce Tahmin Et'e dönelim. Kök dizine "Use var everywhere." yazan bir CLAUDE.md koyup listeyi yeniden aldık:

$ copilot instruction list
Repository instructions:
  • .github/copilot-instructions.md
      from .github/copilot-instructions.md
  • AGENTS.md
      from AGENTS.md
  • CLAUDE.md
      from CLAUDE.md
  • angular.instructions.md
      from .github/instructions/angular.instructions.md
  • dotnet.instructions.md
      from .github/instructions/dotnet.instructions.md

CLI CLAUDE.md'yi de yüklüyor. Copilot'un talimatları birleştirdiği ve genel bir öncelik kuralı olmadığı düşünülünce cevap şu: ikisi de context'e giriyor ve hangisine uyulacağı modele kalıyor. Çelişen talimat, en kötü talimattan da kötü; çünkü davranışı tahmin edilemez yapıyor. Çözüm aynı repoda birden fazla araç kullanılıyorsa kuralları AGENTS.md'de tutmak, CLAUDE.md'yi Claude Code'a özgü küçük farklarla sınırlamak.

Prompt Dosyaları: Tekrar Eden İşler

Talimatlar her istekte geçerli; prompt dosyaları ise senin çağırdığın, tekrar eden görevler. Bookstore'a iki tane ekledik: test ile birlikte yeni endpoint ve migration ekleme.

---
name: new-endpoint
description: Add a minimal API endpoint with an integration test
agent: agent
argument-hint: "[module] [HTTP method and route]"
---

Add the endpoint ${input:route:GET /api/...} to the ${input:module:Ordering} module.

1. Read the module's `*Module.cs` and follow how its existing endpoints are mapped and typed.
2. Return `TypedResults`; describe expected failures with ProblemDetails.
3. Add an integration test in `tests/Bookstore.Api.Tests` that fails before the change and passes after it.
4. Run `dotnet build` and `dotnet test` and report the test summary.

Do not change existing tests. Stop and ask if the endpoint needs a new table.

Frontmatter'daki agent alanı prompt'un hangi modda çalışacağını, argument-hint chat kutusunda görünen ipucunu belirliyor; ${input:route:...} çalıştırırken senden değer istiyor. Son satırdaki "mevcut testleri değiştirme" ve "yeni tablo gerekiyorsa dur ve sor" kuralları, bir sonraki yazıda agent'la çalışırken önemli olacak.

Prompt dosyalarının durumu yüzeye göre farklı. Visual Studio'da .github/prompts/ altındaki dosyalar chat'te / yazınca listenin başında çıkıyor ya da #prompt: ile ekleniyor; /savePrompt mevcut sohbetten bir prompt dosyası, /generateInstructions ise projeyi inceleyip bir copilot-instructions.md taslağı üretiyor. VS Code'da ise 1.146 itibarıyla prompt dosyaları yalnız deprecated Local harness'ında çalışıyor; Copilot harness'ında yazılan bir .prompt.md çalıştırılabilir olmuyor ve doküman, Local harness Şubat 2027'de kalkmadan prompt dosyalarını agent skill'lere dönüştürmeyi öneriyor. Skill'ler altıncı yazının konusu; Bookstore'daki iki prompt dosyası Visual Studio kullananlar için yerinde kalıyor ve altıncı yazıda skill karşılıklarını yazacağız.

Üretimde Dikkat

Talimat bir rica, güvenlik kontrolü değil. "Secret commit'leme" yazmak agent'ın bunu yapamayacağı anlamına gelmez; erişim kontrolü, content exclusion ve secret taraması ayrı katmanlar.

Talimat dosyası değişikliği de review ister. Code review talimatları pull request'in head branch'inden okuduğu için, bir pull request kendi review kurallarını değiştirebilir. .github/instructions/ ve AGENTS.md değişikliklerini CODEOWNERS ile bir sahibe bağlamak bunu görünür yapar.

Boyutu ölç. Her satır her istekte context'e giriyor; ilk yazıdaki hesapta 20 bin token'lık başlangıç context'inin her adımda yeniden gönderildiğini görmüştük. Bookstore'da her zaman yüklenen iki dosya toplam 2.334 karakter; script'teki 8.000 karakterlik bütçe bizim kararımız, Copilot'un bir sınırı değil.

Sık Düşülen Tuzaklar

Talimat dosyasını şişirmek. Wiki'yi kopyalamak yerine, agent'ın koddan çıkaramayacağı kuralları yaz; geri kalanını agent koddan okur.

Aynı repoda Claude Code ve Codex de kullanılıyorsa çelişen talimatlar. Copilot CLI CLAUDE.md'yi de yüklüyor; iki dosyada aynı konuda farklı kural olmamalı.

applyTo'yu talimat dosyasının klasörüne göre yazmak. Glob'lar repo köküne göre; kontrol script'i bu hatayı yakalıyor.

Path'e bağlı talimatın her yüzeyde çalıştığını sanmak. GitHub.com Chat ve IDE'lerdeki code review bu dosyaları okumuyor.

VS Code'da yeni prompt dosyası yazmaya devam etmek. Copilot harness'ında çalışmıyor; yeni tekrar eden işler için skill yaz.

Küçük Bir Deneme

★☆☆ Kendi reponda copilot instruction list çalıştır. Beklemediğin bir kaynak (eski bir CLAUDE.md, kişisel bir talimat) var mı?

★★☆ Bookstore'a tests/**/*.cs için ayrı bir tests.instructions.md ekle ve test kurallarını dotnet.instructions.md'den oraya taşı. Kontrol script'ini çalıştır; sonra glob'u bilerek bozup hatayı gör.

★★★ eng/check-instructions.cs'i bir GitHub Actions adımı olarak çalıştır ve AGENTS.md ile .github/instructions/ için bir CODEOWNERS satırı ekle. Ardından bir pull request'te yalnız code-review.instructions.md'yi değiştir ve review sürecinde bunun nasıl göründüğüne bak.

Talimatlar ve prompt dosyaları hazır. Bir sonraki yazıda bunları kullanan agent'la çok adımlı iş yapıyoruz: tool onayları, terminal komutları, checkpoint'ler ve Bookstore'a "kurumsal siparişte en az 20 adet" kuralını API, Angular ve testleriyle eklemek.