For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/web/agents.md (or send Accept: text/markdown).
Bir kodlama ajanıyla geliştirin
Görevleri bir kodlama ajanına verin: okuduğu dosyalar, yapıştırmaya hazır istem kütüphanesi, katılımsız kurulum ve kontrolü sizde tutan inceleme.
Başlangıç seviyesinde izlenecek yol
Önkoşullar: Aşağıdaki iki başlangıç kılavuzunu okuyun, Web yerel kurulumunu tamamlayın ve bu depoyu düzenleyicinizde kökünden açın. Kodlama ajanı, projenizi okuyan, dosyaları düzenleyen ve komutları çalıştıran bir yapay zeka aracıdır — Cursor, Claude Code, Devin veya benzeri bir asistan. Bu sayfadaki her şey hangisini kullanırsanız kullanın geçerlidir.
Kısa terimler: İstem, ajana yapıştırdığınız talimat metnidir. Diff, ajanın önerdiği dosya değişikliklerinin listesidir. Depo kökü, package.json'u içeren en üst klasördür — ajan her zaman oradan başlamalıdır.
1. Depo kökündeki prompts/ klasörünü açın ve görevinize en yakın istemi kopyalayın. new-landing-page.md iyi bir ilk denemedir.
2. İstemi ajanınıza yapıştırın ve <placeholders> yerlerini doldurun: istediğiniz rota, sayfanın veya ekranın ne yapması gerektiği, kimlerin kullanabileceği ve başarının nasıl göründüğü. Ardından şu satırı ekleyin: Koda dokunmadan önce llms.txt'yi, ardından AGENTS.md'yi, ardından .ai/PROJECT_CONTEXT.md'yi okuyun.
3. Ajanın düzenlemeye başlamadan önce değiştireceği dosyaları ve çalıştıracağı kontrolleri listelemesini isteyin. Bittiğinde diff'i gözden geçirin — ürününüzdeki gerçek değişiklikleri onaylıyorsunuz.
4. Yayınlama, dağıtma ve ücretli sağlayıcı çağrıları asla bir görev isteminin parçası değildir. Bunları açıkça onayladığınız ayrı adımlar olarak tutun.
Ajanınızın okuduğu dosyalar
Depo, yalnızca insanlar için değil ajanlar için de yazılmış küçük bir dosya yığınıyla gelir. Bu bağlamı asla elle yapıştırmazsınız — ajanı llms.txt'ye yönlendirin, gerisini kendisi okur.
Okuma sırası önemlidir: llms.txt haritadır, AGENTS.md sınırları belirler ve .ai/PROJECT_CONTEXT.md önceki oturumların öğrendiklerini taşır. Sınırları atlayan bir ajan, yayınlayamayacağınız kod üretir.
| Dosya | Ajana ne sağlar |
|---|---|
| `llms.txt` | Depo giriş haritası — okunmaya değer her belge ve güvenlik protokolleri, okuma sırasıyla |
| `AGENTS.md` | Vazgeçilemez sınırlar: siz daha fazlasını onaylayana kadar yalnızca yerel çalışma, workspaceId kapsamı, yalnızca sunucuda kalan sırlar |
| `.ai/PROJECT_CONTEXT.md` | Oturumlar arası bellek — son zamanlarda ne ve neden değişti; kod değişikliklerinden önce okunur |
| `.ai/` ayna belgeleri | Önemli dosyaların yanında eşleşen bir .ai/<path>.md notu; dosya başına kararları ve açık konuları kaydeder |
| `docs/agent-setup.md` | Katılımsız runbook — her birinin ardından doğrulama denetim noktası bulunan kurulum, geçiş ve dağıtım aşamaları |
| `prompts/` | Sahiplerin en sık istediği işler için yapıştırmaya hazır görev istemleri |
| `docs/agent-security.md` | Kabul kontrol listesi — kimlik doğrulama, çalışma alanı ve RLS kontrolleri, gizlenmiş günlükler, dağıtım kanıtı |
| `.env.example` | Eksiksiz ortam envanteri — ajan bu dosyada bulunmayan bir değişken adını asla uydurmaz |
İstem kütüphanesi
prompts/README.md dizindir. Her dosya eksiksiz bir brifingtir: yapıştırın, <placeholders> yerlerini doldurun ve kitin kuralları — sabit kodlu renkler yerine tasarım belirteçleri, uydurulmuş desenler yerine kit blokları — onunla birlikte gelir.
Sıfırdan çalışır duruma giden yol için bunun yerine prompts/agent-setup.md'yi yapıştırın — bir sonraki bölümde anlatılan katılımsız kurulumu yürütür.
agent-setup.md— kiti bir ajanla ayağa kaldırın ve dağıtınpick-a-style.md— tüm ürüne bir tasarım stili uygulayınnew-landing-page.md— kit bloklarından bir pazarlama sayfası iskeleti kurunnew-app-screen.md— çalışma alanı uygulama kabuğu içine bir ekran ekleyinrestyle-product.md— mevcut bir sayfayı kit belirteçleriyle yeniden temalandırınui-audit.md— bir rotada görsel ve erişilebilirlik denetimini çalıştırın
Kurulumu ve dağıtımı ajana bırakın
Kit büyük ölçüde kendini kurabilir. prompts/agent-setup.md'yi yapıştırmak, ajanın docs/agent-setup.md'yi — ürünle gelen runbook'u — aşama aşama yürütmesini sağlar: ön kontroller, ortam dosyaları, kurulum, veritabanı başlatma, geçişler, uygulama başlatma ve isteğe bağlı olarak bir VPS dağıtımı. Her aşamadan sonra o aşamanın doğrulama denetim noktasını çalıştırır ve iddia değil, gerçek çıktı bildirir.
İki yardımcı bunu güvenli tutar. scripts/setup-env.mjs, env dosyalarını .env.example'dan önyükler: yalnızca eksik dosyaları oluşturur, yalnızca eksik veya yer tutucu sırları üretir ve --check modu yazmadan doğrular. docker-compose.dev.yml tamamen kapsayıcılı bir geliştirme ortamıdır — Postgres artı bir Node 22 geliştirme kapsayıcısı — bu nedenle ajanın bilgisayarınızda Node.js kurulu olmasına gerek yoktur.
Hangi depoyu aldığınız burada önemlidir. Web deposu ve Tüm Platformlar monorepo'su runbook'u, compose dosyalarını, scripts/setup-env.mjs'yi ve prompts/'u içerir. Bağımsız Mobile ve Desktop depoları platforma özel bir llms.txt, AGENTS.md, .ai/ ayna belgeleri ve docs/agent-security.md dahil seçilmiş belgeler sunar — ancak kurulum runbook'unu veya compose dosyalarını sunmaz, çünkü bu uygulamaların konuştuğu arka uç Web deposunda yaşar.
Ajan oturumlar arasında nasıl hatırlıyor
Ajanların oturumlar arasında belleği yoktur — .ai/ klasörü bellektir. .ai/PROJECT_CONTEXT.md, son zamanlarda neyin ve neden değiştiğini kaydeder. Yanında, .ai/apps/web/src/reports.md gibi bir ayna belgesi, apps/web/src/reports.ts'nin arkasındaki ve tek başına kodun göstermediği kararları açıklar.
Sözleşme basittir: bir dosyayı düzenlemeden önce aynasını okuyun ve değişiklik yerleştiğinde aynayı güncelleyin. Open Threads girdileri bitmemiş işleri kaydeder, böylece sonraki oturum baştan başlamak yerine kaldığı yerden devam eder. Güncelliğini yitirmiş bir ayna hiç olmamasından daha kötüdür — ajanın diff'ini incelerken, değişen dosyaların aynalarının da onunla birlikte güncellendiğini kontrol edin.
Çalışan uygulamanın kendi ajan yüzeyi
Dağıtılmış ürününüz de ajanlara yanıt verir — bu uç noktalar yalnızca depoda değil, çalışan uygulamada da bulunur.
GET /llms.txt— uygulama kendi llmstxt.org dizinini sunar: kılavuzlar, genel sayfalar ve genel uç noktalar, mutlak URL'lerle.POST /api/mcp— uygulamanın araçlarını açan durum bilgisiz bir MCP uç noktası.sk_API anahtarlarını yalnızca bearer belirteç olarak kabul eder — tarayıcı çerez oturumları asla geçerli olmaz. Anahtarları Ayarlar → Geliştiriciler altında oluşturun.GET /api/v1/openapi— genel REST API'nin OpenAPI belirtimi; istemci üreteçleri ve ajan araçları için.GET /api/health— yük dengeleyicilerin ve çalışma süresi kontrollerinin çağırdığı canlılık ve bağımlılık yoklaması; sağlayıcı yapılandırma türlerini bildirir, asla sır bildirmez./status— her alt sistemin durumunu bildiren, insanların okuyabileceği bir sayfa.
Ajanın işini dürüstçe gözden geçirin
Tamamlanmış bir görev özet değil, kanıttır. Ajanın çalışmasını saklamadan önce, docs/agent-security.md'nin bir dağıtımı denetlediği şekilde denetleyin:
Bir şeyler yanlışsa diff'i geri gönderin — ajan, başarısız kontrolü adlandırdığınızda kendi işini en hızlı şekilde düzeltir. Tek başına asla denememesi gereken bir şey için bunu bir kez açıkça söyleyin; sınır oturumun geri kalanında geçerli kalır.
- İddia ettiği testleri gerçekten çalıştırdı — sonuç değil, komutu ve çıktısını isteyin.
- Sırlar yalnızca sunucuda kaldı — hiçbir yeni değer
NEXT_PUBLIC_veyaEXPO_PUBLIC_öneki taşımıyor ve hiçbir anahtar bir rapora veya commit'e yazılmadı. - Kullanıcıya ait her okuma ve yazma
workspaceIdile kapsamlandı — hiçbir sorgu tarayıcının gönderdiği bir kimliğe güvenmiyor. - Değişen her dosyanın
.ai/aynası kodla birlikte ilerledi. - Yayınlama, dağıtma ve ücretli sağlayıcı çağrıları sizin onayladığınız ayrı adımlar olarak kaldı — ajan asla kendi kendine birleştirmedi, göndermedi veya dağıtmadı.
- Bir adım iki kez başarısız olursa, etrafından dolaşmak yerine durup başarısız komutu bildirdi.