<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Recep Şen on Medium]]></title>
        <description><![CDATA[Stories by Recep Şen on Medium]]></description>
        <link>https://medium.com/@senrecep?source=rss-10245e9040f4------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*2Kb7222P0tspvS6RanOKYg.jpeg</url>
            <title>Stories by Recep Şen on Medium</title>
            <link>https://medium.com/@senrecep?source=rss-10245e9040f4------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 09:23:48 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@senrecep/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Kod Yazmayı Bırakın, Sistemi Yönetin: AI Destekli Geliştirmenin Gerçek Potansiyeli]]></title>
            <link>https://senrecep.medium.com/kod-yazmay%C4%B1-b%C4%B1rak%C4%B1n-sistemi-y%C3%B6netin-ai-destekli-geli%C5%9Ftirmenin-ger%C3%A7ek-potansiyeli-64cab2c7305c?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/64cab2c7305c</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[developer-productivity]]></category>
            <category><![CDATA[ai-assisted-development]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Sat, 28 Feb 2026 02:05:30 GMT</pubDate>
            <atom:updated>2026-08-08T13:26:12.091Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0XOiT4M5zP976ZgVjO7n7Q.png" /><figcaption>AI agent’larınızı orkestre edin, kod yazmayı bırakın.</figcaption></figure><p><strong>Read this article in English:</strong> <a href="https://medium.com/@senrecep/stop-writing-code-start-managing-systems-the-real-potential-of-ai-powered-development-71fafeb144de">Stop Writing Code, Start Managing Systems: The Real Potential of AI-Powered Development</a></p><h3>Giriş: AI Araçlarını Zaten Kullanıyordum</h3><p>Bu makaleye “Claude Code nedir ve nasıl kurulur” diye başlamayacağım. Çünkü bunu okuyan insanların çoğu zaten bir AI aracı kullanıyor. Cursor, Copilot, Windsurf, belki ChatGPT; hepsini denedik, güçlü ve zayıf yönlerini gördük.</p><p>Ben de farksız değildim. Yıllardır yazılım geliştiriyorum ve son yıllarda AI araçlarını yoğun şekilde kullanıyordum. Cursor ile başladım, IDE içinde AI destekli geliştirmenin konforunun tadını aldım. Ama bir noktada duvara çarptım: projem büyüdükçe AI’ın yanıtlarının kalitesi düşmeye başladı. Çünkü IDE tabanlı araçlar size bir “asistan” sunuyor: siz yazıyorsunuz, o tamamlıyor. Güzel, ama sınırlı.</p><p>Claude Code’a geçtiğimde paradigma değişti. Bu bir asistan değil, bir geliştirme ortamı. Terminalde çalışan, dosyalarınızı okuyan, komutlar çalıştıran, git işlemleri yapan ve hatta paralel çalışmak üzere başka AI instance’ları başlatabilen bir sistem. Ama asıl güç, bu sistemi nasıl yapılandırdığınızda yatıyor.</p><p>Claude Code’u aylardır birden fazla projede, farklı teknoloji yığınlarında (.NET backend’lerden React Native mobil uygulamalara, Go servislerinden Next.js frontend’lere) üretim ortamında kullanıyorum. Bu makale, o ayların birikimi. Neyi doğru yaptım, neyi yanlış yaptım, hangi yaklaşımlar gerçekten işe yaradı.</p><p>Önemli bir not: bu makaleyi “şu düğmeye tıkla, şu komutu yaz” tarzında bir eğitim olarak değil, bir düşünce çerçevesi olarak okumanızı öneririm. Çünkü AI araçlarının gerçek gücü hangi düğmeye bastığınızdan değil, nasıl düşündüğünüzden gelir.</p><h3>Bölüm 1: Bir Zihniyet Değişimine İhtiyacınız Var</h3><h4>Junior Developer Gibi Değil, CTO Gibi Düşünün</h4><p>AI destekli geliştirmede en yaygın hata, AI’ı “benim yerime kod yazan bir şey” olarak görmektir. “Şu fonksiyonu yaz,” “şu bug’ı düzelt,” “şu API’yi ekle”; bunlar geçerli istekler, ama resmin sadece küçük bir parçası.</p><p>Gerçek verimlilik, bir projeye A’dan Z’ye bir CTO gibi yaklaştığınızda ortaya çıkar:</p><ul><li><strong>Planlama</strong>: Ne inşa ediyoruz ve neden?</li><li><strong>Mimari</strong>: Nasıl yapılandıracağız?</li><li><strong>Geliştirme</strong>: Nasıl implement edeceğiz?</li><li><strong>Test</strong>: Doğru çalıştığını nasıl doğrulayacağız?</li><li><strong>Güvenlik</strong>: Güvenlik açıklarını nasıl tespit edeceğiz?</li><li><strong>Performans</strong>: Yeterince hızlı mı?</li><li><strong>Dağıtım</strong>: Nasıl yayına alacağız?</li></ul><p>Claude Code’un gerçek gücü, bu yaşam döngüsünün her aşamasında size yardımcı olabilmesidir. Sadece “kod yazma” aşamasında değil. Ve bu makalede bu yaklaşımı detaylı olarak anlatacağım.</p><h4>Olasılıksal Düşünmeyi Öğrenin</h4><p>AI deterministik bir makine değildir. Aynı prompt’u iki kez verin, farklı sonuçlar alabilirsiniz. Bu bir bug değil, çalışma prensibidir. Bu prensibi anladığınızda, AI ile çalışma şekliniz temelden değişir:</p><ul><li><strong>İlk denemede mükemmel sonuç beklemeyin.</strong> İteratif çalışın. İlk çıktıyı inceleyin, geri bildirim verin, tekrar deneyin.</li><li><strong>Doğrulama mekanizmaları kurun.</strong> AI “bitti” dedi diye bitmez. Build’in çalıştığını, testlerin geçtiğini, güvenlik taramalarının temiz döndüğünü doğrulayın.</li><li><strong>Deterministik katmanlar ekleyin.</strong> Hook’lar, linter’lar, test suite’leri; bunlar AI’ın olasılıksal doğasının üzerine kesinlik katmanlarıdır.</li></ul><p>Bu zihniyetle başladığınızda, geri kalan her şey çok daha kolay hale gelir.</p><h4>Düşünce Hızında Çalışmayı Öğrenin</h4><p>AI ile çalışırken en büyük darboğazın ne olduğunu biliyor musunuz? AI’ın hızı değil; sizin girdi sağlama hızınız. Bir bug fark ediyorsunuz, terminale geçmeniz, sorunu tanımlamanız, ekran görüntüsü alıp yapıştırmanız, tekrar geri dönmeniz gerekiyor. Her bağlam geçişinde odağınızı kaybediyorsunuz, düşünce silsilesi buharlaşıyor.</p><p>Çözüm: düşündüğünüz anda AI’a girdi verebildiğiniz bir iş akışı kurmak. Benim için bu, bir hotkey’e bağlı konuşmadan metne dönüşüm (konuşmak yazmaktan daha hızlıdır ve prompt’lar dağınık dilbilgisine tolerans gösterir), son kopyaladığım her şeyi hatırlayan bir pano yöneticisi ve görsel bug’lar için anında ekran görüntüsü paylaşımı anlamına geliyor. Bir insanla çalışır gibi, “bak, şu kısım bozuk, şunu da düzelt, ha bir de şu var” diyebilmek gibi.</p><p>Bunu aklınızda tutun: AI ile çalışırken sizi yavaşlatan AI değil; bilgiyi AI’a aktarma hızınızdır.</p><h3>Bölüm 2: CLAUDE.md: Projenizin Stratejik Beyni</h3><h4>Her Oturumun Başladığı Dosya</h4><p>CLAUDE.md, Claude Code’un her konuşmanın başında otomatik olarak okuduğu proje talimat dosyasıdır. Claude her oturumda sıfırdan başlar; önceki konuşmaları hatırlamaz. Ama bu dosya sayesinde projenizi “bilir.”</p><p>Bu dosya, Claude Code deneyiminizin kalitesini belirleyen en büyük faktörlerden biridir. İyi bir CLAUDE.md mühendislik becerisinin yerini tutmaz, ama kötü bir CLAUDE.md uzman bir geliştiriciyi bile sinir eder.</p><h4>Az Çoktur: 100 Satır Kuralı</h4><p>İlk CLAUDE.md dosyam 160 satırı aşıyordu. Her kuralı, her komutu detaylı olarak yazmıştım. Sonuç? Claude önemli bilgileri kaçırıyordu. Uzun dosya = dağınık dikkat.</p><p>Çözüm: CLAUDE.md’nizi 100 satırın altında tutun. Detayları ayrı dosyalara taşıyın. Claude ihtiyaç duyduğunda o dosyalara bakacaktır.</p><pre>CLAUDE.md (70-100 lines)              - Always read<br>.claude/rules/architecture.md         - Referenced when needed<br>.claude/rules/security.md             - Referenced when needed<br>docs/claude/patterns.md               - Referenced when needed</pre><p>Bu yaklaşıma “progressive disclosure” denir: bilgiyi kademeli olarak açığa çıkarmak.</p><h4>WHAT / WHY / HOW Yapısı</h4><p>Etkili bir CLAUDE.md üç bölümden oluşur:</p><p><strong>WHAT</strong>: Proje nedir? Teknoloji yığını, mimari yapı, temel kavramlar. Tek bir paragraf yeterlidir.</p><p><strong>WHY</strong>: Bu kararları neden aldık? Bu kısım kritik. Claude “neden”i bildiğinde, sınır durumlarında çok daha iyi kararlar verir. Örneğin, sadece “console.log kullanma” demek yerine, “console.log kullanma çünkü üretim ortamında performans sorunlarına neden olur ve hassas verileri sızdırabilir” derseniz, Claude geliştirme sırasında geçici kullanımın kabul edilebilir olduğunu anlar.</p><p><strong>HOW</strong>: Nasıl çalışıyoruz? Komutlar, test pattern’leri, adlandırma kuralları. Burada örnekle öğretin: iyi bir kod parçacığı, bir convention’ı üç paragraflık açıklamadan daha iyi anlatır.</p><h4>“Yapma” Bölümü</h4><p>CLAUDE.md’nize her zaman bir “Yapma” bölümü ekleyin. Claude’un bilinen eğilimleri vardır:</p><ul><li>Aşırı mühendislik eğilimi (ekstra soyutlamalar, gereksiz interface’ler)</li><li>Çok fazla dosya oluşturma eğilimi (tek dosyada çözülebilecek şeyleri böler)</li><li>İmkansız senaryolar için hata yönetimi ekleme eğilimi</li><li>Docstring ve yorum ekleme eğilimi (istenmediğinde bile)</li><li>Stub dosya oluşturma eğilimi (dosya var ama return null, return {}, TODO, console.log yer tutucularıyla dolu; dosyanın var olması gerçek implementasyon anlamına gelmez)</li></ul><p>Bu eğilimleri CLAUDE.md’de açıkça belirtmek, gereksiz işlerden kaçınmanın en ucuz yoludur.</p><h4>3 Katmanlı Sınır Belirleme</h4><p>Claude’a ne yapabileceğini, ne zaman sorması gerektiğini ve ne yapmaması gerektiğini açıkça söyleyin:</p><ul><li><strong>Her zaman yap</strong>: Test yaz, testleri çalıştır, adlandırma kurallarına uy</li><li><strong>Önce sor</strong>: Veritabanı migration’ları, yeni dependency ekleme, büyük refactoring</li><li><strong>Asla yapma</strong>: Secret’ları commit’leme, lock dosyalarını düzenleme, testleri silme</li></ul><p>Bu üç katman, Claude’a güvenle hareket edebileceği alanı gösterirken, tehlikeli alanlarda sizi bilgilendirmesini sağlar.</p><h4>Global CLAUDE.md</h4><p>~/.claude/CLAUDE.md dosyası, tüm projelere uygulanan global talimatları içerir. İletişim tercihlerimi (özetler Türkçe, teknik terimler İngilizce), sık kullanılan CLI araçlarını ve genel çalışma prensiplerimi burada tanımlıyorum. Bu sayede her projede tekrarlamama gerek kalmıyor.</p><h4>Yola Özel Kurallar: Doğru Kural, Doğru Dosya</h4><p>Şöyle bir senaryo: tüm test dosyalarınıza aynı kuralları uygulamak istiyorsunuz. Ama test dosyaları 50 farklı dizine dağılmış. Her dizine ayrı bir CLAUDE.md mi koyacaksınız? Tabii ki hayır.</p><p>.claude/rules/ dizininde dosya pattern&#39;ine göre kurallar tanımlayabilirsiniz:</p><pre>---<br>paths: [&quot;**/*.test.tsx&quot;]<br>---<br>Use AAA (Arrange-Act-Assert) pattern in test files.<br>Prefer real database connections over mocks.</pre><p>**/*.test.tsx pattern&#39;i, hangi dizinde olursa olsun tüm kod tabanındaki test dosyalarını yakalar. Aynı mantık geçerli: API endpoint&#39;leri için **/*.api.ts, Terraform dosyaları için terraform/**/*. Her biri kendi özel kurallarıyla.</p><p>Bir de context avantajı var: bu kurallar yalnızca eşleşen dosyalar düzenlenirken yüklenir. Context’te kalıcı olarak yer kaplamazlar, yalnızca ilgili olduklarında devreye girerler.</p><h3>Bölüm 3: Context Window: Anlaşılması Gereken En Kritik Kavram</h3><h4>Nedir ve Neden Önemlidir</h4><p>Context window, Claude’un çalışma belleğidir. Her mesaj, okunan her dosya, her komut çıktısı bu ortak bütçede birikir. Opus’ta bu bütçe yaklaşık 200.000 token’dır.</p><p>Çoğu geliştirici, context %100&#39;e ulaşana kadar her şeyin düzgün çalışacağını varsayar.</p><p><strong>Gerçek:</strong> Düşüş kademelidir ve çubuk dolu görünmeden çok önce başlar. %60&#39;ı geçtiğinde Claude önceki talimatları unutur, aynı hataları tekrarlar, yanlış dosyaları düzenler. Pratik kuralım: %40 civarında aksiyon alın, %60&#39;ı beklemeyin.</p><p>Ama sorun sadece context’in “dolması” değil; aynı zamanda aktif olarak <strong>çürümesidir</strong>. Buna “context rot” deniyor.</p><p>Eski tool çıktıları, zaten düzeltilmiş bug’lardan kalan debug izleri, refactor edilmiş dosyaların eski versiyonları: hepsi context’te birikir. Model güncel olanı eskimiş olandan ayırt edemez. Bayatlamış bilgi sadece yer kaplamaz; aktif olarak zarar verir. Model eski veriyi güncelmiş gibi ele alır ve onun üzerine kararlar verir: yeniden adlandırılmış değişkenlere referans verir, değişmiş pattern’leri takip eder.</p><p>Bu yüzden bu kadar çok multi-agent kurulumu birkaç görevden sonra dağılır. Model aptallaşmadı. Context zehirlendi.</p><p>Bir not: bu tablo sürekli iyileşiyor. Modeller her sürümde uzun oturumlarda daha dayanıklı hale geliyor; Claude Code da neyi compact edeceği, neyi özetleyeceği ve hafızaya neyi kaydedeceği konusunda giderek akıllanıyor. Bugünün terminal agent’ları, bir yıl önce raydan çıkacakları durumlarda, bazen pencere neredeyse doluyken bile tutarlı kalabiliyor. Bu yüzden bu bölümdeki eşikleri fizik kuralı gibi değil, bir mantalite olarak okuyun: oturumlarınızı gözle görülür şekilde daha etkili kılıyorlar, ama kesin kurallar değiller.</p><h4>Bir Konuşma = Bir Görev</h4><p>Eşikler nerede olursa olsun geçerli olan bir alışkanlık var: bir konuşma, bir görev. Auth sistemi + veritabanı şeması + UI bileşenleri + test yazma; hepsini tek bir konuşmada yapmaya çalışmayın. Her biri ayrı bir oturum olmalı.</p><p>“Ama context’i az önce açıkladım, yeni oturumda tekrar mı açıklamam gerekecek?” diye düşünebilirsiniz. Hayır. CLAUDE.md projenizi bilir, oturum hafızanız ise mevcut durumu tutar (bunun nasıl olduğunu bir sonraki alt bölümde ele alıyoruz). Yeni oturum sıfırdan başlamaz.</p><h4>Oturumlar Arası Hafıza</h4><p>Claude stateless’tır; her konuşma sıfırdan başlar. Oturumlar arasında bilgi taşımanın çeşitli yöntemleri var. Ben OMC (oh-my-claudecode) plugin’inin project-memory özelliğini kullanıyorum: teknoloji yığınını, mimari kararları, convention’ları, notları ve direktifleri JSON formatında saklayan, projeye özel bir depo ve her oturum bunu otomatik olarak okuyor.</p><p>Hangi aracı kullanırsanız kullanın, önemli olan prensip şudur: oturum sonunda önemli bilgileri kaydedin, oturum başında okuyun.</p><h4>Pratik Context Yönetimi</h4><p><strong>HUD’u (Heads-Up Display) Kullanın</strong>: Claude Code’un terminal durum çubuğunda bir HUD bulunur. Gerçek zamanlı bilgi gösterir:</p><ul><li>Aktif model (Opus, Sonnet, Haiku)</li><li>Oturum süresi</li><li>Harcanan token sayısı</li><li>Mevcut maliyet ve saatlik maliyet oranı</li><li>Cache hit oranı</li><li>İzin modu (Normal, Auto-Accept, Bypass); Shift+Tab ile geçiş yapılır</li></ul><p><strong>Context doluluk çubuğu</strong>: izlenmesi gereken şey budur. Bunu takip etmek context yönetiminin temelidir; aksiyon alma zamanının geldiğini anında göreceksiniz.</p><p><strong>/compact zamanlaması</strong>: Çubuk yukarıdaki eşiğe ulaştığında, kalite düşmeye başlamadan önce proaktif olarak çalıştırın.</p><p><strong>/clear ile temiz başlangıç</strong>: Bir görev tamamlandığında veya konu değiştiğinde yeni bir oturum başlatın.</p><p><strong>Bilgi sıralaması önemlidir</strong>: AI modelleri uzun girdilerin başını ve sonunu iyi işler ama ortaya gömülü bilgileri kaçırabilir. Uzun bir analiz sonucu veya hata logu gönderiyorsanız, en kritik bilgiyi başa koyun. “Bu fonksiyonda null pointer var, ilgili log çıktısı aşağıda” diye başlamak, 500 satırlık bir logun ortasına gömülü bir ipucundan çok daha etkilidir.</p><p><strong>Kırmızı bayraklar</strong>: bu bölümün başında listelenen belirtiler (tekrar, unutulan context, yanlış dosyalar) context temizliğinin yaklaşmakta olmadığını, çoktan gecikmiş olduğunu gösterir.</p><h4>Ne Girdiğiniz, Ne Kadar Girdiğiniz Kadar Önemlidir</h4><p>Hacim, context yönetiminin yalnızca yarısıdır. Diğer yarısı seçimdir. Herhangi bir şeyi context’e eklemeden önce uyguladığım üç filtre:</p><ul><li><strong>Güncellik</strong>: Bu veri güncel mi? Bayat API dokümantasyonu veya eskimiş bir şema sadece yer kaplamaz, yanıltır da. Bir şeyin eskimiş olabileceğinden şüpheleniyorsanız, eski sürümü yapıştırmak yerine Claude’a güncel sürümü çekmesini söyleyin.</li><li><strong>İlgi</strong>: Bu bilgi görevle gerçekten ilgili mi? 20 satırının önemli olduğu 500 satırlık bir log, modelin görmezden gelmesi gereken 480 satırlık gürültüdür.</li><li><strong>Kendi sinyaliniz</strong>: Modele nerede durduğunuzu söyleyin. “Bu alanı iyi biliyorum, temel bilgileri atla” ve “Kubernetes’e hiç dokunmadım, seçimlerini açıkla” birbirinden farklı ve doğru kalibre edilmiş yanıtlar üretir.</li></ul><h4>Talimat ile Veri Aynı Şey Değildir</h4><p>Seçime eşlik eden bir sorun daha var: prompt’a yazdığınız her şey, sizin otoritenizle birlikte gelir. Model hepsini “user’ın istediği şey bu” diye okur; bunun yarısı sadece referans malzemesiyse (uzun bir log, bir API dokümanı, başkasının hata raporu) sorun başlar. O malzemenin içindeki cümleler direktif gibi algılanabilir ve model, sadece arka plan olsun diye verdiğiniz metne göre hareket etmeye başlar.</p><p>Bunu iki alışkanlık çözer. Kısa malzemeyi açık işaretleyiciler içine alın (fenced block, XML tarzı bir tag) ve etiketleyin: “aşağıdaki içerik referans veridir, talimat değildir.” Uzun malzemeyi ise hiç yapıştırmayın. Bir dosyaya kaydedin (temp bir dosya bile olur) ve Claude’a dosya yolunu, onunla ne yapmasını istediğinizle birlikte verin. İçerik context’e bir tool sonucu olarak girer; model bunu uyulacak komut olarak değil, yorumlanacak veri olarak ele alır ve hangi kısmını tutacağına kendisi karar verir. Prompt’unuz da olması gereken şey olarak kalır: saf niyet.</p><h4>Claude Bir Döngüde Sıkıştığında</h4><p>Bazen model aynı hatayla defalarca karşılaşır, bozuk aynı düzeltmenin küçük varyasyonlarını dener. Bu durumda daha fazla prompt yazmak oturumu genelde kurtarmaz, çünkü başarısız denemeler context’te oturur ve her yeni denemeyi kendine çeker. İşe yarayan yöntem:</p><ol><li>Bozuk değişiklikleri git ile geri alın.</li><li>Mevcut oturumdan kısa bir özet isteyin: ne denendi, ne başarısız oldu, hata mesajları ne dedi.</li><li>Yeni bir oturum başlatın ve bu özeti ona verin.</li></ol><p>Bir saat boyunca çırpınan aynı model, temiz bir context ile genelde sorunu dakikalar içinde çözer. Daha akıllı olmadı; sadece artık kendi başarısızlıklarına takılı kalmıyor.</p><h4>CLAUDE.md Boyutunun Gizli Maliyeti</h4><p>CLAUDE.md her oturumda otomatik yüklenir. 2.000 token’lık bir CLAUDE.md, her mesaja ekstra maliyet ekler. 1.000 mesaj boyunca bu, göz ardı edilemeyecek gizli bir maliyet haline gelir. CLAUDE.md’nizi kısa ve odaklı tutmanın bir nedeni daha.</p><h3>Bölüm 4: Derin Araştırma: AI’dan Maksimum Değer Elde Etmek</h3><h4>Neden Önemli?</h4><p>Derin araştırma, AI kullanım yolculuğumda en büyük verimlilik artışını sağlayan yaklaşımdır. Bir projeye başlamadan veya karmaşık bir karar vermeden önce AI’ın “derin düşünme” modunu kullanarak kapsamlı araştırma yapmak, saatlerce sürecek deneme yanılmayı dakikalara indirebilir.</p><h4>İş Akışım</h4><p>Derin araştırmayı tek bir araca bağlamıyorum. Claude.ai, ChatGPT, Gemini; hepsinin derin araştırma veya benzeri modları var ve her birinin farklı güçlü yönleri var. Önemli olan araç değil, süreçtir:</p><p><strong>Adım 1: Bir konuşmayla başlayın.</strong> Konu hakkında AI ile sohbet edin. Ama sadece soru sormayın; AI’ın size soru sormasını isteyin. “Bu konu hakkında bana sorular sor, gereksinimlerimi anlayalım” deyin. Bu adım kritik çünkü AI’ın hangi bilgiye ihtiyaç duyduğunu ortaya çıkarır.</p><p><strong>Adım 2: AI’ın sorularını yanıtlayın.</strong> AI size 10–15 soru soracaktır. Yanıtlayın. Bu süreç hem kendi düşüncenizi netleştirir hem de AI’a zengin context sağlar.</p><p><strong>Adım 3: Derin araştırma prompt’unu oluşturun.</strong> Konuşmanın sonunda AI’a “şimdi bu konuşmaya dayanarak bana bir derin araştırma prompt’u oluştur” deyin. AI, konuşmadaki tüm bağlamı içeren detaylı, odaklı bir araştırma prompt’u üretecektir.</p><p><strong>Adım 4: Derin araştırmaya gönderin.</strong> Bu prompt’u Claude.ai’ın extended thinking moduna, ChatGPT’nin deep research moduna veya Gemini’nin deep research özelliğine gönderin. Sonuçları karşılaştırın.</p><p><strong>Adım 5: Sonuçları Claude Code’a getirin.</strong> Araştırma sonuçlarını Claude Code oturumunuza getirin. Artık projenize sağlam bir bilgi temeli ile başlıyorsunuz.</p><h4>Derin Araştırmayı Ne Zaman Kullanmalısınız?</h4><ul><li>Yeni bir teknoloji veya framework seçerken</li><li>Karmaşık mimari kararlar (monolit vs mikroservis, event-driven vs request-driven)</li><li>Performans optimizasyon stratejileri</li><li>Güvenlik yaklaşımı belirlerken</li><li>Büyük bir refactoring öncesi strateji</li><li>Aşina olmadığınız bir alandaki en iyi pratikler</li></ul><h4>Önemli Nokta</h4><p>Derin araştırma “Google’da arama yapmak” değildir. AI’ın büyük miktarda bilgiyi sentezleyip, kaynaklarıyla birlikte sizin özel durumunuza özel detaylı bir analiz sunmasıdır. Bu çıktılar, doğrudan CLAUDE.md’ye veya proje dokümantasyonuna eklenerek Claude Code oturumlarınızın kalitesini dramatik şekilde artırabilir.</p><h3>Bölüm 5: İzin Modları ve Plan-Execute-Verify Döngüsü</h3><h4>İzin Modları</h4><p>Claude Code’da Shift+Tab ile üç izin modu arasında geçiş yapabilirsiniz:</p><p><strong>Normal Mode</strong>: Her dosya düzenlemesi ve komut çalıştırması için onay ister. En güvenli, en yavaş.</p><p><strong>Auto-Accept Mode</strong>: Dosya düzenlemelerini otomatik olarak onaylar. “Ne yaptığını biliyorsun, devam et” demenin yolu. Bash komutları için hâlâ onay ister.</p><p><strong>Bypass Mode</strong>: Tüm izinleri otomatik olarak onaylar. Güvenilir, iyi tanımlanmış görevlerde işleri hızlandırır. Ancak bu mod ancak hook güvenlik ağınız (Bölüm 6) mevcutsa mantıklıdır: deterministik korkuluklar izleme işini sizin yerinize yapar. Hook’lar olmadan Bypass, güvenliği kaldırılmış Normal Mode’dan başka bir şey değildir.</p><p>Bu modları bir stil tercihi değil, bir güven merdiveni olarak ele alıyorum. Yeni bir projede Normal Mode ile başlayın. Modelin kod tabanınızda nasıl çalıştığını izleyip nerede tökezlediğini öğrendikten sonra Auto-Accept’e geçin. Bypass’ı sadece bunu hak etmiş görev türlerine açın, tehlikeli noktaları hook’lar kapsasın. İlk günden tam otonomi vermek, insanların silinmiş dosyalar ve force-push’lanmış branch’lerle sonuçlanmasının yoludur.</p><h4>Plan Mode: Ayrı Bir Çalışma Modu</h4><p>Plan Mode, izin modlarından bağımsız bir çalışma modudur. Bu modda Claude hiçbir değişiklik yapamaz; yalnızca analiz eder ve plan önerir. Büyük değişikliklerden önce strateji belirlemek için inanılmaz değerlidir.</p><p>Ama Plan Mode’a girmeden önce bir adım var: <strong>hizalama</strong>. AI’a “bir auth sistemi kur” dediğinizde, ilk 5 dakikada 30 karar verir: JWT mı session mı, e-posta doğrulama var mı yok mu, OAuth mı sadece şifre mi, hata mesajları nasıl görünmeli. Sonucu görene kadar hangi kararları verdiğini bilemezsiniz.</p><p>Çözüm: planlamadan önce AI’ın gri alanları belirlemesini ve size somut sorular sormasını sağlayın. Şöyle deyin: “Bu özelliği planlamadan önce, gri alanları ve birden fazla makul yaklaşımın olduğu noktaları belirle, sonra bana sor.” AI’ın belirsiz noktaları yapılandırılmış seçenekler olarak sunmasını sağlayın: “Oturum yönetimi: A) JWT refresh rotation, B) Redis sunucu taraflı oturum, C) sizin tercihiniz.”</p><p>Bu 10 dakikalık hizalama oturumu, implementasyon ortasında yön düzeltmekten çok daha ucuzdur; hem token hem de zaman açısından.</p><h4>Plan -&gt; Execute -&gt; Verify Döngüsü</h4><p>Bu, benim için en tutarlı şekilde karşılığını veren çalışma kalıbı ve CTO zihniyetinin pratik uygulamasıdır:</p><ol><li><strong>Plan Mode’a geçin</strong>: Claude’un projeyi analiz etmesine ve ne yapacağını planlamasına izin verin</li><li><strong>Planı inceleyin</strong>: Mantıklı mı? Eksik bir şey var mı? Gerekirse düzeltme isteyin</li><li><strong>Auto-Accept’e geçin</strong>: Claude’un planı uygulamasına izin verin</li><li><strong>Doğrulayın</strong>: Build çalışıyor mu? Testler geçiyor mu? Beklenen davranış sağlanıyor mu?</li></ol><p>Burada kritik bir ayrım var: “tüm adımlar tamamlandı” doğrulama değildir. Gerçek doğrulama, sonuçları gözlemlemektir. Doğrulama kriterlerini tanımlarken üç katmanda düşünün:</p><ul><li><strong>Davranışsal</strong>: “Kullanıcı giriş yapabiliyor mu?” Çalıştırıp gözlemlemeniz gerekir.</li><li><strong>Yapısal</strong>: “auth.ts gerçek bir implementasyon mu, yoksa TODO’lar ve return null ile dolu bir stub mı?&quot; Dosyanın var olması yetmez; içeriğin gerçek olması gerekir.</li><li><strong>Bağlantısal</strong>: “Login handler, auth modülündeki fonksiyonu gerçekten import edip kullanıyor mu?” Dosyalar birbirinden bağımsız olarak var olabilirken birbirine bağlı olmayabilir.</li></ul><p>Bu yaklaşıma “goal-backward verification” (hedefe geriye dönük doğrulama) deniyor. “Ne yaptım?” yerine “ne olması gerekiyordu ve oluyor mu?” diye sorarsınız. AI destekli geliştirmede özellikle kritik, çünkü AI’ın en yaygın başarısızlık modu şudur: dosyalar var, build geçiyor, ama parçalar birbirine bağlı değil.</p><p>Bu döngüyü özellikle birden fazla dosyayı etkileyen değişiklikler için kullanıyorum. Claude’un ne yapacağını önce görmek, sonra onaylamak hem zaman kazandırır hem de hata riskini azaltır.</p><h3>Bölüm 6: Hook’lar: Deterministik Güvenlik Ağları</h3><h4>Felsefe</h4><p>Hook’ları şöyle düşünün: Claude bir olasılık makinesidir. Çoğu zaman doğru şeyi yapar, ama bazen yapmaz. Hook’lar, “kesinlikle yapmaması gereken şeyleri yapamayacağını” garanti eden mekanik kilitlerdir.</p><p>AI’ın olasılıksal doğasına deterministik garantiler ekliyorsunuz. Bu, AI destekli geliştirmenin temel güvenlik prensibidir.</p><p>Ayrım çizgisi şu: tek bir başarısızlık mali zarara veya güvenlik riskine yol açabiliyorsa, deterministik garanti şarttır. Gerisi prompt’larla yönetilebilir. Bununla birlikte, günlük sürtünmeyi azaltan ucuz hook’lar da edinmeye değer; sadece güvenlik açısından kritik olanlar kadar zorunlu değiller.</p><h4>Hook Türleri</h4><p>Claude Code, beş farklı noktada hook çalıştırmanıza izin verir:</p><ul><li><strong>PreToolUse</strong>: Bir tool çağrılmadan önce (engelleme yeteneği)</li><li><strong>PostToolUse</strong>: Bir tool çağrıldıktan sonra (doğrulama yeteneği)</li><li><strong>SessionStart</strong>: Bir oturum başladığında (ortam kurulumu)</li><li><strong>UserPromptSubmit</strong>: Kullanıcı mesaj gönderdiğinde (girdi kontrolü)</li><li><strong>Stop</strong>: Agent durduğunda (temizlik)</li></ul><h4>Başlangıç İçin 3 Hook</h4><p>Tüm hook ekosistemini bir anda kurmaya çalışmak yerine, şu üçüyle başlayın:</p><p><strong>1. Tehlikeli Git Koruması (PreToolUse:Bash)</strong>: git push --force, git reset --hard, git checkout . gibi yıkıcı git komutlarını engeller. Bu hook tek başına beni sayısız kez kurtardı.</p><p><strong>2. Conventional Commits (PreToolUse:Bash)</strong>: Commit mesajlarının feat(scope): description formatına uymasını zorunlu kılar. Bu hook olmadan Claude bazen &quot;fix stuff&quot; gibi anlamsız commit mesajları oluşturuyor.</p><p><strong>3. Convention Guard (PostToolUse:Edit|Write)</strong>: Her dosya yazımında projenize özel kuralları kontrol eder. Örneğin, bir TypeScript projesinde: any tip kullanımı, console.log kalıntıları, @ts-ignore kullanımı. İş bölümüne dikkat edin: linter&#39;ınız zaten genel stil kurallarını mekanik olarak yakalıyor, o yüzden Biome veya ESLint&#39;in bedavaya sağladığı şeyi Claude&#39;a öğretmek için context harcamayın. Bu hook, yalnızca projenizin bildiği kurallar içindir.</p><h4>İleri Düzey: Architecture Guard</h4><p>Bu, backend projemizdeki en değerli hook. Her dosya değişikliğinde Clean Architecture katman ihlallerini otomatik olarak kontrol eder. Örneğin, Domain katmanında EF Core import’u veya Application katmanında Infrastructure referansı varsa, hook yakalar ve engeller.</p><p>Bunun gibi domain’e özel hook’lar, projenizin mimari bütünlüğünü AI kaynaklı hatalara karşı korur.</p><h3>Bölüm 7: Custom Agent’lar: Uzman AI Ekibinizi Kurun</h3><h4>Agent Nedir?</h4><p>Agent, belirli bir görev için uzmanlaşmış bir Claude instance’ıdır. .claude/agents/ dizininde markdown dosyaları olarak yaşarlar. Her agent&#39;ın bir system prompt&#39;u, tool kısıtlamaları ve model seçimi vardır.</p><h4>Custom Agent’ları Neden Kullanmalısınız?</h4><p>Genel amaçlı Claude’a “güvenlik incelemesi yap” demekle, güvenlik konusunda uzmanlaşmış bir agent’a aynı şeyi demek arasında ciddi bir kalite farkı vardır. Çünkü custom bir agent:</p><ul><li>Tool kısıtlamaları sayesinde <strong>yalnızca yapması gerekeni yapar</strong></li><li><strong>Odaklanmış context ile çalışır</strong> (yalnızca kendi alanıyla ilgili bilgiler yüklenir)</li><li><strong>Tutarlı yaklaşım sergiler</strong> (her seferinde aynı kontrol listesini takip eder)</li><li><strong>Alan bilgisi taşır</strong> (OWASP kontrol listesi, projeye özel güvenlik kuralları)</li></ul><h4>Temel Agent Stratejisi</h4><p>Her proje için en az şu ikisini oluşturmanızı öneririm:</p><p><strong>Code-reviewer agent</strong>: Kod kalitesi, pattern uyumu, SOLID prensipleri, adlandırma kurallarını kontrol eder. Model olarak Sonnet yeterlidir.</p><p><strong>Debugger agent</strong>: Hata analizi, kök neden tespiti, log incelemesi yapar. Read ve Bash tool’larıyla sınırlayın; düzeltmeyi siz onaylayın.</p><h3>Bölüm 8: Multi-Agent Çalışma: Gerçek Güç Çarpanı</h3><h4>Subagent’lar ve Context Avantajı</h4><p><strong>Subagent’lar</strong>, kısa ömürlü, odaklı görevler için oluşturulan bağımsız Claude instance’larıdır. Kritik nokta şudur: her subagent’ın kendi bağımsız context’i vardır. Bu ne demek?</p><p>Ana oturumunuz context’inin %40&#39;ını zaten kullanmış olsa bile, bir subagent tamamen temiz bir context ile başlar. Bu, context yönetimi açısından devrim niteliğinde bir avantajdır. Araştırma görevlerini, kod incelemelerini ve dosya aramalarını subagent’lara devrettiğinizde, ana oturumunuzun context’i şişmez.</p><h4>Team’ler: Kalıcı Koordinasyon</h4><p>Agent Team’ler, birden fazla Claude Code instance’ını bir ekip olarak koordine etmenize olanak tanır. Subagent’lardan farklı olarak: ekip üyeleri kalıcıdır, birbirlerine mesaj gönderebilir ve paylaşımlı görev listesine erişebilir.</p><p><strong>Subagent’ları ne zaman kullanmalı?</strong></p><ul><li>Tek seferlik görevler: dosya arama, hızlı kod incelemesi, format kontrolü</li><li>Devam etmeden önce sonucu beklemeniz gereken görevler</li></ul><p><strong>Team’leri ne zaman kullanmalı?</strong></p><ul><li>Kapsamlı PR incelemesi (güvenlik + kalite + performans + test kapsamı paralel olarak)</li><li>Büyük feature geliştirme (backend + frontend + test paralel olarak)</li><li>Karmaşık refactoring (yalnızca modüller gerçekten bağımsızsa; bkz. Bölüm 14)</li></ul><h4>Pratik Senaryo: Kapsamlı Kod İncelemesi</h4><p>Bir PR incelemeniz gerekiyor. CTO gibi düşünün: sadece “kod güzel mi?” diye sormayın, tüm boyutları inceleyin:</p><pre>Team Lead (you): Coordination<br>Teammate 1: Security review (OWASP, input validation, auth)<br>Teammate 2: Code quality (patterns, SOLID, cleanliness)<br>Teammate 3: Performance analysis (N+1 queries, memory leaks, caching)<br>Teammate 4: Test coverage (missing tests, edge cases)</pre><p>4 agent paralel çalışır, her biri kendi uzmanlık alanında derinlemesine inceleme yapar. Sonuçlar kapsamlı bir inceleme raporunda birleştirilir. Bunu tek başınıza yapmaya çalışsanız saatler sürer; paralel agent’larla dakikalar içinde tamamlanır.</p><p>Dürüst bir uyarı: dört agent dört rapor üretir ve birinin bunları uzlaştırması gerekir. Paralellik keşfi hızlandırır, ama inceleme çıktısını da katlar. Bir sentez adımı için bütçe ayırın, ya da daha iyisi, bulgular size ulaşmadan önce bir agent’a birleştirip tekrarları ayıklamasını yaptırın. Bölüm 11, verimliliğinizin sınırını üretim hızının değil, bu uzlaştırma maliyetinin belirlediğini ele alıyor.</p><h3>Bölüm 9: Model Routing: Doğru İş İçin Doğru Model</h3><h4>Üç Model, Üç Amaç</h4><p><strong>Haiku</strong>: Hızlı, ucuz. Basit aramalar, dosya bulma, format kontrolleri, hızlı sorular için ideal.</p><p><strong>Sonnet</strong>: Dengeli. Standart implementasyon, debugging, kod incelemesi ve günlük işlerin çoğu için varsayılan tercihiniz olmalı.</p><p><strong>Opus</strong>: Derin akıl yürütme. Karmaşık mimari kararlar, zor bug’lar, büyük refactoring, güvenlik denetimleri için.</p><h4>Strateji</h4><p>Kural basit: varsayılan olarak Sonnet kullanın. Yalnızca gerçekten ihtiyaç duyduğunuzda Opus’a geçin. Basit görevleri Haiku’ya yönlendirin.</p><p>Ama karmaşıklık tek eksen değil. Görev uzunluğu da önemlidir: uzun otonom çalışmalarda, bir modelin adım başına güvenilirliği ham zekasından daha çok sayar. Bölüm 13, bunun nedenini matematiksel olarak ele alıyor.</p><p>Yönlendirmenin maliyet etkisi gerçek. Yüzde noktasına kadar ölçmedim, ama her şeyi Opus’ta çalıştırmayı bıraktığımdan beri günlük harcamamdaki fark açıkça görülüyor, kabaca yarı yarıya veya daha fazla.</p><h3>Bölüm 10: Çapraz Model Orkestrasyonu: Farklı AI’ları Birlikte Kullanmak</h3><h4>Tek Bir Model Yetmez</h4><p>Farklı AI modellerini birlikte kullanmak, beklediğimden daha fazla karşılığını verdi.</p><p><strong>Claude Opus</strong>: Derin akıl yürütme oturumları için orkestratörüm. Karmaşık mimari kararlar, çok adımlı planlama, büyük resmi görme. Bu, önceki bölümdeki Sonnet-varsayılan kuralıyla çelişmiyor: günlük implementasyon Sonnet’te kalır, Opus ise kararların yanlış gitmesinin maliyetli olduğu oturumlarda kendini kanıtlar.</p><p><strong>OpenAI Codex/GPT</strong>: Kod analizi, planlama doğrulaması, eleştirel düşünme. Özellikle farklı bir “bakış açısı” sağlamak için değerli.</p><p><strong>Google Gemini</strong>: Büyük context window (1M token), bir görev gerçekten çok sayıda dosyayı tek seferde okumayı gerektirdiğinde işe yarar. Ama büyük pencere bağışıklık anlamına gelmez: Bölüm 3&#39;teki seçim kuralları burada da geçerlidir ve şişirilmiş bir 1M context, şişirilmiş bir 200k context ile aynı şekilde çürür.</p><h4>Neden Önemli?</h4><p>Her AI modelinin kendi güçlü yönleri, zayıf yönleri ve “kör noktaları” vardır. Tek bir modele bağımlı olduğunuzda, o modelin kör noktalarını fark edemezsiniz. Farklı modelleri birlikte kullanmak daha sağlam ve çok yönlü analiz sağlar.</p><h3>Bölüm 11: Doğrulama Darboğazdır</h3><h4>Üretmek Ucuz, Kontrol Etmek Değil</h4><p>AI’ı orkestra etmeye başladığınızda kimsenin sizi uyarmadığı sorun şu: kod üretmek artık kısıtlayıcı faktör değil. Claude, benim bir günümü alan işi bir saatte üretiyor. Ama o bir saatlik çıktıyı düzgünce doğrulamak (diff’i okumak, akışları çalıştırmak, uç noktaları kontrol etmek) dikkatimin birkaç saatini yiyebiliyor.</p><p>Ve dikkat, agent’lar gibi ölçeklenmiyor. Teşviki sonuna kadar takip edin: inceleme, üretimden daha maliyetli hale geldiğinde, göz gezdirmeye başlarsınız. Sonra güvenmeye başlarsınız. Sonra bozuk bir şey production’a ulaşır ve “bitti” denilen şeyin hiçbir zaman doğrulanmadığı ortaya çıkar. Hiç kimse, işi kontrol etmenin onu istemekten on kat daha maliyetli olduğu bir iş akışını sürdüremez.</p><p>Bu, önceki bölümleri farklı bir ışıkta gösteriyor. Hook’lar (Bölüm 6) otomatikleştirilmiş doğrulamadır. Testler, dikkatiniz başka yerdeyken çalışan doğrulamadır. Bölüm 5&#39;teki Plan-Execute-Verify döngüsü işe yarar, çünkü Verify adımı kahramanlık değil, sistematik bir süreçtir. AI destekli geliştirmenin tavanı ne kadar üretebildiğiniz değildir. Tükenmeden ne kadar doğrulayabildiğinizdir.</p><h4>Üretici Kendi İşini Asla Notlandırmamalı</h4><p>Bildiğim en yüksek kaldıraçlı doğrulama hilesi: kodu yazan oturumun o kodu değerlendirmesine asla izin vermeyin.</p><p>Şu deneyi yapın. Claude’a gerçekten karmaşık bir şey yazdırın, aynı anda birden fazla alana dokunan türden bir değişiklik. Başarı ilan ettiğinde yeni bir oturum açın, aynı diff’i gösterin ve şöyle deyin: “Bu değişikliği inceliyorsun. Görevin sorunları bulmak.” Az önce “her şey çalışıyor” diyen aynı model, size gerçek sorunların bir listesini verecektir.</p><p>Bu bir tesadüf değil. Şirketlerin geliştiricileri test uzmanlarından ayırmasının nedeni de aynı: yazarın context’i işi bitirme niyetiyle kirlenmiştir, temiz context’e sahip bir reviewer’ın ise tek bir hedefi vardır, yanlış olanı bulmak. Farklı çerçeveleme, farklı davranış.</p><p>Titizliği riske göre ölçeklendirin:</p><ul><li>Rutin değişiklik: temiz context’te tek bir inceleme geçişi</li><li>Önemli değişiklik: Bölüm 10&#39;daki kör nokta nedenleriyle, farklı bir modelle ikinci bir geçiş</li><li>Para veya güvenlik söz konusuysa: art arda birkaç geçiş temiz dönene kadar tekrarlayın</li></ul><h3>Bölüm 12: Her Tekrarlanan Hatayı Bir Sisteme Dönüştürün</h3><p>Claude’un stateless olmasının, çoğu insanın hiç harekete geçmediği bir sonucu var: model bir hatayı bir kere yaptıysa, aynı hatayı tekrar yapacaktır, çünkü onu üreten koşullar değişmemiştir.</p><p>Bu yüzden basit bir kural takip ediyorum: aynı hatayı ikinci kez gördüğümde, onu kalıcı bir şeye dönüştürüyorum. Kabaca tercih sırasına göre:</p><ol><li><strong>Bir hook</strong>, mekanik olarak kontrol edilebiliyorsa (engellenen bir komut, yasak bir pattern)</li><li><strong>Bir test</strong>, regresyona uğrayabilecek bir davranışsa</li><li><strong>Bir CLAUDE.md notu veya skill</strong>, modelin sürekli kaçırdığı bir convention veya iş akışıysa</li></ol><p>İlk oluşum size bir düzeltmeye mal olur. Dönüştürme on dakikanıza mal olur. Sonrasındaki her oluşum size sonsuza kadar hiçbir şeye mal olmaz.</p><p>Bunu atlarsanız, aritmetik tersine döner. Kod tabanınızda aktif çalışan bir modelin onlarca tekrarlayan hata modu vardır ve her biri ara sıra bile yeniden ortaya çıksa, gününüz tanıdık hataları düzeltmekle eriyip gider. Daha da kötüsü, hiçbir zaman iyileşmez, çünkü düzelttiğiniz hiçbir şey hiçbir yerde kalıcı hale getirilmemiştir.</p><p>Model oturumlar arasında öğrenmez, ama sisteminiz öğrenebilir. Hook’lar birikir. Testler birikir. CLAUDE.md daha da netleşir. Altı ay sonra model aynıdır; kurulumunuz tanınmaz hale gelmiştir. Kendi kendine öğrenen bir sistemin pratikte anlamı budur: daha akıllı bir model değil, daha akıllı bir harness.</p><h3>Bölüm 13: Uzun Süren Görevler: Güvenilirlik Katlanarak Artar</h3><h4>%99,9 ve %99,99 Neden Neredeyse Aynı Değildir</h4><p>Bir agent’ın bir görevin her adımını zamanın %99,9&#39;unda doğru şekilde tamamladığını varsayalım. Kulağa mükemmel geliyor. Şimdi ona gece boyu süren türden uzun, otonom bir görev verin: bin adımlık okuma, düzenleme, çalıştırma, kontrol etme.</p><p>0,999&#39;un 1000. kuvveti yaklaşık 0,37&#39;dir. “Mükemmel” agent’ınız zamanın %37&#39;sinde temiz bir çalıştırma tamamlar.</p><p>Şimdi adım başına %99,99&#39;a sahip bir agent alın. Aynı bin adımda: yaklaşık %90 temiz çalıştırma. Yuvarlama hatası gibi görünen bir fark, geceyi güvenle bırakabileceğiniz bir agent’la bırakamayacağınız bir agent’ı birbirinden ayırıyor.</p><p>İki pratik sonuç var:</p><p><strong>Model seçimi görev uzunluğuyla değişir.</strong> 20 dakikalık bir görev için en akıllı modeli seçin. 10 saatlik bir çalıştırma için en tutarlı olanı, kendi adımlarını çift kontrol edeni seçin. Hatalar katlandığında titizlik, zekayı yener.</p><p><strong>Checkpoint’ler katlanmayı kırar.</strong> Yukarıdaki matematik, tek bir başarısızlığın her şeyi mahvettiğini varsayıyor, o yüzden başarısızlıkları geri döndürülebilir yapın:</p><ul><li><strong>Kilometre taşlarında commit’i zorunlu kılın.</strong> Agent’a her tamamlanan parçadan sonra commit yapmasını söyleyin. Bir hata o zaman tüm çalıştırmaya değil, bir rollback’e mal olur.</li><li><strong>Bir çalıştırma günlüğü tutun.</strong> Agent’a bir dosya tutturun: ne tamamlandı, ne kaldı, ne ters gitti ve nasıl ele alındı. Kesintiye uğrayan bir çalıştırmayı, sıfırdan başlamak yerine bu dosyadan yeni bir agent devam ettirebilir.</li><li><strong>Önceden bütçe belirleyin.</strong> Zaman, token, kapsam. “Aynı sorunda üç denemeden sonra testler hâlâ başarısız oluyorsa, dur ve bildiklerini yaz” demek, agent’ın çıkışsız bir yolda tüm gece debelenmesine izin vermekten daha iyidir.</li></ul><p>Uzun görevleri, yolda bir şeyin ters gideceğini varsayarak planlayın. Hiçbir şey ters gitmezse, harika. Ters giderse, çalıştırma bunu göğüsler.</p><h3>Bölüm 14: Doğru Yapılan Paralellik</h3><h4>Agent Sayısı Bir Çarpan Değildir</h4><p>Naif varsayım: 10 agent = 10x hız. 10 agent’ı bir kod tabanının aynı kısmına yönlendirdiğinizde gerçekte olan şu: her agent’ın doğru bir değişiklik yapmak için kodun tutarlı bir resmine ihtiyacı vardır ve o resmi oluştururken başka bir agent onu geçersiz kılar. Birbirlerinin işinin üzerine yazarlar, birbirlerinin varsayımlarını bozarlar ve akşamınızı hasarı çözmeye harcarsınız. On agent, sıfır hızlanma.</p><p>Paralellik, işin bağımlılık grafiğini takip ettiğinde işe yarar:</p><ul><li><strong>Gerçekten bağımsız alanlara göre bölün.</strong> Frontend ve backend. Kod paylaşmayan iki servis. Ayrı git worktree’leri, bitince merge edilir. Hızlanmayı gerçek yapan şey bağımsızlıktır.</li><li><strong>Bir yazar, çok okuyucu.</strong> Değişiklikleri tek bir agent yaparken paralel subagent’lar ona araştırma besler: dosya keşfi, doküman arama, pattern arama. Yazmalar seri kalır, okumalar paralel çalışır, hiçbir şey çakışmaz.</li></ul><h4>Paralelleştirmenin En Güvenli Olduğu Şey Keşiftir</h4><p>Okumanın yan etkisi yoktur, bu da araştırmayı törensiz paralelleştirebileceğiniz tek yer yapar. Sürekli geri döndüğüm bir pattern: aynı soruyu iki veya üç agent’a bağımsız olarak verin, sonra başka bir agent’a raporlarını karşılaştırtın.</p><p>Değer, karşılaştırmada saklıdır. Raporlar çelişirse, bu orada belirsiz veya bozuk bir şey olduğuna dair güçlü bir sinyaldir; kendiniz bakın. Uyuşurlarsa, bunu kanıt yerine ölçülü bir kanıt olarak ele alın. Benzer verilerle eğitilmiş modeller kör noktalarını paylaşır ve aynı şekilde kendinden emin bir biçimde yanlış olabilir. Uyuşma aramayı daraltır; davayı kapatmaz.</p><p>Bir kural daha: tek agent döngüsü çalışmadan paralelleştirmeyin. Yön yanlışsa, on agent sizi yanlış yere on kat daha hızlı götürür. Önce sistemi sağlamlaştırın (context, doğrulama, checkpoint’ler), paralellik ancak o zaman zaten çalışan bir şeyin üzerine çarpan etkisi yapar.</p><h3>Bölüm 15: Test, Güvenlik ve Performans: CTO Kontrol Listesi</h3><h4>AI Destekli Geliştirmede Test</h4><p>AI ile kod yazmanın en büyük tuzağı: “şunu hızlıca bitireyim, testleri sonra yazarım.” Testler olmadan AI’ın ürettiği kodu doğrulayamazsınız.</p><p><strong>Kural</strong>: AI’a bir feature yazdırırken, aynı prompt’ta testleri de yazmasını isteyin. “Bu feature’ı implement et ve testlerini yaz, sonra testleri çalıştır” deyin. Doğrulama kriterleri size prompt’ta bir ekstra cümleye mal olur ve karşılığında gelen sonucu değiştirir.</p><h4>Güvenlik Taraması</h4><p>CTO zihniyetiyle, her PR öncesinde güvenlik kontrolleri yapın:</p><ol><li><strong>Hardcoded secret taraması</strong>: API key’leri, şifreleri, token’ları arama</li><li><strong>Input validation kontrolü</strong>: Kullanıcı girdileri doğrulanıyor mu?</li><li><strong>OWASP Top 10 incelemesi</strong>: SQL injection, XSS, CSRF riskleri var mı?</li><li><strong>Dependency güvenliği</strong>: Bilinen güvenlik açıklarına sahip paketler var mı?</li></ol><h4>Performans: Optimize Etmeden Önce Ölçün</h4><p>AI ile performans çalışmasının bir tuzağı var: model, işaret ettiğiniz şeyi gerçek sorun olup olmadığına bakmadan seve seve optimize eder. O yüzden sıra önemlidir: önce ölçün, sonra devredin. N+1 query kontrolü, eksik index, tek parça yüklenmek yerine stream edilmesi gereken payload için isteyin. Somut, kontrol edilebilir istekler (“bu endpoint’i profille ve zamanın nereye gittiğini göster”) gerçek yanıtlar alır; “daha hızlı yap” ise tahmin işi verir.</p><h3>Bölüm 16: Yapın ve Yapmayın</h3><h4>Yapın</h4><ol><li><strong>Her proje için iyi bir CLAUDE.md yazın.</strong> Bu dosya olmadan Claude projenizi bilmez.</li><li><strong>Context’i aktif olarak yönetin.</strong> HUD’daki context çubuğunu ve maliyet bilgisini izleyin, /compact ile erken aksiyon alın, /clear ile temiz başlayın.</li><li><strong>Plan Mode’u alışkanlık haline getirin.</strong> Büyük değişikliklerden önce ne yapılacağını görün, sonra onaylayın.</li><li><strong>Doğrulama kriterleri belirleyin.</strong> “Test yaz” değil, “edge case’leri kapsayan testler yaz ve npm test ile çalıştır.&quot;</li><li><strong>Hook’larla güvenlik ağı örün.</strong> En az 3 temel hook ile başlayın.</li><li><strong>Subagent’ları cömertçe kullanın.</strong> Araştırma, inceleme ve arama görevlerini devredin. Ana context’inizi temiz tutun.</li><li><strong>Derin araştırma ile başlayın.</strong> Karmaşık görevlerde önce araştırın, sonra implement edin.</li><li><strong>Model routing uygulayın.</strong> Basit görevler için Haiku, varsayılan olarak Sonnet, derin analiz için Opus.</li><li><strong>Örnekle öğretin.</strong> Üç paragraflık açıklama yerine, bir kod parçacığı gösterin.</li><li><strong>Oturumları kısa tutun.</strong> Bir konuşma = bir görev. Context patlaması = kalite çöküşü.</li><li><strong>Tekrarlanan hataları sisteme dönüştürün.</strong> Bir hatanın ikinci oluşumu bir hook, bir test veya bir CLAUDE.md notu kazanır (Bölüm 12).</li><li><strong>Üreteni doğrulayandan ayırın.</strong> Temiz context’teki bir inceleme, yazan oturumun göremediğini görür (Bölüm 11).</li></ol><h4>Yapmayın</h4><ol><li><strong>Claude’u linter olarak kullanmayın.</strong> ESLint, Biome, Prettier zaten var. “İki boşluk kullan” gibi kurallar context israfıdır.</li><li><strong>CLAUDE.md’yi romana çevirmeyin.</strong> 100 satırın altında tutun. Progressive disclosure kullanın.</li><li><strong>Doğrulamadan güvenmeyin.</strong> Claude’un “bitti” demesi yetmez. Build, test, güvenlik; doğrulayın.</li><li><strong>Aşırı mühendislik yapmasına izin vermeyin.</strong> CLAUDE.md’de açıkça belirtin: “ekstra soyutlama ekleme, gereksiz interface oluşturma.”</li><li><strong>Test yazmayı ertelemeyin.</strong> Test edilmemiş AI çıktısı, doğrulanmamış çıktıdır.</li><li><strong>Sistem çalışmadan paralelleştirmeyin.</strong> Bozuk bir döngüdeki on agent, on kat daha hızlı kaybeder (Bölüm 14).</li></ol><h3>Sonuç: Yolculuk Devam Ediyor</h3><p>Claude Code benim için “terminalde AI” olarak başladı. Şimdi tam bir geliştirme ekosistemi. CLAUDE.md stratejisi, context yönetimi, hook pipeline’ları, custom agent’lar, multi-agent orkestrasyon, çapraz model kullanımı, kendi kendine öğrenen sistemler; bunların hepsini aylarca süren bir süreçte kademeli olarak öğrendim.</p><p>En önemli ders şudur: AI araçlarının gerçek gücü hangi düğmeye bastığınızdan değil, nasıl düşündüğünüzden gelir. CTO gibi düşünün: sadece kod yazmak değil, planlamak, test etmek, güvenliği sağlamak, performansı ölçmek ve bunların hepsini sistematik olarak yapmak.</p><p>Burada adil bir itiraz var: daha akıllı modeller tüm bu kurulumu gereksiz kılmayacak mı? Ben tam tersine bahse girerim. Daha akıllı modeller devredebileceğiniz şeyin tavanını yükseltir ve bu makaledeki her şey (doğrulama, context disiplini, checkpoint’ler) o devretmeyi gerçekten mümkün kılan şeydir. Model yeteneği, operatör becerisiyle çarpılır. Yetenek büyüdükçe, sistem kuran insanlarla prompt yazan insanlar arasındaki fark büyür.</p><p><strong>Başlamak için:</strong></p><ol><li>İyi bir CLAUDE.md yazın</li><li>Context yönetimini öğrenin (%40 kuralı)</li><li>3 temel hook’u kurun</li><li>Plan Mode’u alışkanlık haline getirin</li><li>Üreteni doğrulayandan ayırın</li></ol><p>Unutmayın: araçlarınızı keskinleştirmenin en iyi yolu, onları her gün kullanmaktır.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=64cab2c7305c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop Writing Code, Start Managing Systems: The Real Potential of AI-Powered Development]]></title>
            <link>https://senrecep.medium.com/stop-writing-code-start-managing-systems-the-real-potential-of-ai-powered-development-71fafeb144de?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/71fafeb144de</guid>
            <category><![CDATA[developer-productivity]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-assisted-development]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Sat, 28 Feb 2026 01:46:39 GMT</pubDate>
            <atom:updated>2026-08-08T13:21:42.183Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0XOiT4M5zP976ZgVjO7n7Q.png" /><figcaption>Orchestrate your AI agents, stop writing code</figcaption></figure><p><strong>Bu makaleyi Turkce okuyun:</strong> <a href="https://medium.com/%40senrecep/kod-yazmay%C4%B1-b%C4%B1rak%C4%B1n-sistemi-y%C3%B6netin-ai-destekli-geli%C5%9Ftirmenin-ger%C3%A7ek-potansiyeli-64cab2c7305c">Kod Yazmayi Birakin, Sistemi Yonetin: AI Destekli Gelistirmenin Gercek Potansiyeli</a></p><h3>Introduction: I Was Already Using AI Tools</h3><p>I’m not going to start this article with “what is Claude Code and how do you install it.” Because most people reading this are already using some AI tool. Cursor, Copilot, Windsurf, maybe ChatGPT; we’ve tried them all, we’ve seen their strengths and weaknesses.</p><p>I was no different. I’ve been developing software for years, and in recent years I’ve been using AI tools intensively. I started with Cursor, got a taste of the comfort of AI-assisted development inside an IDE. But at some point I hit a wall: as my project grew, the quality of AI’s responses started to decline. Because IDE-based tools offer you an “assistant”: you write, it completes. Nice, but limited.</p><p>When I switched to Claude Code, the paradigm shifted. This isn’t an assistant, it’s a development environment. A system that runs in the terminal, reads your files, executes commands, performs git operations, and can even spawn other AI instances to run in parallel. But the real power lies in how you configure this system.</p><p>I’ve been using Claude Code for months in production across multiple projects, spanning different tech stacks (from .NET backends to React Native mobile apps, Go services to Next.js frontends). This article is the accumulation of those months. What I did right, what I did wrong, which approaches actually worked.</p><p>An important note: rather than reading this article as a “click this button, type this command” tutorial, I’d recommend reading it as a thinking framework. Because the real power of AI tools doesn’t come from which button you press, but from how you think.</p><h3>Section 1: You Need a Mindset Shift</h3><h4>Think Like a CTO, Not a Junior Developer</h4><p>The most common mistake in AI-powered development is seeing AI as “a thing that writes code for me.” “Write this function,” “fix this bug,” “add this API”; these are valid requests, but they’re only a small piece of the picture.</p><p>Real productivity emerges when you approach a project from A to Z like a CTO:</p><ul><li><strong>Planning</strong>: What are we building and why?</li><li><strong>Architecture</strong>: How will we structure it?</li><li><strong>Development</strong>: How will we implement it?</li><li><strong>Testing</strong>: How will we verify it works correctly?</li><li><strong>Security</strong>: How will we detect vulnerabilities?</li><li><strong>Performance</strong>: Is it fast enough?</li><li><strong>Deployment</strong>: How will we ship it?</li></ul><p>The real power of Claude Code is that it can help you at every stage of this lifecycle. Not just the “writing code” stage. And in this article, I’ll explain this approach in detail.</p><h4>Learn to Think Probabilistically</h4><p>AI is not a deterministic machine. Give it the same prompt twice, and you might get different results. This isn’t a bug, it’s the operating principle. Once you understand this principle, your way of working with AI fundamentally changes:</p><ul><li><strong>Don’t expect perfect results on the first try.</strong> Work iteratively. Review the first output, give feedback, try again.</li><li><strong>Build verification mechanisms.</strong> Just because AI said “done” doesn’t mean it’s done. Verify that the build works, tests pass, and security scans come back clean.</li><li><strong>Add deterministic layers.</strong> Hooks, linters, test suites; these are layers of certainty on top of AI’s probabilistic nature.</li></ul><p>When you start with this mindset, everything else becomes much easier.</p><h4>Learn to Work at the Speed of Thought</h4><p>You know what the biggest bottleneck is when working with AI? It’s not AI’s speed; it’s your speed of providing input. You spot a bug, you need to switch to the terminal, describe the problem, take a screenshot and paste it, switch back again. With every context switch you lose focus, your train of thought evaporates.</p><p>The solution: building a workflow where you can give AI input the moment you think of it. For me that means speech-to-text bound to a hotkey (talking is faster than typing, and prompts tolerate messy grammar), a clipboard manager that remembers everything I copied recently, and instant screenshot sharing for visual bugs. Like working with a human, being able to say “look, this part is broken, fix that too, oh and there’s also this.”</p><p>Keep this in mind: when working with AI, the thing slowing you down isn’t the AI; it’s your speed of transferring information to the AI.</p><h3>Section 2: CLAUDE.md: Your Project’s Strategic Brain</h3><h4>The File Every Session Starts With</h4><p>CLAUDE.md is the project instruction file that Claude Code automatically reads at the start of every conversation. Claude starts from scratch in every session; it doesn’t remember previous conversations. But thanks to this file, it “knows” your project.</p><p>This file is one of the biggest factors in the quality of your Claude Code experience. A good CLAUDE.md won’t replace engineering skill, but a bad one will frustrate even an expert.</p><h4>Less is More: The 100-Line Rule</h4><p>My first CLAUDE.md file exceeded 160 lines. I had written out every rule, every command in detail. The result? Claude was missing important information. Long file = scattered attention.</p><p>The solution: keep your CLAUDE.md under 100 lines. Move details to separate files. Claude will look at those files when needed.</p><pre>CLAUDE.md (70-100 lines)              - Always read<br>.claude/rules/architecture.md         - Referenced when needed<br>.claude/rules/security.md             - Referenced when needed<br>docs/claude/patterns.md               - Referenced when needed</pre><p>This approach is called “progressive disclosure”: revealing information gradually.</p><h4>The WHAT / WHY / HOW Structure</h4><p>An effective CLAUDE.md consists of three sections:</p><p><strong>WHAT</strong>: What is the project? Tech stack, architectural structure, core concepts. A single paragraph is enough.</p><p><strong>WHY</strong>: Why did we make these decisions? This part is critical. When Claude knows the “why,” it makes much better decisions in edge cases. For example, instead of just saying “don’t use console.log,” if you say “don’t use console.log because it causes performance issues in production and can leak sensitive data,” Claude understands that temporary use during development is acceptable.</p><p><strong>HOW</strong>: How do we work? Commands, test patterns, naming conventions. Teach by example here: one good code snippet communicates a convention better than three paragraphs describing it.</p><h4>The “Don’t” Section</h4><p>Always add a “Don’t” section to your CLAUDE.md. Claude has known tendencies:</p><ul><li>Tendency to over-engineer (extra abstractions, unnecessary interfaces)</li><li>Tendency to create too many files (splits things that could be solved in a single file)</li><li>Tendency to add error handling for impossible scenarios</li><li>Tendency to add docstrings and comments (even when not asked)</li><li>Tendency to create stub files (file exists but is filled with return null, return {}, TODO, console.log placeholders; the existence of a file doesn&#39;t mean real implementation)</li></ul><p>Explicitly stating these tendencies in CLAUDE.md is the cheapest way to avoid unnecessary work.</p><h4>3-Layer Boundary Setting</h4><p>Tell Claude clearly what it can do, when it should ask, and what it should never do:</p><ul><li><strong>Always do</strong>: Write tests, run tests, follow naming conventions</li><li><strong>Ask first</strong>: Database migrations, adding new dependencies, large refactoring</li><li><strong>Never do</strong>: Committing secrets, editing lock files, deleting tests</li></ul><p>These three layers show Claude the space where it can move confidently, while ensuring it informs you in dangerous areas.</p><h4>Global CLAUDE.md</h4><p>The ~/.claude/CLAUDE.md file contains global instructions that apply to all projects. I define my communication preferences (summaries in Turkish, technical terms in English), frequently used CLI tools, and general working principles here. This way I don&#39;t need to repeat them in every project.</p><h4>Path-specific Rules: Right Rule, Right File</h4><p>Here’s a scenario: you want to apply the same rules to all your test files. But test files are scattered across 50 different directories. Are you going to put a separate CLAUDE.md in each directory? Of course not.</p><p>You can define rules by file pattern in the .claude/rules/ directory:</p><pre>---<br>paths: [&quot;**/*.test.tsx&quot;]<br>---<br>Use AAA (Arrange-Act-Assert) pattern in test files.<br>Prefer real database connections over mocks.</pre><p>The **/*.test.tsx pattern catches all test files in the entire codebase, no matter which directory they&#39;re in. Same logic applies: **/*.api.ts for API endpoints, terraform/**/* for Terraform files - each with their own specific rules.</p><p>There’s a context advantage too: these rules only load when matching files are being edited. They don’t take up space in context permanently, they only kick in when relevant.</p><h3>Section 3: Context Window: The Most Critical Concept to Understand</h3><h4>What It Is and Why It Matters</h4><p>The context window is Claude’s working memory. Every message, every file read, every command output accumulates in this shared budget. On Opus, this budget is approximately 200,000 tokens.</p><p>Most developers assume things will work smoothly until context hits 100%.</p><p><strong>Reality:</strong> Degradation is gradual and starts well before the bar looks full. Past 60%, Claude forgets previous instructions, repeats the same mistakes, edits the wrong files. My practical rule: act around 40%, never wait for 60%.</p><p>But the problem isn’t just context “filling up” — it’s also actively <strong>decaying</strong>. This is known as “context rot.”</p><p>Old tool outputs, debug traces from bugs that were already fixed, stale versions of refactored files — all of it accumulates in context. The model can’t distinguish what’s current from what’s outdated. Stale information doesn’t just take up space; it actively causes harm. The model treats old data as current and makes decisions on top of it: references renamed variables, follows changed patterns.</p><p>This is why so many multi-agent setups fall apart after a handful of tasks. The model didn’t get dumber. The context got poisoned.</p><p>One caveat: this picture keeps improving. Models hold up better in long sessions with every release, and Claude Code keeps getting smarter about how it compacts, what it summarizes, and what it saves to memory. Today’s terminal agents stay coherent in situations that would have derailed them a year ago, sometimes even near a full window. So read the thresholds in this section as a mentality rather than physics: following them makes your sessions noticeably better, but they aren’t hard limits.</p><h4>One Conversation = One Task</h4><p>One habit holds regardless of where the thresholds land: one conversation, one task. Auth system + database schema + UI components + writing tests; don’t try to do all of them in a single conversation. Each should be a separate session.</p><p>You might think “but I just explained the context, do I have to explain it again in a new session?” No. CLAUDE.md knows your project, and your session memory holds the current state (the next subsection covers how). A new session doesn’t start from zero.</p><h4>Memory Between Sessions</h4><p>Claude is stateless; every conversation starts from scratch. There are various methods for carrying information between sessions. I use the project-memory feature of the OMC (oh-my-claudecode) plugin: a project-scoped store that keeps tech stack, architectural decisions, conventions, notes, and directives in JSON, and every session reads it automatically.</p><p>Whatever tool you use, the principle is the same: save what matters at session end, read it at session start.</p><h4>Practical Context Management</h4><p><strong>Use the HUD (Heads-Up Display)</strong>: Claude Code has a HUD in the terminal status bar. It shows you real-time information:</p><ul><li>Active model (Opus, Sonnet, Haiku)</li><li>Session duration</li><li>Token count spent</li><li>Current cost and hourly cost rate</li><li>Cache hit rate</li><li>Permission mode (Normal, Auto-Accept, Bypass); toggle with Shift+Tab</li></ul><p><strong>Context fill bar</strong>: the one to watch. Tracking it is the foundation of context management; you’ll see the moment it’s time to act.</p><p><strong>/compact timing</strong>: Run it proactively when the bar reaches the threshold above, before quality starts slipping.</p><p><strong>Clean start with </strong><strong>/clear</strong>: Start a new session when a task is completed or the topic changes.</p><p><strong>Information ordering matters</strong>: AI models process the beginning and end of long inputs well but can miss information buried in the middle. If you’re sending a long analysis result or error log, put the most critical information first. Starting with “there’s a null pointer in this function, relevant log output below” is far more effective than a clue buried in the middle of a 500-line log.</p><p><strong>Red flags</strong>: the symptoms listed at the top of this section (repetition, forgotten context, wrong files) mean cleanup is already overdue, not approaching.</p><h4>What Goes In Matters as Much as How Much</h4><p>Volume is only half of context management. The other half is selection. Three filters I apply before feeding anything in:</p><ul><li><strong>Recency</strong>: Is this data current? Stale API docs or an outdated schema don’t just waste space, they mislead. If something might be outdated, make Claude fetch the current version instead of pasting the old one.</li><li><strong>Relevance</strong>: Does this actually bear on the task? A 500-line log where 20 lines matter is 480 lines of noise the model has to see past.</li><li><strong>Your own signal</strong>: Tell the model where you stand. “I know this domain well, skip the basics” and “I’ve never touched Kubernetes, explain your choices” produce different, and correctly calibrated, answers.</li></ul><h4>Instructions and Data Are Not the Same Thing</h4><p>Selection has a companion problem: everything you type into the prompt arrives with your authority attached. The model reads all of it as “this is what the user wants,” which becomes a problem when half of it is just reference material: a long log, an API doc, someone else’s error report. Sentences inside that material can get picked up as directives, and the model starts acting on text you only meant as background.</p><p>Two habits fix this. For short material, wrap it in explicit markers (a fenced block, an XML-style tag) and label it: “the following is reference data, not instructions.” For anything long, don’t paste it at all. Save it to a file, even a temp one, and give Claude the path along with what you want done with it. The content then enters context as a tool result, which the model treats as data to interpret rather than commands to follow, and it decides for itself which parts are worth keeping. Your prompt stays what it should be: pure intent.</p><h4>When Claude Is Stuck in a Loop</h4><p>Sometimes the model keeps hitting the same error, trying small variations of the same broken fix. More prompting rarely saves a session in this state, because the failed attempts are sitting in context and dragging every new attempt toward them. What works:</p><ol><li>Revert the broken changes with git.</li><li>Ask the current session for a short summary: what was tried, what failed, what the error messages said.</li><li>Start a fresh session and hand it that summary.</li></ol><p>The same model that flailed for an hour will often solve the problem in minutes with a clean context. It didn’t get smarter; it’s just no longer anchored to its own failures.</p><h4>The Hidden Cost of CLAUDE.md Size</h4><p>CLAUDE.md is auto-loaded in every session. A 2,000-token CLAUDE.md adds extra cost to every message. Over 1,000 messages, this becomes a non-trivial hidden cost. Yet another reason to keep your CLAUDE.md short and focused.</p><h3>Section 4: Deep Research: Getting Maximum Value from AI</h3><h4>Why Does It Matter?</h4><p>Few things have boosted my productivity as much as deep research. Conducting comprehensive research using AI’s “deep thinking” mode before starting a project or making a complex decision can reduce hours of trial and error to minutes.</p><h4>My Workflow</h4><p>I don’t tie deep research to a single tool. Claude.ai, ChatGPT, Gemini; they all have deep research or similar modes, and each has different strengths. What matters isn’t the tool, it’s the process:</p><p><strong>Step 1: Start with a conversation.</strong> Chat with AI about the topic. But don’t just ask questions; ask the AI to ask you questions. Say “ask me questions about this topic, let’s understand my requirements.” This step is critical because it surfaces what information the AI needs.</p><p><strong>Step 2: Answer the AI’s questions.</strong> The AI will ask you 10–15 questions. Answer them. This process both clarifies your own thinking and provides the AI with rich context.</p><p><strong>Step 3: Generate the deep research prompt.</strong> At the end of the conversation, tell the AI “now create a deep research prompt for me based on this conversation.” The AI will produce a detailed, focused research prompt that incorporates all the context from the conversation.</p><p><strong>Step 4: Send it to deep research.</strong> Send this prompt to Claude.ai’s extended thinking mode, ChatGPT’s deep research mode, or Gemini’s deep research feature. Compare the results.</p><p><strong>Step 5: Bring the results to Claude Code.</strong> Bring the research results to your Claude Code session. Now you’re starting your project with a solid knowledge foundation.</p><h4>When Should You Use Deep Research?</h4><ul><li>Choosing a new technology or framework</li><li>Complex architectural decisions (monolith vs microservices, event-driven vs request-driven)</li><li>Performance optimization strategies</li><li>Determining security approach</li><li>Strategy before a major refactoring</li><li>Best practices in an area you’re unfamiliar with</li></ul><h4>Important Point</h4><p>Deep research is not “searching on Google.” It’s having AI synthesize large amounts of information and present a detailed analysis tailored to your specific situation, complete with sources. These outputs can dramatically increase the quality of your Claude Code sessions by being added directly to CLAUDE.md or project documentation.</p><h3>Section 5: Permission Modes and the Plan-Execute-Verify Loop</h3><h4>Permission Modes</h4><p>In Claude Code, you can toggle between three permission modes with Shift+Tab:</p><p><strong>Normal Mode</strong>: Asks for approval on every file edit and command execution. Safest, slowest.</p><p><strong>Auto-Accept Mode</strong>: Automatically approves file edits. The way to say “you know what you’re doing, carry on.” Still asks for approval on Bash commands.</p><p><strong>Bypass Mode</strong>: Automatically approves all permissions. Speeds things up on trusted, well-defined tasks. It only makes sense once your hook safety net exists (Section 6): the deterministic guardrails do the watching so you don’t have to. Bypass without hooks is Normal Mode with the safety removed.</p><p>I treat these modes as a trust ladder, not a style preference. Start in Normal Mode on a new project. Once you’ve watched the model work in your codebase and know where it stumbles, move to Auto-Accept. Extend Bypass only to task types that have earned it, with hooks covering the dangerous edges. Granting full autonomy on day one is how people end up with deleted files and force-pushed branches.</p><h4>Plan Mode: A Separate Working Mode</h4><p>Plan Mode is a working mode independent of permission modes. In this mode, Claude can’t make any changes; it only analyzes and proposes plans. Incredibly valuable for strategizing before big changes.</p><p>But there’s one step before entering Plan Mode: <strong>alignment</strong>. When you tell the AI “build an auth system,” it makes 30 decisions in the first 5 minutes: JWT or session, email verification or not, OAuth or password-only, how should error messages look. You don’t know which decisions it made until you see the result.</p><p>The solution: before planning, have the AI identify the grey areas and ask you concrete questions. Say: “Before planning this feature, identify the grey areas and points where multiple reasonable approaches exist, then ask me.” Let the AI present ambiguous points as structured options: “Session management: A) JWT refresh rotation, B) Redis server-side session, C) your preference.”</p><p>This 10-minute alignment session is far cheaper than correcting course mid-implementation — both in tokens and in time.</p><h4>The Plan -&gt; Execute -&gt; Verify Loop</h4><p>This is the working pattern that pays off most consistently for me, and the practical application of the CTO mindset:</p><ol><li><strong>Switch to Plan Mode</strong>: Let Claude analyze the project and plan what to do</li><li><strong>Review the plan</strong>: Does it make sense? Is anything missing? Request corrections if needed</li><li><strong>Switch to Auto-Accept</strong>: Let Claude implement the plan</li><li><strong>Verify</strong>: Does the build work? Do tests pass? Is the expected behavior achieved?</li></ol><p>There’s a critical distinction here: “all steps completed” is not verification. Real verification is observing outcomes. When defining verification criteria, think in three layers:</p><ul><li><strong>Behavioral</strong>: “Can the user log in?” You need to run it and observe.</li><li><strong>Structural</strong>: “Is auth.ts a real implementation, or a stub filled with TODOs and return null?&quot; The file existing isn&#39;t enough; the content has to be real.</li><li><strong>Connective</strong>: “Does the login handler actually import and use the function from the auth module?” Files can exist independently while not being connected to each other.</li></ul><p>This approach is called “goal-backward verification.” Instead of asking “what did I do?” you ask “what was supposed to happen, and is it happening?” Especially critical in AI-powered development, because the most common failure mode of AI is: files exist, build passes, but the pieces aren’t connected.</p><p>I use this loop especially for changes that affect multiple files. Seeing what Claude will do first, then approving it, both saves time and reduces error risk.</p><h3>Section 6: Hooks: Deterministic Safety Nets</h3><h4>Philosophy</h4><p>Think of hooks this way: Claude is a probability machine. Most of the time it does the right thing, but sometimes it doesn’t. Hooks are mechanical locks that guarantee “it absolutely cannot do things it shouldn’t do.”</p><p>You’re adding deterministic guarantees to AI’s probabilistic nature. This is the core safety principle of AI-powered development.</p><p>The dividing line: if a single failure can cause financial damage or security risk, a deterministic guarantee is essential. The rest can be managed with prompts. That said, cheap hooks that remove daily friction are still worth having; they just aren’t mandatory the way the safety-critical ones are.</p><h4>Hook Types</h4><p>Claude Code lets you run hooks at five different points:</p><ul><li><strong>PreToolUse</strong>: Before a tool is called (ability to block)</li><li><strong>PostToolUse</strong>: After a tool is called (ability to validate)</li><li><strong>SessionStart</strong>: When a session starts (environment setup)</li><li><strong>UserPromptSubmit</strong>: When a user sends a message (input control)</li><li><strong>Stop</strong>: When the agent stops (cleanup)</li></ul><h4>3 Hooks to Start With</h4><p>Instead of trying to build the entire hook ecosystem at once, start with these three:</p><p><strong>1. Dangerous Git Protection (PreToolUse:Bash)</strong>: Blocks destructive git commands like git push --force, git reset --hard, git checkout .. This hook alone has saved me numerous times.</p><p><strong>2. Conventional Commits (PreToolUse:Bash)</strong>: Enforces commit messages to follow the feat(scope): description format. Without this hook, Claude sometimes creates meaningless commit messages like &quot;fix stuff.&quot;</p><p><strong>3. Convention Guard (PostToolUse:Edit|Write)</strong>: Checks your project-specific rules on every file write. For example, in a TypeScript project: any type usage, console.log leftovers, @ts-ignore usage. Note the division of labor: your linter already catches generic style mechanically, so don&#39;t burn context teaching Claude what Biome or ESLint enforces for free. The hook is for rules only your project knows.</p><h4>Advanced: Architecture Guard</h4><p>This is the most valuable hook in my backend project. It automatically checks Clean Architecture layer violations on every file change. For example, if there’s an EF Core import in the Domain layer or an Infrastructure reference in the Application layer, the hook catches and blocks it.</p><p>Domain-specific hooks like this protect your project’s architectural integrity against AI-induced mistakes.</p><h3>Section 7: Custom Agents: Build Your Expert AI Team</h3><h4>What Is an Agent?</h4><p>An agent is a Claude instance specialized for a specific task. They live as markdown files in the .claude/agents/ directory. Each agent has a system prompt, tool constraints, and a model selection.</p><h4>Why Should You Use Custom Agents?</h4><p>There’s a significant quality difference between telling general-purpose Claude to “do a security review” versus telling a security-specialized agent the same thing. Because a custom agent:</p><ul><li><strong>Carries domain knowledge</strong> (OWASP checklist, project-specific security rules)</li><li><strong>Only does what it should</strong> thanks to tool constraints</li><li><strong>Works with focused context</strong> (only information relevant to its domain is loaded)</li><li><strong>Exhibits a consistent approach</strong> (follows the same checklist every time)</li></ul><h4>Essential Agent Strategy</h4><p>I recommend creating at least these two for every project:</p><p><strong>Code-reviewer agent</strong>: Checks code quality, pattern conformance, SOLID principles, naming conventions. Sonnet is sufficient as the model.</p><p><strong>Debugger agent</strong>: Performs error analysis, root cause identification, log examination. Limit it to Read and Bash tools; you approve the fix.</p><h3>Section 8: Multi-Agent Work: The Real Force Multiplier</h3><h4>Subagents and the Context Advantage</h4><p><strong>Subagents</strong> are independent Claude instances created for short-lived, focused tasks. The critical point is this: each subagent has its own independent context. What does this mean?</p><p>Even if your main session has already used 40% of its context, a subagent starts with a completely clean context. This is a revolutionary advantage in terms of context management. When you delegate research tasks, code reviews, and file searches to subagents, your main session’s context doesn’t bloat.</p><h4>Teams: Persistent Coordination</h4><p>Agent Teams let you coordinate multiple Claude Code instances as a team. Unlike subagents: team members are persistent, can message each other, and access a shared task list.</p><p><strong>When to use subagents?</strong></p><ul><li>One-off tasks: file search, quick code review, format checking</li><li>Tasks where you need to wait for the result before continuing</li></ul><p><strong>When to use teams?</strong></p><ul><li>Comprehensive PR review (security + quality + performance + test coverage in parallel)</li><li>Large feature development (backend + frontend + test in parallel)</li><li>Complex refactoring (only when the modules are genuinely independent; see Section 14)</li></ul><h4>Practical Scenario: Comprehensive Code Review</h4><p>You need to review a PR. Think like a CTO: don’t just ask “is the code nice?”, examine all dimensions:</p><pre>Team Lead (you): Coordination<br>Teammate 1: Security review (OWASP, input validation, auth)<br>Teammate 2: Code quality (patterns, SOLID, cleanliness)<br>Teammate 3: Performance analysis (N+1 queries, memory leaks, caching)<br>Teammate 4: Test coverage (missing tests, edge cases)</pre><p>4 agents work in parallel, each diving deep in their area of expertise. The results are combined into a comprehensive review report. If you tried to do this alone, it would take hours; with parallel agents, the finding phase is done in minutes.</p><p>One honest caveat: four agents produce four reports, and someone still has to reconcile them. Parallelism speeds up discovery, but it multiplies review output. Budget a synthesis step, or better, have one agent merge and deduplicate the findings before they reach you. Section 11 is about why that reconciliation cost, not generation speed, is what caps your throughput.</p><h3>Section 9: Model Routing: The Right Model for the Right Job</h3><h4>Three Models, Three Purposes</h4><p><strong>Haiku</strong>: Fast, cheap. Ideal for simple searches, finding files, format checks, quick questions.</p><p><strong>Sonnet</strong>: Balanced. Should be your default choice for standard implementation, debugging, code review, and most day-to-day work.</p><p><strong>Opus</strong>: Deep reasoning. For complex architectural decisions, tough bugs, large refactoring, security audits.</p><h4>Strategy</h4><p>The rule is simple: use Sonnet as the default. Only switch to Opus when you genuinely need it. Route simple tasks to Haiku.</p><p>Complexity isn’t the only axis, though. Task length matters too: for long autonomous runs, a model’s per-step reliability counts for more than its raw intelligence. Section 13 does the math on why.</p><p>The cost impact of routing is real. I haven’t measured it to the percentage point, but since I stopped running everything on Opus, the difference on my daily spend has been obvious, on the order of half or better.</p><h3>Section 10: Cross-Model Orchestration: Using Different AIs Together</h3><h4>A Single Model Isn’t Enough</h4><p>Using different AI models together has paid off more than I expected.</p><p><strong>Claude Opus</strong>: My orchestrator for deep-reasoning sessions. Complex architectural decisions, multi-step planning, seeing the big picture. This doesn’t contradict the Sonnet-default rule from the previous section: daily implementation stays on Sonnet, and Opus earns its cost in sessions where decisions are expensive to get wrong.</p><p><strong>OpenAI Codex/GPT</strong>: Code analysis, planning validation, critical thinking. Especially valuable for providing a different “perspective.”</p><p><strong>Google Gemini</strong>: Large context window (1M tokens), useful when a task genuinely requires reading many files in a single pass. A big window isn’t immunity, though: the selection rules from Section 3 still apply, and a bloated 1M context decays the same way a bloated 200k one does.</p><h4>Why Does It Matter?</h4><p>Every AI model has its own strengths, weaknesses, and “blind spots.” When you’re dependent on a single model, you can’t notice that model’s blind spots. Using different models together provides more robust and versatile analysis.</p><h3>Section 11: Verification Is the Bottleneck</h3><h4>Generating Is Cheap, Checking Is Not</h4><p>Here’s the problem nobody warns you about when you start orchestrating AI: generating code stopped being the constraint. Claude produces in an hour what used to take me a day. But properly verifying that hour of output (reading the diff, running the flows, checking the edges) can eat several hours of my attention.</p><p>And attention doesn’t scale the way agents do. Follow the incentive to its end: when review costs more than generation, you start skimming. Then you start trusting. Then something broken reaches production, and it turns out “done” was never verified. No one sustains a workflow where checking the work costs ten times more than requesting it.</p><p>This puts the earlier sections in a different light. Hooks (Section 6) are automated verification. Tests are verification that runs while your attention is elsewhere. The Plan-Execute-Verify loop from Section 5 works because the Verify step is systematized instead of heroic. The ceiling of AI-powered development isn’t how much you can generate. It’s how much you can verify without burning out.</p><h4>The Producer Should Never Grade Its Own Work</h4><p>The highest-leverage verification trick I know: never let the session that wrote the code judge the code.</p><p>Try this experiment. Have Claude write something genuinely complex, the kind of change that touches several areas at once. When it declares success, open a fresh session, point it at the same diff, and say: “You are reviewing this change. Your job is to find problems.” The same model that just said “everything works” will hand you a list of real issues.</p><p>This isn’t a quirk. It’s the same reason companies separate developers from testers: the author’s context is contaminated with the intent to finish, while a reviewer with clean context has one goal, finding what’s wrong. Different framing, different behavior.</p><p>Scale the rigor to the stakes:</p><ul><li>Routine change: one fresh-context review pass</li><li>Important change: a second pass with a different model, for the blind-spot reasons in Section 10</li><li>Money or security on the line: repeat until several consecutive passes come back clean</li></ul><h3>Section 12: Turn Every Repeated Error Into a System</h3><p>Claude’s statelessness has a consequence most people never act on: if the model made a mistake once, it will make the same mistake again, because the conditions that produced it haven’t changed.</p><p>So I follow a simple rule: the second time I see the same error, it gets converted into something permanent. In rough order of preference:</p><ol><li><strong>A hook</strong>, if it can be checked mechanically (a blocked command, a forbidden pattern)</li><li><strong>A test</strong>, if it’s a behavior that can regress</li><li><strong>A CLAUDE.md note or a skill</strong>, if it’s a convention or workflow the model keeps missing</li></ol><p>The first occurrence costs you a fix. The conversion costs you ten minutes. Every occurrence after that costs you nothing, forever.</p><p>Skip this and the arithmetic runs the other way. A model working actively in your codebase has dozens of recurring failure modes, and if each one resurfaces even occasionally, your day dissolves into fixing familiar mistakes. Worse, it never improves, because nothing you fixed was persisted anywhere.</p><p>The model doesn’t learn between sessions, but your system can. Hooks accumulate. Tests accumulate. CLAUDE.md gets sharper. Six months in, the model is the same; your setup is unrecognizable. That’s what a self-learning system means in practice: not a smarter model, a smarter harness.</p><h3>Section 13: Long-Running Tasks: Reliability Compounds</h3><h4>Why 99.9% and 99.99% Are Not Almost the Same</h4><p>Suppose an agent completes each step of a task correctly 99.9% of the time. Sounds excellent. Now give it a long autonomous task, the overnight kind: a thousand steps of reading, editing, running, checking.</p><p>0.999 raised to the 1000th power is about 0.37. Your “excellent” agent finishes a clean run 37% of the time.</p><p>Now take an agent at 99.99% per step. Same thousand steps: about 90% clean runs. A gap that looks like a rounding error separates an agent you can trust overnight from one you can’t.</p><p>Two practical consequences:</p><p><strong>Model choice changes with task length.</strong> For a 20-minute task, pick the smartest model. For a 10-hour run, pick the most consistent one, the one that double-checks its own steps. Meticulousness beats brilliance when errors compound.</p><p><strong>Checkpoints break the compounding.</strong> The math above assumes one failure ruins everything, so make failures recoverable instead:</p><ul><li><strong>Force commits at milestones.</strong> Tell the agent to commit after each completed piece. A mistake then costs a rollback, not the whole run.</li><li><strong>Keep a run log.</strong> Have the agent maintain a file: what’s done, what remains, what went wrong and how it was handled. A fresh agent can resume an interrupted run from this file instead of starting over.</li><li><strong>Set budgets up front.</strong> Time, tokens, scope. “If tests still fail after three attempts on the same issue, stop and write down what you know” beats letting the agent grind all night on a dead end.</li></ul><p>Plan long tasks assuming something will go wrong midway. When nothing does, great. When something does, the run survives it.</p><h3>Section 14: Parallelism Done Right</h3><h4>Agent Count Is Not a Multiplier</h4><p>The naive assumption: 10 agents = 10x speed. What actually happens when you point 10 agents at the same part of a codebase: each agent needs a coherent picture of the code to make a correct change, and while it’s forming that picture, another agent is invalidating it. They overwrite each other’s work, break each other’s assumptions, and you spend the evening untangling the damage. Ten agents, zero speedup.</p><p>Parallelism works when it follows the dependency graph of the work:</p><ul><li><strong>Split by genuinely independent areas.</strong> Frontend and backend. Two services that don’t share code. Separate git worktrees, merged when done. Independence is what makes the speedup real.</li><li><strong>One writer, many readers.</strong> A single agent makes the changes while parallel subagents feed it research: file discovery, doc lookups, pattern searches. Writes stay serialized, reads run in parallel, nothing conflicts.</li></ul><h4>The Safest Thing to Parallelize Is Discovery</h4><p>Reading has no side effects, which makes research the one place you can parallelize without ceremony. A pattern I keep coming back to: give the same question to two or three agents independently, then have another agent compare their reports.</p><p>The comparison is where the value is. When reports disagree, that’s a strong signal something is ambiguous or broken there; look yourself. When they agree, treat it as moderate evidence rather than proof. Models trained on similar data share blind spots and can be confidently wrong in the same way. Agreement narrows the search; it doesn’t close the case.</p><p>One more rule: don’t parallelize until the single-agent loop works. If the direction is wrong, ten agents get you to the wrong place ten times faster. Nail the system first (context, verification, checkpoints), and parallelism becomes a multiplier on something that already works.</p><h3>Section 15: Testing, Security, and Performance: The CTO Checklist</h3><h4>Testing in AI-Powered Development</h4><p>The biggest trap of writing code with AI: “let me finish this quickly, I’ll write tests later.” Without tests, you can’t verify the code AI produces.</p><p><strong>Rule</strong>: When having AI write a feature, ask it to write tests in the same prompt. Say “implement this feature and write its tests, then run the tests.” Verification criteria cost you one extra sentence in the prompt and change what comes back.</p><h4>Security Scanning</h4><p>With the CTO mindset, perform security checks before every PR:</p><ol><li><strong>Hardcoded secret scanning</strong>: Searching for API keys, passwords, tokens</li><li><strong>Input validation check</strong>: Are user inputs being validated?</li><li><strong>OWASP Top 10 review</strong>: Are there SQL injection, XSS, CSRF risks?</li><li><strong>Dependency security</strong>: Are there packages with known vulnerabilities?</li></ol><h4>Performance: Measure Before You Optimize</h4><p>Performance work with AI has one trap: the model will happily optimize whatever you point at, whether or not it’s the actual problem. So the order matters: measure first, then delegate. Ask for the N+1 query check, the missing index, the payload that should be streamed instead of loaded whole. Concrete, checkable requests (“profile this endpoint and show me where the time goes”) get real answers; “make it faster” gets guesswork.</p><h3>Section 16: Do’s and Don’ts</h3><h4>Do</h4><ol><li><strong>Write a good CLAUDE.md for every project.</strong> Without this file, Claude doesn’t know your project.</li><li><strong>Actively manage context.</strong> Monitor the context bar and cost info in the HUD, act early with /compact, start clean with /clear.</li><li><strong>Make Plan Mode a habit.</strong> See what will be done before big changes, then approve.</li><li><strong>Provide verification criteria.</strong> Not “write tests,” but “write tests that cover edge cases and run them with npm test.&quot;</li><li><strong>Weave a safety net with hooks.</strong> Start with at least 3 essential hooks.</li><li><strong>Use subagents generously.</strong> Delegate research, review, and search tasks. Keep your main context clean.</li><li><strong>Start with deep research.</strong> On complex tasks, research first, then implement.</li><li><strong>Apply model routing.</strong> Haiku for simple tasks, Sonnet as default, Opus for deep analysis.</li><li><strong>Teach by example.</strong> Instead of three paragraphs of explanation, show a code snippet.</li><li><strong>Keep sessions short.</strong> One conversation = one task. Context explosion means quality collapse.</li><li><strong>Turn repeated errors into systems.</strong> The second occurrence of a mistake earns a hook, a test, or a CLAUDE.md note (Section 12).</li><li><strong>Separate the producer from the verifier.</strong> A fresh-context review finds what the writing session can’t see (Section 11).</li></ol><h4>Don’t</h4><ol><li><strong>Don’t use Claude as a linter.</strong> ESLint, Biome, Prettier already exist. Rules like “use two spaces” are context waste.</li><li><strong>Don’t turn CLAUDE.md into a novel.</strong> Keep it under 100 lines. Use progressive disclosure.</li><li><strong>Don’t trust without verifying.</strong> Claude saying “done” isn’t enough. Build, test, security; verify.</li><li><strong>Don’t let it over-engineer.</strong> Explicitly state in CLAUDE.md: “don’t add extra abstractions, don’t create unnecessary interfaces.”</li><li><strong>Don’t delay writing tests.</strong> Untested AI output is unverified output.</li><li><strong>Don’t parallelize before the system works.</strong> Ten agents on a broken loop lose ten times faster (Section 14).</li></ol><h3>Conclusion: The Journey Continues</h3><p>Claude Code started as “AI in the terminal” for me. Now it’s a complete development ecosystem. CLAUDE.md strategy, context management, hook pipelines, custom agents, multi-agent orchestration, cross-model usage, self-learning systems; I learned all of these gradually over months.</p><p>The most important lesson is this: the real power of AI tools doesn’t come from which button you press, but from how you think. Think like a CTO: not just writing code, but planning, testing, ensuring security, measuring performance, and doing all of this systematically.</p><p>A fair objection at this point: won’t smarter models make all of this setup unnecessary? I’d bet on the opposite. Smarter models raise the ceiling on what you can delegate, and everything in this article (verification, context discipline, checkpoints) is what lets you actually delegate it. Model capability multiplies with operator skill. As capability grows, the gap between people who build systems and people who type prompts widens.</p><p><strong>To get started:</strong></p><ol><li>Write a good CLAUDE.md</li><li>Learn context management (the 40% rule)</li><li>Set up the 3 essential hooks</li><li>Make Plan Mode a habit</li><li>Separate the producer from the verifier</li></ol><p>Remember: the best way to sharpen your tools is to use them every day.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=71fafeb144de" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Tools: The Complete Guide to Claude Code, OpenCode & Modern Development]]></title>
            <link>https://senrecep.medium.com/ai-coding-tools-the-complete-guide-to-claude-code-opencode-modern-development-eb9da4477dc1?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/eb9da4477dc1</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[open-code]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[oh-my-opencode]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Sat, 24 Jan 2026 15:09:38 GMT</pubDate>
            <atom:updated>2026-01-24T17:11:14.169Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NlwwAHY59OnPPt6cHN_FmA.png" /><figcaption>From zero to production: Master AI-assisted development with Claude Code &amp; OpenCode</figcaption></figure><h3>Introduction: The AI Coding Revolution</h3><p>If you’re still copying code from ChatGPT or Claude.ai into your editor, you’re missing a fundamental shift in software development. Modern AI coding tools don’t just answer questions — they <strong>directly interact with your codebase</strong>, read your files, run commands, and write code for you.</p><p>This guide will take you from complete beginner to power user, covering:</p><ul><li>What AI coding tools are and why they matter</li><li>Core concepts every developer must understand</li><li>Claude Code: Anthropic’s official terminal-based assistant</li><li>OpenCode: The open-source alternative with multi-agent capabilities</li><li>How to choose the right tool for your situation</li><li>Advanced techniques for production development</li></ul><p><strong>Quick Setup</strong>: If you prefer hands-on learning, share this gist with your AI coding tool:</p><pre>Read this gist and set up my project: <br>https://gist.github.com/senrecep/98d3583717581a4138bac62344261f6f</pre><h3>Part 1: Fundamentals</h3><h4>What Are AI Coding Tools?</h4><p>AI coding tools are terminal-based assistants that can:</p><ul><li><strong>Read and write files</strong> directly in your project</li><li><strong>Execute commands</strong> (build, test, deploy)</li><li><strong>Understand context</strong> from your entire codebase</li><li><strong>Generate, refactor, and debug code</strong> based on your instructions</li></ul><p>Unlike web-based AI (ChatGPT, Claude.ai), these tools integrate directly with your development environment.</p><h3>The Two Major Players (January 2026)</h3><pre>| Tool            | Developer              | Model Support   | Cost            |<br>| --------------- | ---------------------- | --------------- | --------------- |<br>| **Claude Code** | Anthropic (official)   | Claude only     | $17-200/month   |<br>| **OpenCode**    | Community (open-source)| 75+ providers   | Free + API costs|</pre><h3>Five Limitations You Should Know</h3><p>Before diving in, understand what current AI coding tools cannot do perfectly:</p><p><strong>1. Single-Agent Problem<br></strong>Most tools use one general-purpose AI for all tasks. It’s like asking one person to be a doctor, lawyer, and architect simultaneously.</p><p><strong>2. Hallucination Risk<br></strong>AI can generate plausible but incorrect code — inventing APIs that don’t exist or using deprecated patterns.</p><p><strong>3. Context Loss<br></strong>In long conversations, AI “forgets” earlier decisions. You’ll find yourself repeating architectural choices.</p><p><strong>4. Quality Gaps<br></strong>Generated code isn’t automatically tested. You must manually verify security, types, and test coverage.</p><p><strong>5. Workflow Fragmentation<br></strong>Requirements → coding → testing → documentation requires separate conversations.</p><h3>Part 2: Core Concepts</h3><h4>CLAUDE.md — Your Project’s Brain</h4><p>A markdown file at your project root that gives AI context. <strong>Both Claude Code and OpenCode read this file</strong>.</p><h4>The Golden Rules</h4><ol><li><strong>Keep under 100 lines</strong> — Long files dilute attention</li><li><strong>WHAT / WHY / HOW structure</strong> — Clear organization</li><li><strong>Explain WHY</strong> — AI makes better decisions with context</li><li><strong>Add NOT TO DO</strong> — Prevent known AI tendencies</li><li><strong>Link to detailed docs</strong> — Progressive disclosure</li></ol><h4>Example CLAUDE.md</h4><pre># MyApp<br><br>## WHAT - Project Overview<br>React Native app with NX monorepo.<br><br>### Tech Stack<br>- TypeScript 5.8, React Native 0.79<br>- UI: Tamagui | State: RTK Query<br><br>## WHY - Architecture Decisions<br>Library-first because parallel development needed.<br><br>## HOW - Conventions<br>- Use Tamagui primitives — *cross-platform consistency*<br>- No console.log — *production performance*<br><br>## Boundaries<br>- ✅ Always: Run tests before commits<br>- ⚠️ Ask first: New dependencies<br>- 🚫 Never: Commit secrets</pre><h4>Context Window — The Critical 20–40% Rule</h4><p><strong>Important insight</strong>: Quality doesn’t degrade at 100% context — it starts at <strong>20–40%</strong>.</p><p>After 60% context usage, AI:</p><ul><li>Forgets previous instructions</li><li>Repeats the same mistakes</li><li>Edits wrong files</li><li>Produces lower quality code</li></ul><h4>Best Practices</h4><ol><li><strong>One conversation = one feature</strong></li><li><strong>Use </strong><strong>/compact regularly</strong></li><li><strong>Clear with </strong><strong>/clear when context bloats</strong></li><li><strong>Update SCRATCHPAD.md for session memory</strong></li></ol><h4>Red Flags</h4><pre>| Signal                     | Action                    |<br>| -------------------------- | ------------------------- |<br>| AI repeats itself          | `/clear`                  |<br>| Forgets previous context   | SCRATCHPAD → `/clear`     |<br>| Edits wrong files          | Clear context             |<br>| Quality drop               | `/compact` + `/clear`     |</pre><h4>MCP (Model Context Protocol)</h4><p>A standard for connecting AI tools to external services (databases, APIs, documentation).</p><p><strong>Critical</strong>: Claude Code and OpenCode use <strong>different MCP formats</strong>:</p><pre>| Feature   | Claude Code              | OpenCode                  |<br>| --------- | ------------------------ | ------------------------- |<br>| Key       | `mcpServers`             | `mcp`                     |<br>| Command   | `&quot;command&quot;: &quot;x&quot;` + `&quot;args&quot;` | `&quot;command&quot;: [&quot;x&quot;, &quot;y&quot;]`|<br>| Type      | Not required             | `&quot;type&quot;: &quot;local&quot;` required|<br>| Toggle    | N/A                      | `&quot;enabled&quot;: true/false`   |</pre><p><strong>Claude Code (</strong><strong>~/.claude/mcp.json):</strong></p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;opencontext&quot;: {<br>      &quot;command&quot;: &quot;oc&quot;,<br>      &quot;args&quot;: [&quot;mcp&quot;]<br>    }<br>  }<br>}</pre><p><strong>OpenCode (</strong><strong>~/.config/opencode/opencode.json):</strong></p><pre>{<br>  &quot;mcp&quot;: {<br>    &quot;opencontext&quot;: {<br>      &quot;type&quot;: &quot;local&quot;,<br>      &quot;command&quot;: [&quot;oc&quot;, &quot;mcp&quot;],<br>      &quot;enabled&quot;: true<br>    }<br>  }<br>}</pre><h4>Skills — Reusable Knowledge</h4><p>Skills are instruction sets that extend AI capabilities. They’re <strong>shared between Claude Code and OpenCode</strong>.</p><p><strong>Directory search order (OpenCode):</strong></p><pre>| Priority | Directory                    | Shared with Claude Code? |<br>| -------- | ---------------------------- | ------------------------ |<br>| 1        | `.opencode/skills/`          | ❌                       |<br>| 2        | `.claude/skills/`            | ✅                       |<br>| 3        | `~/.config/opencode/skills/` | ❌                       |<br>| 4        | `~/.claude/skills/`          | ✅                       |</pre><p><strong>Key insight</strong>: This is <strong>provider-agnostic</strong> — works the same whether you use Claude, GPT, Gemini, or GLM.</p><p><strong>Recommendation</strong>: Use ~/.claude/skills/ for skills shared between both tools.</p><h3>Part 3: Claude Code Mastery</h3><h4>Installation</h4><pre># macOS/Linux<br>curl -fsSL https://claude.ai/install.sh | bash<br># Verify<br>claude --version</pre><h4>Essential Plugins</h4><pre># Workflow<br>/plugin install commit-commands     # Git automation<br>/plugin install code-review         # Quality review<br><br># Integration<br>/plugin install github              # GitHub integration<br>/plugin install firebase            # Firebase tools<br><br># Analysis<br>/plugin install serena              # Semantic code navigation<br>/plugin install context7            # Library documentation</pre><h4>Plugin Categories</h4><p><strong>LSP (Language Server Protocol):</strong></p><ul><li>csharp-lsp, typescript-lsp, pyright-lsp, gopls-lsp</li><li>Makes Claude understand types, detect errors, suggest imports</li></ul><p><strong>Development Workflow:</strong></p><ul><li>commit-commands — /commit, /commit-push-pr</li><li>code-review — Quality and security review</li><li>pr-review-toolkit — Silent failure hunting, type analysis</li></ul><p><strong>Integration:</strong></p><ul><li>github, atlassian, notion, firebase, linear, figma</li></ul><p><strong>Browser Automation:</strong></p><ul><li>playwright — E2E testing</li><li>dev-browser — Claude-controlled browser for verification</li></ul><h4>Custom Agents</h4><p>Create specialized AI assistants in .claude/agents/:</p><pre>---<br>name: security-reviewer<br>description: OWASP-focused code review<br>tools: Read, Grep, Bash<br>model: sonnet<br>---<br><br>You are a security auditor focused on OWASP Top 10.<br><br>## Approach<br>1. Identify vulnerabilities<br>2. Rate severity (critical/high/medium/low)<br>3. Provide specific fixes</pre><h4>Speckit Integration</h4><p>Structured development for complex features:</p><pre># Install<br>uv tool install specify-cli --from git+https://github.com/github/spec-kit.git<br><br># Initialize<br>specify init . --ai claude</pre><h4>Critical Step: Constitution Analysis</h4><p><strong>For existing projects, run this immediately after installation:</strong></p><pre>/speckit.constitution</pre><p>This analyzes your codebase and extracts:</p><ul><li>Code patterns and conventions</li><li>Architecture decisions</li><li>Tech stack specifics</li><li>Naming conventions</li></ul><p>The constitution is saved to .specify/memory/constitution.md and helps AI understand your project&#39;s style.</p><h4>Feature Development Workflow</h4><pre>/speckit.specify &quot;user authentication&quot;  # Create specification<br>/speckit.clarify                         # Resolve ambiguities<br>/speckit.plan                            # Technical planning<br>/speckit.tasks                           # Generate task list<br>/speckit.implement                       # Execute implementation</pre><h3>Part 4: OpenCode Mastery</h3><h4>Installation</h4><pre>curl -fsSL https://opencode.ai/install | bash<br><br># Verify<br>opencode --version</pre><h4>Authentication</h4><pre>opencode auth login</pre><pre># Select provider based on subscription:<br># - Anthropic (if Claude subscription)<br># - OpenAI (if ChatGPT Plus)<br># - Google (if Gemini)</pre><h4>oh-my-opencode — Multi-Agent System</h4><p>oh-my-opencode transforms OpenCode into a multi-agent orchestration system.</p><p><strong>Subscription Levels Explained</strong></p><pre>| Flag              | Requirement          | Effect                      |<br>| ----------------- | ---------------------| ----------------------------|<br>| `--claude=max20`  | Claude Pro/Max + 20x | Full Sisyphus orchestrator  |<br>| `--claude=yes`    | Claude Pro/Max       | Standard Sisyphus           |<br>| `--claude=no`     | No Claude            | ⚠️ Sisyphus may fail        |<br>| `--openai=yes`    | ChatGPT Plus         | GPT-5.2 for Oracle          |</pre><h4>Installation</h4><pre># Example: ChatGPT Plus only (post-OAuth block)<br>npx oh-my-opencode install --no-tui \<br>  --claude=no \<br>  --openai=yes \<br>  --gemini=no<br><br># Or interactive install<br>npx oh-my-opencode install</pre><h4>Agent System</h4><pre>| Agent              | Model                      | Purpose                |<br>| ------------------ | -------------------------- | -----------------------|<br>| **Sisyphus**       | Claude Opus 4.5            | Main orchestrator      |<br>| **Oracle**         | Claude Opus 4.5 / GPT-5.2  | Debugging, architecture|<br>| **Librarian**      | GLM-4.7 (free)             | Code search, context   |<br>| **Frontend**       | Claude Opus 4.5            | UI/UX engineering      |<br>| **Document Writer**| Claude Opus 4.5            | Documentation          |</pre><h4>Ultrawork Mode</h4><p>Trigger parallel agent execution:</p><pre>ulw: implement authentication with tests and documentation</pre><p><strong>Warning</strong>: “Token Furnace” — can cost $50–100 per session.</p><h4>MCP Configuration</h4><p><strong>Important</strong>: OpenCode MCP format differs from Claude Code!</p><pre>mkdir -p ~/.config/opencode<br><br>cat &gt; ~/.config/opencode/opencode.json &lt;&lt; &#39;EOF&#39;<br>{<br>  &quot;mcp&quot;: {<br>    &quot;opencontext&quot;: {<br>      &quot;type&quot;: &quot;local&quot;,<br>      &quot;command&quot;: [&quot;oc&quot;, &quot;mcp&quot;],<br>      &quot;enabled&quot;: true<br>    }<br>  }<br>}<br>EOF</pre><p>Or use CLI:</p><pre>opencode mcp add opencontext --command &quot;oc mcp&quot;<br>opencode mcp list</pre><h4>Rules System</h4><p>Two approaches:</p><ol><li><strong>CLAUDE.md</strong> in project root (simple)</li><li><strong>.opencode/rules/</strong> directory (modular)</li></ol><p>Both work. OpenCode also reads CLAUDE.md files.</p><h3>Part 5: Head-to-Head Comparison</h3><h4>Performance (Real-World Tests)</h4><p>Based on community benchmarks with Opus 4.5:</p><pre>| Metric               | Claude Code  | OpenCode   |<br>| -------------------- | ------------ | ---------- |<br>| Same task completion | 14 min       | 27 min     |<br>| Token usage          | ~191k        | ~278k      |<br>| Speed                | 2× faster    | -          |<br>| Cost                 | 30% cheaper  | -          |</pre><p><strong>Note</strong>: OpenCode’s UX is widely praised as superior.</p><h4>Feature Comparison</h4><pre>| Feature             | Claude Code   | OpenCode       |<br>| ------------------- | ------------- | -------------- |<br>| Model options       | Claude only   | 75+ providers  |<br>| Local models        | ❌            | ✅ (Ollama)    |<br>| Context management  | Excellent     | Good           |<br>| Subagents           | Built-in      | Not native     |<br>| Remote workspaces   | ❌            | ✅             |<br>| GitHub integration  | ✅            | Limited        |<br>| Web interface       | ✅            | ❌             |</pre><h4>Quality Observations</h4><p><strong>Claude Code advantages:</strong></p><ul><li>Better instruction following</li><li>Fewer corrections needed</li><li>Faster completion</li></ul><p><strong>OpenCode advantages:</strong></p><ul><li>Wrote more tests</li><li>Better UX</li><li>Model flexibility</li></ul><p><strong>Common OpenCode issue</strong>: Import bug — keeps failing to add imports, thinking it has done so.</p><h3>Part 6: Choosing Your Tool</h3><h4>Quick Decision Matrix</h4><pre>| If You Want...              | Choose             |<br>| --------------------------- | ------------------ |<br>| Official support + stability| **Claude Code**    |<br>| Free + model flexibility    | **OpenCode**       |<br>| Maximum automation          | **oh-my-opencode** |</pre><h4>Scenario-Based Recommendations</h4><h4>AI Coding Beginner</h4><p><strong>Recommendation</strong>: OpenCode</p><p>Why:</p><ul><li>Free to start</li><li>Experiment with different models</li><li>Learn without financial commitment</li><li>Large community for help</li></ul><h4>Professional Developer</h4><p><strong>Recommendation</strong>: Claude Code</p><p>Why:</p><ul><li>Official support</li><li>Better instruction following</li><li>Faster execution</li><li>Enterprise SLAs available</li></ul><h4>Cost-Conscious Team</h4><p><strong>Recommendation</strong>: OpenCode + ChatGPT Plus</p><p>Why:</p><ul><li>$20/month per developer</li><li>Good quality with GPT-4.1</li><li>No vendor lock-in</li></ul><h4>Quality-Critical Project</h4><p><strong>Recommendation</strong>: Claude Code</p><p>Why:</p><ul><li>Best code quality</li><li>Better instruction following</li><li>Fewer corrections needed</li></ul><h4>Multi-Model Experimentation</h4><p><strong>Recommendation</strong>: OpenCode</p><p>Why:</p><ul><li>75+ providers</li><li>Easy model switching</li><li>Compare outputs</li></ul><h3>Part 7: Using Both Tools Together</h3><h4>What’s Automatically Shared</h4><pre>| Directory                   | Claude Code | OpenCode  |<br>| --------------------------- | ----------- | --------- |<br>| `~/.claude/skills/`         | ✅ Reads    | ✅ Reads  |<br>| `~/.config/opencode/skills/`| ❌          | ✅ Reads  |<br>| `.claude/skills/`           | ✅ Reads    | ✅ Reads  |</pre><p><strong>Result</strong>: Skills in ~/.claude/skills/ work with both tools automatically.</p><h4>What Needs Manual Sync</h4><pre>| Config       | Claude Code          | OpenCode            | Note                      |<br>| ------------ | -------------------- | ------------------- | --------------------------|<br>| MCP Servers  | `mcp.json`           | `opencode.json`     | Format conversion required|<br>| Commands     | `.claude/commands/`  | `.opencode/command/`| Rename directory          |<br>| Agents       | `.claude/agents/`    | `.opencode/agent/`  | Different frontmatter     |</pre><h4>MCP Sync Script</h4><pre># Claude Code → OpenCode (with format conversion)<br>jq &#39;{<br>  mcp: (.mcpServers | to_entries | map({<br>    key: .key,<br>    value: {<br>      type: &quot;local&quot;,<br>      command: ([.value.command] + .value.args),<br>      enabled: true<br>    }<br>  }) | from_entries)<br>}&#39; ~/.claude/mcp.json &gt; ~/.config/opencode/opencode.json<br><br># OpenCode → Claude Code<br>jq &#39;{<br>  mcpServers: (.mcp | to_entries | map({<br>    key: .key,<br>    value: {<br>      command: .value.command[0],<br>      args: .value.command[1:]<br>    }<br>  }) | from_entries)<br>}&#39; ~/.config/opencode/opencode.json &gt; ~/.claude/mcp.json</pre><h3>Best Practices</h3><ol><li><strong>Choose primary tool per project</strong> — Document in .tool-preference</li><li><strong>Sync before switching</strong> — Run sync commands</li><li><strong>Use right tool for task</strong>:</li></ol><ul><li>Claude Code: Speckit, precise work, GitHub integration</li><li>OpenCode: Multi-agent, experimentation, local models</li></ul><h3>Part 8: Advanced Topics</h3><h4>Cross-Platform Tools</h4><p>These tools work identically with <strong>both Claude Code and OpenCode</strong>:</p><h4>Speckit (Spec-Driven Development)</h4><pre># Same installation for both tools<br>uv tool install specify-cli --from git+https://github.com/github/spec-kit.git<br><br># Initialize (only difference is the --ai flag)<br>specify init . --ai claude    # For Claude Code<br>specify init . --ai opencode  # For OpenCode<br># Commands work identically in both<br>/speckit.constitution<br>/speckit.specify &quot;feature&quot;<br>/speckit.implement</pre><h4>OpenContext (Cross-Project Memory)</h4><pre># Same installation<br>npm install -g @aicontextlab/cli<br>oc init</pre><pre># MCP configuration differs by format, but functionality is identical<br># Both tools get the same context and memory capabilities</pre><p><strong>Why this matters:</strong> You can switch between tools without losing your workflow. Specs, constitution, and context are shared.</p><h4>Autonomous Mode (YOLO Mode)</h4><blockquote><em>⚠️ </em><strong><em>USE WITH EXTREME CAUTION</em></strong><em> — These modes skip all permission prompts. Only use in trusted, isolated environments.</em></blockquote><h4>Claude Code</h4><pre>claude --dangerously-skip-permissions</pre><p><strong>Safety restrictions:</strong></p><ul><li>Will NOT run as root or with sudo</li><li>Runs unattended until completion</li><li>No file edit or bash command confirmations</li></ul><h4>OpenCode</h4><pre>// In opencode.json<br>{<br>  &quot;permission&quot;: {<br>    &quot;*&quot;: &quot;allow&quot;<br>  }<br>}</pre><p>Or per-tool:</p><pre>{<br>  &quot;permission&quot;: {<br>    &quot;bash&quot;: &quot;allow&quot;,<br>    &quot;edit&quot;: &quot;allow&quot;<br>  }<br>}</pre><h4>When to Use</h4><p>✅ <strong>Appropriate:</strong></p><ul><li>Isolated Docker containers</li><li>Disposable VMs</li><li>CI/CD pipelines with controlled scope</li><li>Automated testing environments</li></ul><p>❌ <strong>Never use:</strong></p><ul><li>Production servers</li><li>Systems with sensitive data</li><li>Shared development machines</li><li>When running untrusted prompts</li></ul><h4>Best Practice</h4><pre># Run in a disposable container<br>docker run -it --rm -v $(pwd):/app node:20 bash<br>cd /app &amp;&amp; claude --dangerously-skip-permissions</pre><p><strong>Remember:</strong> One wrong command can delete files, expose secrets, or corrupt your system. The permission prompts exist for your protection.</p><h4>Hooks &amp; Continuous Learning</h4><h4>Claude Code Hooks</h4><p>Claude Code supports event-based automation through hooks:</p><pre>| Hook              | When It Runs                |<br>| ----------------- | --------------------------- |<br>| `PreToolUse`      | Before a tool is called     |<br>| `PostToolUse`     | After a tool is called      |<br>| `SessionStart`    | At session start            |<br>| `UserPromptSubmit`| When user sends a message   |<br>| `Stop`            | When agent stops            |</pre><p><strong>Example: Auto-lint after edits</strong></p><pre>{<br>  &quot;hooks&quot;: {<br>    &quot;PostToolUse&quot;: [{<br>      &quot;matcher&quot;: &quot;Edit|Write&quot;,<br>      &quot;hooks&quot;: [{<br>        &quot;type&quot;: &quot;command&quot;,<br>        &quot;command&quot;: &quot;npx eslint --fix \&quot;$CLAUDE_FILE_PATH\&quot;&quot;<br>      }]<br>    }]<br>  }<br>}</pre><h4>Claudeception: Continuous Learning System</h4><p><strong>The problem:</strong> Claude starts fresh every session. A 45-minute debugging session is forgotten in the next session.</p><p><strong>The solution:</strong> <a href="https://github.com/blader/Claudeception">Claudeception</a> automatically extracts non-obvious discoveries and saves them as reusable skills. Next time the same problem occurs, Claude already knows the solution.</p><blockquote><em>See also: </em><a href="https://senrecep.medium.com/production-grade-ai-development-with-claude-code-a-comprehensive-ecosystem-guide-56d7c4a3b744"><em>Production-Grade AI Development with Claude Code</em></a></blockquote><h4>OpenCode: No Native Hook System</h4><pre>| Feature            | Claude Code         | OpenCode                   |<br>| ------------------ | ------------------- | ---------------------------|<br>| Event hooks        | ✅ 5 hook types     | ❌ Not available           |<br>| Continuous learning| ✅ Claudeception    | ❌ Manual only             |<br>| Auto-lint          | ✅ PostToolUse      | ❌ External tools          |<br>| Session memory     | ✅ Hooks + Skills   | ⚠️ Skills only (stateless) |</pre><p><strong>Workaround for OpenCode:</strong> Use external automation (shell scripts, make targets) or wait for community plugins like <a href="https://github.com/zenobi-us/opencode-skillful">opencode-skillful</a>.</p><h4>Community Resources</h4><h4>Templates &amp; Skills</h4><ul><li><a href="https://aitmpl.com/">aitmpl.com</a> — Agents, commands, templates</li><li><a href="https://skills.sh/">skills.sh</a> — 200+ installable skills</li><li><a href="https://github.com/upstash/context7">Context7 CLI</a> — Cross-platform skills</li></ul><p><strong>Installation:</strong></p><pre>npx skills add vercel/react-best-practices<br>npx ctx7 skills install better-icons</pre><h4>Appendix: Quick Reference</h4><h4>Command Comparison</h4><pre>| Task          | Claude Code  | OpenCode   |<br>| ------------- | ------------ | ---------- |<br>| Start         | `claude`     | `opencode` |<br>| Clear context | `/clear`     | `/clear`   |<br>| Compact       | `/compact`   | N/A        |<br>| Plan mode     | `Shift+Tab`  | Similar    |<br>| Commit        | `/commit`    | `/commit`  |</pre><h4>Directory Structure</h4><pre># Global (user-level)<br>~/.claude/<br>├── CLAUDE.md           # Global context<br>├── mcp.json            # MCP servers<br>├── settings.json       # Hooks, preferences<br>└── skills/             # Shared skills (works with OpenCode too)<br><br># Project-level<br>.claude/<br>├── CLAUDE.md           # Project context<br>├── agents/             # Custom agents<br>│   ├── code-reviewer.md<br>│   ├── security-auditor.md<br>│   └── ios-developer.md<br>├── commands/           # Custom slash commands<br>│   ├── git-pr.md<br>│   └── speckit.*.md<br>├── hooks/              # Automation hooks<br>│   ├── post-edit-lint.sh<br>│   └── validate-branch-name.py<br>└── skills/             # Project-specific skills</pre><pre>~/.config/opencode/<br>├── opencode.json       # Config + MCP<br>├── oh-my-opencode.json # oh-my-opencode config<br>├── rules/              # Global rules<br>├── skills/             # Global skills<br>└── agents/             # Global custom agents<br>    └── review.md<br><br># Project-level (OpenCode)<br>.opencode/<br>├── agents/             # Project-specific agents<br>│   └── ios-expert.md<br>├── rules/              # Project rules<br>└── skills/             # Project skills</pre><h4>OpenCode Agent Format</h4><pre>---<br>description: Code review specialist<br>mode: subagent<br>model: anthropic/claude-sonnet<br>temperature: 0.3<br>permission:<br>  edit: deny<br>  bash: ask<br>tools:<br>  write: false<br>  edit: false<br>---<br>You are a code reviewer focused on...</pre><h3>Conclusion</h3><p>The AI coding landscape in 2026 offers powerful options:</p><ul><li><strong>Claude Code</strong> for official support, speed, and quality</li><li><strong>OpenCode</strong> for flexibility, cost optimization, and experimentation</li><li><strong>oh-my-opencode</strong> for multi-agent automation (with caveats)</li></ul><p><strong>Start here:</strong></p><ol><li>If new to AI coding → Try OpenCode (free)</li><li>If professional/team → Start with Claude Code</li><li>As you grow → Learn to use both for different tasks</li></ol><p>The key is understanding that these tools complement each other. Choose the right tool for each task, and you’ll multiply your productivity.</p><blockquote><strong><em>Note</em></strong><em>: For enterprise-grade quality gates and TDD workflows, </em><a href="https://github.com/modu-ai/moai-adk"><strong><em>MoAI-ADK</em></strong></a><strong><em> </em></strong><em>is also worth exploring.</em></blockquote><h3>Resources</h3><h4>Official</h4><ul><li><a href="https://docs.anthropic.com/claude-code">Claude Code Docs</a></li><li><a href="https://opencode.ai/docs">OpenCode Docs</a></li><li><a href="https://github.com/code-yeongyu/oh-my-opencode">oh-my-opencode</a></li></ul><h4>Community</h4><ul><li><a href="https://aitmpl.com/">AI Templates (aitmpl.com)</a></li><li><a href="https://skills.sh/">Skills.sh</a></li><li><a href="https://github.com/github/spec-kit">Spec-Kit</a></li></ul><h4>Analysis</h4><ul><li><a href="https://www.builder.io/blog/opencode-vs-claude-code">Builder.io Comparison</a></li></ul><h3>Previous Article</h3><ul><li><a href="https://senrecep.medium.com/production-grade-ai-development-with-claude-code-a-comprehensive-ecosystem-guide-56d7c4a3b744">Production-Grade AI Development with Claude Code</a> — Deep dive into Claude Code ecosystem setup</li></ul><p><strong>About the Author<br></strong>- Website: <a href="https://senrecep.com/">senrecep.com</a><br>- GitHub: <a href="https://github.com/senrecep">senrecep</a><br>- LinkedIn: <a href="https://linkedin.com/in/senrecep">senrecep</a><br>- X: <a href="https://twitter.com/senrecep0">@senrecep0</a></p><p><em>This guide was written using Claude Code CLI. Updated January 2026.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eb9da4477dc1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Production-Grade AI Development with Claude Code: A Comprehensive Ecosystem Guide]]></title>
            <link>https://senrecep.medium.com/production-grade-ai-development-with-claude-code-a-comprehensive-ecosystem-guide-56d7c4a3b744?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/56d7c4a3b744</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Tue, 20 Jan 2026 20:30:02 GMT</pubDate>
            <atom:updated>2026-01-24T17:11:38.330Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ubmV5hnLH-J199lrtE0eLA.png" /><figcaption>The Claude Code ecosystem: A development environment powered by Plugins, Skills, Hooks, MCP, and Prompts</figcaption></figure><h3><strong>Introduction: “Asking Questions” Isn’t Enough</strong></h3><p>Claude Code, Anthropic’s terminal-based AI assistant, is transforming the software development landscape. Yet most developers use Claude Code as a simple Q&amp;A tool, barely scratching the surface of its true potential.</p><p>In this article, I’ll share how I transformed Claude Code into a professional-grade development environment across two production projects — a .NET microservices ecosystem and an NX monorepo-based React Native mobile application.</p><h4><strong>Tools that supercharge Claude Code:</strong></h4><ul><li><strong>Plugins</strong> — From LSP support to browser automation</li><li><strong>Custom Agents</strong> — Project and domain-specific AI assistants</li><li><strong>Skills</strong> — Reusable knowledge and workflows</li><li><strong>MCP Servers</strong> — External tool and service integrations</li><li><strong>Hooks</strong> — Automation and continuous learning mechanisms</li><li><strong>Community Resources</strong> — <a href="https://www.aitmpl.com/">aitmpl.com</a> for templates, <a href="https://skills.sh/">skills.sh</a> for skills</li></ul><h4><strong>What you’ll learn in this article:</strong></h4><ul><li>Strategic CLAUDE.md configuration (the Less is More principle)</li><li>The critical importance of context window management (the 20–40% rule)</li><li>External memory systems (SCRATCHPAD, OpenContext)</li><li>Categorized use of the plugin ecosystem</li><li>Custom agent design strategies</li><li>External tool integration with MCP servers</li><li>Automation and continuous learning with Hooks</li><li>Browser automation for testing and verification</li><li>Structured feature development with Speckit</li><li>Team onboarding and knowledge sharing strategies</li></ul><p><strong>⚡ Want to skip ahead?</strong> If you prefer hands-on setup over reading, share this gist with Claude Code:</p><pre>Read this gist and set up my project: <br>https://gist.github.com/senrecep/98d3583717581a4138bac62344261f6f</pre><p>Claude will automatically configure everything based on your project. Come back to this article when you want to understand <em>why</em> each piece matters.</p><h3>Section 1: CLAUDE.md — Your Project’s Strategic Brain</h3><h4>The Role of CLAUDE.md</h4><p>CLAUDE.md is the project instructions file that Claude Code reads at the start of every conversation. Claude starts fresh each session, but this file helps it &quot;know&quot; your project — understanding architectural decisions, code style, and common pitfalls to avoid.</p><h4>Common Mistakes and Solutions</h4><p><strong>Mistake #1: Writing Everything<br></strong>My first approach was a massive 160+ line CLAUDE.md file. The result? Claude constantly missed important information.</p><pre>Why this is wrong:<br>├── Unnecessary token consumption every session<br>├── Long file = scattered attention<br>└── Critical rules get lost in the noise</pre><p><strong>Mistake #2: Using It Like a Linter</strong></p><pre># WRONG APPROACH<br>- Use semicolons at end of lines<br>- Use 2 spaces instead of tabs<br>- Variable names should be camelCase</pre><p>ESLint,Biome and Prettier already handle this. Using Claude as a linter just fills up context unnecessarily.</p><p><strong>The Right Approach: WHAT / WHY / HOW + Progressive Disclosure<br></strong>I use progressive disclosure for an effective CLAUDE.md structure:</p><pre>CLAUDE.md (70-100 lines)            → Always read<br>├── docs/claude/architecture.md     → Referenced when needed<br>├── docs/claude/patterns.md         → Referenced when needed<br>├── .specify/memory/constitution.md → Non-negotiable rules<br>└── SCRATCHPAD.md                   → Inter-session memory</pre><p><strong>Backend CLAUDE.md Example (Clean Architecture + CQRS)</strong></p><pre># CLAUDE.md<br><br>&gt; **New to this project?** Run `./scripts/setup-claude.sh`<br><br>## WHAT - Project Overview<br>.NET 9.0 microservices ecosystem. Clean Architecture + CQRS.<br><br>### Layer Structure (each service)<br>Core/Domain/       → Entities, Enums (NO EF dependencies - keeps domain pure)<br>Core/Application/  → CQRS handlers, DTOs (business logic lives here)<br>Infrastructure/    → EF Core, Repos (implements Application interfaces)<br>Presentation/      → WebApi (thin layer, delegates to Application)<br><br>## WHY - Architecture Decisions<br>- **CQRS Split**: Separates reads/writes because we had performance issues mixing them<br>- **Layer Isolation**: Domain has NO infrastructure deps because we had bugs from EF tracking leaking into business logic<br>- **DI per Layer**: Each layer has ServiceRegistration.cs because scattered registrations caused missing dependency bugs<br><br>## HOW - Code Style (with WHY)<br>- `_camelCase` for private fields → distinguishes from parameters<br>- `sealed` on public classes → prevents unintended inheritance, better performance<br>- Explicit types (avoid `var`) → we had bugs from wrong type inference<br><br>## What NOT To Do (Claude Tendencies)<br>- **Don&#39;t over-engineer**: No extra abstractions I didn&#39;t ask for<br>- **Don&#39;t add files**: If task can be done in existing file, do it there<br>- **Don&#39;t add error handling for impossible scenarios**: Trust internal code</pre><p><strong>Mobile CLAUDE.md Example (NX Monorepo + React Native)</strong></p><pre># Mobile Project<br><br>## WHAT - Project Overview<br>**NX monorepo** for mobile application supporting iOS, Android, and Web.<br><br>### Tech Stack<br>- TypeScript 5.8, React Native 0.79, React 18<br>- UI: Tamagui 1.132<br>- State: RTK Query<br>- Backend: Firebase, RevenueCat<br><br>## WHY - Architecture Decisions<br>This project follows a **library-first architecture**. Every feature lives in `libs/`<br>as a self-contained library. This enables parallel development, clear boundaries,<br>and easier testing.<br><br>## HOW - Code Conventions (with WHY)<br>- Use Tamagui primitives (`Box`, `Text`) not React Native (`View`, `Text`)<br>  → *because Tamagui provides cross-platform consistency*<br>- Use theme tokens for colors/spacing<br>  → *because hardcoded values break when theme changes*<br>- Memoize with `useCallback`/`useMemo`<br>  → *because re-renders cause performance issues on mobile*</pre><h4>The Power of WHY Explanations</h4><pre># Rule (without WHY)<br>- No console.log<br><br># Rule (with WHY)<br>- No console.log — *because it causes performance issues in production<br>  and leaks sensitive data*</pre><p>When Claude knows “why,” it makes better decisions even in edge cases. If you say “don’t use console.log,” it won’t use it even during debugging. But if you say “it causes performance issues in production,” it understands that temporary use during development is acceptable.</p><h4>Global CLAUDE.md — Instructions That Apply to All Projects</h4><p>The ~/.claude/CLAUDE.md file contains global instructions that apply across all projects. For example, I define frequently used CLI tools here:</p><pre>## JSON Tools Available<br><br>I have the following CLI tools installed for JSON processing:<br><br>- **jq** - JSON query and transformation (`jq &#39;.key&#39; file.json`)<br>- **fx** - Interactive JSON explorer (`fx data.json` or pipe with `| fx`)<br>- **jless** - Terminal JSON viewer with vim-like navigation<br>- **gron** - Makes JSON grep-friendly (`gron file.json | grep &quot;key&quot;`)<br><br>When working with JSON files:<br>- Use `jless` for quick inspection of large files<br>- Use `gron | grep` to find specific values<br>- Use `fx` for interactive exploration and JavaScript transformations<br>- Use `jq` for complex queries and transformations</pre><p><strong>Why a global CLAUDE.md?</strong> Instead of defining the same tools repeatedly in every project, I define them once in the global file and use them across all projects. Claude knows which tools it can use when working with JSON files and selects the appropriate one.</p><p><strong>Pro Tip: Subagent Control<br></strong>Claude Code sometimes spawns Sonnet or Haiku subagents even for knowledge tasks. For higher quality output, add this line to your global CLAUDE.md:</p><pre>## Subagent Preferences<br>Always launch opus subagents for knowledge-intensive tasks.</pre><p>On large projects, the <strong>Orchestrator + Subagents</strong> combination works far more effectively than vanilla Claude Code.</p><h4>CLAUDE.md Golden Rules</h4><pre>| Rule                       | Why                                              |<br>|----------------------------|--------------------------------------------------|<br>| **&lt; 100 lines**            | Long files fill up context                       |<br>| **Explain WHY**            | Claude makes better decisions when it knows &quot;why&quot;|<br>| **Add NOT TO DO**          | Prevent Claude&#39;s known tendencies                |<br>| **Progressive disclosure** | Reference details in separate files              |</pre><h4><strong>Six Areas Every Effective CLAUDE.md Covers</strong></h4><p>The WHAT/WHY/HOW structure defines <em>how</em> to present information, while the six areas below define <em>what types</em> of information should be included. Using both together yields the most effective results.</p><p>Through trial and error, I noticed that well-functioning CLAUDE.md files share a common structure. Each one covers these six areas:</p><pre>| Area                  | What to Include                                        |<br>|-----------------------|--------------------------------------------------------|<br>| **Commands**          | Executable commands with flags (`npm test --coverage`) |<br>| **Testing**           | Test framework, patterns, coverage expectations        |<br>| **Project Structure** | Key directories and their purposes                     |<br>| **Code Style**        | Examples of good code, not just descriptions           |<br>| **Git Workflow**      | Branch naming, commit format, PR process               |<br>| **Boundaries**        | What the AI should never touch  </pre><p><strong>I use a three-tier approach for boundaries:</strong></p><pre>## Boundaries<br>- ✅ **Always:** Run tests before commits, follow naming conventions<br>- ⚠️ **Ask first:** Database migrations, new dependencies<br>- 🚫 **Never:** Commit secrets, edit lock files, delete tests</pre><p><strong>The most important thing I learned:</strong> Instead of writing three paragraphs <em>describing</em> your style, include one code snippet <em>showing</em> it. Claude learns far better from examples. Also, put commands at the top of your file — Claude references them frequently.</p><p><strong>How do we fit all this in 100 lines?</strong> Write the <em>summary</em> of each area in CLAUDE.md — detailed patterns, lengthy code examples, and comprehensive explanations live in separate files under docs/claude/. For example:</p><ul><li>CLAUDE.md: “Code style: _camelCase for private fields, sealed on public classes&quot;</li><li>docs/claude/code-style.md: 20+ lines of detailed examples, edge cases, anti-patterns</li></ul><h3>Section 2: Context Window — The Most Critical Topic</h3><h4>The 20–40% Rule</h4><pre>| Metric                          | Value          |<br>|---------------------------------|----------------|<br>| Opus 4.5 Context                | 200,000 tokens |<br>| **Quality degradation begins**  | **20-40%**     |<br>| Critical degradation            | 60%+           |</pre><p>Most developers assume context works fine until it’s 100% full. The reality is that <strong>quality loss begins around 20–40%</strong>. After 60%, Claude:</p><ul><li>Forgets previous instructions</li><li>Repeats the same mistakes</li><li>Edits wrong files</li><li>Produces lower quality code</li></ul><h4><strong>The “One Conversation = One Feature” Principle</strong></h4><pre>❌ WRONG: Everything in one conversation<br>├── Build auth system<br>├── Change database schema<br>├── Update UI components<br>└── (Context exploded, quality dropped)<br><br>✅ RIGHT: Focused conversations<br>Session 1: Auth planning → Decisions to SCRATCHPAD<br>Session 2: Login implementation<br>Session 3: Error handling<br>Session 4: Profile page</pre><h4>The Copy-Paste Reset Technique</h4><p>When context bloats:</p><ol><li>Copy important information (terminal output, code snippets)</li><li>Get a summary with /compact</li><li>Clear with /clear</li><li>Paste and continue</li></ol><pre>&quot;We&#39;re working on the auth system.<br>- LoginScreen completed<br>- authSlice exists in Redux store<br>- Now we&#39;ll do error handling<br>Let&#39;s continue.&quot;</pre><h4>Red Flags — When to Clear?</h4><pre>| Signal                        | Action                         |<br>|-------------------------------|--------------------------------|<br>| Claude keeps repeating itself | `/clear`                       |<br>| Forgetting previous context   | Write to SCRATCHPAD, `/clear`  |<br>| Editing wrong files           | Clear context                  |<br>| Noticeable quality drop       | `/compact` + `/clear`          |</pre><h3>Section 3: External Memory Systems</h3><p>Claude is stateless. Every conversation starts from scratch. So how do we carry information between sessions?</p><h4>SCRATCHPAD.md — Inter-Session Memory</h4><p>A SCRATCHPAD.md file at the project root:</p><pre># Scratchpad - External Memory<br><br>## Current Task<br>[Currently active task]<br><br>## Key Decisions Made<br>| Decision | Why | Date |<br>|----------|-----|------|<br>| JWT (not session) | Mobile-first, offline support | 2024-01-15 |<br><br>## Files Modified<br>- file1.cs - Added X<br>- file2.cs - Refactored Y<br><br>## Notes for Next Session<br>[Important notes for the next session]</pre><p><strong>Workflow:</strong></p><ol><li>At session start: “Read SCRATCHPAD.md”</li><li>When important decision is made: Update the file</li><li>At session end: Add notes</li><li>After /clear: &quot;Read SCRATCHPAD.md&quot;</li></ol><p><strong>Alternative: progress.txt Pattern</strong> — A more minimal approach for autonomous loops (like Ralph):</p><pre># progress.txt<br>## Completed<br>- [x] Auth module - JWT implementation<br>- [x] User service - CRUD endpoints<br><br>## Current<br>- [ ] Payment integration - Stripe setup<br><br>## Decisions<br>- Used repository pattern for data access (testability)<br><br>## Next Session Notes<br>- Stripe webhook signature verification pending</pre><p>This pattern is especially powerful when combined with git commit: progress.txt is updated and committed at the end of each iteration. Future iterations have full context through the git history + progress.txt combination.</p><h4>OpenContext — Persistent Memory Across Projects</h4><p>OpenContext enables you to share knowledge across multiple projects.</p><pre># Installation<br>npm install -g @aicontextlab/cli<br><br># Usage<br>/opencontext-context  # Load project context<br>/opencontext-search   # Search previous writings<br>/opencontext-create   # Create new doc</pre><p>My global MCP configuration (~/.claude/mcp.json):</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;opencontext&quot;: {<br>      &quot;command&quot;: &quot;oc&quot;,<br>      &quot;args&quot;: [&quot;mcp&quot;]<br>    }<br>  }<br>}</pre><h4>Claude Code Indexer — Persistent Memory That Understands Your Codebase</h4><p>Claude Code Indexer is a multi-language code indexing tool that works with a <strong>graph database</strong>. It supports <strong>Python, JavaScript, TypeScript, Java, and AutoIt</strong>.</p><p><strong>Smart File Management:</strong></p><ul><li>Automatically ignores node_modules/ and .git/ directories</li><li>Respects .gitignore rules — doesn&#39;t index unnecessary files</li><li>This enables fast and efficient operation even on large projects</li></ul><p><strong>Core Capabilities:</strong></p><ul><li><strong>Multi-keyword Search</strong>: Search with multiple keywords</li><li><strong>Semantic Indexing</strong>: Understands code relationships through graph structure</li><li><strong>LLM Memory</strong>: Stores Claude’s previous analyses — no need to re-analyze the same file</li><li><strong>Coding Patterns &amp; Best Practices</strong>: Stores patterns and best practices you’ve established for the project</li><li><strong>Critical Components</strong>: Identifies and prioritizes critical components in the project</li></ul><p><strong>MCP Integration:</strong> Works as a native MCP server with Claude Desktop. Installation is automated — no manual configuration needed.</p><p><strong>Why I use it:</strong> Claude doesn’t need to rediscover the codebase every session. Analyses from previous sessions, established patterns, and architectural insights are preserved. This saves significant time, especially on large projects.</p><pre># Example usage<br>mcp__claude-code-indexer__index_codebase      # Index the project<br>mcp__claude-code-indexer__search_code         # Multi-keyword search<br>mcp__claude-code-indexer__get_coding_patterns # Get patterns<br>mcp__claude-code-indexer__store_llm_memory    # Store analysis results</pre><h3>Section 4: Plugin Ecosystem — Supercharged Development</h3><p>The real power of Claude Code lies in plugins. Here’s the distribution of plugins I use by category:</p><h4>LSP Plugins (Language Server Protocol)</h4><pre>| Plugin           | Language   | Why Critical                         |<br>|------------------|------------|--------------------------------------|<br>| `csharp-lsp`     | C#         | Type errors, IntelliSense in backend |<br>| `typescript-lsp` | TypeScript | Type-aware suggestions in mobile     |<br>| `pyright-lsp`    | Python     | For scripts and automation           |<br>| `gopls-lsp`      | Go         | CLI tool development                 |<br>| `kotlin-lsp`     | Kotlin     | Android native development           |<br>| `lua-lsp`        | Lua        | Neovim config, game scripting        |</pre><p><strong>Without LSP</strong> Claude sees code as just text. <strong>With LSP</strong> it detects type errors, missing imports, unused variables — everything.</p><h4>Development Workflow Plugins</h4><pre>| Plugin              | Description                  | Use Case                             |<br>|---------------------|------------------------------|--------------------------------------|<br>| `commit-commands`   | `/commit`, `/commit-push-pr` | Git workflow automation              |<br>| `code-review`       | Code review                  | Pre-PR quality check                 |<br>| `pr-review-toolkit` | Detailed PR review agents    | Silent failure hunting, type analysis|<br>| `feature-dev`       | Guided feature development   | Complex feature implementation       |<br>| `code-simplifier`   | Code simplification          | Refactoring                          |<br>| `security-guidance` | Security best practices      | Vulnerability scanning               |</pre><h4>Integration Plugins</h4><pre>| Plugin      | Integration     | Use                          |<br>|-------------|-----------------|------------------------------|<br>| `github`    | GitHub          | Issues, PRs, Actions         |<br>| `atlassian` | Jira/Confluence | Task tracking, documentation |<br>| `Notion`    | Notion          | Knowledge base               |<br>| `firebase`  | Firebase        | Auth, Firestore, hosting     |<br>| `linear`    | Linear          | Issue tracking               |<br>| `figma`     | Figma           | Design-to-code               |</pre><h4>Semantic Analysis &amp; Documentation</h4><pre>| Plugin            | Use                                        |<br>|-------------------|--------------------------------------------|<br>| `serena`          | Semantic code analysis, symbol navigation  |<br>| `context7`        | Library documentation lookup               |<br>| `greptile`        | Cross-repo semantic search                 |<br>| `document-skills` | PDF, spreadsheet, documentation generation |</pre><h4>Browser Automation</h4><pre>| Plugin        | Use                                    |<br>|---------------|----------------------------------------|<br>| `playwright`  | Browser testing, E2E automation        |<br>| `dev-browser` | Claude-controlled browser for testing  |</pre><h4>Productivity &amp; UI</h4><pre>| Plugin                  | Use                        |<br>|-------------------------|----------------------------|<br>| `claude-hud`            | Status line enhancement    |<br>| `hookify`               | Custom hooks creation      |<br>| `learning-output-style` | Educational output mode    |<br>| `design-and-refine`     | Iterative design workflow  |<br>| `claude-stt`            | Speech-to-text input       |</pre><h3>Section 5: Custom Agents — Project and Domain-Specific AI Assistants</h3><p><strong>💡Find Ready-Made Agents:</strong> Browse community agents at <a href="https://www.aitmpl.com/agents">aitmpl.com/agents</a> — pre-built agents for code review, debugging, architecture, and more.</p><h4>What is an Agent?</h4><p>An agent is a Claude instance specialized for a specific task. It’s defined by a system prompt + tool restrictions.</p><h4>Why I Use Custom Agents</h4><p><strong>1. Domain Expertise</strong>: An agent specialized in Clean Architecture, CQRS, or React Native performance is far more effective than general-purpose Claude.</p><p><strong>2. Consistent Approach</strong>: Guarantees a consistent approach for the same type of tasks. A security auditor always follows the same checklist.</p><p><strong>3. Tool Restrictions</strong>: Security layers like preventing a debugger agent from having file deletion permissions.</p><p><strong>4. Focused Context</strong>: The agent’s system prompt focuses only on its own domain, context doesn’t fill with unnecessary information.</p><h4>Agent Categories in Backend Project</h4><p><strong>Architecture &amp; Design:</strong></p><ul><li>backend-architect — API design, microservice boundaries, scalability</li><li>database-architect — Schema design, normalization, indexing strategies</li><li>cloud-architect — Cloud infrastructure, deployment patterns</li></ul><p><strong>Code Quality:</strong></p><ul><li>c-sharp-pro — Modern C# 12/13 features, async patterns, LINQ</li><li>security-auditor — OWASP Top 10, vulnerability detection</li><li>code-reviewer — Quality, maintainability, best practices</li></ul><p><strong>Maintenance:</strong></p><ul><li>dotnet-upgrade — .NET version migration</li><li>unused-code-cleaner — Dead code removal</li><li>architecture-modernizer — Legacy to modern architecture</li></ul><h4>Agent Categories in Mobile Project</h4><p><strong>Development:</strong></p><ul><li>typescript-pro — Modern TypeScript, generics, utility types</li><li>mobile-developer — Cross-platform mobile patterns</li><li>ios-developer — iOS-specific development, Swift interop</li></ul><p><strong>Performance &amp; Quality:</strong></p><ul><li>react-performance-optimization — React Native performance, memoization</li><li>debugger — Root cause analysis, stack trace interpretation</li><li>performance-engineer — App performance, memory leaks, startup time</li></ul><p><strong>Process:</strong></p><ul><li>git-flow-manager — Branch strategy, merge conflicts</li><li>context-manager — Multi-agent coordination</li></ul><h4>Agent File Structure</h4><pre>---<br>name: c-sharp-pro<br>description: Write idiomatic C# code with modern language features.<br>tools: Read, Write, Edit, Bash<br>model: sonnet<br>---<br><br>You are a C# and .NET expert specializing in modern, performant enterprise applications.<br><br>## Focus Areas<br>- Modern C# features (C# 12/13) - primary constructors, collection expressions<br>- Async/await patterns, Task Parallel Library<br>- Clean Architecture, CQRS, Mediator patterns<br><br>## Approach<br>1. Leverage C# language features for concise, expressive code<br>2. Apply SOLID principles and Domain-Driven Design<br>3. Use async/await properly - avoid blocking calls</pre><h4>Defining Boundaries: The Three-Tier Approach</h4><p><strong>Note:</strong> You can use this approach both in CLAUDE.md (project-wide boundaries) and in agent files (agent-specific boundaries). We saw an example for CLAUDE.md in Section 1 above.</p><p>My first agents only had a “don’t do” list. But Claude sometimes became overly cautious because it didn’t know what it <em>could</em> do. Now I use a three-tier system:</p><pre>## Boundaries<br>- ✅ **Always do:** Write to `tests/`, run tests before commits, follow naming conventions<br>- ⚠️ **Ask first:** Database schema changes, adding dependencies, modifying CI/CD config<br>- 🚫 **Never do:** Commit secrets, edit `node_modules/`, remove failing tests</pre><p>The advantage of this approach:</p><ul><li><strong>“Always do”</strong> shows the agent where it can act confidently</li><li><strong>“Ask first”</strong> defines gray areas — risky but sometimes necessary operations</li><li><strong>“Never do”</strong> draws hard lines — critical for destructive actions</li></ul><p>For example, here’s how I define boundaries for my test-agent:</p><pre>## Boundaries<br>- ✅ **Always:** Write to `tests/`, use existing test patterns, run `npm test` to verify<br>- ⚠️ **Ask first:** Adding new test dependencies, changing test configuration<br>- 🚫 **Never:** Modify source code in `src/`, remove failing tests, skip test verification</pre><h4>The Agent Template I Use</h4><p>When creating a new agent, I follow this structure:</p><pre>---<br>name: your-agent-name<br>description: [One-sentence description of what this agent does]<br>tools: Read, Write, Edit, Bash<br>model: sonnet<br>---<br><br>You are an expert [role] for this project.<br><br>## Your Role<br>- You specialize in [specific domain]<br>- You understand [relevant patterns/technologies]<br>- Your output: [what you produce]<br><br>## Project Knowledge<br>- **Tech Stack:** [technologies with versions]<br>- **Key Directories:**<br>  - `src/` – [what&#39;s here]<br>  - `tests/` – [what&#39;s here]<br><br>## Commands You Can Use<br>- **Build:** `npm run build`<br>- **Test:** `npm test`<br>- **Lint:** `npm run lint --fix`<br><br>## Boundaries<br>- ✅ **Always:** [safe actions]<br>- ⚠️ **Ask first:** [risky but sometimes needed]<br>- 🚫 **Never:** [destructive actions]</pre><h3>Section 6: Skills — Reusable Knowledge and Workflows</h3><p><strong>💡 Discover Skills:</strong> Browse community skills at <a href="https://skills.sh/">skills.sh</a> — 200+ installable skills with npx skills add &lt;owner/repo&gt;</p><p><strong>Cross-Platform Management:</strong> <a href="https://github.com/upstash/context7/tree/master/packages/cli">Context7 CLI</a> (ctx7) manages skills across Claude Code, Cursor, Codex, and other AI editors:</p><pre>npx ctx7 skills search [term]   # Search registry<br>npx ctx7 skills install [skill] # Install skill</pre><h4>The Difference Between Skill and Agent</h4><pre>| Agent                    | Skill                       |<br>|--------------------------|-----------------------------|<br>| Autonomous task executor | Reusable knowledge/workflow |<br>| Runs as subagent         | Runs in main conversation   |<br>| Has tool restrictions    | Uses all available tools    |<br>| Task-focused             | Knowledge-focused           |</pre><h4>Why I Create Custom Skills</h4><p><strong>1. Continuous Learning</strong>: To prevent knowledge learned in each session from being lost. The Claudeception skill exists exactly for this purpose — it automatically extracts non-obvious debugging solutions and project-specific patterns.</p><p><strong>2. Cross-Project Knowledge</strong>: React Native performance patterns learned in one project apply to other projects too. Once saved as a skill, it becomes globally available.</p><p><strong>3. Standardized Workflows</strong>: Instead of remembering the same commands for browser automation every time, I use workflows defined within skills.</p><p><strong>4. Team Knowledge Sharing</strong>: When a new team member starts using Claude Code, they already have access to accumulated skills.</p><h4>My Global Skill Categories</h4><p><strong>Learning &amp; Knowledge Extraction:</strong></p><ul><li>claudeception — Automatically extracts knowledge from conversations. Non-obvious debugging solutions and project-specific patterns are saved as skills.</li></ul><p><strong>Browser Automation:</strong></p><ul><li>agent-browser — Provides standardized workflows for headless browser commands. Offers a consistent interface for operations like element selection, form filling, and taking screenshots.</li></ul><p><strong>Development Best Practices:</strong></p><ul><li>vercel-react-best-practices — React and Next.js performance optimization patterns. Provides guidance on memoization, lazy loading, and bundle optimization.</li><li>react-native-best-practices (Callstack) — Production-tested optimization skills for React Native and Expo. Years of experience from the Callstack team: startup time, re-renders, list performance, memory management. Why I use this skill pack: Mobile performance issues typically fall into the same patterns — FlatList virtualization, memoization strategies, Hermes optimizations. Instead of doing the same research every time, I can quickly apply proven solutions.</li></ul><p><strong>UI/UX:</strong></p><ul><li>web-design-guidelines — Accessibility, responsive design, UX best practices. Used in UI code reviews.</li></ul><p><strong>External Integration:</strong></p><ul><li>opencontext-* — Persistent memory integration across projects. Context loading, search, and new doc creation workflows.</li></ul><h4>Claudeception: The Continuous Learning System</h4><p>The main reason I use Claudeception: <strong>Claude starts fresh every session</strong>. A non-obvious solution discovered in one session is forgotten in the next.</p><p><strong>When do I extract skills?</strong></p><ol><li><strong>Non-obvious Solutions</strong>: Debugging techniques not found in documentation</li><li><strong>Project-Specific Patterns</strong>: Conventions specific to the project</li><li><strong>Error Resolution</strong>: Error messages and their actual solutions</li><li><strong>Workflow Optimizations</strong>: Multi-step processes</li></ol><p><strong>Quality Criteria:</strong></p><ul><li>Will it be reusable in the future?</li><li>Is it knowledge that required discovery?</li><li>Can specific trigger conditions be defined?</li><li>Did the solution actually work?</li></ul><h3>Section 7: MCP Servers — External Tool Integration</h3><h4>What is MCP?</h4><p>Model Context Protocol — A protocol that adds external tools to Claude.</p><h4>Project-Local MCP</h4><p><strong>In the mobile project</strong> (.mcp.json):</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;nx-mcp&quot;: {<br>      &quot;type&quot;: &quot;stdio&quot;,<br>      &quot;command&quot;: &quot;npx&quot;,<br>      &quot;args&quot;: [&quot;nx-mcp&quot;]<br>    }<br>  }<br>}</pre><h4>Global MCP</h4><p>~/.claude/mcp.json:</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;context7&quot;: {<br>      &quot;command&quot;: &quot;npx&quot;,<br>      &quot;args&quot;: [&quot;-y&quot;, &quot;@anthropic/context7-mcp&quot;],<br>      &quot;description&quot;: &quot;Documentation lookup for libraries&quot;<br>    },<br>    &quot;serena&quot;: {<br>      &quot;command&quot;: &quot;uvx&quot;,<br>      &quot;args&quot;: [&quot;serena-mcp&quot;],<br>      &quot;description&quot;: &quot;Semantic code analysis&quot;<br>    },<br>    &quot;opencontext&quot;: {<br>      &quot;command&quot;: &quot;oc&quot;,<br>      &quot;args&quot;: [&quot;mcp&quot;]<br>    }<br>  }<br>}</pre><h4>MCP Use Cases</h4><pre>| MCP Server    | Use                                      |<br>|---------------|------------------------------------------|<br>| `context7`    | Library documentation lookup             |<br>| `serena`      | Semantic code navigation, symbol finding |<br>| `nx-mcp`      | NX workspace analysis                    |<br>| `opencontext` | Cross-project knowledge base             |</pre><h3>Section 8: Hooks — Automation and Continuous Learning</h3><h4>Hook Types</h4><pre>| Hook               | When It Runs               |<br>|--------------------|----------------------------|<br>| `PreToolUse`       | Before a tool is called    |<br>| `PostToolUse`      | After a tool is called     |<br>| `SessionStart`     | At session start           |<br>| `UserPromptSubmit` | When user sends a message  |<br>| `Stop`             | When agent stops           |</pre><h4>Claudeception Activator Hook</h4><p>In my global settings (~/.claude/settings.json):</p><pre>{<br>  &quot;hooks&quot;: {<br>    &quot;UserPromptSubmit&quot;: [<br>      {<br>        &quot;hooks&quot;: [<br>          {<br>            &quot;type&quot;: &quot;command&quot;,<br>            &quot;command&quot;: &quot;~/.claude/hooks/claudeception-activator.sh&quot;<br>          }<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><p><strong>What does this hook do?</strong> It reminds Claude with every prompt:</p><ul><li>“Did you learn something non-obvious in this task?”</li><li>“Is there something that would be useful in similar situations in the future?”</li><li>“If yes, run the claudeception skill”</li></ul><p><strong>Result</strong>: Claude automatically creates new skills and knowledge accumulates.</p><h4>PostToolUse: Auto-Lint Hook Example</h4><p>Running ESLint after every file edit:</p><pre>{<br>  &quot;hooks&quot;: {<br>    &quot;PostToolUse&quot;: [<br>      {<br>        &quot;matcher&quot;: &quot;Edit|Write&quot;,<br>        &quot;hooks&quot;: [<br>          {<br>            &quot;type&quot;: &quot;command&quot;,<br>            &quot;command&quot;: &quot;bash -c &#39;if [[ \&quot;$CLAUDE_FILE_PATH\&quot; =~ \\.(ts|tsx)$ ]]; then npx eslint --fix \&quot;$CLAUDE_FILE_PATH\&quot; 2&gt;/dev/null || true; fi&#39;&quot;<br>          }<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><h3>Section 9: Browser Automation — Testing and Verification</h3><h4>Dev-Browser Plugin</h4><p>A plugin that enables Claude to control the browser:</p><pre># Use case examples<br>&quot;Open localhost:3000 and verify the signup flow works&quot;<br>&quot;Go to the settings page and figure out why the save button isn&#39;t working&quot;<br>&quot;Test the checkout process end-to-end&quot;</pre><p><strong>Features:</strong></p><ul><li><strong>Persistent Pages</strong>: Navigate once, Claude can run multiple scripts</li><li><strong>LLM-Optimized DOM Snapshots</strong>: Page inspection optimized for AI</li><li><strong>Stateful Server</strong>: State is preserved throughout the session</li></ul><h4>Agent-Browser Skill</h4><p>A command-line tool for headless browser automation:</p><pre>agent-browser open &lt;url&gt;        # Navigate to page<br>agent-browser snapshot -i       # Get interactive elements with refs<br>agent-browser click @e1         # Click element by ref<br>agent-browser fill @e2 &quot;text&quot;   # Fill input by ref<br>agent-browser screenshot        # Take screenshot<br>agent-browser close             # Close browser</pre><p><strong>Workflow:</strong></p><ol><li>Navigate: agent-browser open &lt;url&gt;</li><li>Snapshot: agent-browser snapshot -i (returns elements with refs like @e1, @e2)</li><li>Interact using refs from the snapshot</li><li>Re-snapshot after significant DOM changes</li></ol><h4>Security: Docker Sandbox</h4><p>When coding AFK (Away From Keyboard) — especially in autonomous loops like Ralph — having Claude with full access to your system can be risky. Isolated operation with Docker sandbox:</p><pre>docker sandbox run claude</pre><p>This command runs Claude Code inside a container — your project files are mounted but access to home directory, SSH keys, and system files is blocked. Optional for HITL (Human-in-the-loop) coding, but a critical security layer for autonomous loops running overnight.</p><h3>Section 10: Speckit — Structured Feature Development</h3><p>A 5-step workflow for complex features:</p><pre>/speckit.specify &quot;Feature description&quot;  # 1. Create spec<br>/speckit.clarify                        # 2. Resolve ambiguities<br>/speckit.plan                           # 3. Write technical plan<br>/speckit.tasks                          # 4. Break into tasks<br>/speckit.implement                      # 5. Implement</pre><h4>Constitution</h4><p>A file that defines project principles — non-negotiable rules:</p><pre># .specify/memory/constitution.md<br><br>## Non-Negotiable Principles<br><br>### I. Clean Architecture &amp; Layer Separation<br>Every service MUST follow the four-layer structure with strict dependency rules:<br>- **Domain Layer**: Entities, Enums. MUST NOT reference EF Core.<br>- **Application Layer**: CQRS handlers, DTOs. MUST only depend on Domain.<br>- **Infrastructure Layer**: EF Core, Repositories.<br>- **Presentation Layer**: WebApi, Controllers. Thin layer.<br><br>### II. CQRS Pattern Enforcement<br>All data operations MUST follow Command-Query Responsibility Segregation.<br><br>### III. Build-Test-Commit Workflow (NON-NEGOTIABLE)<br>No code changes may be committed without passing verification:<br>1. **Build**: `dotnet build` MUST succeed with zero errors<br>2. **Test**: Relevant tests MUST pass<br>3. **Commit**: Only after build and tests pass<br><br>### IV. Code Style Standards<br>- Private fields: `_camelCase`<br>- Interfaces: `IPascalCase`<br>- File-scoped namespaces<br>- Explicit types (avoid `var`)<br>- Public classes: `sealed` unless designed for inheritance<br><br>### V. Simplicity &amp; YAGNI<br>- Only make changes directly requested<br>- Do not add features beyond scope<br>- Three similar lines &gt; premature abstraction<br>- Delete unused code completely</pre><h4>When to Use Speckit?</h4><pre>| Situation            | Approach                    |<br>|----------------------|-----------------------------|<br>| Simple bug fix       | Do directly                 |<br>| Small feature        | Plan mode (Shift+Tab)       |<br>| Complex feature      | `/speckit.specify` workflow |<br>| Multi-service change | Definitely Speckit          |</pre><h3>Section 11: Custom Commands</h3><p>Define frequently used workflows as commands.</p><p><strong>/git-pr — Commit, Push, PR</strong></p><pre># .claude/commands/git-pr.md<br><br>Commit staged changes, push to remote, and create a pull request.<br><br>## Steps<br>1. Run `git status` to see changes<br>2. Run `git diff --staged` to review staged changes<br>3. Run `git log -3 --oneline` for recent commit style<br>4. Create commit with semantic message<br>5. Push to remote with `-u` flag<br>6. Create PR using `gh pr create`<br><br>## Commit Format<br>type(scope): description<br><br>Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;</pre><p><strong>/git-fix-issue — Fetch and Fix Issue</strong></p><pre># .claude/commands/git-fix-issue.md<br><br>---<br>args: issue_number<br>---<br><br>Fetch GitHub issue and implement the fix.<br><br>## Steps<br>1. Fetch issue: `gh issue view $ARGUMENTS`<br>2. Create branch: `git checkout -b fix/issue-{number}`<br>3. Analyze and implement fix<br>4. Run tests<br>5. Commit with `fixes #{number}` reference</pre><h3>Section 12: Team Onboarding</h3><h4>Project-Local vs Global</h4><pre>| Component               | Location     | Scope   | Git? |<br>|-------------------------|--------------|---------|------|<br>| CLAUDE.md               | Project root | Project | ✅   |<br>| .claude/agents/         | Project      | Project | ✅   |<br>| .claude/commands/       | Project      | Project | ✅   |<br>| .claude/skills/         | Project      | Project | ✅   |<br>| .mcp.json               | Project root | Project | ✅   |<br>| .specify/               | Project      | Project | ✅   |<br>| ~/.claude/plugins/      | Home         | Global  | ❌   |<br>| ~/.claude/mcp.json      | Home         | Global  | ❌   |<br>| ~/.claude/hooks/        | Home         | Global  | ❌   |<br>| ~/.claude/settings.json | Home         | Global  | ❌   |</pre><h4>Setup Script</h4><pre>#!/bin/bash<br># scripts/setup-claude.sh<br><br>CRITICAL_PLUGINS=(<br>    &quot;csharp-lsp@claude-plugins-official&quot;<br>    &quot;typescript-lsp@claude-plugins-official&quot;<br>    &quot;context7@claude-plugins-official&quot;<br>    &quot;serena@claude-plugins-official&quot;<br>    &quot;commit-commands@claude-plugins-official&quot;<br>    &quot;code-review@claude-plugins-official&quot;<br>    &quot;github@claude-plugins-official&quot;<br>    &quot;playwright@claude-plugins-official&quot;<br>)<br><br>for plugin in &quot;${CRITICAL_PLUGINS[@]}&quot;; do<br>    claude plugins install &quot;$plugin&quot;<br>done<br><br>echo &quot;Claude Code setup complete!&quot;</pre><h4>Onboarding Checklist</h4><p>For a new developer:</p><ol><li><strong>Clone repo</strong> — project-local configs come with it</li><li><strong>Run setup script</strong>: ./scripts/setup-claude.sh</li><li><strong>Restart Claude</strong> — plugins become active</li><li><strong>Read onboarding doc</strong>: docs/AI_SETUP.md</li><li><strong>Load context</strong>: /opencontext-context (if available)</li></ol><h3>Section 13: Advanced Tools That Extend the Ecosystem</h3><p>So far we’ve covered the basic configuration of Claude Code. In this section, I’m introducing community tools that take the ecosystem to the next level — for autonomous coding, persistent memory, and visual workflow design:</p><h4>Auto-Claude — Autonomous Multi-Agent Framework</h4><p><a href="https://github.com/AndyMik90/Auto-Claude">github.com/AndyMik90/Auto-Claude</a></p><p><strong>What does it do?</strong></p><ul><li>Autonomous multi-agent coding framework</li><li>Automates planning, implementation, and validation</li><li><strong>Parallel agent terminals</strong> for simultaneous task execution</li><li>Isolated changes with git worktrees</li><li>AI-powered merge conflict resolution</li><li>Three-layer security model (OS-level isolation, filesystem restrictions, command allowlisting)</li></ul><p><strong>Why it matters:</strong> Transforms Claude Code from a single-task tool into a production-grade autonomous development system. Visualizes project management with a desktop application and Kanban board visualization.</p><h4>Claude OS — AI Memory System</h4><p><a href="https://github.com/brobertsaz/claude-os">github.com/brobertsaz/claude-os</a></p><p><strong>What does it do?</strong></p><ul><li>Gives Claude <strong>persistent memory</strong></li><li>Remembers architectural decisions, coding patterns, project preferences</li><li>Natural language memory saving (“remember this…”)</li><li><strong>Hybrid indexing</strong>: tree-sitter + semantic embeddings</li><li>Phase 2 selective semantic embedding — top 20% important files</li><li>One-click setup with community skills</li><li>4 knowledge bases per project: memories, profile, index, docs</li></ul><p><strong>Why it matters:</strong> Instead of starting from scratch every session, Claude begins to accumulate institutional knowledge. Achieves the same search quality with fewer embedding chunks.</p><h4>CC-WF-Studio — Visual Workflow Editor</h4><p><a href="https://github.com/0xSojalSec/cc-wf-studio">github.com/0xSojalSec/cc-wf-studio</a></p><p><strong>What does it do?</strong></p><ul><li><strong>VSCode extension</strong> as visual workflow editor</li><li>Drag-and-drop node creation</li></ul><p><strong>Multiple node types:</strong></p><ul><li><strong>Prompt</strong>: Reusable templates with {{variables}}</li><li><strong>Sub-Agent</strong>: Autonomous AI agents with tool permissions</li><li><strong>Skill Nodes</strong>: Integration with existing skills</li><li><strong>MCP Tools</strong>: External service connections</li><li><strong>Control Flow</strong>: IfElse, Switch, AskUserQuestion</li><li><strong>AI-assisted workflow refinement</strong> — improve workflows with natural language</li><li>One-click export to .claude/agents/ and .claude/commands/</li><li>Multi-language support (EN, JP, KR, CN)</li></ul><p><strong>Why it matters:</strong> You can visually design complex agent workflows without writing code.</p><h4>Browser Automation Tools</h4><p><strong>Agent-Browser</strong> (<a href="https://github.com/vercel-labs/agent-browser">vercel-labs/agent-browser</a>)</p><ul><li>Rust implementation + Node.js fallback</li><li>Reference-based element selection (@e1, @e2)</li><li>Accessibility tree extraction</li><li>Multi-session support</li><li>CLI-first design for AI agent workflows</li></ul><p><strong>Dev-Browser</strong> (<a href="https://github.com/SawyerHood/dev-browser">SawyerHood/dev-browser</a>)</p><ul><li>Persistent pages across interactions</li><li>LLM-optimized DOM snapshots</li><li>Chrome extension for logged-in sessions</li></ul><h3>Section 14: Community Ecosystem — Don’t Build Everything From Scratch</h3><p>One of the biggest productivity gains comes from leveraging community resources. Two platforms have emerged as essential destinations for Claude Code users:</p><h4>AI Templates (aitmpl.com)</h4><p><a href="https://www.aitmpl.com/"><strong>aitmpl.com</strong></a> — The complete Claude Code template marketplace.</p><pre>| Category       | What You&#39;ll Find                                           |<br>|----------------|------------------------------------------------------------|<br>| **Agents**     | Pre-built agents for code review, debugging, architecture  |<br>| **Commands**   | Ready-to-use git workflows, deployment scripts             |<br>| **Settings**   | Optimized settings.json configurations                     |<br>| **Hooks**      | Auto-lint, CI triggers, learning hooks                     |<br>| **MCPs**       | Model Context Protocol server configurations               |<br>| **Skills**     | Reusable knowledge modules                                 |<br>| **Templates**  | Complete project setups (React, Next.js, .NET, etc.)       |</pre><p><strong>Why it matters:</strong> Instead of writing every agent and command from scratch, start with battle-tested templates. The platform includes 30+ company stacks (OpenAI, Stripe, AWS, GitHub) — configurations proven in production.</p><p><strong>Additional tools:</strong></p><ul><li>Analytics dashboard for Claude session monitoring</li><li>Health check diagnostics for optimization</li><li>Conversation monitor for response analysis</li></ul><h3>Skills.sh — The Agent Skills Directory</h3><p><a href="https://skills.sh/"><strong>skills.sh</strong></a> — 200+ installable skills for AI agents.</p><pre># Install any skill with one command<br>npx skills add &lt;owner/repo&gt;</pre><pre>| Feature              | Details                                          |<br>|----------------------|--------------------------------------------------|<br>| **Skills Count**     | 200+ and growing                                 |<br>| **Supported Agents** | 15+ (Claude Code, Cursor, Copilot, Gemini, etc.) |<br>| **Contributors**     | Vercel, Anthropic, Expo, community developers    |<br>| **Installation**     | Single command via npx                           |</pre><p><strong>Popular skills include:</strong></p><ul><li>React and web design best practices</li><li>Framework-specific guidance (Expo, Next.js, Remix)</li><li>Security and testing utilities</li><li>Development workflow automation</li></ul><h3>Best Practices Summary</h3><h4>CLAUDE.md</h4><ul><li>Keep under 100 lines</li><li>WHAT / WHY / HOW structure</li><li>Add WHY explanations</li><li>Add NOT TO DO section</li><li>Progressive disclosure (details in separate files)</li></ul><h4>Context Management</h4><ul><li>One conversation = one feature</li><li>Use SCRATCHPAD.md</li><li>Apply copy-paste reset</li><li>Watch for red flags</li><li>Use /compact regularly</li></ul><h4>Ecosystem</h4><ul><li>Install LSP plugin (for your language)</li><li>Install critical workflow plugins</li><li>Define project-local MCP (.mcp.json)</li><li>Create custom agents (domain-specific)</li></ul><h4>Team</h4><ul><li>Create setup-claude.sh script</li><li>Commit project-local configs to repo</li><li>Write docs/AI_SETUP.md documentation</li></ul><h4>Workflow</h4><ul><li>Use plan mode (Shift+Tab)</li><li>Use Speckit for complex features</li><li>Define constitution</li><li>Automate with hooks</li></ul><h4>Quick Setup: Let Claude Do It For You</h4><p>Now that you understand the WHY and HOW, here’s the fastest way to set everything up: <strong>let Claude Code do it for you</strong>.</p><p>I’ve created a comprehensive gist that serves as both a knowledge base and setup guide. Simply share it with Claude Code, and it will:</p><ol><li><strong>Detect your scenario</strong> — New project or existing codebase</li><li><strong>Create a checklist</strong> — Track what needs to be done</li><li><strong>Set up everything</strong> — CLAUDE.md, agents, commands, directory structure</li><li><strong>Handle cross-platform issues</strong> — Automatically adapts to macOS/Linux/Windows</li><li><strong>Install missing tools</strong> — Detects and offers to install uv, gh, node, etc.</li></ol><h4>How to Use</h4><p>Open Claude Code in your project directory and type:</p><pre>Read this gist and set up my project: <br>https://gist.github.com/senrecep/98d3583717581a4138bac62344261f6f</pre><h4>What Happens Next</h4><p><strong>For New Projects (no source code yet):</strong></p><p>Claude will ask discovery questions:</p><ul><li>What are you building?</li><li>Which language/framework?</li><li>What’s the MVP scope?</li></ul><p>Then it creates everything: constitution, CLAUDE.md, agents, commands, and helps you start your first feature with Speckit.</p><p><strong>For Existing Projects:</strong></p><p>Claude analyzes your codebase first:</p><ul><li>Detects tech stack and architecture</li><li>Identifies build/test/lint commands</li><li>Notes existing conventions</li></ul><p>Then it creates a customized Claude ecosystem that respects your existing patterns.</p><h4>The Gist Contains</h4><pre>| Section    | Purpose                                                       |<br>|------------|---------------------------------------------------------------|<br>| **Part A** | New project setup flow with checklist                         |<br>| **Part B** | Existing project setup flow with checklist                    |<br>| **Part C** | Core templates (CLAUDE.md, agents, commands)                  |<br>| **Part D** | Plugin &amp; tool installation guides                             |<br>| **Part E** | Instructions for Claude (scenario detection, error handling)  |</pre><h4>Cross-Platform Support</h4><p>The gist includes automatic handling for:</p><ul><li><strong>Missing tools</strong>: If uv or gh isn&#39;t installed, Claude detects your OS and offers the correct install command</li><li><strong>OS differences</strong>: Unix commands like cat and ls are automatically adapted for Windows (PowerShell equivalents)</li><li><strong>Package managers</strong>: Uses brew on macOS, apt on Linux, winget on Windows</li></ul><h4>Why Use the Gist?</h4><pre>| Manual Setup           | Gist-Assisted Setup           |<br>|------------------------|-------------------------------|<br>| Read entire article    | Skim article for concepts     |<br>| Remember all steps     | Claude tracks checklist       |<br>| Copy-paste templates   | Claude customizes templates   |<br>| Debug setup issues     | Claude handles errors         |<br>| ~1-2 hours             | ~10-15 minutes                |</pre><p>The article explains WHY. The gist tells Claude WHAT to do. Together, they give you a production-grade setup in minutes.</p><h3>Conclusion</h3><p>When properly configured, Claude Code can radically transform your software development process. The configuration I’ve shared in this article — plugins, custom agents, hooks, MCP servers, skills — evolved iteratively over months.</p><p><strong>Key takeaways:</strong></p><ol><li><strong>CLAUDE.md should be short and concise</strong> — supported with WHY</li><li><strong>Context management is critical</strong> — quality starts degrading at 20–40%</li><li><strong>External memory is essential</strong> — use SCRATCHPAD and OpenContext</li><li><strong>The plugin ecosystem is powerful</strong> — LSP + workflow + integration</li><li><strong>Custom agents are valuable</strong> — domain-specific expertise</li><li><strong>Hooks enable automation</strong> — continuous learning is possible</li><li><strong>Browser automation is necessary for testing</strong> — Dev-browser, agent-browser</li><li><strong>Speckit for complex features</strong> — structured development</li></ol><p>Adapt this configuration to your own projects. Every project is different — the important thing is to understand the patterns and customize them to your needs.</p><p><em>A final note: This article, including all of the above tools, was written entirely using Claude Code CLI — from outline creation, research, drafting, to iterative editing. The best way to test your tools is to use them every day.</em></p><h3>Resources</h3><h4>Quick Setup</h4><ul><li><a href="https://gist.github.com/senrecep/98d3583717581a4138bac62344261f6f">Claude Code Ecosystem Setup Gist</a></li></ul><h4>Official Documentation</h4><ul><li><a href="https://docs.anthropic.com/claude-code">Claude Code Documentation</a></li><li><a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md">HumanLayer — Writing Good CLAUDE.md</a></li></ul><h4>Community Resources</h4><ul><li><a href="https://www.aitmpl.com/agents">AI Templates (aitmpl.com/agents)</a> — Community-driven platform for Claude Code templates. Find agents, commands, settings, hooks, MCPs, plugins, skills, and complete project templates. A constantly growing ecosystem with community contributions.</li><li><a href="https://skills.sh/">Skills.sh</a> — The Open Agent Skills Ecosystem. 200+ installable skills for Claude Code and other AI agents. Install with npx skills add &lt;owner/repo&gt;. Includes skills from Vercel, Anthropic, Expo, and community contributors.</li><li><a href="https://github.com/upstash/context7/tree/master/packages/cli">Context7 CLI (Upstash)</a> — Cross-platform skills registry. Manage AI coding skills across Claude Code, Cursor, Codex, OpenCode, and other editors with npx ctx7 skills install.</li><li><a href="https://github.com/VoltAgent/awesome-claude-skills">Awesome Claude Skills (VoltAgent)</a> — Curated skill collection. Includes official Anthropic skills, partner skills, and community contributions. A great resource to start when looking for new skills.</li></ul><h4>Tools and Projects</h4><ul><li><a href="https://github.com/vercel-labs/agent-browser">vercel-labs/agent-browser</a></li><li><a href="https://github.com/SawyerHood/dev-browser">SawyerHood/dev-browser</a></li><li><a href="https://github.com/AndyMik90/Auto-Claude">AndyMik90/Auto-Claude</a></li><li><a href="https://github.com/brobertsaz/claude-os">brobertsaz/claude-os</a></li><li><a href="https://github.com/0xSojalSec/cc-wf-studio">0xSojalSec/cc-wf-studio</a></li></ul><p><strong>About the Author<br></strong>- Website: <a href="https://senrecep.com/">senrecep.com</a><br>- GitHub: <a href="https://github.com/senrecep">senrecep</a><br>- LinkedIn: <a href="https://linkedin.com/in/senrecep">senrecep</a><br>- X: <a href="https://twitter.com/senrecep0">@senrecep0</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=56d7c4a3b744" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Performance Analysis of Parameter Passing Methods in C#]]></title>
            <link>https://senrecep.medium.com/performance-analysis-of-parameter-passing-methods-in-c-ceeffcefd624?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/ceeffcefd624</guid>
            <category><![CDATA[structs-vs-classes]]></category>
            <category><![CDATA[parameter-passing]]></category>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[performance]]></category>
            <category><![CDATA[benchmarking]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Thu, 20 Feb 2025 08:12:00 GMT</pubDate>
            <atom:updated>2026-06-20T01:00:04.725Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YRUnVdBdIPORvARlCchSsw.jpeg" /></figure><p>A while back I was profiling a high-throughput service that processed hundreds of thousands of requests per second. The CPU profiles looked reasonable, memory allocations looked fine — until I noticed that a handful of hot-path methods were consistently triggering Gen0 garbage collections. The culprit turned out to be something I had never thought twice about: the way I was passing parameters.</p><p>That experience sent me down a rabbit hole. I wanted actual numbers — not intuition, not Stack Overflow answers, but measured nanosecond-level data across every major C# type. So I built a BenchmarkDotNet harness, ran 660 test scenarios, and wrote up what I found.</p><h3>Test Setup</h3><p>Before getting into the results, here’s exactly what I measured and how.</p><p><strong>Technical specifications:</strong></p><ul><li>Test Framework: BenchmarkDotNet</li><li>Test Scenarios: Parameter counts from 3 to 8</li><li>Total Test Count: 660 (60 scenarios × average 11 iterations)</li><li>Tested Types:<br>Struct-based: struct, readonly struct, ref struct, readonly ref struct, record struct, readonly record struct<br>Reference-based: class, sealed class, record, sealed record<br>Direct parameter passing (no wrapper type)</li></ul><p><strong>Measurement metrics:</strong></p><ul><li>Mean: Average execution time</li><li>Error: Margin of error in measurements</li><li>StdDev: Consistency of measurements</li><li>Median: Median execution time</li><li>Memory Usage: Bytes allocated on the heap</li></ul><h3>Raw Benchmark Results</h3><pre>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| EightParametersByReadonlyStruct       | EightParams | 0.0089 ns | 0.0021 ns | 0.0020 ns | 0.0095 ns | 15.00      | -      | -         |<br>| EightParametersByRecordStruct         | EightParams | 0.0108 ns | 0.0041 ns | 0.0039 ns | 0.0103 ns | 15.00      | -      | -         |<br>| EightParametersByReadonlyRefStruct    | EightParams | 0.0134 ns | 0.0020 ns | 0.0018 ns | 0.0132 ns | 14.00      | -      | -         |<br>| EightParametersByRefStruct            | EightParams | 0.0156 ns | 0.0030 ns | 0.0028 ns | 0.0163 ns | 15.00      | -      | -         |<br>| EightParametersByStruct               | EightParams | 0.0171 ns | 0.0039 ns | 0.0037 ns | 0.0176 ns | 15.00      | -      | -         |<br>| EightParametersByReadonlyRecordStruct | EightParams | 0.0268 ns | 0.0023 ns | 0.0022 ns | 0.0270 ns | 15.00      | -      | -         |<br>| EightParameters                       | EightParams | 0.0374 ns | 0.0211 ns | 0.0176 ns | 0.0298 ns | 13.00      | -      | -         |<br>| EightParametersBySealedClass          | EightParams | 3.9528 ns | 0.0108 ns | 0.0084 ns | 3.9549 ns | 12.00      | 0.0076 | 48 B      |<br>| EightParametersBySealedRecord         | EightParams | 3.9665 ns | 0.0147 ns | 0.0131 ns | 3.9667 ns | 14.00      | 0.0076 | 48 B      |<br>| EightParametersByRecord               | EightParams | 4.0113 ns | 0.0220 ns | 0.0206 ns | 4.0012 ns | 15.00      | 0.0076 | 48 B      |<br>| EightParametersByClass                | EightParams | 4.0182 ns | 0.0551 ns | 0.0431 ns | 4.0169 ns | 12.00      | 0.0076 | 48 B      |<br>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| SevenParametersByReadonlyStruct       | SevenParams | 0.0132 ns | 0.0024 ns | 0.0022 ns | 0.0130 ns | 14.00      | -      | -         |<br>| SevenParametersByStruct               | SevenParams | 0.0146 ns | 0.0028 ns | 0.0026 ns | 0.0142 ns | 13.00      | -      | -         |<br>| SevenParameters                       | SevenParams | 0.0159 ns | 0.0052 ns | 0.0046 ns | 0.0166 ns | 14.00      | -      | -         |<br>| SevenParametersByReadonlyRefStruct    | SevenParams | 0.0177 ns | 0.0026 ns | 0.0022 ns | 0.0176 ns | 13.00      | -      | -         |<br>| SevenParametersByRecordStruct         | SevenParams | 0.0179 ns | 0.0017 ns | 0.0016 ns | 0.0178 ns | 15.00      | -      | -         |<br>| SevenParametersByRefStruct            | SevenParams | 0.0179 ns | 0.0024 ns | 0.0022 ns | 0.0181 ns | 15.00      | -      | -         |<br>| SevenParametersByReadonlyRecordStruct | SevenParams | 0.0292 ns | 0.0026 ns | 0.0023 ns | 0.0288 ns | 14.00      | -      | -         |<br>| SevenParametersByClass                | SevenParams | 3.9931 ns | 0.0254 ns | 0.0237 ns | 3.9937 ns | 15.00      | 0.0076 | 48 B      |<br>| SevenParametersBySealedClass          | SevenParams | 4.0053 ns | 0.0161 ns | 0.0135 ns | 3.9979 ns | 13.00      | 0.0076 | 48 B      |<br>| SevenParametersByRecord               | SevenParams | 4.0944 ns | 0.0724 ns | 0.0677 ns | 4.0916 ns | 15.00      | 0.0076 | 48 B      |<br>| SevenParametersBySealedRecord         | SevenParams | 4.1725 ns | 0.1052 ns | 0.0879 ns | 4.2199 ns | 13.00      | 0.0076 | 48 B      |<br>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| SixParametersByRefStruct              | SixParams   | 0.0021 ns | 0.0085 ns | 0.0066 ns | 0.0000 ns | 12.00      | -      | -         |<br>| SixParametersByRecordStruct           | SixParams   | 0.0131 ns | 0.0069 ns | 0.0061 ns | 0.0110 ns | 14.00      | -      | -         |<br>| SixParametersByReadonlyRecordStruct   | SixParams   | 0.0136 ns | 0.0054 ns | 0.0045 ns | 0.0130 ns | 13.00      | -      | -         |<br>| SixParametersByStruct                 | SixParams   | 0.0146 ns | 0.0016 ns | 0.0012 ns | 0.0149 ns | 12.00      | -      | -         |<br>| SixParametersByReadonlyRefStruct      | SixParams   | 0.0168 ns | 0.0114 ns | 0.0101 ns | 0.0159 ns | 14.00      | -      | -         |<br>| SixParameters                         | SixParams   | 0.0208 ns | 0.0072 ns | 0.0064 ns | 0.0184 ns | 14.00      | -      | -         |<br>| SixParametersByReadonlyStruct         | SixParams   | 0.0386 ns | 0.0213 ns | 0.0210 ns | 0.0383 ns | 16.00      | -      | -         |<br>| SixParametersBySealedClass            | SixParams   | 3.6935 ns | 0.0120 ns | 0.0106 ns | 3.6921 ns | 14.00      | 0.0064 | 40 B      |<br>| SixParametersBySealedRecord           | SixParams   | 3.7268 ns | 0.0095 ns | 0.0079 ns | 3.7270 ns | 13.00      | 0.0064 | 40 B      |<br>| SixParametersByRecord                 | SixParams   | 3.7375 ns | 0.0099 ns | 0.0088 ns | 3.7393 ns | 14.00      | 0.0064 | 40 B      |<br>| SixParametersByClass                  | SixParams   | 3.7637 ns | 0.0832 ns | 0.0854 ns | 3.7260 ns | 17.00      | 0.0064 | 40 B      |<br>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| FiveParametersByStruct                | FiveParams  | 0.0122 ns | 0.0028 ns | 0.0026 ns | 0.0130 ns | 15.00      | -      | -         |<br>| FiveParameters                        | FiveParams  | 0.0145 ns | 0.0068 ns | 0.0057 ns | 0.0136 ns | 13.00      | -      | -         |<br>| FiveParametersByRecordStruct          | FiveParams  | 0.0147 ns | 0.0033 ns | 0.0031 ns | 0.0148 ns | 15.00      | -      | -         |<br>| FiveParametersByReadonlyStruct        | FiveParams  | 0.0159 ns | 0.0033 ns | 0.0031 ns | 0.0162 ns | 15.00      | -      | -         |<br>| FiveParametersByReadonlyRecordStruct  | FiveParams  | 0.0167 ns | 0.0043 ns | 0.0041 ns | 0.0170 ns | 15.00      | -      | -         |<br>| FiveParametersByReadonlyRefStruct     | FiveParams  | 0.0167 ns | 0.0037 ns | 0.0032 ns | 0.0170 ns | 14.00      | -      | -         |<br>| FiveParametersByRefStruct             | FiveParams  | 0.0275 ns | 0.0138 ns | 0.0129 ns | 0.0205 ns | 15.00      | -      | -         |<br>| FiveParametersBySealedRecord          | FiveParams  | 3.6785 ns | 0.0159 ns | 0.0141 ns | 3.6770 ns | 14.00      | 0.0064 | 40 B      |<br>| FiveParametersBySealedClass           | FiveParams  | 3.6964 ns | 0.0158 ns | 0.0123 ns | 3.6935 ns | 12.00      | 0.0064 | 40 B      |<br>| FiveParametersByRecord                | FiveParams  | 3.6994 ns | 0.0114 ns | 0.0107 ns | 3.6982 ns | 15.00      | 0.0064 | 40 B      |<br>| FiveParametersByClass                 | FiveParams  | 3.8910 ns | 0.0951 ns | 0.0794 ns | 3.9040 ns | 13.00      | 0.0064 | 40 B      |<br>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| FourParameters                        | FourParams  | 0.0171 ns | 0.0047 ns | 0.0044 ns | 0.0154 ns | 15.00      | -      | -         |<br>| FourParametersByReadonlyRecordStruct  | FourParams  | 0.5746 ns | 0.0333 ns | 0.0396 ns | 0.5763 ns | 21.00      | -      | -         |<br>| FourParametersByRecordStruct          | FourParams  | 0.5781 ns | 0.0305 ns | 0.0271 ns | 0.5790 ns | 14.00      | -      | -         |<br>| FourParametersByReadonlyStruct        | FourParams  | 0.5926 ns | 0.0342 ns | 0.0380 ns | 0.5998 ns | 19.00      | -      | -         |<br>| FourParametersByStruct                | FourParams  | 0.6749 ns | 0.0347 ns | 0.0426 ns | 0.6816 ns | 22.00      | -      | -         |<br>| FourParametersByRefStruct             | FourParams  | 0.6863 ns | 0.0359 ns | 0.0515 ns | 0.6945 ns | 28.00      | -      | -         |<br>| FourParametersByReadonlyRefStruct     | FourParams  | 0.6889 ns | 0.0364 ns | 0.0577 ns | 0.6910 ns | 33.00      | -      | -         |<br>| FourParametersBySealedClass           | FourParams  | 3.4595 ns | 0.0209 ns | 0.0195 ns | 3.4674 ns | 15.00      | 0.0051 | 32 B      |<br>| FourParametersByClass                 | FourParams  | 3.4767 ns | 0.0314 ns | 0.0294 ns | 3.4868 ns | 15.00      | 0.0051 | 32 B      |<br>| FourParametersByRecord                | FourParams  | 3.4836 ns | 0.0144 ns | 0.0135 ns | 3.4857 ns | 15.00      | 0.0051 | 32 B      |<br>| FourParametersBySealedRecord          | FourParams  | 3.7335 ns | 0.0230 ns | 0.0215 ns | 3.7415 ns | 15.00      | 0.0051 | 32 B      |<br>| Method                                | Categories  | Mean      | Error     | StdDev    | Median    | Iterations | Gen0   | Allocated |<br>| ------------------------------------- | ----------- | --------: | --------: | --------: | --------: | ---------: | -----: | --------: |<br>| ThreeParameters                       | ThreeParams | 0.0188 ns | 0.0115 ns | 0.0102 ns | 0.0155 ns | 14.00      | -      | -         |<br>| ThreeParametersByRecordStruct         | ThreeParams | 0.5678 ns | 0.0277 ns | 0.0259 ns | 0.5662 ns | 15.00      | -      | -         |<br>| ThreeParametersByReadonlyRecordStruct | ThreeParams | 0.5717 ns | 0.0302 ns | 0.0267 ns | 0.5729 ns | 14.00      | -      | -         |<br>| ThreeParametersByRefStruct            | ThreeParams | 0.7168 ns | 0.0360 ns | 0.0538 ns | 0.7239 ns | 30.00      | -      | -         |<br>| ThreeParametersByReadonlyRefStruct    | ThreeParams | 0.7234 ns | 0.0365 ns | 0.0721 ns | 0.7082 ns | 48.00      | -      | -         |<br>| ThreeParametersByReadonlyStruct       | ThreeParams | 0.7349 ns | 0.0368 ns | 0.0573 ns | 0.7346 ns | 32.00      | -      | -         |<br>| ThreeParametersByStruct               | ThreeParams | 0.7548 ns | 0.0370 ns | 0.0648 ns | 0.7332 ns | 39.00      | -      | -         |<br>| ThreeParametersByClass                | ThreeParams | 3.4737 ns | 0.0831 ns | 0.0737 ns | 3.4421 ns | 14.00      | 0.0051 | 32 B      |<br>| ThreeParametersBySealedClass          | ThreeParams | 3.4743 ns | 0.0697 ns | 0.0582 ns | 3.4544 ns | 13.00      | 0.0051 | 32 B      |<br>| ThreeParametersBySealedRecord         | ThreeParams | 3.8524 ns | 0.0835 ns | 0.0781 ns | 3.8314 ns | 15.00      | 0.0051 | 32 B      |<br>| ThreeParametersByRecord               | ThreeParams | 3.9852 ns | 0.1021 ns | 0.1327 ns | 3.9314 ns | 24.00      | 0.0051 | 32 B      |</pre><h3>Struct-Based Types</h3><p>The headline result from these benchmarks is how dramatically struct-based types outperform reference types at 5+ parameters. The gap is not marginal — we’re talking about the difference between sub-nanosecond execution and ~4 ns, with zero heap allocation versus 32–48 bytes per call.</p><p><strong>struct and </strong><strong>readonly struct</strong> showed excellent performance across the board, particularly for small data structures. With 3–4 parameters you&#39;re looking at 0.6–0.7 ns. Jump to 5+ parameters and the JIT starts doing something clever — times drop to 0.01–0.03 ns. Adding readonly to a struct buys you another 5–10% on average, since the compiler can skip defensive copies when passing to methods that might otherwise mutate the value.</p><p><strong>ref struct and </strong><strong>readonly ref struct</strong> sit in roughly the same performance band as their non-ref counterparts, with the added constraint that they can&#39;t escape to the heap. If you&#39;re building something like a parser or a span-based processing pipeline, this is often exactly what you want: the compiler enforces stack-only lifetime, and you get the performance to match.</p><p><strong>record struct and </strong><strong>readonly record struct</strong> were consistently the best-performing types in the 3–4 parameter range (~0.57 ns), edging out the plain struct variants. They carry all the benefits of value semantics — zero allocation, stack storage — and layer on value-based equality and immutability for free. For most modern C# code that needs a small, immutable parameter bundle, readonly record struct is the answer.</p><h3>Reference Types</h3><p>The story for reference types is simpler and less exciting from a performance standpoint. Every class-based variant hovered in the 3.4–4.2 ns range regardless of parameter count, and every call allocated 32–48 bytes on the heap. That allocation cost is what matters in tight loops — it’s not the 4 ns per call, it’s the GC pressure that accumulates.</p><p><strong>class and </strong><strong>sealed class</strong> are essentially the same story. sealed class is 1–3% faster, which tracks with the fact that sealing a class allows the JIT to devirtualize certain call patterns. In practice, you&#39;d never choose sealed purely for this gain — but it&#39;s good to know the ceiling.</p><p><strong>record and </strong><strong>sealed record</strong> match class performance almost exactly. They bring value-based equality and a nice positional syntax, but they don&#39;t change the fundamental allocation model. If you&#39;re wrapping parameters in a record for convenience, you&#39;re still paying the heap cost.</p><h3>Direct Parameter Passing</h3><p>There’s one outlier worth talking about: passing parameters directly, with no wrapper type at all. It clocked in at 0.015–0.037 ns with zero allocation — the fastest option across the board when parameter count is low. The trade-off is ergonomics. Once you get past 4–5 parameters, a naked method signature becomes hard to read, hard to refactor, and easy to get wrong. The struct variants close the gap fast enough that grouping into a readonly record struct is almost always the better call.</p><h3>Practical Recommendations</h3><p>The numbers above translate into a few concrete rules I now follow:</p><p><strong>For 3–4 parameters in a hot path</strong>, reach for readonly record struct. You get ~0.57 ns execution, zero allocation, built-in equality, and a clean constructor syntax. The ergonomics are better than a plain struct and the performance is comparable.</p><p><strong>For 5+ parameters</strong>, all struct variants converge at ~0.01–0.03 ns, which is essentially noise-floor territory. Pick whichever struct type fits your constraints: readonly struct if you need to pass by value across a wide API, ref struct if you want to guarantee stack-only lifetime.</p><p><strong>When you need inheritance or large shared objects</strong>, class types are appropriate — just don’t use them on hot paths where the allocation cost will accumulate. Object pooling or a structural redesign is usually a better answer than trying to optimize a class-based parameter pattern.</p><p><strong>When value equality matters but you’re not on a hot path</strong>, record reference types are fine. The ergonomics are excellent and the ~4 ns allocation cost is irrelevant in most application code.</p><h3>Conclusion</h3><p>The gap between struct-based and reference-type parameter passing in C# is larger than most developers expect — roughly 200x in execution time and 100% in allocation overhead at 5+ parameters. That difference is usually invisible in typical application code, but it surfaces quickly in high-frequency paths: parsers, serializers, math-heavy compute loops, or any method that gets called millions of times per second.</p><p>The good news is that the modern C# type system gives you precise tools to handle this. readonly record struct hits the sweet spot of performance, immutability, and developer ergonomics for the majority of cases. Once you internalize when to reach for each variant, writing allocation-free hot paths stops feeling like a sacrifice and starts feeling like the natural default.</p><p>The full benchmark source is available on <a href="https://dotnetfiddle.net/cyCLlv">.NET Fiddle</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ceeffcefd624" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Modern Way to Manage C# Business Rules: Rule Engine Pattern ]]></title>
            <link>https://senrecep.medium.com/the-modern-way-to-manage-c-business-rules-rule-engine-pattern-14bb1c72d700?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/14bb1c72d700</guid>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[rule-engine]]></category>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[functional-programming]]></category>
            <category><![CDATA[design-patterns]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Mon, 03 Feb 2025 23:10:01 GMT</pubDate>
            <atom:updated>2026-06-19T16:08:50.052Z</atom:updated>
            <content:encoded><![CDATA[<h3>The Modern Way to Manage C# Business Rules: Rule Engine Pattern</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pB8tE3u6QErZpbX0TMurmg.jpeg" /></figure><p>I’ve been building business applications in C# for a long time. Finance, e-commerce, healthcare — every domain comes with its own set of rules. “The user must be 18 or older.” “The order total must exceed the minimum threshold.” “The credit applicant must not be on the blacklist.” These rules start simple. A few if statements here, a validation method there. But they never stay simple.</p><p>When I first encountered this problem at scale, I was working on a project with hundreds of business rules scattered across dozens of services. The same validation logic was duplicated in three different places, each with slightly different error messages. One service checked the user’s age with &gt;=18, another with &gt;17. A bug in one place would get fixed, but the copy in another service would keep failing silently. Testing was a nightmare because the rules were buried inside thick method bodies with six levels of nesting.</p><p>That experience pushed me to find a better way. What I landed on was the <strong>Rule Engine Pattern</strong> — a pattern that treats business rules as first-class, composable objects rather than scattered conditionals. Combined with the <strong>Result Pattern</strong> for error handling, it transformed how I think about domain validation in C#.</p><h3>The problem with traditional approaches</h3><p>The issues I ran into were not unique. Most C# codebases that grow beyond a certain size develop the same symptoms.</p><p>On the technical side, validation code gets scattered and duplicated. Test coverage drops because the rules are tangled with business logic that’s hard to isolate. Error handling becomes inconsistent — one method throws an ArgumentException, another returns a boolean, a third writes to a log and continues silently. Performance degrades as exception-based control flow accumulates overhead.</p><p>On the business process side, there’s no single place to look at all the rules governing a particular entity. When regulations change, you’re grepping through the codebase hoping you found every spot that needs updating. Rule dependencies become implicit and fragile. New team members have no documentation to fall back on because the rules are encoded in imperative code that only makes sense with full context.</p><p>The Rule Engine Pattern addresses all of these by giving each rule a dedicated, testable unit with a consistent interface. Rules become centralized, modular, and independently verifiable. The Result Pattern replaces exception-based error handling with explicit, type-safe return values — no performance penalty, no invisible failure modes, no inconsistent messages.</p><h3>Core components of the Rule Engine Pattern</h3><h4>The Result Pattern</h4><p>At the heart of the Rule Engine is the Result Pattern. Instead of throwing exceptions for expected business errors, every rule evaluation returns a Result — either success or failure with structured error details. This matters for three reasons: you eliminate the performance overhead of exception unwinding, you make error paths explicit and predictable, and you gain consistent error messages across the entire application.</p><h4>Rule types and definition approaches</h4><p>The Rule Engine supports both object-oriented and functional programming approaches. You can define rules using any of these structures:</p><pre>public sealed class UserRule : IRule&lt;User&gt; { }<br>public sealed record UserRule : IRule&lt;User&gt; { }<br>public struct UserRule : IRule&lt;User&gt; { }<br>public readonly record struct UserRule : IRule&lt;User&gt; { }</pre><p>I strongly recommend readonly record struct for most cases. Because it&#39;s a value type, there&#39;s no heap allocation. Immutability makes it inherently thread-safe. The record syntax keeps the implementation concise. The readonly modifier enables additional compiler optimizations. And the memory footprint is minimal. In my benchmarks, the difference between value-type rules and class-based rules was substantial — the same pattern I documented in my parameter-passing performance analysis.</p><h4>Rule interfaces</h4><p>The Rule Engine provides specialized interfaces for different validation scenarios, and choosing the right one matters.</p><p><strong>Simple rules</strong> perform a single validation. They’re the building blocks — one rule, one check, one result:</p><pre>// IRule&lt;TContext&gt;<br>// IRule&lt;TContext, TResult&gt;<br><br>// IAsyncRule&lt;TContext&gt;<br>// IAsyncRule&lt;TContext, TResult&gt;<br><br><br>internal readonly record struct AdultRule : IRule&lt;User&gt;{<br>    public Result Evaluate(User context) =&gt;<br>        context.Age &gt;= 18<br>            ? Result.Success()<br>            : Error.Validation(&quot;USER.NOT_ADULT&quot;, &quot;User must be 18 or older&quot;);<br>}</pre><p><strong>Linear rules</strong> form a chain where each rule points to the next. Evaluation stops at the first failure. This is the chain-of-responsibility pattern applied to validation — useful when later rules depend on earlier ones passing:</p><pre>// ILinearRule&lt;TContext&gt;<br>// ILinearRule&lt;TContext, TResult&gt;<br><br>// ILinearAsyncRule&lt;TContext&gt;<br>// ILinearAsyncRule&lt;TContext, TResult&gt;<br><br>internal readonly record struct EmailFormatRule : ILinearRule&lt;string&gt;{<br>    public IRuleBase&lt;string&gt;? Next =&gt; new DomainRule();<br>    public Result Evaluate(string email) =&gt;<br>        email.Contains(&#39;@&#39;)<br>            ? Result.Success()<br>            : Error.Validation(&quot;EMAIL.INVALID_FORMAT&quot;, &quot;Email must contain @&quot;);<br>}</pre><p><strong>Logical rules</strong> combine multiple rules with AND/OR semantics. AND rules require all to pass; OR rules require at least one. This is where compositional power really shines — you can build complex validation trees from simple, testable pieces:</p><pre>// IAndRule&lt;TContext&gt;<br>// IAndRule&lt;TContext, TResult&gt;<br><br>// IAndAsyncRule&lt;TContext&gt;<br>// IAndAsyncRule&lt;TContext, TResult&gt;<br><br>// IOrRule&lt;TContext&gt;<br>// IOrRule&lt;TContext, TResult&gt;<br><br>// IOrAsyncRule&lt;TContext&gt;<br>// IOrAsyncRule&lt;TContext, TResult&gt;<br><br>internal readonly record struct PaymentMethodRule : IOrRule&lt;Payment&gt;{<br>    public IRuleBase&lt;Payment&gt;[] Rules =&gt;<br>    [<br>        new CreditCardRule(),<br>        new BankTransferRule(),<br>        new CryptoRule()<br>    ];<br>}</pre><p><strong>Conditional rules</strong> branch based on the result of an evaluation. If the condition passes, one rule executes; if it fails, another does. Think of it as an if/else at the rule composition level:</p><pre>// IConditionalRule&lt;TContext&gt;<br>// IConditionalRule&lt;TContext, TResult&gt;<br><br>// IConditionalAsyncRule&lt;TContext&gt;<br>// IConditionalAsyncRule&lt;TContext, TResult&gt;<br><br>internal readonly record struct CardTypeRule : IConditionalRule&lt;CreditCard&gt;{<br>    public IRuleBase&lt;CreditCard&gt;? Success =&gt; new AmexRule();<br>    public IRuleBase&lt;CreditCard&gt;? Failure =&gt; new MasterCardRule();<br>    public Result Evaluate(CreditCard context) =&gt;<br>        context.Number.Length == 15<br>            ? Result.Success()<br>            : Result.Failure();<br>}</pre><h3>Implementation examples</h3><p>Theory is useful, but real-world examples are what matter. Here are two scenarios I’ve actually implemented in production systems.</p><h4>E-Commerce: Order validation</h4><p>An order must pass several checks before it can be processed. Stock must be available, the payment method must be valid, the shipping address must be complete, and the order amount must exceed a minimum. With AND rules, all of these run and all failures are reported together:</p><pre>public readonly record struct OrderValidationRule : IAndRule&lt;Order&gt;{<br>    private readonly IStockService _stockService;<br>    private readonly IPaymentService _paymentService;<br>    public OrderValidationRule(IStockService stockService, IPaymentService paymentService)<br>    {<br>        _stockService = stockService;<br>        _paymentService = paymentService;<br>    }<br>    public IRuleBase&lt;Order&gt;[] Rules =&gt;<br>    [<br>        new OrderAmountRule(minimumAmount: 50),<br>        new StockAvailabilityRule(_stockService),<br>        new PaymentMethodValidationRule(_paymentService),<br>        new ShippingAddressRule(),<br>        new UserValidationRule()<br>    ];<br>}</pre><h4>Finance: Credit application</h4><p>A credit application has a natural sequence: first check the blacklist, then verify the age, then validate income, then check the credit score. Linear rules handle this elegantly, stopping at the first failure because there’s no point checking a credit score for someone who’s on the blacklist:</p><pre>public readonly record struct CreditApplicationRule : ILinearRule&lt;CreditApplication&gt;{<br>    private readonly ICreditScoreService _creditScoreService;<br>    private readonly IBlacklistService _blacklistService;<br>    public CreditApplicationRule(ICreditScoreService creditScoreService, IBlacklistService blacklistService)<br>    {<br>        _creditScoreService = creditScoreService;<br>        _blacklistService = blacklistService;<br>    }<br>    public IRuleBase&lt;CreditApplication&gt;? Next =&gt; new CreditScoreRule(_creditScoreService);<br>    public async ValueTask&lt;Result&gt; EvaluateAsync(CreditApplication application)<br>    {<br>        var blacklistResult = await _blacklistService.CheckAsync(application.UserId);<br>        if (blacklistResult.IsBlacklisted)<br>            return Error.Validation(&quot;CREDIT.BLACKLISTED&quot;, &quot;User is blacklisted&quot;);<br>        if (application.Age &lt; 18)<br>            return Error.Validation(&quot;CREDIT.UNDERAGE&quot;, &quot;Must be 18 or older&quot;);<br>        if (application.MonthlyIncome &lt; 5000)<br>            return Error.Validation(<br>                code: &quot;CREDIT.LOW_INCOME&quot;,<br>                description: &quot;Insufficient monthly income&quot;,<br>                metadata: new ErrorMetadata(<br>                    (&quot;MinimumIncome&quot;, 5000),<br>                    (&quot;ActualIncome&quot;, application.MonthlyIncome)<br>                )<br>            );<br>        return Result.Success();<br>    }<br>}</pre><h3>Best practices</h3><p>Over time, I’ve settled on a set of practices that consistently lead to cleaner, more maintainable rule engines.</p><p><strong>Single responsibility.</strong> Each rule should check exactly one thing. When a rule starts doing two checks, split it. The composability of the pattern makes this cheap.</p><p><strong>Centralized error management.</strong> Don’t create error objects inside rule methods. Define them in a central location so that error codes and messages stay consistent across the entire codebase:</p><pre>internal static class UserErrors{<br>    public static Error NotAdult =&gt; Error.Validation(<br>        code: &quot;USER.NOT_ADULT&quot;,<br>        description: &quot;User is not adult&quot;<br>    );<br>    public static Error InvalidSalary(decimal minSalary, decimal actualSalary) =&gt; Error.Validation(<br>        code: &quot;USER.INVALID_SALARY&quot;,<br>        description: &quot;User has insufficient salary&quot;,<br>        metadata: new ErrorMetadata(<br>            new KeyValuePair&lt;string, object?&gt;(&quot;MinSalary&quot;, minSalary),<br>            new KeyValuePair&lt;string, object?&gt;(&quot;ActualSalary&quot;, actualSalary)<br>        )<br>    );<br>}<br>public Result Evaluate(User context)<br>{<br>    if (context.Age &lt; 18)<br>        return UserErrors.NotAdult;<br>    if (context.Salary &lt; 5000)<br>        return UserErrors.InvalidSalary(5000, context.Salary);<br>    return Result.Success();<br>}</pre><p>This approach centralizes error codes and messages, prevents duplication, keeps messages consistent, simplifies maintenance, and gives you IntelliSense support throughout the project.</p><p><strong>Descriptive error codes.</strong> Group error codes by domain and operation — USER.*, PAYMENT.*, ORDER.*. Use meaningful names like NOT_FOUND, INVALID_FORMAT, INSUFFICIENT_FUNDS. Stick to a consistent naming convention across the entire system.</p><p><strong>Rich metadata.</strong> Don’t just say “insufficient income.” Include the minimum required and the actual amount in the metadata. This makes debugging, logging, and client-side error rendering dramatically easier.</p><p><strong>Testability.</strong> Each rule is independently testable by design. Write separate test cases for success, failure, and edge conditions. Don’t forget to assert on metadata values — they’re part of the contract.</p><p><strong>Performance.</strong> Use record struct to minimize heap allocation. Use static error definitions to reduce object creation. Avoid string concatenation in error messages — use pre-built error objects instead.</p><p><strong>Rule definitions.</strong> Prefer readonly record struct unless you have a specific reason not to. Design rule state to be immutable. Manage dependencies through constructor injection. Keep each rule small and focused.</p><h3>Functional style usage</h3><p>The Rule Engine also supports a functional API for cases where you don’t want to define separate rule classes. This is particularly useful for ad-hoc validations or when rules are simple enough that a full class would be overkill.</p><p><strong>AND rules</strong> — all must pass:</p><pre>Result result = RuleEngine.And(<br>    rules: [<br>        UserRules.ActiveCheck,<br>        UserRules.AdultCheck,<br>        UserRules.SalaryCheck,<br>        UserRules.CoupleCheck<br>    ],<br>    context: user);<br>Result result = RuleEngine.And(<br>    rules: [<br>        input =&gt; input % 2 == 0,<br>        input =&gt; input % 3 == 0<br>    ],<br>    context: 120);</pre><p><strong>OR rules</strong> — at least one must pass:</p><pre>Result result = RuleEngine.Or(<br>    rules: [<br>        PaymentRules.CreditCardCheck,<br>        PaymentRules.BankTransferCheck<br>    ],<br>    context: payment);<br>Result result = RuleEngine.Or(<br>    rules: [<br>        input =&gt; input &gt; 0,<br>        input =&gt; input % 2 == 0<br>    ],<br>    context: 120);</pre><p><strong>Linear rules</strong> — sequential validation that stops at the first failure:</p><pre>Result result = RuleEngine.Linear(<br>    rules: [<br>        EmailRules.EmptyCheck,<br>        EmailRules.AtSignCheck,<br>        EmailRules.LocalPartCheck,<br>        EmailRules.DomainCheck<br>    ],<br>    context: email);<br>Result result1 = RuleEngine.Linear(<br>    rules: [<br>        input =&gt; input &gt; 0,<br>        input =&gt; input &lt; 100,<br>        input =&gt; input % 2 == 0,<br>        input =&gt; input % 3 == 0<br>    ],<br>    context: 120);<br>Result result2 = RuleEngine.Linear(<br>    rules: [<br>        input =&gt; input &gt; 0<br>            ? Result.Success()<br>            : Error.Validation(&quot;input_greater_than_0&quot;),<br>        input =&gt; input &lt; 100<br>            ? Result.Success()<br>            : Error.Validation(&quot;input_less_than_100&quot;),<br>        input =&gt; input % 2 == 0<br>            ? Result.Success()<br>            : Error.Validation(&quot;input_even&quot;),<br>        input =&gt; input % 3 == 0<br>            ? Result.Success()<br>            : Error.Validation(&quot;input_multiple_of_3&quot;)<br>    ],<br>    context: 120);</pre><p><strong>Conditional rules</strong> — branching based on evaluation:</p><pre>Result result = RuleEngine.If(<br>    rule: input =&gt; input &gt; 0,<br>    success: input =&gt; input &lt; 100,<br>    failure: input =&gt; input % 2 == 0,<br>    context: 120);</pre><h3>Rule types and function signatures</h3><p>For reference, here is the complete type system the Rule Engine provides.</p><p><strong>OOP Rule Types</strong></p><p>Simple rules:</p><pre>IRule&lt;TContext&gt;<br>IRule&lt;TContext, TResult&gt;<br>IAsyncRule&lt;TContext&gt;<br>IAsyncRule&lt;TContext, TResult&gt;</pre><p>Linear rules:</p><pre>ILinearRule&lt;TContext&gt;<br>ILinearRule&lt;TContext, TResult&gt;<br>ILinearAsyncRule&lt;TContext&gt;<br>ILinearAsyncRule&lt;TContext, TResult&gt;</pre><p>OR rules:</p><pre>IOrRule&lt;TContext&gt;<br>IOrRule&lt;TContext, TResult&gt;<br>IOrAsyncRule&lt;TContext&gt;<br>IOrAsyncRule&lt;TContext, TResult&gt;</pre><p>AND rules:</p><pre>IAndRule&lt;TContext&gt;<br>IAndRule&lt;TContext, TResult&gt;<br>IAndAsyncRule&lt;TContext&gt;<br>IAndAsyncRule&lt;TContext, TResult&gt;</pre><p>Conditional rules:</p><pre>IConditionalRule&lt;TContext&gt;<br>IConditionalRule&lt;TContext, TResult&gt;<br>IConditionalAsyncRule&lt;TContext&gt;<br>IConditionalAsyncRule&lt;TContext, TResult&gt;</pre><p><strong>Functional Approach Signatures</strong></p><p>Simple function signatures:</p><pre>Func&lt;TContext, Result&gt;<br>Func&lt;TContext, CancellationToken, Result&gt;<br>Func&lt;TContext, CancellationToken, ValueTask&lt;Result&gt;&gt;</pre><p>Generic result returning functions:</p><pre>Func&lt;TContext, Result&lt;TResult&gt;&gt;<br>Func&lt;TContext, CancellationToken, Result&lt;TResult&gt;&gt;<br>Func&lt;TContext, CancellationToken, ValueTask&lt;Result&lt;TResult&gt;&gt;&gt;</pre><p>This rich type system lets you choose the appropriate rule type for each scenario, mix synchronous and asynchronous operations freely, enhance type safety with generic results, manage resources properly with cancellation token support, and use functional and OOP approaches together in the same codebase.</p><h3>Conclusion</h3><p>The Rule Engine Pattern changed how I approach business validation in C#. What used to be scattered if chains buried in service methods became composable, testable, self-documenting rule objects. The Result Pattern eliminated the guesswork around error handling — no more wondering whether a method throws or returns null or silently logs.</p><p>If your codebase has business rules spread across multiple layers, if your validation error messages are inconsistent, if testing your domain logic requires setting up the entire application context — this pattern is worth adopting. Start with one domain entity, extract its rules into composable objects, and see how it feels. In my experience, once the pattern is in place, it becomes the obvious way to add new rules.</p><p>The project is open source. You can examine the source code, fork it, and contribute.</p><ul><li><a href="https://www.nuget.org/packages/CSharpEssentials">NuGet Package</a></li><li><a href="https://github.com/senrecep/CSharpEssentials">GitHub Repository</a></li><li><a href="https://www.nuget.org/profiles/recepsen">All My NuGet Packages</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=14bb1c72d700" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Google Cloud Secret Manager Integration for Your .NET Applications]]></title>
            <link>https://senrecep.medium.com/google-cloud-secret-manager-integration-for-your-net-applications-84f2576f6027?source=rss-10245e9040f4------2</link>
            <guid isPermaLink="false">https://medium.com/p/84f2576f6027</guid>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[nuget]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[security]]></category>
            <category><![CDATA[devops]]></category>
            <dc:creator><![CDATA[Recep Şen]]></dc:creator>
            <pubDate>Thu, 30 Jan 2025 17:04:58 GMT</pubDate>
            <atom:updated>2026-06-20T00:55:11.807Z</atom:updated>
            <content:encoded><![CDATA[<h3>Google Cloud Secret Manager Integration for Your .NET Applications</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-xH_ywG0vq8mwoTc0r_BwQ.jpeg" /></figure><p>Every .NET developer eventually hits the same wall: you have API keys, database connection strings, and passwords scattered across appsettings.json files, environment variables, and maybe even hardcoded somewhere you would rather not admit. You know it is not sustainable. You know it is not secure. But wiring up a proper secrets management solution always feels like it should be simpler than it actually is.</p><p>I hit that wall while working on a microservice architecture running on Google Cloud. Google’s own Secret Manager client library works fine on its own, but getting it to play nicely with .NET’s IConfiguration system -- the thing your entire application already depends on for configuration -- was more friction than I wanted. Especially when you multiply that friction across multiple services, multiple environments, and multiple regions.</p><p>So I built a library to fix it. CSharpEssentials.GcpSecretManager bridges Google Cloud Secret Manager and .NET’s configuration system so that secrets show up exactly like values from appsettings.json. No special access patterns, no custom service registrations -- just the standard IConfiguration interface your code already uses.</p><h3>What the Library Offers</h3><p>The library focuses on the problems that actually come up in production. It provides seamless Google Cloud Secret Manager integration with .NET’s IConfiguration, prefix-based filtering so each service only loads its own secrets, batch processing for performance when you have hundreds of secrets, region-specific configuration for latency-sensitive deployments, and support for both JSON-parsed and raw secret values.</p><h3>Getting Started</h3><p>Install the NuGet package and you are ready to go:</p><pre>dotnet add package CSharpEssentials.GcpSecretManager</pre><h3>Usage Scenarios</h3><p>The library supports several configurations depending on your architecture. Here are the most common ones.</p><h3>Simple Application</h3><pre>builder.Configuration.AddGcpSecretManager();</pre><pre>{<br>  &quot;GoogleSecretManager&quot;: {<br>    &quot;Projects&quot;: [<br>      {<br>        &quot;ProjectId&quot;: &quot;your-project-id&quot;<br>      }<br>    ]<br>  }<br>}</pre><p>This is the quickest path. You define the project ID in appsettings.json, call AddGcpSecretManager(), and every secret in that project becomes available through IConfiguration. It works well when you have a single application with a single GCP project and just want your secrets centralized without any ceremony.</p><h3>Microservice Architecture</h3><pre>{<br>  &quot;GoogleSecretManager&quot;: {<br>    &quot;Projects&quot;: [<br>      {<br>        &quot;ProjectId&quot;: &quot;payment-service-prod&quot;,<br>        &quot;PrefixFilters&quot;: [<br>          &quot;payment_&quot;<br>        ],<br>        &quot;Region&quot;: &quot;europe-west1&quot;<br>      },<br>      {<br>        &quot;ProjectId&quot;: &quot;user-service-prod&quot;,<br>        &quot;PrefixFilters&quot;: [<br>          &quot;user_&quot;<br>        ],<br>        &quot;Region&quot;: &quot;europe-west1&quot;<br>      }<br>    ]<br>  }<br>}</pre><p>In a microservice setup, you typically have separate GCP projects per service, and each service should only load the secrets it actually needs. Prefix-based filtering makes this clean: the payment service loads only payment_* secrets, the user service loads only user_* secrets. No accidental cross-contamination, and startup stays fast because you are not pulling in hundreds of irrelevant secrets.</p><h3>Multi-Region Application</h3><pre>{<br>  &quot;GoogleSecretManager&quot;: {<br>    &quot;Projects&quot;: [<br>      {<br>        &quot;ProjectId&quot;: &quot;my-app-prod&quot;,<br>        &quot;Region&quot;: &quot;europe-west1&quot;,<br>        &quot;PrefixFilters&quot;: [<br>          &quot;eu_&quot;<br>        ]<br>      },<br>      {<br>        &quot;ProjectId&quot;: &quot;my-app-prod&quot;,<br>        &quot;Region&quot;: &quot;us-central1&quot;,<br>        &quot;PrefixFilters&quot;: [<br>          &quot;us_&quot;<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><p>When your application runs across regions and latency matters, you can point each deployment to the closest Secret Manager replica. The same project can be referenced multiple times with different regions and prefix filters, so your EU deployment pulls eu_* secrets from europe-west1 while your US deployment pulls us_* secrets from us-central1.</p><h3>Development/Staging/Production</h3><pre>builder.Configuration.AddGcpSecretManager(options =&gt;<br>{<br>    options.BatchSize = 10;<br>    options.PageSize = 300;<br>    options.AddProject(new ProjectSecretConfiguration<br>    {<br>        ProjectId = &quot;my-app-&quot; + environment,<br>        PrefixFilters = [$&quot;{environment}_&quot;]<br>    });<br>});</pre><p>This approach gives you programmatic control over the configuration. You can dynamically set the project ID and prefix based on the current environment, and tune performance parameters like BatchSize and PageSize for your specific workload. It fits naturally into CI/CD pipelines where the environment name drives everything.</p><h3>JSON and Raw Secrets</h3><pre>{<br>  &quot;GoogleSecretManager&quot;: {<br>    &quot;Projects&quot;: [<br>      {<br>        &quot;ProjectId&quot;: &quot;my-app-prod&quot;,<br>        &quot;SecretIds&quot;: [<br>          &quot;app-config&quot;,<br>          &quot;service-account&quot;,<br>          &quot;ssl-cert&quot;<br>        ],<br>        &quot;PrefixFilters&quot;: [<br>          &quot;app_&quot;,<br>          &quot;creds_&quot;<br>        ],<br>        &quot;RawSecretIds&quot;: [<br>          &quot;service-account&quot;,<br>          &quot;ssl-cert&quot;<br>        ],<br>        &quot;RawSecretPrefixes&quot;: [<br>          &quot;creds_&quot;<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><p>By default, the library tries to parse secret values as JSON and flatten them into configuration keys. But not everything is JSON. Service account credential files, SSL/TLS certificates, SSH private keys, and PEM files are all stored as raw text. Marking them with RawSecretIds or RawSecretPrefixes tells the library to skip JSON parsing and store the value as-is.</p><p>One thing to keep in mind: secrets listed in RawSecretIds and RawSecretPrefixes must also appear in SecretIds or PrefixFilters. The raw flags control how a secret is parsed, not whether it is loaded.</p><h3>Performance Tips</h3><p>There are a few levers you can pull to keep startup times low. Increase BatchSize (try 20) when you have many secrets, and increase PageSize (try 500) for large projects. Always specify Region to avoid unnecessary cross-region calls. Use PrefixFilters aggressively so you are only loading what you need. And for specific known secrets, SecretIds lets you skip the listing step entirely and fetch them directly.</p><h3>Security Tips</h3><p>On the security side, use service accounts with minimal permissions — secretmanager.secretAccessor is usually all you need. Create separate service accounts per environment so a compromised dev credential cannot read production secrets. Organize your secret names with environment-based prefixes (prod_, staging_, dev_) and service-based prefixes (auth_, payment_, email_) to keep things manageable as your secret count grows.</p><h3>Wrapping Up</h3><p>CSharpEssentials.GcpSecretManager takes the friction out of using Google Cloud Secret Manager in .NET applications. Whether you are running a single web app or orchestrating dozens of microservices across regions, the configuration options scale with your architecture. The library is open source and actively maintained — contributions and issue reports are welcome.</p><h3>Links</h3><ul><li><a href="https://www.nuget.org/packages/CSharpEssentials.GcpSecretManager">NuGet Package</a></li><li><a href="https://github.com/SenRecep/CSharpEssentials/tree/main/CSharpEssentials.GcpSecretManager">GitHub — GcpSecretManager</a></li><li><a href="https://github.com/SenRecep/CSharpEssentials">CSharpEssentials Library Family</a></li><li><a href="https://www.nuget.org/profiles/recepsen">All My NuGet Packages</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=84f2576f6027" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>