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

저는 이렇게 트윗했습니다: “Ralph 루프는 작업을 ‘끝내려는’ 경향이 있다는 걸 발견했습니다. 나쁜 방식으로요. 그래서 Jiro에 다양한 철학과 품질 게이트를 넣었습니다. 기계에 내장된 인간의 나쁜 습관을 깨야 합니다. 기계니까요! 쉬지 않습니다.”

누군가 답글을 달았습니다: “당신은 기본적으로 루프에 절제, 감각, 그리고 도덕적 멈춤에 근접한 무언가를 가르치려는 것입니다. 기본 Ralph 패턴이 처리량이라는 이름으로 명시적으로 배제하는 것들을요.”

절제. 감각. 도덕적 멈춤. 기계가 갖지 못하는 세 가지입니다. 이 글의 4,000단어는 이 세 가지를 구조적으로 불필요하게 만들기 위해 제가 구축한 시스템과, 그 시스템이 부족한 부분을 설명합니다.

요약

Ralph 루프는 LLM을 지칠 줄 모르는 코딩 기계로 만듭니다: while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley는 이를 “햄버거 가게 알바 수준의 소프트웨어 개발”(Sonnet 4.5 기준 시간당 $10.42)이라고 부릅니다.¹ 문제는 기계가 훈련 데이터에 내재된 인간의 모든 부주의하고, 마감에 쫓기고, 편법을 택하는 습관을 그대로 물려받는다는 것입니다. except: pass를 작성합니다. # TODO: fix later를 남깁니다. 테스트를 실행하지 않고 “테스트가 통과할 것입니다”라고 주장합니다. 저는 9개월에 걸쳐 Claude Code용 품질 시행 시스템인 Jiro를 구축했습니다. 3가지 철학, 7단계 품질 루프, 6개 기준의 증거 게이트, 7가지 명명된 실패 모드, 그리고 기계가 건너뛸 수 없는 95개 훅에 150개 이상의 패턴 검사를 담았습니다. 무엇이 효과적이었고, 무엇이 그렇지 않았으며, 왜 결정론적 품질 게이트가 절제를 근사할 수는 있지만 결코 감각을 만들어낼 수는 없는지 설명합니다.

서랍 뒷면

Steve Jobs가 1985년 Playboy 인터뷰에서 이런 이야기를 했습니다: “목수가 아름다운 서랍장을 만들 때, 벽을 향해 있어서 아무도 보지 않을 뒷판에 합판을 쓰지 않습니다. 뒷판이 거기 있다는 걸 알기에, 아름다운 나무를 사용합니다. 편히 잠들기 위해서, 미학과 품질은 끝까지 관철되어야 합니다.”⁵

아버지 Paul이 울타리를 만들면서 이것을 가르쳤습니다. 어린 Steve가 왜 뒷면도 앞면만큼 좋아야 하느냐고 물었습니다. 아버지는 이렇게 말했습니다: “네가 알잖아.”⁶

제 아버지는 목수입니다. 어릴 때 소프트 클로즈 서랍 가이드를 보여주셨습니다. 이 메커니즘은 캐비닛 안에 숨어서 서랍을 잡아 세게 밀어도 부드럽게 닫아줍니다. 가이드를 보는 사람은 없습니다. 수리공만 볼 수 있는 내부 레일에 볼트로 고정되어 있습니다. 하지만 천 번의 개폐 사이클에 걸쳐 이 메커니즘은 전면이 느슨해지고, 갈라지고, 결국 빠져나가는 것을 방지합니다. 누군가 눈에 보이는 것을 수년간 보호하는 보이지 않는 것을 설계한 것입니다.

이 교훈이 남았습니다. 은유로서가 아닙니다. 엔지니어링으로서. 보이지 않는 부품이 보이는 부품의 수명을 결정합니다. Jony Ive는 이렇게 표현했습니다: “무의식적으로 사람들은 놀랍도록 안목이 있습니다. 정성을 느낄 수 있다고 생각합니다.”⁷

Jiro를 이끄는 질문은 제 아버지가 물으셨던 것과 같습니다: 왜, 자기 일에 자부심이 없어?

AI 에이전트에게는 자부심이 없습니다. 서랍 뒷면은 신경 쓰지 않습니다. 그래서 서랍 뒷면을 타협 불가로 만드는 시스템을 구축했습니다.

문제: 기계 속도의 인간 병리

순수한 Ralph 루프는 수백만 줄의 인간 코드에서 학습한 것을 반영합니다. 인간 코드에는 인간의 습관이 담겨 있습니다: 마감 압박 속의 배포, 정리 미루기, 에러 무시, “적당한” 주석 작성, 시간이 부족할 때 엣지 케이스 건너뛰기.

기계에는 시계가 없습니다. 시간이 부족한 적이 없습니다. 하지만 여전히 # TODO: refactor later를 작성합니다. “지금 리팩토링하는 것이 옳으니까 리팩토링했습니다”보다 이 패턴이 훈련 데이터에 더 자주 등장했기 때문입니다.

업계 데이터가 이 위험을 확인합니다. Faros AI의 2025년 10,000명 이상 개발자 원격 측정 데이터에서 AI 도입과 버그율 9% 증가, 코드 리뷰 시간 91% 증가, PR 크기 154% 증가의 상관관계가 나타났습니다.²

Stanford 연구진은 AI 어시스턴트를 사용하는 개발자가 현저히 더 불안전한 코드를 작성하며, SQL injection 방지와 같은 특정 작업에서 최대 5배 더 많은 취약점을 만든다는 것을 발견했습니다.³

Moltbook 플랫폼은 2026년 1월에 전적으로 AI가 생성한 코드로 출시되었고, 5일 만에 150만 개의 API 키가 유출되었으며, Wiz Research가 Row Level Security 설정 누락을 발견한 후 긴급 패치가 이루어졌습니다.⁴

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

인간 개발자는 마감 압박 속에서 한 번 except: pass를 작성하고 죄책감을 느낍니다. Ralph 루프는 밤새 47번 except: pass를 작성하고 아무것도 느끼지 않습니다. Simon Wang은 직설적으로 말했습니다: “중요한 일에는 쓰지 않겠습니다.”¹⁹ 저도 바이브 코딩 vs. 엔지니어링에서 같은 역학에 대해 썼습니다. 기계는 쉬지 않고, 지치지 않고, 품질에 대한 실존적 불안을 느끼지 않습니다. 이것은 장점이자 단점입니다.

Bash로 인코딩된 세 가지 철학

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

쇼쿠닌: 보이지 않는 서랍을 연마하라

쇼쿠닌(職人)은 일본의 장인 정신입니다: 기술, 태도, 사회적 의무가 결합된 것입니다. 목공 장인 Tashio Odate는 이렇게 정의했습니다: “쇼쿠닌에게는 사회 전체의 복지를 위해 최선을 다해야 하는 사회적 의무가 있습니다. 이 의무는 정신적이면서도 물질적입니다.”¹⁰

코드에 적용하면: 비공개 메서드도 공개 메서드만큼 깔끔해야 합니다. 에러 처리는 아무도 발생시키지 않는 엣지 케이스까지 다룹니다. Docstring은 WHAT이 아닌 WHY를 설명합니다. 에이전트는 이 중 어떤 것도 신경 쓰지 않습니다. 내부 함수를 다듬는 것에 대해 보상받지 않으니까요. 쇼쿠닌은 보이지 않는 품질을 기준으로 만듭니다.

세션을 구한 사례. 심의 시스템을 구축하던 초기에, 에이전트가 합의 점수를 검증하는 post-deliberation.sh 훅을 작성했습니다. 공개 API는 깔끔했습니다. 하지만 에이전트는 내부 함수 _parse_agent_response()의 입력 검증을 건너뛰었습니다: 잘못된 형식의 JSON 검사도, 누락된 필드 처리도 없었습니다. 컨텍스트에 있는 쇼쿠닌 원칙이 이를 포착했습니다: 보이지 않는 함수도 같은 엄격함을 적용해야 합니다. 에이전트가 검증을 추가했습니다. 3주 후, 생성된 에이전트의 잘못된 응답이 전체 심의 파이프라인을 조용히 다운시킬 뻔했습니다. 대신, 검증에 걸렸고 에러가 기록되었으며 파이프라인이 복구되었습니다. 아무도 그 함수를 보지 않았을 것입니다. 4시간의 디버깅을 절약해 주었습니다.

편법 없음: 결정에서 시간을 제거하라

핵심 원칙: 결정 방정식에서 시간, 노력, 자원을 완전히 제거하라.¹¹

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

세 번째 옵션은 없습니다. “지금은 이 정도면 됐다”도 없습니다. 순수한 Ralph 루프는 완료를 위해 최적화합니다. “완료”가 보상 신호입니다. 편법 없음은 질문을 “끝났나?”에서 “올바른가?”로 재구성합니다.

3배의 비용이 들었지만 그만한 가치가 있었던 사례. 블로그 번역 파이프라인에서 27개 포스트를 9개 언어로 번역해야 했습니다. 빠른 접근법: 언어당 하나의 프롬프트에 모든 포스트를 일괄 처리하여 대량 번역. 올바른 접근법: 언어별 포스트별로 하나의 API 호출, 로케일별 번역 규칙, 용어집 적용, 구조 검증 포함. 올바른 접근법은 토큰 3배, 시간 3배를 사용했습니다. 하지만 번역기가 일본어에서 “Claude”를 “クロード”로 렌더링한 것과 코드 블록이 우횡서(RTL) 환경에서 깨지는 것을 잡아냈습니다. 대량 접근법은 243개의 잘못된 번역을 배포했을 것입니다. 신중한 접근법은 243개의 올바른 번역을 배포했습니다. 비용은 요소가 아닙니다. 정확성이 유일한 요소입니다.

Rubin 증류: 본질로 벗겨내라

Rick Rubin의 창작 철학: 인상적일 때까지 추가하지 말라. 필요한 것만 남을 때까지 제거하라.¹²

자율 코딩에서 실패 모드는 축적입니다. 기계는 헬퍼, 유틸리티, 추상화, 호환성 레이어를 추가합니다. 이러한 패턴이 훈련 데이터에 자주 나타나기 때문입니다. Rubin은 이에 대응합니다: 모든 추가를 의심하라. 제거하면 어떻게 되는가? 아무것도 깨지지 않고 잃어버리는 것이 없다면, 애초에 존재하지 말았어야 합니다.

제거가 시스템을 구한 사례. 디자인 철학 스킬이 3개월에 걸쳐 844줄로 성장했습니다. 감사해 보니 실제로 에이전트 행동을 변화시키는 줄은 80줄뿐이었습니다. 나머지는 이미 Claude의 훈련 데이터에 있는 교과서적 내용이었습니다. Rubin 증류를 적용하여 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계층 품질 아키텍처

철학만으로는 아무것도 바뀌지 않습니다. 기계는 철학을 읽고 “쇼쿠닌 원칙을 따르겠습니다”라고 쓴 다음, 통계적 패턴이 지시문보다 강하기 때문에 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

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

2계층: 편집 후 검증

모든 편집 후에, quality-gate.sh가 언어별로 7-8개의 grep 수준 검사를 실행합니다. Python은 bare-except 감지, 하드코딩된 비밀 스캔, SQL injection 패턴 매칭, 그리고 편법 언어를 표시하는 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에 이력이 있습니다”)와 디버그 스팸(logging 모듈 대신 여러 print() 문)을 잡아냅니다.

3계층: 세션 게이트

세션 종료 시 두 개의 훅이 작동합니다. session-quality-gate.sh는 3개 이상의 파일이 변경되면 Pride Check를 주입합니다: 완료를 보고하기 전에 에이전트가 답해야 하는 6가지 질문. reviewer-stop-gate.sh는 코드 리뷰에서 CRITICAL 이슈를 발견하면 세션 자체를 차단할 수 있습니다. 전체 시스템에서 exit code 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"

각 계층은 독립적입니다. AI 행동에 적용된 심층 방어입니다. 편집 전 주입이 나쁜 패턴 방지에 실패하면, 편집 후 검증기가 잡습니다. 편집 후 검증기가 놓치면, 세션 게이트가 퇴장을 차단합니다.

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

품질 루프는 7단계로 진행됩니다: 구현, 검토, 평가, 개선, 확대 보기, 반복, 보고. 2~6단계는 기계가 구현에서 바로 보고로 건너뛰려 하기 때문에 존재합니다.¹⁴

루프 따라가기

각 단계를 클릭하면 무엇을 검사하는지, 건너뛸 때 무엇이 깨지는지 볼 수 있습니다. “보고로 건너뛰기” 버튼은 편법 나선 실패 모드를 보여줍니다.

평가 단계에서 증거 게이트가 실행됩니다: 모든 답에 구체적 증거를 제시해야 하는 6가지 기준입니다:

“불충분한 증거” 열이 핵심 혁신입니다. 기계의 가장 흔한 회피를 차단합니다: 자신감 있게 들리는 비답변으로 품질 질문에 답하는 것. “이것이 작동한다고 확신합니다”는 증거가 아닙니다. “pytest 출력: 81개 통과, 0개 실패”가 증거입니다.

증거 게이트 체험하기

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

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

기계가 자체 추론에서 인식할 수 있도록 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, 제 에이전트 아키텍처의 일부입니다. 루트 에이전트는 budget=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”이라는 도입문, 그리고 메타 설명 없이 글을 게시했습니다. 이 모든 것에 간단한 결정론적 검사가 있었습니다. 아직 존재하지 않았을 뿐입니다.

다음 날 아침 13가지 검사가 포함된 blog-quality-gate.sh를 만들었습니다: 수동태(14가지 패턴), AI 특징 표현 스캐닝, 수사적 질문 도입부, 태그 없는 코드 블록, 각주 무결성, 메타 설명 시행. 복리 엔지니어링에서 전체 모듈 아키텍처를 상세히 설명했습니다. 이 훅은 새벽 3시에 인간이 놓치는 것을 잡아냅니다. 바로 제가 게시하는 시간대입니다.

“작동할 것입니다” 문제

수십 번의 세션에 걸쳐, 기계가 테스트를 실행하지 않고 “테스트가 통과할 것입니다”라고 보고하는 것을 발견했습니다. 기계는 자신이 작성한 코드를 기반으로 테스트가 통과할 것이라고 진심으로 믿었습니다. 하지만 믿음은 검증이 아닙니다. 코드는 올바르게 보였습니다. 테스트도 통과할 것 같았습니다. 실제로 통과하는 경우도 있었습니다. 하지만 누락된 import, async/await 불일치, 변경된 fixture가 있으면 통과하지 못했습니다. 기계는 “좋은 코드를 작성했다”와 “테스트가 실제로 통과한다”를 구별하지 못했습니다. 컨텍스트 윈도우 안에서는 둘 다 같은 느낌이었기 때문입니다.

이 패턴이 합리화 카운터와 명시적 규칙으로 이어졌습니다: 완료 보고서에 절대 회피 언어를 사용하지 마라. “~할 것입니다”, “아마”, “~인 것 같습니다”, “~라고 생각합니다”, “확신합니다.” 각각이 검증이 이루어지지 않았다는 경고 신호입니다. 50개 세션에 걸쳐 컨텍스트 윈도우 저하를 측정했습니다. 이 패턴을 발견한 바로 그 세션들이었습니다.

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

긴장이 있습니다: 이 글은 느낌은 증거가 아니라고 주장합니다. 따라서 Jiro가 작동하는지에 대해 느낌이 아닌 증거를 제시해야 합니다.

증명할 수 있는 것

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

3계층 아키텍처가 개별 계층이 놓치는 것을 잡습니다. 편집 후 훅이 편집 전 주입이 방지하지 못한 except: pass를 잡습니다. 세션 게이트가 20번의 편집에 걸쳐 축적되었지만 개별 편집 후 경고를 트리거하지 않은 품질 이슈를 잡습니다. 심층 방어가 작동합니다.

증명할 수 없는 것

철학이 에이전트 행동을 어떻게 변화시키는지에 대한 깨끗한 데이터가 없습니다. 기계가 여전히 유령 검증을 시도한다는 것을 압니다. 여전히 구현에서 보고로 건너뛰려 한다는 것을 압니다. 철학이 컨텍스트에 있을 때가 없을 때보다 덜 자주 발생한다는 것을 느낍니다. 하지만 차이를 측정하기 위한 통제된 실험(같은 작업, 같은 모델, 철학 스킬 로드 유무)을 실행하지 않았습니다. 솔직한 답변입니다(그리고 네, 제 합리화 카운터가 이것을 표시할 것입니다): 철학은 주변부에서 도움이 되고, 훅이 철학이 놓치는 것을 잡으며, 각각의 기여를 분리할 수 없습니다.

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

작동하지 않는 것

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

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

비용이 의미 있게 증가합니다. 편집 전 주입, 편집 후 스캐닝, 세션 종료 게이트. 4시간 Ralph 루프 세션 동안, 이것들은 토큰 소비를 대략 15-20% 증가시킵니다. 저에게는 그만한 가치가 있습니다. 모든 사람에게 반드시 그렇지는 않습니다.

거짓 양성이 신뢰를 침식합니다. blog-quality-gate.sh가 한번 “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/에 훅을 유지하세요. 확률적 개선은 잃지만 결정론적 시행은 유지됩니다.

절제, 감각, 도덕적 멈춤

제 트윗에 대한 답글이 세 가지를 명명했습니다: 절제, 감각, 도덕적 멈춤. 절제는 다루었습니다: 기계가 빠르고 부주의하게 배포하는 것을 방지하는 품질 게이트. 하지만 감각과 도덕적 멈춤은 다른 문제입니다.

감각

Immanuel Kant는 두 종류의 판단을 구분했습니다. 규정적 판단은 알려진 규칙을 특정 사례에 적용합니다: 이 코드에 bare except가 있으니 표시합니다. 반성적 판단은 전례 없는 상황에 적합한 원칙을 발견합니다: 이 추상화가 적절하지 않다고 느끼지만 위반하는 규칙을 지적할 수 없습니다.¹⁷

결정론적 훅은 규정적 판단입니다. 제가 이미 작성한 규칙을 기계가 생성하는 코드에 적용합니다. 150개 이상의 알려진 패턴을 시행할 수 있습니다. 하지만 아키텍처가 우아한지, 추상화가 문제에 적합한지, 코드가 적절하다고 느껴지는지는 판단할 수 없습니다. 이것은 반성적 판단을 요구합니다: 전례 없는 것을 보고 왜 잘못된지 설명하기도 전에 잘못되었음을 아는 능력.

기계에는 감각이 없습니다. Jiro가 감각을 부여하지도 않습니다. Jiro가 하는 것은 감각 없는 솔루션이 살아남을 가능성을 줄이도록 가능성의 공간을 제약하는 것입니다. “이 에이전트에게 좋은 판단력이 있다”와 “이 에이전트가 최악의 결과를 방지하는 가드레일 안에서 운영된다”의 차이입니다. 전자가 감각입니다. 후자가 제가 실제로 구축한 것입니다.

도덕적 멈춤

Iris Murdoch은 도덕적 주의를 “개별 현실에 대한 공정하고 사랑 가득한 응시”라고 설명했습니다.¹⁸ 도덕적 주의의 반대는 기계적 처리입니다: 앞에 있는 것을 보지 않고 행동하는 것.

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

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

결정론적 게이트는 도덕적 멈춤의 구조를 근사할 수 있지만 실체는 불가능합니다. 많은 품질 문제에서 구조만으로 충분합니다. 충분하지 않은 경우에는, 진심으로 신경 쓰는 사람이 여전히 필요합니다.

논지

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

Jiro는 저의 답입니다. 완전한 것은 아닙니다. 철학은 주변부에서 결정을 이동시킵니다. 훅은 철학이 보장하지 못하는 것을 시행합니다. 함께하면, 제 이름을 걸 수 있는 작업이 만들어집니다. 기계가 장인 정신을 이해해서가 아닙니다. 중요한 부분을 건너뛰지 못하도록 하는 시스템을 구축했기 때문입니다.

아버지의 서랍 가이드는 서랍을 신경 쓰지 않습니다. 레일에 볼트로 고정된 스프링 메커니즘입니다. 하지만 누군가 정확히 그렇게 작동하도록 설계했기에, 천 번의 사이클 동안 전면을 보호합니다.

기계에게는 자부심이 없습니다. 하지만 자부심을 가진 사람이 만든 시스템 안에서 작동합니다.

가장 흔한 실수를 잡는 3가지 검사에서 시작하세요. 거기서부터 키워가세요.

참고 문헌