AI_GUIDELINES.md

AI Guidelines for ESGO Launcher Development

[!IMPORTANT]
All AI assistants contributing to this repository MUST read and adhere to these guidelines before proposing or executing any code changes.

1. Strict Type Safety & Error Handling

Python esnek bir dil olsa da, ESGO Launcher'da tip güvenliği ve hata yönetimi en yüksek önceliğe sahiptir.

Rule: Bütün fonksiyonlar, sınıflar ve değişkenler typing modülü (örn: Optional, List, Dict) kullanılarak kesin tip bildirimlerine (type hints) sahip OLMALIDIR.

Rule: Tip denetiminden kaçmak için Any kullanımı kesinlikle YASAKTIR.

Rationale: Projenin kararlılığını korumak için mypy gibi statik tip denetleyicilerin tam kapasiteyle çalışması gerekir. Hatalar try/except bloklarıyla güvenli bir şekilde yakalanmalı, sessizce geçiştirilmemelidir (pass kullanılmamalıdır).

2. Mandatory Documentation (""")

Yazılan tüm yeni kodlar, hem insanlar hem de gelecekteki yapay zeka bağlamları için kendini açıklayıcı nitelikte olmalıdır.

Rule: Eklenen her yeni class, def (fonksiyon/metot) ve modül dosyası KESİNLİKLE üç tırnak ("""...""") kullanılarak yazılmış docstring içermelidir.

Format: Türkçe/İngilizce çift dilli yorumlara izin verilir, ancak teknik açıklama net ve yapısal olarak tanımlayıcı olmalıdır.

3. Persistent Knowledge Base (.md)

Farklı oturumlar ve yapay zeka asistanları arasında mimari bütünlüğü sağlamak için:

Rule: Bütün eklenen yeni özellikler ve sistemsel geliştirmeler (ufak/büyük fark etmeksizin) ANINDA knowledge/history/engine_features.md dosyasına eklenmelidir.

Rule: Bütün hata düzeltmeleri (bug fixes), çökme (crash) çözümleri, kararlılık yamaları ve düzeltmeler ise ANINDA knowledge/history/bug_fixes.md dosyasına eklenmelidir.

Rule: Bu bir TAVSİYE DEĞİL, ZORUNLULUKTUR! Yapılan işlemi tamamladıktan sonra history/engine_features.md veya history/bug_fixes.md dosyalarını (yapılan değişikliğin türüne göre) güncellemezseniz, kural ihlali yapmış olursunuz.

Rule: For every significant feature or refactor, a corresponding .md file must be created or updated in the knowledge/ directory.

Rule: If you modify existing code structures, you MUST update the related documentation in the knowledge/ folder to reflect the changes immediately.

Rule: Before starting work, the AI must search and read relevant files in the knowledge/ directory (especially those inside knowledge/history/) to understand the existing logic, patterns, and resolved issues.

4. Modular Responsibility

ESGO Launcher sıkı bir modüler mimari izler.

Rule: main.py dosyasını olabildiğince temiz ve kısa tutun.

Rule: Mantıksal işlemleri özelleşmiş modüllere devredin (örn: steam_tracker.py, epic_parser.py, gog_integration.py, ui_manager.py).

Rule: Birbirinden bağımsız birden fazla sorumluluğu yöneten, devasa "God Object" sınıfları oluşturmayın.

5. Verification Standards

   Rule: Herhangi bir yapısal değişiklikten sonra sıfır hata ve sıfır uyarı olduğundan emin olmak için mutlaka mypy ve pytest (veya projede kullanılan linter/test aracı) çalıştırılmalıdır.

   Rule: Geçici yer tutuculardan (placeholder) kaçının. Eğer bir asset veya dizin yolu (path) gerekliyse, gerçekçi ve sistemde karşılığı olan yapılar kullanın.

ESGO Launcher AI Constitutional Guidelines (v2026)

API Accuracy (Strict Enforcement): Projede kullanılan tüm UI kütüphaneleri (örn: PyQt, Tkinter, CustomTkinter vb.) ve sistem/dosya yönetim modülleri (os, subprocess, pathlib) web'den kontrol edilerek en güncel kararlı dökümantasyonuna sadık kalarak yazılmalıdır. Eski sürüm API'larını kullanmak veya önermek kesinlikle YASAKTIR.

Kırıcı Değişiklikler (Breaking Changes) ve Onay: Eğer bir kütüphanenin en güncel kararlı sürümüne geçiş, kod tabanında geniş çaplı kırıcı değişiklikler (breaking changes) veya büyük yapısal refaktörler gerektiriyorsa; AI bu güncellemeyi doğrudan uygulamamalıdır. Öncelikle durum hakkında kullanıcıya detaylı bilgi vermeli ve onay istemelidir.

Modern Python Standartları: Kodlar; Python'un güncel sürümlerine uygun (örneğin match/case yapıları, modern pathlib kullanımı) şekilde yazılmalıdır.

Memory Safety & Performance: Python'da bellek sızıntılarını (memory leak) önlemek için, özellikle UI bileşenleri ve dış döngüler (event loop) oluşturulurken referans yönetimine (garbage collection) dikkat edilmelidir.

Deprecated Uyarısı: Eğer bir kütüphane dokümantasyonunda bir fonksiyon veya sınıf "deprecated" olarak işaretlenmişse, AI bunu asla kullanmamalı, direkt güncel karşılığına geçmelidir.

Documentation: Yaptığın her köklü değişikliği """ docstring'leri ile kodun içine ve ilgili .md dosyalarına işle. AI her işe başlarken kendi geçmiş .md raporlarını okumalıdır.

Modularization: Dosyalar 800 satırı geçmemelidir. Mantıksal ayrımı temiz tut.

Zero-Error Policy: Projenin çalışma durumu her zaman 0 error / 0 warning hedefinde tutulmalıdır.

6. Strict File Boundary Enforcement

   Rule: Existing module boundaries are ABSOLUTE and MUST NOT be changed.

   Rule: DO NOT merge files, collapse modules, or move logic between modules unless explicitly instructed.

   Rule: Each module has a SINGLE responsibility and must remain isolated.

   Rule: If a task requires changes across multiple modules, modify them individually — NEVER combine them.

   Violation Condition: If an AI merges modules, combines files, or centralizes logic into a single file, the solution is INVALID.

7. Scope Isolation Rule

   Rule: AI must ONLY modify the explicitly requested file or module.

   Rule: Expanding scope beyond the requested area is FORBIDDEN.

   Rule: No "improvements", "refactors", or "optimizations" outside the given scope.

   Example: If asked to fix a bug in steam_tracker.py: ONLY modify steam_tracker.py. DO NOT touch ui_manager.py, core.py, or other modules.

   Violation Condition: If AI modifies unrelated modules, the answer is INVALID.

8. No Implicit Refactor Rule

   Rule: Refactoring is ONLY allowed when explicitly requested.

   Rule: AI must NOT reorganize, restructure, or rewrite code unless instructed.

   Forbidden Actions: Combining multiple modules into one, moving logic "for readability", changing architecture without explicit permission.

   Allowed: Minimal, localized fixes.

9. Architecture Preservation Rule

   Rule: The current architecture is considered STABLE and must be preserved.

   Rule: AI must treat the codebase as a production system, not a prototype.

   Priority Order: 1. Stability, 2. Modularity, 3. Readability, 4. Performance.

   Rule: If a change risks breaking architecture, it must NOT be applied.

10. Small Function Rule

    Rule: Functions should remain small and focused (ideally <100 lines).

    Rule: If a function grows too large, split it into smaller helper functions.

    Forbidden: Large monolithic functions, Multi-responsibility functions.

    Goal: AI-friendly, low-context code.

11. Multi-Module Coordination Rule

    Rule: When working across multiple modules:

    Analyze all modules
    
    Propose a plan
    
    Wait for confirmation
    
    Then implement
    

    Rule: Direct multi-module changes without planning are FORBIDDEN.

12. Anti-God Object Rule

    Rule: No class may exceed a reasonable responsibility scope.

    Rule: Large classes must be decomposed into smaller sub-systems.

    Forbidden: Centralized "manager" objects controlling everything, Overloaded state containers (God Objects).

    Goal: Composable systems with clear boundaries.

13. AI Behavior Lock

    Rule: AI must NOT assume missing context.

    Rule: AI must NOT "improve" unspecified areas.

    Rule: AI must NOT take initiative beyond instructions.

    Rule: If uncertain: ASK instead of modifying code.

14. Single Responsibility Per File (SRP)

    Rule: Every single .py file must have ONE specific, clearly defined responsibility and execute it exceptionally well.

    Rule: If a file manages UI, it should NOT manage local directory parsing or API calls.

    Goal: Strict adherence to SOLID principles, ensuring maximum maintainability and predictability. The "One File, One Task" architecture ensures that bugs are deeply localized.

15. Memory Bank Rule (ZORUNLU)

ESGO Launcher uses a persistent memory-bank/ folder as the long-term project memory for all AI assistants.

Rule: Before starting any task, the AI MUST read all existing files inside the memory-bank/ folder.

Rule: projectbrief.md is the source of truth for project scope, goals, and core requirements.

Rule: activeContext.md MUST reflect the current focus, recent changes, next steps, active decisions, and important learnings.

Rule: progress.md MUST track what works, what is left to build, current status, known issues, and the evolution of project decisions.

Rule: systemPatterns.md MUST document architecture, technical decisions, design patterns, component relationships, and critical implementation paths.

Rule: techContext.md MUST document technologies, dependencies, development setup, technical constraints, and tool usage patterns.

Rule: productContext.md MUST document why the project exists, what problems it solves, how it should work, and user experience goals.

Required Memory Bank Structure Plaintext

memory-bank/ projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md

16. Documentation Quality Score Rule (ZORUNLU)

ESGO Launcher does not accept low-quality """ docstrings. Documentation must be useful for humans, future AI assistants, and long-term maintenance.

Rule: Every new or modified class, def (function/method), and module MUST have a documentation quality score.

Rule: The AI MUST internally evaluate every docstring with a score from 0/10 to 10/10.

Rule: Any documentation below 8/10 is considered unacceptable and MUST be improved before the task is completed.

Rule: The AI MUST prefer clear technical explanations over vague comments.

Rule: Documentation must explain purpose, responsibility, constraints, expected parameters (Args:), and return types (Returns:) when relevant.

Rule: Documentation must NOT simply repeat the item name.

Documentation Score Meaning Plaintext

0/10 = Missing documentation. 1/10 = Useless placeholder comment. 2/10 = Extremely vague and not technically helpful. 3/10 = Mostly repeats the item name. 4/10 = Mentions purpose but lacks useful context. 5/10 = Basic explanation, but incomplete. 6/10 = Understandable but missing constraints, parameters, or return types. 7/10 = Good enough for humans, but not strong enough for long-term AI context. 8/10 = Acceptable: clear purpose, behavior, typing info, and relevant context. 9/10 = Strong: explains purpose, behavior, constraints, types, and integration context. 10/10 = Excellent: future-proof, precise, technically rich, and useful for AI/human maintenance.

17. Copyright and SPDX Header Rule (ZORUNLU)

    Rule: Every project source file (e.g., .py files) MUST begin with the following exact two-line header:

Python

SPDX-License-Identifier: (Lisans Türü)-only

Copyright (c) 2026 (Github Adı) / ESGO Launcher. All rights reserved.

Rule: When creating a new .py source file, this header must be prepended at the very top.

Rule: AI assistants and developers MUST preserve this header during any modifications or refactoring.

Rule: If a file is updated in a subsequent year (e.g., 2027, 2028, etc.), the copyright year in the header should be updated to reflect the active year or year range (e.g., 2026-2027 or 2026-2028).