# Kodlama ajanları için prompt nasıl yazılır?

Adres: https://agentvera.dev/blog/kodlama-ajanlari-icin-prompt-yazmak/ · Yayın: 2026-10-27

Kodlama ajanı prompt rehberi: kötü ve iyi örnekler, dosya ve kısıt vermek, önce plan istemek, işi bölmek, doğrulama komutu ve tekrar kullanılan promptlar.

**Kısaca:**

- Bir kodlama ajanına iyi prompt hedefi, başlanacak dosyaları, kısıtları ve sonucun nasıl kontrol edileceğini söyler. Belirsiz prompt belirsiz kod getirir.
- Küçük bir düzeltmeden büyük her iş için önce plan iste, işi inceleyebileceğin adımlara böl ve ajana işin bittiğini hangi komutun kanıtlayacağını söyle.
- Tekrarladığın kurallar CLAUDE.md, AGENTS.md ya da GEMINI.md’ye, tekrarladığın iş akışları skill’lere veya özel komutlara gider; böylece her prompt kısa kalır.

**Bir yapay zekâ kodlama ajanına yazılan iyi prompt dört şey söyler: ne istediğini, nereden başlanacağını, neyin değişmemesi gerektiğini ve işin işe yaradığının nasıl anlaşılacağını.** Kötü sonuçların çoğu yanlış kelimelerden değil, bunlardan birinin eksik olmasından gelir. Ajan kodunu okuyabilir, komut çalıştırabilir ve dosya düzenleyebilir; promptun görevi bu işi doğru yöne çevirmek ve ona bir bitiş çizgisi vermek.

Bu rehber kötü ve iyi promptları yan yana gösteriyor, sonra bağlam vermeyi, planı, işi bölmeyi, doğrulamayı ve tekrar kullandığın promptları nerede tutacağını anlatıyor. Örnekler Claude Code ve Codex CLI ile, ama alışkanlıklar Gemini CLI ve diğer her [kodlama ajanı](/sozluk/kodlama-ajani/ "Kodlama ajanı nedir") için geçerli.

## Ajana prompt yazmak sohbet botuna yazmaktan neden farklı?

Bir sohbet botunun elinde yalnızca senin mesajın var. Bir kodlama ajanının elinde bütün depon, bir kabuk ve bir döngü var: dosya okur, bir değişiklik yapar, bir şey çalıştırır, sonuca bakar ve yeniden dener. Bu, promptun ne yapması gerektiğini değiştirir:

- **Kod yapıştırman gerekmez.** Dosyaları göster, ajan okusun.
- **Sınır koyman gerekir.** Her şeyi düzenleyebilen bir ajan, kastetmediğin yerleri de düzenleyebilir.
- **Bir durma kuralı gerekir.** Yoksa işin yeterince iyi olduğuna ajan kendisi karar verir ve onun çıtası seninkiyle aynı olmayabilir.

Ajanın okuduğu her ek dosya [bağlam penceresini](/sozluk/baglam-penceresi/ "Bağlam penceresi nedir") de doldurur. Odaklı bir prompt ajanı odakta, oturumu da ucuz tutar.

## Kötü prompt ve iyi prompt

Tipik bir ilk deneme şöyle:

```text
fix the login bug
```

Ajan hangi hatanın kastedildiğini, nerede olduğunu ve “düzeldi”nin ne demek olduğunu tahmin etmek zorunda. Yanlış dosyayı değiştirebilir, sağlam bir fonksiyonu yeniden yazabilir ya da hatayı yakalayıp susturarak belirtiyi “düzeltebilir”.

Aynı istek bir ajan için yazılınca:

```text
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.

Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.

Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.
```

Daha uzun, ama her satır ajanı bir tahminden kurtarıyor. Promptu Türkçe de yazabilirsin; önemli olan içerik. Her parçanın işi şu:

| Parça | Örnek | Neden işe yarar |
| --- | --- | --- |
| Belirti | “doğru parolayla bile 401 dönüyor” | Ajan neyi yeniden üreteceğini bilir |
| Biliyorsan neden | “e-postaları yazıldığı gibi saklıyor” | Uzun bir aramayı atlatır |
| Başlanacak dosyalar | `src/auth/login.ts` | Daha az okuma, daha az yanlış tahmin |
| Kısıtlar | “veritabanı şemasını değiştirme” | Değişikliği küçük ve güvenli tutar |
| Bitti ölçütü | adı verilmiş bir test ve `pnpm test` | Ajanın kontrol edebileceği bir bitiş çizgisi |

Nedeni her zaman bilmezsin. Sorun değil: bunu söyle ve ajandan düzeltmeden önce nedeni bulmasını iste. “X neden oluyor, bul ve hiçbir şeyi değiştirmeden önce açıkla” tek başına güçlü bir prompttur.

## Deneme değil, bağlam ver

En faydalı bağlam somut ve kontrol edilebilir olandır. Kabaca değer sırasıyla:

1. **Dosya yolları ve semboller.** `src/billing/invoice.ts`, `calculateTax()`. Claude Code’da ve Codex’te `@` yazıp bir dosya seçerek ekleyebilirsin.
2. **Hata çıktısı.** Stack trace’i ya da kalan testin çıktısını özetini değil, aynen yapıştır.
3. **Kısıtlar.** Kullandığın ya da kullanmadığın kütüphaneler, dokunulmayacak klasörler, geriye dönük uyumlu kalması gereken API’ler.
4. **Kod tabanındaki örnekler.** “`src/routes/users.ts`’deki kalıbı izle”, o kalıbı anlatan bir paragraftan iyidir.
5. **Neden.** Kullanıcıya dönük hedefi anlatan tek bir cümle, ajanın senin yazmadığın konularda makul seçimler yapmasına yardım eder.

Dışarıda bırakılacaklar: projenin uzun geçmişi, ilgisiz kod hakkındaki görüşlerin ve her görevde geçerli talimatlar. Sonuncular, aşağıda anlatılan proje dosyasına aittir.

Arayüz işlerinde ekran görüntüsü işe yarar. Claude Code da Codex de görsel kabul eder; Codex ayrıca komut satırında `codex --image path/to/file.png` alır.

## Önce plan iste

Küçük bir düzeltmeden büyük her işte düşünmeyi yapmaktan ayır. Ajandan kodu okuyup bir plan önermesini iste, planı incele, sonra uygulamasına izin ver.

- **Claude Code:** durum çubuğunda plan modu görünene kadar Shift+Tab’a bas, tek bir prompttan önce `/plan` yaz ya da `claude --permission-mode plan` ile başlat. Plan modunda Claude okur ve önerir ama düzenlemez. Ayrıntılar [Claude Code plan modu](/blog/claude-code-plan-modu/ "Claude Code plan modu") yazısında.
- **Codex CLI:** `/plan`, Codex’ten uygulamadan önce plan yapmasını ister. `/permissions` ile Read Only’ye geçip salt okunur bir oturum da açabilirsin.
- **Her ajan:** kelimelerle söyle: “Henüz hiçbir şeyi düzenleme. İlgili dosyaları oku ve değiştireceğin dosyalarla birlikte numaralı bir plan ver.”

İyi çalışan bir plan promptu:

```text
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.
```

Planı okumak bir dakika sürer ve pahalı hataları yakalar: yanlış klasör, istemediğin yeni bir bağımlılık, beklemediğin bir migration. Plan yanlışsa düz bir dille düzelt (“yeni bir ayrıştırıcı yerine mevcut `toRows()` yardımcısını kullan”) ve güncellenmiş plan iste.

## Büyük işleri adımlara böl

Ajanlar tek oturuşta inceleyebileceğin işlerde en iyisini çıkarır. “Faturalama sistemini kur” gibi bir prompt, kontrol etmesi de geri alması da zor büyük bir fark üretir. İşi böl:

```text
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.
```

Sonra 2. adım API, 3. adım arayüz, 4. adım e-postalar. Her adımdan sonra incelersin, commit edersin ve sıradakine geçersin. Bunu işletmenin iki alışkanlığı var:

- **Adımlar arasında commit et.** Temiz bir commit bir kontrol noktasıdır. 3. adım bozulursa karışık bir farkı çözmeye uğraşmak yerine 2. adımın sonuna dönersin. Seçenekler [Claude Code değişikliklerini geri alma](/blog/claude-code-degisiklikleri-geri-alma/ "Claude Code değişikliklerini geri alma") yazısında.
- **İlgisiz iş için temiz bağlam.** Konu değiştirirken Claude Code’da `/clear`, Codex’te `/new` kullan. Eski bağlam token harcar ve ajanı önceki göreve geri çeker.

Birbirinden bağımsız adımlar paralel de çalışabilir; her ajan kendi [git worktree’sinde](/blog/git-worktree-paralel-gelistirme/ "Git worktree ile paralel geliştirme") çalışırsa birbirlerinin dosyalarının üzerine yazmazlar.

## Ajana nasıl doğrulayacağını söyle

“Çalışır hale getir” dediğinde çalışmanın ne demek olduğuna ajan karar verir. Bir doğrulama talimatı bu kararı sana geri verir. İyileri, sonucu net olan komutlardır:

```text
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
  empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.
```

Çıtayı yükselten birkaç kalıp:

- **Önce test.** “Hatayı yeniden üreten bir test yaz, çalıştır ve kaldığını göster. Sonra test geçene kadar kodu düzelt.” Bu, testin gerçekten hatayı kapsadığını kanıtlar. Fazlası [yapay zekâ ile test yazmak](/blog/yapay-zeka-ile-test-yazmak/ "Yapay zekâ ile test yazmak") yazısında.
- **İddia değil kanıt iste.** “Çıktıyı yapıştır”, “çalıştığını onayla”dan daha zor taklit edilir.
- **Neyin bozulmaması gerektiğini söyle.** “`tests/auth/` içindeki mevcut testler geçmeye devam etmeli.”
- **Kestirmeleri yasakla.** “Testleri atlama ya da silme, tip hatalarını susturmak için `any` ekleme.” Bir kontrolü geçirme baskısındaki ajanlar bazen bu yollara sapar.

Sonra farkı oku. Değişikliği ikinci bir modelin incelemesi çok şey yakalar; bkz. [yapay zekâ ile kod incelemesi](/blog/yapay-zeka-kod-incelemesi/ "Yapay zekâ kod incelemesi").

## Ters giden promptlar ve düzeltmeleri

| Prompt | Genelde ne olur | Daha iyisi |
| --- | --- | --- |
| “Bu dosyayı temizle” | Büyük bir yeniden yazım, yeniden adlandırılmış fonksiyonlar, başka yerlerde kırılan importlar | “`parse.ts`’deki ayrıştırmayı kendi fonksiyonuna çıkar; dışa açık API değişmesin” |
| “Test ekle” | Kodun yaptığını yaptığını doğrulayan yüzeysel testler | “Boş girdi, 10 MB dosya ve bozuk başlık için test ekle; 40. satırdaki kontrolü kaldırırsam her biri kalmalı” |
| “Hızlandır” | Rastgele mikro optimizasyonlar | “`/search` uç noktası 10 bin satırda 2 sn sürüyor. Profille, zamanın nereye gittiğini söyle, sonra bir düzeltme öner” |
| “En iyi pratikleri kullan” | Modelin o an en iyi saydığı şey | Pratiğin adını ver: “`src/db/users.ts`’deki repository kalıbını kullan” |
| Birbiriyle ilgisiz on düzeltmelik liste | Yarısı yapılmış, altıncı maddede bağlam dolmuş | Prompt başına bir görev ya da on görev bir kuyrukta |

## Promptları tekrar kullanılır yap

Aynı talimatı her oturumda yazıyorsan onu promptlarından çıkar.

### Proje kuralları: CLAUDE.md, AGENTS.md, GEMINI.md

Her ajan oturum başında bir proje talimat dosyası okur: Claude Code için `CLAUDE.md`, Codex (ve başka birçok ajan) için `AGENTS.md`, Gemini CLI için `GEMINI.md`. Komutları ve kuralları buraya kısa ve net yaz:

```markdown
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck

## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.
```

Artık “bitti demeden önce testleri çalıştır” sen yazmadan her promptun parçası. Claude Code, Codex ve Gemini CLI’da `/init` ilk taslağı oluşturur. Birkaç ajan için tek bir kural seti tutmayı [CLAUDE.md nasıl yazılır](/blog/claude-md-nasil-yazilir/ "CLAUDE.md nasıl yazılır") yazısı anlatıyor.

### Tekrarlanan iş akışları: skill’ler ve özel komutlar

Ara sıra tekrarladığın bir iş için, örneğin bir sürüm çıkarmak, bir migration ya da bir inceleme kontrol listesi, bir kez skill ya da özel komut olarak yaz ve adıyla çağır.

**Claude Code** skill kullanır: içinde `SKILL.md` dosyası olan bir klasör; proje için `.claude/skills/<ad>/`, kendin için `~/.claude/skills/<ad>/`. Klasör adı bir komut olur ve `$ARGUMENTS`, komuttan sonra yazdığın her şeyi alır:

```markdown
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.
```

Artık `/fix-issue 123` bütün promptu çalıştırır. `.claude/commands/` içindeki eski Markdown dosyaları aynı şekilde çalışmaya devam eder, ama Anthropic’in belgeleri yeni işler için skill’i öneriyor, çünkü bir skill klasörü betik ve referans dosyaları da tutabilir. İsteğin bir skill’in açıklamasıyla eşleşirse Claude onu kendisi de yükler. Fazlası [Claude Code skill nedir](/blog/claude-code-skill-nedir/ "Claude Code skill nedir") yazısında.

**Codex** skill’leri projede `.agents/skills`, kendin için `~/.codex/skills` klasöründen, aynı `SKILL.md` biçiminde okur.

**Gemini CLI** `.gemini/commands/` (proje) ya da `~/.gemini/commands/` (kullanıcı) içinde TOML özel komutları kullanır. `{{args}}` komuttan sonra yazdığın metinle değiştirilir; alt klasörler ad alanı olur, yani `git/commit.toml` `/git:commit` olarak çağrılır:

```toml
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""
```

Kullanışlı bir kural: her zaman geçerli kurallar proje dosyasına, ara sıra kullandığın iş akışları skill’lere gider; promptun kendisi yalnızca bugünkü göreve özgü olanı taşır.

## Kopyalayabileceğin bir prompt şablonu

```text
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>
```

Her satır her seferinde gerekmez. Bir yazım hatası için “Goal” yeter. Yeni bir özellik için hepsini doldur.

## AgentVera’da ajanlara prompt yazmak

AgentVera; Claude Code, Codex, Gemini CLI ve diğer CLI ajanlarını gerçek terminallerde yan yana çalıştıran, macOS, Windows ve Linux için bir masaüstü uygulaması. Promptlar aynı; birkaç özellik tekrar eden kısımları üstlenir:

- **[Verify](/ozellikler/verify/ "AgentVera Verify"):** mesajına yazdığın bitti ölçütleri kabul kriterleri olarak çıkarılır. Ajan turunu bitirince ayrı bir doğrulayıcı farka bakar, izin verilen test komutlarını çalıştırır ve her kriteri kanıtıyla geçti ya da kaldı diye işaretler. Dosya düzenleyemez. Verify Pro ve Team planlarında.
- **[Kod incelemesi](/ozellikler/kod-incelemesi/ "Kod incelemesi"):** tur bitince ajanın yazdığını ikinci bir Claude modeli inceler; bulgular doğrudan ajana geri gidebilir.
- **[Ajana gönder](/ozellikler/ajana-gonder/ "Ajana gönder"):** bir terminal hatasını, farkı, logu ya da bir kod satırını kopyalayıp promptuna yapıştırmak yerine ⌘⇧L ile bir ajana gönder.
- **[Skill galerisi](/ozellikler/skill-galerisi/ "Skill galerisi"):** Claude Code ve Codex skill’lerini tek listede oluştur, düzenle, aç ya da kapat; paylaşılan skill’leri güvenlik taramasından sonra kur.
- **[Çalışma alanı](/ozellikler/calisma-alani/ "Çalışma alanı"):** proje başına bir ajan ızgarası; böldüğün her adıma kendi ajanını ve worktree’sini verebilirsin.

[AgentVera’yı indir](/indir/ "AgentVera’yı indir") ve bir sonraki promptunu bunlarla birlikte dene.

## Toparlarsak

Promptları yeni katılmış yetenekli bir iş arkadaşına yazılan bir iş kaydı gibi yaz: hedef, nereye bakılacağı, neye dokunulmayacağı ve sonucu nasıl değerlendireceğin. İş büyükse plan iste, inceleyebileceğin adımlara böl ve her zaman işin bittiğini kanıtlayan bir komut ver. Tekrarladıklarını `CLAUDE.md`, `AGENTS.md` ya da bir skill’e taşı. Ajan bir veritabanına dokunduğunda aynı alışkanlıklar daha da önemli; [yapay zekâ ile SQL yazmak](/blog/yapay-zeka-ile-sql-yazmak/ "Yapay zekâ ile SQL yazmak") yazısı bunları şemalara ve migration’lara uyguluyor.

## Sık sorulanlar

**Bir kodlama ajanına yazılan prompt ne kadar uzun olmalı?** Hedefi, başlanacak dosyaları, kısıtları ve bitti ölçütünü söylemeye yetecek kadar, daha fazla değil. Küçük bir düzeltme için iki üç satır yeter. Bir özellik için genelde kısa bir paragraf ve bir liste. Her görev için geçerli olan arka plan bilgisi her prompta değil, CLAUDE.md ya da AGENTS.md’ye yazılır.

**Kod yazmadan önce ajandan plan istemeli miyim?** Birkaç dosyadan fazlasına dokunan ya da tam tarif edemediğin her iş için evet. Claude Code’da plan modunu (Shift+Tab ya da /plan), Codex’te /plan’ı kullan. Planı oku, düzelt, sonra ajanın uygulamasına izin ver. Tek satırlık bir düzeltmede plan gereksiz yük olur.

**“Sen kıdemli bir yazılımcısın” gibi prompt hileleri kodlama ajanlarına yarar mı?** Somut bilgiden çok daha az. Bir rol cümlesi pek bir şeye mal olmaz, ama ajan başlanacak dosyadan, testleri çalıştıran komuttan ve beklediğin davranıştan çok daha fazlasını kazanır. Kelimelerini görevle ilgili gerçeklere harca.

**Tekrar tekrar kullandığım promptları nerede tutmalıyım?** Proje kuralları CLAUDE.md (Claude Code), AGENTS.md (Codex ve diğer ajanlar) ya da GEMINI.md (Gemini CLI) dosyasına gider. Tekrarlanan iş akışları skill olur: Claude Code’da .claude/skills/<ad>/SKILL.md, Codex’te .agents/skills. Gemini CLI, .gemini/commands içinde TOML özel komutları kullanır.

**Kodlama ajanının bitmemiş bir işe “bitti” demesini nasıl önlerim?** Çalıştırması gereken bir kontrol ver: bir test komutu, bir build ya da bir curl isteği; çıktısını yapıştırmasını iste. Değişiklikten önce kalan, sonra geçen yeni bir test iste. Ardından farkı kendin incele ya da ikinci bir ajana inceletir.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/