Özel ilkeler

Ö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 kontrol edin.

Özel bir ilke yazın

Dashboard
CLI

Admin → policy editor sayfasına gidin, New policy seçin ve önlemek istediğiniz hatayı açıklayın.
İ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.
Taslağı kaydedin ve Publish version seçerek değişmez bir sürüm oluşturun.
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.

.failproofai/policies/checkout-policies.ts oluşturun. Dosya adı policies.js, policies.mjs veya policies.ts ile bitmelidir.
customPolicies.add() ile bir veya daha fazla ilke kaydedin.
Dosyayı failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project ile doğrulayın ve kurun.
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.

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

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<string, unknown> \| undefined`	Geçerli araç çağrısının kanonik girdisi.
`payload`	`Record<string, unknown>`	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<string, unknown>`	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:

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 bölümüne bakın.

Tüm ilke olay adları

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

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

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

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:

<project>/.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:

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.

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.

Özel ilkeleri dağıtın

Bir sürümü yayımlayın, observe modunda dağıtın, kararları doğrulayın ve uygulamaya geçin.

Connect your agents

Reference

HTTP API

Özel bir ilke yazın

Dar bir kuralla başlayın

Bir karar seçin

İlke nesnesi

İlke bağlamı

Yaygın araç girdileri

Olayı seçin

Yaygın ilke düzenlerini yazın

Korunan yollara yazmaları engelle

Zorunlu olmayan rehberlik verin

Oturum tamamlamasını kapılandırın

İlke dosyalarını yükleyin

Kural dosyaları

Açık dosyalar

Doğrulama ve test

Çalışma zamanı davranışı

API dışa aktarmaları

Özel ilkeleri dağıtın

​Özel bir ilke yazın

​Dar bir kuralla başlayın

​Bir karar seçin

​İlke nesnesi

​İlke bağlamı

​Yaygın araç girdileri

​Olayı seçin

​Yaygın ilke düzenlerini yazın

​Korunan yollara yazmaları engelle

​Zorunlu olmayan rehberlik verin

​Oturum tamamlamasını kapılandırın

​İlke dosyalarını yükleyin

​Kural dosyaları

​Açık dosyalar

​Doğrulama ve test

​Çalışma zamanı davranışı

​API dışa aktarmaları

Özel ilkeleri dağıtın

Özel bir ilke yazın

Dar bir kuralla başlayın

Bir karar seçin

İlke nesnesi

İlke bağlamı

Yaygın araç girdileri

Olayı seçin

Yaygın ilke düzenlerini yazın

Korunan yollara yazmaları engelle

Zorunlu olmayan rehberlik verin

Oturum tamamlamasını kapılandırın

İlke dosyalarını yükleyin

Kural dosyaları

Açık dosyalar

Doğrulama ve test

Çalışma zamanı davranışı

API dışa aktarmaları