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

# 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.

```yaml
# 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/