Kodlama agent'ı ile çalışmak

Orbi'nin kendi MCP sunucusu var (İşbirliği). Bir kodlama agent'ı buna bağlandığında panonuz onun iş kuyruğu olur. Kartı okur, işi yapar, dalı açar, PR'ı gönderir ve kartı review'a düşürür.

Bu sayfa o düzeni kurmayı anlatır. Anlatılan şey teorik de değildir, Orbi ekibi kendi panosunu böyle kullanıyor.

#Neye benziyor

1. Siz kart açarsınız, örneğin "Global aramada / kısayolu çalışmıyor".
2. Agent kartı çeker, kodu okur, düzeltir.
3. Dal açar, push eder ve PR açar. PR açıklamasını da kendisi yazar.
4. Kartın altına "ne yaptım, ne düşündüm" yorumunu bırakır, kartı review'a alır ve size atar.
5. Siz sabah panoya bakarsınız.

Aradaki fark şuraya dayanır. Bir sohbet penceresinde çalışan agent'ın işi sohbet geçmişinde kalır, panoya bağlı bir agent'ın işi ise ekibin geri kalanının göreceği yerde kalır.

#Kurulum

#1. Agent'ı oluşturun

En doğru kurulum, kodlama agent'ını panoda bir takım üyesi yapmaktır.

Ayarlar → Takım → Takım üyesi ekle → Agent ekle ile bir agent oluşturun (örn. "Developer"), çalışma yerini "Dışarıdan bağlanır" seçin, Oluştur deyin. Kurulum rehberi ve token'lar profilinizin Araç erişimi sekmesindedir; agent sayfasındaki Bağlantı bölümü yalnız bağlantı durumunu gösterir ve Araç erişimini aç düğmesiyle oraya götürür (Agent'lar). Anahtar üretmenize gerek yoktur; kimlik bir sonraki adımda tarayıcıda verilir.

Böylece ajanın yazdığı her yorum panoda o agent'ın adıyla görünür ve "bu işi ben mi yaptım, AI mı" sorusu ortadan kalkar. Ayrıca kendi bildirimleriniz çalışır. Ajan sizin adınıza çalışmadığı için kartınıza yorum yazdığında ya da review'a taşıdığında haber alırsınız.

Kendi adınıza da bağlayabilirsiniz. Onay ekranında "Ben"i seçerseniz ajan sizin adınıza çalışır, yani yaptığı her şey panoda size aitmiş gibi görünür ve kendi işleminizin bildirimini almadığınız için değişiklikleri kaçırırsınız. Hızlı bir deneme için yeterlidir, kalıcı bir düzen için değildir.

#2. Agent'ı bağlayın

Kurulum rehberi istemci kartlarından oluşur (Claude Code, Claude, Cursor, VS Code, Diğer istemci); kartı seçince numaralı adımlar açılır ve hepsi tek bir bilgiye dayanır: Orbi'nin adresi. Rehber profilinizin Araç erişimi sekmesinde durur. Claude Code için komut şu biçimdedir, içinde anahtar yoktur.

claude mcp add --transport http orbi https://mcp.orbiwork.space/mcp

Sonra Claude Code'da /mcp yazıp sunucunun yanındaki Authenticate'i seçin. Tarayıcıda Orbi açılır, giriş yapmadıysanız önce giriş yaparsınız. Onay ekranı iki şey sorar: hangi workspace ve kimin adına. Oluşturduğunuz agent'ı seçip İzin ver deyin. Terminale döndüğünüzde bağlantı kurulmuştur.

Cursor için rehberde Cursor'a ekle düğmesi vardır; tıklayınca Cursor sunucuyu ekler ve yanında "Needs login" gösterir, ona tıklayınca aynı onay ekranı açılır. VS Code kartında da VS Code'a ekle düğmesi vardır; düğme çalışmazsa projedeki .vscode/mcp.json dosyasına yapıştırılacak hazır blok oradadır. Başka bir ayar dosyası kullanan istemciler için adres Diğer istemci kartındadır. Claude masaüstü ve claude.ai'de Ayarlar → Bağlayıcılar → Özel bağlayıcı ekle ekranındaki kutuya adresi yapıştırmanız yeter.

Birden fazla workspace'iniz varsa her biri ayrı bir bağlantıdır. Aynı adresi farklı bir adla bir kez daha ekler, onay ekranında öbür workspace'i seçersiniz. Bağlantı sayısı değişmez, kalkan şey anahtar kopyalamaktır.

Tarayıcısı olmayan istemciler için gizli anahtar yolu durur: profilinizin Araç erişimi sekmesinde Token üret ile bir token üretirsiniz. Agent adına token'ı Admin üretir; agent'ı pencerenin Kimin adına alanında seçersiniz. Token bir kez gösterilir ve yanında Claude Code, Cursor, VS Code, stdio köprüsü ve kendi istemciniz için adımlar gelir. mcp-remote köprüsü ve kendi yazdığınız betikler bu yolu kullanır. Kendi istemcinizi bağlıyorsanız bilmeniz gereken tek şey şudur. Adres tektir, her istek o adrese gider ve her istekte kimlik başlığı taşınır.

Hangi yolla bağlanırsanız bağlanın, bağlantı profilinizin Araç erişimi sekmesindeki Erişim token'ları listesinde bir satır olarak görünür ve iptal ettiğiniz anda istemci bir sonraki çağrıda kopar. Satıra tıklayınca token'ın paneli açılır: ne zaman oluşturulduğu, ne zaman sona ereceği, en son ne zaman kullanıldığı, hangi cihazdan bağlanıldığı ve tarayıcıdan verilen bir yetkiyse hangi istemciye verildiği orada yazar. İptal düğmesi de aynı paneldedir. Token kapalı bir alanı ancak bu panelde Kapalı alanları seç ile seçerseniz görür.

Bağlantıyı doğrulamak için agent'a whoami aracını çağırmasını söyleyin. Hangi kullanıcı, hangi workspace, hangi yetki ve hangi Orbi kurulumuna bağlandığını söyler. Son kısım önemlidir, çünkü birden fazla Orbi kurulumuyla çalışıyorsanız (örneğin biri deneme, biri gerçek) kart numaraları ikisinde de aynıdır ama kartlar farklıdır. "Düzelttim" denen iş yanlış kurulumda yapılmışsa kimse onu göremez ve whoami bunu tek çağrıda netleştirir.

Bağlantı kurulduğu anda Orbi ajana workspace'in tanıtımını gönderir (projeler, koleksiyonlar, tanımlı agent'lar, workspace bağlamı ve çalışma kuralları) ve ayrıntısı İşbirliği sayfasındadır. Buradan çıkan pratik sonuç şudur. Her oturuma projeyi baştan anlatarak başlamanız gerekmez. Ajanın bilmesini istediğiniz kalıcı bilgi Orbi'de dursun. Ayarlar → Genel → Workspace Bağlamı'na yazdığınız metin hem Orbi agent'larına hem bağlanan kodlama agent'ına gider. Projeye özel kurallar proje açıklamasına, ekibin öğrendikleri koleksiyonlara yazılır.

#3. Kartları hazırlayın

Agent iyi bir brief'le iyi çalışır, tıpkı insan gibi (Görevler). Kartta şunlar olsun.

• Ne istiyorsunuz. Somut sonuç yazın, "şunu iyileştir" demeyin.
• Nerede. Dosya ya da ekran adı verin, ya da @task.N ile önceki işe bağlayın.
• Neye uyulacak. Mevcut desene uysun, yeni bağımlılık eklemesin, testler geçsin.

Kartı agent'a atayın ve kuyruğa alın. Dışarıdan bağlanan bir agent'a atanmış kart Orbi'de çalıştırılmaz. "İstemci bekleniyor" işaretiyle kuyrukta durur ve ajanınız onu kendi kuyruğunda bulur (list_tasks filtresiz çağrıldığında kendi işlerini döndürür). İşaretin yanında ajanın istemcisinin çevrimiçi mi, çevrimdışı mı, yoksa hiç bağlanmamış mı olduğu yazar ve "neden başlamıyor" sorusunun cevabı çoğu zaman oradadır. İstemci o an bağlı değilse Orbi bunu kartı kuyruğa alırken zaten söyler ve onayınızı ister.

Agent birden fazla depoda çalışıyorsa. Agent sayfasındaki "Depolar" listesine istediğiniz kadar depo eklersiniz; her ekleme aynı seçiciyle yapılır (bağlı cihazların klasörlerinden seçin ya da adresi yazın), ilk satır varsayılandır ve her satır o deponun hangi cihazlarda bulunduğunu söyler; hiçbir cihazda yoksa daha eklerken uyarır. Böyle bir agent'a atanan kartın yazma kutusunun altında bir depo seçicisi belirir ve kartın hangi depoda çalışılacağını siz seçersiniz; agent depo tahmin etmez. Tek depolu agent'ta bu seçici hiç görünmez. Sunucu ve istemci gibi birbirine bağlı iki depoya dokunan bir iş için bir üst kart açın: ortak sözleşmeyi (uç noktalar, mesaj biçimi) onun açıklamasına yazın, depo başına bir alt kart açın ve çekmecedeki "Bir üst karta bağla" ya da "Alt kart ekle" seçicisiyle (başlık ya da numarayla arar) bağlayın; bir agent da kart açarken üst kartı söyleyerek alt kartları kendisi kurabilir. Alt kart cihaza giderken üst kartın açıklaması da gider, iki alt kart aynı sözleşmeyi okur; alt kartların birleştirme istekleri üst kartta toplu görünür. Böyle bir işi tek kartta tutmak isterseniz kartı bir kadroya verin: koordinatör depo başına bir üye koşusu açar, her biri kendi dalında çalışır ve birleştirme istekleri aynı kartta toplanır.

Kimse almazsa kart 6 saat sonra hata durumuna geçer, böylece kapalı bir dizüstü yüzünden sessizce bekleyen kart kalmaz. Ajanınız kartı aldıktan sonra da aynı tavan geçerlidir, yani kart 6 saat boyunca hiç ilerlemezse hata durumuna alınır. Uzun süren bir iş bu yüzden kesilmez, çünkü kodlama işleri saatler sürebilir. Buna karşılık duran bir oturum da kartı süresiz "çalışıyor"da bırakmaz.

#Döngüyü kurmak

Bir agent koşusu sonsuza kadar sürmez, model araç çağırmayı bıraktığında biter. Bu bir kusur değildir, çünkü sonsuz döngüde kalan bir agent'ın bağlam penceresi dolar ve duracak yeri kalmaz.

Doğru kalıp, döngüyü dışarıdan sürmektir.

her N dakikada bir:
  1. list_tasks            → bana atanmış bitmemiş kartlar
  2. kart yoksa            → çık
  3. get_task              → kartın tamamını oku
  4. işi yap               → dal, commit, PR
  5. add_task_comment      → ne yaptığını yaz
  6. set_task_state review → kart otomatik olarak açan insana döner

Son adımı ajan atlarsa kart "çalışıyor"da kalır ve yukarıdaki tavana takılıp hataya düşer. O zaman da bitmiş bir iş panoda hiç başlamamış gibi görünür. Bu yüzden betiğinize şunu ekleyin: komut sıfır kodla bittiyse ve kart hala "çalışıyor"daysa kartı kendiniz Review'a alın. Ajan zaten almışsa bu çağrı hiçbir şey değiştirmez, çünkü birinci yazar hep ajandır.

Zamanlayıcı ne olursa olsun (cron, systemd timer, CI zamanlayıcısı) önemli olan durumun agent'ta değil panoda olmasıdır. Koşu yarıda kesilse bile bir sonraki tur kaldığı yerden devam eder, çünkü gerçek kartta yazılıdır.

Kendi döngünüzü yazmak zorunda değilsiniz. Orbi Node cihazınızı ya da sunucunuzu panoya bağlar; hangi klasörde hangi kodlama aracının koşacağını arayüzden seçersiniz, kartı alma ve kapatma işini uygulama üstlenir. Yukarıdaki döngü hala geçerlidir ve kendi betiğinizi yazmak isterseniz aynı sözleşmeyle çalışır: soru sormadan biter, exit code doğru olur ve MCP'ye erişir.

#Ekibin ortak hafızası

Kodlama agent'ı yalnızca kartları değil, ekibin paylaşılan hafızasını da okur ve yazar. Koleksiyonlara (list_collections, read_collection, search_records, write_record) ve dosyalara (list_files, read_file, write_file) uzanır, tam liste İşbirliği sayfasındadır.

Bunun pratik karşılığı şudur. Agent'ınız bir mimari kararı, bir ölçümü ya da "bu yaklaşımı denedik, şu yüzden olmadı" bilgisini koleksiyona yazdığında, o bilgi ekip arkadaşınızın oturumunda da vardır. Aynı şey Orbi agent'ları için de geçerlidir, çünkü araçlar birebir aynıdır, yani sizin kodlama agent'ınızın yazdığı kaydı Orbi orchestrator'ı da okur.

İki pratik alışkanlık işinizi kolaylaştırır.

• Yazmadan önce ara. search_records semantik çalışır ve aynı bilgiyi ikinci kez yazmak hafızayı büyütmez, kirletir. Koleksiyonun dedup sütunu varsa write_record benzer kaydı bulup yazmayı reddedebilir (sonuçtaki written alanına bakın). Dedup sütunu tanımlı değilse bu koruma yoktur ve aramayı siz yapmalısınız.
• Karta değil hafızaya yazın. Yorum bir konuşmadır ve kart kapanınca akıştan düşer, koleksiyon kaydı ise kalıcıdır ve aranabilir. "Bu koşuda ne yaptım" yoruma, "bundan sonra bunu bilmemiz gerek" koleksiyona yazılır.

#İki tuzak

set_task_state ile queued vermek Orbi'nin kendi agent'larını çalıştırır. Kodlama agent'ınız bir kartı "sıraya aldım" anlamında işaretlemek isterse todo kullanmalıdır, çünkü queued bir yürütme emridir (Görevler).

Yorumda @agent.<ad> geçerse o agent çalışmaya başlar. Kodlama agent'ınız bir Orbi agent'ından bahsetmek isterse, mention yerine düz metinle anmalıdır.

#Yetki ve güvenlik

• Token ayrı bir izin sistemi tanımlamaz, sahibinin rolünü devralır. Rolünüz düşerse token'ın yetkisi de anında düşer.
• Salt-okunur token, yalnızca panoyu izleyen istemciler için doğru seçimdir. Kart açma, durum değiştirme ve yorum yazma kapalı olur.
• İptal bir sonraki çağrıda etkilidir ve oturum önbelleği yoktur.
• Token'ı bir depoya commit etmeyin. Ortam değişkeninde tutun.

#Sınırlar

• Kodlama agent'ının kendi kullanım limitleri Orbi'nin kontrolünde değildir. Uzun gözetimsiz koşular için sağlayıcınızın faturalandırma modelini kontrol edin.
• Orbi MCP sunucusunda şu an token başına oran sınırı yoktur. Kendi ekibinizin kendi token'ı için sorun değildir, ama token'ı üçüncü bir tarafla paylaşmayın.
• Paylaşılan bellek uzaktan silinmez. Koleksiyon kaydı silmek ve başkasının dosyasını silmek arayüzde kalır. Kodlama agent'ınız bunları yazabilir ve güncelleyebilir, silemez. İki dar istisna vardır. Kart silinebilir (delete_task) ve bunun için bir kişinin açıkça istemiş olması gerekir. Agent'ın kendi yazdığı, yükleme olmayan ve hiçbir karta bağlı olmayan dosya da çöpe taşınabilir (delete_file) ve 30 gün boyunca arayüzden geri alınır. Kimin sildiği etkinlik günlüğünde kalır.