Bir kodlama ajanıyla geliştirin

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.

• Başlamadan önce
• Terminal temelleri
• Web yerel kurulumu

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.

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

• Kurulumu sizin için bir ajana yaptırın

• agent-setup.md — kiti bir ajanla ayağa kaldırın ve dağıtın
• pick-a-style.md — tüm ürüne bir tasarım stili uygulayın
• new-landing-page.md — kit bloklarından bir pazarlama sayfası iskeleti kurun
• new-app-screen.md — çalışma alanı uygulama kabuğu içine bir ekran ekleyin
• restyle-product.md — mevcut bir sayfayı kit belirteçleriyle yeniden temalandırın
• ui-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 odaklı kurulumu izleyin

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.

• Doğrulama kapıları ve test paketi

• İ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_ veya EXPO_PUBLIC_ öneki taşımıyor ve hiçbir anahtar bir rapora veya commit'e yazılmadı.
• Kullanıcıya ait her okuma ve yazma workspaceId ile 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.