failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -1,10 +1,10 @@
 ---
 title: 아키텍처
-description: "훅 핸들러, 설정 로딩, 정책 평가가 내부적으로 동작하는 방식"
+description: "훅 핸들러, 설정 로딩, 정책 평가의 내부 동작 방식"
 icon: sitemap
 ---
 
-이 문서는 failproofai가 내부적으로 어떻게 동작하는지 설명합니다. 훅 시스템이 에이전트 툴 호출을 가로채는 방식, 설정이 로드되고 병합되는 방식, 정책이 평가되는 방식, 그리고 대시보드가 에이전트 활동을 모니터링하는 방식을 다룹니다.
+이 문서는 failproofai의 내부 동작 방식을 설명합니다. 훅 시스템이 에이전트 도구 호출을 가로채는 방법, 설정이 로드되고 병합되는 방법, 정책이 평가되는 방법, 그리고 대시보드가 에이전트 활동을 모니터링하는 방법을 다룹니다.
 
 ---
 
@@ -12,10 +12,10 @@ icon: sitemap
 
 failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다:
 
-1. **훅 핸들러** - Claude Code가 에이전트 툴 호출마다 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다.
+1. **훅 핸들러** - Claude Code가 모든 에이전트 도구 호출 시 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다.
 2. **에이전트 모니터 (대시보드)** - 에이전트 세션을 모니터링하고 정책을 관리하기 위한 Next.js 웹 애플리케이션입니다.
 
-두 서브시스템 모두 `~/.failproofai/`와 프로젝트의 `.failproofai/` 디렉터리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일시스템을 통해서만 통신합니다.
+두 서브시스템 모두 `~/.failproofai/`와 프로젝트의 `.failproofai/` 디렉토리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일 시스템을 통해서만 통신합니다.
 
 ---
 
@@ -23,7 +23,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다:
 
 ### Claude Code와의 통합
 
-`failproofai policies --install`을 실행하면 `~/.claude/settings.json`에 다음과 같은 항목이 작성됩니다:
+`failproofai policies --install`을 실행하면, `~/.claude/settings.json`에 다음과 같은 항목이 작성됩니다:
 
 ```json
 {
@@ -44,7 +44,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다:
 }
 ```
 
-Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하고, stdin으로 JSON 페이로드를 전달합니다.
+Claude Code는 각 도구 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하며, stdin으로 JSON 페이로드를 전달합니다.
 
 ### 페이로드 형식
 
@@ -60,13 +60,13 @@ Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브
 }
 ```
 
-`PostToolUse` 이벤트의 경우 페이로드에 툴의 출력값이 담긴 `tool_result`도 포함됩니다.
+`PostToolUse` 이벤트의 페이로드에는 도구의 출력 결과가 담긴 `tool_result`도 포함됩니다.
 
-핸들러는 stdin 입력을 1 MB로 제한합니다. 이를 초과하는 페이로드는 폐기되며 모든 정책이 암묵적으로 allow 처리됩니다.
+핸들러는 stdin을 1 MB로 제한합니다. 이를 초과하는 페이로드는 폐기되며 모든 정책은 암묵적으로 허용됩니다.
 
 ### 응답 형식
 
-**Deny (PreToolUse):**
+**거부 (PreToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -76,7 +76,7 @@ Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브
 }
 ```
 
-**Deny (PostToolUse):**
+**거부 (PostToolUse):**
 ```json
 {
   "hookSpecificOutput": {
@@ -85,7 +85,7 @@ Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브
 }
 ```
 
-**Instruct (Stop 이벤트를 제외한 모든 이벤트):**
+**지시 (Stop 이벤트 제외한 모든 이벤트):**
 ```json
 {
   "hookSpecificOutput": {
@@ -94,20 +94,20 @@ Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브
 }
 ```
 
-**Stop 이벤트의 instruct:**
+**Stop 이벤트 지시:**
 - 종료 코드: `2`
-- 이유는 stdout이 아닌 stderr에 기록됩니다
+- 이유는 stdout이 아닌 stderr에 기록됨
 
-**Allow:**
+**허용:**
 - 종료 코드: `0`
-- stdout 출력 없음
+- stdout 비어 있음
 
-**메시지를 포함한 allow:**
+**메시지와 함께 허용:**
 
-`allow(message)`를 통해 정책이 작업을 허용하면서도 Claude에게 정보성 컨텍스트를 전달할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 씁니다 (설정 파일이 아니라 deny 및 instruct 응답과 마찬가지로 Claude Code에 대한 핸들러의 응답입니다):
+`allow(message)`를 사용하면 작업이 허용되더라도 정책이 Claude에게 정보성 컨텍스트를 전송할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 기록합니다 (설정 파일이 아닌, 위의 거부 및 지시 응답과 동일하게 Claude Code에 대한 핸들러의 응답입니다):
 
 ```json
-// 훅 핸들러 프로세스가 stdout에 씁니다
+// 훅 핸들러 프로세스가 stdout에 기록
 {
   "hookSpecificOutput": {
     "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
@@ -115,12 +115,12 @@ Claude Code는 각 툴 호출 전에 `failproofai --hook PreToolUse`를 서브
 }
 ```
 - 종료 코드: `0` (작업이 허용됨)
-- 여러 정책이 메시지와 함께 `allow`를 반환하면, 해당 메시지들이 줄바꿈으로 연결되어 하나의 `additionalContext` 문자열로 합쳐집니다
-- 어떤 정책도 메시지를 제공하지 않으면 stdout은 비어 있습니다 (기존 동작과 동일)
+- 여러 정책이 메시지와 함께 `allow`를 반환하면, 해당 메시지들이 줄바꿈으로 연결되어 단일 `additionalContext` 문자열이 됨
+- 어떤 정책도 메시지를 제공하지 않으면 stdout은 비어 있음 (기존과 동일)
 
 ### 처리 파이프라인
 
-`src/hooks/handler.ts`가 전체 파이프라인을 구현합니다:
+`src/hooks/handler.ts`는 전체 파이프라인을 구현합니다:
 
 ```text
 stdin JSON
@@ -131,62 +131,62 @@ stdin JSON
   → customPoliciesPath에서 커스텀 정책 로드 (설정된 경우)
   → 커스텀 정책을 정책 레지스트리에 등록
   → 모든 정책 평가 (내장 정책 먼저, 그 다음 커스텀)
-      → 첫 번째 deny가 나오면 즉시 중단
-      → instruct 결정은 누적됨
-      → allow 메시지는 누적됨
-  → stdout에 JSON 결정 출력
-  → ~/.failproofai/hook-activity.jsonl에 이벤트 저장
+      → 첫 번째 거부가 단락(short-circuit)
+      → 지시 결정이 누적됨
+      → 허용 메시지가 누적됨
+  → JSON 결정을 stdout에 기록
+  → 이벤트를 ~/.failproofai/hook-activity.jsonl에 저장
   → 종료
 ```
 
-LLM 호출 없이 일반적인 페이로드 기준으로 전체 프로세스가 100ms 이내에 완료됩니다.
+전체 프로세스는 LLM 호출 없이 일반적인 페이로드 기준 100ms 이내에 완료됩니다.
 
 ---
 
 ## 설정 로딩
 
-`src/hooks/hooks-config.ts`가 세 단계 범위의 설정 로딩을 구현합니다.
+`src/hooks/hooks-config.ts`는 세 가지 범위의 설정 로딩을 구현합니다.
 
 ```text
-[1] {cwd}/.failproofai/policies-config.json        ← 프로젝트  (최우선)
+[1] {cwd}/.failproofai/policies-config.json        ← 프로젝트  (가장 높은 우선순위)
 [2] {cwd}/.failproofai/policies-config.local.json  ← 로컬
-[3] ~/.failproofai/policies-config.json             ← 전역   (최하위 우선순위)
+[3] ~/.failproofai/policies-config.json             ← 전역   (가장 낮은 우선순위)
 ```
 
 병합 로직:
-- `enabledPolicies` - 세 파일 전체에서 중복 제거 후 합집합
-- `policyParams` - 정책별 키, 해당 키를 정의한 첫 번째 파일이 전체를 결정
-- `customPoliciesPath` - 해당 키를 정의한 첫 번째 파일이 결정
-- `llm` - 해당 키를 정의한 첫 번째 파일이 결정
+- `enabledPolicies` - 세 파일 모두에서 중복 제거된 합집합
+- `policyParams` - 정책별 키, 이를 정의하는 첫 번째 파일이 전체 우선
+- `customPoliciesPath` - 이를 정의하는 첫 번째 파일이 우선
+- `llm` - 이를 정의하는 첫 번째 파일이 우선
 
-웹 대시보드는 프로젝트 cwd 없이 실행되기 때문에 읽기 및 쓰기에 `readHooksConfig()`(전역 전용)를 사용합니다.
+웹 대시보드는 프로젝트 cwd 없이 실행되므로 읽기 및 쓰기에 `readHooksConfig()`(전역만)를 사용합니다.
 
 ---
 
 ## 정책 평가
 
-`src/hooks/policy-evaluator.ts`가 정책을 순서대로 실행합니다.
+`src/hooks/policy-evaluator.ts`는 정책을 순서대로 실행합니다.
 
 각 정책에 대해:
 
-1. 정책의 `params` 스키마를 조회합니다 (있는 경우).
+1. 정책의 `params` 스키마(존재하는 경우)를 조회합니다.
 2. 병합된 설정에서 `policyParams[policy.name]`을 읽습니다.
 3. 스키마 기본값 위에 사용자 제공 값을 병합하여 `ctx.params`를 생성합니다.
 4. 해결된 컨텍스트와 함께 `policy.fn(ctx)`를 호출합니다.
 5. 결과가 `deny`이면 즉시 중단하고 해당 결정을 반환합니다.
 6. 결과가 `instruct`이면 메시지를 누적하고 계속 진행합니다.
-7. 결과가 `allow`이면 다음 정책으로 넘어갑니다.
+7. 결과가 `allow`이면 다음 정책으로 계속 진행합니다.
 
-모든 정책 실행 후:
-- `deny`가 반환된 경우, deny 응답을 출력합니다.
-- `instruct` 반환값이 수집된 경우, 모든 메시지를 합쳐 단일 instruct 응답을 출력합니다.
-- 그 외의 경우, allow 응답을 출력합니다 (stdout 비움, 종료 코드 0).
+모든 정책이 실행된 후:
+- `deny`가 반환된 경우 거부 응답을 내보냅니다.
+- `instruct` 반환이 수집된 경우 모든 메시지를 결합한 단일 지시 응답을 내보냅니다.
+- 그렇지 않으면 허용 응답을 내보냅니다 (stdout 비어 있음, 종료 코드 0).
 
 ---
 
 ## 내장 정책
 
-`src/hooks/builtin-policies.ts`가 26개의 내장 정책을 `BuiltinPolicyDefinition` 객체로 정의합니다:
+`src/hooks/builtin-policies.ts`는 26개의 내장 정책을 `BuiltinPolicyDefinition` 객체로 정의합니다:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition {
 }
 ```
 
-`params`를 받는 정책은 각 파라미터에 대한 타입과 기본값을 포함하는 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn` 호출 전에 해결된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되기 때문에 정책 함수는 null 체크 없이 `ctx.params`를 읽습니다.
+`params`를 받는 정책은 각 파라미터에 대한 타입과 기본값을 포함한 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn`을 호출하기 전에 해결된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되므로 정책 함수는 null 검사 없이 `ctx.params`를 읽습니다.
 
-정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 인젝션을 통한 우회를 방지합니다 (예: `sudo systemctl status *` 패턴은 명령에 `; rm -rf /`를 덧붙이는 방식으로 우회할 수 없습니다).
+정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 인젝션을 통한 우회를 방지합니다 (예: `sudo systemctl status *` 패턴은 명령어에 `; rm -rf /`를 추가해도 우회할 수 없음).
 
 ---
 
 ## 커스텀 정책
 
-`src/hooks/custom-hooks-registry.ts`가 `globalThis` 기반 레지스트리를 구현합니다:
+`src/hooks/custom-hooks-registry.ts`는 `globalThis` 기반 레지스트리를 구현합니다:
 
 ```typescript
 const REGISTRY_KEY = "__failproofai_custom_hooks__";
@@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... }
 export function clearCustomHooks(): void { ... }  // 테스트에서 사용
 ```
 
-`src/hooks/custom-hooks-loader.ts`가 사용자의 정책 파일을 로드합니다:
+`src/hooks/custom-hooks-loader.ts`는 사용자의 정책 파일을 로드합니다:
 
 1. 설정에서 `customPoliciesPath`를 읽고, 없으면 건너뜁니다.
-2. 절대 경로로 변환하고 파일 존재 여부를 확인합니다.
-3. `customPolicies`가 동일한 `globalThis` 레지스트리로 해결될 수 있도록 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성합니다.
+2. 절대 경로로 확인하고 파일 존재 여부를 확인합니다.
+3. 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하여 `customPolicies`가 동일한 `globalThis` 레지스트리로 해결되도록 합니다.
 4. ESM 호환성을 보장하기 위해 전이적 로컬 임포트를 재귀적으로 재작성합니다.
 5. 임시 `.mjs` 파일을 작성하고 엔트리 파일을 `import()`합니다.
 6. `getCustomHooks()`를 호출하여 등록된 훅을 가져옵니다.
 7. `finally` 블록에서 모든 임시 파일을 정리합니다.
 
-오류 발생 시(파일 없음, 구문 오류, 임포트 실패), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 내장 정책에는 영향이 없습니다.
+오류 발생 시(파일 없음, 구문 오류, 임포트 실패), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 내장 정책은 영향을 받지 않습니다.
 
-커스텀 정책은 모든 내장 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책의 실행을 중단시키지만, 내장 정책은 그 시점에 이미 모두 실행된 상태입니다.
+커스텀 정책은 모든 내장 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책의 실행을 단락(short-circuit)시키지만, 이 시점에서 모든 내장 정책은 이미 실행된 상태입니다.
 
 ---
 
 ## 활동 로깅
 
-각 훅 이벤트 이후, 핸들러는 `~/.failproofai/hook-activity.jsonl`에 JSONL 한 줄을 추가합니다:
+각 훅 이벤트 후, 핸들러는 `~/.failproofai/hook-activity.jsonl`에 JSONL 줄을 추가합니다:
 
 ```json
 {
@@ -258,19 +258,19 @@ export function clearCustomHooks(): void { ... }  // 테스트에서 사용
 }
 ```
 
-non-allow 결정을 내린 정책당 한 줄이 기록됩니다. allow 결정은 파일 크기를 줄이기 위해 기록하지 않습니다.
+허용이 아닌 결정을 내린 정책당 한 줄씩 기록됩니다. 허용 결정은 기록하지 않습니다(파일 크기를 작게 유지하기 위함).
 
 ---
 
 ## 대시보드 아키텍처
 
-대시보드는 App Router와 React 서버 컴포넌트 및 서버 액션을 사용하는 **Next.js 16** 애플리케이션입니다.
+대시보드는 App Router를 사용하는 **Next.js 16** 애플리케이션으로, React 서버 컴포넌트와 서버 액션을 활용합니다.
 
 ```text
 app/
   layout.tsx                  ← 루트 레이아웃 (테마, 텔레메트리, 내비게이션)
   projects/page.tsx           ← 서버 컴포넌트: 모든 Claude 프로젝트 목록
-  project/[name]/page.tsx     ← 서버 컴포넌트: 프로젝트 내 세션 목록
+  project/[name]/page.tsx     ← 서버 컴포넌트: 프로젝트의 세션 목록
   project/[name]/session/
     [sessionId]/page.tsx      ← 서버 컴포넌트: 세션 뷰어 렌더링
   policies/page.tsx           ← 클라이언트 컴포넌트: 정책 관리 + 활동 로그
@@ -286,16 +286,16 @@ app/
 
 **데이터 흐름:**
 
-- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 파일시스템에서 직접 프로젝트/세션 데이터를 읽습니다 (읽기에는 API 레이어 없음).
+- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 API 레이어 없이 파일 시스템에서 직접 프로젝트/세션 데이터를 읽습니다.
 - 정책 페이지는 모든 변경 작업(토글, 파라미터 업데이트, 설치/제거)에 서버 액션을 사용합니다.
-- 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하고 메시지와 툴 호출의 타임라인을 렌더링합니다.
+- 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하여 메시지와 도구 호출의 타임라인을 렌더링합니다.
 
 **주요 설계 결정:**
 
-- 데이터베이스 없음 - 모든 영구 상태는 일반 파일에 저장됩니다 (`~/.failproofai/`, `~/.claude/projects/`).
-- 변경 작업에 서버 액션 사용 - CRUD 작업에 REST API가 필요 없습니다.
-- 읽기 페이지에 React 서버 컴포넌트 사용 - 초기 로드 속도 향상, 데이터 패칭을 위한 클라이언트 번들 불필요.
-- 상호작용이 필요한 곳에서만 클라이언트 컴포넌트 사용 (정책 토글, 활동 검색, 로그 뷰어).
+- 데이터베이스 없음 - 모든 영구 상태는 일반 파일(`~/.failproofai/`, `~/.claude/projects/`)에 저장됩니다.
+- 변경 작업에 서버 액션 사용 - CRUD 작업을 위한 REST API가 필요 없습니다.
+- 읽기 페이지에 React 서버 컴포넌트 사용 - 초기 로드가 빠르고 데이터 페칭을 위한 클라이언트 번들이 없습니다.
+- 상호작용이 필요한 경우에만 클라이언트 컴포넌트 사용 (정책 토글, 활동 검색, 로그 뷰어).
 
 ---
 
@@ -304,29 +304,29 @@ app/
 ```text
 failproofai/
 ├── bin/
-│   └── failproofai.mjs           # CLI 라우터 (hook / dashboard / install 등)
+│   └── failproofai.mjs           # CLI 라우터 (훅 / 대시보드 / 설치 등)
 ├── src/hooks/
 │   ├── handler.ts                # 훅 이벤트 파이프라인
-│   ├── builtin-policies.ts       # 26개의 정책 정의
+│   ├── builtin-policies.ts       # 26개 정책 정의
 │   ├── policy-evaluator.ts       # 정책 실행 엔진
 │   ├── policy-registry.ts        # 정책 등록 및 조회
 │   ├── policy-types.ts           # TypeScript 인터페이스
 │   ├── hooks-config.ts           # 다중 범위 설정 로딩
 │   ├── custom-hooks-registry.ts  # globalThis 기반 훅 레지스트리
 │   ├── custom-hooks-loader.ts    # 사용자 JS 훅을 위한 ESM 로더
-│   ├── manager.ts                # 설치 / 제거 / 목록 조회 작업
+│   ├── manager.ts                # 설치 / 제거 / 목록 작업
 │   ├── install-prompt.ts         # 대화형 정책 선택 프롬프트
 │   ├── hook-logger.ts            # hook.log에 로깅
 │   ├── hook-activity-store.ts    # hook-activity.jsonl에 활동 저장
 │   └── llm-client.ts             # LLM API 클라이언트 (AI 기반 정책용)
 ├── app/                          # Next.js 대시보드 (페이지 + 서버 액션)
 ├── lib/                          # 공유 유틸리티
-│   ├── projects.ts               # 파일시스템에서 Claude 프로젝트 열거
+│   ├── projects.ts               # 파일 시스템에서 Claude 프로젝트 열거
 │   ├── log-entries.ts            # Claude 트랜스크립트 JSONL 형식 파싱
 │   ├── paths.ts                  # 시스템 경로 해결
 │   └── ...
 ├── components/                   # 공유 React UI 컴포넌트
 ├── contexts/                     # React 컨텍스트 프로바이더 (테마, 자동 새로고침, 텔레메트리)
-├── examples/                     # 커스텀 훅 파일 예제
+├── examples/                     # 커스텀 훅 파일 예시
 └── __tests__/                    # 단위 및 E2E 테스트
 ```

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

@@ -4,25 +4,25 @@ description: "설정 파일 형식, 세 가지 범위 시스템, 그리고 병
 icon: gear
 ---
 
-failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 커스텀 정책을 어디서 로드할지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되었습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다.
+failproofai는 JSON 설정 파일을 사용하여 어떤 정책을 활성화할지, 정책이 어떻게 동작할지, 그리고 커스텀 정책을 어디서 불러올지를 제어합니다. 설정은 팀과 공유하기 쉽도록 설계되어 있습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다.
 
 ---
 
 ## 설정 범위
 
-설정 범위는 세 가지이며, 우선순위 순서대로 평가됩니다:
+우선순위 순서로 평가되는 세 가지 설정 범위가 있습니다:
 
 | 범위 | 파일 경로 | 용도 |
-|-------|-----------|---------|
+|------|-----------|------|
 | **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 |
-| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 오버라이드, gitignore 처리 |
+| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 재정의, gitignore 처리 |
 | **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 적용되는 사용자 수준 기본값 |
 
-failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 로드하여 병합합니다.
+failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 불러와 병합합니다.
 
 ### 병합 규칙
 
-**`enabledPolicies`** - 세 범위의 합집합입니다. 어느 한 수준에서라도 활성화된 정책은 적용됩니다.
+**`enabledPolicies`** - 세 범위 모두의 합집합입니다. 어느 레벨에서든 활성화된 정책은 유효합니다.
 
 ```text
 project:  ["block-sudo"]
@@ -32,7 +32,7 @@ global:   ["block-sudo", "sanitize-api-keys"]
 resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 중복 제거된 합집합
 ```
 
-**`policyParams`** - 특정 정책의 파라미터를 처음으로 정의한 범위가 전적으로 우선합니다. 정책 파라미터 내부의 값은 깊은 병합이 이루어지지 않습니다.
+**`policyParams`** - 해당 정책의 파라미터를 가장 먼저 정의한 범위가 완전히 우선합니다. 정책 파라미터 내부의 값은 깊은 병합(deep merge)이 수행되지 않습니다.
 
 ```text
 project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
@@ -46,12 +46,12 @@ project:  (block-sudo 항목 없음)
 local:    (block-sudo 항목 없음)
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 
-resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 폴스루
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 전달됨
 ```
 
-**`customPoliciesPath`** - 처음으로 정의한 범위가 우선합니다.
+**`customPoliciesPath`** - 가장 먼저 정의한 범위가 우선합니다.
 
-**`llm`** - 처음으로 정의한 범위가 우선합니다.
+**`llm`** - 가장 먼저 정의한 범위가 우선합니다.
 
 ---
 
@@ -102,7 +102,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 폴스
 
 타입: `string[]`
 
-활성화할 정책 이름 목록입니다. 이름은 `failproofai policies`가 표시하는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요.
+활성화할 정책 이름 목록입니다. 이름은 `failproofai policies`에서 표시하는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요.
 
 `enabledPolicies`에 포함되지 않은 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다.
 
@@ -110,19 +110,19 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 폴스
 
 타입: `Record<string, Record<string, unknown>>`
 
-정책별 파라미터 오버라이드입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에 문서화되어 있습니다.
+정책별 파라미터 재정의입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에 문서화되어 있습니다.
 
-정책에 파라미터가 있지만 별도로 지정하지 않으면 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다.
+파라미터가 있는 정책에 대해 별도로 지정하지 않으면 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일한 동작을 경험합니다.
 
-정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시에는 조용히 무시되지만, `failproofai policies`를 실행하면 경고로 표시됩니다.
+정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시 자동으로 무시되지만, `failproofai policies` 실행 시 경고로 표시됩니다.
 
-#### `hint` (공통 설정)
+#### `hint` (공통 옵션)
 
 타입: `string` (선택 사항)
 
-정책이 `deny` 또는 `instruct`를 반환할 때 사유에 덧붙여지는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공할 수 있습니다.
+정책이 `deny` 또는 `instruct`를 반환할 때 이유(reason)에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실질적인 지침을 제공할 수 있습니다.
 
-기본 제공 정책, 커스텀 정책(`custom/`), 프로젝트 컨벤션 정책(`.failproofai-project/`), 사용자 컨벤션 정책(`.failproofai-user/`) 등 모든 정책 유형에서 동작합니다.
+기본 제공, 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 사용할 수 있습니다.
 
 ```json
 {
@@ -141,40 +141,40 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 폴스
 }
 ```
 
-`block-force-push`가 거부할 때, Claude는 다음을 보게 됩니다: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+`block-force-push`가 차단할 때 Claude는 다음을 확인합니다: *"Force-pushing is blocked. Try creating a fresh branch instead."*
 
-문자열이 아닌 값과 빈 문자열은 조용히 무시됩니다. `hint`를 설정하지 않으면 동작이 변경되지 않습니다(하위 호환성 유지).
+문자열이 아닌 값과 빈 문자열은 자동으로 무시됩니다. `hint`가 설정되지 않으면 동작이 변경되지 않습니다(이전 버전과 호환).
 
 ### `customPoliciesPath`
 
 타입: `string` (절대 경로)
 
-커스텀 훅 정책이 담긴 JavaScript 파일 경로입니다. `failproofai policies --install --custom <path>` 명령으로 자동 설정되며, 저장 전에 절대 경로로 변환됩니다.
+커스텀 훅 정책이 포함된 JavaScript 파일의 경로입니다. `failproofai policies --install --custom <path>`를 실행하면 자동으로 설정됩니다(저장 전에 절대 경로로 변환됨).
 
-파일은 매 훅 이벤트마다 새로 로드됩니다. 캐싱은 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참조하세요.
+파일은 매 훅 이벤트마다 새로 불러오며, 캐싱이 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참조하세요.
 
 ### 컨벤션 기반 정책
 
-명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉터리에서 정책 파일을 자동으로 검색하여 로드합니다:
+명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉터리에서 정책 파일을 자동으로 검색하여 불러옵니다:
 
-| 수준 | 디렉터리 | 범위 |
-|-------|-----------|-------|
+| 레벨 | 디렉터리 | 범위 |
+|------|----------|------|
 | 프로젝트 | `.failproofai/policies/` | 버전 관리를 통해 팀과 공유 |
 | 사용자 | `~/.failproofai/policies/` | 개인용, 모든 프로젝트에 적용 |
 
-**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 로드됩니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉터리 내 다른 파일은 무시됩니다.
+**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 불러옵니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉터리 내 다른 파일은 무시됩니다.
 
-**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 별도 항목이 필요하지 않습니다. 해당 디렉터리에 파일을 넣기만 하면 다음 훅 이벤트에서 자동으로 인식됩니다.
+**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 별도의 항목이 필요하지 않습니다. 디렉터리에 파일을 추가하기만 하면 다음 훅 이벤트 시 자동으로 반영됩니다.
 
-**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉터리가 모두 검색됩니다. 두 수준의 일치하는 파일이 모두 로드됩니다(`customPoliciesPath`는 첫 번째 범위가 우선하는 것과 다릅니다).
+**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉터리 모두 검색합니다. 두 레벨에서 일치하는 파일이 모두 로드됩니다(`customPoliciesPath`는 첫 번째 범위 우선 방식을 사용하는 것과 다름).
 
-자세한 내용과 예시는 [커스텀 정책](/ko/custom-policies)을 참조하세요.
+자세한 내용과 예제는 [커스텀 정책](/ko/custom-policies)을 참조하세요.
 
 ### `llm`
 
 타입: `object` (선택 사항)
 
-AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 경우에는 필요하지 않습니다.
+AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 설정에서는 필요하지 않습니다.
 
 ```json
 {
@@ -187,20 +187,20 @@ AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다.
 
 ---
 
-## CLI로 설정 관리하기
+## CLI에서 설정 관리하기
 
-`policies --install` 및 `policies --uninstall` 명령은 Claude Code의 `settings.json`(훅 진입점)에 기록하고, `policies-config.json`은 직접 관리하는 파일입니다. 두 파일은 별개입니다:
+`policies --install` 및 `policies --uninstall` 명령은 Claude Code의 `settings.json`(훅 진입점)에 기록하며, `policies-config.json`은 직접 관리하는 파일입니다. 두 파일은 별개입니다:
 
-- **`settings.json`** - 각 도구 사용 시 Claude Code가 `failproofai --hook <event>`를 호출하도록 지시
+- **`settings.json`** - Claude Code가 각 도구 사용 시 `failproofai --hook <event>`를 호출하도록 지시
 - **`policies-config.json`** - failproofai가 어떤 정책을 어떤 파라미터로 평가할지 지시
 
-`policies-config.json`은 언제든지 직접 편집할 수 있으며, 변경 사항은 재시작 없이 다음 훅 이벤트에서 즉시 반영됩니다.
+`policies-config.json`은 언제든지 직접 편집할 수 있으며, 변경 사항은 재시작 없이 다음 훅 이벤트 시 즉시 적용됩니다.
 
 ---
 
 ## 예시: 팀 기본값이 포함된 프로젝트 수준 설정
 
-`.failproofai/policies-config.json`을 저장소에 커밋하세요:
+`.failproofai/policies-config.json`을 저장소에 커밋합니다:
 
 ```json
 {
@@ -219,4 +219,4 @@ AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다.
 }
 ```
 
-각 개발자는 `.failproofai/policies-config.local.json`(gitignore 처리)을 생성하여 팀원에게 영향을 주지 않고 개인 오버라이드를 적용할 수 있습니다.
+각 개발자는 `.failproofai/policies-config.local.json`(gitignore 처리됨)을 생성하여 팀원에게 영향을 주지 않고 개인 설정을 재정의할 수 있습니다.