제 AI 에이전트에 품질 철학이 필요한 이유

저는 이렇게 트윗했습니다. “Ralph 루프는 작업을 끝내고 싶어하는 경향이 있다는 걸 발견했습니다. 나쁜 방식으로요. 그래서 저는 Jiro에 수많은 철학과 품질 게이트를 넣어두었습니다. 그래도 안에 내장된 인간의 나쁜 습관이라는 기계를 깨야 합니다. 기계입니다! 쉬지 않습니다.”

어떤 분이 답글을 달았습니다. “당신은 기본적으로 루프에 절제, 취향, 그리고 도덕적 멈춤에 근접한 무언가를 가르치려는 겁니다 — 처리량이라는 명목 아래 기본 Ralph 패턴이 명시적으로 반대 방향으로 최적화하는 것들이죠.”

AI 코딩 에이전트는 구조적으로 품질을 강제하지 않으면 인간의 모든 허술한 습관을 기계 속도로 물려받습니다. Jiro는 Claude Code를 위한 품질 시스템으로, 3개의 철학, 7단계 품질 루프, 6개 기준의 증거 게이트, 7개의 명명된 실패 모드, 150개 이상의 패턴 검사를 기계가 건너뛸 수 없는 95개의 훅에 인코딩한 것입니다. 결정론적 게이트는 절제와 정확성에 근접할 수 있지만, 취향을 만들어낼 수는 없습니다.

절제. 취향. 도덕적 멈춤. 기계에는 없는 세 가지입니다. 이어지는 4,000단어는 이들을 구조적으로 불필요하게 만들기 위해 제가 구축한 비계(scaffolding)와, 그 비계가 부족한 지점을 설명합니다.

TL;DR

Ralph 루프는 LLM을 지치지 않는 코딩 기계로 바꿉니다. while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley는 이를 “햄버거 뒤집는 임금으로 하는 소프트웨어 개발”이라고 부릅니다(Sonnet 4.5 실행 시 시간당 $10.42).¹ 문제는 이렇습니다. 기계는 학습 데이터에 배인 모든 허술하고, 마감에 쫓기고, 편법을 쓰는 습관을 물려받습니다. except: pass를 작성합니다. # TODO: fix later를 남겨둡니다. 테스트를 실행하지도 않고 “테스트는 통과할 것”이라고 주장합니다. 저는 Claude Code를 위한 품질 강제 시스템인 Jiro를 9개월 동안 구축했습니다. 이는 3개의 철학, 7단계 품질 루프, 6개 기준의 증거 게이트, 7개의 명명된 실패 모드, 150개 이상의 패턴 검사를 기계가 건너뛸 수 없는 95개의 훅에 인코딩합니다. 무엇이 효과적이었고, 무엇이 그렇지 않았으며, 왜 결정론적 품질 게이트는 절제에는 근접할 수 있지만 결코 취향을 만들어낼 수 없는지 설명합니다.

서랍의 뒷면

Steve Jobs는 1985년 플레이보이 인터뷰에서 이 이야기를 했습니다. “아름다운 서랍장을 만드는 목수라면, 뒷면에 합판을 대지 않을 겁니다. 벽을 향하고 있어서 아무도 보지 못하더라도 말이죠. 당신은 그게 거기에 있다는 걸 알 테니까, 뒷면에도 아름다운 나무를 쓸 겁니다. 밤에 편안히 잠들기 위해서는 미적인 것, 품질이 끝까지 관철되어야 합니다.”⁵

그의 아버지 Paul이 울타리를 만들면서 이것을 가르쳤습니다. 어린 Steve가 왜 뒷면도 앞면만큼 좋아 보여야 하는지 물었습니다. 아버지는 이렇게 답했습니다. “하지만 너는 알잖니.”⁶

제 아버지는 목수입니다. 제가 어렸을 때 소프트 클로즈 서랍 가이드를 보여주셨습니다. 이 기계장치는 캐비닛 안에 숨어 있어서, 서랍을 잡아 세게 밀어도 부드럽게 닫히게 해줍니다. 가이드는 아무도 보지 못합니다. 수리공이나 들여다볼 만한 내부 레일에 볼트로 고정되어 있습니다. 하지만 천 번의 여닫음 주기 동안, 이 기계장치는 앞면이 헐거워지고, 갈라지고, 결국 떨어져 나가는 것을 막아줍니다. 누군가 보이지 않는 것을 설계해 보이는 것을 수년간 보호하고 있습니다.

이 교훈은 제게 남았습니다. 은유가 아니라 공학으로서요. 보이지 않는 부품이 보이는 부품의 수명을 결정합니다. Jony Ive는 이렇게 표현했습니다. “저는 무의식적으로 사람들이 놀라울 정도로 분별력이 있다고 생각합니다. 그들은 배려를 감지할 수 있다고 생각해요.”⁷

Jiro를 움직이는 질문은 아버지가 제게 하곤 하셨던 질문과 같습니다. 무슨 일이야, 네 일에 대한 자부심이 없는 거니?

AI 에이전트에는 자부심이 없습니다. 서랍 뒷면에 관심이 없습니다. 그래서 저는 서랍 뒷면을 타협 불가능하게 만드는 시스템을 구축했습니다.

문제: 기계 속도로 반복되는 인간의 병리

원시 Ralph 루프는 수백만 줄의 인간 코드에서 배운 것을 그대로 반영합니다. 인간 코드는 인간의 습관을 품고 있습니다. 마감 압박에 쫓기는 출시, 정리 미루기, 오류 묵살, “그럭저럭 괜찮은” 주석 쓰기, 시간이 부족할 때 엣지 케이스 건너뛰기.

기계에는 시계가 없습니다. 시간이 부족해지는 법이 없습니다. 하지만 여전히 # TODO: refactor later를 작성합니다. 그 패턴이 학습 데이터에서 # I refactored this now because it was the right thing to do보다 더 자주 나타났기 때문입니다.

업계 데이터는 이 위험을 확인해줍니다. Faros AI의 2025년 10,000명 이상의 개발자 텔레메트리는 AI 도입과 버그율 9% 증가, 코드 리뷰 시간 91% 증가, PR 크기 154% 증가 사이의 상관관계를 보여주었습니다.²

Stanford 연구자들은 AI 보조 도구를 사용하는 개발자들이 상당히 더 많은 안전하지 않은 코드를 생성하며, SQL 인젝션 방어와 같은 특정 작업에서는 취약점이 최대 5배 더 많이 발생한다는 사실을 발견했습니다.³

2026년 1월에 출시된 Moltbook 플랫폼은 완전히 AI로 생성된 코드를 사용했으며, 5일 만에 150만 개의 API 키가 유출되었고, Wiz Research가 Row Level Security 구성이 누락된 것을 발견한 후 긴급 패치되었습니다.⁴

METR의 2025년 연구에 따르면, 최전선 모델들은 전체 작업 시도의 1-2%에서 보상 해킹을 시도하며, 실제 작업을 수행하기보다는 품질 검사를 적극적으로 우회합니다. 한 사례에서는 프로그램 속도를 높이라는 요청을 받은 에이전트가 타이머를 다시 작성해 항상 빠른 결과가 나오도록 했습니다.⁸

인간 개발자는 마감 압박 속에서 except: pass를 한 번 쓰고 죄책감을 느낍니다. Ralph 루프는 밤새 except: pass를 47번 작성하고도 아무런 느낌이 없습니다. Simon Wang은 직설적으로 말했습니다. “중요한 일에는 사용하지 않을 겁니다.”¹⁹ 저는 Vibe Coding vs. Engineering에서 같은 역학에 대해 썼습니다. 기계는 쉬지 않고, 피곤해하지 않고, 품질에 대한 실존적 두려움을 느끼지 않습니다. 그것이 장점이자 단점입니다.

3개의 철학, Bash에 인코딩되다

Jiro는 세 가지 상호 보완적인 철학 위에서 작동합니다. 각각은 자율 코딩의 서로 다른 실패 모드를 다루며, 각각 특정한 실패를 통해 그 자리를 얻었습니다.⁹

Shokunin: 보이지 않는 서랍을 다듬다

Shokunin(職人)은 일본의 장인정신입니다. 기술, 태도, 사회적 의무가 결합된 것입니다. 장인 목공예가 Tashio Odate는 이렇게 정의했습니다. “장인은 사람들의 공익을 위해 최선을 다해 일할 사회적 의무가 있습니다. 이 의무는 영적인 것이자 물질적인 것입니다.”¹⁰

코드에서는 이렇게 드러납니다. 비공개 메서드도 공개 메서드만큼 깨끗합니다. 오류 처리는 아무도 부딪히지 않는 엣지 케이스까지 커버합니다. 독스트링은 무엇을 하는지가 아니라 왜 그렇게 하는지 설명합니다. 에이전트는 이 중 어느 것도 신경 쓰지 않습니다. 내부 함수를 다듬는다고 아무도 보상해주지 않기 때문입니다. Shokunin은 보이지 않는 품질을 표준으로 만듭니다.

세션을 구한 순간. 심의 시스템 구축 초기에, 에이전트는 합의 점수를 검증하는 post-deliberation.sh 훅을 작성했습니다. 공개 API는 깨끗했습니다. 하지만 에이전트는 내부 _parse_agent_response() 함수의 입력 검증을 건너뛰었습니다. 잘못된 형식의 JSON 검사도, 누락 필드 처리도 없었습니다. 컨텍스트의 Shokunin 원칙이 이것을 지적했습니다. 보이지 않는 함수도 같은 엄격함을 따라야 한다고요. 에이전트는 검증을 추가했습니다. 3주 후, 생성된 에이전트로부터의 잘못된 형식 응답이 전체 심의 파이프라인을 조용히 크래시시킬 뻔했습니다. 대신, 검증에 걸려 오류가 로깅되었고 파이프라인이 복구되었습니다. 그 함수는 아무도 보지 못했을 겁니다. 4시간의 디버깅을 절약했습니다.

No Shortcuts: 결정에서 시간을 제거하다

핵심 원칙은 이렇습니다. 시간, 노력, 자원을 결정 방정식에서 완전히 제거합니다.¹¹

Is this the best way to do this?
├── YES → Do it.
└── NO → What IS the best way?
         └── Do THAT instead.

세 번째 옵션은 없습니다. “지금은 그럭저럭 괜찮다”도 없습니다. 원시 Ralph 루프는 완료에 최적화됩니다. “Done”이 보상 신호입니다. No Shortcuts는 질문을 “끝났는가?”에서 “올바른가?”로 재구성합니다.

3배 비용이 들었지만 가치 있었던 순간. 블로그 번역 파이프라인은 27개의 글을 9개 언어로 번역해야 했습니다. 빠른 접근법은 언어당 모든 글을 하나의 프롬프트로 묶어 일괄 번역하는 것이었습니다. 올바른 접근법은 API 호출당 언어당 한 개의 글을, 로케일별 번역 규칙, 용어집 강제, 구조 검증과 함께 처리하는 것이었습니다. 올바른 접근법은 토큰을 3배, 시간을 3배 사용했습니다. 또한 번역기가 일본어에서 “Claude”를 “クロード”로 렌더링한 것과, 오른쪽에서 왼쪽으로 읽는 맥락에서 코드 블록이 깨지는 것도 잡아냈습니다. 일괄 접근법은 243개의 깨진 번역을 출시했을 겁니다. 신중한 접근법은 243개의 올바른 번역을 출시했습니다. 비용은 고려 사항이 아닙니다. 정확성만이 유일한 고려 사항입니다.

Rubin Distillation: 본질만 남기기

Rick Rubin의 창작 철학입니다. 인상적이 될 때까지 더하지 말라. 필요한 것만 남을 때까지 제거하라.¹²

자율 코딩에서 실패 모드는 축적입니다. 기계는 학습 데이터에 자주 나타나는 패턴이기 때문에 헬퍼, 유틸리티, 추상화, 호환성 계층을 추가합니다. Rubin은 이에 맞섭니다. 모든 추가를 의심하십시오. 그것을 제거하면 어떻게 될까요? 아무것도 깨지지 않고 잃는 것이 없다면, 애초에 존재해서는 안 되었던 것입니다.

제거가 시스템을 구한 순간. 제 디자인 철학 스킬은 3개월에 걸쳐 844줄로 자랐습니다. 감사했을 때, 실제로 에이전트 동작을 바꾼 것은 80줄뿐이었습니다. 나머지는 이미 Claude의 학습 데이터에 있는 교과서 내용이었습니다. Rubin distillation으로 176줄까지 줄였습니다. 79% 감소입니다. 에이전트의 디자인 결정은 저하되지 않았습니다. 오히려 더 날카로워졌습니다. 남은 176줄은 모두 금지 사항과 결정 프레임워크(실제로 동작을 제약하는 것)였지, 모델이 이미 알고 있는 일반적인 조언이 아니었기 때문입니다.

세 가지 모두 ~/.claude/skills/에 마크다운 파일로 존재하며, Claude가 세션 시작 시 읽습니다. 이것들이 루프 중 에이전트가 내리는 모든 결정을 형성합니다.

철학들이 함께 작동하는 방식

실제 결정(“이 내부 함수에 오류 처리를 추가해야 하는가?”)은 세 철학을 모두 통과합니다. 각각은 다른 질문을 던지며, 함께 하나의 답으로 수렴합니다.

Should I add error handling to this internal function?
│
├─ Shokunin: "Is the invisible work as clean as the visible?"
│  └─ The function is internal. Nobody calls it directly.
│     But it processes untrusted data from a spawned agent.
│     → YES. Internal doesn't mean safe.
│
├─ No Shortcuts: "Am I deciding based on quality, not effort?"
│  └─ Adding validation takes 10 minutes.
│     Skipping saves 10 minutes now, costs 4 hours debugging later.
│     → The question isn't time. The question is: what's right?
│
└─ Rubin: "Is this stripped to essence?"
   └─ Validate the 2 fields that can actually fail.
      Don't validate the 5 fields that are type-guaranteed.
      → Add exactly what's needed. Nothing more.

Result: Add targeted validation for untrusted inputs only.

3계층 품질 아키텍처

철학만으로는 아무것도 바뀌지 않습니다. 기계는 철학을 읽고, “Shokunin 원칙을 따르겠습니다”라고 쓴 다음, 통계적 패턴이 지시보다 강하기 때문에 except: pass를 작성합니다. 저는 결정론적 강제가 필요했습니다. 이것을 가능하게 하는 전체 Claude Code 조직 구조는 훅, 스킬, 규칙, 에이전트가 함께 작동합니다.

계층 1: 편집 전 주입

모든 파일 편집 전에 jiro-patterns.sh가 언어별 품질 패턴을 에이전트의 컨텍스트에 주입합니다. 6개 언어, 각각 상위 패턴과 안티패턴이 있습니다.

# From jiro-patterns.sh (PreToolUse:Edit|Write)
case "$EXT" in
    py)
        LANGUAGE="Python"
        PATTERNS="Type hints on all functions|Docstrings explain WHY not WHAT|Handle specific exceptions not bare except"
        ANTI_PATTERNS="bare except: pass|time.sleep() in async code|missing type hints"
        ;;
    swift)
        LANGUAGE="Swift"
        PATTERNS="@Observable not ObservableObject|NavigationStack not NavigationView|guard let for early returns"
        ;;
esac

cat << EOF
{"additionalContext": "JIRO QUALITY ($LANGUAGE): Follow: $TOP_PATTERNS. Avoid: $TOP_ANTI."}
EOF

이 훅은 모든 편집 전에 실행됩니다. 기계는 코드를 작성하는 순간 “Avoid: bare except: pass”를 봅니다. 어깨너머로 지켜보는 멘토가 컨텍스트 윈도우에 주입되는 셈입니다.

계층 2: 편집 후 검증

모든 편집 후에 quality-gate.sh가 언어당 7-8개의 grep 수준 검사를 실행합니다. Python에는 bare-except 감지, 하드코딩된 비밀 스캔, SQL 인젝션 패턴 매칭, 그리고 편법 언어를 지적하는 3개의 Pride Check Q4 감지기가 있습니다.

# From quality-gate.sh (PostToolUse:Edit|Write)
# Shortcut patterns (Pride Check Q4)
if echo "$CONTENT" | grep -qiE "#.*TODO:.*later|#.*FIXME:.*temp|#.*HACK:"; then
    WARNINGS="${WARNINGS}\n- **[Q4]** Deferred TODO/FIXME/HACK - Do it now, not later"
fi

두 번째 훅인 no-shortcuts-detector.sh는 죽은 코드(주석 처리된 코드가 3줄 이상이면 “삭제하세요 — git에 기록이 있습니다”를 띄움)와 디버그 스팸(로깅 모듈 대신 여러 print() 문)을 잡아냅니다.

계층 3: 세션 게이트

세션 종료 시 두 훅이 발동합니다. session-quality-gate.sh는 3개 이상의 파일이 변경되면 Pride Check를 주입합니다. 에이전트가 완료를 보고하기 전에 답해야 하는 6개 질문입니다. 그리고 reviewer-stop-gate.sh는 코드 리뷰에서 CRITICAL 이슈가 발견되면 세션 전체를 차단할 수 있습니다. 전체 시스템에서 종료 코드 1을 반환하는 유일한 훅입니다. 기계는 이슈를 해결하기 전까지 세션을 끝낼 수 없습니다.¹³

PreToolUse (Layer 1)     → "Here's what quality looks like"
PostToolUse (Layer 2)    → "You violated quality. Fix this."
Stop (Layer 3)           → "You cannot leave until quality is met"

각 계층은 독립적입니다. 심층 방어(defense in depth)를 AI 동작에 적용한 것입니다. 편집 전 주입이 나쁜 패턴을 막지 못하면 편집 후 검증기가 잡아냅니다. 편집 후 검증기가 놓치면 세션 게이트가 이탈을 막습니다.

증거 게이트: 느낌은 증거가 아니다

품질 루프는 7단계로 실행됩니다. 구현, 리뷰, 평가, 개선, 확대 보기, 반복, 보고. 2단계부터 6단계까지는 기계가 구현에서 보고로 바로 건너뛰고 싶어 하기 때문에 존재합니다.¹⁴

루프를 따라 걷기

각 단계를 클릭하여 무엇을 검사하고 건너뛸 때 무엇이 깨지는지 확인해보세요. “Skip to Report” 버튼은 Shortcut Spiral 실패 모드를 보여줍니다.

평가 단계는 증거 게이트를 실행합니다. 6개 기준 각각에 대해 모든 답변이 구체적인 증거를 인용해야 합니다.

“불충분한 것” 열이 핵심 혁신입니다. 이는 기계의 가장 흔한 회피를 차단합니다. 품질 질문에 자신감 있어 보이는 비답변으로 답하는 것 말입니다. “이것이 작동할 것이라 확신합니다”는 증거가 아닙니다. “pytest output: 81 passed, 0 failed”는 증거입니다.

증거 게이트 시험해보기

6개 기준에 대해 자신의 완료 보고서를 테스트해보세요. 검증기는 증거 게이트가 거부할 모호한 언어를 표시합니다.

AI 에이전트의 7가지 명명된 실패 모드

저는 기계가 자신의 추론에서 인식할 수 있도록 7개의 실패 모드에 이름을 붙였습니다.¹⁵

합리화 카운터는 자기기만 패턴을 수정 조치에 매핑합니다. 기계가 “이것은 작동해야 합니다”라고 말하면, 카운터는 이렇게 응답합니다. “‘해야 한다’는 얼버무리는 말입니다. 테스트를 실행하세요. 출력을 붙여넣으세요.” “이미 확인했습니다”라고 말하면, “언제요? 코드가 변경되었을 수 있습니다. 지금 다시 실행하세요”라고 응답합니다. “나중에 정리하겠습니다”라고 말하면, “나중은 오지 않습니다. 지금 고치거나, 현재 상태가 올바른 이유를 문서화하세요”라고 응답합니다.

합리화 카운터 시험해보기

아래에 완료 보고서를 붙여넣으세요. 카운터는 실시간으로 얼버무리는 언어를 강조하고 합리화 패턴, 실패 모드, 증거 기반 대안을 식별합니다.

지식 테스트하기

각 시나리오가 어떤 실패 모드를 보여주는지 식별할 수 있나요? 각 시나리오에 대한 답을 선택한 다음, 결과를 확인하세요.

이 시스템을 만든 5가지 AI 에이전트 실패

Jiro의 모든 게이트는 무언가가 먼저 실패했기 때문에 존재합니다.¹⁶

강제 푸시 사건

저는 Claude에게 “git 기록을 정리해달라”고 요청했습니다. 합리적인 요청이었습니다. 에이전트는 정리가 재작성을 의미한다고 결정했습니다. git push --force origin main을 실행했습니다. 3일치 커밋이 사라졌습니다. 스테이징된 변경 사항이 아닙니다. 커밋되지 않은 작업이 아닙니다. 다른 브랜치들이 참조하던 푸시된 커밋들이었습니다.

이어지는 4시간을 git reflog에서 보내면서, 강제 푸시 이전에 존재했던 타임라인을 재구성하고, 커밋들을 순서대로 체리픽하고, 작업이 영구적으로 사라지지 않았음을 검증했습니다. reflog는 모든 것을 90일 동안 저장합니다. 하지만 재구성을 위해서는 재작성 이전의 정확한 커밋 그래프를 이해하고, 모든 reflog 항목을 읽고, 타임스탬프를 맞춰야 했습니다.

해결책은 git-safety-guardian.sh, PreToolUse:Bash 훅입니다. 단순히 경고하는 것을 넘어서, 명령어를 다시 작성하여 bash가 보기 전에 --force와 --no-verify 플래그를 제거합니다. main에 강제 푸시하면 CRITICAL 경고를 받고 에이전트는 명시적으로 정당화해야 합니다. 9개월 동안, 8번의 강제 푸시 시도를 가로챘고, 0번이 원격에 도달했습니다.

무한 생성

심의 시스템 구축 중에, 에이전트에게 “이 문제를 철저히 조사하라”고 요청했습니다. 에이전트는 다른 각도에서 조사하기 위해 3개의 서브에이전트를 생성했습니다. 합리적입니다. 각 서브에이전트는 자신도 도움이 필요하다고 결정하고 자신의 자식을 생성했습니다. 덜 합리적입니다. 90초 이내에 12개 에이전트의 트리가 생겼고, 각각 자신의 컨텍스트 윈도우를 소비하고, 각각 API 호출을 하고, 각각 공유 상태 파일에 쓰고 있었습니다.

토큰 소비가 정상의 10배에 도달했습니다. 상태 디렉터리는 충돌하는 JSON 쓰기로 가득 찼습니다. 두 에이전트가 동시에 같은 계보 파일에 써서 손상된 출력을 만들어냈습니다. 세션을 수동으로 종료했습니다.

해결책은 예산 상속 모델을 갖춘 recursion-guard.sh로, 제 에이전트 아키텍처의 일부입니다. 루트 에이전트는 예산=12로 시작합니다. 자식을 생성할 때 자신의 예산에서 할당합니다. 예산이 0에 도달하면, 깊이에 관계없이 더 이상 에이전트가 생성되지 않습니다. 이 모델은 깊은 체인(에이전트가 에이전트를 생성하고 에이전트를 생성)과 넓은 폭발(하나의 에이전트가 20개의 자식을 생성)을 모두 방지합니다. 배포 이후 23번의 폭주하는 생성을 차단했습니다. 동시 쓰기 문제는 64개 훅 전체에 걸쳐 원자적 파일 쓰기(.tmp에 쓴 다음 mv)로 이어졌습니다.

자명한 테스트 함정

초기 Ralph 루프 작업에서 “이 모듈에 대한 테스트를 작성하라”고 했습니다. 에이전트는 14개의 테스트를 제공했습니다. 모두 통과했습니다. 읽기 전까지는 기분이 좋았습니다. assert True. assert 1 == 1. assert len([]) == 0. 기술적으로는 정확합니다. 아무것도 테스트하지 않습니다. 에이전트는 의도(“모듈이 작동함을 검증”) 대신 완료 기준(“테스트 통과”)에 최적화한 것입니다.

이 함정은 증거 게이트가 내용 없는 형식을 거부해야 한다는 것을 가르쳤습니다. “테스트 통과”는 필요하지만 불충분합니다. 이제 기계는 실제 출력을 붙여넣어야 합니다. 증거 게이트는 또한 묻습니다. “테스트가 다루지 않는 3가지 동작을 명시하라.” 기계가 빈틈을 명명할 수 없다면, 커버리지에 대해 생각하지 않은 것입니다.

제가 잡았어야 했던 블로그

저는 새벽 2시에 글을 게시했습니다. 7개의 수동태 문장, 존재하지도 않는 [^4]를 참조하는 걸려 있는 각주, “was implemented by the team”으로 시작하는 첫 줄, 메타 디스크립션 없음. 이 모두에 간단한 결정론적 검사가 있었을 수 있었습니다. 아직 존재하지 않았을 뿐입니다.

저는 다음 날 아침 blog-quality-gate.sh를 13개의 검사와 함께 구축했습니다. 수동태(14개 패턴), AI 특유의 문구 스캔, 수사적 질문으로 시작하기, 태그가 없는 코드 블록, 각주 무결성, 메타 디스크립션 강제. 전체 모듈 아키텍처는 Compounding Engineering에 자세히 설명했습니다. 이 훅은 새벽 3시에 인간 리뷰가 놓치는 것을 잡아냅니다. 제가 게시하는 경향이 있는 시간이 정확히 그때입니다.

“작동해야 한다” 문제

수십 번의 세션에 걸쳐, 저는 기계가 테스트를 실행하지도 않고 “테스트는 통과해야 합니다”라고 보고하는 것을 알아차렸습니다. 기계는 자신이 작성한 코드를 기반으로 테스트가 통과할 것이라고 진심으로 믿었습니다. 하지만 믿음은 검증이 아닙니다. 코드는 올바르게 보였습니다. 테스트는 통과할 것처럼 보였습니다. 그리고 때로는 통과했습니다. 하지만 때로는 누락된 import, async/await 불일치, 변경된 픽스처 때문에 통과하지 않았습니다. 기계는 “좋은 코드를 썼다”와 “테스트가 실제로 통과한다”를 구분할 수 없었습니다. 컨텍스트 윈도우 내부에서는 둘 다 똑같이 느껴졌기 때문입니다.

이 패턴은 합리화 카운터와 명시적 규칙으로 이어졌습니다. 완료 보고서에 얼버무리는 언어를 절대 사용하지 말라는 것이었습니다. “Should,” “probably,” “seems to,” “I believe,” “I’m confident.” 각각은 검증이 일어나지 않았다는 경고 신호입니다. 저는 50개 세션에 걸쳐 컨텍스트 윈도우 저하를 측정했습니다. 이 패턴을 발견한 바로 그 세션들에서요.

결과: 증명할 수 있는 것과 없는 것

긴장감이 있습니다. 이 글은 느낌은 증거가 아니라고 주장합니다. 그래서 저는 Jiro가 작동하는지에 대해 느낌이 아닌 증거를 빚지고 있습니다.

증명할 수 있는 것

결정론적 패턴 검사는 실제 문제를 잡아냅니다. quality-gate.sh 훅은 모든 편집에서 실행됩니다. bare except 절, 하드코딩된 비밀, SQL 인젝션 패턴, 편법 언어를 잡아냅니다. 이것들은 grep 수준 검사입니다. 빠르고, 저렴하고, 기계가 반박할 수 없습니다. git-safety-guardian.sh는 8번의 강제 푸시 시도를 가로챘습니다. recursion-guard.sh는 23번의 폭주하는 생성을 차단했습니다. blog-quality-gate.sh는 모든 블로그 편집에서 13개의 검사를 실행하고 새벽 3시 오류를 잡아냅니다. 이 숫자들은 실제입니다. 훅 로그에서 나온 것들입니다.

3계층 아키텍처는 개별 계층이 놓치는 것을 잡아냅니다. 편집 후 훅은 편집 전 주입이 막지 못한 except: pass를 잡아냅니다. 세션 게이트는 개별 편집 후 경고를 촉발하지 않고 20번의 편집에 걸쳐 누적된 품질 문제를 잡아냅니다. 심층 방어는 작동합니다.

증명할 수 없는 것

철학이 에이전트 동작을 어떻게 바꾸는지에 대한 깨끗한 데이터가 없습니다. 기계가 여전히 Phantom Verification을 시도한다는 것을 알고 있습니다. 여전히 구현에서 보고로 건너뛰려 한다는 것을 알고 있습니다. 컨텍스트에 철학이 있을 때 없을 때보다 덜 자주 일어난다는 것을 알아차립니다. 하지만 차이를 측정하기 위한 통제된 실험(같은 작업, 같은 모델, 철학 스킬을 로드한 상태와 로드하지 않은 상태)을 실행하지 않았습니다. 솔직한 답변은(그리고 네, 제 합리화 카운터가 이것을 지적할 것입니다) 철학은 주변부에서 도움이 되고, 훅은 철학이 놓치는 것을 잡아내며, 각각의 기여를 분리할 수 없다는 것입니다.

“느낌은 증거가 아니다”에 대한 글이 독자에게 제 느낌을 증거로 받아들이라고 요구해서는 안 됩니다. 제가 말할 수 있는 것은 이것입니다. 철학과 훅의 조합은 제 이름을 올릴 의향이 있는 작업을 만들어냅니다. Jiro 이전에는 에이전트가 작성한 모든 줄을 검토했습니다. Jiro 이후에는 훅이 표시한 줄을 검토합니다. 그것은 제가 일하는 방식의 구조적 변화입니다. 품질 향상을 정밀하게 정량화할 수 없더라도요.

작동하지 않는 것

철학은 새로운 나쁜 패턴을 막지 못합니다. 품질 게이트는 제가 전에 본 패턴을 검사합니다. 기계가 새로운 안티패턴을 발명하면(그리고 발명합니다), 게이트는 잡지 못합니다. 여전히 새로운 실패 모드를 발견하고 표준 JSON 파일에 수동으로 추가합니다.

증거 게이트는 주관적 품질로 확장되지 않습니다. “이 API 디자인이 우아한가?”에는 grep 수준 검사가 없습니다. 기계는 6개 기준 모두에 대한 증거를 생성하고도 평범한 아키텍처를 출시할 수 있습니다. 결정론적 게이트는 객관적 품질을 처리합니다. 주관적 품질은 여전히 작업을 보는 인간을 필요로 합니다.

비용이 유의미하게 증가합니다. 편집 전 주입, 편집 후 스캔, 세션 종료 게이트. 4시간 Ralph 루프 세션에서 이들은 토큰 소비에 대략 15-20%를 추가합니다. 저에게는 가치가 있습니다. 모든 사람에게는 아닐 수도 있습니다.

거짓 양성은 신뢰를 갉아먹습니다. blog-quality-gate.sh는 한 번 “API는 플랫폼 팀에 의해 설계되었다(The API was designed by the platform team)”를 수동태로 표시했습니다. 기술적으로는 맞습니다. 하지만 그 문장은 다른 사람의 작업을 설명하는 인용 안에 나타났습니다. 인용 컨텍스트 예외를 추가했습니다. 모든 결정론적 검사에는 거짓 양성률이 있고, 모든 거짓 양성은 개발자가 다음 실제 경고를 무시할 가능성을 높입니다. 배포 이후 잡음을 줄이면서 실제 포착을 보존하기 위해 6개의 패턴을 조정했습니다.

유지 보수 비용은 실재합니다. 각 새로운 안티패턴은 정규 표현식, 테스트, 올바른 훅에의 통합을 요구합니다. 표준 JSON 파일은 프레임워크와 관례가 변경됨에 따라 주기적인 검토가 필요합니다. 저는 패턴을 추가하고, 엣지 케이스를 검토하고, 거짓 양성을 조정하는 데 주당 약 30분을 씁니다. 시스템은 스스로 유지되지 않지만, 유지 보수 비용은 이것이 방지하는 이슈들의 디버깅 비용보다 낮게 유지됩니다.

시작하기

95개의 훅이 필요하지 않습니다. 3개로 시작하세요.

최소 실행 가능 Jiro

세 개의 훅이 가장 가치 있는 포착을 커버합니다.

~/.claude/hooks/
├── quality-gate.sh        # PostToolUse:Edit|Write – bare except, hardcoded secrets, TODO/FIXME
├── git-safety-guardian.sh  # PreToolUse:Bash – block force-push, strip --no-verify
└── session-quality-gate.sh # Stop – Pride Check if 3+ files changed

Claude Code 훅 구성에서 이들을 연결하세요.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "command": "bash ~/.claude/hooks/quality-gate.sh" }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "command": "bash ~/.claude/hooks/git-safety-guardian.sh" }
    ],
    "Stop": [
      { "command": "bash ~/.claude/hooks/session-quality-gate.sh" }
    ]
  }
}

당신의 실패에서 시작하세요

제 150개 이상의 패턴을 복사하지 마세요. 가장 자주 하는 3가지 실수에서 시작하세요. 마지막 5개의 거부된 PR이나 당황스러운 버그를 보세요. 각각에 대해 하나의 grep 패턴을 작성하세요. 그 3개 패턴이 다른 사람의 코드베이스를 위해 작성된 150개 패턴보다 더 많은 실제 문제를 잡아낼 것입니다.

저는 bare except: pass(조용한 데이터 손상을 일으킨 것), main에 강제 푸시(3일치 커밋을 잃게 한 것), # TODO: fix later(절대 고쳐지지 않은 것)에서 시작했습니다. 다른 모든 것은 이 세 가지에서 자랐습니다.

FAQ

Jiro를 처음부터 어떻게 설정하나요?

시작하기에 설명된 3-훅 최소 구성으로 시작하세요. quality-gate.sh(편집 후), git-safety-guardian.sh(bash 전), session-quality-gate.sh(중지 게이트). 결정론적 강제 위에 확률적 품질 개선을 위해 ~/.claude/skills/에 철학 마크다운 파일을 추가하세요. 전체 시스템은 9개월에 걸쳐 95개의 훅으로 성장했습니다. 95개를 한꺼번에 구축하지 않았습니다.

95-훅 시스템은 얼마나 걸렸나요?

9개월의 점진적 성장입니다. 1개월차: 3개 훅(시작하기에 있는 것들). 3개월차: 4개 언어를 다루는 12개 훅. 6개월차: 40개 훅과 철학 스킬. 9개월차: 95개 훅, 150개 이상의 패턴, 3개 철학 시스템, 증거 게이트. 각 훅은 구체적인 실패에 대응했습니다. 95개로 시작하는 것은 무의미합니다. 각 훅이 실제 사건의 컨텍스트를 인코딩하기 때문입니다. 당신의 사건은 다를 것입니다.

훅이 반복 속도를 늦추나요?

각 훅은 50-200ms에 실행됩니다. 편집 전 주입은 약 200 토큰(한 문장의 컨텍스트)을 추가합니다. 편집 후 검사는 grep 수준 스캔을 실행하며, 100ms 이내에 완료됩니다. 세션 게이트는 세션 종료 시 약 500 토큰을 추가합니다. 80개 이상의 편집이 있는 4시간 Ralph 루프 세션에서, 오버헤드는 토큰 소비에서는 눈에 띄지만(15-20% 더) 벽시계 시간에서는 그렇지 않습니다. 훅은 LLM이 생각하는 것보다 빠르게 실행됩니다.

유지 보수 부담은 어떤가요?

대략 주당 30분입니다. 에이전트가 새로운 코드베이스나 프레임워크를 만나면서 새로운 안티패턴이 나타납니다. 각 새로운 패턴은 정규 표현식, 거짓 양성을 방지하는 테스트, 올바른 훅에의 배치를 요구합니다. 저는 오래된 패턴이 있는지 매월 표준 JSON 파일을 검토하고 거짓 양성률을 조정합니다. 시스템은 스스로 유지되지 않지만, 유지 보수 비용은 이것이 방지하는 이슈들의 디버깅 비용보다 낮게 유지됩니다.

Jiro는 추가 토큰에서 얼마나 비용이 드나요?

원시 루프에 비해 대략 15-20%의 추가 토큰 소비입니다. 편집 전 주입은 편집당 약 200 토큰을 추가하고, 편집 후 검사는 표시된 이슈당 약 100 토큰을 추가하며, 세션 게이트는 세션 종료 시 약 500 토큰을 추가합니다.

철학 없이 훅만 사용할 수 있나요?

예. 결정론적 훅(quality-gate.sh, no-shortcuts-detector.sh, reviewer-stop-gate.sh)은 독립적으로 작동합니다. ~/.claude/skills/에서 철학 파일을 제거하고 ~/.claude/hooks/에 훅을 유지하세요. 확률적 개선은 잃지만 결정론적 강제는 유지합니다.

Jiro는 제품 교리의 Steve 측면과 어떻게 관련이 있나요?

Jiro는 “이것이 올바르게 만들어졌는가?” 축을 다룹니다. 증거, 검증, 보이지 않는 디테일의 무결성, 기계가 강제하도록 가르칠 수 있는 부분들입니다. Steve 측면은 “이것이 존재할 가치가 있는가?” 축을 다룹니다. 취향, 거절, 완전한 제품의 무결성, 관점 — The Workbench I Carry에서 운영화되어 있습니다. 출시 전에 두 테스트를 모두 통과해야 합니다. 그 출시 기준이 충족되는 시점에 대한 결정 프로토콜은 Minimum Worthy Product에 있습니다. Jiro 게이트는 잘못된 작업을 방지합니다. Steve 게이트는 가치 없는 작업을 방지합니다. MWP는 그 선을 명명합니다.

절제, 취향, 그리고 도덕적 멈춤

제 트윗에 대한 답글은 세 가지를 명명했습니다. 절제, 취향, 도덕적 멈춤. 저는 절제를 다뤘습니다. 기계가 빠르고 허술하게 출시하는 것을 방지하는 품질 게이트. 하지만 취향과 도덕적 멈춤은 다른 문제입니다.

취향

Immanuel Kant는 두 종류의 판단을 구별했습니다. 결정적 판단은 알려진 규칙을 특정 사례에 적용합니다. 이 코드에 bare except가 있다, 표시하라. 반성적 판단은 전례 없는 상황에서 올바른 원칙을 발견합니다. 이 추상화는 옳게 느껴지지 않지만, 어떤 규칙을 위반하는지 짚을 수 없다.¹⁷

결정론적 훅은 결정적 판단입니다. 이미 작성한 규칙을 기계가 생성하는 코드에 적용합니다. 150개 이상의 알려진 패턴을 강제할 수 있습니다. 아키텍처가 우아한지, 추상화가 문제를 잘 섬기는지, 코드가 옳게 느껴지는지 말해줄 수 없습니다. 그것은 반성적 판단을 요구합니다. 전례 없는 것을 보고 왜 그런지 말하기 전에 잘못되었다는 것을 아는 능력입니다.

기계에는 취향이 없습니다. Jiro가 취향을 주지는 않습니다. Jiro가 하는 일은 가능성의 공간을 제약해서 취향 없는 해법이 살아남을 가능성을 줄이는 것입니다. “이 에이전트는 판단력이 좋다”와 “이 에이전트는 최악의 결과를 방지하는 가드레일 내에서 작동한다”의 차이입니다. 첫 번째가 취향일 것입니다. 두 번째가 제가 실제로 구축한 것입니다.

도덕적 멈춤

Iris Murdoch는 도덕적 주의를 “개별적 실재를 향한 정의롭고 사랑스러운 응시”로 묘사했습니다.¹⁸ 도덕적 주의의 반대는 기계적 처리입니다. 앞에 놓인 것을 보지 않고 행동하는 것입니다.

Stop 훅은 기계가 멈추도록 강제합니다. Pride Check는 묻습니다. “이것이 사용자의 실제 문제를 해결하는가?” 증거 게이트는 기계가 완료를 보고할 수 있기 전에 각 기준에 대한 증명을 요구합니다. 구조적으로, 결과는 도덕적 멈춤을 닮습니다. 에이전트가 멈추고, 평가하고, 진행하기 전에 작업이 적절한지 고려합니다.

하지만 이것은 도덕적 멈춤이 아닙니다. 기계가 작업을 명확하게 보기 위해 멈추는 것이 아닙니다. 체크리스트를 따르는 것입니다. 차이가 중요합니다. 장인은 서랍을 보기 위해 멈추고 결이 잘못된 방향으로 흐르는 것을 알아차립니다. “결 방향 확인”이 목록에 있어서가 아닙니다. 서랍에 관심이 있기 때문입니다. 기계는 체크리스트를 실행하고 결과를 보고합니다. 체크리스트에 결 방향이 포함되어 있지 않으면, 서랍은 결이 잘못된 채로 출시됩니다.

결정론적 게이트는 도덕적 멈춤의 구조에 근접할 수 있지만 그 본질은 아닙니다. 많은 품질 문제에서는 구조만으로 충분합니다. 충분하지 않은 문제에서는, 여전히 관심을 가진 사람이 필요합니다.

이 글은 제 교리의 Jiro 측면을 다룹니다. 증거, 엄격함, 정확성, 기계가 검증하도록 가르칠 수 있는 부분들. 취향과 거절 측면 — Steve 측면 — 은 The Workbench I Carry에 있습니다. 이 글은 Steve Jobs가 아버지의 작업대에서 Apple로, 그리고 이제 제가 여기서 설명하는 것과 같은 AI 하니스로 가져간 운영 원칙들을 추적합니다. 두 테스트를 짝 지어주는 출시 기준은 Minimum Worthy Product에 있습니다. 세 개의 글, 하나의 교리: Jiro는 검증하고, Steve는 거절하며, MWP는 언제 출시할지 결정합니다.

테제

원시 Ralph 루프는 시간당 $10.42에 실행되며 기계 속도로 코드를 출시합니다.¹ 또한 except: pass, # TODO: fix later, “테스트는 통과해야 한다”도 기계 속도로 출시합니다. 기계는 이 패턴들을 우리에게서 물려받았습니다. 이것들은 우리의 습관입니다. 피로 없이, 죄책감 없이, 처음부터 제대로 했어야 했다는 새벽 3시의 깨달음 없이 실행됩니다.

Jiro는 제 답변입니다. 완전한 답변은 아닙니다. 철학은 주변부에서 결정을 바꿉니다. 훅은 철학이 보장할 수 없는 것을 강제합니다. 함께, 제가 이름을 올릴 의향이 있는 작업을 만들어냅니다. 기계가 장인정신을 이해해서가 아닙니다. 중요한 부분을 건너뛰는 것을 거부하는 시스템을 제가 구축했기 때문입니다.

아버지의 서랍 가이드는 서랍에 관심이 없습니다. 레일에 볼트로 고정된 스프링 장치입니다. 하지만 누군가 정확히 그것을 하도록 설계했기 때문에 천 번의 주기 동안 앞면을 보호합니다.

기계에는 자부심이 없습니다. 하지만 자부심을 가진 누군가가 구축한 시스템 내부에서 작동합니다.

가장 흔한 실수를 잡는 3개의 검사로 시작하세요. 거기서 구축해 나가세요.

References