İçeriğe geç

CLAUDE.md Nedir ve Yazılım Takımınız İçin Nasıl Yapılandırılır?

Anasayfa

CLAUDE.md Nedir ve Yazılım Takımınız İçin Nasıl Yapılandırılır?

CLAUDE.md, Claude Code’a proje hakkında kalıcı bağlam ve çalışma talimatları vermek için kullanılan Markdown dosyasıdır. Claude Code ile bir yazılım projesi üzerinde çalışırken yapay zekaya her yeni oturumda projenizin mimarisini, kullandığınız teknolojileri, kodlama standartlarını veya hangi komutları çalıştırması gerektiğini tekrar tekrar açıklamak zorunda değilsiniz.

Doğru yapılandırılmış bir CLAUDE.md dosyası; Claude Code’un kod tabanını daha hızlı anlamasına, ekip standartlarına uygun kod üretmesine, doğru test ve build komutlarını kullanmasına ve proje boyunca daha tutarlı davranmasına yardımcı olur.

Bu rehberde CLAUDE.md nedir, ne işe yarar, nasıl oluşturulur, nereye yerleştirilir ve yazılım ekipleri için nasıl yapılandırılır sorularını örneklerle ele alacağız. Ayrıca doğrudan kendi projenize uyarlayabileceğiniz bir CLAUDE.md şablonu da bulacaksınız.

CLAUDE.md Nedir?

CLAUDE.md, Claude Code’un bir proje üzerinde çalışırken dikkate almasını istediğiniz proje bilgilerini ve talimatları Markdown formatında tanımladığınız dosyadır.

Dosyanın içerisinde örneğin şu bilgiler bulunabilir:

  • Projenin amacı ve mimarisi
  • Kullanılan programlama dilleri ve framework’ler
  • Repository yapısı
  • Kodlama standartları
  • Naming convention’lar
  • Build ve development komutları
  • Test komutları
  • Git workflow kuralları
  • Güvenlik gereksinimleri
  • Claude’un değiştirmemesi gereken dosyalar
  • Ekip tarafından kullanılan özel geliştirme kuralları

Böylece Claude Code’a her görevde aynı bağlamı yeniden vermek yerine proje seviyesinde ortak bir çalışma çerçevesi oluşturabilirsiniz.

Örneğin bir projede React, TypeScript ve Node.js kullanılıyorsa ve ekip fonksiyonel component standardını benimsemişse bu bilgi CLAUDE.md içerisinde tanımlanabilir.

Claude Code daha sonra kod üretirken veya mevcut kodu değiştirirken bu talimatları bağlam olarak kullanabilir.

CLAUDE.md Ne İşe Yarar?

CLAUDE.md’nin temel amacı Claude Code’a projenize özgü bağlam sağlamaktır.

Bir geliştirici projeye ilk kez dahil olduğunda README dosyasını, mimari dokümantasyonu ve ekip standartlarını incelemek zorundadır. Claude Code için de benzer bir bağlama ihtiyaç vardır.

CLAUDE.md bu bağlamın merkezi kaynaklarından biri haline gelir.

Örneğin Claude’a yalnızca:

Yeni bir kullanıcı endpoint'i oluştur.

şeklinde bir görev verdiğinizi düşünelim.

Proje hakkında yeterli bağlam yoksa Claude’un bilmesi gereken birçok şey vardır:

  • Hangi framework kullanılıyor?
  • Endpoint’ler hangi klasörde tutuluyor?
  • Controller yapısı nasıl?
  • Validation hangi kütüphane ile yapılıyor?
  • Test yazılması gerekiyor mu?
  • API response standardı nedir?
  • Hangi dosyalara dokunulmamalı?

Bu bilgilerin CLAUDE.md içerisinde tanımlanması, Claude Code’un görevi projenizin mevcut standartlarına daha uygun biçimde gerçekleştirmesine yardımcı olur.

CLAUDE.md Kullanmanın Avantajları

Daha Tutarlı Kod Üretimi

Kodlama standartlarının açıkça tanımlanması Claude’un farklı görevlerde benzer kuralları takip etmesini kolaylaştırır.

Örneğin ekip içerisinde:

  • TypeScript strict mode kullanılması,
  • any kullanımından kaçınılması,
  • component isimlerinin PascalCase olması,
  • testlerin ilgili modülün yanında tutulması

gibi kurallar varsa bunlar CLAUDE.md içerisine eklenebilir.

Daha Az Tekrarlanan Prompt

Her yeni görevde proje mimarisini tekrar açıklamak yerine ortak bilgiler CLAUDE.md içerisinde tutulabilir.

Bu da promptların daha kısa ve göreve odaklı olmasını sağlar.

Takım Standartlarının Korunması

CLAUDE.md yalnızca bireysel geliştiriciler için değil, yazılım ekipleri için de önemlidir.

Repository içerisinde ortak bir CLAUDE.md tutulduğunda ekip üyelerinin Claude Code kullanırken aynı temel talimatlardan hareket etmesi sağlanabilir.

AI Destekli Geliştirmede Daha Kontrollü Süreç

Claude’un hangi komutları kullanması, hangi klasörlere müdahale etmemesi veya hangi işlemleri gerçekleştirmeden önce geliştiriciden onay alması gerektiği gibi kurallar da tanımlanabilir.

Bu yaklaşım özellikle kurumsal yazılım projelerinde önem kazanır.

CLAUDE.md Dosyası Nereye Konur?

CLAUDE.md farklı kapsam seviyelerinde kullanılabilir. Hangi seviyenin tercih edileceği, verilen talimatın kapsamına bağlıdır.

KonumKullanım amacı
Kullanıcı seviyesiFarklı projelerde kullanılacak kişisel çalışma tercihleri
Proje kök diziniTüm repository için geçerli proje kuralları
Alt dizinBelirli modül veya klasöre özgü talimatlar

Çoğu ekip için temel CLAUDE.md dosyasının repository’nin kök dizininde bulunması mantıklıdır.

Kullanıcıya özel ve tüm projelerde geçerli talimatlar ~/.claude/CLAUDE.md dosyasında tutulabilir. Projeye özel kişisel notlar için CLAUDE.local.md, konu veya dosya yoluna göre ayrıştırılmış kurallar için ise .claude/rules/ dizini kullanılabilir.

Örnek proje yapısı:

my-project/
├── CLAUDE.md
├── README.md
├── package.json
├── src/
├── tests/
└── docs/

Ancak büyük monorepo veya çok katmanlı projelerde farklı bölümler için daha spesifik talimatlar tanımlamak gerekebilir.

Örneğin:

project/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
├── backend/
│   └── CLAUDE.md
└── infrastructure/
    └── CLAUDE.md

Bu yapı sayesinde genel proje kuralları ile frontend, backend veya altyapıya özgü kurallar birbirinden ayrılabilir.

Claude Code, başlangıçta çalışma dizininin üst hiyerarşisindeki ilgili talimat dosyalarını yükler. Alt dizinlerdeki CLAUDE.md dosyaları ise Claude o dizinlerdeki dosyalarla çalıştığında bağlama alınır. Bu nedenle alt dizin talimatlarının görevle gerçekten ilgili ve üst düzey kurallarla uyumlu olması gerekir.

CLAUDE.md Nasıl Oluşturulur?

CLAUDE.md normal bir Markdown dosyasıdır. Bu nedenle oluşturmak için özel bir dosya formatına ihtiyacınız yoktur.

Projenizin kök dizininde:

CLAUDE.md

adında bir dosya oluşturabilirsiniz.

Ardından Claude’un projeyi anlaması için gerçekten gerekli olan bilgileri bölümler halinde ekleyebilirsiniz.

İyi bir CLAUDE.md’nin amacı mümkün olduğunca uzun olmak değil, Claude’a karar verirken ihtiyaç duyduğu doğru bağlamı sağlamaktır.

Başlangıç için aşağıdaki yapı kullanılabilir.

Hazır CLAUDE.md Şablonu

Aşağıdaki CLAUDE.md şablonunu kendi projenize göre düzenleyebilirsiniz:

# Project Overview

Bu repository [proje açıklaması] için kullanılmaktadır.

## Tech Stack

- Language:
- Framework:
- Database:
- Testing:
- Package Manager:

## Project Structure

- `/src` - Application source code
- `/tests` - Automated tests
- `/docs` - Project documentation
- `/config` - Configuration files

## Coding Standards

- Mevcut proje mimarisini takip et.
- Gereksiz dependency ekleme.
- Küçük ve yeniden kullanılabilir fonksiyonlar oluştur.
- Mevcut naming convention'ları koru.
- Yeni kod yazmadan önce ilgili mevcut implementasyonu incele.

## Commands

Development:
`npm run dev`

Build:
`npm run build`

Test:
`npm test`

Lint:
`npm run lint`

## Testing Rules

- Yeni özellikler için test yaz.
- Mevcut testleri gereksiz yere değiştirme.
- Değişiklik tamamlandıktan sonra ilgili testleri çalıştır.
- Başarısız testleri görmezden gelme.

## Security Rules

- Secret veya API key commit etme.
- Kullanıcı girdilerini doğrula.
- Hassas verileri loglama.
- Authentication ve authorization kontrollerini atlama.

## Git Rules

- İlgisiz dosyalarda değişiklik yapma.
- Büyük değişiklikleri küçük ve anlaşılır parçalara ayır.
- Mevcut branch stratejisini takip et.

## Do Not

- Gereksiz dependency ekleme.
- Environment dosyalarını değiştirme.
- Mevcut public API'leri gerekçe olmadan değiştirme.
- Testleri yalnızca başarılı görünmeleri için silme veya devre dışı bırakma.

## Before Completing a Task

1. Değişiklikleri gözden geçir.
2. İlgili testleri çalıştır.
3. Lint kontrolünü gerçekleştir.
4. Gereksiz dosya değişikliklerini kontrol et.
5. Yapılan değişiklikleri kısaca açıkla.

Bu yapı her proje için birebir kullanılmak zorunda değildir. Asıl amaç Claude’un karar vermesi gereken noktalarda belirsizliği azaltmaktır.

Gerçek Bir CLAUDE.md Örneği

Örneğin TypeScript tabanlı bir SaaS uygulamasında daha spesifik bir CLAUDE.md şöyle yapılandırılabilir:

# Project Overview

This repository contains our B2B SaaS application.

## Stack

- TypeScript
- React
- Node.js
- PostgreSQL
- Jest
- ESLint

## Coding Standards

- Use TypeScript for all new files.
- Do not use `any` unless absolutely necessary.
- Use functional React components.
- Follow existing naming conventions.
- Prefer existing utilities over creating duplicate helpers.

## Backend

- Keep controllers thin.
- Business logic belongs in service modules.
- Validate external input before processing.
- Database access must use the existing repository layer.

## Testing

Run tests before completing a task.

Do not remove failing tests to make the build pass.

New business logic should include relevant tests.

## Security

Never commit credentials.

Never expose internal error details in API responses.

Validate and sanitize external input.

## Before Making Changes

Inspect similar implementations already available in the repository.

Do not introduce a new architectural pattern unless necessary.

Burada dikkat edilmesi gereken nokta, talimatların genel ifadeler yerine uygulanabilir ve kontrol edilebilir kurallar şeklinde yazılmasıdır.

“İyi kod yaz” gibi bir talimat yerine:

Do not use any unless absolutely necessary.

gibi açık bir kural çok daha kullanışlıdır.

CLAUDE.md İçerisinde Hangi Bilgiler Olmalı?

Her repository farklıdır ancak kurumsal projelerde bazı bilgi türleri özellikle değerlidir.

1. Proje Tanımı

Claude önce projenin ne yaptığını anlamalıdır.

Örneğin:

## Project Overview

This application is a B2B payment platform used by enterprise customers.

Tek bir cümle bile Claude’un sonraki görevleri yorumlamasında önemli bağlam sağlayabilir.

2. Teknoloji Yığını

Projede kullanılan temel teknolojileri belirtin.

## Tech Stack

- Next.js
- TypeScript
- PostgreSQL
- Redis
- Jest

3. Repository Yapısı

Özellikle büyük projelerde önemli klasörlerin görevini açıklayın.

## Repository Structure

/apps/web       Frontend application
/apps/api       Backend API
/packages/ui    Shared UI components
/packages/core  Shared business logic

4. Build, Test ve Development Komutları

Claude’un doğru komutları tahmin etmeye çalışması yerine bunları açıkça tanımlayın.

## Commands

npm run dev
npm run build
npm test
npm run lint

5. Kodlama Standartları

Ekibin gerçekten uyguladığı kuralları belirtin.

Örneğin:

- Use TypeScript strict mode.
- Prefer named exports.
- Do not introduce new dependencies without approval.
- Follow existing patterns before creating new abstractions.

6. Test Politikası

Bir değişikliğin ne zaman tamamlanmış kabul edildiğini tanımlayın.

Örneğin:

Before completing a task:

1. Run relevant unit tests.
2. Run lint.
3. Check TypeScript errors.
4. Report any failing tests.

7. Güvenlik Kuralları

Özellikle kurumsal projelerde güvenlik talimatları ayrı bir bölüm olarak ele alınmalıdır.

Claude’a yalnızca ne yapması gerektiğini değil, ne yapmaması gerektiğini de söylemek önemlidir.

CLAUDE.md ile README.md Arasındaki Fark Nedir?

CLAUDE.md ve README.md aynı amaçla kullanılmaz.

README.md, öncelikle projeyi kullanan veya projeye katkıda bulunan insanlar için hazırlanır. Kurulum, proje açıklaması, kullanım örnekleri ve contribution bilgileri içerebilir.

CLAUDE.md ise Claude Code’un proje üzerinde çalışırken ihtiyaç duyduğu talimatları ve bağlamı içerir.

Basitçe ifade edersek:

README.mdCLAUDE.md
İnsanlara yöneliktirClaude Code’a bağlam sağlar
Projeyi açıklarClaude’un projede nasıl çalışacağını tanımlar
Kurulum ve kullanım içerebilirKodlama ve çalışma kuralları içerebilir
Genel dokümantasyondurAI geliştirme bağlamıdır

Bu iki dosya birbirinin alternatifi değildir.

İyi yapılandırılmış bir projede README geliştiricilerin projeyi anlamasını sağlarken CLAUDE.md Claude Code’un proje standartlarını anlamasına yardımcı olabilir.

CLAUDE.md ile .claude/settings.json Arasındaki Fark Nedir?

Bu iki yapı da Claude Code çalışma ortamıyla ilişkili olsa da farklı amaçlara hizmet eder.

CLAUDE.md, Claude’a doğal dil ile bağlam ve çalışma talimatları vermek için kullanılır.

Örneğin:

Always run unit tests after changing business logic.

gibi bir proje kuralı CLAUDE.md içerisinde tanımlanabilir.

.claude/settings.json ise Claude Code’un yapılandırma ve izin davranışlarını yönetmek için kullanılan farklı bir mekanizmadır.

Önemli bir ayrım vardır: CLAUDE.md içindeki maddeler Claude’a bağlam ve yönlendirme sağlar; teknik olarak zorunlu bir güvenlik politikası uygulamaz. Bir işlemin her koşulda engellenmesi veya belirli bir aşamada otomatik kontrol çalıştırılması gerekiyorsa izin ayarları ve hook mekanizmaları kullanılmalıdır.

Dolayısıyla genel yaklaşım şu şekilde düşünülebilir:

CLAUDE.md = Claude neyi bilmeli ve nasıl çalışmalı?

settings = Claude Code ortamı nasıl yapılandırılmalı?

Kurumsal projelerde bu iki yapı birbirini tamamlayabilir.

Yazılım Takımları CLAUDE.md’yi Nasıl Kullanmalı?

Bireysel projelerde CLAUDE.md hazırlamak nispeten kolaydır. Ancak dosyanın asıl değeri ekip kullanımında ortaya çıkabilir.

Repository içerisindeki CLAUDE.md dosyasının ekip tarafından ortak bir doküman olarak yönetilmesi gerekir.

Örneğin ekip yeni bir mimari karar aldığında CLAUDE.md de güncellenebilir.

Böylece:

Developer → repository → CLAUDE.md → Claude Code

arasında ortak bir çalışma standardı oluşur.

Ancak burada önemli bir nokta vardır:

CLAUDE.md geliştirici dokümantasyonunun tamamını kopyaladığınız devasa bir dosyaya dönüşmemelidir.

Dosyada Claude’un görevleri yerine getirirken sık ihtiyaç duyacağı bilgiler bulunmalıdır.

CLAUDE.md Best Practices: En İyi Uygulamalar

Kısa ve Spesifik Talimatlar Yazın

Uzun açıklamalar yerine doğrudan uygulanabilir kurallar tercih edin.

Kötü örnek:

Try to write good and maintainable code.

Daha iyi:

Prefer functions under 50 lines.
Reuse existing utilities before creating new ones.

Projede Zaten Geçerli Olan Kuralları Yazın

CLAUDE.md hayali bir mimari tarif etmek için kullanılmamalıdır.

Claude’a:

Use repository pattern.

diyorsanız projenin gerçekten repository pattern kullanması gerekir.

Aksi halde mevcut kod ile CLAUDE.md arasında çelişki oluşabilir.

“Do Not” Bölümü Ekleyin

Yapay zeka destekli geliştirmede yalnızca yapılması gerekenler değil, kaçınılması gereken davranışlar da önemlidir.

Örneğin:

## Do Not

- Do not modify migration history.
- Do not change public APIs without approval.
- Do not add dependencies unless necessary.
- Do not commit secrets.

Mevcut Kodu Referans Almasını Söyleyin

Claude’un yeni pattern üretmesi yerine repository’deki mevcut implementasyonları incelemesini isteyebilirsiniz.

Örneğin:

Before implementing a new feature, inspect similar implementations in the repository and follow existing patterns.

Bu basit talimat özellikle büyük ve uzun süredir geliştirilen projelerde faydalıdır.

CLAUDE.md’yi Güncel Tutun

Projenin framework’ü, build komutları veya mimarisi değişirken CLAUDE.md eski kalırsa dosya yanlış bağlam üretmeye başlayabilir.

Bu nedenle CLAUDE.md de kod tabanının bir parçası olarak değerlendirilmelidir.

Büyük Projelerde Birden Fazla CLAUDE.md Kullanımı

Monorepo ve büyük kurumsal uygulamalarda tek bir CLAUDE.md dosyasına yüzlerce kural eklemek yerine bağlamı bölmek daha kullanışlı olabilir.

Örneğin:

company-platform/
├── CLAUDE.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── api/
│       └── CLAUDE.md
└── packages/

Ana dosyada şirket veya repository genelindeki kurallar bulunurken alt dizinlerde teknoloji veya modüle özgü bilgiler tanımlanabilir.

Örneğin frontend tarafında React component standartları önemliyken backend tarafında API, database ve authentication kuralları daha önemli olabilir.

Bu yaklaşım Claude’a görevle daha ilgili bağlam sağlamayı kolaylaştırır.

CLAUDE.md ve Subagent Kullanımı

Claude Code’un daha gelişmiş kullanım senaryolarında farklı görevler için özelleştirilmiş agent yaklaşımları kullanılabilir.

Örneğin bir yazılım geliştirme sürecinde farklı görevler şu şekilde ayrılabilir:

Main Agent
   |
   |-- Code Review Agent
   |
   |-- Testing Agent
   |
   |-- Security Agent
   |
   |-- Documentation Agent

Bu noktada CLAUDE.md proje seviyesindeki ortak bağlamı sağlarken farklı agent’lar kendi görevlerine özgü talimatlarla çalışabilir.

Örneğin bir security review agent’ın odak noktaları:

  • Authentication kontrolleri
  • Authorization problemleri
  • Input validation
  • Secret yönetimi
  • Dependency riskleri

olabilir.

Testing agent ise:

  • Unit test coverage
  • Edge case’ler
  • Integration testleri
  • Regression riskleri

üzerine yoğunlaşabilir.

Bu tür yapılar özellikle AI destekli yazılım geliştirmeyi ekip seviyesinde standartlaştırmak isteyen organizasyonlar için önemlidir.

Yapay zekanın yazılım geliştirme ve test süreçlerinde kullanımını daha geniş kapsamda ele almak isteyen ekipler BlueMark Academy’nin Yapay Zeka ile Test Otomasyonu Eğitimi programını da inceleyebilir.

CLAUDE.md Kullanırken Yapılan Yaygın Hatalar

Dosyayı Gereğinden Fazla Uzatmak

Her dokümantasyonu CLAUDE.md içerisine kopyalamak daha iyi sonuç anlamına gelmez.

Claude’un görev sırasında ihtiyaç duyacağı bilgileri önceliklendirin.

Belirsiz Talimatlar Kullanmak

“Clean code yaz” gibi ifadeler yorumlamaya açıktır.

Bunun yerine ölçülebilir ve uygulanabilir kurallar tanımlayın.

Birbiriyle Çelişen Kurallar Yazmak

Örneğin dosyanın bir bölümünde:

Always use functional components.

başka bir bölümünde:

Use class components for complex components.

yazılması Claude’un hangi standardı takip edeceğini belirsiz hale getirir.

Eski Komutları Dosyada Bırakmak

Build veya test altyapısı değiştiğinde CLAUDE.md de güncellenmelidir.

CLAUDE.md’yi Her Problemin Çözümü Olarak Görmek

CLAUDE.md güçlü bir bağlam aracıdır ancak iyi yazılım mimarisinin, dokümantasyonun, testlerin ve kod inceleme süreçlerinin yerini almaz.

En iyi sonuç bu araçların birlikte kullanılmasıyla elde edilir.

Kurumsal Projelerde CLAUDE.md Nasıl Yönetilmeli?

Kurumsal kullanımda CLAUDE.md bireysel bir prompt dosyası değil, yazılım geliştirme standartlarının AI sistemlerine aktarılmasını sağlayan katmanlardan biri olarak ele alınabilir.

Bu nedenle ekiplerin şu sorulara cevap vermesi gerekir:

  • CLAUDE.md’yi kim güncelleyecek?
  • Hangi kurallar repository seviyesinde olacak?
  • Hangi bilgiler alt modüllere taşınacak?
  • Güvenlik kuralları nasıl tanımlanacak?
  • Yeni dependency ekleme yetkisi nasıl yönetilecek?
  • Test zorunlulukları nasıl belirtilecek?
  • Claude’un değiştirmemesi gereken alanlar hangileri?
  • İnsan onayı gerektiren işlemler hangileri?

AI destekli geliştirme olgunlaştıkça konu yalnızca “Claude’a iyi prompt yazmak” olmaktan çıkar ve AI araçlarını mevcut yazılım geliştirme yaşam döngüsüne kontrollü biçimde entegre etmek haline gelir.

Bu nedenle kurumların Claude Code gibi araçları kullanırken prompt mühendisliği, yazılım geliştirme standartları, test otomasyonu, güvenlik ve yönetişim konularını birlikte değerlendirmesi gerekir.

Özellikle cloud tabanlı uygulamalarda CLAUDE.md içerisindeki talimatların yalnızca kod standartlarını değil, projenin çalıştığı altyapıyı da dikkate alması önemlidir. Örneğin Google Cloud üzerinde çalışan projelerde kullanılan servisler, deployment yaklaşımı, erişim politikaları ve uygulamanın cloud mimarisi Claude’a verilecek proje bağlamının bir parçası olabilir. Google Cloud altyapısı, temel servisleri ve mimari yaklaşımı konusunda ekip yetkinliğini geliştirmek isteyen kurumlar Google Cloud Platform Fundamentals Eğitimi programını inceleyebilir.

BlueMark Academy’nin Yapay Zeka Eğitimleri sayfasında kurum ve ekiplerin farklı kullanım senaryolarına yönelik yapay zeka eğitim programlarını inceleyebilirsiniz.

CLAUDE.md Hakkında Sık Sorulan Sorular

CLAUDE.md nedir?

CLAUDE.md, Claude Code’a bir yazılım projesi hakkında bağlam ve çalışma talimatları vermek için kullanılan Markdown dosyasıdır. Proje mimarisi, teknoloji yığını, kodlama standartları, test komutları ve ekip kuralları gibi bilgiler içerebilir.

CLAUDE.md ne işe yarar?

Claude Code’un üzerinde çalıştığı repository’yi ve ekip standartlarını daha iyi anlamasına yardımcı olur. Böylece her görevde aynı proje bilgilerinin tekrar prompt içerisinde verilmesi ihtiyacını azaltabilir.

CLAUDE.md dosyası nereye konur?

Proje genelindeki talimatlar için CLAUDE.md dosyası repository’nin kök dizininde kullanılabilir. Daha büyük projelerde belirli klasör veya modüller için daha spesifik talimatlar da yapılandırılabilir.

CLAUDE.md nasıl oluşturulur?

Projenizde CLAUDE.md adında standart bir Markdown dosyası oluşturup içerisine proje açıklaması, teknoloji yığını, önemli komutlar, kodlama standartları, test kuralları ve Claude’un uyması gereken proje talimatlarını ekleyebilirsiniz.

CLAUDE.md içerisinde neler olmalı?

Her proje farklı olsa da proje amacı, teknoloji yığını, repository yapısı, build ve test komutları, kodlama standartları, güvenlik kuralları ve yapılmaması gereken işlemler iyi bir başlangıç oluşturur.

CLAUDE.md ile README.md aynı şey mi?

Hayır. README.md esas olarak insanlar için proje dokümantasyonu sağlar. CLAUDE.md ise Claude Code’un proje üzerinde çalışırken kullanacağı bağlam ve talimatları tanımlar.

Her proje için CLAUDE.md gerekli mi?

Hayır. Küçük ve basit projelerde kapsamlı bir CLAUDE.md gerekmeyebilir. Ancak ekip standartlarının, özel mimari kuralların veya karmaşık repository yapısının bulunduğu projelerde daha değerli hale gelir.

CLAUDE.md ne kadar uzun olmalı?

Belirli bir ideal kelime sayısı yoktur. Amaç mümkün olan en uzun dosyayı oluşturmak değil, Claude’un doğru karar vermesi için gerekli bilgileri açık ve öz biçimde sağlamaktır.

CLAUDE.md’ye kod örnekleri eklenebilir mi?

Evet. Özellikle projeye özgü pattern’lerin anlaşılması için kısa kod örnekleri kullanılabilir. Ancak uzun kaynak kodlarını dosyaya taşımak yerine Claude’u repository içerisindeki mevcut implementasyonlara yönlendirmek çoğu durumda daha sürdürülebilir olur.

CLAUDE.md ekip tarafından paylaşılabilir mi?

Evet. Proje seviyesindeki CLAUDE.md repository içerisinde tutulduğunda ekip için ortak Claude Code çalışma standartlarının oluşturulmasına yardımcı olabilir.

Sonuç: İyi Bir CLAUDE.md Nasıl Olmalı?

İyi hazırlanmış bir CLAUDE.md dosyası Claude Code’a mümkün olduğunca fazla bilgi veren dosya değildir. Doğru zamanda ihtiyaç duyacağı doğru bağlamı veren dosyadır.

İyi bir yapı için öncelikle:

  • Projenin ne yaptığını açıklayın.
  • Kullanılan teknoloji yığınını belirtin.
  • Repository yapısını tanımlayın.
  • Doğru build ve test komutlarını ekleyin.
  • Kodlama standartlarını açık kurallarla ifade edin.
  • Güvenlik gereksinimlerini belirtin.
  • Yapılmaması gereken işlemleri tanımlayın.
  • Claude’u mevcut kod ve pattern’leri incelemeye yönlendirin.
  • Proje geliştikçe CLAUDE.md’yi de güncelleyin.

Claude Code ve benzeri agentic coding araçları yaygınlaştıkça yazılım ekipleri açısından önemli soru yalnızca “Yapay zekaya nasıl kod yazdırabiliriz?” olmayacaktır. Asıl konu, yapay zekayı mevcut geliştirme standartları, test süreçleri, güvenlik politikaları ve ekip çalışma biçimleriyle nasıl uyumlu hale getireceğimizdir.

CLAUDE.md bu yapının küçük ancak önemli parçalarından biridir.

Kurumunuzda üretken yapay zeka araçlarının daha sistematik kullanımını planlıyorsanız BlueMark Academy’nin kurumsal Yapay Zeka Eğitimleri programlarını inceleyebilir; yazılım kalite süreçlerine odaklanıyorsanız Yapay Zeka ile Test Otomasyonu Eğitimi içeriğine göz atabilirsiniz.