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/ /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.

Kodlama ajanları için prompt nasıl yazılı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ı 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 de doldurur. Odaklı bir prompt ajanı odakta, oturumu da ucuz tutar.

Kötü prompt ve iyi prompt

Tipik bir ilk deneme şöyle:

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:

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:

Dosya yolları ve semboller. src/billing/invoice.ts, calculateTax(). Claude Code’da ve Codex’te @ yazıp bir dosya seçerek ekleyebilirsin.
Hata çıktısı. Stack trace’i ya da kalan testin çıktısını özetini değil, aynen yapıştır.
Kısıtlar. Kullandığın ya da kullanmadığın kütüphaneler, dokunulmayacak klasörler, geriye dönük uyumlu kalması gereken API’ler.
Kod tabanındaki örnekler. “src/routes/users.ts’deki kalıbı izle”, o kalıbı anlatan bir paragraftan iyidir.
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 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:

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:

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 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 ç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:

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 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.

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:

## 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 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:

---
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 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:

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

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: 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: tur bitince ajanın yazdığını ikinci bir Claude modeli inceler; bulgular doğrudan ajana geri gidebilir.
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: 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ı: proje başına bir ajan ızgarası; böldüğün her adıma kendi ajanını ve worktree’sini verebilirsin.

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 yazısı bunları şemalara ve migration’lara uyguluyor.