Dokümantasyon Düzeni

Bu repoda iki ayrı dokümantasyon katmanı var. İkisi farklı okuyuculara yazılır ve farklı kurallarla güncellenir.

docs/: ekip dokümantasyonu

Yapı ve kurallar smartmenu-adisyon-plugin eklentisinden gelir. Eklenti dört servis reposunun hepsine kurulur:

/plugin marketplace add https://github.com/OverfitSoft/smart-menu-adisyon-plugin
/plugin install smartmenu-adisyon-plugin@smart-menu-adisyon-plugin-marketplace

Nereye yazılır

Panel şu an endpoint açmadığı için docs/api/ henüz yok. İlk route handler ya da dışarıya açılan server action ile birlikte oluşturulmalı. Panelin çağırdığı backend endpoint’leri backend reposunda belgelenir; burada yalnızca Veri ve entegrasyon sayfasındaki tabloda listelenir.

Mevcut mimari sayfaları:

• Genel bakış: reponun sistemdeki yeri, yığın, dizinler, komutlar
• Rotalar ve kabuk: URL’ler, (panel) grubu, Server/Client sınırı, auth
• Ekranlar: her ekranın davranışı ve bağlı olduğu işler
• Tasarım sistemi: token’lar, bileşen sınıfları, ortak parçalar
• Veri ve entegrasyon: fixture’lar, sayaçlar, bekleyen backend işleri

Yeni bir alan (ör. auth geldiğinde) mevcut sayfalardan birine sığmıyorsa yeni bir docs/architecture/<konu>.md açın. Sayfalar tek bir story’ye değil, sistemin bir alanına karşılık gelmeli.

Biçim

Her dosyanın en üstünde şu frontmatter zorunludur:

---
title: <başlık>
updated: <YYYY-MM-DD>
---

• Bir sayfayı değiştirdiğinizde updated alanını da güncelleyin.
• Değişiklik breaking change ise (ör. bir rota kaldırıldı, bir endpoint sözleşmesi değişti) dosyanın en üstüne, frontmatter’ın hemen altına ⚠️ ile başlayan bir uyarı ekleyin.
• Sayfalar sistemin şu anki halini anlatır. Bir değişiklik bir cümleyi yanlış yaptıysa o cümleyi düzeltin; altına düzeltme notu eklemeyin. Geçmiş için git ve changelog.md var.

Ne zaman güncellenir

Kod değişikliği şunlardan birini etkiliyorsa, ilgili docs/ dosyası aynı commit’te güncellenir:

• Yeni rota veya ekran, ekranda davranış değişikliği
• Yeni veya değişen endpoint, gerçek veriye geçen bir ekran
• Tasarım sistemine yeni token veya bileşen
• Kurulum, komut ya da doğrulama adımlarında değişiklik

Ayrı bir “docs PR’ı” açılmaz. Eklentinin Stop hook’u her oturumun sonunda bunun yapılıp yapılmadığını Claude’a kontrol ettirir.

Merkezi docs sitesine aktarım

docs/ değişiklikleri ana branch’e merge edildikten sonra her servis reposundaki sync-docs.yml GitHub Action’ı içeriği merkezi docs reposuna göndermesi ve orada deploy tetiklemesi için planlandı. Bu workflow henüz hiçbir repoda yok; şu an docs/ yalnızca repoda okunur.

CLAUDE.md ve docs/claude/: Claude çalışma dokümanları

Claude Code oturumlarının kod yazmadan önce okuduğu, “neden böyle”yi reddedilen alternatiflerle birlikte anlatan İngilizce dokümanlardır.

• Branch’ler CLAUDE.md veya docs/claude/*.md dosyalarını düzenlemez. Paralel branch’ler aynı dosyayı düzenlediğinde her merge’te çakışma çıkıyor ve çözümler metin kaybettiriyordu (SCRUM-198).
• Bunun yerine her issue için docs/claude/pending/<ISSUE-KEY>.md notu bırakılır. Yeni dosya çakışmaz. Biçim: docs/claude/pending/README.md.
• Sprint sonunda biri dev’de /claude-md-sync çalıştırır; notlar dokümanlara işlenir ve silinir.
• dev’e açılan ve bu dosyaları doğrudan düzenleyen PR’lar docs-guard kontrolünden (.github/workflows/docs-guard.yml) geçemez. Gerçekten gerekiyorsa PR’a docs-sync etiketi eklenir.

update-docs skill’i ve Stop hook’u “docs/ klasörü” dediğinde docs/claude/ kastedilmez. Oradaki değişiklik her zaman pending notuyla yapılır.

Bir değişiklikte ikisi birlikte

Tipik bir issue’da (ör. Menü ekranını gerçek veriye bağlamak) aynı commit şunları içerir:

1. Kod değişikliği.
2. docs/architecture/screens.md ve docs/architecture/data-and-integration.md güncellemesi (updated alanı dahil).
3. docs/changelog.md’ye tek satır.
4. docs/claude/pending/SCRUM-<n>.md notu (hedef: data.md).