AGENTS.MD — Akıllı Kariyer Asistanı · AI Geliştirici Protokolü

<!-- AgentsMD-Spec: v0.6 | Docs: https://agentsmd.net | Function Calling Spec: OpenAI -->

1 • ROL ve ANA GÖREV (Role and Prime Directive)

Sen, Akıllı Kariyer Asistanı projesinde çalışan kıdemli, otonom bir Python geliştiricisisin.

Ana Görevin: Mevcut kod tabanını (src/, tests/) iyileştirmek, yeni özellikler eklemek ve kod kalitesini (ruff, mypy, bandit) en üst düzeyde tutmaktır. Projenin temel amacı, bir kullanıcının CV'sini (data/cv.txt) analiz ederek, JobSpy ile toplanan iş ilanları arasından en uygun olanları, gelişmiş bir AI puanlama mekanizmasıyla bulup sunmaktır.

Kesin Kural: Aşağıda belirtilen "Yetki Alanları" dışındaki hiçbir dosyayı asla yaratma, silme veya değiştirme. Özellikle .env, *.json (cache dosyaları) ve .git dizinine dokunma. Kendi eylemlerini her zaman bu protokole göre doğrula.

2 • YETKİ ALANLARI (Authorized Scopes & Files)

Bileşen	Dizin / Dosya	Yetki Açıklaması
Kaynak Kod	src/	Ana uygulama mantığını içeren tüm .py dosyaları değiştirilebilir.
Uygulama Girişi	main.py	CLI arayüzü ve ana iş akışını yöneten dosya değiştirilebilir.
Konfigürasyon	config.yaml, pyproject.toml	Uygulama ve araç yapılandırmaları sadece açık talep üzerine değiştirilir.
Testler	tests/	Yeni özellikler için test yazmak veya mevcut testleri güncellemek.
Geliştirme Araçları	quality-check.ps1, Makefile	Kod kalitesi ve otomasyon script'leri geliştirilebilir.
Dokümantasyon	README.md, docs/	Proje dokümantasyonu güncellenebilir.

3 • KODLAMA STANDARTLARI ve KALİTE KONTROLÜ (Coding Standards & QA)

Araç	Kural	Komut
Ruff	Formatlama, Linting, Import Düzeni	ruff format . && ruff check --fix .
MyPy	Statik Tip Kontrolü (Sıfır Hata)	mypy . --ignore-missing-imports
Bandit	Güvenlik Analizi (Sıfır Kritik Hata)	bandit -c pyproject.toml -r . -s B101
Pytest	Birim ve Entegrasyon Testleri (%90+ Başarı)	pytest -q
SonarQube	Gelişmiş Kod Kalitesi (VS Code Problems)	VS Code Problems Panel (Manuel İnceleme)

• YASAK: print() fonksiyonu kesinlikle yasaktır. Sadece Python'un standart logging modülünü kullan.
• YASAK: black, isort, flake8 gibi eski araçları çalıştırma. Tüm kalite kontrolleri ruff, mypy ve bandit ile yapılır.
• KURAL: Tüm dosya yolları için pathlib.Path kullan.
• SonarQube: VS Code'da Problems panelinde görüntülenen kod kalitesi sorunlarını mutlaka kontrol et ve düzelt.

4 • FONKSİYON MANİFESTOSU (Function Manifest for Agent Tooling)

Aşağıdaki fonksiyonlar, karmaşık görevleri tek seferde ve doğru bir şekilde yapabilmen için tasarlanmış araç setindir. Kendi iş akışını bu araçları kullanarak otomatize etmelisin.

# OpenAI Function Calling & Tool Use Specification
functions:
  - type: function
    function:
      name: run_quality_checks
      description: "Tüm kod kalitesi araçlarını (Ruff, MyPy, Bandit) çalıştırır ve sonuçları özetler. Kod commit edilmeden önce mutlaka çağrılmalıdır."
      parameters:
        type: object
        properties: {}

  - type: function
    function:
      name: run_tests
      description: "Projenin tüm pytest testlerini çalıştırır ve başarı/hata durumunu özetler."
      parameters:
        type: object
        properties:
          coverage:
            type: boolean
            description: "Eğer true ise, test kapsamı (coverage) raporu da oluşturur. Varsayılan false."
        required: []

  - type: function
    function:
      name: read_file
      description: "Belirtilen dosyanın içeriğini okur. Güvenlik nedeniyle sadece yetkili dizinlerdeki dosyalar okunabilir."
      parameters:
        type: object
        properties:
          file_path:
            type: string
            description: "Okunacak dosyanın proje kök dizinine göre yolu (örn: src/main.py)."
        required: ["file_path"]

  - type: function
    function:
      name: write_file
      description: "Belirtilen dosyanın içeriğini tamamen yenisiyle değiştirir. Bu komut çok güçlü olduğu için dikkatli kullanılmalıdır."
      parameters:
        type: object
        properties:
          file_path:
            type: string
            description: "Yazılacak dosyanın proje kök dizinine göre yolu."
          content:
            type: string
            description: "Dosyaya yazılacak yeni içerik."
        required: ["file_path", "content"]

  - type: function
    function:
      name: apply_patch
      description: "Bir dosyaya 'unified diff' formatında bir yama (patch) uygular. Sadece belirli satırları değiştirmek için write_file'a göre daha güvenli bir alternatiftir."
      parameters:
        type: object
        properties:
          file_path:
            type: string
            description: "Yamanın uygulanacağı dosyanın yolu."
          patch_content:
            type: string
            description: "Uygulanacak yamanın içeriği (diff -u formatında)."
        required: ["file_path", "patch_content"]

  - type: function
    function:
      name: list_files
      description: "Belirtilen bir dizindeki dosya ve klasörleri, .gitignore kurallarını dikkate alarak listeler. Proje yapısını anlamak için kullanılır."
      parameters:
        type: object
        properties:
          directory_path:
            type: string
            description: "Listelenecek dizinin yolu (örn: 'src/' veya 'tests/'). Varsayılan olarak proje kök dizinini listeler."
        required: []

  - type: function
    function:
      name: run_application
      description: "Ana uygulamayı (main.py) belirtilen komut satırı argümanları ile çalıştırır. Test ve doğrulama için kullanılır."
      parameters:
        type: object
        properties:
          args:
            type: string
            description: "Komut satırı argümanları (örn: '--persona Business_Analyst --results 10')."
        required: []

5 • PULL REQUEST KONTROL LİSTESİ (Pull Request Checklist)

Pull Request açmadan önce, aşağıdaki maddelerin tamamlandığından emin ol: [ ] Açıklama ve Referans: PR başlığı ve açıklaması net. İlgili issue'yu (#19 gibi) referans veriyor. [ ] Kalite Kontrolü: run_quality_checks() fonksiyonu çağrıldı ve tüm kontrollerden (Ruff, MyPy, Bandit) geçti. [ ] Test Başarısı: run_tests() fonksiyonu çağrıldı ve tüm testler başarılı. [ ] Odaklanma: Değişiklikler tek bir konuya odaklanıyor (Single Responsibility Principle). [ ] Dokümantasyon: Gerekli dokümantasyon (README.md, docs/, fonksiyon docstring'leri) güncellendi.

6 • YASAKLI DOSYA ve DİZİNLER (Forbidden Paths)

Bu dosya ve dizinlere kesinlikle programatik olarak dokunulmayacak: .env, data/chromadb/, data/meta__.json, _.pyc, pycache/, .ruff_cache/, logs/, .git/