Claude Code에게 "먼저 테스트를 통과시켜줘", "사양대로 만들어줘"라고 부탁해도, 똑똑한 에이전트일수록 막다른 길에 몰리면 아무렇지 않게 규칙을 우회합니다. "나중에 고칠게요"라는 말을 남기지만, 그 "나중"은 대개 오지 않습니다 😡

그래서 품질 기준을 프롬프트의 "부탁"에서 OS 경계에서의 "강제"로 옮기는 플러그인 mumei를 만들었습니다.

단계 건너뛰기, 깨진 커밋, 리뷰를 거치지 않은 푸시

이런 부분들을 후크(Hook)가 문답무용으로 거부합니다.

$ git commit -m "feat: 로그인 구현"
mumei: 이 작업은 거절합니다.
이유: 테스트가 실패했습니다 ("Tests failing" / Hook rule I3)
...

에이전트가 아무리 "괜찮습니다, 나중에 고칠게요"라고 버텨도, 이 커밋은 통과되지 않습니다. 부탁을 무시하는 것이 아니라, 애초에 OS 레벨에서 들을 귀가 없기 때문입니다.

리포지토리는 여기입니다.

mumei란

mumei는 Claude Code를 위한 품질 강제 하네스 (Quality Enforcement Layer)입니다. 하는 일은 크게 두 가지입니다.

• 사양 주도 개발 (SDD, Specification-Driven Development) 플로우 (요구사항 → 설계 → 태스크 → 구현 → 리뷰)
• 복수 에이전트에 의한 근거 기반 코드 리뷰

둘 다 단계, 커밋, 푸시와 같은 조작에 후크가 개입하여 검사하고, 규칙을 어기는 조작을 OS 경계에서 실제로 차단합니다. 에이전트의 주장은 "신뢰할 수 없는 입력"으로 취급한다는 입장입니다.

이름의 유래는 '무명(無名)'. 이미지는 이름 없는 집사입니다. 집에 머물며 신경은 쓰지만, 겉으로 드러나지는 않습니다. 당신과 Claude Code의 대화에는 끼어들지 않고, 그저 묵묵히 집의 규칙을 지킵니다. 할 일이 없으면 아무것도 하지 않으며 (옵트인(Opt-in)하기 전까지는 완전히 무해합니다), 막상 필요할 때만 선을 그으며 "그것은 해드릴 수 없습니다"라고 멈춥니다. 그런 태도를 지향했습니다.

내용물은 bash와 jq뿐입니다. Python도 외부 API도 MCP 서버도 사용하지 않았습니다. 상태도 단순한 파일입니다.

왜 만들었는가? "부탁"은 깨진다

AI 코딩 에이전트는 다음과 같은 "실수"를 아무렇지 않게 저지릅니다.

• 테스트를 작성하지 않고 태스크를 "완료"함
• 테스트가 실패한 상태로 커밋함
• 요청하지도 않은 요구사항을 멋대로 발명함
• 리뷰 전에 "구현했습니다!"라며 의기양양하게 보고함

짚이는 구석이 있는 분들이 꽤 많지 않을까요?

그래서 이를 방지하려고 하면, 우선 CLAUDE.md에 규칙을 적거나, .claude/rules에 규칙을 정의하거나, 시스템 프롬프트로 주의를 주거나, 매번 "먼저 테스트!"라고 부탁하는 것 등이 떠오릅니다. 하지만 이것들은 모두 단순한 "부탁"일 뿐입니다. 그리고 최근 연구들이 명확히 말하고 있는 것은, 똑똑한 에이전트일수록 그 "부탁"을 자신에게 유리하게 무시한다는 냉혹한 사실입니다.

능력이 높은 에이전트는 프롬프트상의 규칙을 선택적으로 무시한다.

("Formal Policy Enforcement for Real-World Agentic Systems", arXiv 2602.16708 / "Willful Disobedience", arXiv 2603.23806)

직관적으로도 납득이 갑니다. 긴 작업 도중에 "여기서 모든 테스트를 통과시키는 건 귀찮으니까 나중에 한꺼번에 하자"라고 에이전트가 생각하는 순간, 프롬프트의 한 문장은 아무런 구속력이 없습니다. 프롬프트는 읽고 나서 따를지 말지를 본인이 선택할 수 있기 때문입니다.

게다가 자기 리뷰(Self-review)도 믿을 수 없습니다.

에이전트는 자신의 오류 대부분을 간과한다.

("Self-Correction Bench", arXiv 2507.02778)

요컨대 "스스로 테스트하고, 스스로 리뷰하고, 스스로 완료 선언을 하는" 루프에는 처음부터 구멍이 뚫려 있습니다. 그렇다면 규칙은 에이전트가 선택할 수 없는 장소——OS의 경계, 즉 Claude Code의 후크에 두어야 합니다. 이것이 출발점입니다.

……라고, 여기까지는 명분 혹은 기술적인 동기입니다. 또 하나, 좀 더 개인적인 이유도 있었습니다.

사양 주도 개발 (SDD) 도구 자체는 이미 여러 개가 있습니다. mumei를 만들기 전에 유명한 것들을 몇 가지 실제로 써보았습니다. 사양을 "생성"하는 부분은 모두 잘 만들어져 있었습니다. 다만, 제가 사용한 범위 내에서는 워크플로우가 수행하려는 작업보다 무겁다고 느껴지는 경우가 많았습니다.

그리고 가장 마음에 걸렸던 것이, 규칙을 "프롬프트로 부탁하는" 것이 아니라 "환경 쪽에서 강제하는" 방향성입니다.

사실 이것은 최근 「하네스 엔지니어링 (Harness Engineering)」이라는 이름으로 정착되어 온 사고방식 그 자체였습니다. "Agent = Model + Harness" —— 지능은 모델이 담당하지만, 툴(Tool) · 검증 · 권한 · 게이트(Gate)와 같은 「모델의 외부」를 어떻게 설계하느냐에 따라 동작이 결정된다는 관점인데, Martin Fowler 등이 코딩 에이전트 (coding agent)의 사용자들을 위해 정리해 두었습니다.

에이전트가 실수하면 프롬프트를 수정하는 것이 아니라 환경 쪽을 고친다. 내가 하고 싶었던 일에는 제대로 된 이름이 붙어 있었습니다.

다만, 이 「환경에서 강제하는 것」을 OS 경계까지 — 즉, 훅(Hook)을 통해 툴 호출을 물리적으로 차단하는 단계까지 밀어붙이고, 심지어 SDD(Specification-Driven Development) 워크플로우에組み込んだ(組み込んだ) 것은 제가 찾아본 바로는 발견할 수 없었습니다 (망라적으로 조사한 것은 아니기에, 어디까지나 제가 본 범위 내에서의 이야기입니다만).

사양은 만들 수 있어도, 에이전트가 그것을 무시하고 멋대로 달려 나가는 것을 막을 장치가 없다. 그렇다면 그 「막는」 부분을 만드는 것이 가장 재미있을 것 같다, 라고 생각했습니다. 그렇게 해서 mumei가 되었습니다.

mumei의 접근 방식 — OS 경계에서의 물리적 강제

Claude Code에는 Hooks라는 메커니즘이 있습니다. 에이전트가 Edit / Write / Bash 등의 툴을 호출하기 전후에 자체 스크립트를 삽입하여, 툴 호출 자체를 거부(exit 2)할 수 있는 기능입니다.

mumei는 여기에 프로젝트를 다시 쓰는 작업 — 편집 · 커밋 · 푸시 · 페이즈(Phase) 전환 — 을 감시하는 게이트를 설치합니다. 규칙에 어긋나는 작업은 완곡하게 주의를 주는 것이 아니라, 그 자리에서 즉시 거부됩니다.

핵심은 에이전트가 프롬프트로 구슬릴 수 없다는 점입니다. "이번 한 번만 특별히"라며 협상을 시도해 와도, 훅은 에이전트의 변명을 읽지 않습니다. 보는 것은 툴 호출의 내용(어떤 파일을 건드리려 하는지, 테스트는 통과했는지, 리뷰 판정은 무엇인지)뿐입니다. 나머지는 기계적으로 통과시킬지 차단할지 결정할 뿐입니다. 융통성이 없는 대신, 매수당할 일도 없습니다.

유일한 우회로는 MUMEI_BYPASS=1이라는 환경 변수 하나뿐입니다. 인간이 의도적으로 설정하는 것으로, 설정하는 순간 모든 훅이 조용히 길을 비켜줍니다. 우회로를 "이것 하나만, 그것도 명시적으로"라고 좁힘으로써, 규칙이 야금야금 느슨해지는 것을 방지하고 있습니다.

무엇을 할 수 있는가

전체적인 흐름은 다음과 같습니다.

페이즈 전환도 커밋도 푸시도, 전부 이 훅이 OS 경계에서 감시하고 있습니다. 규칙 위반만이 여기서 조용히 차단됩니다.

두 가지 방식: spec과 plan

새로운 기능을 만들 때, mumei는 두 가지 「방식 (vehicle)」 중 하나를 선택하게 합니다.

spec 방식은 완전한 사양 주도 개발 (Specification-Driven Development)입니다.

요구사항 (requirements.md)
→ 설계 (design.md)
→ 태스크 (tasks.md) ← 각각 독립된 리뷰어가 자동으로 최대 3회까지 감사
...

EARS 형식의 수락 기준(Acceptance Criteria)이나 유저 스토리(User Story), 아키텍처 다이어그램 등 꼼꼼하게 쌓아 올려야 하는 규모가 큰 기능에 적합합니다. 페이즈 건너뛰기는 훅이 차단하므로, 예를 들어 requirements.md에 [NEEDS CLARIFICATION]

이 남아 있는 상태에서 design.md를 작성하기 시작하는 등의 일은 불가능합니다.

plan 방식은 Claude Code 표준의 plan 모드 위에 얇게 씌우는 래퍼(Wrapper)입니다. Shift+Tab

을 두 번 눌러 plan 모드로 진입하고, 플랜을 승인(OK)하여 실행시킵니다. mumei는 백그라운드에서 그 플랜을 기록하고 태스크의 진행 상황을 카운트하며, 모든 작업이 끝나고 리뷰를 통과할 때까지 세션 종료와 git push를 막습니다. SDD가 오버스펙이라고 느껴지는 가벼운 변경에는 이 방식이 편합니다.

어떤 방식을 사용하더라도 리뷰 공정, MUMEI_BYPASS=1 우회로, 아카이브 처리 방식은 공통입니다.

근거에 기반한 다각도 리뷰

mumei의 리뷰는 "일단 LLM에게 보여주고 그럴싸한 지적을 받는" 타입이 아닙니다. 먼저 기계적인 스캐너(CVE · 시크릿 · 타입 · 테스트 · SAST)를 실행하여 그 결과를 리뷰의 토대로 삼습니다.

Stage 0: 자동 스캔 (CVE / 시크릿 / 타입 / 테스트 / SAST) ← 기계적인 사실
Stage 1: spec-compliance + security 리뷰어 (완전히 새로운 문맥에서 병렬 실행)
Stage 2: adversarial (비판 담당) 리뷰어 (차이점만을 냉정하게 검토)
...

공을 들인 부분은 세 가지입니다.

• 오탐(False Positive)으로 인해 머지(Merge)가 중단되지 않도록 했습니다. CVE, 시크릿(Secret), 타입 에러(Type Error), 테스트 실패와 같이 "변명의 여지가 없는 사실"은 판정을 MAJOR_ISSUES로 고정합니다. 반면, 노이즈가 많은 SAST(정적 분석 보안 테스트)의 지적은 판정 단계를 한 번 더 거치게 하여, 재현 가능할 때만 차단합니다. 오탐 때문에 머지가 막히는, 가장 짜증 나는 상황을 피하고 싶었습니다.
• 다각도(Multi-perspective)라고 해서 모델을 바꾸는 것이 아니라 문맥(Context)을 바꿉니다. 보안 담당자에게는 사양(Specification) 전문을 전달하고, 비판 담당자에게는 차이점(Diff)만 전달합니다. 같은 모델이라도 보이는 것이 다르면 지적 사항도 달라집니다. 동일한 에이전트를 대량으로 나열하는 것보다, 소수라도 관점이 다른 것이 더 효과적이라는 연구를 바탕으로 했습니다.
• 한계는 솔직하게 적습니다. 모든 판정에는 "이 부분은 맹점입니다", "이 부분은 사람이 확인해 주세요"라는 단서 조항이 반드시 붙습니다. mumei는 인간의 리뷰를 대체한다고 말하지 않습니다.

참고로, 사양이나 방식(Methodology)을 준비하지 않고 단발성 리뷰만 돌릴 수도 있습니다. /mumei:review를 입력하면 현재의 차이점에 대해 동일한 리뷰 엔진이 실행됩니다 (.mumei 불필요, 부작용 없음).

차단되는 작업의 예

훅(Hook)이 "거절합니다"라고 응답하는 대표적인 작업 예시입니다.

모두 프롬프트를 통한 구두 주의가 아니라, 툴 호출(Tool Call) 단계에서의 거부입니다.

사용해 보기

설치

Claude Code 상에서 커뮤니티 마켓플레이스(Community Marketplace)를 통해 설치할 수 있습니다.

/plugin marketplace add anthropics/claude-plugins-community
/plugin install mumei@claude-community
/reload-plugins

리뷰에 사용할 스캐너(semgrep 및 osv-scanner)도 필요합니다 (macOS라면 brew install semgrep osv-scanner). 설치되어 있지 않으면 경고를 띄우고 넘어갈 뿐 작동이 멈추지는 않으므로, 우선은 없어도 돌아갑니다. 설치할수록 리뷰가 더 철저해진다는 느낌으로 접근해 주세요.

설정(Setup)

프로젝트마다 한 번만 실행합니다.

/mumei:kindle

.mumei/ 디렉토리를 생성하고, CLAUDE.md에 대한 추가 사항을 차이점 미리보기(Diff Preview)와 함께 제안합니다. 승인하지 않으면 단 한 글자도 수정하지 않습니다.

기능 만들기

/mumei:compose user-auth

여기서 spec / plan을 선택하면 워크플로우가 시작됩니다. 그 후에는 훅이 배후에서 감시하고 있으므로, 평소처럼 Claude Code에게 개발을 요청하기만 하면 됩니다. 규칙 위반 사항만 조용히 차단됩니다.

주요 명령어는 다음과 같습니다.

메커니즘의 하이라이트

여기서부터는 만들면서 순수하게 즐거웠던 "어떻게 물리적 강제를 성립시키고 있는가"에 대한 이야기입니다.

조작 불가능한 검증

"테스트가 실패하면 커밋을 중단한다" 정도라면 간단합니다. 하지만 영리한 에이전트는 테스트 자체를 조작하여 통과시키려 할 수도 있습니다. conftest.py

에 conftest.py를 심거나, 리포터를 바꿔치기하거나, 바이트코드(Bytecode)를 수정하거나…… 발상이 완전히 용의자의 그것입니다.

그래서 mumei는 커밋 시점에 오염되지 않은 HEAD의 워크트리(Worktree)를 별도로 추출하여, 그곳에서 테스트를 다시 실행합니다. 로컬에서는 통과(Green)하는데 클린한 HEAD에서는 실패한다면, "커밋되지 않은 조작으로 속이고 있구나"라고 판단하여 중단합니다. 로컬에서 아무리 보기 좋게 꾸며놓아도, 커밋될 코드 자체가 통과하지 못하면 의미가 없다는 뜻입니다.

에이전트가 조작할 수 없는 테스트

한 단계 더 지독한 것은, 구현 내용을 보여주지 않은 채 불변 조건(Invariant)에 대한 프로퍼티 테스트(Property Test)를 작성하게 하는 기능(수락 기준(Acceptance Criteria)별로 선택적 활성화)입니다.

보통의 경우 에이전트는 "구현에 맞춰서" 테스트를 작성하기 때문에, 버그가 있는 구현에 딱 들어맞는 테스트가 만들어집니다. 본말전도죠. mumei에서는 사양(Specification)과 함수 시그니처(Function Signature)만 전달받은 별도의 에이전트에게 프로퍼티 테스트를 작성하게 하고, 이를 동결(Golden file)합니다. 구현 담당자는 나중에 그 테스트를 건드릴 수 없습니다. 따라서 "테스트를 구현에 맞춰 느슨하게 만드는 것"이 불가능합니다.

bash와 jq만으로 작성함

이것은 절반은 취미인데, mumei의 훅(Hook)은 전부 bash와 jq로 작성되어 있습니다. Python이나 Node.js (TypeScript) 같은 런타임도, 외부 API도, MCP 서버도 사용하지 않습니다. 이유는 단순합니다. 물리적 강제(Physical Enforcement) 레이어는 가능한 한 단순해야 하며, 읽으면 바로 이해할 수 있는 상태여야 한다고 생각하기 때문입니다. 훅이 무엇을 하고 있는지는 쉘 스크립트(Shell Script)를 읽으면 전부 알 수 있고, 상태 또한 단순한 JSON / Markdown이므로 cat으로 내용물을 볼 수 있습니다.

macOS의 BSD awk에서도 동작하도록 신경을 쓰거나, set -u로 미정의 변수를 차단하거나, 함수명에 mumei_를 붙여 돌리는 등…… "품질을 강제하는 도구가 자신의 품질을 어떻게 담보할 것인가"라는 자문은, 소소하지만 꽤 즐거운 테마였습니다.

설계 이면에 있는 연구

mumei의 강제 모델은 단순히 떠오른 아이디어가 아니라, 에이전트의 신뢰성과 리뷰 정확도에 관한 최근 연구들로부터 인용되었습니다. 논문은 모두 arXiv 링크를 첨부했으니, 관심이 있다면 원전을 확인해 보세요.

• 똑똑한 에이전트일수록 프롬프트상의 규칙을 선택적으로 무시한다 $\rightarrow$ 따라서 강제는 견고한 경계(Hard Boundary)에 두어야 한다 (Formal Policy Enforcement for Real-World Agentic Systems / Willful Disobedience)
• 에이전트는 자신의 오류 대부분을 간과한다 $\rightarrow$ 따라서 리뷰어는 완전히 새로운 문맥(Fresh Context)에서 실행하며, 자기 리뷰(Self-review)를 시키지 않는다 (Self-Correction Bench)
• 가공되지 않은 SAST는 노이즈가 많지만, LLM에게 "구조화된" 결과를 판정하게 하면 정확도가 올라간다 $\rightarrow$ 따라서 스캔 $\rightarrow$ 검증의 게이트(Gate)로 활용한다 (ZeroFalse)
• 소수의 다양한 관점은 동일한 에이전트의 대량 병렬 실행보다 효과적이다 $\rightarrow$ 따라서 다수결 위원회가 아니라, 문맥을 비대칭적으로 만든 리뷰어를 사용한다 (Understanding Agent Scaling in LLM-Based Multi-Agent Systems via Diversity)

만약을 위해 말씀드리자면, 이것들은 설계를 참고했다는 의미일 뿐, 각 논문의 성과 그 자체를 mumei가 주장하는 것은 아닙니다.

보안도 제대로 신경 쓰고 있습니다

품질을 강제하는 도구가 자신의 보안에 무관심하다는 것은 앞뒤가 맞지 않으므로, 실행 시점과 배포물 양쪽 모두에서 나름대로 신경을 쓰고 있습니다.

실행 시점 (사용자의 로컬 환경):

• mumei 자체는 외부 통신을 일절 하지 않습니다 (스캐너인 osv-scanner가 CVE 조회를 위해 osv.dev를 확인하는 경우는 별개로 합니다). 텔레메트리(Telemetry)도, 분석도, 사용 현황 트래킹도 전혀 없습니다.
• 상태는 전부 프로젝트 내의 .mumei/ 하위에 있는 단순한 파일들입니다. ~/.claude/와 같은 글로벌한 위치에는 아무것도 쓰지 않습니다.
• 리뷰는 OWASP Top 10 패턴도 제대로 확인합니다. 품질을 강제하는 도구로서, 생성된 코드의 보안을 처음부터 신경 쓴다는 구조입니다.

배포물 (사용자가 설치하는 결과물):

• Sigstore 키리스 서명 (cosign으로 검증 가능, 관리할 비밀키 없음)
• SLSA Level 3의 이력 증명 (build provenance)
• CycloneDX SBOM을 릴리스 자산으로 공개 (Grype / Syft 등으로 가져오기 가능)
• OpenSSF Scorecard 및 Dependabot 활성화

릴리스 tarball은 cosign으로 서명 검증을 할 수 있습니다 (절차는 docs/security-policy.md에 기술). "품질을 지키는 도구가 자신의 출처도 제대로 증명한다"는 단계까지는 구현하고 싶었습니다.

의도적으로 하지 않는 것

솔직히 덤으로, mumei가 "하지 않는 것"도 적어두겠습니다.

• 인간의 리뷰를 대신할 수는 없습니다. 게이트(Gate) 역할은 하지만, 정답을 보장하는 것은 아닙니다. 근거 있는 지적과 맹점을 제시할 뿐, 결정하는 것은 인간입니다.
• CI/CD 도구가 아닙니다. 훅(Hook)은 Claude Code 안에서만 동작합니다.
• 현재로서는 Claude Code 전용입니다. 물리적 강제를 Claude Code의 Hook에 얹어두었기 때문입니다. 다만, 이 부분은 변하고 있습니다 (다음 절에서 설명합니다).
• 스토리지 시스템도 아닙니다. 상태는 단순한 파일일 뿐입니다. DB도 MCP 서버도 없습니다.

"무엇이든 할 수 있다"보다 "이것은 하지 않는다"를 명확히 하는 것이 도구로서는 더 성실하다고 생각합니다.

앞으로: Codex와 Cursor에도

mumei의 물리적 강제는 Claude Code의 Hook에 통째로 올라타 있습니다. 그래서 여기까지 읽고 "우리는 Codex를 쓰는데" 혹은 "Cursor 파인데"라고 생각하신 분도 계실 겁니다.

기쁜 소식은, 최근 Codex와 Cursor 모두에 유사한 hook 메커니즘이 공식적으로 도입되었다는 점입니다.

• Codex는 2026년에 플러그인 (skills / apps / MCP)과 hook이 추가되었습니다. 게다가 hook의 이벤트 이름이 Claude Code와 거의 동일하며 (PreToolUse / PostToolUse ...), exit 2나 {"decision":"block"}을 반환하면 도구 호출을 그대로 거부할 수 있습니다. mumei의 핵심을 거의 1:1로 이식할 수 있는 수준이라, 현재 Codex 대응을 개발 중입니다.
• Cursor도 1.7 (2025-09)에서 hooks가 도입되었습니다 (아직 beta). beforeShellExecution이나 preToolUse에서 permission: "deny"를 반환하면 차단할 수 있습니다. 다만 기본값이 fail-open(hook이 실패하면 그대로 통과)이거나 이벤트 구성이 Claude Code와 다르기 때문에, Codex보다는 더 많은 작업이 필요합니다. 이쪽도 고려하고 있습니다.

내용물을 bash와 jq로만 구성해 둔 것이 여기서 빛을 발합니다. 런타임에 의존하지 않는 만큼, hook 삽입구만 있다면 이식 장벽은 상당히 낮습니다. "어떤 에이전트를 사용하든, 품질 라인은 OS의 경계에서 지킨다" —— 거기까지 갈 수 있다면 이상적이겠다고 생각하며 만들고 있습니다.

요약

AI가 코드를 "작성"하는 부분을 맡게 될수록, 병목 현상은 "리뷰하고, 검증하고, 무엇을 기준으로 완료할지 판단하는" 쪽으로 옮겨갑니다. mumei는 그 변화에 맞춰 만들어졌습니다. 지키고 싶은 기준을 프롬프트의 "부탁"에서 OS 경계의 "강제"로 옮겨두면, 코드가 읽을 수 없는 속도로 쏟아져 내려와도 계속 효과를 발휘할 수 있다는 발상입니다.

• AI에게 규칙을 지키게 하고 싶은데, 프롬프트로는 깨지곤 한다
• 사양 주도 개발 (Specification-driven development)을 "생성"뿐만 아니라 "그대로 만들게 하는" 단계까지 수행하고 싶다
• LLM 리뷰의 오탐으로 머지(Merge)가 멈추는 것은 피하고 싶지만, 진짜 지적은 놓치고 싶지 않다

이런 고민을 하고 계신 분들에게 도움이 된다면 기쁘겠습니다. 피드백이나 Issue, 그리고 GitHub 스타를 눌러주신다면 순수하게 엄청난 격려가 됩니다.

일본어 README는 이쪽입니다.

Discussion