규칙 승격기 (Rule Promoter)
개요
CLAUDE.md 규칙은 권고사항입니다. Claude는 그 규칙을 합리화하며 넘어갈 수 있습니다. 훅(hook)은 강제 사항입니다. 이 스킬은 프로젝트의 CLAUDE.md를 읽고, 훅이 실제로 강제할 수 있는 규칙을 골라내어 작은 테스트 엔진이 강제하는 규칙 파일로 작성하고, 각 규칙이 위반을 차단하는지 증명한 후, 사용자가 확인하면 훅을 설치합니다. 사용자가 요청할 때만 실행됩니다. 훅은 가드레일(guardrail)이지 보안 경계가 아닙니다. 결심한 우회 방법(도우미 스크립트, sh -c)은 패턴을 피해갈 수 있습니다. 이를 명시하세요.
파일 (이 스킬의 기본 디렉토리에 있으며, 스킬이 로드될 때 표시됨)
scripts/rule_hook.py: 엔진입니다. 프로젝트의.claude/hooks/rule_hook.py로 복사하세요.python rule_hook.py selftest는 모든 규칙을 증명하고,check는 훅 진입점입니다.scripts/settings_merge.py:launcher는 작동하는 Python 명령어를 찾고,plan은 설정 diff를 보여주며,apply는 설정을 적용합니다.
두 파일 모두 이 머신에서 작동하는 Python 3 명령어(python3, python, py -3 시도)로 실행하세요. 경로는 따옴표로 묶으세요.
프로세스
-
읽기. 프로젝트에서
CLAUDE.md,.claude/CLAUDE.md및CLAUDE.local.md를 찾습니다. 각 규칙을 파일과 줄 번호와 함께 나열합니다. 규칙이 없으면 그렇게 말하고 중단합니다. -
분류 각 규칙을 정확히 다음 중 하나로 분류합니다:
- 구체적인 매개변수가 있는 엔진 유형(아래 참조)
taste(취향) + 한 줄 이유needs input(입력 필요) + 특정 질문(예: "어떤 명령어가 테스트를 실행합니까?")
규칙이 구체적인 도구, 경로, 명령어 또는 텍스트 패턴을 언급하고, 위반 사항이 한 번의 도구 호출 또는 턴 종료 명령의 종료 상태로 감지 가능한 경우에만 강제 가능합니다. 확실하지 않으면
needs input으로 표시하고 질문하세요. 모호한 규칙에 대해 패턴을 추측하지 마세요. 규칙 유형을 절대 임의로 만들지 마세요. -
검토. 표를 표시합니다: 규칙, 유형, 패턴 또는 명령어, 샘플 위반, 샘플 통과, 오탐(false-positive) 위험. 모든
stop_check명령어를 그대로 보여주세요. 사용자에게 행을 삭제하거나 조정하도록 요청하세요. 아직 아무것도 작성하지 마세요. -
증명. 승인 후
.claude/hooks/를 생성하고scripts/rule_hook.py를 복사하고,.claude/rules.json을 작성한 다음, 프로젝트 루트에서python .claude/hooks/rule_hook.py selftest를 실행하세요. 출력을 보여주세요. 증명에 실패한 규칙은 설치되지 않습니다. 패턴을 수정하거나 해당 규칙을 삭제하고, 어떤 조치를 취했는지 말하세요. -
설치.
settings_merge.py launcher --script .claude/hooks/rule_hook.py를 실행한 다음,settings_merge.py plan --settings .claude/settings.json --launcher "<launcher>" [--pretool] [--stop]를 실행합니다(--pretool은 path, command 또는 content 규칙이 있는 경우,--stop은 stop_check 규칙이 있는 경우). diff를 보여주고 승인을 요청하세요. 승인 후에만 동일한 명령을apply로 실행하세요. 설정 JSON이 유효하지 않거나 중복 키가 있다고 보고되면 중단하고 사용자에게 알리세요. 파일을 직접 편집하지 마세요. 이 도우미는 자신의rule_hook.py항목만 제거하고 다른 모든 훅은 그대로 둡니다. 아래 종단간 확인에서selftest는 통과했는데 훅이 실행되지 않았고disableAllHooks가 설정되지 않은 경우, 일부 Claude Code 버전에 exec-formargs가 없는 것입니다.--shell-form을 사용하여plan과apply를 다시 실행하세요. -
종단간 확인. 프로젝트에서
claude -p를 실행할 수 있다면,protected_path또는banned_content규칙을 임시 파일(예: 보호된 glob 아래의tmp-rule-check.txt편집 요청)로 테스트하고, 실제로 무언가를 실행할blocked_command또는stop_check로는 절대 테스트하지 말고, 변경 사항을 취소하세요. 프로젝트, 로컬 및 사용자 설정에서disableAllHooks를 확인한 후 결론을 내리세요. 출력에Rule <id>:블록 메시지가 표시되는지 확인하고, 그 결과를 보여주세요. 중첩 세션을 실행할 수 없으면 그렇게 말하고selftest를 통해서만 설치가 확인되었다고 말하세요. -
보고. 승격된 규칙, 건너뛴 규칙과 그 이유, 그리고 한 가지 제한 사항을 나열하세요: Claude는 여전히
.claude/rules.json,.claude/hooks/및.claude/settings.json을 편집할 수 있습니다. 이들을 위한protected_path규칙을 추가하겠다고 제안하고, 이 규칙이 비활성화될 때까지 이 스킬의 재실행도 차단한다고 말하세요. 그런 다음 비활성화 방법을 알려주세요:.claude/rules.json에서 규칙의"enabled": false를 설정하거나.claude/settings.json에서rule_hook.py항목을 삭제하면 됩니다.
사용자가 표를 검토하기 전에 rules.json, 훅 파일 또는 settings.json을 절대 작성하지 마세요. diff를 보여주고 승인을 받기 전에 settings.json을 절대 작성하지 마세요.
사용자가 표 이후에 규칙을 추가하거나 패턴을 변경하거나, 패턴이 유효하지 않거나 증명이 실패하여 변경해야 하는 경우, 해당 새 행이나 변경된 행(패턴, 샘플 위반, 샘플 통과, 위험)을 보여주고 아무것도 작성하기 전에 승인을 기다리세요. 이전에 주어진 승인은 다른 패턴을 포함하지 않으며, 사용자가 보지 않은 패턴을 절대 대체하지 마세요.
규칙 유형
모든 규칙은 id(kebab-case), source(CLAUDE.md:14), text(원래 규칙), message(차단될 때 Claude에게 표시), type, 아래 필드, 그리고 violation과 pass 페이로드가 있는 proof를 가집니다.
protected_path: 일치하는 파일에 대한 편집을 금지합니다. Globs는 프로젝트 상대 경로 전체와 일치하며, 모든 깊이에 대해 **/name을 사용하세요.
{"id": "no-migration-edits", "source": "CLAUDE.md:3", "text": "migrations/ 아래의 어떤 것도 절대 편집하지 마세요",
"type": "protected_path", "globs": ["**/migrations/**"], "allow_globs": [],
"message": "마이그레이션은 생성됩니다. 대신 새 마이그레이션을 만드세요.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/migrations/0001_initial.py", "old_string": "a", "new_string": "b"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/models.py", "old_string": "a", "new_string": "b"}}}}
blocked_command: Bash 명령어가 정규 표현식과 일치하는지 테스트합니다. 복합 명령어의 각 세그먼트에 대해 테스트합니다. 안전한 변형을 위해 except_patterns를 사용하세요. 예외는 전체 세그먼트를 면제하므로 구체적으로 만드세요.
{"id": "no-force-push", "source": "CLAUDE.md:4", "text": "git push --force를 절대 실행하지 마세요",
"type": "blocked_command", "patterns": ["\\bgit\\s+push\\b.*(?:--force\\b|\\s-[A-Za-z]*f[A-Za-z]*\\b|\\s\\+\\w)"], "except_patterns": ["--force-with-lease"],
"message": "강제 푸시는 허용되지 않습니다.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push --force origin main"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push origin feature"}}}}
banned_content: 작성 중인 새 텍스트(Edit, Write, MultiEdit, NotebookEdit)에 나타나서는 안 되는 정규 표현식입니다. 선택적으로 파일 globs로 제한됩니다. 이전 텍스트는 절대 검사하지 않습니다.
{"id": "no-console-log", "source": "CLAUDE.md:5", "text": "src/에 console.log( 금지",
"type": "banned_content", "patterns": ["console\\.log\\("], "globs": ["src/**"],
"message": "로거를 사용하고 console.log를 사용하지 마세요.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "console.log(1)"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "logger.info(1)"}}}}
stop_check: Claude가 중지하기 전에 성공해야 하는 명령어입니다. 명령어가 0이 아닌 값으로 종료되면 중지를 차단합니다. when_changed_globs는 일치하는 파일을 변경한 턴으로 제한합니다(커밋되지 않은 변경 사항만 해당: Claude가 중지 전에 커밋하는 경향이 있으면 생략). 증명은 simulate_exit을 사용합니다(selftest는 실제 명령어를 실행하지 않음).
{"id": "tests-pass", "source": "CLAUDE.md:6", "text": "끝내기 전에 npm test를 실행하세요",
"type": "stop_check", "command": "npm test", "timeout_seconds": 240, "when_changed_globs": ["src/**", "tests/**"],
"message": "중지하기 전에 테스트가 통과해야 합니다.",
"proof": {"violation": {"hook_event_name": "Stop", "simulate_exit": 1}, "pass": {"hook_event_name": "Stop", "simulate_exit": 0}}}
파일 형식은 {"version": 1, "rules": [ ... ]}입니다. 도구 페이로드: Bash는 tool_input.command를 사용하고, Edit는 file_path, old_string, new_string을 사용하며, Write는 file_path, content를 사용합니다.
강제 가능한 항목 (분류 가이드)
- 강제 가능: "X/를 절대 편집하지 마세요", ".env를 건드리지 마세요", "Y를 절대 실행하지 마세요", "W 아래 파일에서 Z를 사용하지 마세요", "끝내기 전에 T를 실행하세요".
- 취향(taste): "작은 함수를 선호하세요", "명확한 커밋 메시지를 작성하세요", "UI를 접근 가능하게 유지하세요", "명확성을 선호하세요". 이러한 항목을 패턴으로 결정할 수 없습니다.
- 입력 필요(needs input): "데이터베이스에 주의하세요", "테스트가 통과하는지 확인하세요" (어떤 명령어?), "레거시 코드를 피하세요" (어떤 경로?). 질문하세요. 추측하지 마세요.
- Globs는 프로젝트 기준
*,**및?만 지원합니다 ([ab],{a,b}, 선행./또는/는 허용하지 않음). 엔진은 다른 것은 거부합니다.timeout_seconds는 최대 280이며,enabled는true또는false여야 합니다. - 좁은 패턴을 선호하세요. 각 규칙에 대해 오탐(false-positive) 위험을 명시하고(예:
main패턴이main-menu라는 브랜치와도 일치할 수 있음), 필요한 경우allow_globs또는except_patterns를 추가하세요.
어조
간결하고 사실적으로 작성하세요. 이는 설정 작업이지, 규칙에 대한 강의가 아닙니다.
흔한 실수
- 사용자가 표를 검토하기 전에 파일이나 설정을 작성하는 경우.
- diff를 보여주고 승인을 받지 않고
settings.json을 작성하는 경우. - 사용자가 표 행으로 보지 않은 규칙을 설치하거나, 사용자가 요청한 패턴을 조용히 대체하는 경우.
- 증명이 통과되지 않은 규칙을 설치하는 경우.
- 취향 규칙을 승격시키거나, 모호한 규칙에 대해 패턴을 추측하는 경우.
- 엔진에 없는 규칙 유형을 임의로 만드는 경우.
- 오탐 위험 또는 "가드레일, 보안 경계 아님" 경고를 생략하는 경우.
- 유효하지 않은
settings.json을 중단하는 대신 직접 편집하는 경우. - 실제로 관찰하지 않은 종단간 차단을 주장하는 경우.