AGENTS.md Nedir ve Nasıl Kullanılır?
Son zamanlarda yapay zekâ destekli kodlama araçlarını kullanırken AGENTS.md isimli bir dosyayla daha sık karşılaşmaya başladım.
Özellikle Codex, GitHub Copilot ve benzeri AI coding agent araçları projeyi sadece yazdığımız prompt üzerinden anlamaya çalışmıyor. Projenin nasıl çalıştığını, hangi kurallara uyulması gerektiğini ve kod yazarken nelere dikkat edilmesini istediğimizi de bilmesi gerekiyor.
İşte AGENTS.md dosyası burada devreye giriyor.
AGENTS.md Nedir?
AGENTS.md, bir yazılım projesinde AI coding agent'lara proje hakkında bilgi vermek ve uyulması gereken kuralları belirtmek için kullanılan bir Markdown dosyasıdır.
En basit haliyle bu dosyayı, yapay zekâya proje hakkında verdiğimiz sürekli talimatların bulunduğu bir dosya gibi düşünebiliriz.
Örneğin projemizde:
- Hangi teknolojilerin kullanıldığı
- Projenin nasıl çalıştırıldığı
- Testlerin nasıl çalıştırılacağı
- Kod yazarken hangi kurallara uyulacağı
- Dosyaların hangi klasörlerde bulunduğu
- Hangi dosyalara dokunulmaması gerektiği
gibi bilgileri AGENTS.md içerisinde belirtebiliriz.
AGENTS.md Ne İşe Yarar?
Normalde bir AI coding agent'a her görev verdiğimizde bazı bilgileri tekrar tekrar söylememiz gerekebilir.
Örneğin şöyle bir projemiz olduğunu düşünelim:
React + TypeScript MUI kullanılıyor Testler Vitest ile çalışıyor npm yerine pnpm kullanılıyor ESLint kuralları önemli API kodları src/api altında bulunuyor
Her yeni görevde bunları tekrar yazmak yerine bu bilgileri AGENTS.md içerisine koyabiliriz.
Böylece AI agent projede çalışırken bu kuralları ve proje yapısını dikkate alabilir.
AGENTS.md Nereye Konur?
En temel kullanımda AGENTS.md dosyasını projenin ana dizinine koyabiliriz.
my-project/ ├── AGENTS.md ├── package.json ├── src/ ├── tests/ └── README.md
Bu şekilde dosya projenin genel kurallarını ve yapısını anlatmak için kullanılabilir.
Daha büyük projelerde alt klasörlerde de ayrı AGENTS.md dosyaları kullanılabilir. Böylece belirli bir klasör veya bölüm için farklı kurallar tanımlanabilir.
AGENTS.md İçerisine Ne Yazılır?
Burada aslında tamamen projenin ihtiyaçlarına göre hareket edebiliriz. Ancak başlangıç olarak birkaç temel başlık yeterli olacaktır.
1. Proje Hakkında Bilgi
Öncelikle AI agent'ın üzerinde çalıştığı projeyi kısaca tanıtabiliriz.
# Proje Bu proje React ve TypeScript kullanılarak geliştirilmiş bir web uygulamasıdır. UI tarafında MUI kullanılmaktadır. State yönetimi Redux Toolkit ile yapılmaktadır.
2. Projeyi Çalıştırma
Projeyi çalıştırmak için hangi komutların kullanıldığını da belirtebiliriz.
# Development Bağımlılıkları kur: pnpm install Development ortamını çalıştır: pnpm dev
Bu özellikle AI agent'ın projeyi kendi ortamında çalıştırması gerektiğinde faydalı olabilir.
3. Test Komutları
Testlerin nasıl çalıştırılacağını da yazabiliriz.
# Tests Unit testleri çalıştır: pnpm test Lint kontrolü: pnpm lint
Böylece agent yaptığı değişikliklerden sonra hangi kontrolleri çalıştırması gerektiğini bilir.
4. Kodlama Kuralları
Projede uyulmasını istediğimiz kodlama kurallarını da burada belirtebiliriz.
# Coding Rules * TypeScript kullan. * Yeni kodlarda any kullanma. * Mevcut component yapısını koru. * Gereksiz dependency ekleme. * Mevcut naming convention'a uy.
Bu bölüm özellikle ekip içerisinde ortak kodlama standartları varsa oldukça faydalı olabilir.
5. Proje Yapısı
AI agent'ın proje içerisinde hangi klasörün ne amaçla kullanıldığını bilmesini de sağlayabiliriz.
# Project Structure src/components UI componentleri burada bulunur. src/api API istekleri burada bulunur. src/pages Sayfa componentleri burada bulunur. src/utils Ortak yardımcı fonksiyonlar burada bulunur.
Basit Bir AGENTS.md Örneği
Yukarıdaki bölümleri bir araya getirirsek basit bir AGENTS.md dosyası şöyle olabilir:
# AGENTS.md ## Project This is a React + TypeScript application. MUI is used for UI components. ## Package Manager Use pnpm. Do not use npm or yarn. ## Development Install dependencies: pnpm install Run the application: pnpm dev ## Tests Run tests with: pnpm test Run lint: pnpm lint ## Coding Rules * Use TypeScript. * Do not use any unless necessary. * Follow the existing project structure. * Reuse existing components when possible. * Do not add unnecessary dependencies. ## Project Structure src/components UI components. src/api API related code. src/pages Application pages. src/utils Shared utility functions.
AGENTS.md ile README.md Aynı Şey mi?
İlk bakışta ikisi birbirine benziyor gibi görünebilir ama amaçları biraz farklı.
README.md daha çok projeyi insanlara tanıtmak için kullanılır. Projenin ne yaptığı, nasıl kurulacağı ve nasıl kullanılacağı gibi bilgiler burada bulunur.
AGENTS.md ise özellikle AI coding agent'ın projede çalışırken ihtiyaç duyacağı talimatları ve proje bilgisini vermek için kullanılır.
| Dosya | Amaç |
|---|---|
README.md |
Projeyi insanlara tanıtmak ve kullanımını anlatmak |
AGENTS.md |
AI agent'a proje kurallarını ve çalışma şeklini anlatmak |
AGENTS.md Çok Uzun Olmalı mı?
Bence burada dikkat edilmesi gereken noktalardan biri de dosyayı gereksiz yere büyütmemek.
AGENTS.md içerisine projedeki her şeyi yazmak yerine agent'ın gerçekten ihtiyaç duyacağı bilgileri koymak daha mantıklı.
Örneğin projenin bütün teknik dokümantasyonunu bu dosyaya doldurmak yerine kısa bir şekilde nerede ne olduğunu gösterebiliriz.
Daha detaylı bilgiler gerekiyorsa bunları ayrı dokümantasyon dosyalarında tutup AGENTS.md içerisinden bu dosyalara yönlendirebiliriz. Bu yaklaşımda AGENTS.md daha çok bir yol haritası gibi kullanılmış olur.
Birden Fazla AGENTS.md Kullanılabilir mi?
Büyük projelerde tek bir AGENTS.md dosyası yeterli olmayabilir.
Örneğin projemizin şöyle bir yapısı olduğunu düşünelim:
project/ ├── AGENTS.md ├── frontend/ │ ├── AGENTS.md │ └── src/ └── backend/ ├── AGENTS.md └── src/
Burada ana AGENTS.md içerisinde bütün proje için geçerli kuralları, frontend ve backend içerisindeki dosyalarda ise sadece o bölüme özel kuralları tutabiliriz.
Bu sayede özellikle büyük ve monorepo şeklindeki projelerde farklı bölümlerin kendi kurallarını tanımlamak mümkün olur.
Hangi AI Araçlarında Kullanılır?
AGENTS.md fikri belirli bir AI aracına bağlı olmak zorunda değil. Günümüzde farklı coding agent araçları tarafından proje bağlamı ve talimatları sağlamak amacıyla kullanılabiliyor.
Örneğin GitHub, AGENTS.md dosyasını farklı AI agent'lar arasında paylaşılabilecek sürekli proje kuralları için kullanmayı öneriyor.
OpenAI tarafında da Codex ile çalışırken AGENTS.md dosyası proje talimatlarını ve çalışma kurallarını aktarmak için kullanılıyor.
Sonuç
Kısaca toparlamak gerekirse AGENTS.md, AI coding agent'ın projemizi daha iyi anlamasına yardımcı olan bir Markdown dosyasıdır.
Projeyi nasıl çalıştıracağını, hangi paket yöneticisini kullanacağını, testlerin nasıl çalıştırılacağını ve kod yazarken hangi kurallara uyması gerektiğini bu dosyada belirtebiliriz.
Ben özellikle sürekli aynı kuralları AI'a tekrar tekrar söylemek yerine bunları proje içerisine koymanın daha kullanışlı olduğunu düşünüyorum. Böylece yeni bir görev verirken sadece yapmak istediğimiz işe odaklanabiliyoruz.
Özellikle AI coding agent'ların projelerde daha fazla kullanılmaya başladığı bir dönemde AGENTS.md gibi dosyalar, projenin yapısını ve çalışma kurallarını AI'a aktarmak için oldukça kullanışlı bir yöntem haline geliyor.
