Ekipte Claude Code: Paylaşılan .claude Klasörü, Plugin'ler, Output Style'lar ve Managed Settings

Sürüm notu: Bu yazı Claude Code 2.1.325'i (13 Kasım 2026) anlatır; plugin, marketplace, output style ve managed settings ayrıntıları 15 Kasım 2026'da code.claude.com/docs'taki Plugins overview, Create a Claude Code plugin, Add components to a plugin, Create a marketplace, Plugin loading reference, Manage Claude Code plugins for your organization, Code intelligence plugins, Plugin security and trust, Output styles, Deploy managed settings ve All settings sayfalarından kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. JSON dosyaları ayrıştırılıp plugin.json, marketplace.json ve settings dosyaları schemastore.org şemalarıyla doğrulanmış, frontmatter'lar YAML (yapılandırma dosyalarında kullanılan metin veri biçimi) ayrıştırıcısıyla okunmuş, hooks.json'daki komutlar örnek hook girdileriyle PowerShell 7.7'de çalıştırılmıştır.

Önce Tahmin Et

Ayşe, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) önceki yazılarda biriken skill'leri, subagent'ları, hook'ları ve MCP (Model Context Protocol; dış araç ve veri kaynaklarına bağlanma protokolü) ayarını tek bir plugin'e taşıdı ve kendi makinesinde claude --plugin-dir ./plugins/bookstore-dev ile denedi. Üç şey dikkatini çekti: commit'lenmiş bir migration'ı düzenletmeye çalıştığında aynı ret iki kez geldi; daha önce sorusuz çalışan search_books tool'u yeniden onay istedi; PR (pull request kısaltması) merge edildikten sonra da CI'daki @claude job'ında migration guard hiç devreye girmedi.

Tahminin ne? Ret neden iki kez geldi, izin kuralı neden artık eşleşmiyor, CI'da hook'lar neden çalışmadı? Cevaplar plugin ve Üretimde Dikkat bölümlerinde.

Repo'ya Ne Girer, Ne Girmez

Ekip kullanımı, neyin herkesin ortak ayarı neyin kişisel olduğunu ayırmakla başlıyor. Bookstore'da commit'lenenler ve commit'lenmeyenler:

• Commit'lenir: CLAUDE.md, .claude/rules/, .claude/settings.json, .worktreeinclude, .claude-plugin/marketplace.json ve plugins/bookstore-dev/.
• Commit'lenmez: .claude/settings.local.json, CLAUDE.local.md, .claude/worktrees/, plugin'in node_modules klasörü ve ~/.claude/ altındaki her şey.

Claude Code settings.local.json'ı kendisi yazdığında dosyayı global git exclude listesine ekliyor; elle oluşturduysan .gitignore'a sen ekle. Ayar önceliği üçüncü yazıdaki gibi: managed settings, komut satırı, settings.local.json, .claude/settings.json ve en sonda ~/.claude/settings.json.

Plugin Ne Zaman Gerekir

Plugin, Claude Code'un tek parça olarak kurup yüklediği bir klasör: skill'ler, subagent'lar, hook'lar, MCP ve LSP (Language Server Protocol; editöre tip hatası ve sembol bilgisi veren protokol) server'ları, output style'lar ve .claude-plugin/plugin.json manifest'i. Bunların hepsi plugin olmadan da çalışıyor; belgelerin önerisi de kurulum tek projeye ya da yalnız sana hizmet ettiği sürece standalone kalman. Plugin, ayarı ekiple paylaşmak, birden çok yerde kullanmak ya da sürümlü dağıtmak istediğinde anlam kazanıyor.

Bookstore tek repo olsa da plugin'e geçmenin iki somut sebebi var. Birincisi organizasyon tarafında: aşağıda göreceğimiz allowManagedHooksOnly açıldığında proje hook'ları çalışmıyor, managed settings'in zorunlu açtığı plugin'lerin hook'ları çalışıyor. İkincisi bakım: skill, agent, hook ve MCP ayarı tek birim olarak açılıp kapanıyor, /plugin ekranında bileşenleriyle görünüyor.

Bedeli de var. Etkin bir plugin her session'ın parçası: Claude'un kendiliğinden çağırabildiği her skill ve agent'ın adı ve açıklaması her turda context'te duruyor, MCP server'ları her session'la başlıyor, hook'lar her event'te çalışıyor. Plugin'in çalıştırdığı her şey senin kullanıcı yetkinle çalışıyor.

bookstore-dev Plugin'i

Plugin repo'nun içinde, plugins/bookstore-dev altında duruyor. Bileşen klasörleri plugin kökünde; .claude-plugin/ içinde yalnız manifest var, belgelere göre oraya konan bileşenler yüklenmiyor:

plugins/bookstore-dev/
├── .claude-plugin/plugin.json
├── skills/add-migration/SKILL.md
├── skills/angular-component/{SKILL.md,reference.md}
├── agents/{ef-query-reviewer,angular-a11y-checker,test-runner,ui-tester}.md
├── hooks/hooks.json
├── scripts/{protect-migrations,format-file,short-test-output,stop-guard}.ps1
├── output-styles/mentor.md
├── .mcp.json
├── dbhub.toml
├── sql/create-readonly-login.sql
├── package.json
└── package-lock.json

Manifest'te zorunlu alan yalnız name; bu ad plugin'in bütün skill ve agent'larının önekine dönüşüyor:

{
  "name": "bookstore-dev",
  "displayName": "Bookstore Dev",
  "description": "Skills, subagents, hooks and MCP servers for working on the Bookstore repository with Claude Code",
  "author": {
    "name": "Bookstore team"
  }
}

version'ı bilinçli olarak yazmadık. Belgelere göre version verirsen kullanıcılar bu değer değişene kadar cache'teki kopyada kalıyor; yazmazsan git'ten kurulan plugin commit'leri takip ediyor. Repo'dan yerinde yüklenen bir plugin'de ise version hiç dikkate alınmıyor.

Taşımada adlar değişiyor. /add-migration artık /bookstore-dev:add-migration, subagent bookstore-dev:ef-query-reviewer, /mcp'deki server plugin:bookstore-dev:bookstore, tool'lar da mcp__plugin_bookstore-dev_bookstore__search_books biçiminde. Tahmindeki ikinci sorunun cevabı bu: .claude/settings.json'daki mcp__bookstore__search_books kuralı yeni adla eşleşmiyor, kuralları yeni adlarla güncellemek gerekiyor. Plugin agent'larında permissionMode, hooks, mcpServers ve initialPrompt alanları yok sayılıyor; ui-tester'daki mcpServers satırını kaldırıp tools'taki wildcard'ı mcp__plugin_bookstore-dev_playwright__* yaptık.

Hook'lar hooks/hooks.json'a, settings dosyasındaki hooks nesnesiyle aynı biçimde taşınıyor. Değişen tek şey script yolu: her hook süreci CLAUDE_PLUGIN_ROOT ortam değişkenini alıyor. İlk event:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "& \"$env:CLAUDE_PLUGIN_ROOT\\scripts\\protect-migrations.ps1\"",
            "onFailure": "block",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hook'ların adında önek yok. Tahmindeki ilk sorunun cevabı da burada: orijinaller .claude/settings.json'da dururken plugin'i yüklersen aynı hook iki kez çalışıyor. Plugin'in çalıştığını gördükten sonra .claude/ altındaki kopyaları ve settings'teki hooks bloğunu sil. Skill ve agent'lar önekli olduğu için çakışmıyor, ama ikisi birden listede görünüyor.

MCP server'ları plugin kökündeki .mcp.json'da. ${CLAUDE_PLUGIN_ROOT} ve ${CLAUDE_PROJECT_DIR} command, args ve env alanlarında yerine konuyor; DBHub ve Playwright MCP paketleri artık plugin'in kendi package.json'ında:

{
  "mcpServers": {
    "bookstore": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["${CLAUDE_PROJECT_DIR}/src/Bookstore.Mcp.Server/bin/Debug/net10.0/Bookstore.Mcp.Server.dll"],
      "env": {
        "Bookstore__CustomerId": "7"
      }
    },
    "bookstore-db": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/node_modules/@bytebase/dbhub/dist/index.js",
        "--transport", "stdio",
        "--config=${CLAUDE_PLUGIN_ROOT}/dbhub.toml"
      ],
      "env": {
        "BOOKSTORE_RO_PASSWORD": "${BOOKSTORE_RO_PASSWORD}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/node_modules/@playwright/mcp/cli.js",
        "--browser", "msedge",
        "--isolated",
        "--allowed-origins", "http://localhost:4200"
      ]
    }
  }
}

package-lock.json'ı da ekledik. Plugin ileride git'ten kopyalanarak kurulursa Claude Code bağımlılıkları kendisi kuruyor; bunun için kökte package.json ile birlikte bir lockfile gerekiyor, kurulum lifecycle script'leri çalıştırılmadan ve 60 saniye sınırıyla yapılıyor.

Marketplace ve Ekibe Dağıtım

Marketplace, plugin'leri ve her birinin nereden alınacağını listeleyen bir katalog. Bookstore repo'sunun kökü aynı zamanda bir marketplace:

{
  "name": "bookstore",
  "description": "Claude Code plugins for the Bookstore repository",
  "owner": {
    "name": "Bookstore team"
  },
  "plugins": [
    {
      "name": "bookstore-dev",
      "source": "./plugins/bookstore-dev",
      "description": "Migration and component skills, review subagents, migration guard and format hooks, Bookstore MCP servers"
    }
  ]
}

source yolu marketplace kökünden yazılıyor ve .. içeremiyor. Girdinin name'i ile manifest'teki name aynı olmalı; kurulum kimliği bookstore-dev@bookstore girdinin adından oluşuyor. Ekip için gereken son parça .claude/settings.json'daki iki anahtar ve yeni adlı izin kuralları:

{
  "permissions": {
    "allow": [
      "mcp__plugin_bookstore-dev_bookstore__search_books",
      "mcp__plugin_bookstore-dev_bookstore__check_stock",
      "mcp__plugin_bookstore-dev_bookstore-db__search_objects"
    ]
  },
  "extraKnownMarketplaces": {
    "bookstore": {
      "source": {
        "source": "directory",
        "path": "./"
      }
    }
  },
  "enabledPlugins": {
    "bookstore-dev@bookstore": true
  }
}

Belgelere göre extraKnownMarketplaces yalnız workspace trust dialog'unu kabul ettiğin klasörde uygulanıyor. Yerel bir directory marketplace'i plugin'i göreli yolla listeliyorsa kurulum gerekmiyor; plugin session başında yerinde yükleniyor ve dosyalarda yaptığın değişiklik bir sonraki session'da ya da /reload-plugins ile geçerli oluyor. Göreli yol repo'nun ana checkout'una göre çözülüyor. Plugin'in MCP server'ları da proje .mcp.json'ı gibi server başına onaydan geçiyor. Yeni gelen geliştirici için kurulum:

git clone <bookstore-repo-url>
cd bookstore
npm ci --prefix plugins/bookstore-dev
claude

npm ci şart, çünkü yerinde yüklenen plugin'lerde Claude Code bağımlılık kurmuyor. Plugin'in kendisini geliştirirken claude --plugin-dir ./plugins/bookstore-dev ile tek session'lık yükleme, claude plugin validate ./plugins/bookstore-dev ile manifest ve frontmatter kontrolü, claude plugin details bookstore-dev ile bileşen listesi var.

Yerel marketplace yerine GitHub kaynağı da seçilebilir; fark sürüm ve kurulumda:

GitHub seçeneğinde marketplace'i repo'da bir kez claude plugin marketplace add your-org/bookstore --scope project ile kaydedip yazdığı .claude/settings.json'ı commit'liyorsun; enabledPlugins tek başına kurmadığı için her geliştirici yukarıdaki tek install komutunu her clone'da bir kez çalıştırıyor. Bookstore'da plugin repo'yla birlikte değiştiği için directory kaynağını seçtik.

Anthropic'in Marketplace'leri ve Code Intelligence

Claude Code ilk interaktif terminal session'ında Anthropic'in resmî marketplace'ini (claude-plugins-official) kendisi ekliyor; topluluk marketplace'i claude-community'yi sen eklemelisin. Bu iki ad yalnız github.com/anthropics/ altındaki repo'lardan kabul ediliyor; bizimki dahil geri kalan her marketplace üçüncü taraf.

Resmî marketplace'teki code intelligence plugin'leri Claude'a bir language server bağlıyor: düzenlemeden sonra tip hatalarını görüyor, sembole göre geziniyor. C# için csharp-lsp ve TypeScript için typescript-lsp var. Plugin language server'ı içermiyor, binary'yi önce sen kuruyorsun:

dotnet tool install --global csharp-ls
npm install -g typescript-language-server typescript

/plugin install csharp-lsp@claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official

Binary her makinede ayrı kurulduğu için bu plugin'leri repo'ya değil user scope'a kurmak mantıklı. Server, Claude ilgili uzantıdaki bir dosyayı ilk düzenlediğinde başlıyor; düzenlemenin altında yeni diagnostic sayısını söyleyen bir satır görürsen çalışıyor demek. Görmüyorsan /plugin'in Errors sekmesinde Executable not found in $PATH satırına bak.

Bir plugin'i kurmadan önce kaynağını oku. Belgeler hooks/hooks.json'daki komutlara, .mcp.json'daki server komutlarına ve bin/ klasörüne bakmanı öneriyor. Permission rule'lar ve sandbox Claude'un tool çağrılarını kapsıyor; hook'lar ve MCP server süreçleri ise sandbox dışında, senin yetkinle çalışıyor. Marketplace'te auto-update açıksa incelediğin dosyalar arka planda değişebiliyor.

Output Style'lar

Output style, Claude'un bütün session boyunca rolünü, tonunu ve cevap biçimini belirleyen talimat seti. Default dışında dört hazır stil var: Proactive rutin kararlarda soru sormadan ilerliyor, Concise sonuçla başlayıp anlatımı kısaltıyor, Explanatory değişikliklerin arkasındaki kararı Insight bloklarıyla açıklıyor, Learning ise buna ek olarak tasarım kararı içeren küçük parçaları TODO(human) ile işaretleyip senin yazmanı bekliyor. Learning, ekibe yeni katılan bir junior'ın ilk haftası için iyi bir seçim.

/output-style learning ya da /config ile seçilen stil .claude/settings.local.json'a yazılıyor. Settings'teki outputStyle değeri büyük küçük harfe duyarlı: Learning doğru, learning Default'a düşüyor. Plugin'ler de stil taşıyabiliyor; bookstore-dev'deki stil Learning'in Bookstore'a uyarlanmış hâli:

---
name: mentor
description: For developers new to Bookstore. Names the module and layer of each change and leaves the new tests for you to write.
keep-coding-instructions: true
---

You are pairing with a developer who is new to the Bookstore repository.

- Before you change code, name the module (Catalog, Ordering, Inventory, Payments,
  Shipping, Notifications, Institutional, Identity) and the layer (endpoint,
  EF Core, Contracts, Angular client) the change belongs to, and point to one
  existing file that shows the convention to follow.
- When a rule in CLAUDE.md or .claude/rules decides something, say which rule.
- When the change needs a new test, write the test name and what it must assert,
  mark the spot with a TODO(human) comment and wait for the developer to write it.
  Write the rest of the change yourself.
- After each change, list the commands that verify it, such as `dotnet test` or
  `npm test` in web/bookstore-web.

Stil /output-style listesinde bookstore-dev:mentor olarak çıkıyor. keep-coding-instructions: true Claude Code'un yazılım geliştirme talimatlarını koruyor; custom stillerde varsayılan değer false. Output style bir talimat, zorlama değil: proje bilgisi CLAUDE.md'de, her seferinde olması gereken şey hook'ta kalmalı. Stil ana konuşmaya ve fork'lara uygulanıyor, diğer subagent'lara uygulanmıyor. Status line ile context ve maliyeti sürekli görmek serinin son yazısında.

Managed Settings: Organizasyonun Belirledikleri

Bu bölümde resmî belgelerden yararlanılmıştır. Managed settings, kullanıcı ve proje ayarlarının geçersiz kılamadığı en üst katman. Üç yoldan geliyor: Team ve Enterprise planlarında claude.ai admin konsolundaki Organization settings, Claude Code, Managed settings ekranından (Owner ya da Primary Owner rolü gerekiyor); MDM (mobile device management; şirket cihazlarına merkezden ayar dağıtan Intune, Jamf gibi araçlar) ile, Windows'ta HKLM\SOFTWARE\Policies\ClaudeCode altındaki Settings değeriyle; ya da Windows'ta C:\Program Files\ClaudeCode\managed-settings.json dosyasıyla. Varsayılan olarak makinede tek kaynak uygulanıyor: önce server-managed, sonra MDM, sonra dosya. Bookstore'un şirketi için bir örnek:

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "requiredMinimumVersion": "2.1.325",
  "permissions": {
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/appsettings.Production.json)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/bookstore" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "bookstore": {
      "source": { "source": "github", "repo": "your-org/bookstore" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "bookstore-dev@bookstore": true
  },
  "allowManagedHooksOnly": true
}

forceLoginMethod ve forceLoginOrgUUID girişleri şirketin claude.ai organizasyonuyla sınırlıyor; ilk yazıdaki "kişisel abonelikle şirket repo'su" tuzağını organizasyon böyle kapatıyor. requiredMinimumVersion daha eski bir sürümün açılmasını engelliyor; minimumVersion ise yalnız güncellemenin daha eskiye inmesini önlüyor. disableBypassPermissionsMode bypass modunu ve --dangerously-skip-permissions bayrağını kapatıyor; auto mode'u kapatmak istersen ayrı anahtar disableAutoMode: "disable".

strictKnownMarketplaces plugin'lerin yalnız listedeki kaynaklardan kurulmasına izin veriyor ama hiçbir şeyi kaydetmiyor; kaydı extraKnownMarketplaces yapıyor. Managed'daki bookstore girdisi repo'daki aynı adlı girdinin yerini alıyor, enabledPlugins da plugin'i her makinede kurup zorunlu açıyor. Bu durumda plugin artık repo'dan yerinde değil, varsayılan branch'ten kopyalanarak geliyor; değişiklik merge edilince autoUpdate ile dağılıyor.

allowManagedHooksOnly yedinci yazıda söz verdiğimiz anahtar. Açıkken yalnız managed settings'teki hook'lar, Agent SDK hook'ları ve managed enabledPlugins'in tam plugin@marketplace kimliğiyle zorunlu açtığı plugin'lerin hook'ları çalışıyor; kullanıcı, proje ve local hook'ları engelleniyor. Bunun iki yan etkisi var: /goal hook'lara dayandığı için çalışmıyor, status line da yalnız managed settings'ten okunuyor.

MCP tarafında sekizinci yazıda andığımız üç araç var: managed-mcp.json ile sabit bir server seti dağıtmak, allowedMcpServers ve allowManagedMcpServersOnly ile allowlist'i managed settings'e kilitlemek, strictPluginOnlyCustomization'a "mcp" ekleyip server'ların yalnız plugin'lerden gelmesini sağlamak. Belgeler serverName eşleşmesinin bir güvenlik kontrolü olmadığını, çünkü adı kullanıcının verdiğini özellikle yazıyor.

Politikanın uygulandığını bir makinede /status'taki Setting sources satırıyla kontrol et; dosya için Enterprise managed settings (file) görmelisin. Şemaya uymayan girdileri claude doctor listeliyor. Kullanımı izlemek için Team ve Enterprise'da claude.ai/analytics/claude-code, Console'da platform.claude.com/claude-code dashboard'ları var. Ekip politikasının kendisi AI Destekli Geliştirme serisinin altıncı yazısında.

Üretimde Dikkat

CI davranışı değişiyor. Belgelere göre -p koşularında repo'nun extraKnownMarketplaces kaydı yalnız daha önce trust edilmiş klasörlerde uygulanıyor; CI runner'ı öyle bir klasör değil. Hook'lar .claude/settings.json'dayken @claude job'ında çalışıyordu, plugin'e taşınınca çalışmıyor. Tahmindeki üçüncü sorunun cevabı bu. Guard'ı CI'da istiyorsan claude_args'a --plugin-dir ./plugins/bookstore-dev ekleyebilirsin; o zaman Stop hook'undaki dotnet test da orada çalışır ve SQL Server ister.

Worktree'lerde plugin ana checkout'tan yükleniyor, çünkü göreli yol oraya çözülüyor. Bir worktree'de plugin'i değiştiriyorsan o session'ı --plugin-dir ile aç.

Plugin'i kod gibi review et. plugins/ altındaki bir değişiklik, merge edildiği gün ekipteki herkesin makinesinde onların yetkisiyle çalışan bir hook ya da server demek.

Sık Düşülen Tuzaklar

Orijinalleri silmemek. Hook'lar iki kez çalışıyor, skill ve agent'lar listede çift görünüyor.

Eski tool adlarıyla kalan izin kuralları. Kural sessizce eşleşmeyi bırakıyor; tek belirti yeniden gelen onay soruları.

Bileşenleri .claude-plugin/ içine koymak ya da agent'a mcpServers yazmak. İkisi de hata vermeden yok sayılabiliyor; /plugin'in Errors sekmesine ve claude plugin details çıktısına bak.

Git'ten dağıtılan plugin'de version yazıp artırmayı unutmak. Kullanıcılar yeni commit'leri hiç almıyor.

Doğrulanmamış bir topluluk plugin'ini user scope'a kurmak. Her projede, her session'da senin yetkinle çalışıyor.

Küçük Bir Deneme

★☆☆ /output-style learning ile küçük bir Bookstore değişikliği iste, sonra aynı işi bookstore-dev:mentor ile tekrarla. Claude'un hangi parçaları sana bıraktığını karşılaştır.

★★☆ .claude/hooks/ kopyalarını silmeden plugin'i yükle, commit'lenmiş bir migration'ı düzenletmeyi dene ve ret mesajını say. Sonra kopyaları silip /reload-plugins çalıştır.

★★★ Bir test makinesinde C:\Program Files\ClaudeCode\managed-settings.json'a yalnız {"allowManagedHooksOnly": true} koy. /status'taki Setting sources satırını oku, sonra commit'lenmiş bir migration'ı düzenletmeyi dene: bookstore-dev'i proje ayarı açtığı için migration guard artık çalışmamalı. Dosyayı silip aynı denemeyi tekrarla.

Plugin, Claude Code'u ekip içinde paylaşılan bir araç hâline getirdi. On ikinci yazıda aynı harness'i kendi kodumuzdan çağıracağız: Claude Agent SDK ile Bookstore için gece çalışan bir bağımlılık raporu agent'ı yazacağız.