AI-diff incelemesi (/changes/ akışı)

İçerik yenilemesi, redesign veya büyük bir kopya tazelemesi sonrasında, eleştirmenlerin her değişiklik üstünde tek tek karar vermesini istersin — koca bir diff’i göz gezdirmek değil. PinAppAI AI-diff review akışı git geçmişini per-item bir review yüzeyine çevirir: Before/After kartlarıyla bir /changes/ sayfası üret, deploy et, bağlantıyı paylaş, karar ver.

Parçalar nasıl birleşiyor

git diff (son commit’ler)
   │
   │  AI prompt (Claude Code / Cursor / herhangi bir ajan)
   ▼
/changes/ HTML sayfası        ← üretilir, sitenle birlikte deploy edilir
   │
   │  /changes/ üzerindeki widget items_detail’i API’ye gönderir
   ▼
PinAppAI change_items’ı doldurur
   │
   │  Eleştirmen /changes/ veya herhangi bir kaynak sayfayı ziyaret eder
   ▼
   • /changes/ → her madde için Approve/Reject/Request-change barları + özet
   • kaynak sayfa → sayfa-içi review chip’i + karar paneli + sayfalar arası gezinme

1. /changes/ üret

Projeni app.pinappai.com’da aç, Snippet modal’ını aç ve AI diff prompt’unu kopyala düğmesine bas. Repo’na erişimi olan Claude Code, Cursor veya herhangi bir AI ajanına yapıştır.

Ajan son commit’leri okur, anlamlı her değişikliği özetler ve şu özelliklere sahip tek dosyalık self-contained bir /changes/ sayfası yazar:

• Her atomik değişiklik için bir <div class="pp-change-item"> wrapper’ı
• Her madde üzerinde data-pp-page-url (değişikliğin yaşadığı kaynak sayfa) ve data-pp-source-selector (öğeye giden benzersiz CSS seçici)
• Kırmızı/yeşil satırlarda BEFORE / AFTER metni
• Tüm CSS inline — deploy etmek için tek dosya, silmek için tek dosya

AI üretici kaynak dosyalarını asla değiştirmez. Prompt’unun temel kuralı şu: “kaynak markup’ı anlamak için okursun; düzenlemezsin.” /changes/ yazdığı tek artefakttır.

2. Deploy et + aç

/changes/’i diğer sayfalar gibi commit’le ve deploy et. Eleştirmenler https://siten.com/changes/’i ziyaret eder ve şunları görür:

• Bir başlık özeti: 20 / 249 (%8) · ✓ 11 · ✗ 5 · ↻ 4 · 229 bekleyen
• Her madde, Before/After + üç düğme barıyla render edilen bir kart olarak:
  • ✓ Onayla — AI’nın önerdiği yazımı kabul et
  • ✗ Reddet — alternatif metne taahhüt vermeden reddet
  • ↻ Değişiklik iste — istediğin yazımı yaz; bir sonraki AI iterasyonu o metni uygular
• Her madde başlığının yanında küçük siyah bir ↗ ikonu — kaynak sayfayı yeni sekmede sayfa-içi review paneli o maddeye odaklı şekilde açar

Kararlar PinAppAI sunucularında kalıcı olur ve eleştirmenin doğrulanmış e-postasına bağlanır. /changes/’i yeniden yükle, kararların hâlâ orada.

3. Asıl sayfada incele (sayfa-içi mod)

Bir eleştirmen, /changes/ maddelerinin hedef aldığı bir kaynak sayfayı (/pricing/, /tr/features/asset-management/, …) ziyaret ettiğinde, sağ altta bir chip belirir:

16 bu sayfada incelenecek değişiklik

Tıkla → sürüklenebilir bir alt panel açılır:

• Asıl render edilmiş öğe sayfa üstünde kırmızı çerçevelenir
• Şu anki madde için BEFORE / AFTER satırları
• Approve / Reject / Request-change düğmeleri (Request’te inline metin düzenleme)
• Tüm maddeler arasında gezmek için ◀ ▶ — sayfa sınırlarını da aşar: bu sayfanın son maddesinde Next basınca sonraki sayfanın ilk maddesine sorunsuzca geçer
• Mevcut sayfadaki konumunu proje toplamı üstünde gösteren 1/4 of 249 sayacı
• 249 rakamı, tüm kart görünümüne dönmek için /changes/’e altı çizili bir bağlantı

Kendi maddesi olmayan sayfalarda da 249 bu sitede incelenecek değişiklik chip’i görürsün — tıklayınca proje genelinde alfabetik olarak ilk bekleyen maddeye atlar.

4. Otomatik keşif (cold start)

Eleştirmenin ilk ziyareti bir kaynak sayfa ise (henüz hiç /changes/ ziyareti olmamışsa), widget kendi kendini bootstrap eder: aynı origin’den /changes/’i fetch eder, maddeleri parse eder ve arka planda API’ye POST eder. Sayfa yüklenmesini bitirdiğinde chip doğru sayıyla belirir. Manuel ısıtma adımı gerekmez.

/changes/ varsayılan olmayan bir yolda yaşıyorsa (örn. /tr/changes/), widget’a şununla söyle:

<script src="https://api.pinappai.com/widget.js"
        data-project="pk_..."
        data-changes-url="/tr/changes/" defer></script>

5. Kararları sonraki AI iterasyonuna teslim et

Eleştirmenler bitirdiğinde, sıraya alınmış kararları kaynak koda uygulamak için iki yolun var — ekibinin tercih ettiğini seç:

• MCP-native (önerilen): AI client’ında /pinappai:apply-decisions çalıştır. Ajan sıraya alınmış kararları getirir, dosyaya göre gruplar, her birini uygular (geri al’lar orijinale döner; değişiklik talepleri eleştirmenin literal yazımını uygular), iterasyon sınır marker’ını yazar ve commit’lemeden önce sorar (a/b/c/d seçeneği — bkz. /tr/docs/mcp/).
• Export markdown: admin’deki Approvals görünümünü aç ve Kararları AI için kopyala düğmesine bas. Claude Code’a veya MCP kurulu olmayan herhangi bir AI client’ına yapıştır; markdown self-contained ve aynı sonucu üretir.

Her iki yol da istediğin literal metni uygular — yorum-düzyazısını yorumlamaz.

Apply sonrası onaylama (iterasyon-döngüsü v2)

Değişiklikler canlıya çıkıp eleştirmenler her CR için karar verdikten sonra, admin Approvals sekmesinde uygulanmış her CR’ı görür — tüm iterasyonlar arasında düz bir liste, her CR kaynak iterasyonuyla etiketlenmiş. Bir CR üzerinde alacağın aksiyon, eleştirmenlerin söylediğine bağlıdır:

Eleştirmen sonucu	Admin seçenekleri
Tüm eleştirmenler onayladı	Onayla — CR’ı kapatır (closed_accepted).
Tüm eleştirmenler reddetti	Revert — CR’ı geçerli iterasyona geri gönderir; AI değişikliği geri alır. Veya Wontfix — revert olmadan kapatır.
Tüm eleştirmenler değişiklik istedi	Yeni değişiklik uygula — orijinali kapatır, eleştirmenin ifadesinden türetilmiş ardıl bir CR doğurur ve geçerli iterasyona yönlendirir. Veya Wontfix.
Karışık eleştirmen sesleri	Dördü de — Onayla / Revert / Yeni değişiklik uygula / Wontfix. İsteğe bağlı olarak hangi sesi takip ettiğini denetim günlüğüne kaydetmek için bir eleştirmen atfedebilirsin (cited_reviewer_id).

Durum makinesi özeti: accept / apply_new (orijinal üzerinde) / wontfix terminaldir (CR’lar Closed’da görünür). revert aynı CR’ı tutar; apply_new bir ardıl yaratır. İkisi de açık iterasyona otomatik bağlanır (yoksa yeni bir tane açar), bir sonraki AI çalıştırması için Current iteration sekmesinde görünürler.

Onaylamanın üç yolu:

• MCP: pinappai_acknowledge_change_request({ project, cr_id, outcome, cited_reviewer_id?, note? })
• İterasyon-öncelikli dashboard (app.pinappai.com/dashboard-v2, workspace ayarlarından opt-in): CR-başına koşullu aksiyon düğmeleri + “Onaylanan tümünü onayla (N)” toplu eylemi.
• Eski admin dashboard’u: mevcut admin status PATCH hâlâ çalışır (done → accept; wontfix → terminal); Phase 2 dual-writes eşleşen olayı otomatik yayınlar.

Tam durum makinesi + coverage modeli için bkz. /tr/docs/iteration-loop/.

5.5. İterasyon sınır marker’ı

Her apply çalışması (ister apply-decisions ister fix-changes) çalışmanın ISO zaman damgasıyla .pinappai/last-applied.json’u yazar:

{
  "last_applied_at": "2026-05-06T21:05:00Z",
  "bundle_summary": "applied 8 decisions (3 rollbacks, 5 modifies)"
}

Bir sonraki /changes/ yeniden-üretiminde (ister /pinappai:generate-changes-page ile ister admin’in AI-diff prompt’unu yeniden çalıştırarak), generator bu marker’ı okur ve diff’i “git log —since=<o zaman damgası>” ile kapsamlandırır. Eleştirmenler sadece son uygulamadan beri sürüklenmiş içeriği görür — projenin başlangıcından bu yana biriken sürüklenmenin tamamını değil.

.pinappai/last-applied.json’u her apply’dan kaynak değişiklikleriyle birlikte commit’le. Marker dosyası, kaynağa-uygulayan her slash komutunun sonundaki “Etkilenen dosyalar” listesinde. Ayrı bir commit’te (veya daha kötüsü, commit’lenmemiş) kalırsa, bir sonraki /changes/ regen’inin diff aralığı non-deterministic olur.

.pinappai/context.json (proje-şekli önbelleği) yanında yaşar. Her ikisi de küçücüktür — commit’le.

Production’a hazırlık

Yenilemeyi production’a göndermeye hazır olduğunda, /changes/ ve tüm review markup’ının müşteri tarafına çıkan build’den çıkmasını istersin. İki yol:

• MCP-native: AI client’ında /pinappai:remove çalıştır. Ajan widget script tag’ini kaldırır, /changes/’i siler, opsiyonel yardımcıları temizler, dört git grep doğrulama komutu çalıştırır ve commit’lemeden önce sorar.
• Export markdown: admin’deki Snippet modal’ını aç ve Remove prompt’unu AI için kopyala düğmesine bas. Aynı sonuç.

Her iki yol da .pinappai/ klasörünü tasarım gereği korur — denetim izin ve proje-şekli önbelleğin kaldırmadan sağ çıkar, böylece daha sonra yeniden kurarken (veya bu durumdan branch ayırırken) aynı temele inersin. .pinappai/’i kaldırmak ayrı, açık bir onay adımıdır.