Anthropic Claude Code Mimarisi: CLAUDE.md, Özel Slash Komutları ve Üretim Ortamı İçin En Popüler 10 Otonom Mühendislik Skill’i

Reaktif Sohbetten Deterministik Ajanik Mühendisliğe Geçiş

Büyük dil modellerinin yazılım geliştirme süreçlerine entegrasyonunda ilk nesil yaklaşım, geliştiricinin IDE içinde satır tamamlaması veya sohbet penceresine kod parçacıkları yapıştırması üzerine kuruluydu. Ancak büyük ölçekli kurumsal kod tabanlarında (monorepo yapıları, dağıtık mikroservisler, sıkı regülasyonlu finans ve sağlık sistemleri) rastgele serbest metin istemleriyle (ad-hoc prompting) yürütülen ajan etkileşimleri ciddi bir mimari sürüklenmeye (architectural drift) yol açmaktadır. Ajanın her oturumda proje kurallarını yeniden keşfetmeye çalışması, test yazmadan üretim kodunu değiştirmesi, veritabanı tablolarını kilitleyen migration dosyaları üretmesi veya bağlam penceresi (context window) dolduğunda önceki mimari kısıtları unutması, kontrolsüz otomasyonun en büyük darboğazlarıdır.

Anthropic Claude Code, doğrudan işletim sistemi kabuğu (shell), dosya sistemi, Git çalışma ağacı ve Model Context Protocol (MCP) sunucularıyla etkileşime giren terminal tabanlı bir ajanik çalışma zamanı (agentic runtime) sunarak bu paradigmayı kökten değiştirmiştir. Claude Code'un gerçek mühendislik gücü, ham model zekasından ziyade etrafına inşa edilen deterministik kontrol katmanlarından gelmektedir. Bu katmanlar dört temel sütun üzerinde yükselir:

1. Hiyerarşik CLAUDE.md ve .claude/rules/ Bellek Mimarisi: Projenin değişmez mimari kurallarını, derleme/test komutlarını ve sınırlarını oturum başında sıfır arama maliyetiyle bağlama enjekte eden kalıcı bellek katmanı.
2. Özel Slash Komutları (.claude/commands/*.md) ve Kademeli Yüklenen Yetenekler (.claude/skills/<ad>/SKILL.md): Tekrarlanan karmaşık mühendislik iş akışlarını $ARGUMENTS parametreleri ve araç kısıtlamalarıyla (allowed-tools) standartlaştıran modüler komut paketleri.
3. Yaşam Döngüsü Kancaları (PreToolUse, PostToolUse, Stop): LLM'in olasılıksal doğasını deterministik kabuk komutlarıyla denetleyen; tehlikeli kabuk çağrılarını engelleyen ve her dosya düzenlemesinden sonra otomatik linter/tip kontrolü çalıştıran güvenlik kapıları.
4. İzole Alt Ajanlar (.claude/agents/) ve Git Worktree Paralelliği: Bağlam kirliliğini (context pollution) önlemek için her görevi kendi bağımsız bağlam penceresinde veya izole edilmiş bir Git çalışma dizininde yürüten çoklu ajan orkestrasyonu.

Bu teknik referans makalesinde, Claude Code mimarisinin iç çalışma prensipleri, CLAUDE.md ile .claude/skills arasındaki yapısal farklar ve küresel yazılım mühendisliği ekiplerinin üretim ortamında en yoğun kullandığı 10 temel otonom mühendislik yeteneği (skill & slash command) kod örnekleri ve mimari tablolarla incelenmektedir.

1. Hiyerarşik CLAUDE.md Mimarisi ve .claude/skills Evrimi

Claude Code bir çalışma dizininde başlatıldığında (/init veya doğrudan oturum açılışı), dosya sistemini yukarıdan aşağıya tarayarak katmanlı bir bellek ağacı oluşturur. Bu mimari, tüm kuralları tek bir devasa dosyaya yığmak yerine kapsam bazlı bağlam enjeksiyonu (scoped context injection) uygular:

• Kurumsal / Küresel Katman (~/.claude/CLAUDE.md): Geliştiricinin tüm projelerinde geçerli olan güvenlik ilkeleri, tercih edilen CLI araçları (ripgrep, fd, jq) ve genel kodlama standartları.
• Depo Kök Katmanı (./CLAUDE.md ve ./.claude/rules/*.md): Monorepo veya mikroservis deposunun temel mimari değişmezleri (invariants), paket yöneticisi komutları, test çalıştırma protokolleri ve katmanlar arası bağımlılık kuralları.
• Yerel Geliştirici Katmanı (./CLAUDE.local.md): .gitignore içinde tutulan, yerel veritabanı portları, test ortamı uç noktaları ve kişisel çalışma alanı ayarlarını barındıran özel dosya.
• Alt Dizin / Modül Katmanı (./services/payment/CLAUDE.md): Yalnızca ajan ilgili alt dizindeki dosyaları okuduğunda veya düzenlediğinde dinamik olarak bağlama yüklenen, modüle özgü alan (domain) kuralları.

.claude/commands ve .claude/skills Arasındaki Mimari Fark

Claude Code ekosisteminde özel iş akışlarını tanımlamanın iki tamamlayıcı yolu bulunur:

1. Özel Slash Komutları (.claude/commands/<komut-adi>.md): Kullanıcı tarafından terminalde açıkça /project:<komut-adi> <argümanlar> (veya doğrudan /<komut-adi>) şeklinde tetiklenen deterministik şablonlardır. Dosya içindeki $ARGUMENTS yer tutucusu, komut satırından geçirilen dal adı, PR numarası veya hata koduyla dinamik olarak değiştirilir. Ayrıca !backtick sözdizimi (örneğin !git status veya `!`gh pr diff) kullanılarak, istem henüz modele gönderilmeden önce kabuk komutlarının çıktısı doğrudan şablona gömülebilir.
2. Ajan Yetenekleri (.claude/skills/<skill-adi>/SKILL.md): Klasik komutların evrimleşmiş halidir. Kademeli Bağlam Açıklaması (Progressive Disclosure) ilkesiyle çalışır: Oturum başında Claude Code yalnızca SKILL.md dosyalarının YAML üstbilgisindeki (frontmatter) name ve description alanlarını (yaklaşık 30–50 token) belleğe alır. Görev tanımı ilgili yeteneğin açıklamasıyla eşleştiğinde, ajan SKILL.md gövdesini, yardımcı betikleri (scripts/) ve şablonları o anda bağlama yükler. Böylece 50 farklı mühendislik yeteneği tanımlansa dahi başlangıç bağlam penceresi şişmez.

<!-- Dosya: .claude/skills/tdd-red-green/SKILL.md -->
---
name: tdd-red-green
description: Yeni bir özellik eklenirken veya hata düzeltilirken uygulanacak zorunlu Red-Green-Refactor Test-Driven Development (TDD) disiplini. Üretim kodu yazılmadan önce başarısız test üretilmesini şart koşar.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash(npm run test*)
  - Bash(npx vitest*)
  - Bash(./mvnw test*)
---

# Otonom TDD (Red-Green-Refactor) Protokolü

Hedeflenen görev: $ARGUMENTS

## Kesin Uygulama Adımları
1. **RED (Başarısız Test İnşası):**
   - Hedef davranış için yalnızca birim veya entegrasyon testi yazılır.
   - Üretim sınıflarında (`src/main/**`) hiçbir değişiklik yapılmaz.
   - Test çalıştırılır ve beklenen doğrulama (assertion) hatasıyla başarısız olduğu kanıtlanır.

2. **GREEN (Minimum Geçerli Uygulama):**
   - Yalnızca başarısız olan testi geçirecek en yalın üretim kodu yazılır.
   - Spekülatif soyutlama veya kapsam dışı optimizasyon eklenmez.
   - Test paketi yeniden çalıştırılır ve %100 geçiş doğrulanır.

3. **REFACTOR (Yapısal İyileştirme):**
   - Kod tekrarları temizlenir, tip güvenliği sıkılaştırılır ve sınır durumları (edge-cases) kontrol edilir.
   - Her değişiklikten sonra testlerin yeşil kaldığı teyit edilir.

2. Üretim Ortamı İçin En Popüler 10 Claude Code Skill ve Slash Komutu

Aşağıdaki 10 mühendislik yeteneği, kurumsal yazılım ekiplerinin Claude Code'u günlük geliştirme, güvenlik denetimi ve operasyonel müdahale süreçlerinde standartlaştırmak için kullandığı en etkili desenleri temsil etmektedir.

Yetenek 1: Otonom TDD Döngüsü (/project:tdd — Red-Green-Refactor)

Dil modellerinin en yaygın zafiyeti, hem üretim kodunu hem de birim testini aynı anda yazarak üretim kodundaki mantık hatasını doğrulayan totolojik testler üretmesidir. /project:tdd komutu ve tdd-red-green yeteneği, süreci üç katı aşamaya böler. İlk aşamada ajan yalnızca src/test/ dizinine yazma yetkisine sahiptir ve yeni gereksinimi doğrulayan bir test yazar. Test çalıştırılıp Red (başarısız) durumu terminal çıktısıyla kanıtlanmadan ikinci aşamaya geçilemez. İkinci aşamada (Green) testi geçirecek minimum kod yazılır; üçüncü aşamada (Refactor) ise mimari temizlik yapılarak regresyon paketi doğrulanır.

Yetenek 2: Git Worktree ile Paralel Ajan Çalıştırma (/project:worktree-spawn)

Tek bir çalışma dizininde birden fazla ajanın aynı anda dosya düzenlemesi, Git indeks kilitlenmelerine (index.lock) ve derleme önbelleği bozulmalarına neden olur. Claude Code'un yerleşik claude --worktree bayrağı ve özel /project:worktree-spawn komutu, her görevi git worktree add ../wt-<görev> -b feat/<görev> komutuyla bağımsız bir dosya sistemi dizinine ayırır.

Ancak Git worktree kullanımında iki kritik mühendislik problemi ortaya çıkar: node_modules (veya yerel derleme önbellekleri) ile .gitignore içindeki .mcp.json / .env dosyaları yeni çalışma ağacına otomatik taşınmaz. Gelişmiş /project:worktree-spawn betiği bu sorunu şu otomasyonla çözer:

#!/usr/bin/env bash
# Dosya: .claude/scripts/spawn-worktree.sh
set -euo pipefail

TASK_SLUG="$1"
BASE_BRANCH="${2:-main}"
REPO_ROOT="$(git rev-parse --show-toplevel)"
WT_DIR="$(dirname "$REPO_ROOT")/wt-${TASK_SLUG}"

echo "[Worktree] İzole çalışma alanı oluşturuluyor: ${WT_DIR}"
git worktree add "$WT_DIR" -b "feat/${TASK_SLUG}" "$BASE_BRANCH"

# 1. Ağır bağımlılıkları yeniden indirmek yerine sembolik bağlantı (symlink) kur
if [ -d "${REPO_ROOT}/node_modules" ] && [ ! -e "${WT_DIR}/node_modules" ]; then
  ln -s "${REPO_ROOT}/node_modules" "${WT_DIR}/node_modules"
fi

# 2. Git-ignore kapsamındaki yerel yapılandırmaları kopyala ve port çakışmasını önle
for cfg in .env.local CLAUDE.local.md .mcp.json; do
  if [ -f "${REPO_ROOT}/${cfg}" ]; then
    cp "${REPO_ROOT}/${cfg}" "${WT_DIR}/${cfg}"
  fi
done

echo "[Worktree] Hazır: cd ${WT_DIR} && claude"

Bu yapı sayesinde bir mühendis aynı anda 4 farklı terminal sekmesinde 4 ayrı Claude Code ajanını (örneğin: ödeme servisi refaktörü, e2e test yazımı, dokümantasyon güncellemesi ve güvenlik yaması) sıfır bağlam ve dosya çakışmasıyla paralel çalıştırabilir.

Yetenek 3: Derin Mimari PR İnceleme ve Güvenlik Denetimi (/project:pr-audit)

Yüzeysel kod inceleme botları yalnızca sözdizimi veya basit stil hatalarını yakalarken, /project:pr-audit komutu allowed-tools: [Read, Grep, Glob, Bash(git diff*), Bash(gh pr view*)] kısıtlamasıyla salt-okuma (read-only) modunda çalışır. Ajan, !gh pr diff $ARGUMENTS`` çıktısını alır ancak incelemeyi yalnızca değişen satırlarla sınırlamaz; değiştirilen fonksiyonları çağıran tüm üst katmanları (call graph) Grep ile tarar.

Denetim matrisi dört boyutu kapsar:

• Yetkilendirme ve Sahiplik (IDOR / BOLA): Çok kiracılı (multi-tenant) uç noktalarda tenantId veya userId doğrulamasının atlanıp atlanmadığı.
• Enjeksiyon ve SSRF: Ham SQL sorguları, şablon motoru girdileri (SSTI) ve dış URL çağrılarında iç ağ (169.254.169.254, localhost) filtrelemesi.
• Eşzamanlılık ve Yarış Koşulları (Race Conditions): Finansal bakiye veya stok güncellemelerinde iyimser/kötümser kilitleme (SELECT ... FOR UPDATE veya @Version) eksikliği.
• Hata Sızıntısı: Stacktrace veya iç altyapı detaylarının istemci yanıtına sızdırılması.

Yetenek 4: Pre-Commit ve Yaşam Döngüsü Hook Otomasyonu (PreToolUse & PostToolUse)

CLAUDE.md içindeki talimatlar olasılıksaldır; bağlam penceresi karmaşıklaştığında model bir kuralı gözden kaçırabilir. Oysa .claude/settings.json içinde tanımlanan Hooks (Kancalar) %100 deterministiktir ve işletim sistemi düzeyinde yürütülür.

• PreToolUse: Ajan bir aracı (Bash, Write, Edit) çağırmadan hemen önce tetiklenir. Standart girdiden (stdin) araç adını ve parametrelerini JSON olarak alır. Eğer denetim betiği exit 2 koduyla dönerse, araç çağrısı kesin olarak engellenir ve hata mesajı ajana geri bildirim olarak iletilir.
• PostToolUse: Dosya düzenleme (Edit / Write) tamamlandığı milisaniyede tetiklenir; yalnızca değişen dosya üzerinde biçimlendirici (prettier, gofmt, spotless) ve hızlı tip denetleyicisi (tsc --noEmit) çalıştırır.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' | grep -Eq '(rm -rf /|git push --force|DROP DATABASE|--no-verify)' && { echo 'BLOCKED: Yıkıcı veya güvenlik kapısını atlayan komut tespit edildi!' >&2; exit 2; } || exit 0"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -Eq '(\\.env\\.production|id_rsa|secrets\\.yaml)' && { echo 'BLOCKED: Üretim gizli anahtar dosyalarına doğrudan erişim yasaktır!' >&2; exit 2; } || exit 0"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path'); if [[ \"$FILE\" =~ \\.(ts|tsx)$ ]]; then npx eslint --fix \"$FILE\" && npx tsc --noEmit; fi"
          }
        ]
      }
    ]
  }
}

Yetenek 5: Bağlam Sıkıştırma (Context Compaction) ve Hiyerarşik Bellek (/project:checkpoint)

Uzun süren hata ayıklama veya çok adımlı refaktör oturumlarında, terminal çıktıları ve dosya okumaları bağlam penceresini hızla doldurur. Bağlam doluluk oranı %70'i aştığında modellerde "ortada kaybolma" (lost-in-the-middle) etkisi ve gecikme artışı gözlemlenir. Yerleşik /compact komutunu tamamlayan özel /project:checkpoint yeteneği, oturum sıfırlanmadan önce yapılandırılmış bir durum özeti üretir:

1. Tamamlanan mimari değişiklikleri ve doğrulanan testleri listeler.
2. Çözülmemiş yan etkileri ve bir sonraki adımı .claude/memory/ACTIVE_TASK.md dosyasına yazar.
3. Ardından /compact çağrısıyla binlerce satırlık ham log çıktısını budayarak token tüketimini %65 ila %80 oranında düşürürken, kritik tasarım kararlarının kaybolmasını önler.

Yetenek 6: Çoklu Servis API Sözleşme Doğrulama (/project:contract-check)

Mikroservis ve çoklu istemci (Web + iOS/Android) mimarilerinde en sık yaşanan üretim arızası, arka uçtaki bir Java/Go DTO sınıfında veya enum değerinde yapılan değişikliğin istemci TypeScript tiplerine yansıtılmamasıdır (Contract Drift). /project:contract-check komutu:

• Arka uçtaki Controller/DTO tanımları veya OpenAPI/Protobuf şemaları ile ön uçtaki Zod/TypeScript arayüzlerini çapraz tarar.
• İstemcinin beklediği ancak API'nin döndürmediği alanları, nullable uyumsuzluklarını ve enum sabitlerindeki kaymaları tespit ederek kırılma matrisi (breaking change report) çıkarır.

Yetenek 7: Otomatik Hata Ayıklama: Log ve Stacktrace Triage (/project:triage)

Üretim veya hazırlık (staging) ortamında oluşan bir istisna (exception) yığın izini manuel olarak incelemek yerine, /project:triage komutu hatayı doğrudan kod tabanındaki yürütme grafiğiyle eşleştirir. Ajan:

1. Stacktrace içindeki çerçeveleri (frames) ayrıştırarak üçüncü taraf kütüphane gürültüsünü filtreler ve uygulama kodundaki tam satırları (Read) açar.
2. git log -S ve git blame ile ilgili satırlara son 14 günde dokunan commit'leri inceler.
3. Hatayı deterministik olarak yeniden üreten bir birim testi yazar ve kök nedeni (Root Cause Analysis - RCA) kanıtlarıyla raporlar.

Yetenek 8: Veritabanı Şema ve Migration Denetçisi (/project:migration-guard)

Büyük hacimli üretim tablolarında yapılan dikkatsiz bir şema değişikliği (ALTER TABLE), veritabanında dakikalarca süren ACCESS EXCLUSIVE LOCK oluşturarak tüm sistemi kesintiye uğratabilir. /project:migration-guard yeteneği, Flyway, Liquibase veya Prisma migration dosyalarını canlıya çıkmadan önce denetler:

• PostgreSQL'de indeks eklenirken CREATE INDEX CONCURRENTLY kullanılıp kullanılmadığını kontrol eder.
• Mevcut bir sütuna NOT NULL kısıtı eklenirken tablo taramasını önleyen CHECK (... IS NOT NULL) NOT VALID ve ardından VALIDATE CONSTRAINT iki aşamalı deseninin uygulanmasını zorunlu kılar.
• Sütun silme veya yeniden adlandırma işlemlerinde Expand-and-Contract (Genişlet ve Daralt) sıfır kesintili dağıtım uyumluluğunu doğrular.

Yetenek 9: Performans Darboğazı ve Flamegraph Analizi (/project:perf-profile)

Uygulama gecikmelerinde (p99 latency) sezgisel tahminlerle yapılan optimizasyonlar çoğu zaman yanlış katmana odaklanır. /project:perf-profile komutu; Java Flight Recorder (JFR), Go pprof, Node.js V8 CPU profilleri veya PostgreSQL EXPLAIN (ANALYZE, BUFFERS) çıktılarını girdi olarak alır:

• ORM katmanındaki gizli N+1 sorgu patlamalarını (@EntityGraph veya JOIN FETCH eksikliklerini) tespit eder.
• Sıcak döngülerde (hot loops) gereksiz nesne tahsisi (allocation pressure), JSON serileştirme darboğazları ve senkron kilit çekişmelerini (lock contention) bularak somut benchmark karşılaştırmalı yama üretir.

Yetenek 10: MCP Sunucu Orkestrasyonu (.mcp.json) ve Alt Ajan Koordinasyonu

Skills katmanı Claude Code'a nasıl çalışacağını öğretirken, Model Context Protocol (MCP) sunucuları ajana dış dünyayla güvenli iletişim kurma yeteneği kazandırır. Depo kökündeki .mcp.json dosyası ve .claude/agents/ altındaki uzman alt ajanlar birlikte çalışarak tam otonom bir mühendislik hattı kurar:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://readonly_auditor@localhost:5432/app_staging"
      ]
    },
    "github-enterprise": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_MCP_TOKEN}"
      }
    },
    "sentry-telemetry": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_MCP_TOKEN}"
      }
    }
  }
}

Bu kurguda ana ajan; Sentry MCP üzerinden canlı hata telemetrisini çeker, postgres-readonly MCP üzerinden hazırlık veritabanındaki sorgu planını (EXPLAIN) doğrular, .claude/agents/security-reviewer.md alt ajanına güvenlik denetimini devreder ve GitHub MCP üzerinden tüm kanıtları içeren PR'ı açar.

3. En Popüler 10 Claude Code Mühendislik Yeteneğinin Mimari Karşılaştırma Tablosu

Aşağıdaki tablo, incelenen 10 temel yeteneğin tetikleme mekanizmalarını, bağlam maliyeti profillerini, izolasyon seviyelerini ve üretim ortamındaki birincil mühendislik etkilerini karşılaştırmaktadır:

4. Kurumsal Uygulama İçin Mimari En İyi Pratikler

Claude Code altyapısını bireysel denemelerden kurumsal mühendislik standardına taşırken üç temel tasarım ilkesi korunmalıdır:

1. CLAUDE.md Dosyalarını Yalın ve Doğrulanabilir Tutmak: Kök CLAUDE.md dosyası 150–200 satırı aşmamalıdır. Uzun API kılavuzları veya nadiren kullanılan prosedürler kök dosyaya yazılmak yerine .claude/skills/ altındaki yetenek paketlerine taşınmalıdır; böylece yalnızca ihtiyaç duyulduğunda bağlama yüklenir.
2. Güvenliği İstemlere Değil, Hook ve Araç Kısıtlarına Devretmek: "Üretim veritabanını silmeniz yasaktır" gibi olasılıksal metin kuralları yerine .claude/settings.json içindeki PreToolUse kancaları (exit 2) ve allowed-tools beyaz listeleriyle güvenlik işletim sistemi seviyesinde zorunlu kılınmalıdır.
3. Versiyon Kontrolü ile Ekip Senkronizasyonu: .claude/commands/, .claude/skills/, .claude/agents/ ve .claude/settings.json dosyaları doğrudan Git deposuna dahil edilerek tüm mühendislik ekibinin aynı deterministik kalite kapılarını kullanması sağlanmalı; kişiye özel ayarlar ise CLAUDE.local.md ve .claude/settings.local.json içinde izole edilmelidir.