README.ko.md

⚠️ This is an auto-generated translation. For the latest version, see the English README. Community corrections welcome!

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇪🇸 Español | 🇧🇷 Português | 🇩🇪 Deutsch | 🇫🇷 Français | 🇷🇺 Русский | 🇮🇳 हिन्दी | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇹 Italiano | 🇸🇦 العربية | 🇮🇱 עברית

---

---

지원 하네스

두 가지 클래스로 나뉜 12개의 하네스 — 코딩 CLI 10개, 채팅 및 어시스턴트 게이트웨이 2개(Hermes, OpenClaw). 모든 하네스에 걸쳐 하나의 정책 API와 하나의 세션 히스토리를 공유합니다. 정책이 차단할 수 있는 범위는 하네스마다 다릅니다. 툴 호출을 실행 전에 멈추는 기능은 12개 모두에서 검증되었으며, 턴 종료 게이트는 8개에서 작동합니다. 하네스별 매트릭스에서 각 하네스가 지원하는 이벤트를 확인할 수 있습니다.

12개 하네스 중 어디에도 속하지 않는 에이전트는 Python SDK를 통해 보고하며, 트레이싱, 세션, 감사 기능을 제공합니다. 해당 환경에서의 정책 집행은 자체 런타임에 훅이 필요합니다 — 문의하시면 매핑을 도와드립니다.

{/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens instead of collapsing into ragged orphan rows). */}

설치

npm install -g failproofai
failproofai config                             # 에이전트와 데몬 연결 설정
failproofai policies add FailproofAI/policies  # 적용할 정책 선택
failproofai                                    # localhost:8020에서 대시보드 실행

설정은 훅을 연결하되 정책을 아무것도 적용하지 않습니다 — 두 번째 명령이 머신에 가드레일을 설치하는 역할을 하며, 모든 팩은 동일한 방식으로 지정합니다 (failproofai policies add <owner>/<repo>; policies show <owner>/<repo>로 먼저 내용을 확인할 수 있습니다). 터미널 없이 failproofai config를 실행하면 — CI, 컨테이너, 에이전트가 직접 구동하는 경우 — 묻지 않고 바로 적용합니다. 한 번도 설정되지 않은 머신에서는 다른 명령을 실행해도 동일한 설정 마법사가 먼저 실행됩니다. FAILPROOFAI_NO_FIRST_RUN=1로 이를 비활성화할 수 있습니다.

팩이 추가되기 전까지는 block-failproofai-commands만 정책을 집행합니다. 이 정책은 항상 활성화되어 있으며 끄거나 일시 중지할 수 없습니다. 집행을 일시 중지할 수 있는 에이전트는 다른 모든 정책도 끌 수 있기 때문입니다.

---

차단 대상

정책	차단 내용
block-env-files	.env 및 기타 시크릿 파일 읽기
warn-repeated-tool-calls	동일한 툴 호출을 반복하는 에이전트 루프
block-sudo	권한 상승
warn-destructive-sql	DROP, TRUNCATE, 조건 없는 DELETE
block-terraform / block-kubectl	검토되지 않은 라이브 인프라 변경
block-rm-rf	재귀적 파일 삭제
block-force-push / block-push-master	git push --force, main 브랜치로의 직접 푸시

이 모든 정책은 툴 호출을 실행 전에 차단하므로 12개 하네스 모두에서 동작합니다. 처음 네 가지는 툴을 호출할 수 있는 모든 에이전트에 적용되고, 나머지 세 가지는 개발자들이 가장 선호하는 정책입니다 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 클래스입니다. sanitize-* 계열은 별도로 작동합니다. 툴이 반환된 후 실행되므로, 시크릿이 컨텍스트에 포함되지 않도록 막는 것이 아니라 툴 출력에서 시크릿을 감지해 보고합니다.

→ 39개의 기본 제공 정책 전체 보기

---

커스텀 정책

.failproofai/policies/ 디렉터리에 파일을 추가하면 자동으로 로드됩니다 — 별도의 플래그가 필요 없습니다. 커밋하면 팀 전체가 다음 풀 때 적용됩니다.

import { customPolicies, deny, allow } from "failproofai";

customPolicies.add({
  name: "no-production-writes",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolInput?.file_path?.includes("production"))
      return deny("Writes to production paths are blocked.");
    return allow();
  },
});

모든 정책에서 사용할 수 있는 세 가지 결정:

결정	효과
allow()	작업 허용
deny(message)	차단 — 메시지가 에이전트에게 반환됨
instruct(message)	통과시키되, 에이전트의 다음 프롬프트에 컨텍스트 추가

→ 정책 작성하기

---

관측성

정책 집행은 절반에 불과합니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 파악하는 것입니다.

인수 없이 failproofai를 실행하면 localhost:8020에서 대시보드가 시작되며, 이미 머신에 저장된 실행 히스토리를 읽어옵니다 — 계정도, 회원가입도, 외부 전송도 없습니다. 세션 목록, 각 실행 내의 모델 호출 순서, 툴 호출, 훅 결정, 차단된 내용과 정책이 에이전트에 전달한 내용, 그리고 히스토리에서 위험 패턴을 스캔하고 차단할 정책을 제안하는 오프라인 감사(failproofai audit)를 제공합니다.

→ 로컬 대시보드 · 트레이스 읽기 · 로컬 감사

Failproof AI Observability는 동일한 데이터 모델의 호스팅 버전으로, 플릿 전체에서 에이전트를 운영하는 팀을 위한 서비스입니다. 모든 하네스의 모든 실행을 한 곳에서 확인하고, 병렬 서브에이전트를 별도 레인으로 표시하는 실행 그래프, 모델·툴·훅의 p50/p95/p99 레이턴시, 모델별 비용 및 컨텍스트 윈도우 추적, 오류 추적, 공유 가능한 대시보드를 갖춘 자체 트레이스 SQL 쿼리, 자체 서비스로 점수를 매기는 평가, 반복적인 실패를 증거 기반 결과로 변환하는 예약 감사, Slack·이메일·서명된 웹훅으로의 알림 라우팅을 제공합니다. Enterprise 플랜에서는 자체 클러스터 셀프 호스팅도 지원합니다.

→ 세션 · 감사 · 데모 예약

---

문서

시작하기
빠른 시작	설치, 하네스 연결, 첫 번째 실행 확인
개념	훅 시스템 작동 방식
지원 하네스	12개 전체 및 각 하네스의 집행 범위

관측
세션	실행 추적: 모델, 툴, 오류, 레이턴시
트레이스 읽기	실행 그래프가 말해주는 것
감사	여러 세션에 걸친 실패 패턴 탐지
로컬 대시보드	localhost:8020, 계정 불필요

집행
정책 팩	Failproof AI 정책 및 정책 허브의 팩
정책 작성하기	감사 결과 기반 또는 코드로 직접 작성
설정	설정 스코프, 병합 규칙 및 정책 파라미터

커스텀 에이전트 연동
Python SDK	하네스 없이 에이전트 실행을 보고
Policy SDK	allow / deny / instruct 레퍼런스

---

라이선스

Commons Clause가 포함된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전문은 LICENSE를 참조하세요.

---

기여하기

CONTRIBUTING.md를 참조하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다.

시작 전에 빌드하세요. 먼저 bun install && bun run build를 실행하세요. 이 저장소는 failproofai 자체 훅을 자기 자신에게 적용하며, 훅은 컴파일된 dist/ 번들에서 failproofai 임포트를 해석합니다 — 빌드 없이는 Cannot find package 'failproofai' 훅 오류가 발생합니다. src/ 변경 후에는 다시 빌드하세요. 자세한 내용은 Build before the in-repo dev hooks will work를 참조하세요.

---

SF와 벵갈루루에서 ❤️를 담아 befailproof.ai가 만들었습니다.