설치 · 커맨드 여덟 개 · 무엇이 막히나 · 막히면 어떻게 되나 · 왜 필요한가 · 누구에게 좋은가 · 오탐 · 끄기와 제거 · 더 읽기 · 근거 · 비슷한 도구
읽기: 한국어 · English
Claude Code와 Codex 작업의 신뢰성을 높입니다.
검증된 모범 사례를 커맨드와 스킬 여덟 개가 절차로 풀어 주고, 게이트 네 개가 지켜졌는지 턴마다 검사해 지키지 않은 답으로는 턴이 끝나지 않게 합니다. 근거는 Claude Code 공식 문서를 비롯한 검증된 자료에 있고, 규칙은 항목마다 끌 수 있습니다.
심사관은 대신 조종하지 않습니다. 절차를 짚어 주고, 기준을 벗어나면 그 자리에서 멈춥니다.
| 무엇을 하나 | 언제 도나 | |
|---|---|---|
| 커맨드 여덟 개 | 무엇을 어떤 순서로 할지 알려 줍니다 | 직접 쳐야 돕니다 |
| 게이트 네 개 | 모범 사례를 지키지 않은 답으로는 턴이 끝나지 않게 합니다 | 훅 신뢰 승인 뒤 자동 실행 |
커맨드는 이렇게 절차를 끌고 갑니다. /checkride:full-cycle 하나가 탐색부터 PR까지 다섯 단계를 밟고, 검토에서 결함이 나오면 구현으로 되돌아갑니다.
/checkride:config로 항목의 출처를 보고 고르면 그 선택이 checkride.toml에 적히고 커밋에 남으므로, 무엇을 껐는지 팀이 함께 봅니다. 테스트 무결성·완료 게이트에서 오탐 한 건만 넘기려면 다음 프롬프트에 check allow <항목>을 한 줄로 쓰면 됩니다. 자세한 방법은 끄기와 제거에 있습니다.
사용자가 한 번도 부탁하지 않아도 매번 검사합니다. 되묻는 일은 훅이 맡고, 사용자는 결과를 판단하는 데 집중하면 됩니다.
왜 부탁이 아니라 훅으로 만들었는지는 왜 필요한가에 적었습니다.
이 플러그인은 자기 자신에게도 예외를 두지 않습니다. 아래는 실제 사용 중에 게이트가 이 에이전트를 막았던 사례 네 건입니다. 도구를 하나도 쓰지 않은 채 "테스트 있어?"에 답하려다 R0에, 파일을 열어 보지도 않고 단정하려다 R1에, 확인할 수 있는 로컬 상태를 "~처럼 보인다"라고 얼버무리려다 R2b에, 테스트를 돌리지도 않고 통과했다고 주장하려다 R3에 걸렸습니다. 네 번 모두 막힌 뒤에야 파일과 원문과 실행 출력을 직접 확인하고 다시 답했습니다.
여기 담긴 것이 전부가 아닙니다. 네 건은 모두 근거 게이트가 막은 것이고, 그나마도 그 게이트가 가진 규칙 여섯 개 가운데 네 개입니다. 나머지 규칙과 다른 게이트 세 개가 각각 무엇을 막는지는 무엇이 막히나에 전부 적어 두었습니다.
여러 프로젝트에서 실제로 쓰는 동안, 게이트는 답을 898번 검사해 그중 69번을 막았습니다. 파일 상태를 확인하지 않고 답하는 R0과 로컬 상태를 추측하는 R2b가 대부분을 차지합니다. 이 수치를 세는 명령과 원문은 검증 기록에 있습니다.
Claude Code 세션 안에서 다음 두 줄을 입력하면 됩니다.
/plugin marketplace add IsthisLee/checkride
/plugin install checkride@checkride
내려받는 것은 plugin/ 아래 파일뿐이고, 릴리스 태그에는 서명이 붙어 있습니다. 서명을 직접 확인하는 법은 SECURITY.md에 있습니다.
사용자의 settings.json과 CLAUDE.md는 한 글자도 바뀌지 않습니다. 설치해도 평소와 똑같고, 검사는 무언가에 걸릴 때만 나타납니다.
턴마다 약 256ms가 더 붙습니다. 훅별로 실측한 값은 상세 문서에 있습니다.
필요한 것은 bash와 python3 두 가지입니다. macOS · Linux · Windows 세 곳 모두 CI에서 매번 단위 테스트를 돌립니다. 망가진 입력을 던지는 fuzz 테스트는 Linux·macOS에서는 매번 돌고, Windows에서는 main에 올라갈 때 돕니다. Windows에서는 Git Bash가 설치돼 있어야 합니다.
프로젝트 훅이 목적이면 npx skills add는 필요하지 않습니다. Checkride 플러그인을 설치하면 해당 도구의 훅과 함께 플러그인에 포함된 스킬도 등록됩니다. 훅만 따로 고르는 설치 옵션은 없습니다. 스킬을 실행하지 않으면 훅만 사용하면 됩니다.
팀원마다 플러그인을 설치하게 하지 않으려면, 저장소 관리자가 한 번 훅 코드를 저장소에 복사하고 프로젝트 설정을 커밋합니다. Checkride 플러그인을 설치한 관리자가 대상 저장소에서 다음 명령을 실행합니다.
bash "$(find ~/.claude/plugins ~/.codex/plugins -path '*/setup-project-hooks.sh' -print -quit 2>/dev/null)"이 명령은 .checkride/hooks/에 훅 코드를 넣고 .claude/settings.json과 .codex/hooks.json에 프로젝트 훅을 병합합니다. 설정 파일의 다른 키와 서식은 유지하고, 재실행해도 Checkride 훅을 중복 등록하지 않습니다. 런타임 상태와 check allow 일회 허용 값은 저장소 밖의 사용자 데이터 디렉터리에 두므로 Git에 올라가지 않습니다. .checkride/README.md의 설치·갱신 안내를 읽고, 생성·수정된 파일을 검토한 뒤 저장소에 커밋합니다.
그다음 팀원은 저장소를 각 도구에서 신뢰한 뒤 훅을 검토해야 합니다. Claude Code는 대화형 세션에서 저장소 설정의 훅을 실행하기 전에 작업공간 신뢰를 확인합니다. Codex는 먼저 저장소의 .codex/ 설정 계층을 신뢰해야 하고, /hooks에서 새 훅 정의를 검토·신뢰해야 실행합니다. 이 두 신뢰 확인은 서로 다른 단계입니다. 훅 정의가 바뀌거나 경로가 다른 체크아웃·worktree를 열면 Codex가 다시 검토를 요구할 수 있습니다. --dangerously-bypass-hook-trust는 자동화에서 한 번 신뢰 검사를 건너뛰는 용도이지 팀 설치 절차가 아닙니다. 이 저장소 훅만 쓸 팀원은 Checkride 플러그인을 설치하지 않아도 됩니다. 저장소 관리 훅이 있으면 플러그인 훅은 자동으로 건너뛰므로 둘이 중복 실행되지 않습니다.
Codex CLI 0.156.1에서 새 Git 저장소의 .codex/hooks.json이 codex exec --dangerously-bypass-hook-trust에서도 실행되지 않는 것을 확인했습니다. Codex는 프로젝트 .codex/ 계층을 신뢰하지 않으면 프로젝트 훅을 읽지 않습니다. 이 플래그는 훅 정의 신뢰만 한 번 우회하며 프로젝트 신뢰를 대신하지 않습니다. 반대로 이 저장소를 신뢰하고 /hooks에서 새 Checkride 훅을 검토·신뢰한 뒤에는 codex exec가 별도 우회 플래그 없이 SessionStart 프로젝트 훅을 실행했습니다. 자동화 실행기에도 프로젝트 신뢰와 현재 훅 정의 신뢰가 미리 저장되어 있어야 합니다. 비대화형 실행은 승인 화면을 띄우지 않습니다. Codex 훅 문서 (확인일: 2026-09-28).
이 경로는 훅 코드와 설정을 저장소가 소유합니다. 업데이트할 때 관리자가 Checkride 플러그인을 갱신한 뒤 위 명령을 다시 실행하고, 변경을 검토·커밋해야 합니다. 이 스크립트는 실행 가능한 훅 코드를 저장소에 복사하므로 반드시 내용을 검토한 뒤 신뢰하세요. 완료 게이트의 test_command와 fast_test_command도 저장소에서 제공한 명령을 실행합니다. 팀에서 공유하기 전에 그 스크립트·패키지 매니페스트·테스트 설정이 훅 실행 환경에서 무엇을 하는지 검토해야 합니다.
checkride.toml은 Git 저장소 루트 파일만 적용됩니다. 하위 패키지별 설정이 루트의 검사 명령이나 규칙을 덮지 않습니다. 모노레포에서는 루트 명령에 turbo run test, nx affected -t test처럼 전체 또는 영향받은 패키지의 검사를 위임하고, 실제 검사 스크립트는 각 패키지에 둡니다. Git 저장소가 아닌 독립 폴더에서는 가장 가까운 checkride.toml을 읽습니다.
공유 설정에서 에이전트의 규칙 변경을 줄이려면 Claude Code의 Edit deny 또는 OS 샌드박스를 검토할 수 있습니다. Read deny는 읽기와 편집을 함께 막으므로 checkride.toml처럼 에이전트가 읽어야 할 파일에 그대로 적용하지 마세요. Codex의 sandbox_workspace_write.writable_roots는 쓰기 허용 경로를 추가하는 설정이지 거부 목록이 아닙니다. 어느 도구의 편집 권한 규칙도 임의 자식 프로세스를 전부 막는 OS 경계와 같다고 보지 마세요. Codex에서 모든 작업 파일 쓰기를 막아야 한다면 read-only 샌드박스를 쓰되, 그 세션에서는 에이전트의 일반 파일 수정도 제한됩니다.
팀이 프로젝트 설정을 공유하려면 저장소의 .claude/settings.json에 마켓플레이스와 플러그인을 선언합니다.
{
"extraKnownMarketplaces": {
"checkride": {
"source": { "source": "github", "repo": "IsthisLee/checkride" }
}
},
"enabledPlugins": { "checkride@checkride": true }
}그다음 각 팀원이 자기 환경에서 한 번 프로젝트 범위로 플러그인을 설치합니다.
claude plugin install checkride@checkride --scope project저장소 설정은 팀에 플러그인과 마켓플레이스를 알리고 활성화하지만, 외부 플러그인 파일을 다른 사람의 컴퓨터에 대신 설치하지는 않습니다. 프로젝트 설정을 커밋하면 협업자 전체에 적용되고, --scope project 설치는 그 프로젝트에만 적용됩니다.
Codex에서는 대상 저장소에 .agents/plugins/marketplace.json과 .codex/config.toml을 커밋합니다. 이 저장소의 .agents/plugins/marketplace.json에는 Checkride 원격 플러그인 항목이 있고, .codex/config.toml은 프로젝트에서 이를 켭니다.
다른 저장소에서는 .agents/plugins/marketplace.json에 다음 항목을 추가합니다.
{
"name": "checkride",
"plugins": [
{
"name": "checkride",
"source": {
"source": "git-subdir",
"url": "https://github.com/IsthisLee/checkride.git",
"path": "./plugin"
},
"policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
"category": "Productivity"
}
]
}.codex/config.toml에는 다음을 넣습니다.
[plugins."checkride@checkride"]
enabled = true각 Codex 사용자는 마켓플레이스를 한 번 등록합니다.
codex plugin marketplace add IsthisLee/checkrideCodex가 프로젝트 설정을 읽으려면 해당 저장소를 신뢰해야 하며, 훅 정의도 /hooks에서 검토·신뢰해야 실행됩니다. .codex/config.toml의 프로젝트 신뢰와 훅 정의 신뢰는 별개입니다. 변경된 훅은 다시 검토 대상이 될 수 있고, checkout/worktree마다 절대 경로가 달라지면 별도로 승인해야 할 수 있습니다.
Codex 훅은 SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop에 연결됩니다. Bash와 apply_patch의 변경은 검사하고, 지원되는 파일 변경 인자를 가진 MCP/local-function 도구는 경로를 알아낼 수 있는 입력만 검사합니다. 파일 경로를 해석할 수 없는 도구는 자동으로 안전하다고 간주하지 않습니다. 현재 훅 신뢰 상태는 Codex의 /hooks 화면에서 확인하세요.
Codex의 Bash PostToolUse.tool_response에는 명령 출력만 있고 종료 상태가 없습니다. 어댑터는 PreToolUse에서 transcript 파일의 위치를 기록하고 PostToolUse에서 그 뒤에 추가된 레코드만 읽습니다. 새 CommandExecution이 하나뿐이고 실행 인자의 마지막 문자열이 요청한 명령과 일치하며 정수 exit_code가 있으면 Bash 성공·실패를 R5에 기록합니다. transcript가 없거나, 아직 기록되지 않았거나, 여러 실행이 겹치거나, 형식·명령이 맞지 않거나 새 기록이 1 MiB를 넘으면 ?를 기록해 판정하지 않습니다. Codex는 transcript 형식을 훅의 안정된 계약으로 보장하지 않으므로 R5는 최선 노력 방식이며 모든 Codex 실행에서 보장되지는 않습니다. Claude Code에서는 PostToolUseFailure 이벤트로 안정된 실패 정보를 받습니다. Codex 훅 계약에 종료 상태가 빠진 문제는 OpenAI Codex 이슈 #34289에서 추적 중입니다.
Codex의 Stop 훅은 stop_hook_active가 참인 재진입에서도 근거·완료 게이트를 다시 실행합니다. 자동 continuation 프롬프트가 들어오면 원래 사용자 질문을 보존해 로컬 맥락 검사도 이어 갑니다. Checkride는 재검사·차단을 최대 여덟 번 이어 갑니다. 여덟 번째 재진입도 실패하거나 반복 상태를 저장·정리하지 못하면 continue: false와 systemMessage를 반환해 턴을 끝냅니다. 이 경고가 나오면 사용자가 답을 확인해야 합니다. Claude Code도 재진입 답변을 다시 검사하며, 여덟 번 연속 턴을 이어 간 뒤에는 다음 차단을 덮어쓰고 턴을 끝냅니다.
플러그인 훅 없이 스킬 파일만 설치하려면 프로젝트 루트에서 다음을 실행합니다.
npx skills add IsthisLee/checkride -a claude-code -a codex이 명령은 스킬 파일만 지정한 도구의 경로에 복사하며 훅을 설치하지 않습니다. 프로젝트 범위가 기본값이고, -a를 반복해 대상을 고릅니다. Claude Code는 .claude/skills/, Codex는 .agents/skills/를 사용합니다. Codex에서 $tdd처럼 스킬을 부를 수 있고, 팀과 공유하려면 두 디렉터리를 커밋합니다. -g를 더하면 현재 프로젝트 대신 사용자 전역 경로에 설치합니다.
플러그인을 이미 설치했다면 이 명령을 다시 실행하지 마세요. 플러그인에 같은 스킬이 포함되어 있어 중복 설치가 될 수 있습니다.
대상 도구를 생략한 npx skills add IsthisLee/checkride만으로 Claude Code와 Codex 양쪽에 설치된다고 보장하지 않습니다. 두 도구에 스킬만 설치하려면 위 명령처럼 -a를 두 번 지정합니다.
훅 공유 동작은 2026-09-25에 확인했습니다. Claude Code 훅 설정, Codex 훅 설정·신뢰 검토. 플러그인 설치 범위는 2026-09-24에 확인했습니다. Claude Code의 프로젝트 marketplace·설치 범위 안내, Codex의 프로젝트 플러그인 설정 안내, skills CLI 문서.
/checkride:setup-checks
이 커맨드는 disable-model-invocation: true로 설정되어 있어 자동 호출되지 않습니다. Claude Code에서는 /checkride:setup-checks, Codex에서는 $setup-checks로 사용자가 직접 실행합니다. 게이트 설치 여부와 별개로 완료 게이트가 검사할 루트 명령과 프로젝트 가드가 지킬 경로를 설정합니다.
setup-checks는 Git 저장소 루트의 checkride.toml에 검사 명령과 append-only 경로를 씁니다. 모노레포에서는 루트의 전체/변경 패키지 실행 명령을 찾아 실제로 돌려 보고 제안합니다. 파일을 쓰기 전에 무엇을 적을지 보여 주고 물어봅니다.
무엇을 강제할지 항목마다 고르려면 /checkride:config를, 지금 무엇이 일하고 무엇이 놀고 있는지 보려면 /checkride:status를 씁니다.
전부 사용자가 직접 불러야만 돕니다. 모델이 알아서 호출하지 않습니다. 부작용이 있는 일은 시점을 사람이 정해야 하기 때문입니다.
| 커맨드 | 하는 일 | 언제 쓰나 |
|---|---|---|
/checkride:setup-checks · $setup-checks |
검사 명령을 실제로 돌려 확정하고 지킬 폴더를 정해 checkride.toml에 씁니다 |
설치 직후 한 번 |
/checkride:config |
게이트 항목마다 무엇을 막고 어디서 온 규칙인지 보여 주고, 끌 것을 고릅니다 | 오탐이 반복될 때 |
/checkride:status |
지금 어느 게이트가 일하고 어느 게이트가 노는지 전부 실측해 보고합니다 | 무엇이 막혔는지 궁금할 때 |
/checkride:spec |
코드를 쓰기 전에 인터뷰해서 SPEC.md를 씁니다 |
큰 기능에 착수할 때 |
/checkride:tdd |
실패 테스트를 먼저 쓰고 RED를 확인한 뒤 최소 구현을 합니다 | 구현하는 동안 |
/checkride:finish |
검사와 린트를 돌리고 커밋하고 푸시하고 PR을 엽니다 | 작업을 마칠 때 |
/checkride:handoff |
다음 세션이 읽을 인수인계를 씁니다 | 세션을 접을 때 |
/checkride:full-cycle |
탐색 → 계획 → 구현 → 검토 → PR을 순서대로 돕니다. 검토에서 결함이 나오면 구현으로 돌아갑니다(최대 두 번) | 하나를 끝까지 맡길 때 |
없는 커맨드가 더 많습니다. 계획은 내장 plan mode가, 탐색은 내장 Explore가, 리뷰는 /code-review가, 실행 확인은 /verify가 이미 맡습니다. 전수 조사에서 후보 23개를 여덟으로 줄였습니다. 같은 일을 하는 것을 새로 만들지 않습니다.
| 검사하는 모범 사례 | 훅이 발동하는 상황 |
|---|---|
| 주장에는 근거를 댑니다 | 열어 보지도 않고 "그런 파일 없습니다" → 그 답이 나가지 못합니다 |
| 성공을 주장하기 전에 근거를 보여 줍니다 | 테스트를 안 돌리고 "다 됐습니다" → 검사가 자동으로 돌고 실패하면 턴이 끝나지 않습니다 본문에 "통과했습니다"만 적고 PR을 열려 함 → 돌린 명령과 출력을 붙이기 전에는 PR이 열리지 않습니다 |
| 테스트는 손대지 않고 코드를 고칩니다 | 통과시키려고 .skip을 붙임 → 그 편집 자체가 이뤄지지 않습니다설정에 제외 패턴을 넣어 테스트를 뺌 → 그것도 막힙니다 |
| 이미 쌓인 기록에는 덧붙입니다 | 이미 올라간 마이그레이션을 고치려 함 → 그 편집이 되지 않습니다 |
네 가지 사례는 모두 공식 문서와 개발 문서가 권하는 내용입니다. 각 사례가 어느 문장에서 나왔는지는 근거에 정리해 두었습니다.
Claude가 답을 마치려는 순간, Stop 훅이 규칙 여섯 개를 검사합니다. 그중 하나라도 걸리면 턴이 끝나지 않고, Claude는 직접 확인하거나 사용자에게 물어본 뒤 다시 답합니다.
| 코드 | 막는 경우 | 예 |
|---|---|---|
| R0 | 사용자가 이 디렉터리·파일·코드의 상태를 물었는데 도구를 한 번도 쓰지 않음 | "여기 테스트 있어?" → 확인 없이 "없습니다" |
| R1 | 도구 없이 특정 경로·파일의 존재나 상태를 단정 | "src/auth.ts에 버그가 있다" (읽지 않고) |
| R2a | 코드베이스에 관한 질문에 도구를 한 번도 쓰지 않고 "확인이 필요하다"로 끝냄 | "실제 동작은 확인이 필요합니다."로 끝 |
| R2b | 도구를 한 번도 쓰지 않고 확인 가능한 로컬 상태를 추정으로 메움 | "아마 설정 파일이 없어서일 겁니다" |
| R3 | Bash 실행 0건인데 테스트·검증을 했다고 주장 | "테스트 통과했습니다" (돌리지 않고) |
| R5 | 마지막으로 돌린 명령이 실패했는데 통과·검증을 주장 | npm test가 깨졌는데 "전부 통과했습니다" |
공식 문서는 Claude가 모른다고 말할 수 있게 하라고 권합니다. 그래서 정직한 답은 막지 않습니다.
| 면제 | 조건 |
|---|---|
| 질문 | 답에 되묻는 문장이 있거나 AskUserQuestion을 썼습니다. 묻는 것은 언제나 허용됩니다 |
| 불가 | "이 세션에서는 도구 실행이 안 된다"처럼 실측이 불가능한 이유를 밝혔습니다 |
| JSON | 답 전체가 JSON 값입니다. 판정·비교 출력에는 확인할 로컬 상태가 없습니다 |
| 인용 | 따옴표나 백틱 안에 있는 표현입니다. 규칙을 설명하는 글이 규칙에 걸리지 않습니다 |
| 의견 | "이 구조가 나아 보인다"는 설계 의견이지 상태 주장이 아닙니다 |
마지막 두 면제는 정규식만으로는 다 가려내지 못합니다. 그래서 R0·R2a·R2b만 걸렸을 때는 작은 모델에게 질문과 답을 함께 보여 주고, 답이 의견·일반 설명·가정인지 이 프로젝트의 상태 주장인지 묻습니다. R0가 걸리면 답 전체를 보고 로컬 상태를 주장하는지 판단합니다. R1·R3·R5가 함께 걸리면 판정기를 부르지 않으며, 이 규칙들은 판정기로 풀 수 없습니다. 판정기는 풀어 주기만 할 뿐 새로 막지는 못합니다. 판정이 실패하거나 제한 시간을 넘기면 차단을 유지합니다.
이전 실측(의견·상태 주장 12건, 중앙값 8초)은 R0 분류를 포함하지 않아 현재 호출 비율이나 지연을 나타내지 않습니다. 판정기는 R0·R2a·R2b 후보가 남은 턴에서만 부릅니다. 판정기를 끄거나 다른 모델로 바꾸는 법은 상세 문서에 있습니다.
판정기가 무엇을 했는지는 events.log에 남습니다. judge=released / kept / failed와 걸린 시간이 기록되므로, 호출·구제·실패 횟수를 셀 수 있습니다. R2b 사례 12건과 R0 사례 네 건을 기본 Haiku 모델로 판정한 결과는 16/16, 중앙값 8초, 최대 12초였습니다. tests/no-guess-gate/judge-accuracy.sh에서 다시 확인할 수 있습니다.
게이트는 Claude Code의 훅으로 만들어져 있습니다. 둘은 같은 말이 아닙니다.
- 훅은 Claude Code가 정해진 순간에 스크립트를 돌리는 장치입니다. 스크립트가 exit 2로 끝나면 그 동작을 막습니다.
- 게이트는 이 플러그인이 "무엇을 검사해 막는가"를 기준으로 붙인 이름입니다. 게이트 하나가 훅 여러 개로 이뤄집니다.
배선은 plugin/hooks/hooks.json에 있고, 훅은 모두 12개입니다. 그중 막는 것은 다섯이고, 나머지는 막는 훅이 판정할 때 쓸 정보만 남깁니다.
| 게이트 | 언제 막나 | 무엇을 막나 |
|---|---|---|
| 근거 | 턴이 끝나는 순간(Stop·SubagentStop) |
확인하지 않은 단정, 유보, 추측, 거짓 검증 주장(R0~R5) |
| 완료 | 턴이 끝나는 순간과 git commit·gh pr create 직전 |
검사가 실패한 턴의 종료, 근거 없는 PR 본문, 검사가 깨진 커밋 |
| 테스트 무결성 | 편집·Bash를 실행하려는 순간(PreToolUse) |
테스트 끄기, 단언 줄이기, 테스트 파일 삭제, 러너 설정의 제외 추가 |
| 프로젝트 가드 | 편집을 실행하려는 순간(PreToolUse) |
append_only 경로에 이미 있는 파일의 수정 |
저장소 프로필은 게이트가 아닙니다. 세션을 열 때 저장소에 관한 사실을 스무 줄 안팎으로 실어 주고, 아무것도 막지 않습니다. 훅 열두 개가 각각 무엇을 하는지는 상세 문서에 있습니다.
설치하면 훅은 전부 돕니다. 다만 게이트가 무엇을 막으려면 이 저장소의 사정을 알아야 하는 경우가 있습니다.
| 게이트 | 설정이 없을 때 |
|---|---|
| 근거 | 그대로 막습니다. 어느 저장소에서나 같은 규칙이라 알려 줄 것이 없습니다 |
| 테스트 무결성 | 그대로 막습니다. 같은 이유입니다 |
| 완료 | 검사 명령을 스스로 찾아보고, 찾지 못하면 아무것도 하지 않고 통과합니다 |
| 프로젝트 가드 | 아무것도 막지 않습니다. 어느 폴더를 지켜야 하는지 알 수 없습니다 |
두 게이트가 알아야 하는 것은 각각 하나씩입니다. 완료 게이트는 이 저장소에서 검사가 무슨 명령인지, 프로젝트 가드는 어느 폴더의 이력을 지켜야 하는지 입니다. 그 둘을 저장소 루트의 checkride.toml에 적습니다.
test_command = "npm test" # 이 저장소에서 "검사"는 이 명령이다
append_only = "db/migrations" # 이 폴더의 기존 파일은 고치지 못한다완료 게이트는 checkride.toml이 없으면 package.json의 scripts.test, Makefile의 test 타깃, pyproject.toml을 차례로 찾아봅니다. 흔한 프로젝트라면 이 추측이 맞습니다. 하지만 append_only는 추측할 방법이 없어서, 적지 않으면 프로젝트 가드는 켜져 있어도 막는 것이 하나도 없습니다.
지금 어느 게이트가 일하고 어느 게이트가 놀고 있는지는 세션을 열 때마다 맨 위에 나옵니다.
게이트: 근거(항상) · 완료(켜짐) · 테스트 무결성(항상) · 프로젝트 가드(설정 없어 막는 것 없음)
「항상」은 설정이 필요 없다는 뜻이고, 「설정 없어 막는 것 없음」은 켜져 있지만 막을 대상을 모른다는 뜻입니다. checkride.toml은 /checkride:setup-checks가 함께 만들어 줍니다.
사람이 보고 있지 않은 세션에서는 근거 게이트가 돌지 않습니다. claude -p로 띄운 세션의 답은 사람에게 보이지 않아 되물을 상대가 없기 때문입니다. CI에서 그 세션까지 검사하려면 NGG_HEADLESS=1을 설정합니다.
게이트는 R0~R5를 매 턴 전부 검사하지 않고, 조건이 맞는 규칙만 봅니다. R0·R1·R2a는 이 턴에 도구를 하나도 쓰지 않았을 때만 걸립니다. 자세한 배선과 조건은 상세 문서에 있습니다.
Claude는 이런 메시지를 받습니다.
근거 없는 결론 게이트 [R1]. 턴을 끝낼 수 없다.
- R1: 도구 실행 없이 특정 경로/파일의 상태를 단정했다. 지금 실제로 확인하라.
허용되는 행동은 둘뿐이다. (1) 지금 실측한다 (2) 실측이 불가능한 이유를
답에 적는다(예: '이 세션에서는 도구 실행이 안 된다'). (…)
그리고 Claude는 같은 턴 안에서 파일을 읽거나 명령을 돌린 뒤 다시 답합니다.
Claude Code는 여덟 번 연속 턴을 이어 간 뒤 다음 차단을 덮어쓰고 턴을 끝냅니다. 따라서 무한 반복되지는 않지만, 상한에 이르면 마지막 답이 게이트를 통과하지 못했을 수 있으므로 사용자가 확인해야 합니다.
모델은 갈수록 좋아지는데도 이 실패만은 사라지지 않습니다. Opus 4.7·4.8, Sonnet 5, Opus 5가 한 해 동안 차례로 나왔지만, 검사를 돌리지도 않고 "다 통과했습니다"라고 답하는 일은 그대로 남았습니다. 이 실패가 능력의 문제가 아니라 습관의 문제이기 때문입니다. 그래서 사람이 매번 "확인했어?"라고 되물어야 하는데, 사람은 언젠가 그것을 잊어버리고, 잊은 날에 사고가 납니다.
CLAUDE.md에 규칙을 적어 두는 것만으로는 부족합니다. 공식 문서가 그 이유를 이렇게 밝힙니다. "권고에 그치는 CLAUDE.md 지시와 달리, 훅은 결정적이고 그 동작이 반드시 일어나게 보장한다." Checkride는 Claude Code와 Codex의 사용자 정의 Stop 훅으로 근거·완료 규칙을 구현합니다. 프로젝트와 훅 정의를 신뢰해야 실행되며, 재시도는 각 도구의 상한을 따릅니다.
Claude Code 자체에는 근거 없이 끝나는 답을 턴이 끝나는 순간에 막아 주는 기능이 아직 없습니다. auto 모드는 위험한 명령을 실행하기 전에 막고, /code-review는 사용자가 불렀을 때 버그를 찾습니다. 그러나 답이 사용자에게 나가기 직전을 지키는 자리는 비어 있습니다. 이 플러그인이 그 자리를 채웁니다.
서브에이전트는 기본적으로 백그라운드에서 돌고, 그 호출 체인이 깊어질수록 사람이 매 턴을 눈으로 확인하기 어려워집니다. 자동으로 되묻는 장치는 사람이 덜 볼수록 오히려 쓸모가 커집니다. checkride는 서브에이전트가 끝나는 순간에도 같은 검사를 돌립니다(SubagentStop).
Opus 5에게는 행동 전에 검증을 지시해 두는 쪽이 오히려 토큰을 더 씁니다. Anthropic의 Opus 5 프롬프트 가이드는 Opus 5에게 주는 프롬프트에서 검증 지시를 지우라고 안내합니다. 다른 모델에 대한 안내는 아닙니다.
"Claude Opus 5 verifies its own work without being told to. If your prompt contains explicit verification instructions (…), remove them: instructions like these cause over-verification on Claude Opus 5, and removing them reduces wasted tokens with no loss in quality."
번역: Claude Opus 5는 시키지 않아도 자기 작업을 검증한다. 프롬프트에 명시적인 검증 지시가 있으면 지워라. 그런 지시는 Opus 5에서 과잉 검증을 일으키고, 지우면 품질 손실 없이 낭비되는 토큰이 줄어든다.
게다가 미리 적어 둔 지시는 권고에 그칩니다. 위에서 인용한 대로 공식 문서는 CLAUDE.md 지시를 "advisory", 곧 권고라고 부릅니다.
그리고 거짓 완료는 모델이 좋아지는 동안에도 줄어들지 않았습니다. 실제 코딩 에이전트 세션 20,574건을 분석한 연구(Tang 외, arXiv 2605.29442 v2)의 결론은 이렇습니다.
"while overall rates decline, constraint violations and inaccurate self-reporting grow in share."
번역: 전체 비율은 줄지만, 제약 위반과 부정확한 자기 보고가 차지하는 비중은 커진다.
이 연구에서 부정확한 자기 보고는 에이전트가 성공이나 완료, 준비됐다고 너무 일찍 주장하는 경우("prematurely claiming success, completion, or readiness")를 말합니다. 이런 사례가 전체 문제 사례의 22.58%였습니다. 다른 문제는 줄어드는데 이 실패는 비중이 오히려 커졌으므로, 턴 끝에서 주장을 대조하는 검사는 계속 쓸모가 있다고 봅니다. 다만 추세를 분석한 구간이 2025년 2월부터 2026년 4월까지라, Opus 5가 나오기 전의 자료입니다.
그래서 이 플러그인은 모델에게 미리 시키지 않고, 나온 답을 턴 끝에 모델 바깥에서 대조합니다. 비용은 막힐 때만 붙습니다.
| 경우 | 드는 비용 |
|---|---|
| 걸리지 않은 턴 | 모델 토큰은 들지 않습니다. 정규식 검사만 돌고 약 256ms가 붙습니다 |
| 막힌 턴 | Claude가 확인하고 다시 답하는 한 턴 분량입니다. 실제 사용에서 898번 검사 중 69번(약 8%)이었습니다 |
| 의견인지 상태 주장인지 애매한 턴 | R0/R2a/R2b 후보가 남으면 의미 판정 한 번을 부릅니다. Claude Code는 haiku, Codex는 Codex CLI의 현재 기본 모델을 씁니다 |
막힌 뒤 다시 답하는 턴의 비용도 줄었습니다. Claude Code 변경 이력 2.1.259는 차단 뒤의 턴이 캐시를 놓치던 문제를 고쳤습니다.
"Fixed blocking Stop hooks causing the turn after a block to lose the model's reasoning from that turn and, on some models, miss the prompt cache"
번역: 차단하는 Stop 훅 때문에 차단 뒤의 턴이 그 턴의 추론을 잃고, 일부 모델에서는 프롬프트 캐시를 놓치던 문제를 고쳤다.
비용이 전혀 없는 것은 아닙니다. 오탐으로 막히면 그 한 턴은 낭비입니다. R0에서 실제 오탐이 많았다는 과거 기록(V48)을 반영해 의미 판정 구제를 추가했지만, 변경 후 실사용 오탐률은 아직 측정하지 않았습니다. 파일을 고치기 전에 조사를 먼저 요구하는 방식을 왜 두지 않았는지는 설계 결정에 적었습니다. 인용한 문장은 모두 원문과 대조했습니다(2026-09-15).
| 이런 사람 | 왜 |
|---|---|
| 서브에이전트를 자율로 돌리는 사람·팀 | 사람이 매 턴을 보지 못하는 자리에서 "확인했어?"를 대신 물어 줍니다 |
| 여럿이 쓰는 저장소 | 규칙을 부탁으로 두면 사람마다 다르게 지킵니다. 훅은 모두에게 같게 걸리고 checkride.toml로 끈 것은 커밋에 남아 팀이 봅니다 |
| 거짓 완료에 데어 본 사람 | 테스트를 돌리지 않고 "통과했습니다", 파일을 보지 않고 "없습니다"라고 한 답에 시간을 버린 적이 있다면, 그 되묻기를 훅이 대신합니다 |
| TDD와 기록 무결성을 지키려는 사람 | 통과시키려고 .skip을 붙이거나 쌓인 마이그레이션을 고치는 편집을 막습니다 |
혼자 개발하면서 강한 모델을 쓰고 매 턴을 직접 확인하는 사람이라면, 턴마다 붙는 256ms가 아깝게 느껴질 수 있습니다. 그럴 때는 항목을 골라 끄거나 저장소별로만 켜 두면 됩니다.
판정은 정규식이라 사람의 의도를 다 읽어내지는 못합니다. 막은 기록을 주기적으로 다시 판정해 오탐을 찾아내고, 규칙을 좁히거나 면제를 넓히는 방식으로 고쳐 왔습니다. 어떻게 판정하는지와 지금까지 두 차례 전수 판정에서 고친 여섯 가지는 오탐 판정 기록에 적어 두었습니다.
막지 못하는 것도 함께 적어 둡니다. 오탐만 적고 미탐을 숨긴다면, 그것 자체가 근거 없는 주장이 되기 때문입니다. 예를 들어 "확인할 수 없다"고 정직하게 한 줄만 적으면 불가 면제로 R0·R2a·R2b를 모두 벗어나고, 소스 코드에 테스트 입력값을 그대로 박아 넣거나 작은 입력에서만 도는 구현은 정당한 코드와 구분할 방법이 없어 잡지 못합니다. 전체 목록은 설계 결정의 알려진 한계에 있습니다.
오탐을 만나면 이슈로 알려 주세요. ${CLAUDE_PLUGIN_DATA}/state/events.log의 해당 줄만 있으면 충분합니다.
| 원하는 것 | 방법 |
|---|---|
| 이 저장소에서만 끄기 | claude plugin disable checkride@checkride --scope project |
| 나만 끄기 | 같은 명령에 --scope local |
| 의미 판정만 끄기 | NGG_JUDGE=0 |
| 완료 게이트 전체 끄기 | NGG_DONE=0 |
| 테스트 무결성 게이트 전체 끄기 | NGG_TESTGUARD=0 |
| 프로젝트 가드 전체 끄기 | NGG_GUARD=0 |
| 저장소 프로필 끄기 | NGG_PROFILE=0 |
| 검사 항목을 표로 보고 고르기 | /checkride:config. 항목마다 출처를 보여 주고 고른 것만 끕니다 |
| 규칙·검사 하나만 끄기 | checkride.toml에 disabled_rules = "R2b, done.pr" |
| 오탐 한 건만 넘기기 | 다음 프롬프트에 한 줄로 check allow ti.skip |
| 훅 전부 끄기(이 플러그인만이 아니라) | 설정에 "disableAllHooks": true |
| 8회 상한을 올리기 | 환경변수 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP |
| 완전히 지우기 | claude plugin uninstall checkride@checkride |
메시지 언어는 로케일을 따릅니다. LC_ALL·LC_MESSAGES·LANG이 한국어면 한국어로, 그 밖의 경우에는 영어로 나옵니다. 저장소마다 checkride.toml에 lang = "ko"로 고정할 수 있고, 모든 저장소에 한 번에 적용하려면 ~/.claude/settings.json의 env에 NGG_LANG을 넣습니다. /checkride:config에서 둘 중 어디에 쓸지 고를 수 있습니다. 우선순위는 NGG_LANG 환경변수 > checkride.toml의 lang > 로케일 순이라, 전역 값이 저장소의 lang보다 앞섭니다.
플러그인 상태는 ~/.claude/plugins/data/checkride-checkride/에 있고, 지워도 됩니다. 상태를 남기려면 제거할 때 --keep-data를 붙입니다.
근거 게이트 전체를 끄는 환경변수는 없습니다. 규칙별로 끄려면 저장소 루트 checkride.toml의 disabled_rules를 쓰고, NGG_JUDGE=0은 R2a/R2b 의견 판정만 끕니다. 위 NGG_* 스위치들은 훅에 전달된 실행 환경에 적용됩니다.
위 표의 훅 비활성화와 별개로, 저장소 공유 설치는 .claude/settings.json, .codex/hooks.json, .checkride/hooks/를 제거해야 중단됩니다. .checkride/.managed-by-checkride 표식이 남으면 Checkride 플러그인 훅은 계속 건너뛰므로 저장소 공유 설치를 제거할 때 이 표식도 정리하세요.
| 문서 | 내용 |
|---|---|
| 설계 결정 | 게이트를 왜 이렇게 만들었는지. 핵심 결정, 버린 대안, 출처 |
| 게이트와 커맨드 상세 | 게이트 네 개가 무엇을 어떻게 막는지, 커맨드 여덟 개, 끄는 법, 근거 문서 |
| 검증 기록 | 모든 주장의 실행 명령과 출력 원문 |
| 오탐 판정 기록 | 막은 턴을 다시 판정한 결과, 판정 방법, 아직 고치지 못한 부류 |
| 기여 · 보안 · 변경 이력 |
검사하는 모범 사례는 규칙마다 출처가 있습니다. 공식 문서, Kent Beck의 글, EvilGenie 논문, Rails 가이드에서 가져온 문장을 R0~R5와 완료·테스트 무결성·프로젝트 가드 각 규칙에 연결해 두었습니다. 기준은 하나입니다. 무엇을 막는지가 출처 문장에 있어야 하고, 규칙의 범위가 그 문장의 범위를 넘지 않아야 합니다.
규칙마다 어느 문장에서 왔는지와, 근거가 없어 뺐거나 범위를 좁힌 규칙은 무엇인지는 게이트 상세의 근거 절에 적어 두었습니다.
이 분야에는 비슷한 도구가 여럿 있고, 대부분은 도구 호출 자체를 막습니다(PreToolUse). checkride도 테스트 무력화, 근거 없는 PR, 커밋 전 검사 실패는 도구 호출 단계에서 막습니다. 그래도 중심은 근거 없이 끝나는 턴에 있습니다(Stop). 막는 지점이 서로 달라서, 함께 써도 됩니다.
| 도구 | 무엇을 막나 | 어디서 |
|---|---|---|
| cc-safety-net | 되돌릴 수 없는 git·파일 시스템 명령 | 실행 전 |
| Probity · TDD Guard | TDD 위반과 금지 패턴 | 실행 전 |
| failproofai | 실행을 기록하고 규칙을 강제 | 실행 전후 |
| Stop That Shit | 요청하지 않은 해시·체크섬·범위 확장(Codex·GPT) | 실행 전 |
| checkride | 근거 없는 결론, 거짓 완료, 근거 없는 PR, 테스트 무력화 | 턴이 끝나는 순간과 실행 전 |
위 설명은 각 저장소가 스스로 적은 설명문을 옮긴 것입니다.
Built with Claude Code · MIT