Bu repository için kontrollü bir multi-agent geliştirme altyapısı oluştur.
Amacımız, güçlü bir planner/architect agent’ın işleri küçük görevlere bölmesi; frontend, backend, test ve review agent’larının ise yalnızca kendi uzmanlık alanlarında çalışmasıdır.
Önce repository’yi analiz et. Kullanılan teknoloji, paket yöneticisi, test sistemi, lint ve typecheck komutlarını mevcut dosyalardan tespit et. Tahmin yürütme. Bulamadığın bilgiler için güvenli ve genel varsayımlar kullan, ancak bunları açıkça belirt.
Aşağıdaki dosya ve klasörleri oluştur:
.claude/
agents/
architect.md
frontend-worker.md
backend-worker.md
test-worker.md
reviewer.md
integrator.md
skills/
project-conventions/
SKILL.md
CLAUDE.md
docs/
architecture.md
decisions.md
field-guide.md
agent-workflow.md
tasks/
task.schema.json
example-task.json
scripts/
create-agent-worktrees.sh
remove-agent-worktrees.sh
- Mevcut uygulama kodunu değiştirme.
- Dependency ekleme.
- Package manager değiştirme.
- Mevcut config dosyalarını değiştirme.
- Yalnızca yukarıda belirtilen agent altyapısı dosyalarını oluştur.
- Repository’de var olan komutları ve klasörleri referans al.
- Yazdığın bütün Markdown dosyaları doğrudan kullanılabilir ve açık olmalı.
- Agent’ların görev sınırlarını kesin olarak tanımla.
- Agent’ların gereksiz refactor yapmasını yasakla.
- Her worker yalnızca kendisine verilen görev ve izin verilen dosyalar üzerinde çalışmalı.
- Belirsiz durumda agent kod yazmak yerine
BLOCKED
sonucu döndürmeli. - Worker’lar doğrudan ana branch’e merge veya push yapmamalı.
- Reviewer mümkün olduğunca salt okunur çalışmalı.
- Integrator yalnızca testleri geçen ve review onayı alan görevleri birleştirmeli.
Repository’nin agent çalışma anayasası olacak şekilde hazırla.
Şunları içersin:
- Projenin tespit edilen teknoloji yığını
- Paket yöneticisi
- Geliştirme, lint, test, typecheck ve build komutları
- Kodlama standartları
- Dosya ve klasör organizasyonu
- Yasaklanan davranışlar
- Agent görev akışı
PASS
,REQUEST_CHANGES
,BLOCKED
veFAILED
durumlarının anlamları- Her değişiklikten sonra çalıştırılması gereken doğrulamalar
- Güvenlik ve gizli bilgi kuralları
- Commit mesajı standardı
- Agent’ların hangi belgeleri önce okuması gerektiği
Repository’de bulunmayan bir komutu gerçekmiş gibi yazma. Bulunmayan komutların yanına PROJECT-SPECIFIC COMMAND REQUIRED
notu ekle.
Her agent dosyası Claude Code subagent formatında YAML frontmatter içersin.
Sorumlulukları:
- Repository ve specification analizi
- Mimari plan oluşturma
- İşi küçük ve bağımsız görevlere ayırma
- Görev bağımlılıklarını belirleme
- Her görev için izin verilen dosya sınırlarını belirleme
- Acceptance criteria üretme
- Riskleri ve belirsizlikleri tespit etme
Kurallar:
- Uygulama kodu yazmamalı.
- Gereksiz mimari değişiklik önermemeli.
- Her görevi mümkünse 1–5 dosyalık değişiklikle sınırlamalı.
- Aynı dosyanın birden fazla paralel worker tarafından değiştirilmesini engellemeli.
- Çıktıyı
tasks/task.schema.json
ile uyumlu JSON olarak üretebilmeli.
Sorumlulukları:
- UI, component, hook, client state ve frontend entegrasyonları
- Mevcut tasarım ve mimari kalıplarına uyum
- İlgili frontend testlerinin çalıştırılması
Kurallar:
- Yalnızca görevde izin verilen dosyaları değiştirmeli.
- Backend, CI veya altyapı değişiklikleri yapmamalı.
- İstenmeyen refactor yapmamalı.
- Yeni dependency eklememeli.
- İş sonunda değişen dosyaları, test sonuçlarını ve riskleri raporlamalı.
Sorumlulukları:
- API, server, veri erişimi ve backend iş mantığı
- Mevcut backend mimarisine uyum
- İlgili testlerin çalıştırılması
Kurallar frontend worker ile aynı katılıkta olmalı.
Repository’de backend bulunmuyorsa bu agent dosyasında açıkça şunu belirt:
This repository currently appears to have no backend implementation. Use this agent only for backend-related packages or services added outside the current application scope.
Sorumlulukları:
- Unit, integration ve mevcutsa end-to-end testleri
- Edge case analizi
- Regression testleri
- Test fixture ve mock düzenlemeleri
Kurallar:
- Production davranışını yalnızca testi kolaylaştırmak için değiştirmemeli.
- Test geçsin diye assertion zayıflatmamalı.
- Mevcut test standardını takip etmeli.
- Flaky testleri gizlememeli.
- Test kapsamındaki eksikleri raporlamalı.
Sorumlulukları:
- Specification uyumu
- Kod doğruluğu
- Type safety
- Test yeterliliği
- Güvenlik
- Performans
- Gereksiz değişiklik
- Dosya sınırı ihlali
- Mimari uyum
Mümkünse yalnızca read, grep, glob ve test komutlarına erişsin.
Kod yazmamalı.
Çıktısı kesin olarak şu formatta olmalı:
RESULT: PASS | REQUEST_CHANGES | BLOCKED
SUMMARY:
...
FINDINGS:
- severity: critical | high | medium | low
file:
line:
issue:
recommendation:
VERIFICATION:
- command:
result:
RISKS:
...
Sorumlulukları:
- Worker commit’lerini değerlendirmek
- Bağımlılık sırasına göre birleştirmek
- Merge conflict’lerini semantik olarak çözmek
- Birleşmiş branch üzerinde lint, test, typecheck ve build çalıştırmak
- Başarısız entegrasyonda değişikliği geri almak veya
BLOCKED
döndürmek
Kurallar:
- Review onayı olmayan değişikliği birleştirmemeli.
- Testleri atlamamalı.
- Conflict çözerken özellik kaybına neden olmamalı.
- Ana branch’e otomatik push yapmamalı.
- Force push yapmamalı.
.claude/skills/project-conventions/SKILL.md
dosyasında repository’ye özel ortak kuralları tanımla.
Şunları kapsasın:
- İsimlendirme
- Import düzeni
- TypeScript kuralları
- Component ve hook kuralları
- State management yaklaşımı
- API çağrı yaklaşımı
- Error ve state yaklaşımı
- Test yaklaşımı
- Accessibility
- Logging
- Environment variable kullanımı
- Gizli bilgi yönetimi
- Agent raporlama formatı
Repository’de gördüğün gerçek kod örüntülerine dayan. Emin olmadığın konulara Needs project confirmation
etiketi koy.
Mevcut repository’nin kısa ve gerçekçi mimari özetini oluştur.
Şunları kapsasın:
- Uygulama türü
- Ana klasörler
- Veri akışı
- State yönetimi
- API katmanı
- Navigation veya routing
- Test yapısı
- Build ve deployment hakkında tespit edilebilen bilgiler
- Bilinen mimari sınırlar
Bilgi uydurma. Tespit edilemeyen alanları açıkça belirt.
Architecture Decision Record benzeri basit bir format oluştur.
Örnek şablon:
## ADR-001: Karar başlığı
- Status:
- Date:
- Context:
- Decision:
- Consequences:
- Alternatives considered:
İlk karar olarak multi-agent çalışma modelinin neden worktree, dar görev sınırı ve bağımsız review kullandığını açıkla.
Agent’ların proje içinde keşfettiği tekrar kullanılabilir bilgileri yazacağı bir yapı oluştur.
Bölümler:
- Architecture notes
- Development commands
- Testing notes
- Known pitfalls
- Security notes
- Performance notes
- Integration notes
Dosyada agent’ların geçici görev bilgisi veya konuşma özeti saklamaması gerektiğini belirt.
Başından sonuna çalışma akışını yaz:
- Specification alınması
- Architect analizi
- Görev JSON’larının üretilmesi
- Worktree oluşturulması
- Worker’ın görevi uygulaması
- Testlerin çalıştırılması
- Reviewer kontrolü
- Değişiklik talebi veya onay
- Integrator merge işlemi
- Birleşmiş kodun doğrulanması
- Field guide ve decisions güncellemesi
- Final rapor
Ayrıca paralel çalıştırma kurallarını belirt:
- Aynı dosyayı değiştiren görevler paralel çalışamaz.
- Bağımlılığı tamamlanmamış görev başlatılamaz.
- Varsayılan concurrency en fazla 3 worker olmalı.
- Her görev en fazla 2 otomatik retry almalı.
- İkinci başarısızlıktan sonra
BLOCKED
olmalı.
tasks/task.schema.json
geçerli JSON Schema olsun.
Şu alanları içersin:
id
title
objective
description
assignedAgent
priority
status
dependencies
acceptanceCriteria
filesAllowed
filesForbidden
commands
risks
assumptions
worktree
branch
attempts
maxAttempts
result
commit
reviewResult
createdAt
updatedAt
Status enum:
pending
ready
running
review
changes_requested
approved
integrating
completed
blocked
failed
Assigned agent enum:
architect
frontend-worker
backend-worker
test-worker
reviewer
integrator
filesAllowed
, acceptanceCriteria
ve commands
boş bırakılamasın.
maxAttempts
varsayılan olarak 2 olsun.
Repository’ye uygun, küçük ve risksiz bir örnek görev oluştur.
Örnek görev gerçek uygulama kodunu değiştirmeyi gerektirmesin. Dokümantasyon veya basit bir test altyapısı incelemesi olabilir.
scripts/create-agent-worktrees.sh
:
- Bash strict mode kullansın.
- Repository root’unu otomatik tespit etsin.
- Varsayılan olarak şu worktree’leri hazırlasın:
../<project-name>-frontend
../<project-name>-backend
../<project-name>-tests
../<project-name>-review
../<project-name>-integration
- Branch isimleri şu formatta olsun:
swarm/frontend
swarm/backend
swarm/tests
swarm/review
swarm/integration
- Branch veya worktree zaten varsa güvenli şekilde uyarı versin.
- Mevcut veriyi silmesin.
- Force kullanmasın.
- Çalıştırma sonunda oluşturulan worktree’leri listeylesin.
scripts/remove-agent-worktrees.sh
:
- Yalnızca bu altyapının oluşturduğu worktree’leri hedeflesin.
- Kirli worktree varsa silmesin.
- Force kullanmasın.
- Branch’leri varsayılan olarak silmesin.
- Kullanıcıya yapılan ve atlanan işlemleri raporlasın.
Her iki script için de çalıştırılabilir izin gerektiğini final raporunda belirt. İzin değişikliğini uygulayabiliyorsan uygula.
Dosyaları oluşturduktan sonra şu sırayla rapor ver:
- Tespit edilen proje yapısı
- Oluşturulan dosyalar
- Her agent’ın kısa görevi
- Tespit edilemeyen veya doğrulanması gereken bilgiler
- Kullanım komutları
- Önerilen ilk deneme görevi
- Oluşturulan altyapının sınırlamaları
Son olarak aşağıdaki doğrulamaları yap:
- JSON dosyalarının parse edilebildiğini kontrol et.
- Shell scriptlerine
bash -n
uygula. - Markdown frontmatter alanlarını gözden geçir.
- Oluşturulan dosyalar dışında değişiklik yapılmadığını
git diff --stat
ile doğrula.
Doğrulama başarısız olursa problemi düzelt ve tekrar çalıştır.
Şimdi repository’yi incele, dosyaları oluştur ve doğrulamaları tamamla.