> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Özel ilkeler > Aracılarınıza özgü hataları önlemek için JavaScript veya TypeScript ilkeleri yazın, test edin ve dağıtın. Özel ilkeler, izlemeleriniz veya denetimlerinizden bir hata desenini, bir ajan çalışırken çalışan bir karara dönüştürür. Bir ilke bir işleme izin verebilir, ajanı rehberlik eder veya başka bir olaya neden olmadan önce işlemi reddedebilir. Davranış araçlarınız, yollarınız, komutlarınız, ortamlarınız veya işletme kurallarınıza bağlı olduğunda özel bir ilke kullanın. Mevcut bir kontrolü yeniden oluşturmamak için önce [yerleşik ilke kataloğunu](/tr/policies/builtin-catalog) kontrol edin. ## Özel bir ilke yazın 1. **Admin → policy editor** sayfasına gidin, **New policy** seçin ve önlemek istediğiniz hatayı açıklayın. 2. İlke kaynağını ekleyin, ardından editörde beklenen eşleşmeleri ve güvenli eşleşmeyenleri test edin. Her doğrulama hatasını çözün. 3. Taslağı kaydedin ve **Publish version** seçerek değişmez bir sürüm oluşturun. 4. **Admin → enforcement** sayfasına gidin, sürümü bir test makinesine **observe** modunda dağıtın ve **Observe → policy** altında kararlarını doğruladıktan sonra uygulamaya geçin. Özel bir ilke yazıp yayımlamak için kullanılan ilke editörü. 1. `.failproofai/policies/checkout-policies.ts` oluşturun. Dosya adı `policies.js`, `policies.mjs` veya `policies.ts` ile bitmelidir. 2. `customPolicies.add()` ile bir veya daha fazla ilke kaydedin. 3. Dosyayı `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project` ile doğrulayın ve kurun. 4. Eşleşen bir işlem ve bir güvenli işlem tetikleyin. `failproofai policies` çalıştırın, ardından **Observe → policy** altında atfedilen kararları inceleyin. ## Dar bir kuralla başlayın Bu ilke, yalnızca komut production'u hedeflediğinde yıkıcı Kubernetes komutlarını engeller. Bu tam hata modunun dışındaki her şey `allow()` döndürür. ```ts theme={null} import { customPolicies, allow, deny } from "failproofai"; const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i; const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i; customPolicies.add({ name: "block-destructive-production-kubectl", description: "Block destructive Kubernetes commands against production", match: { events: ["PreToolUse"] }, fn: async ({ toolName, toolInput }) => { if (toolName !== "Bash") return allow(); const command = String(toolInput?.command ?? ""); if (!DESTRUCTIVE_KUBECTL.test(command)) return allow(); if (!PRODUCTION_TARGET.test(command)) return allow(); return deny( "Destructive production Kubernetes commands require the approved deployment workflow.", ); }, }); ``` İyi ilkeler bir cümleyle açıklanacak kadar dar olmalıdır. Gözlemlenebilir işlemi eşleştirin—ajanın sahip olmasını umduğunuz niyeti değil—ve kural uygulanmadığı anda `allow()` döndürün. ## Bir karar seçin | Yardımcı | Sonuç | Şu zaman kullanın | | ------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `allow(reason?)` | İşlem devam eder. | İlke uygulanmaz veya işlem güvenlidir. | | `instruct(reason)` | İşlem, sistemin desteklediği yerde rehberlik ile devam eder. | Ajanı uygulamayı zorlamamadan daha iyi bir yaklaşıma yönlendirmek istediğinizde. | | `deny(reason)` | İşlem, olay ve sistem engellemeyi desteklediğinde engellenir. | İşlem ilerlememeli. | Ajanın iyileşmesi gereken nedenini yazın. Neyin algılandığını ve bunun yerine ne yapması gerektiğini açıklayın. Bir güvenlik sınırı için `instruct()` kullanmayın. Rehberlik sunumu ajan sistemine göre değişir. İşlem engellenmeli olduğunda `deny()` kullanın. ## İlke nesnesi ```ts theme={null} customPolicies.add({ name: "policy-name", description: "What this policy prevents", match: { events: ["PreToolUse"] }, fn: async (ctx) => allow(), }); ``` | Alan | Gerekli | Açıklama | | -------------- | ------- | ------------------------------------------------------------------------------------- | | `name` | Evet | İlkenin kararlı tanımlayıcısı. Dosyalar arasında adları benzersiz tutun. | | `description` | Hayır | İlke listelemeleri ve kararlarda gösterilen insan tarafından okunabilir amaç. | | `match.events` | Hayır | İlkeyi çağıran olay türleri. `match` atlanırsa her kullanılabilir olay için çağrılır. | | `fn` | Evet | `allow`, `instruct` veya `deny` sonucu döndüren senkron veya asenkron işlev. | Araçları `fn` içinde filtreleyin. `match.toolNames` genel özel ilke türünün parçası değildir. ## İlke bağlamı Her ilke bir `PolicyContext` alır. | Alan | Tür | İçerdikleri | | ----------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- | | `eventType` | `HookEventType` | Şu anda değerlendirilen normalleştirilmiş olay. | | `toolName` | `string \| undefined` | `Bash`, `Read`, `Write` veya `Edit` gibi kanonik araç adı. | | `toolInput` | `Record \| undefined` | Geçerli araç çağrısının kanonik girdisi. | | `payload` | `Record` | Tam normalleştirilmiş olay yükü. | | `session` | `SessionMetadata \| undefined` | Oturum kimliği, çalışma dizini, transcript yolu, izin modu ve uygun olduğunda sistem meta verileri. | | `cli` | `string \| undefined` | Kaynak ajan sistemi, örneğin `claude`, `codex` veya `cursor`. | | `params` | `Record` | Yerleşik ilke parametreleri. Özel ilkeler şu anda boş bir nesne alırlar. | Her isteğe bağlı değeri gerçekten isteğe bağlı olarak görün. Ajan sürümleri ve olay türleri aynı alanları sağlamaz. ### Yaygın araç girdileri Failproof AI, bir ilkenin genellikle tek bir giriş şekli kullanabilmesi için desteklenen sistemler arasında yaygın araçları normalleştirir. | Araç | Yaygın alanlar | | ------- | --------------------------------------- | | `Bash` | `command` | | `Read` | `file_path` | | `Write` | `file_path`, `content` | | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | Araç giriş değerleri `unknown` olarak yazıldığından savunmacı dönüştürme kullanın: ```ts theme={null} const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` ## Olayı seçin | Olay | Ne zaman çalışır | Tipik kullanım | | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `PreToolUse` | Bir araç yürütülmeden önce. | Komutları, yazmaları, okumaları ve harici işlemleri engelleyin veya yönlendirin. | | `PostToolUse` | Bir araç döndükten sonra. | Sonuçları ajanın ulaşmasından önce inceleyin. Bir reddetme tüm sonucu engeller; seçili alanları düzenlemez. | | `PermissionRequest` | Ajan izin istediğinde. | Kuruluşa özgü izin kurallarını uygulayın. | | `UserPromptSubmit` | Gönderilen bir istem devam etmeden önce. | Yasaklı talimatları reddedin veya iş akışı rehberliği ekleyin. | | `Stop` | Ajan bitirmeyi denediğinde. | Yerel doğrulama adımı gibi erişilebilir bir tamamlama koşulu gerektirin. | | `SubagentStop` | Bir alt ajan bitirmeyi denediğinde. | Üst ajanına dönmeden önce devredilen işi kapılandırın. | | `SessionStart` / `SessionEnd` | Oturum sınırlarında. | Oturum düzeyinde durumu kaydedin veya kontrol edin. | Olay kullanılabilirliği ve engelleme davranışı ajan sistemine bağlıdır. Karma bir filo arasında bir olaya güvenmeden önce [Ajan sistemleri](/tr/reference/harnesses) bölümüne bakın. `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, `UserPromptExpansion`, `PostToolBatch` ve `Setup`. ## Yaygın ilke düzenlerini yazın ### Korunan yollara yazmaları engelle ```ts theme={null} import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "block-generated-file-edits", description: "Require generated files to be changed through their generator", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const filePath = String(ctx.toolInput?.file_path ?? ""); if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow(); return deny("Edit the source and run the generator instead of changing generated output."); }, }); ``` ### Zorunlu olmayan rehberlik verin ```ts theme={null} import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "prefer-reviewed-deploy-command", description: "Guide agents toward the reviewed deployment wrapper", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const command = String(ctx.toolInput?.command ?? ""); if (!/^kubectl\s+apply\b/.test(command.trim())) return allow(); return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly."); }, }); ``` ### Oturum tamamlamasını kapılandırın ```ts theme={null} import { execFileSync } from "node:child_process"; import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "require-clean-typecheck", description: "Require the project typecheck to pass before the agent finishes", match: { events: ["Stop"] }, fn: async (ctx) => { const cwd = ctx.session?.cwd; if (!cwd) return allow(); try { execFileSync("bunx", ["tsc", "--noEmit"], { cwd, stdio: "ignore", timeout: 8_000, }); return allow(); } catch { return deny("Fix the typecheck errors before finishing the task."); } }, }); ``` Reddedilen `Stop` olayı ajanın yeniden denemesini sağlayabilir. Yalnızca ajanın geçerli ortamda karşılayabileceği bir koşulla kapılandırın ve her alt işlemi veya ağ çağrısını sınırlandırın. ## İlke dosyalarını yükleyin ### Kural dosyaları Kural dosyaları otomatik olarak yüklenir: ```text theme={null} /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` * Proje ve kullanıcı ilke dizinleri her ikisi de yüklenir. * Dosyalar her dizin içinde alfabetik olarak yüklenir. * Bir dosya `policies.js`, `policies.mjs` veya `policies.ts` ile bitmelidir. * Bir dosyada birden çok `customPolicies.add()` çağrısı desteklenir. * Yerel modüllerden göreceli içe aktarmalar desteklenir. * Proje ilkeleri kaydedilebilir, böylece aynı kurallar depo izini takip eder. ### Açık dosyalar Doğrulamada veya yapılandırmada giriş dosyasını doğrudan belirtmek istediğinizde açık yolları kullanın: ```bash theme={null} failproofai policies --install \ --custom ./security.policies.ts \ --custom ./workflow.policies.ts \ --scope project ``` Açık dosyalar ilk olarak yüklenir, arkasından proje kural dosyaları ve ardından kullanıcı kural dosyaları gelir. Her iki yol tarafından da keşfedilen bir dosya bir kez yüklenir. ## Doğrulama ve test Doğrulama modülü üretim yükleyiciyle yürütür ve en az bir ilke kaydını onaylar. ```bash theme={null} failproofai policies --install \ --custom ./.failproofai/policies/checkout-policies.ts \ --scope project failproofai policies ``` Doğrulama eksik dosyaları, söz dizimi hatalarını, çözülmemiş içe aktarmaları, üst düzey istisnalarını ve modül yükleme zaman aşımlarını yakalar. Eşleştirme mantığınızın doğru olduğunu kanıtlamaz. En az şu durumları test edin: * Eşleşmeli ve istenen ilke nedenini üretmeli olan bir işlem. * Yakında ama güvenli olan ve `allow()` döndürmeli olan bir işlem. * Eksik veya hatalı biçimlendirilmiş araç alanları. * Alternatif komut söz dizimi, yollar, alıntılama, büyük küçük harfler ve boşluklar. * Kullanılamayan bir alt işlem veya ağ bağımlılığı. Sonucu **Observe → policy** altında özel ilkenize atfettirin. Farklı bir yerleşik ilke kararı verdi ise engellenen bir test yeterli değildir. ## Çalışma zamanı davranışı * Yerleşik ilkeler özel ilkelerden önce değerlendirilir. * İlk `deny` daha fazla ilke değerlendirmesini durdurur. * Sistem engelleme yapmadığında birden çok `instruct` sonucu birleştirilebilir. * Bir ilke işlevinin 10 saniyelik yürütme süresi vardır. * Atılan istisna veya zaman aşımı günlüğe kaydedilir ve `allow()` olarak değerlendirilir. * Yüklenmesi başarısız olan bir kural dosyası atlanır; diğer özel dosyalar ve yerleşik ilkeler devam eder. * Üst düzey modül yüklemenin de 10 saniyelik süresi vardır. * Bulut observe modu ilkeyi çalıştırır ancak uygulama yapmadan allow olmayan bir kararı kaydeder. İlke modüllerini belirleyici ve hızlı tutun. Üst düzey ağ çağrılarından veya sunucu başlatmadan kaçının. `fn` içinde işi sınırlandırın, bağımlılık başarısızlıklarını yakalayın ve bu başarısızlığın işleme izin verip vermemesi gerektiğini bilerek seçin. ## API dışa aktarmaları | Dışa aktarma | Amaç | | ---------------------------- | ------------------------------------------------------------------- | | `customPolicies.add(policy)` | Modül yüklendiğinde özel bir ilke kaydedin. | | `allow(reason?)` | İşleme izin verin. | | `instruct(reason)` | İşleme izin verin ve desteklendiği yerde rehberlik sağlayın. | | `deny(reason)` | Desteklendiği yerde işlemi engelleyin. | | `getCustomHooks()` | Modül kayıt defterinde şu anda kayıtlı ilkeleri döndürün. | | `clearCustomHooks()` | Kayıt defterini temizleyin, öncelikle testler ve yükleyiciler için. | TypeScript `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` ve `PolicyFunction` dışa aktarır. Bir sürümü yayımlayın, observe modunda dağıtın, kararları doğrulayın ve uygulamaya geçin.