Belgeler / Kalite ve yönetişim

Gate ve Yönetişim Merkezi

Tek bir gate sözleşmeyi her commit, push ve pipeline'da uygular; Yönetişim Merkezi ise yaşam döngüsünün tamamını bir araya getirir.

Kalite sözleşmesi ekibin ne istediğini söyler. Gate ise bunu uygular. Git hook'larının, CI'ın, yuli-mcp gate komutunun ve ajan hook'larının aynı şekilde kullandığı, motora ait tek bir komuttur. Sonuç, onu kimin çağırdığına bağlı değildir.

Komut

agent-engine gate --project <raíz> --stage pre-commit|commit-msg|pre-push|ci \
  [--message-file <archivo>] [--base <revisión>] [--format text|json]

--project belirtilmezse geçerli klasör kullanılır. Git içermeyen bir klasör her zaman geçer.

Çıkış kodu Anlamı
0 Geçti.
1 Engellendi: bir denetim başarısız oldu.
2 Kullanım hatası.

Her aşama neyi denetler

Aşama Neyi karşılaştırır Denetimler
pre-commit Stage'deki değişiklikler Aşağıdakilerin tümü.
commit-msg Commit mesajı Yalnızca yapay zekâ atfı ve istisnalar.
pre-push @{upstream}'e (veya origin/HEAD'e) karşı Aşağıdakilerin tümü.
ci PR veya MR'ın hedef dalına (veya HEAD~1'e) karşı Aşağıdakilerin tümü.

Denetimler

Denetim Yuli'deki etiket Sonuç
Eklenen satırlardaki gizli bilgiler Gizli bilgiler Engeller. Tür ve satır bildirilir, değer asla bildirilmez.
Testlerdeki hileler Test bütünlüğü Profil hileleri engelliyorsa engeller; aksi halde uyarır.
Değişikliğin boyutu Değişiklik boyutu Katı uygulamada engeller; aksi halde uyarır.
Dokunulan korunan dosyalar Korunan yollar Katı uygulamada engeller; aksi halde uyarır.
İletilerde bir yapay zekâya atıf Yapay zeka atfı Bir yapay zekâya ait Co-Authored-By olmadığını denetler.
Süresi dolmuş istisnalar İstisnalar Uyarır. Asla engellemez.
Testi olmayan mevcut kod Güvenlik ağı Uyarır. Asla engellemez.

Testlerde hileye karşı koruma

İşi bitirme baskısı altındaki bir ajan, kodu düzeltmek yerine bir testi «düzeltebilir». Yuli bunu algılar.

Testlerde:

  • Silinen doğrulamalar (assertion) veya silinen testler.
  • Atlanan testler: @Disabled, @Ignore, .skip(, xit, #[ignore], pytest veya unittest skip'leri, t.Skip.
  • assertTrue(true) veya expect(true).toBe(true) gibi önemsiz doğrulamalar.
  • Testin geçmesi için değiştirilen beklenen değerler.
  • Bir test içinde her şeyi yakalayan catch.

Build ve CI'da:

  • Düşürülen asgari kapsam.
  • Build'de atlanan testler.
  • npm test || true gibi yok sayılan hatalar.
  • Boş bir betikle değiştirilen test betiği.
  • Devre dışı bırakılan kalite gate'i veya devre dışı bırakılan test görevi.

Güvenlik ağı

Mevcut kod dosyaları karakterizasyon veya birim testleri olmadan değişirse gate uyarır: değişiklik davranışı korumalıdır. Commit'i asla engellemez.

Git hook'larını kurma

Yönetişim Merkezi'nde Kapılar sekmesinde Hook'ları kur düğmesine basın.

  1. Yuli .githooks/pre-commit, .githooks/commit-msg ve .githooks/pre-push dosyalarını yazar.
  2. git config --local core.hooksPath .githooks ayarını yapar.

core.hooksPath zaten başka bir aracı (örneğin husky) gösteriyorsa veya Yuli'nin yazmadığı bir hook varsa Yuli hiçbir şey kurmaz. Motor kullanılamıyorsa hook uyarır ve geçişe izin verir: commit yapamaz halde kalmanıza asla yol açmaz.

Hook'ları kaldır yapılandırmayı kaldırır ve yalnızca Yuli'nin betiklerini siler.

CI'da

CI Oluştur ile üretilen pipeline'lar, agent-engine gate --stage ci çalıştıran «Sözleşme kapıları» adımını içerir. Böylece CI, yerel ekibinizle aynı kuralları uygular.

Yönetişim Merkezi

Sağ raydan (Daha fazla araç → Yönetişim Merkezi) ya da komut paletinden açın: Yönetişim Merkezi'ni aç. 10 sekmesi vardır.

Sekme İçeriği
Sözleşme Kritiklik, eşikler, korunan yollar, istisnalar, katmanlar, SLO, lisans politikası, bağımsız inceleyici, veri sınıflandırması, FinOps bütçeleri ve geçmiş.
Kapılar Bir aşama için gate'i çalıştırma, hook'ları kurma veya kaldırma ve CI kartı.
Hassas veriler Bilgisayardan çıkarken maskelenen değerler, kodda sınıflandırılmış alanlar ve Git geçmişindeki gizli bilgiler.
Analiz Gereksinimler (EARS kalıpları, belirsizlik, ISO 25010 özellikleri, Gherkin) ve sözlük.
Tasarım Kararlar (ADR), Tehditler (STRIDE), API'ler (OpenAPI), C4, SLO ve Eski sistemler.
Ölçüm Mimari uygunluk fonksiyonları, LCOM4, değişiklik bağımlılığı, bus factor, borç kaydı, twelve-factor ve feature flag'ler.
Testler Kararsız testler ve karantina, mutasyon, test türleri, yarış koşulları ve yük.
Tedarik zinciri Bağımlılıklar ve lisanslar, SBOM, IaC, kapsayıcılar, DAST, köken (SLSA, cosign), CODEOWNERS ve geçmiş.
Teslimat CI, release, rollback, kademeli dağıtım, runbook, post-mortem'ler, DORA, SPACE, build'ler ve FinOps.
Ajanlar Bağlam, İnceleme, Telemetri, Öğrenme, Benchmark ve Enjeksiyon.

Ürettiği belgeler

Belge Yol
ADR (mimari kararlar) docs/architecture/adr/
STRIDE tehdit modeli docs/architecture/threat-model.md
C4 diyagramları docs/architecture/c4.md
SBOM docs/reports/sbom.cdx.json ve docs/reports/sbom.spdx.json
Runbook docs/operations/runbook.md
Post-mortem'ler docs/operations/postmortems/

DORA

Teslimat sekmesi dört DORA metriğini hesaplar: dağıtım sıklığı, lead time, değişiklik hata oranı ve MTTR; Elit, Yüksek, Orta ve Düşük bantlarıyla. Kayıtlı dağıtımları veya CI'ı kullanır. Yuli üretimdeki bir APM'yi görmez.

Bağımsız inceleme

Değişikliği başka bir aileden bir model inceler. Değişikliği yazan modelle aynı aileden bir model asla kullanılmaz. Yapılandırılmış bir model yoksa bunu kullanılamaz olarak belirtir. Düzenlemeye tabi ve Güvenlik açısından kritik profillerinde zorunludur.

Tüm ajanlar için bağlam

Ajanlar → Bağlam bölümündeki «Tüm ajanlar için bağlam» kısmı, aynı kuralları her araç için yazar:

Hedef Dosya
Claude Code (CLAUDE.md) .claude/CLAUDE.md
AGENTS.md (Codex ve diğerleri) AGENTS.md
Kiro (.kiro/steering) .kiro/steering/yuli.md
Antigravity .agent/rules/yuli.md
Cursor (.cursor/rules) .cursor/rules/yuli.mdc
GitHub Copilot .github/copilot-instructions.md
Gemini (GEMINI.md) GEMINI.md

İçerik yönetilen bir bloğa yazılır; bloğun dışına yazdıklarınıza dokunulmaz. Varsayılan olarak dosyalar Git dışında kalır; Git'te sürümle ile etkinleştirin. Her hedef durumunu gösterir: Güncel, Eskimiş, Mevcut değil veya Elle düzenlenmiş.

Öğrenilen kurallar

Aynı bulgu 30 gün içinde en az 2 görevde 3 veya daha fazla kez göründüğünde .ai/rules/learned.md içinde bir kurala dönüşür. Bunu Ajanlar → Öğrenme bölümünde reddedebilirsiniz; yalnızca kanıtı iki katına çıkarsa yeniden önerilir.

Dürüst sınırlar

  • DAST (OWASP ZAP), kapsayıcı taraması (Trivy veya Grype) ve imzalama (cosign) yalnızca kuruluysa ve her zaman onayla çalışır. Eksiklerse Yuli bunu belirtir ve sonucu taklit etmez.
  • Önleyici kurallar ve IaC kuralları metin üzerindeki kalıplardır. Her bulgu, bir insanın doğrulayabilmesi için dosyası ve satırıyla birlikte gelir.