Belgeler / Kalite ve yönetişim

Kalite sözleşmesi

Kalite kuralları prompt'ta değil, deponun sürümlenen bir dosyasında durur ve insanlar ile ajanlar için aynı şekilde geçerlidir.

Kalite sözleşmesi, projenizdeki .ai/contract.json dosyasıdır. Ekibin ne kadar titizlik istediğini tanımlar: ölçüm eşikleri, kapsam, karmaşıklık, değişikliklerin boyutu, korunan yollar ve istisnalar.

Sözleşmeyi motorun gate'i, Git hook'ları, CI ve ajanlar uygular. Sonuç, kodu kimin yazdığına bağlı değildir: bir insan, Yuli, Claude Code, Codex, Kiro veya Antigravity.

Dosya yoksa veya geçerli değilse Yuli varsayılan değerleri kullanır (kritiklik İş). Her alan isteğe bağlıdır; bu nedenle kısmi bir sözleşme de çalışır.

Nerede düzenlenir

Yönetişim Merkezi'ni açın (sağ ray → Daha fazla araç ya da komut paletinde Yönetişim Merkezi'ni aç) ve Sözleşme sekmesine girin.

Kaydet ve imzala ile kaydettiğinizde Yuli değişikliği git config user.name değerinizle kaydeder. Tüm değişiklikleri Sözleşme geçmişi içinde görebilirsiniz.

Kritiklik

Kritiklik, eşiklerden oluşan eksiksiz bir profil seçer. Dört düzey vardır:

Dosyadaki değer Yuli'deki etiket Ne zaman kullanılır
low Düşük Prototipler, dahili araçlar, deneyler.
business İş İş uygulamaları. Varsayılan değerdir.
regulated Düzenlemeye tabi Denetime veya mevzuata tabi sistemler.
safety Güvenlik açısından kritik Bir hatanın ağır sonuçları olduğu yazılımlar.

Profiller

Eşik Düşük İş Düzenlemeye tabi Güvenlik açısından kritik
Kabul puanı 80 90 92 95
Ölçüm turları 2 3 4 5
Asgari kapsam %50 %70 %80 %90
En fazla bilişsel karmaşıklık 20 15 15 10
En fazla döngüsel karmaşıklık 15 10 10 8
Asgari mutasyon %0 %0 %60 %75
Değişiklik başına dosya 60 40 25 15
Değişiklik başına satır 2000 1000 600 400
Bağımsız inceleme Hayır Hayır Evet Evet
Testlerde hileyi engelle Hayır Evet Evet Evet
Katı uygulama Hayır Hayır Evet Evet

Belirli bir eşiği gates içinde geçersiz kılabilirsiniz. Yalnızca o alan değişir; geri kalanı profilden gelmeye devam eder. Testlerde hileyi engelle ve Katı uygulama yalnızca kritikliğe bağlıdır ve geçersiz kılınamaz.

Sözleşmedeki kabul puanı ve tur sayısı, Ölçüm aşamasının yerel ayarlarının yerini alır.

Dosya yapısı

{
  "schemaVersion": 1,
  "criticality": "business",
  "gates": { "minCoverage": 75, "maxCyclomatic": null },
  "changeLimits": { "maxFiles": 40, "maxLines": 1000 },
  "protectedPaths": ["db/migrations/**"],
  "waivers": []
}
Alan Neyi tanımlar
criticality low, business, regulated veya safety.
gates acceptanceScore, maxMeasureRounds, minCoverage, maxCognitive, maxCyclomatic, requireIndependentReview, minMutationScore. null profildeki değeri alır.
changeLimits Değişiklik başına maxFiles ve maxLines.
protectedPaths Varsayılan olarak korunanlara eklenen ek glob'lar.
waivers Süresi olan istisnalar.
architecture Katmanlar (name, paths, mayDependOn içeren layers) ve forbidCycles.
slos Hizmet hedefleri: latencyP95Ms, availability veya errorRate.
licensePolicy SPDX'e veya strong-copyleft gibi bir aileye göre izin verilen (allow) ve yasaklanan (deny) lisanslar.
reviewer Bağımsız inceleyici: requireOtherFamily, provider, model.
dataClassification Düzeyleriyle birlikte veri kalıpları: public, internal, confidential veya restricted.
finops Servis başına aylık bütçe ve sorumlusu.

Değişiklik sınırları

Bir değişikliğin boyutu git diff --numstat ile ölçülür. Kilit dosyaları (package-lock.json, yarn.lock, Cargo.lock, go.sum ve benzerleri) dosya olarak sayılır, ancak satırları sayılmaz.

Sınırın aşılması katı uygulamada (Düzenlemeye tabi ve Güvenlik açısından kritik) engeller. Diğer profillerde bir uyarıdır.

Korunan yollar

Bir ajan, istense bile bu dosyaları düzenleyemez:

  • .ai/contract.json, .ai/quality.json ve .ai/state/**
  • .claude/settings.json ve .claude/settings.local.json
  • .githooks/**
  • .github/workflows/**, .gitlab-ci.yml ve Jenkinsfile
  • CODEOWNERS ve .github/CODEOWNERS

Karşılaştırma büyük/küçük harf duyarsızdır. Kendi yollarınızı protectedPaths içine ekleyin. Yuli'den kaydedilen bir sözleşme değişikliği denetim kaydına girer ve onaylanmış sayılır.

İstisnalar (waivers)

Bir istisna, bir kuralın geçici ve gerekçeli olarak atlanmasına izin verir.

Alan İçerik
id İstisnanın tanımlayıcısı.
rule İstisna tutulan kural: secrets, protectedPaths, testIntegrity, belirli bir hile türü veya *.
path Uygulandığı glob. Boş, herhangi bir yol anlamına gelir.
reason Gerekçe.
approvedBy Onaylayan kişi.
expires Bitiş tarihi, AAAA-MM-DD.
ticket İsteğe bağlı başvuru.

Bir istisna expires gününe kadar (o gün dahil) geçerlidir. Eksik veya hatalı yazılmış bir tarih süresi dolmuş sayılır. Süre dolduğunda kural yeniden geçerli olur ve gate bunu bildirir.

Arayüzde her istisna durumunu gösterir: Geçerli, Yakında bitiyor, Süresi doldu veya Geçersiz tarih.

testIntegrity, testlerdeki tüm hile tespitlerini aynı anda istisna tutar. Dar bir yol ve yakın bir tarihle kullanın.

Denetim

Her kayıt, .ai/state/contract-audit.jsonl dosyasına tarih, yazar, SHA-256 özeti ve bir özet içeren bir satır ekler (örneğin «criticality business→regulated; waivers +1»).

Yazar her zaman bir insandır: belirtilen ad veya git config user.name değeriniz. «Yuli» ve «Yuli Code» yazar olarak reddedilir.

Sonraki adım