Yerleşik İlkeler - FailproofAI

failproofai, ortak agent başarısızlık modlarını yakalayan 30 yerleşik ilke ile birlikte gelir. Her ilke belirli bir hook olay türü ve araç adında tetiklenir. Dokuz ilke, kod yazmadan davranışlarını ayarlamanıza izin veren parametreleri kabul eder. Dört iş akışı ilkesi, Claude’un durdurmadan önce commit → push → PR → CI işlem hattını uygular.

Genel Bakış

İlkeler kategorilere ayrılmıştır:

Kategori	İlkeler	Hook türü
Tehlikeli komutlar	block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands	PreToolUse
Sırlar (sanitizers)	sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens	PostToolUse
Ortam	block-env-files, protect-env-vars	PreToolUse
Dosya erişimi	block-read-outside-cwd, block-secrets-write	PreToolUse
Git	block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged	PreToolUse
Veritabanı	warn-destructive-sql, warn-schema-alteration	PreToolUse
Uyarılar	warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install	PreToolUse
İş akışı	require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop	Stop

block- — ajanı ilerlemekten durdur.
warn- — ajanı kendini düzeltmesi için ek bağlam sağla.
sanitize- — araç çıktısından gizli verileri temizle.
require- — koşullar karşılanana kadar Stop olayını engelle.

Her ilke policyParams içinde isteğe bağlı bir hint alanını destekler. İpucu, deny veya instruct mesajına eklenir ve Claude tarafından görülür; ilke kodunu değiştirmeden işlem yapılabilir rehberlik sağlar. Yerleşik, özel ve kural tabanlı ilkeler ile çalışır. Ayrıntılar için Konfigürasyon → hint bölümüne bakınız.

Tehlikeli komutlar

Ajanları geri alması zor olan veya ana sistemi hasar görebilecek işlemleri çalıştırmaktan engelleyin.

`block-sudo`

Olay: PreToolUse (Bash)
Varsayılan: Herhangi bir sudo komutunu reddeder. sudo anahtar kelimesini içeren çağrıları engeller. Desen eşleştirmesi, shell operatör enjeksiyonu yoluyla bypass’ı önlemek için ham dizgiye değil, ayrıştırılmış komut jetonlarında yapılır. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`allowPatterns`	`string[]`	`[]`	İzin verilen tam komut önekleri. Her giriş ayrıştırılmış argv jetonlarına karşı eşleştirilir.

Örnek:

{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}

Bu yapılandırma ile sudo systemctl status nginx izin verilir, ancak sudo rm /etc/hosts reddedilir.

Desenler ayrıştırılmış jetonlara karşı eşleştirilir, ham komut dizgesine değil. Bu, eklenen shell operatörleri yoluyla bypass’ı önler (örn. sudo systemctl status x; rm -rf / öğesi sudo systemctl status * ile eşleşmez).

`block-rm-rf`

Olay: PreToolUse (Bash)
Varsayılan: rm -rf, rm -fr ve benzer özyinelemeli silme biçimlerini reddeder. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`allowPaths`	`string[]`	`[]`	Güvenli bir şekilde özyinelemeli olarak silinebilecek yollar (ör. `/tmp`).

Örnek:

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}

`block-curl-pipe-sh`

Olay: PreToolUse (Bash)
Varsayılan: curl <url> | bash, curl <url> | sh, wget <url> | bash ve benzer desenleri reddeder. Parametre yok.

`block-failproofai-commands`

Olay: PreToolUse (Bash)
Varsayılan: failproofai’ın kendisini kaldıracak veya devre dışı bırakacak komutları reddeder (ör. npm uninstall failproofai, failproofai policies --uninstall). Parametre yok.

Sırlar (sanitizers)

Ajanları kimlik bilgilerini bağlamlarına veya çıktılarına sızmaktan engelleyin. Sanitizer ilkeleri PostToolUse olaylarında tetiklenir. Claude bir Bash komutunu çalıştırdığında, bir dosya okuduğunda veya herhangi bir aracı çağırdığında, bu ilkeler çıktıyı Claude’a geri gelmeden önce inceler. Gizli bir desen algılanırsa, ilke çıktının geri geçirilmesini önleyen bir deny kararı döndürür.

`sanitize-jwt`

Olay: PostToolUse (tüm araçlar)
Varsayılan: JWT jetonlarını (nokta ile ayrılan üç base64url segmenti) gizler. Parametre yok.

`sanitize-api-keys`

Olay: PostToolUse (tüm araçlar)
Varsayılan: Yaygın API anahtarı biçimlerini gizler: Anthropic (sk-ant-), OpenAI (sk-), GitHub PAT’ları (ghp_), AWS erişim anahtarları (AKIA), Stripe anahtarları (sk_live_, sk_test_) ve Google API anahtarları (AIza). Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`additionalPatterns`	`{ regex: string; label: string }[]`	`[]`	Gizli olarak kabul edilecek ek regex desenleri.

Örnek:

{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}

`sanitize-connection-strings`

Olay: PostToolUse (tüm araçlar)
Varsayılan: Gömülü kimlik bilgilerini içeren veritabanı bağlantı dizelerini gizler (ör. postgresql://user:password@host/db). Parametre yok.

`sanitize-private-key-content`

Olay: PostToolUse (tüm araçlar)
Varsayılan: PEM bloklarını gizler (-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY-----, vb.). Parametre yok.

`sanitize-bearer-tokens`

Olay: PostToolUse (tüm araçlar)
Varsayılan: Authorization: Bearer <token> başlıklarını gizler; burada jeton 20 veya daha fazla karakterdir. Parametre yok.

Ortam

Gizli ortam yapılandırmasını ajanlar tarafından okunmasından veya maruz kalmasından koruyun.

`block-env-files`

Olay: PreToolUse (Bash, Read)
Varsayılan: .env dosyalarını cat .env aracılığıyla okumayı, dosya yolu olarak .env olan Read araç çağrılarını, vb. reddeder. .envrc veya diğer ortam ile ilgili dosyaları engellemiyor; yalnızca tam olarak .env adlı dosyaları engeller. Parametre yok.

`protect-env-vars`

Olay: PreToolUse (Bash)
Varsayılan: Ortam değişkenlerini yazdıracak komutları reddeder: printenv, env, echo $VAR. Parametre yok.

Dosya erişimi

Ajanları proje sınırları içinde çalışmakta ve gizli dosyalarından uzak tutun.

`block-read-outside-cwd`

Olay: PreToolUse (Read, Bash)
Varsayılan: Mevcut çalışma dizini (proje kökü) dışındaki dosyaları okumayı reddeder. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`allowPaths`	`string[]`	`[]`	Cwd dışında olsa bile izin verilen mutlak yol önekleri.

Örnek:

{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}

`block-secrets-write`

Olay: PreToolUse (Write, Edit)
Varsayılan: Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazmaları reddeder: id_rsa, id_ed25519, *.key, *.pem, *.p12, *.pfx. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`additionalPatterns`	`string[]`	`[]`	Engellecek ek dosya adı desenleri (glob stili).

Örnek:

{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}

Git

Geri alması zor olan yanlışlıkla push’ları, force-push’ları ve dal hatalarını engelleyin.

`block-push-master`

Olay: PreToolUse (Bash)
Varsayılan: git push origin main ve git push origin master komutlarını reddeder. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`protectedBranches`	`string[]`	`["main", "master"]`	Doğrudan push yapılamayan dal adları.

Örnek:

{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}

Tüm dallara push yapılmasına izin vermek için (enabledPolicies içinden kaldırmadan bu ilkeyi etkili bir şekilde devre dışı bırakmak için), protectedBranches: [] olarak ayarlayın.

`block-work-on-main`

Olay: PreToolUse (Bash)
Varsayılan: main veya master dallarını doğrudan checkout yapmayı reddeder. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`protectedBranches`	`string[]`	`["main", "master"]`	Doğrudan checkout yapılamayan dal adları.

`block-force-push`

Olay: PreToolUse (Bash)
Varsayılan: git push --force ve git push -f komutlarını reddeder. İlke özgü parametre yok. Alternatifler önerisi için çapraz kesim hint kullanın:

{
  "policyParams": {
    "block-force-push": {
      "hint": "Geçerli HEAD'inizden yeni bir dal oluşturun (ör. `git checkout -b <new-branch>`) ve bunu push edin."
    }
  }
}

`warn-git-amend`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u git commit --amend çalıştırırken dikkatli ilerleme talimatı verir. Komutu engellemiyor. Parametre yok.

`warn-git-stash-drop`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u git stash drop çalıştırmadan önce onay alması talimatı verir. Komutu engellemiyor. Parametre yok.

`warn-all-files-staged`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u git add -A veya git add . çalıştırdığında neyi staging yaptığını gözden geçirme talimatı verir. Komutu engellemiyor. Parametre yok.

Veritabanı

Veritabanınıza karşı yürütülmeden önce yıkıcı SQL işlemlerini yakalayın.

`warn-destructive-sql`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u DROP TABLE, DROP DATABASE veya WHERE yan tümcesi olmayan DELETE içeren SQL çalıştırmadan önce onay alması talimatı verir. Parametre yok.

`warn-schema-alteration`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u ALTER TABLE ifadeleri çalıştırmadan önce onay alması talimatı verir. Parametre yok.

Uyarılar

Ajanları potansiyel olarak riskli ancak yıkıcı olmayan işlemlerden önce ek bağlam sağlayın.

`warn-large-file-write`

Olay: PreToolUse (Write)
Varsayılan: Claude’u 1024 KB’tan büyük dosyaları yazmadan önce onay alması talimatı verir. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`thresholdKb`	`number`	`1024`	Uyarı verilen dosya boyutu eşiği (kilobayt).

Örnek:

{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}

Hook işleyicisi yüklerde 1 MB stdin sınırı uygular. Bu ilkeyi küçük içerikle test etmek için thresholdKb öğesini 1024’ün altında bir değere ayarlayın.

`warn-package-publish`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u npm publish çalıştırmadan önce onay alması talimatı verir. Parametre yok.

`warn-background-process`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u nohup, &, disown veya screen aracılığıyla arka plan işlemleri başlatırken dikkatli olması talimatı verir. Parametre yok.

`warn-global-package-install`

Olay: PreToolUse (Bash)
Varsayılan: Claude’u npm install -g, yarn global add veya sanal ortam olmadan pip install çalıştırmadan önce onay alması talimatı verir. Parametre yok.

AI davranışı

Ajanların takılı kaldığı veya beklenmedik şekilde davrandığı zamanları algılayın.

`warn-repeated-tool-calls`

Olay: PreToolUse (tüm araçlar)
Varsayılan: Aynı araç 3 veya daha fazla kez aynı parametrelerle çağrıldığında Claude’u yeniden düşünmesi talimatı verir; bu durum ajanın bir döngüde takılı olduğunun yaygın bir işaretidir. Parametre yok.

İş akışı

Disiplinli bir oturum sonu iş akışını uygulayın. Bu ilkeler Stop olayında tetiklenir ve her koşul karşılanana kadar Claude’u durdurmaktan engeller. Doğal bir bağımlılık zincirini takip eder: commit → push → PR → CI. Bir ilke reddederse, zincirdeki sonraki ilkeler atlanır (deny kısa devre yapar). Tüm iş akışı ilkeleri başarısızlık açılır: gerekli araç kullanılabilir değilse (ör. gh kurulmamış, git remote yoksa), ilke kontrol neden atlandığını açıklayan bilgilendirici bir mesaj ile izin verir.

`require-commit-before-stop`

Olay: Stop
Varsayılan: Değiştirilmemiş değişiklikler varken (değiştirilmiş, staged veya izlenmeyen dosyalar) durdurmayı reddeder. Çalışma dizini temiz olduğunda bilgilendirici bir mesaj döndürür. Parametre yok.

`require-push-before-stop`

Olay: Stop
Varsayılan: Push edilmemiş commit’ler olduğunda veya geçerli dal izleme dalı olmadığında durdurmayı reddeder. Gerekirse tracking dalı oluşturmak için git push -u önerir. Yapılandırılmış remote yoksa açık başarısız olur. Parametreler:

Parametre	Tür	Varsayılan	Açıklama
`remote`	`string`	`"origin"`	Push yapılacak remote adı.

Örnek:

{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}

`require-pr-before-stop`

Olay: Stop
Varsayılan: Geçerli dal için pull request yoksa veya mevcut PR kapalı/merge edilmişse durdurmayı reddeder. Claude’u gh pr create ile PR oluşturması talimatı verir. Parametre yok.

Bu ilke GitHub CLI (gh) kurulu ve kimliği doğrulanmış olmasını gerektirir. Pull request’lere okuma erişimi için repo kapsamına sahip kişisel erişim jetonuyla gh auth login çalıştırın. gh kurulu veya kimliği doğrulanmamışsa, ilke açık başarısız olur ve nedeni Claude’a bildirir.

`require-ci-green-before-stop`

Olay: Stop
Varsayılan: Geçerli dal üzerinde CI kontrolleri başarısız veya hala çalışıyorsa durdurmayı reddeder. Hem GitHub Actions iş akışı çalıştırmaları hem de üçüncü taraf bot kontrolleri (ör. CodeRabbit, SonarCloud, Codecov) kontrol eder. skipped sonuçlarını başarı olarak kabul eder. Tüm kontroller geçtiğinde bilgilendirici bir mesaj döndürür. Parametre yok.

Bu ilke GitHub CLI (gh) kurulu ve kimliği doğrulanmış olmasını gerektirir. İş akışı çalıştırmalarına okuma erişimi ve Checks API’ye erişim için repo kapsamına sahip kişisel erişim jetonuyla gh auth login çalıştırın. gh kurulu veya kimliği doğrulanmamışsa, ilke açık başarısız olur ve nedeni Claude’a bildirir.

Bireysel ilkeleri devre dışı bırakma

Yapılandırmanızda enabledPolicies içinden belirli bir ilkeyi kaldırın veya panonun Policies sekmesinde kapatın.

{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}

enabledPolicies içinde listelenmemiş ilkeler çalışmaz; hatta policyParams girdileri olsa bile.

Başlangıç

Temel Kavramlar

CLI

Araçlar

Gelişmiş

​Genel Bakış

​Tehlikeli komutlar

​block-sudo

​block-rm-rf

​block-curl-pipe-sh

​block-failproofai-commands

​Sırlar (sanitizers)

​sanitize-jwt

​sanitize-api-keys

​sanitize-connection-strings

​sanitize-private-key-content

​sanitize-bearer-tokens

​Ortam

​block-env-files

​protect-env-vars

​Dosya erişimi

​block-read-outside-cwd

​block-secrets-write

​Git

​block-push-master

​block-work-on-main

​block-force-push

​warn-git-amend

​warn-git-stash-drop

​warn-all-files-staged

​Veritabanı

​warn-destructive-sql

​warn-schema-alteration

​Uyarılar

​warn-large-file-write

​warn-package-publish

​warn-background-process

​warn-global-package-install

​AI davranışı

​warn-repeated-tool-calls

​İş akışı

​require-commit-before-stop

​require-push-before-stop

​require-pr-before-stop

​require-ci-green-before-stop

​Bireysel ilkeleri devre dışı bırakma

Genel Bakış

Tehlikeli komutlar

`block-sudo`

`block-rm-rf`

`block-curl-pipe-sh`

`block-failproofai-commands`

Sırlar (sanitizers)

`sanitize-jwt`

`sanitize-api-keys`

`sanitize-connection-strings`

`sanitize-private-key-content`

`sanitize-bearer-tokens`

Ortam

`block-env-files`

`protect-env-vars`

Dosya erişimi

`block-read-outside-cwd`

`block-secrets-write`

Git

`block-push-master`

`block-work-on-main`

`block-force-push`

`warn-git-amend`

`warn-git-stash-drop`

`warn-all-files-staged`

Veritabanı

`warn-destructive-sql`

`warn-schema-alteration`

Uyarılar

`warn-large-file-write`

`warn-package-publish`

`warn-background-process`

`warn-global-package-install`

AI davranışı

`warn-repeated-tool-calls`

İş akışı

`require-commit-before-stop`

`require-push-before-stop`

`require-pr-before-stop`

`require-ci-green-before-stop`

Bireysel ilkeleri devre dışı bırakma