| Kavram | Bir Cümleyle | Nerede Yaşar | Ne Zaman Tetiklenir |
|---|---|---|---|
| Rules | AI'ın nasıl davranacağını belirler | .cursor/rules/ |
Her zaman / otomatik / agent kararıyla / manuel |
| Commands | Tekrar eden prompt'ları kısayola bağlar | .cursor/commands/ |
Kullanıcı /komut yazınca |
| Skills | AI'a alan uzmanlığı öğretir | .cursor/skills/ |
Agent gerekli gördüğünde otomatik yükler |
| Subagents | Paralel çalışan uzman agent'lar | .cursor/agents/ |
Agent delege ettiğinde veya manuel çağrıda |
| Hooks | Agent yaşam döngüsüne müdahale scriptleri | .cursor/hooks.json |
Dosya düzenlenince, komut çalışmadan önce vb. |
Rules → "Hep böyle yaz" (davranış kuralları)
Commands → "Bu komutu çalıştır" (kısayol prompt'lar)
Skills → "Bunu nasıl yapacağını bil" (bilgi paketleri)
Subagents → "Sen şunu yap, ben bunu" (paralel iş dağılımı)
Hooks → "Her düzenlemeden sonra X'i çalıştır" (otomasyon)
Rules, AI agent'ın kodlama stili, proje standartları ve tercihlerin konusunda tutarlı davranmasını sağlar. Bir nevi "onboarding dokümanı" gibi düşün — yeni bir takım arkadaşına vereceğin belgeyi buraya yazarsın.
| Tür | Açıklama | Ayar |
|---|---|---|
| User Rules | Tüm projelerde geçerli kişisel tercihler | Cursor Settings > Rules |
| Project Rules | Projeye özel, .cursor/rules/ içinde |
Her biri bir klasör + RULE.md |
| Team Rules | Admin panelinden yönetilen takım kuralları | Enterprise/Team plan |
| AGENTS.md | Basit alternatif, proje kökünde tek dosya | Proje root'una koy |
.cursor/rules/
├── coding-standards/
│ └── RULE.md
├── api-conventions/
│ └── RULE.md
└── testing-rules/
└── RULE.md
---
description: "TypeScript API endpoint'leri için kodlama standartları"
alwaysApply: false
---
# API Kodlama Standartları
- Tüm endpoint'ler try/catch ile sarılmalı
- Response tipi her zaman generic Result<T> ile dönmeli
- Validation için Zod kullan
- Loglama için structured logging (JSON format)
- Her endpoint'e rate limiting uygula| Değer | Davranış |
|---|---|
true |
Her chat oturumunda context'e eklenir |
false |
Agent, description'a bakarak gerekli olup olmadığına karar verir |
---
description: "React component kuralları"
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
---Bu rule, sadece belirtilen pattern'e uyan dosyalar açıldığında otomatik uygulanır.
- Rule'ları kısa tut: 500 satırı geçme, uzun rule'lar göz ardı edilebilir
alwaysApply: true'yu az kullan: Her istekte context token'ı harcar- Spesifik description yaz: "Genel kodlama kuralları" yerine "NestJS service katmanı için dependency injection kuralları"
@filereferansı kullan: Rule içinde proje dosyalarına referans verebilirsin- Versiyonla:
.cursor/rules/Git'e commit'le, tüm takım aynı kurallarla çalışsın - Context window dolduğunda agent rule'ları unutabilir — uzun konuşmalarda "kuralları tekrar oku" de
---
description: "Entity Framework Core ve .NET API geliştirme standartları"
globs: ["**/*.cs"]
---
# .NET Geliştirme Kuralları
- Repository pattern kullan, doğrudan DbContext'i controller'dan çağırma
- Soft delete için global query filter uygula
- Migration'lar için anlamlı isim ver (AddUserRolesTable gibi)
- Async/await pattern'ini her yerde kullan, .Result veya .Wait() yasak
- FluentValidation ile input validation yap
- Hangfire job'ları için idempotent tasarlaSık kullandığın prompt'ları Markdown dosyası olarak kaydet, /komut yazarak anında çağır. Takımla paylaşılabilir, Git'e commit'lenebilir.
.cursor/commands/ # Proje bazlı
~/.cursor/commands/ # Global (tüm projeler)
Her .md dosyası bir komut olur. Dosya adı = komut adı.
.cursor/commands/review.md
# Code Review
Bu dosyadaki kodu incele ve şu kriterlere göre değerlendir:
## Kontrol Listesi
- Error handling: Tüm async işlemler try/catch içinde mi?
- N+1 query problemi var mı?
- Input validation yapılmış mı?
- Güvenlik açıkları var mı? (SQL injection, XSS)
- Naming convention'lara uyuluyor mu?
## Çıktı Formatı
Her dosya için APPROVE, REQUEST_CHANGES veya COMMENT verdikti ver.Kullanım: Chat'te /review yaz, seç, çalıştır.
/commit — Otomatik Commit Mesajı:
# Git Commit
Mevcut değişiklikleri analiz et ve conventional commit formatında mesaj oluştur:
"<type>(<scope>): <description>"
Tipler: fix | feat | chore | docs | refactor | test | perf
Birden fazla değişiklik varsa her biri için ayrı -m flag'i kullan./test — Test Yazma:
# Test Yaz
Bu dosya için kapsamlı test suite oluştur:
1. Mevcut test pattern'ini kontrol et (xUnit, NUnit, Jest vb.)
2. Happy path + edge case + error case testleri yaz
3. Mock/stub kullanımında mevcut projedeki pattern'i takip et
4. Test isimlerini Should_ExpectedBehavior_When_Condition formatında yaz/pr — Pull Request Açıklaması:
# Pull Request Oluştur
GitHub CLI kullanarak kapsamlı PR oluştur:
## Şablon:
### Ne Değişti
[Değişikliklerin kısa açıklaması]
### Neden
[Değişikliğin sebebi]
### Test
- [ ] Unit test eklendi/güncellendi
- [ ] Manuel test yapıldı
`gh pr create` komutunu oluşturulan açıklamayla çalıştır.
"Closes #issue-number" formatını kullan.Komutlar içinde @dosya referansı kullanabilirsin:
# Yeni Component Oluştur
@src/components/Button.tsx dosyasındaki pattern'i takip ederek
yeni bir component oluştur. Stil için Tailwind kullan.Bir komut başka bir komutu referans alabilir:
# Deploy Öncesi Kontrol
1. Önce @review.md komutunu çalıştır
2. Sonra @test.md ile testleri yaz
3. Son olarak @commit.md ile commit at- Kısa tut: 150 satırı geçmesin, context'i gereksiz şişirme
- Tek amaca odaklan: Her komut tek bir iş yapsın
- Takımla paylaş: Git'e commit'le, herkes aynı komutları kullansın
- İsimlendirme: Dosya adını açıklayıcı yap (
create-pr.md,security-audit.md) /summarizebuilt-in komutu: Uzun konuşmalarda context'i sıkıştırır
Skills, agent'a belirli bir konuda "nasıl yapılır" bilgisi verir. Rules "ne yapma/yap" der, Skills "şu adımları takip et" der. Agent başlangıçta sadece skill metadata'sını (isim + açıklama) okur, tam içeriği ancak gerektiğinde yükler — bu sayede token tasarrufu sağlanır.
| Rules | Skills | |
|---|---|---|
| Amaç | Davranış kuralları | Prosedürel bilgi |
| Yükleme | Baştan yüklenir | Lazım olunca yüklenir |
| Benzetme | "Hız limiti 120 km/h" | "Motor yağı değiştirme kılavuzu" |
| Token | Her zaman harcar | Sadece kullanınca harcar |
.cursor/skills/
├── database-migration/
│ ├── SKILL.md # Ana talimatlar (zorunlu)
│ ├── references/ # Detaylı dokümanlar
│ │ └── ef-core-guide.md
│ └── scripts/ # Çalıştırılabilir scriptler
│ └── generate-migration.sh
├── api-documentation/
│ └── SKILL.md
└── docker-setup/
├── SKILL.md
└── scripts/
└── docker-compose-gen.py
---
name: database-migration
description: >
Entity Framework Core migration oluşturma ve yönetme.
Yeni tablo eklerken, ilişki tanımlarken veya mevcut şemayı
değiştirirken bu skill'i kullan.
---
# EF Core Migration Yönetimi
## Adımlar
1. Mevcut DbContext'i ve entity'leri incele
2. Değişikliği entity class'ına uygula
3. Migration oluştur: `dotnet ef migrations add <İsim>`
4. Migration SQL'ini kontrol et: `dotnet ef migrations script`
5. Uygula: `dotnet ef database update`
## Kurallar
- Migration ismi PascalCase ve açıklayıcı olmalı
- Her migration tek bir mantıksal değişikliği kapsamalı
- Down() metodu her zaman yazılmalı (geri alınabilirlik)
- Seed data migration'da değil, ayrı seeder'da olmalı
## Referanslar
Detaylı EF Core konfigürasyonu için bkz: `references/ef-core-guide.md`Agent şu akışla çalışır:
1. Kullanıcı: "Yeni bir migration oluştur"
2. Agent: skill metadata'larını tarar
3. Agent: "database-migration" skill'inin description'ı eşleşiyor
4. Agent: SKILL.md'nin tam içeriğini yükler
5. Agent: Adımları takip ederek işi yapar
Bu yüzden description çok kritik — agent buraya bakarak karar veriyor.
- Description'ı tetikleyici yazarken: "X yaparken, Y oluştururken, Z sorulduğunda kullan" şeklinde yaz
- SKILL.md'yi kısa tut: Birkaç yüz satırı geçmesin, detayları
references/klasörüne taşı - Script ekle: Tekrar eden işler için
scripts/altına bash/python scriptleri koy - Progressive disclosure: Agent zaten akıllı, sadece bilmediği bilgiyi ver
- Tek seviye derinlik: SKILL.md → references/ arası tek link yeterli, daha derine gitme
---
name: redis-caching
description: >
Redis cache implementasyonu ve stratejileri.
Cache eklerken, cache invalidation yaparken veya
cache-aside pattern uygularken kullan.
---
# Redis Cache Stratejileri
## Cache-Aside Pattern
1. Önce cache'e bak
2. Cache'te yoksa DB'den al
3. DB sonucunu cache'e yaz
4. TTL her zaman belirle (default 5 dakika)
## Key Naming Convention
`{service}:{entity}:{id}` → Örnek: `fizbot:listing:12345`
## Invalidation Kuralları
- Write-through: Yazma işleminde cache'i güncelle
- Event-driven: RabbitMQ mesajıyla cache temizle
- TTL-based: Kritik olmayan veriler için yeterli
## Dikkat
- Cache stampede'e karşı distributed lock kullan
- Serialization için MessagePack tercih et (JSON'dan hızlı)Ana agent'ın yanında çalışan, izole context'e sahip uzman agent'lar. Büyük görevleri parçalara ayırıp paralel çalıştırmak, veya belirli bir alanda (güvenlik, test, review) uzmanlaşmış agent oluşturmak için kullanılır.
| Command | Skill | Subagent | |
|---|---|---|---|
| Ne | Prompt kısayolu | Bilgi paketi | Bağımsız agent |
| Context | Ana agent ile paylaşır | Ana agent'a yüklenir | İzole context |
| Çalışma | Senkron | Senkron | Senkron veya asenkron |
| Benzetme | Makro | Kılavuz | Takım arkadaşı |
.cursor/agents/ # Proje bazlı
~/.cursor/agents/ # Global (tüm projeler)
.cursor/agents/security-reviewer.md
---
name: security-reviewer
description: >
Güvenlik açıkları için kod incelemesi yapar.
Kod değişikliklerinden sonra veya güvenlik review istendiğinde kullan.
model: inherit
readonly: true
is_background: false
---
Sen bir güvenlik uzmanısın. Verilen kodu şu açılardan incele:
1. **Injection Açıkları:** SQL injection, command injection, XSS
2. **Authentication/Authorization:** Eksik yetkilendirme kontrolleri
3. **Veri Sızıntısı:** Hassas bilgilerin log'lanması, response'da gereksiz veri
4. **Dependency Güvenliği:** Bilinen CVE'ler
5. **Rate Limiting:** DDoS koruması
## Çıktı Formatı
Her bulgu için:
- **Seviye:** CRITICAL | HIGH | MEDIUM | LOW
- **Dosya:** Etkilenen dosya yolu
- **Açıklama:** Ne bulundu
- **Öneri:** Nasıl düzeltilmeli| Alan | Açıklama | Seçenekler |
|---|---|---|
name |
Benzersiz tanımlayıcı | kebab-case |
description |
Agent'ın ne zaman delegasyon yapacağını belirler | Kritik — iyi yaz |
model |
Hangi LLM kullanılacak | inherit, fast, veya model ID |
readonly |
Dosya yazma izni | true = sadece okuma |
is_background |
Arka planda çalışsın mı | true = asenkron |
tools |
Erişebileceği araçlar | ["Read", "Grep", "Glob", "Bash"] |
---
name: doc-generator
description: Kod değişikliklerinden sonra dökümantasyonu günceller
model: fast
readonly: false
is_background: true
---
Arka planda çalış ve şunları yap:
1. Değişen dosyaları tespit et (git diff)
2. Her public method için JSDoc/XML doc güncelle
3. README.md'yi gerekirse güncelleis_background: true olduğunda ana agent beklemeden devam eder, subagent arka planda çalışır.
Cursor 2.x ile subagent'lar kendi subagent'larını oluşturabilir:
Ana Agent
├── security-reviewer (background)
├── test-writer
│ └── coverage-checker
└── doc-generator (background)
- 2-3 ile başla: Çok fazla subagent karmaşıklık yaratır
readonly: truegüvenlik ağı: Review/audit amaçlı agent'lar dosya değiştirmesin- Tool kısıtlama: Gereksiz tool verme,
tools: ["Read", "Grep", "Glob"]yeterli olabilir - Description spesifik yaz: "Genel işler için" değil, "OAuth flow implementasyonunda kullan"
- Model seçimi önemli: Hızlı işler için
fast, karmaşık analiz içininheritveya spesifik model - Background agent'ları dikkatli kullan: Dosya çakışması riski var
1. Kullanıcı: "Bu feature'ı implement et"
2. Ana agent: Kodu yazar
3. Ana agent → test-writer subagent: "Bu kod için test yaz"
4. Ana agent → security-reviewer subagent: "Bu kodu güvenlik açısından tara" (background)
5. Test sonuçları gelince ana agent düzeltmeleri yapar
6. Security bulguları gelince raporlar
Agent'ın belirli anlardaki davranışını yakalayıp harici script çalıştırman sağlar. Formatter çalıştırma, tehlikeli komutları engelleme, düzenleme sonrası test koşma gibi işler için kullanılır.
| Olay | Ne Zaman Tetiklenir | Müdahale? |
|---|---|---|
beforeSubmitPrompt |
Prompt modele gönderilmeden önce | Bilgi amaçlı |
beforeShellExecution |
Terminal komutu çalışmadan önce | ✅ Engelleyebilir |
beforeMCPExecution |
MCP tool çağrısından önce | ✅ Engelleyebilir |
beforeReadFile |
Dosya okunmadan önce | ✅ Engelleyebilir |
afterFileEdit |
Dosya düzenlendikten sonra | ✅ Formatter çalıştırabilir |
stop |
Agent görevi tamamladığında | Bilgi amaçlı |
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": "npx prettier --write {{filePath}}",
"description": "Düzenlenen dosyayı Prettier ile formatla"
}
],
"beforeShellExecution": [
{
"command": "node .cursor/scripts/validate-command.js",
"description": "Tehlikeli komutları engelle"
}
],
"stop": [
{
"command": "osascript -e 'display notification \"Agent tamamladı!\" with title \"Cursor\"'",
"description": "macOS bildirimi göster"
}
]
}
}beforeShellExecution örneği:
{
"conversation_id": "668320d2-...",
"generation_id": "490b90b7-...",
"command": "rm -rf /important-folder",
"hook_event_name": "beforeShellExecution",
"workspace_roots": ["/Users/nejdet/projects/myapp"]
}beforeShellExecution ve beforeMCPExecution hook'larından JSON döndürerek müdahale edebilirsin:
{
"continue": false,
"permission": "deny",
"userMessage": "⚠️ Bu komut engellendi: rm -rf tehlikeli!",
"agentMessage": "Bu komutu çalıştırma iznim yok, alternatif öner."
}| Alan | Açıklama |
|---|---|
continue |
true = devam et, false = durdur |
permission |
allow, deny, ask |
userMessage |
Kullanıcıya gösterilecek mesaj |
agentMessage |
AI agent'a iletilecek mesaj |
1. Her düzenlemede formatter çalıştır:
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": "dotnet format --include {{filePath}}",
"description": ".NET dosyalarını formatla"
}
]
}
}2. Tehlikeli komutları engelle:
// .cursor/scripts/validate-command.js
const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
const blocked = ['rm -rf', 'drop database', 'docker system prune -a'];
const isBlocked = blocked.some(cmd => input.command.includes(cmd));
if (isBlocked) {
console.log(JSON.stringify({
continue: false,
permission: "deny",
userMessage: `🚫 Engellenen komut: ${input.command}`,
agentMessage: "Bu komut güvenlik politikası gereği engellenmiştir."
}));
} else {
console.log(JSON.stringify({ continue: true, permission: "allow" }));
}3. GitButler tarzı otomatik commit (stop hook):
{
"version": 1,
"hooks": {
"stop": [
{
"command": "git add -A && git commit -m 'ai: agent session completed'",
"description": "Agent bitince otomatik commit"
}
]
}
}- Güvenlik önce: Hook'lar shell komutu çalıştırır,
sudokullanma - Secret'ları hardcode etme: Environment variable veya vault kullan
- Hata toleransı: Hook crash ederse agent'ı etkileyebilir, defensive programming yap
.cursor/hooks.jsondevre dışı bırakma: Dosyayı yeniden adlandır veya sil- Cursor restart gerekli: hooks.json değişikliği sonrası Cursor'u yeniden başlat
- Rules vs Hooks: Rules context'i şekillendirir, Hooks runtime davranışını şekillendirir
my-project/
├── .cursor/
│ ├── rules/ # AI davranış kuralları
│ │ ├── coding-standards/
│ │ │ └── RULE.md
│ │ ├── dotnet-conventions/
│ │ │ └── RULE.md
│ │ └── api-patterns/
│ │ └── RULE.md
│ │
│ ├── commands/ # Slash komutları
│ │ ├── review.md
│ │ ├── commit.md
│ │ ├── test.md
│ │ └── create-pr.md
│ │
│ ├── skills/ # Uzmanlık paketleri
│ │ ├── ef-core-migration/
│ │ │ ├── SKILL.md
│ │ │ └── references/
│ │ ├── redis-caching/
│ │ │ └── SKILL.md
│ │ └── rabbitmq-messaging/
│ │ ├── SKILL.md
│ │ └── scripts/
│ │
│ ├── agents/ # Subagent'lar
│ │ ├── security-reviewer.md
│ │ ├── test-writer.md
│ │ └── doc-generator.md
│ │
│ └── hooks.json # Yaşam döngüsü hook'ları
│
├── AGENTS.md # (Opsiyonel) Basit global kurallar
└── ...
"AI'ın her zaman X yapmasını istiyorum"
→ RULE (alwaysApply: true)
"Sadece .cs dosyalarında Y kuralı uygulansın"
→ RULE (globs: ["**/*.cs"])
"Her seferinde aynı prompt'u yazıyorum"
→ COMMAND (.cursor/commands/isim.md)
"AI, Redis cache nasıl implement edilir bilsin"
→ SKILL (.cursor/skills/redis-caching/SKILL.md)
"Güvenlik taramasını paralelde yapsın"
→ SUBAGENT (.cursor/agents/security-reviewer.md)
"Her dosya düzenlemesinden sonra formatter çalışsın"
→ HOOK (afterFileEdit)
"Tehlikeli terminal komutlarını engellesin"
→ HOOK (beforeShellExecution)
- Context bütçesi yönet:
alwaysApply: truerule sayısını minimumda tut, skills zaten lazy-load yapıyor - Yeni chat başlat: Feature tamamlandığında yeni oturum aç, eski context kirliliğinden kurtul
/summarizekullan: Uzun konuşmalarda context sıkıştır- Komut + Skill zinciri:
/refactorkomutu → skill'leri referans eder → agent uygular - Hook ile CI/CD entegrasyonu:
stophook'unda test suite çalıştır, sonucu bildirim olarak al - Model seçimi: Hızlı işler için lighter model, karmaşık refactor için Claude Sonnet/Opus
@sembollerini agresif kullan:@dosya,@codebase,@Web,@docsile context zenginleştir- Takım standardizasyonu: Rules + Commands + Skills'i Git'e commit'le, onboarding'i hızlandır
- Rule'ları test et: Aynı belgeyi rule'suz ve rule'lu oluşturup kalite farkını gör
- Subagent'ları kademeli ekle: 2-3 temel subagent ile başla, ihtiyaç oldukça genişlet
Bu cheatsheet Cursor 2.x (Şubat 2026) için hazırlanmıştır. Cursor hızla gelişen bir araçtır, güncel bilgi için docs.cursor.com adresini kontrol edin.