failproofai 0.0.6-beta.1 → 0.0.6-beta.2

package/.next/standalone/docs/ko/custom-policies.mdx

@@ -1,14 +1,14 @@
 ---
 title: 커스텀 정책
-description: "JavaScript로 나만의 정책을 작성하세요 - 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 연동 등"
+description: "JavaScript로 나만의 정책을 작성하세요 - 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 연동"
 icon: code
 ---
 
-커스텀 정책을 사용하면 에이전트 동작에 대한 규칙을 직접 작성할 수 있습니다: 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack 연동, 승인 워크플로우 연동 등 다양한 용도로 활용할 수 있습니다. 빌트인 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다.
+커스텀 정책을 사용하면 모든 에이전트 동작에 대한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack이나 승인 워크플로우 연동 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다.
 
 ---
 
-## 빠른 예시
+## 빠른 예제
 
 ```js
 // my-policies.js
@@ -41,26 +41,26 @@ failproofai policies --install --custom ./my-policies.js
 
 ### 방법 1: 컨벤션 기반 (권장)
 
-`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣기만 하면 자동으로 로드됩니다 — 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일만 넣으면 바로 동작합니다.
+`*policies.{js,mjs,ts}` 파일을 `.failproofai/policies/` 디렉터리에 넣으면 자동으로 로드됩니다. 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일만 넣으면 바로 동작합니다.
 
 ```
-# 프로젝트 레벨 — git에 커밋되어 팀 전체에 공유
+# 프로젝트 레벨 — git에 커밋, 팀과 공유
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
-# 사용자 레벨 — 개인 설정, 모든 프로젝트에 적용
+# 사용자 레벨 — 개인용, 모든 프로젝트에 적용
 ~/.failproofai/policies/my-policies.mjs
 ```
 
 **동작 방식:**
-- 프로젝트 디렉터리와 사용자 디렉터리를 모두 스캔합니다 (합집합 방식 — 스코프 우선순위 방식 아님)
-- 각 디렉터리 내에서 파일은 알파벳 순서로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 등의 접두사를 사용하세요
-- `*policies.{js,mjs,ts}` 패턴에 맞는 파일만 로드되며, 그 외 파일은 무시됩니다
-- 각 파일은 독립적으로 로드됩니다 (파일별 fail-open)
-- 명시적 `--custom` 및 빌트인 정책과 함께 사용할 수 있습니다
+- 프로젝트 디렉터리와 사용자 디렉터리 모두 스캔됩니다 (합집합 — 첫 번째 스코프 우선이 아님)
+- 각 디렉터리 내에서 파일은 알파벳 순으로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 등의 접두사를 사용하세요
+- `*policies.{js,mjs,ts}` 패턴에 매칭되는 파일만 로드되며, 나머지 파일은 무시됩니다
+- 각 파일은 독립적으로 로드됩니다 (파일 단위로 fail-open)
+- 명시적 `--custom` 및 내장 정책과 함께 사용 가능합니다
 
 <Tip>
-컨벤션 정책은 팀 전체에 정책을 공유하는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 자동으로 적용받습니다.
+컨벤션 정책은 조직의 품질 기준을 수립하는 가장 간편한 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 동일한 규칙을 개발자별 설정 없이 자동으로 적용받습니다. 팀에서 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 시간이 지날수록 이 정책들은 매 기여마다 발전하는 살아있는 품질 기준이 됩니다.
 </Tip>
 
 ### 방법 2: 명시적 파일 경로
@@ -76,11 +76,11 @@ failproofai policies --install --custom ./new-policies.js
 failproofai policies --uninstall --custom
 ```
 
-변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 매 훅 이벤트마다 새로 로드됩니다 - 이벤트 간 캐싱은 없습니다.
+변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 모든 훅 이벤트마다 새로 로드되며, 이벤트 간 캐싱은 없습니다.
 
 ### 두 방법 함께 사용하기
 
-컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서:
+컨벤션 정책과 명시적 `--custom` 파일은 공존할 수 있습니다. 로드 순서:
 
 1. 명시적 `customPoliciesPath` 파일 (설정된 경우)
 2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순)
@@ -98,45 +98,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-정책을 등록합니다. 하나의 파일에 여러 정책을 추가하려면 여러 번 호출하면 됩니다.
+정책을 등록합니다. 같은 파일에 여러 정책을 추가하려면 필요한 만큼 호출하세요.
 
 ```ts
 customPolicies.add({
   name: string;                         // 필수 - 고유 식별자
-  description?: string;                 // `failproofai policies` 출력에 표시됨
+  description?: string;                 // `failproofai policies` 출력에 표시
   match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략 시 모든 이벤트에 매칭
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
 
-### 결정 헬퍼
+### 결정 헬퍼 함수
 
 | 함수 | 효과 | 사용 시점 |
 |----------|--------|----------|
-| `allow()` | 조용히 작업을 허용 | 동작이 안전하고 메시지가 필요 없을 때 |
-| `deny(message)` | 작업을 차단 | 에이전트가 이 동작을 수행해서는 안 될 때 |
-| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 컨텍스트를 제공할 때 |
+| `allow()` | 작업을 조용히 허용 | 작업이 안전하고 메시지가 필요 없을 때 |
+| `deny(message)` | 작업을 차단 | 에이전트가 이 작업을 수행하면 안 될 때 |
+| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트에게 올바른 방향을 유지하도록 추가 정보를 제공할 때 |
 
-`deny(message)` - 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에게 표시됩니다. 하나의 `deny`가 발생하면 이후 모든 평가가 중단됩니다.
+`deny(message)` - 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에게 표시됩니다. 하나의 `deny`가 발생하면 이후의 모든 평가가 단락됩니다.
 
-`instruct(message)` - 메시지는 현재 툴 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+`instruct(message)` - 메시지는 현재 도구 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
 
 <Tip>
-`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny` 또는 `instruct` 메시지에 추가 가이던스를 붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요.
+`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 모든 `deny` 또는 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 이 기능은 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참고하세요.
 </Tip>
 
 ### 정보성 allow 메시지
 
-`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전달합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달되며, `instruct`와 동일한 메커니즘을 사용하지만 의미상 다릅니다: 경고가 아닌 상태 업데이트입니다.
+`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다. `instruct`와 동일한 메커니즘을 사용하지만 의미론적으로 다릅니다. 경고가 아닌 상태 업데이트입니다.
 
 | 함수 | 효과 | 사용 시점 |
 |----------|--------|----------|
-| `allow(message)` | 허용하면서 Claude에게 컨텍스트 전달 | 검사가 통과되었음을 확인하거나, 검사가 건너뛰어진 이유를 설명할 때 |
+| `allow(message)` | 허용하고 Claude에게 컨텍스트 전송 | 검사가 통과되었음을 확인하거나, 검사가 건너뛰어진 이유를 설명할 때 |
 
-활용 예시:
+사용 사례:
 - **상태 확인:** `allow("All CI checks passed.")` — Claude에게 모든 것이 정상임을 알림
-- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude가 완전한 컨텍스트를 갖도록 검사가 건너뛰어진 이유를 알림
-- **다중 메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면 모든 메시지가 줄바꿈으로 연결되어 함께 전달됩니다
+- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude가 전체 컨텍스트를 파악할 수 있도록 검사가 건너뛰어진 이유를 알림
+- **메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면, 모든 메시지가 개행으로 연결되어 함께 전달됩니다
 
 ```js
 customPolicies.add({
@@ -160,8 +160,8 @@ customPolicies.add({
 | 필드 | 타입 | 설명 |
 |-------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | 호출되는 툴 (예: `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | 툴의 입력 파라미터 |
+| `toolName` | `string \| undefined` | 호출 중인 도구 (예: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | 도구의 입력 파라미터 |
 | `payload` | `Record<string, unknown>` | Claude Code로부터의 전체 원시 이벤트 페이로드 |
 | `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참조) |
 
@@ -177,10 +177,10 @@ customPolicies.add({
 
 | 이벤트 | 발생 시점 | `toolInput` 내용 |
 |-------|--------------|----------------------|
-| `PreToolUse` | Claude가 툴을 실행하기 전 | 툴의 입력 (예: Bash의 경우 `{ command: "..." }`) |
-| `PostToolUse` | 툴 실행 완료 후 | 툴의 입력 + `tool_result` (출력) |
+| `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력값 (예: Bash의 경우 `{ command: "..." }`) |
+| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력값 + `tool_result` (출력) |
 | `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 항상 `allow()`를 반환해야 하며, 알림을 차단할 수 없습니다 |
-| `Stop` | Claude 세션이 종료될 때 | 비어 있음 |
+| `Stop` | Claude 세션이 종료될 때 | 없음 |
 
 ---
 
@@ -188,13 +188,13 @@ customPolicies.add({
 
 정책은 다음 순서로 평가됩니다:
 
-1. 빌트인 정책 (정의 순서)
-2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 순서)
-3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
-4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
+1. 내장 정책 (정의 순서)
+2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 호출 순서)
+3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내에서는 `.add()` 순서)
+4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내에서는 `.add()` 순서)
 
 <Note>
-첫 번째 `deny`가 이후 모든 정책 평가를 중단시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+첫 번째 `deny`가 이후의 모든 정책 평가를 단락시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
 </Note>
 
 ---
@@ -218,46 +218,46 @@ customPolicies.add({
 });
 ```
 
-엔트리 파일에서 도달 가능한 모든 상대 임포트가 해석됩니다. 이는 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고 ESM 호환성을 보장하기 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다.
+엔트리 파일에서 도달 가능한 모든 상대 임포트가 해석됩니다. 이는 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고, ESM 호환성을 보장하기 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다.
 
 ---
 
 ## 이벤트 타입 필터링
 
-`match.events`를 사용하여 정책이 발동되는 시점을 제한합니다:
+`match.events`를 사용하여 정책이 실행될 시점을 제한할 수 있습니다:
 
 ```js
 customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // 세션이 종료될 때만 발동됨
-    // ctx.session.transcriptPath에 전체 세션 로그가 있음
+    // 세션이 종료될 때만 실행됨
+    // ctx.session.transcriptPath에 전체 세션 로그가 포함됨
     return allow();
   },
 });
 ```
 
-`match`를 완전히 생략하면 모든 이벤트 타입에서 발동됩니다.
+`match`를 완전히 생략하면 모든 이벤트 타입에서 실행됩니다.
 
 ---
 
-## 에러 처리 및 실패 모드
+## 오류 처리 및 실패 모드
 
-커스텀 정책은 **fail-open** 방식입니다: 에러가 발생해도 빌트인 정책이 차단되거나 훅 핸들러가 크래시되지 않습니다.
+커스텀 정책은 **fail-open** 방식으로 동작합니다. 오류가 발생해도 내장 정책이 차단되거나 훅 핸들러가 충돌하지 않습니다.
 
 | 실패 상황 | 동작 |
 |---------|----------|
-| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 빌트인은 정상 계속 |
-| 파일 없음 | `~/.failproofai/hook.log`에 경고 기록; 빌트인 계속 |
-| 문법/임포트 에러 (명시적) | `~/.failproofai/hook.log`에 에러 기록; 명시적 커스텀 정책 건너뜀 |
-| 문법/임포트 에러 (컨벤션) | 에러 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 |
-| `fn` 런타임 에러 | 에러 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 |
-| `fn`이 10초 초과 | 타임아웃 기록; `allow`로 처리 |
-| 컨벤션 디렉터리 없음 | 컨벤션 정책 실행 안 됨; 에러 없음 |
+| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않으며, 컨벤션 정책과 내장 정책은 정상적으로 계속됩니다 |
+| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속됩니다 |
+| 구문/임포트 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 |
+| 구문/임포트 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 정상 로드 |
+| 런타임에서 `fn` 예외 발생 | 오류 기록; 해당 훅은 `allow`로 처리됨; 다른 훅은 계속됩니다 |
+| `fn`이 10초를 초과 | 타임아웃 기록; `allow`로 처리됨 |
+| 컨벤션 디렉터리 없음 | 컨벤션 정책 미실행; 오류 없음 |
 
 <Tip>
-커스텀 정책 에러를 디버깅하려면 로그 파일을 모니터링하세요:
+커스텀 정책 오류를 디버깅하려면 로그 파일을 확인하세요:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -266,13 +266,13 @@ tail -f ~/.failproofai/hook.log
 
 ---
 
-## 전체 예시: 다중 정책
+## 전체 예제: 다중 정책
 
 ```js
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// 에이전트가 secrets/ 디렉터리에 쓰는 것을 방지
+// 에이전트가 secrets/ 디렉터리에 쓰지 못하도록 방지
 customPolicies.add({
   name: "block-secrets-dir",
   description: "Prevent agent from writing to secrets/ directory",
@@ -285,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// 에이전트가 올바른 방향을 유지하도록: 커밋 전 테스트 확인
+// 에이전트 방향 유지: 커밋 전 테스트 확인
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -300,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// 동결 기간 중 계획되지 않은 의존성 변경 방지
+// 동결 기간 중 예기치 않은 의존성 변경 방지
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -321,33 +321,33 @@ export { customPolicies };
 
 ---
 
-## 예시 파일
+## 예제 파일
 
-`examples/` 디렉터리에는 바로 실행 가능한 정책 파일들이 있습니다:
+`examples/` 디렉터리에는 바로 실행 가능한 정책 파일들이 포함되어 있습니다:
 
 | 파일 | 내용 |
 |------|----------|
-| `examples/policies-basic.js` | 일반적인 에이전트 실패 모드를 다루는 5가지 기본 정책 |
+| `examples/policies-basic.js` | 일반적인 에이전트 실패 모드를 다루는 5가지 스타터 정책 |
 | `examples/policies-advanced/index.js` | 고급 패턴: 전이적 임포트, 비동기 호출, 출력 스크러빙, 세션 종료 훅 |
-| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 파일 쓰기 차단, git 히스토리 재작성 방지) |
-| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 리마인더, 파일 쓰기 감사) |
+| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 쓰기 차단, git 히스토리 재작성 방지) |
+| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 알림, 감사 파일 쓰기) |
 
-### 명시적 파일 예시 사용
+### 명시적 파일 예제 사용
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### 컨벤션 기반 예시 사용
+### 컨벤션 기반 예제 사용
 
 ```bash
-# 프로젝트 레벨로 복사
+# 프로젝트 레벨에 복사
 mkdir -p .failproofai/policies
 cp examples/convention-policies/*.mjs .failproofai/policies/
 
-# 또는 사용자 레벨로 복사
+# 또는 사용자 레벨에 복사
 mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-설치 명령어가 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 감지됩니다.
+설치 명령이 필요 없습니다. 다음 훅 이벤트 시 파일이 자동으로 감지됩니다.

package/.next/standalone/docs/ko/examples.mdx

@@ -4,13 +4,13 @@ description: "Claude Code 및 Agents SDK를 위한 훅 설정 방법"
 icon: book-open
 ---
 
-일반적인 시나리오에 바로 사용할 수 있는 예시 모음입니다. 각 예시에는 설치 방법과 예상 동작이 포함되어 있습니다.
+일반적인 시나리오에 바로 사용할 수 있는 예시 모음입니다. 각 예시에는 설치 방법과 기대 동작이 포함되어 있습니다.
 
 ---
 
-## Claude Code용 훅 설정
+## Claude Code를 위한 훅 설정
 
-Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면 모든 도구 호출 시 실행되는 훅 명령이 Claude Code의 `settings.json`에 등록됩니다.
+Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면, 모든 도구 호출 시 실행되는 훅 명령어가 Claude Code의 `settings.json`에 등록됩니다.
 
 <Steps>
   <Step title="failproofai 설치">
@@ -18,7 +18,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc
     npm install -g failproofai
     ```
   </Step>
-  <Step title="모든 내장 정책 활성화">
+  <Step title="내장 정책 전체 활성화">
     ```bash
     failproofai policies --install
     ```
@@ -35,15 +35,15 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc
     claude
     ```
 
-    이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /`를 실행하도록 요청해 보세요 — 차단됩니다.
+    이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /` 실행을 요청해 보세요 — 차단됩니다.
   </Step>
 </Steps>
 
 ---
 
-## Agents SDK용 훅 설정
+## Agents SDK를 위한 훅 설정
 
-[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발하는 경우, 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다.
+[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발 중이라면, 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다.
 
 <Steps>
   <Step title="프로젝트에 failproofai 설치">
@@ -52,7 +52,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc
     ```
   </Step>
   <Step title="에이전트에 훅 설정">
-    에이전트 프로세스를 생성할 때 훅 명령을 전달합니다. 훅은 Claude Code와 동일한 방식으로 — stdin/stdout JSON을 통해 — 실행됩니다:
+    에이전트 프로세스 생성 시 훅 명령어를 전달합니다. Claude Code에서와 동일하게 stdin/stdout JSON 방식으로 훅이 실행됩니다:
 
     ```bash
     failproofai --hook PreToolUse   # 각 도구 실행 전 호출
@@ -65,12 +65,12 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc
 
     customPolicies.add({
       name: "limit-to-project-dir",
-      description: "Keep the agent inside the project directory",
+      description: "에이전트를 프로젝트 디렉터리 내로 제한",
       match: { events: ["PreToolUse"] },
       fn: async (ctx) => {
         const path = String(ctx.toolInput?.file_path ?? "");
         if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
-          return deny("Agent is restricted to the project directory");
+          return deny("에이전트는 프로젝트 디렉터리로 제한됩니다");
         }
         return allow();
       },
@@ -86,35 +86,35 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc
 
 ---
 
-## 파괴적 명령 차단
+## 파괴적인 명령어 차단
 
-가장 일반적인 설정으로, 에이전트가 되돌릴 수 없는 피해를 입히는 것을 방지합니다.
+가장 일반적인 설정 — 에이전트가 되돌릴 수 없는 손상을 입히지 못하도록 방지합니다.
 
 ```bash
 failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
 ```
 
 각 정책의 역할:
-- `block-sudo` — 모든 `sudo` 명령 차단
-- `block-rm-rf` — 재귀적 파일 삭제 차단
-- `block-force-push` — `git push --force` 차단
-- `block-curl-pipe-sh` — 원격 스크립트를 셸로 파이핑하는 것 차단
+- `block-sudo` - 모든 `sudo` 명령어 차단
+- `block-rm-rf` - 재귀적 파일 삭제 차단
+- `block-force-push` - `git push --force` 차단
+- `block-curl-pipe-sh` - 원격 스크립트를 셸로 파이프하는 명령 차단
 
 ---
 
 ## 시크릿 유출 방지
 
-에이전트가 도구 출력에서 자격 증명을 보거나 유출하지 못하도록 차단합니다.
+에이전트가 도구 출력에서 자격 증명을 확인하거나 유출하지 못하도록 차단합니다.
 
 ```bash
 failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
 ```
 
-이 정책들은 `PostToolUse`에서 실행됩니다 — 도구 실행 후, 에이전트가 출력을 확인하기 전에 민감한 정보를 제거합니다.
+이 정책들은 `PostToolUse` 시점에 실행됩니다 — 도구 실행 후 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다.
 
 ---
 
-## 에이전트 대기 시 Slack 알림 받기
+## 에이전트가 대기 중일 때 Slack 알림 받기
 
 알림 훅을 사용하여 유휴 알림을 Slack으로 전달합니다.
 
@@ -123,7 +123,7 @@ import { customPolicies, allow, instruct } from "failproofai";
 
 customPolicies.add({
   name: "slack-on-idle",
-  description: "Alert Slack when the agent is waiting for input",
+  description: "에이전트가 입력을 기다릴 때 Slack에 알림 전송",
   match: { events: ["Notification"] },
   fn: async (ctx) => {
     const webhookUrl = process.env.SLACK_WEBHOOK_URL;
@@ -160,20 +160,20 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c
 
 ## 에이전트를 특정 브랜치에 고정
 
-에이전트가 브랜치를 전환하거나 보호된 브랜치에 푸시하는 것을 방지합니다.
+에이전트가 브랜치를 전환하거나 보호된 브랜치에 푸시하지 못하도록 방지합니다.
 
 ```javascript
 import { customPolicies, allow, deny } from "failproofai";
 
 customPolicies.add({
   name: "stay-on-branch",
-  description: "Prevent the agent from checking out other branches",
+  description: "에이전트가 다른 브랜치로 체크아웃하지 못하도록 방지",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
     const cmd = String(ctx.toolInput?.command ?? "");
     if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
-      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+      return deny("현재 브랜치를 유지하세요. 새 브랜치가 필요하면 -b 옵션을 사용하세요.");
     }
     return allow();
   },
@@ -184,20 +184,20 @@ customPolicies.add({
 
 ## 커밋 전 테스트 실행 요구
 
-에이전트가 커밋하기 전에 테스트를 실행하도록 상기시킵니다.
+에이전트에게 커밋 전 테스트를 실행하도록 상기시킵니다.
 
 ```javascript
 import { customPolicies, allow, instruct } from "failproofai";
 
 customPolicies.add({
   name: "test-before-commit",
-  description: "Remind the agent to run tests before committing",
+  description: "에이전트에게 커밋 전 테스트 실행을 상기",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
     const cmd = String(ctx.toolInput?.command ?? "");
     if (/git\s+commit/.test(cmd)) {
-      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+      return instruct("커밋 전에 테스트를 실행하세요. 먼저 `npm test` 또는 `bun test`를 사용하세요.");
     }
     return allow();
   },
@@ -208,9 +208,9 @@ customPolicies.add({
 
 ## 프로덕션 저장소 잠금
 
-팀의 모든 개발자가 동일한 정책을 적용받도록 프로젝트 수준의 설정을 저장소에 커밋합니다.
+프로젝트 수준 설정을 커밋하여 팀의 모든 개발자가 동일한 정책을 적용받도록 합니다.
 
-저장소에 `.failproofai/policies-config.json`을 생성합니다:
+저장소에 `.failproofai/policies-config.json` 파일을 생성합니다:
 
 ```json
 {
@@ -238,16 +238,70 @@ git add .failproofai/policies-config.json
 git commit -m "Add failproofai team policies"
 ```
 
-failproofai가 설치된 모든 팀원은 이 규칙을 자동으로 적용받습니다.
+failproofai를 설치한 모든 팀원이 이 규칙을 자동으로 적용받게 됩니다.
 
 ---
 
-## 더 많은 예시
+## 컨벤션 정책으로 조직 전체 품질 기준 구축
 
-저장소의 [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) 디렉토리에는 다음 파일들이 포함되어 있습니다:
+가장 효과적인 설정: 프로젝트에 맞게 조정된 정책을 담은 `.failproofai/policies/` 디렉터리를 저장소에 커밋합니다. 모든 팀원이 별도의 설치 명령이나 설정 변경 없이 자동으로 적용받습니다.
+
+<Steps>
+  <Step title="디렉터리 생성 후 정책 추가">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // 팀이 선호하는 패키지 매니저 강제 적용
+    // (또는 내장 prefer-package-manager 정책을 활성화하세요)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("npm 대신 bun을 사용하세요.");
+        return allow();
+      },
+    });
+
+    // 에이전트에게 커밋 전 테스트 실행을 상기
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("커밋 전에 테스트를 실행하세요.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="git에 커밋">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+  </Step>
+  <Step title="지속적으로 개선하기">
+    팀에서 새로운 장애 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 기준이 됩니다.
+  </Step>
+</Steps>
+
+---
+
+## 추가 예시
+
+저장소의 [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) 디렉터리에는 다음이 포함되어 있습니다:
 
 | 파일 | 내용 |
-|------|------|
-| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기 차단, force-push 차단, 파이프된 스크립트 차단 |
+|------|---------------|
+| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기, 강제 푸시, 파이프 스크립트 차단 |
 | `policies-notification.js` | 유휴 알림 및 세션 종료 시 Slack 알림 |
 | `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 스크러빙, Stop 이벤트 처리 |