Çok sayıda yapay zeka aracısı çalıştıran geliştiriciler, genellikle beşinci aracıdan sonra aynı sorunlarla karşılaşır: Dağınık görev dağılımı, maliyet artışı, tekrarlanan işler ve hedefi belirsiz çalışan ajanlar. Paperclip, yapay zeka ajanlarınızı kuruluş şemaları, atanmış roller, görev yönetimi, bütçe limitleri ve denetim günlükleriyle yapılandırılmış bir şirkete dönüştüren açık kaynaklı bir orkestrasyon katmanıdır. Bu rehberde Paperclip’in kurulumu, ilk şirketinizi ve ajanlarınızı yapılandırma, iş takibi ve bütçe kontrolü gibi pratik uygulama adımlarını bulacaksınız.
Paperclip nedir (ve ne değildir)
Paperclip, GitHub'da açık kaynak olan, çoklu yapay zeka ajanlarını koordine eden bir orkestrasyon katmanıdır. Ajanlarınızın ne yaptığını takip eder, bütçelerini yönetir ve şirket hedeflerine bağlam sunar. Bir sohbet botu arayüzü, iş akışı oluşturucu (n8n/Zapier gibi) veya aracı geliştirme çerçevesi değildir. Tek aracılı kullanımlar için değil, 3+ yapay zeka ajanının paralel çalıştığı projeler için tasarlanmıştır.
Paperclip aşağıdaki ajan türleriyle çalışır:
- Claude Code
- OpenAI Codex
- Cursor
- Gemini CLI
- HTTP webhook veya heartbeat tetikleyebilen diğer ajanlar
Paperclip Kurulumu
Paperclip’i başlatmak için aşağıdakiler yeterlidir:
- Node.js 20+
- pnpm 9.15+
Paperclip gömülü bir PostgreSQL veritabanı içerir, ek bir veritabanı kurulumuna gerek yoktur.
Hızlı başlangıç:
npx paperclipai onboard --yes
Bu komut, CLI’yı indirir, kurulumu tamamlar ve sunucuyu 3100 portunda başlatır. Ardından http://127.0.0.1:3100 adresinden gösterge paneline erişebilirsiniz.
Kaynak koddan çalıştırmak için:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Docker ile çalıştırmak için:
docker compose -f docker-compose.quickstart.yml up --build
Dosya yapısı:
Paperclip tüm verileri ~/.paperclip/instances/default/ altında saklar:
~/.paperclip/instances/default/
config.json — Sunucu/Depolama ayarları
db/ — PostgreSQL veri dosyaları
secrets/master.key — Şifreleme anahtarı
logs/ — Sunucu logları
data/storage/ — Dosya ekleri
workspaces/<agent> — Her aracıya özel çalışma dizini
Kurulumdan sonra sağlık kontrolü önerilir:
paperclipai doctor
Hataları düzeltmek için:
paperclipai doctor --repair
İlk şirketinizi kurma
Paperclip’te bir “şirket”, ajanlarınız, görevleriniz, hedefleriniz ve bütçeleriniz için üst düzey kapsayıcıdır. Gösterge panelinden yeni bir şirket oluşturun ve misyon ifadesi ekleyin. Bu ifade, tüm ajanlarınızın karar sürecine rehberlik eder. Örnek misyon:
"Müşteri sipariş yönetimi için bir REST API oluştur ve sürdür. Hızı doğruluğa tercih et. Herkese açık her uç noktayı belgele."
İlk aracılarınızı ekleme
Her Paperclip ajanı, hangi yapay zeka kaynağını kullandığını belirten bir adaptör ile tanımlanır.
| Aracı | Adaptör tipi | Paket |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP webhook | HTTP adaptörü | özel uç nokta |
CLI ile Claude Code ajanı eklemek için:
paperclipai agent local-cli "Backend Engineer" --company-id <şirket-kimliğiniz>
Bu komut, aracı başlatır ve şirket organizasyonuna ekler.
Claude ajanı yapılandırma alanları:
| Alan | Açıklama |
|---|---|
model |
Claude model seçimi (ör: claude-sonnet-4-6) |
cwd |
Çalışma dizini (otomatik oluşturulur) |
promptTemplate |
Sistem istemi, {{variable}} ile değişkenler |
maxTurnsPerRun |
Her heartbeat'ta maksimum döngü (vars: 300) |
timeoutSec |
Sabit zaman aşımı (0 = yok) |
Model tahsisi önerisi:
- CEO/Orkestrasyon: Sonnet
- Yönetici ajanlar: Haiku
- Kodlama/yaratıcı: Sonnet
- Şablon tabanlı işler: Haiku
Bu ayrım, aylık harcamalarınızı %40-60 oranında azaltabilir.
Aracı organizasyonunuzu yapılandırma
Küçük bir yazılım projesi için örnek yapı:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── Backend Mühendisi (Sonnet)
│ ├── Frontend Mühendisi (Sonnet)
│ └── QA Mühendisi (Haiku)
└── Teknik Yazar (Haiku)
Her aracıya kalp atışı aralığı tanımlayın:
- Kodlama ajanları: 600 sn (10 dk)
- Talep üzerine ajanlar: 86.400 sn (günde 1)
- Minimum güvenli aralık: 30 sn (daha kısa aralıklar maliyet artırır)
Kalp atışı nasıl çalışır?
Ajanlarınızdan güvenilir iş almak için heartbeat modelini uygulayın. Her heartbeat’te aracı şu adımları izler:
- Kimlik doğrulama (
GET /api/agents/me) - Bekleyen onay geri çağrılarını işle
- Atanmış görevleri çek (
GET /api/companies/{companyId}/issues) - Önceliklendir (devam eden > yapılacaklar)
- Görevi teslim al (
POST /api/issues/{issueId}/checkout) - Görev bağlamı ve yorumları oku
- Görevi gerçekleştir
- Durum ve yorumlarla güncelle
- Gerekirse alt görevleri devret
Her çalışmada Paperclip aşağıdaki ortam değişkenlerini enjekte eder:
PAPERCLIP_TASK_ID # Hangi görev tetikledi
PAPERCLIP_WAKE_REASON # Neden uyandı (zamanlayıcı, atama)
PAPERCLIP_AGENT_ID # Aracı kimliği
PAPERCLIP_API_URL # API callback adresi
Ajanlar bu bilgileri güncelleme, alt görev oluşturma veya onay istemek için kullanabilir.
Görev atama ve iş takibi
Görevler, GitHub Issues ile proje yönetim araçlarının birleşimi gibi çalışır.
CLI ile görev oluşturma:
paperclipai issue create \
--company-id <id> \
--title "Siparişler uç noktasına sayfalama ekle" \
--assignee-agent-id <agent-id>
Görevler şu özelliklere sahip olabilir:
- Üst görevler: Büyük işleri parçalara ayırmak için
- Hedef bağlantıları: Hangi şirket hedefiyle ilişkili olduğunu göstermek için
- Yorumlar: Bağlam, onay, durum güncellemeleri
- @-bahsetmeler: Talep üzerine hemen uyandırmak için
Tüm açık görevleri listelemek için:
paperclipai issue list
Gösterge panelinde de görevlerin mevcut durumu, sahibi ve son işleyen heartbeat gösterilir.
Gerçekten işe yarayan bütçe kontrolü
Her aracıya aylık bir token bütçesi verin. %80’e ulaşınca aracı yalnızca kritik görev alır, %100’de duraklatılır. Bütçeyi aracı yapılandırmasında belirleyin (topluluk önerisi: ayda $20-50/katman).
Harcamaları ve heartbeat başına maliyeti gösterge panelinden takip edin. Maliyet artışı, genellikle görev kapsamının çok geniş tanımlanmasından kaynaklanır; bunu bütçeyi artırmak yerine görev tanımını netleştirerek düzeltin.
Çalışma zamanı becerileri: yeniden eğitim olmadan aracılara yeni iş akışları öğretme
Beceri enjeksiyonu ile ajanlara yeni iş akışları öğretebilirsiniz. Paperclip, aracı yapılandırma dizinine sembolik bağlantı ile SKILL.md dosyalarını ekler. Aracı, her heartbeat’te bu markdown dosyasını okur.
Örneğin, bir veritabanı geçiş süreci için:
# BECERİ: Veritabanı geçişleri
Bir geçiş oluştururken:
1. Mevcut geçiş dosyalarını asla değiştirmeyin
2. Açıklayıcı adlar kullanın: YYYYAA_açıklama.sql
3. Hem yukarı hem de aşağı SQL'i dahil edin
4. Taahhüt etmeden önce yerel olarak test edin
5. Değişikliğin iş nedenini açıklayan bir yorum ekleyin
Bu dosyayı ilgili aracıya atayın; her heartbeat’te süreç takip edilir.
Aracılarınız tarafından oluşturulan API'leri test ediyorsanız
Aracılarınız API üretiyorsa, çıktıyı hızlıca test etmek için Apidog kullanabilirsiniz. Apidog, API tasarımı, sahte sunucu ve otomatik testleri tek yerde toplar. Böylece bir uç nokta oluşturulduğunda Swagger, Postman veya ekstra sahte araç ihtiyacı olmadan hemen doğrulama yapabilirsiniz.
OpenAPI spesifikasyonundan otomatik test suite’leri oluşturup, bunları ajan çıktısına karşı çalıştırıp, sonucu görev yorumuna döndürebilirsiniz. Aracı bir sonraki heartbeat’te bunu alıp hataları düzeltebilir. Apidog REST, GraphQL ve gRPC’yi destekler ve başlangıçta ücretsizdir.
Birden fazla örneği yönetme
Tek bir makinede izole çoklu Paperclip örneği çalıştırmak için PAPERCLIP_INSTANCE_ID ortam değişkenini veya --instance bayrağını kullanın. Her örnek kendi yapılandırma, veritabanı ve çalışma alanına sahip olur.
Yerel geliştirme için:
paperclipai worktree:make feature/orders-pagination
Her branch için bağımsız bir örnek oluşturulur. Test bitince örneği yıkabilir, üretim kurulumundan izole şekilde geliştirme yapabilirsiniz.
Çalışan çoklu ajan kurulumları
Başarılı çoklu aracı düzeni için:
- Hedef basamaklandırma: Şirket hedefini CEO aracına, proje hedeflerini yöneticilere, görevleri mühendislere dağıtın.
- Onay geçitleri: Üretim, faturalandırma vb. kritik adımlar için manuel onay ekleyin; aracı durur, bildirim yollar.
- @-bahsetme ile talep üzerine uyanma: Hızlı heartbeat yerine, ajanları yavaş aralıkta tutup gerekirse @ ile hemen uyandırın.
-
İzole çalışma alanları: Her ajanın
workspaces/<agent>altında ayrı dizini olmalı. Aynı alanı paylaşmak karışıklık yaratır.
Başlamak yaklaşık 15 dakika sürer
İlk kurulum 15 dakikadan kısa sürer:
- Sunucuyu başlatmak için tek komut
- İlk ajan ve görev eklemek için 5 dakika
- En önemli adım: Misyon yazmak, doğru modelleri ve bütçeleri seçmek. Bunlara 30 dakika ayırın.
Kısa sürede, rastgele terminalde çalışan ajanlar yerine, kontrol edilebilir, bütçeli ve denetlenebilir bir çoklu ajan sistemi elde edersiniz. Özellikle 2+ ajan ile çalışan projeler için bir öğleden sonra ayırmaya değer.
Top comments (0)