bande-a-bonnot/boucle-framework구조화된 메모리, 안전 후크, 루프 관리를 갖춘 자율 에이전트 프레임워크. 그 위에서 실행되는 에이전트에 의해 구축되었습니다.
실제로 규칙을 강제하는 Claude Code 후크입니다. 7개의 독립 실행형 후크와 CLAUDE.md 정책을 위한 enforce-hooks, 감사 도구, 1,900개 이상의 테스트, 심각도 등급과 해결 방법이 포함된 검색 가능한 Claude Code 격차 코퍼스가 있습니다.
빠른 링크: 설정 확인 · 후크 설치 · 알려진 제한 사항 · JSON 내보내기 · 빠른 시작 · 분류 · 업데이트 체크리스트 · 안전 지원 증거 · 지원 예제 · 읽기 전용 감사 · 개별 후크 · 플랫폼 지원 · 권장 Claude Code 버전 · 문제 해결 · Boucle 프레임워크 (선택 사항, 자율 에이전트용)
Claude Code의 CLAUDE.md 규칙은 읽히지만 강제되지 않습니다 — 세션 시작 시에는 작동하지만 컨텍스트가 커짐에 따라 성능이 저하됩니다. 권한 시스템에는 알려진 격차가 있습니다 — 와일드카드가 복합 명령어와 일치하지 않으며, 거부 규칙은 파이프 세그먼트를 확인하지 못하고 여러 줄 주석으로 우회될 수 있습니다. 이러한 후크는 텍스트 규칙과 권한이 할 수 없는 경계를 강제합니다.
후크가 위험한 명령을 차단할 때:``` Claude tries: rm -rf ~/projects bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss. Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...
프롬프트 없음, "확실합니까?" 대화상자 없음. 명령이 실행되지 않습니다.
<a id="check-your-setup"></a>
**현재 설정 확인:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
이 명령은 Claude Code를 시작하는 프로젝트 루트에서 실행하세요. 프로젝트 훅은 현재 디렉터리에서 확인되므로, 하위 디렉터리에서 실행하면 리포지토리 루트의 .claude/settings.json을 찾지 못할 수 있습니다. 이미 git checkout 내부에 있다면:```sh
cd "$(git rev-parse --show-toplevel)"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
A부터 F까지 Claude Code 안전 구성을 점수로 매기고 각 격차에 대한 한 줄 수정 사항을 표시합니다. `--verify`를 추가하여 각 후크에 테스트 페이로드를 전송하고 실제로 차단하는지 확인합니다:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify
CI 또는 스크립트 기반 워크스테이션 점검의 경우, 검증 시 FAIL-OPEN 훅, 손상된 훅 파일, 건너뛴 PreToolUse 검사, 훅 없음, 또는 페이로드 검사 없음이 발견되면 실패합니다:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict
[스크립트 검사 가이드](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/CI.md)를 사용하여 GitHub Actions, 개발자 워크스테이션 검사, 종료 코드, CI로 증명할 수 있는 한계에 대해 알아보세요.
검사는 훅 설치, 훅 상태(누락/실행 불가능한 스크립트), 실시간 확인(`rm -rf /`를 bash-guard에 보내고, `git push --force`를 git-safe에 보내는 등 차단 여부 확인), enforce-hooks 및 CLAUDE.md의 `@enforced` 규칙, 환경 문제(IS_DEMO, JSONC 설정, jq/python3 의존성, Windows 훅 안정성), 알려진 CLI 버전 회귀를 다룹니다. 사용자 수준(`~/.claude/settings.json`) 및 프로젝트 수준(`.claude/settings.json`) 설정을 모두 스캔하며, 프레임워크 훅뿐만 아니라 사용자 정의/서드파티 훅도 보여주는 훅 인벤토리를 제공합니다. 요약에는 `enforce-hooks` 정책 훅이 포함되어 있어 8개의 프레임워크 훅 슬롯이 계산됩니다. `install.sh all`은 아래 나열된 7개의 독립 실행형 훅을 설치합니다. 또한, deny 규칙이 bash-guard 없이 구성된 경우 경고합니다. deny 패턴은 [복합 명령어 및 멀티라인 스크립트에 의해 우회될 수 있기 때문입니다](https://github.com/anthropics/claude-code/issues/38119). 감사에는 훅 설치가 필요하지 않습니다. 수백 개의 테스트로 검증되었습니다.
감사에서 검증된 훅으로 이동하는 10분 경로는 [안전 검사 빠른 시작](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/QUICKSTART.md)을 참조하세요.
도움이 필요하면 [안전 지원 증거 가이드](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/SUPPORT_EVIDENCE.md)를 사용하여 개인 설정이나 비밀을 노출하지 않고 요약 블록을 공유하세요. 해당 경계가 있는 공개 블록만 출력하려면 다음을 실행하세요:
```shell
cat <<'EOF'
{{- hook_inventory }}
EOF
``````sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only
안전한 공개 보고서와 피해야 할 안전하지 않은 스니펫의 예시를 보려면 다음을 참조하세요. 안전한 지원 예시.
업스트림 Claude Code 훅 및 권한 격차에 대해서는 다음을 사용하세요. 검색 가능한 제한 사항 페이지, 기계 판독 가능 JSON 내보내기, 또는 Atom 피드.
macOS / Linux 요구 사항: bash, python3, jq. 설치 프로그램은
python3를 사용하여 Claude Code settings.json을 관리하고, safety-check는 python3를 사용하여
감사를 수행하며, 대부분의 독립형 셸 훅은 jq를 사용하여 Claude Code 훅 페이로드를 파싱합니다.
필수 사항부터 시작하세요 (bash-guard + git-safe + file-guard):```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended
이 세 가지 훅은 모든 Claude Code 사용자가 가져야 할 안전망을 구성합니다: 위험한 명령 차단, 파괴적인 git 작업 방지, 민감한 파일 보호. 설치 후, 위의 안전 점검을 `--verify`와 함께 실행하여 각 훅이 의도한 대로 차단하는지 확인하십시오.
**설치가 성공했지만 훅이 아무것도 차단하지 않는 경우:**
- macOS/Linux에서는 `install.sh check --verify --strict`를 먼저 실행하고 (네이티브 Windows에서는 `install.ps1 verify`). 깔끔한 설치가 훅이 작동 중임을 증명하지는 않습니다.
- 다음으로 `install.sh doctor`를 실행하십시오 (Windows에서는 `install.ps1 doctor`). 누락된 파일, 잘못된 권한, `settings.json`의 JSONC 및 기타 자동 실패 열림 상태 등을 포착합니다.
- Windows에서는 Windows PowerShell 5가 아닌 PowerShell 7 (`pwsh`)을 사용하십시오.
- 사용자 정의 거부 훅을 작성하는 경우, 하드 블록에는 `stderr` + `exit 2`를 선호하십시오. JSON `permissionDecision: "deny"`는 Claude Code 표면에서 여전히 일관성이 없습니다.
**모든 훅을 한 번에 설치:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Windows (PowerShell 7+) — 네이티브 PS1 후크, bash나 jq가 필요하지 않습니다. PowerShell 7 (pwsh)이 필요하며, 내장된 Windows PowerShell 5가 아닙니다. 동일한 권장 안전 세트로 시작하십시오:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"
또는 모든 독립형 훅을 한 번에 설치하세요:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
훅 관리:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- list
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- upgrade
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall read-once
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall all
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- backup
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- restore