AGENTS.md ve HUMAN.md nedir, nasıl yazılır?

AGENTS.md nedir

AGENTS.md, bir depoyu kök dizininde bulunan ve bir kodlama aracısına proje üzerinde nasıl çalışacağını bildiren düz metin biçimli bir Markdown dosyasıdır. Resmi site bu dosyayı "aracılar için README: yapay zeka kodlama aracılarının projeniz üzerinde çalışmasına yardımcı olacak bağlamı ve talimatları sağlamak için ayrılmış, öngörülebilir bir konum" olarak tanımlar. Biçimin sorumluluğu, Linux Foundation bünyesindeki Agentic AI Foundation tarafından yürütülür. Temmuz 2026 itibarıyla Codex, Cursor, Jules, Devin ve GitHub Copilot dahil yirmiden fazla aracı tarafından okunur.

Bu kuralın varlık nedeni pratiktir. Ekibe yeni katılan kişi README dosyasını okur, derleme komutunu tahmin eder ve tahmin yanlışsa birine sorar. Bir aracı soru soramaz. Tahminde bulunur, npm test kullanan bir projede pnpm test komutunu çalıştırır, hatayı okur ve başka bir şey dener. Bu işlemlerin her biri için ödeme yapılır. Gerçek komutun bir kez yazılması, bu hata sınıfının tamamını ortadan kaldırır.

Zorunlu alan yoktur. Site bunu açıkça belirtir: "AGENTS.md yalnızca standart Markdown'dur. İstediğiniz başlıkları kullanabilirsiniz; aracı yalnızca sağladığınız metni ayrıştırır." Tek teknik özellik budur. Değer biçimden kaynaklanmaz. Değer, her aracın zaten denetlediği bir yolda bulunan dosyadan kaynaklanır.

Dosyanın nereye yerleştirileceği ve hangi dosyanın geçerli olacağı

İlk dosya depo kök dizinine yerleştirilmelidir. Monorepo içinde her alt projeye ek dosyalar yerleştirilebilir. Kural basittir: "agents, dizin ağacındaki en yakın dosyayı otomatik olarak okur; bu nedenle en yakın dosya önceliklidir." İki dosya çakıştığında, düzenlenen dosyaya daha yakın olan dosya geçerli olur. Sohbete yazılanlar ise her iki dosyanın üzerindedir.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

İç içe yerleştirme kullanılmalıdır. Çünkü bir klasörde geçerli, sonraki klasörde geçersiz olan bir kuralı ifade etmenin tek yolu budur. "Her endpoint girdisini doğrular" kuralı endpoint'lerin yanına yerleştirilmelidir. Kök dosyaya konulursa, ilgisiz her görevde yüklenir ve hiçbir fayda sağlamaz.

AGENTS.md dosyasına neler yazılmalı

Bir aracının kodu okuyarak çıkaramayacağı bilgileri yazın. Kesin derleme, test ve lint komutları, terminale yapıştıracağınız biçimde ilk sırada yer almalıdır. Tek bir testi çalıştırma komutunu da ekleyin. Yalnızca tüm test paketini çalıştırmayı bilen bir araç, tüm paketi kırk kez çalıştırabilir. Araç varsayılanından farklı olan kuralları belirtin. Araç varsayılanı zaten bilinir; yalnızca sizin farklı uygulamanızı açıklamanız gerekir. Kullanıyorsanız commit mesajı biçimini ve pull request kurallarını ekleyin.

Bir iddianın kontrol edilebilmesini sağlayacak kadar somut olun. "2 boşluk girintisi kullanın" uygulanabilir bir talimattır; çünkü uygulanıp uygulanmadığı kontrol edilebilir. "Kodu düzgün biçimlendirin" uygulanabilir değildir; çünkü içeriğinde doğrulanabilecek hiçbir şey yoktur. Konumlar için de aynı kural geçerlidir: "API işleyicileri src/api/handlers/ içinde bulunur" ifadesi, "Dosyaları düzenli tutun" ifadesinden daha kullanışlıdır.

Olumsuz kurallar da yer kaplamaya değerdir. "dist/ altındaki dosyaları hiçbir zaman düzenlemeyin; bunlar npm run build tarafından oluşturulur" ifadesi belirli bir hatayı önler. Ayrıca nedeni belirttiği için araç, yazmadığınız eşdeğer durumu da çıkarabilir.

Bunlardan hangisine hiçbir zaman yer verilmemelidir

Bu dosyalara hiçbir zaman gizli bilgi eklenmemelidir. Dosya git'e işlenir, her oturumun başında bağlama yüklenir ve her istekte bir model sağlayıcısına gönderilir. AGENTS.md içindeki bir API key, depo geçmişinizde ve üçüncü tarafın günlüklerinde yer alan bir API key anlamına gelir. Gizli bilgiyi yapıştırmak yerine ona işaret edilmelidir: "veritabanı parolası .env içinde bulunuyor; bu dosya gitignore ile dışlanıyor; okumadan önce sorulmalıdır." Daha geniş kapsamlı uygulamalar kimlik bilgilerini bir aracının erişim alanı dışında tutma bölümünde ele alınmaktadır.

Aracının bakarak çıkarabileceği bilgileri eklemeyin. Yapıştırılmış bir dizin listesi, bağımlılık listenizin kopyası veya klasör adlarını tekrarlayan bir mimari özeti: bunların tümü yazıldıktan sonraki hafta güncelliğini yitirir ve bu arada her oturumda bağlam tüketir. Sorunlu noktaları ve nedenlerini koruyun. Envanteri kaldırın.

CLAUDE.md aynı fikrin Claude Code örneğidir

Claude Code CLAUDE.md dosyasını okur ve AGENTS.md dosyasını kendiliğinden okumaz. Proje dosyası ./CLAUDE.md veya ./.claude/CLAUDE.md konumunda bulunur. Tüm projeler için kişisel tercihler ~/.claude/CLAUDE.md konumuna yazılır. Linux üzerinde bir kuruluş, makine genelinde kullanılacak dosyayı /etc/claude-code/CLAUDE.md konumuna dağıtabilir. Bulunan dosyalar, dosya sistemi kökünden çalışma dizininize kadar birleştirilir. Bu nedenle oturumu başlattığınız konuma en yakın dosya en son okunur.

Deponuzda zaten bir AGENTS.md varsa ikinci bir kopya tutmayın. Dosyayı içe aktarın ve yalnızca Claude'a özgü içerikleri ekleyin:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Ek içerik eklemeniz gerekmiyorsa sembolik bağlantı kullanabilirsiniz:

ln -s AGENTS.md CLAUDE.md

Başarılı olduğunda komut hiçbir çıktı vermez. Sonraki oturumunuzda /context komutunu çalıştırın ve CLAUDE.md ifadesinin Memory files altında göründüğünü doğrulayın. Bu listede yoksa dosya hiç yüklenmemiştir; dolayısıyla içindeki hiçbir kural uygulanmamıştır. Dosya yazmak yerine ilk taslağı oluşturmak için /init komutunu çalıştırın. Bu komut kod tabanını okur ve başlangıç dosyası oluşturur. CLAUDE.md zaten varsa dosyanın üzerine yazmak yerine iyileştirmeler önerir.

Her dosyayı yaklaşık 200 satırın altında tutun. Daha uzun dosyalar bağlam penceresinin daha büyük bölümünü tüketir ve kurallara uyum azalır. Bu alan için başka nelerin rekabet ettiğini görmek isterseniz bir aracının bağlam penceresini gerçekte neyin doldurduğu konuyu ayrıntılı olarak açıklar.

Bir noktayı özellikle vurgulamak gerekir. AGENTS.md bir yönlendirmedir, izin sistemi değildir. İçerik olağan bağlam olarak modele iletilir. Model dosyayı okur ve genellikle kurallara uyar, ancak kurallarla çelişen bir eylemi hiçbir şey engellemez. "never push to main" gibi her seferinde uygulanması gereken bir kural için hook veya izin ayarı kullanın. Bunlar kod olarak çalışır ve modelin kurala uymaya karar vermesine bağlı değildir.

Bu dosyaları sizin için oluşturan araçlar

30 July 2026 tarihinde GitHub trend listesindeki iki proje, yaklaşımın hangi yöne ilerlediğini gösteriyor.

agent0ai/dox (July 2026 itibarıyla 1,368 yıldız), AGENTS.md dosyalarından oluşan bir ağaç yapısını güncel tutmaya yönelik bir çerçevedir. Herhangi bir paket veya çalışma zamanı içermez. AGENTS.md dosyasının içeriği kendi kök AGENTS.md dosyanıza kopyalanır; kurulum bundan ibarettir. Mevcut bir proje için aracıya şu talimat verilir:

Initialize DOX tree for this project now.

Ardından aracı, alt AGENTS.md dosyalarını ve bunların dizinlerini oluşturur, herhangi bir şeyi düzenlemeden önce bu ağaç yapısını tarar ve bir değişiklik uygulandıktan sonra etkilenen belgeleri günceller. Bunun temel varsayımı şudur: Bir aracının çalışmasının yan etkisi olarak güncellediği belgeler doğru kalır; bir kişinin elle güncellediği belgeler ise doğru kalmaz.

HUMAN.md: aynı yaklaşımın size uygulanması

Intuition-Lab/personal-model (Temmuz 2026 itibarıyla 1,260 yıldız), bu yaklaşımı bir depo yerine bir kişiye uygular. Proje, HUMAN.md dosyanızı yazdığınız bir dosya olarak değil, sistemin çıktısı olarak tanımlar: "şu anda neyin önemli olduğunun, genellikle nasıl karar verdiğinizin ve dikkatinizin nereye yöneldiğinin yaşayan bir modeli." macOS 13 veya sonraki sürümlerde yerel olarak çalışır. macOS izni verildikten sonra etkinlikleri kaydeder ve sonucu MCP (model context protocol) üzerinden aracılara sunar. Kısa kurulum yolu:

uv tool install personal-model
persome onboard
persome model open --after 30

Faydaların çoğunu elde etmek için bunların hiçbirine gerek yoktur. Elle yazılmış bir HUMAN.md yaklaşık yirmi satırdan oluşur: rolünüz, saat diliminiz, gerçekten kullandığınız teknoloji yığını, daha önce verdiğiniz ve yeniden gündeme getirilmesini istemediğiniz kararlar ve ne kadar açıklama istediğiniz. Bir proje dosyasının sağladığı tekrarlanan açıklama ihtiyacını, bir üst katmanda aynı şekilde azaltır.

Bir uyarı: HUMAN.md bir kişi profili olduğundan tanımı gereği hassas bilgiler içerir. Dosyayı herkese açık bir depoda tutmayın. ~/.claude/CLAUDE.md içine veya proje kökündeki gitignore kapsamına alınmış bir CLAUDE.local.md dosyasına koyun. Bu dosya, commit edilmiş dosyanın yanında yüklenir ve aynı şekilde işlenir.

Kopyalayabileceğiniz başlangıç şablonu

Bu şablon bilerek kısa tutulmuştur. Uygun olmayan bölümleri silin ve güncel tutamayacağınız bölümler eklememeye çalışın.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Yazın, ardından doğrudan yerinde düzeltin. Bir satır ekleme sinyali, aynı düzeltmeyi sohbete iki kez yazmanızdır. Bu tek kural dosyayı kullanışlı tutar ve dosyanın makineler dahil kimsenin okumadığı bir belgeye dönüşmesini önler. Dosya kararlı hale geldiğinde repository ile birlikte taşınır. Bu, özellikle agent dizüstü bilgisayarınızdan başka bir yerde çalıştığında önemlidir: kendi sunucunuzda bir coding agent çalıştırma bu kurulumu açıklar.

FAQ

AGENTS.md, CLAUDE.md ile aynı dosya mıdır?

İki farklı dosya adı altında aynı fikirdir. Claude Code, CLAUDE.md dosyasını okur ve bunları birbirine bağlamadığınız sürece AGENTS.md dosyasını yok sayar. Tek bir dosyayı temel kaynak olarak tutun ve diğer dosyayı ona bağlayın. Bunun için CLAUDE.md dosyanızın başına @AGENTS.md satırını ekleyebilir veya ln -s AGENTS.md CLAUDE.md kullanabilirsiniz. Ayrı ayrı sürdürülen iki tam kopya bir ay içinde farklılaşır.

AGENTS.md yazmak, aracının bu dosyaya uyacağını garanti eder mi?

Hayır. İçerik bağlam olarak sağlanır. Model içeriği okur ve genellikle buna uyar, ancak bu içeriğe aykırı bir eylemi engelleyen bir mekanizma yoktur. Belirsiz talimatlara en az güvenilir biçimde uyulur. Birbiriyle çelişen yönlendirmeler içeren iki dosya, seçimi araca bırakır. Her seferinde geçerli olması gereken bir kural için hook veya permission rule kullanın. Bunlar, modelin kararından bağımsız olarak istemci tarafından uygulanır.

AGENTS.md git'e commit edilmeli mi?

Evet. Projeyle ilgili ve her zaman geçerli olan build komutları, dizin yapısı ve kurallar gibi bilgiler için commit edilmelidir. Dosyanın amacı budur. Böylece ekip arkadaşlarınızın araçları da sizin aracınızla aynı bağlamla başlar. Kişisel bilgiler veya tek bir makineye özgü ayarlar ayrı bir gitignored dosyada tutulmalıdır. Kimlik bilgileri ise bu dosyaların hiçbirinde yer almamalıdır.

HUMAN.md nedir ve buna ihtiyacım var mı?

HUMAN.md, bir proje yerine kişi için hazırlanmış, makine tarafından okunabilir bir profildir. Rolünüzü, kısıtlarınızı ve daha önce karara bağladığınız konuları içerir. Böylece bu konular her oturumda yeniden açılmaz. Başlamak için herhangi bir araca ihtiyacınız yoktur. Kullanıcı düzeyindeki talimat dosyanıza elle yazılmış yirmi satır eklemek, faydanın büyük bölümünü sağlar. Bu dosyayı kişisel veri olarak değerlendirin ve gönderdiğiniz hiçbir repository'ye eklemeyin.