> ## 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.

# 시작하기

> failproofai를 설치하고, 정책을 활성화하여 에이전트를 안정적으로 실행하세요

## 요구 사항

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (선택 사항 - 소스에서 빌드할 때만 필요)

***

## 설치

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## 빠른 시작

<Steps>
  <Step title="정책 활성화">
    정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 시크릿 유출, 그 외 여러 장애 상황을 피해가 발생하기 전에 차단합니다.

    ```bash theme={null}
    failproofai policies --install
    ```

    이 명령은 설치된 에이전트 CLI에 훅 항목을 기록합니다 (Claude Code의 `~/.claude/settings.json`, OpenAI Codex의 `~/.codex/hooks.json`, GitHub Copilot CLI의 `~/.copilot/hooks/failproofai.json`, Cursor Agent의 `~/.cursor/hooks.json`, OpenCode의 `~/.config/opencode/plugins/failproofai.mjs` 생성 플러그인 심 및 `~/.config/opencode/opencode.json`의 `plugin` 배열 등록 항목, Pi의 `~/.pi/agent/settings.json`, Hermes의 `~/.hermes/config.yaml`). 둘 이상의 CLI가 설치되어 있으면 선택 프롬프트가 표시됩니다. `--cli claude codex copilot cursor opencode pi hermes` (원하는 조합)를 전달하면 프롬프트를 건너뜁니다.

    GitHub Copilot CLI, Cursor Agent, OpenCode, Pi 지원은 **베타** 단계입니다 — `--cli copilot`, `--cli cursor`, `--cli opencode`, 또는 `--cli pi`로 설치하세요. Hermes (hermes-agent, Slack/Telegram 게이트웨이)는 `--cli hermes`로 사용자 범위에 설치되며 오프라인 감사 소스이기도 합니다.

    ```bash theme={null}
    failproofai policies --install --scope project
    failproofai policies --install --cli codex --scope project
    failproofai policies --install --cli copilot --scope project
    failproofai policies --install --cli cursor --scope project
    failproofai policies --install --cli opencode --scope project
    failproofai policies --install --cli pi --scope project
    failproofai policies --install --cli hermes --scope user
    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
    ```
  </Step>

  <Step title="확인">
    ```bash theme={null}
    failproofai policies
    ```

    모든 정책과 활성화 여부, 설정된 파라미터를 표시합니다.
  </Step>

  <Step title="대시보드 실행">
    ```bash theme={null}
    failproofai
    ```

    `http://localhost:8020`에 로컬 대시보드를 열어 세션을 탐색하고, 도구 호출을 검사하며, 정책을 관리할 수 있습니다.
  </Step>

  <Step title="에이전트 실행">
    평소처럼 Claude Code를 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 차단합니다. 에이전트를 무인으로 실행한 후 대시보드에서 결과를 확인하세요.
  </Step>
</Steps>

***

## 정책 작동 방식

에이전트가 도구를 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다.

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

각 정책은 다음 세 가지 결정 중 하나를 반환합니다.

* **allow** - 에이전트가 정상적으로 진행됩니다
* **deny** - 작업이 차단되고 에이전트에게 이유가 전달됩니다
* **instruct** - 에이전트의 프롬프트에 추가 컨텍스트가 삽입됩니다

<Note>
  정책은 로컬 프로세스에서 실행됩니다. 원격 서비스로는 아무것도 전송되지 않습니다.
</Note>

***

## 컨벤션 기반 정책으로 팀 정책 설정하기

팀 전체에 품질 기준을 빠르게 적용하는 방법은 `.failproofai/policies/` 컨벤션을 활용하는 것입니다. 이 디렉터리에 정책 파일을 넣으면 자동으로 로드됩니다 — 별도의 플래그, 설정 변경, 설치 명령이 필요 없습니다.

<Steps>
  <Step title="정책 디렉터리 생성">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="정책 파일 추가">
    스타터 예제를 복사하거나 직접 작성하세요.

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    또는 새로 작성하세요.

    ```js theme={null}
    // .failproofai/policies/team-policies.mjs
    import { customPolicies, allow, deny, instruct } from "failproofai";

    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("Run tests before committing.");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="git에 커밋">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    failproofai를 설치한 모든 팀원이 이 정책을 자동으로 적용받습니다. 개발자별 별도 설정이 필요 없습니다.
  </Step>
</Steps>

<Tip>
  `.failproofai/policies/`를 저장소에 커밋하면 팀 전체가 동일한 기준을 공유할 수 있습니다. 팀이 새로운 장애 유형을 발견할 때마다 정책을 추가하고 푸시하세요 — 모든 팀원이 다음 `git pull` 시 업데이트를 받습니다. 시간이 지남에 따라 이 정책들은 지속적으로 발전하는 살아있는 품질 기준이 됩니다.
</Tip>

***

## 데이터 저장

모든 설정과 로그는 로컬 머신에 저장됩니다.

| 경로                                        | 저장 내용                    |
| ----------------------------------------- | ------------------------ |
| `~/.failproofai/policies-config.json`     | 전역 정책 설정                 |
| `~/.failproofai/hook-activity.jsonl`      | 훅 실행 이력                  |
| `~/.failproofai/hook.log`                 | 커스텀 훅 오류 디버그 로그          |
| `.failproofai/policies-config.json`       | 프로젝트별 설정 (커밋됨)           |
| `.failproofai/policies-config.local.json` | 개인 오버라이드 (gitignore 처리됨) |

***

## 제거

```bash theme={null}
failproofai policies --uninstall
```

`~/.claude/settings.json`에서 훅 항목을 제거합니다. `~/.failproofai/`의 설정 파일은 유지됩니다.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="설정" icon="gear" href="/ko/configuration">
    범위 및 설정 파일 형식
  </Card>

  <Card title="기본 제공 정책" icon="shield" href="/ko/built-in-policies">
    파라미터가 있는 26가지 정책 전체 목록
  </Card>

  <Card title="커스텀 정책" icon="code" href="/ko/custom-policies">
    JavaScript로 나만의 정책 작성하기
  </Card>

  <Card title="에이전트 모니터" icon="chart-line" href="/ko/dashboard">
    세션 모니터링 및 정책 활동 검토
  </Card>
</CardGroup>