AGENTS.md ve HUMAN.md dosyaları nasıl hazırlanır?

AGENTS.md nedir

AGENTS.md, bir deponun kök dizininde bulunan ve kodlama aracına o proje üzerinde nasıl çalışması gerektiğini bildiren düz bir markdown dosyasıdır. Resmi site bunu "aracılar için bir 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 yer" olarak tanımlar. Format, Linux Foundation bünyesindeki Agentic AI Foundation tarafından yönetilmektedir ve Temmuz 2026 itibarıyla Codex, Cursor, Jules, Devin ve GitHub Copilot dahil olmak üzere yirmiden fazla aracı tarafından okunmaktadır.

Bu kuralın var olma nedeni pratiktir. Ekibinize yeni katılan bir kişi README dosyasını okur, derleme komutunu tahmin eder ve tahmin yanlış olduğunda birine sorar. Bir aracı ise soru soramaz. Tahmin yürütür, pnpm test kullanan bir projede npm test komutunu çalıştırır, hatayı okur ve başka bir şey dener. Bu token'ların her biri için ücret ödersiniz. Gerçek komutu bir kez yazmak, bu tür hataların tamamını ortadan kaldırır.

Zorunlu alan yoktur. Site bu konuda nettir: "AGENTS.md sadece standart Markdown'dır. İstediğiniz başlıkları kullanın; aracı, sağladığınız metni basitçe ayrıştırır." Spesifikasyonun tamamı budur. Değer formatta değil, her aracın halihazırda baktığı bir yolda bulunan dosyanın kendisindedir.

Dosyanın konumu ve hangi dosyanın geçerli olduğu

İlk dosyayı depo kök dizinine yerleştirin. Bir monorepo yapısında her alt projenin içine daha fazla dosya ekleyebilirsiniz; kural basittir: "aracılar dizin ağacındaki en yakın dosyayı otomatik olarak okur, bu nedenle en yakındaki dosya önceliklidir." İki dosya arasındaki bir çakışma, düzenlenmekte olan dosyaya göre çözümlenir ve sohbet ekranına yazdığınız her şey her iki dosyayı da geçersiz kılar.

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 yapısını kullanmak faydalıdır, çünkü bu yöntem bir klasörde doğru olan ancak diğerinde yanlış olan bir kuralı belirtmenin tek yoludur. "Her uç nokta kendi girdisini doğrular" gibi bir kural, uç noktaların yanında yer almalıdır. Kök dizindeki bir dosyada bu kural, alakasız her görevde yüklenir ve hiçbir fayda sağlamaz. Eğer kök dizindeki dosyanız her servis için ayrı bir bölüm içerecek kadar büyüdüyse, onu iç içe bir yapıya bölmek çözüm olacaktır; bu işlem hangi kuralların aşağı taşınacağını ve hangilerinin en üstte kalacağını belirler.

AGENTS.md dosyasında neler yer almalı

Bir ajanın kodu okuyarak çıkarım yapamayacağı bilgileri yazın. Tam derleme, test ve lint komutlarını, terminale yapıştırabileceğiniz biçimde en başa ekleyin. Tek bir testi çalıştırmak için gereken komutu da belirtin; çünkü yalnızca tüm test paketini çalıştırmayı bilen bir ajan, aynı işlemi kırk kez tekrarlayacaktır. Araç varsayımlarından sapan kuralları listeleyin; ajan zaten varsayılanları bildiği için yalnızca sapmaları öğrenmeye ihtiyaç duyar. Varsa commit mesajı formatını ve pull request kurallarını ekleyin.

Bir iddianın doğrulanabileceği kadar somut olun. "2 boşluklu girintileme kullanın" uygulanabilir bir talimattır çünkü ya yapılmıştır ya da yapılmamıştır. "Kodu düzgün biçimlendirin" ifadesi ise doğrulanabilir hiçbir yanı olmadığı için kullanışlı değildir. Aynı durum konumlar için de geçerlidir: "API işleyicileri src/api/handlers/ dizininde bulunur" ifadesi, "dosyaları düzenli tutun" demekten çok daha etkilidir.

Negatif kurallar da yerini hak eder. "dist/ altındaki dosyaları asla düzenlemeyin, bunlar npm run build tarafından oluşturulmuştur" kuralı belirli bir hatayı engeller ve nedenini belirttiği için ajan, yazmadığınız benzer durumları da kendi başına çözebilir. Kapsam ile ilgili bir kural da burada yer almalıdır, çünkü kendi kararına bırakılan bir ajan, istediğinizden daha fazla yeri değiştirecektir: yaygın olarak kopyalanan bir beceri, yalnızca çalışan en küçük değişikliği yapma konusunda ısrarcı olmaktan ibarettir.

İçerisinde asla bulunmaması gerekenler

Bu dosyalardan birinin içerisine asla gizli veri koymayın. Dosya git deposuna 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çerisindeki bir API anahtarı, hem depo geçmişinizde hem de üçüncü tarafın günlüklerinde yer alan bir API anahtarı demektir. Gizli veriyi yapıştırmak yerine ona işaret edin: "veritabanı parolası gitignore edilmiş olan .env dosyasındadır; okumadan önce izin isteyin." Bu konudaki daha geniş disiplin kimlik bilgilerini bir ajanın erişiminden uzak tutma bölümünde ele alınmıştır.

Ajanın bakarak çıkarım yapabileceği her şeyi dışarıda bırakın. Yapıştırılmış bir dizin listesi, bağımlılık listenizin bir kopyası veya klasör isimlerini tekrar eden bir mimari genel bakışı: bunların hepsi yazdığınızdan bir hafta sonra güncelliğini yitirir ve bu süre zarfında her oturumda bağlam maliyeti oluşturur. Tuzakları ve nedenleri tutun. Envanteri çıkarın. Nedenleri ayrı tutmakta fayda vardır; çünkü alışılmadık bir yapının neden var olduğunu göremeyen bir ajan, onu sessizce yeniden düzenleyerek ortadan kaldıracaktır. Bunun yanında bir DESIGN.md tutmanın amacı da budur.

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

Claude Code, CLAUDE.md dosyasını okur ancak AGENTS.md dosyasını kendiliğinden okumaz. Proje dosyası ./CLAUDE.md veya ./.claude/CLAUDE.md konumunda bulunur; her projeye özel tercihler ~/.claude/CLAUDE.md içine yazılır ve bir organizasyon, Linux üzerinde makine genelinde geçerli bir dosyayı /etc/claude-code/CLAUDE.md konumuna gönderebilir. Keşfedilen dosyalar, dosya sistemi kök dizininden çalışma dizininize kadar birleştirilir; bu nedenle oturumu başlattığınız yere en yakın olan dosya en son okunur. O dizinde başlattığınız her oturum aynı yığını yükler; bu da aynı makinede iki oturumu yan yana çalıştırmayı mümkün kılar ve bu oturumlar çalışırken birbirlerine iş devredebilirler.

Deponuzda halihazırda bir AGENTS.md dosyası varsa, ikinci bir kopya tutmayın. Onu içe aktarın ve ardından yalnızca Claude'a özgü olanları ekleyin:

@AGENTS.md

## Claude Code

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

Ekleyecek ekstra bir şeyiniz olmadığında sembolik bağ (symlink) iş görür:

ln -s AGENTS.md CLAUDE.md

Komut, başarı durumunda herhangi bir çıktı vermez. Bir sonraki oturumunuzda /context komutunu çalıştırın ve Memory files altında CLAUDE.md ifadesinin göründüğünü doğrulayın. Eğer listede yoksa dosya hiç yüklenmemiş demektir, dolayısıyla içindeki hiçbir kural uygulanmamıştır. Yazmak yerine ilk taslağı oluşturmak için /init komutunu çalıştırın: bu komut kod tabanını okur ve bir başlangıç dosyası üretir; CLAUDE.md zaten mevcutsa, üzerine yazmak yerine iyileştirmeler önerir.

Her dosyayı yaklaşık 200 satırın altında tutun. Daha uzun dosyalar pencerenin daha fazlasını tüketir ve uyum oranı düşer. Bu alan için başka nelerin rekabet ettiğini görmek isterseniz, bir ajanın bağlam penceresini gerçekte nelerin doldurduğu konusundaki döküm inceleyebilirsiniz.

Bir nokta vurgulanmalıdır. AGENTS.md bir izin sistemi değil, bir rehberdir. İçerik sıradan bir bağlam olarak iletilir, bu nedenle model bunu okur ve genellikle uyar; ancak buna aykırı bir eylemi engelleyecek bir mekanizma yoktur. Yazdığınız bir kural sessizce atlandığında ve nedenini anlayamadığınızda, metni üçüncü kez yeniden yazmadan önce bir talimatın neden göz ardı edildiğine dair nedenleri inceleyin. "main dalına asla push yapma" gibi her seferinde geçerli olması gereken bir kural için bir hook veya izin ayarı kullanın; çünkü bunlar kod olarak çalışır ve modelin itaat etme kararına bağlı değildir.

Bu dosyaları sizin yerinize oluşturan araçlar

30 Temmuz 2026 tarihinde GitHub popüler listesinde yer alan iki proje, bu konudaki eğilimin nereye gittiğini göstermektedir.

agent0ai/dox (Temmuz 2026 itibarıyla 1.368 yıldız), AGENTS.md dosyalarından oluşan bir ağacı güncel tutmaya yarayan bir çerçevedir. Herhangi bir paket veya çalışma zamanı (runtime) içermez. Kendi kök dizininizdeki AGENTS.md dosyasının içine ilgili içeriği kopyalarsınız; kurulum bu kadar basittir. Hali hazırda var olan bir proje için ajansınıza şu komutu verirsiniz:

Initialize DOX tree for this project now.

Ajan daha sonra alt AGENTS.md dosyalarını ve bunların dizinlerini oluşturur, herhangi bir düzenleme yapmadan önce ağacı tarar ve bir değişiklik gerçekleştiğinde ilgili dokümantasyonu günceller. Bu yaklaşımın temelindeki varsayım şudur: Bir ajanın çalışmasının yan etkisi olarak güncel tuttuğu dokümantasyon doğru kalırken, bir insanın elle güncellediği dokümantasyon zamanla geçerliliğini yitirir.

HUMAN.md, size yöneltilen aynı yöntem

Intuition-Lab/personal-model (Temmuz 2026 itibarıyla 1.260 yıldız), aynı modeli bir depo yerine bir kişi üzerinde uygular. Proje, HUMAN.md dosyanızı sizin yazdığınız bir dosya olarak değil, sistemin çıktısı olarak kurgular: "şu an neyin önemli olduğuna, nasıl karar verdiğinize ve dikkatinizin nereye yöneldiğine dair yaşayan bir model." macOS 13 veya sonraki sürümlerde yerel olarak çalışır, macOS izni verdiğinizde etkinlikleri yakalar 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

Bu avantajların çoğunu elde etmek için bunların hiçbirine ihtiyacınız yoktur. Elle yazılmış bir HUMAN.md yaklaşık yirmi satırdır: rolünüz, saat diliminiz, fiilen kullandığınız teknoloji yığını, halihazırda verdiğiniz ve tekrar açılmasını istemediğiniz kararlar ve ne kadar açıklama istediğiniz. Bir proje dosyasının sağladığı aynı tekrarlayan açıklamaları, bir katman yukarıda olacak şekilde kaydeder.

Bir uyarı. HUMAN.md bir kişinin profili olduğundan, tanımı gereği hassastır. Herkese açık bir depoda tutmayın. ~/.claude/CLAUDE.md içine veya proje kök dizininde gitignore edilmiş bir CLAUDE.local.md içine yerleştirin; bu dosya, commit edilen dosya ile birlikte yüklenir ve aynı şekilde işlenir.

Kopyalayabileceğiniz bir başlangıç şablonu

Bu metin bilinçli olarak kısa tutulmuştur. Uygulanamayan bölümleri silin ve güncel tutamayacağınız bölümleri eklemekten kaçını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.

Metni yazın ve ardından yerinde düzeltin. Bir satırı eklemeniz gerektiğinin işareti, aynı düzeltmeyi sohbet penceresine iki kez yazmanızdır. Bu tek kural, dosyanın işlevsel kalmasını sağlar ve dosyanın makineler dahil kimsenin okumadığı bir dokümana dönüşmesini engeller. Dosya kararlı hale geldiğinde depo ile birlikte taşınır; bu durum, aracın dizüstü bilgisayarınız dışında bir yerde çalıştığı durumlarda en önemli hale gelir: kendi sunucunuzda kodlama aracı çalıştırma konusu bu kurulumu kapsamaktadır.

FAQ

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

Bu iki dosya, aynı mantığın iki farklı dosya ismiyle ifade edilmesidir. Claude Code, CLAUDE.md dosyasını okur ve siz onları birbirine bağlamadığınız sürece AGENTS.md dosyasını görmezden gelir. Bir dosyayı temel kaynak olarak belirleyin ve diğerini ona bağlayın; bunu CLAUDE.md dosyanızın en üstüne @AGENTS.md satırını ekleyerek veya ln -s AGENTS.md CLAUDE.md kullanarak yapabilirsiniz. Ayrı ayrı tutulan iki tam kopya, bir ay içinde birbirinden farklılaşacaktır.

AGENTS.md dosyası yazmak, ajanın buna uymasını garanti eder mi?

Hayır. İçerik bağlam olarak iletilir; bu nedenle model bunu okur ve genellikle uyar, ancak buna aykırı bir eylemi engelleyen bir mekanizma yoktur. Belirsiz talimatlara en az güvenilir şekilde uyulur ve birbirine zıt yönlendirmeler içeren iki dosya, ajanın rastgele birini seçmesine neden olur. Her zaman geçerli olması gereken bir kural için, modelin kararlarından bağımsız olarak istemci tarafından uygulanan bir kanca (hook) veya izin kuralı kullanın.

AGENTS.md dosyası git deposuna eklenmeli midir?

Evet; derleme komutları, dizin yapısı ve kurallar gibi proje hakkında doğru olan her şey için eklenmelidir. Dosyanın amacı budur; böylece ekip arkadaşlarınızın ajanları da sizinle aynı bağlamla işe başlar. Kişisel olan veya tek bir makineye özgü bilgiler gitignore edilmiş ayrı bir dosyada tutulmalı, kimlik bilgileri ise hiçbirine yazılmamalıdır.

HUMAN.md nedir ve bir tane oluşturmam gerekir mi?

HUMAN.md, bir projeden ziyade bir kişiye ait makine tarafından okunabilir bir profildir. Rolünüzü, kısıtlamalarınızı ve daha önce aldığınız kararları içerir; böylece her oturumda aynı konuların tekrar açılması engellenir. Başlamak için herhangi bir araca ihtiyacınız yoktur: kullanıcı düzeyindeki talimat dosyanıza el ile yazacağınız yirmi satır, size faydanın büyük kısmını sağlayacaktır. Bunu kişisel veri olarak değerlendirin ve dışarıya gönderdiğiniz hiçbir depoya dahil etmeyin.