티켓 점수가 80/100점 미만이면 코드를 작성하지 않도록 Claude Code를 설정했습니다

저는 몇 달 동안 실제 프로젝트에서 Claude Code를 매일 사용해 왔습니다. 정말 훌륭합니다. 또한 매우 뛰어난 즉흥 연주자이기도 한데, 바로 그 점이 문제입니다.

실패 모드 (Failure mode)
반복되는 패턴은 다음과 같았습니다: 제가 모호한 티켓 (ticket)을 작성하면, Claude Code는 즐겁게 코딩을 시작합니다. 제가 요청한 것과 비슷하지만 완전히 일치하지는 않는 무언가를 내놓습니다. 제가 예상하지 못한 파일들을 건드리기도 합니다. 보안 및 UI 리뷰가 구현과 같은 머릿속에서 이루어지다 보니, 명백한 오류를 아무도 잡아내지 못했습니다. 각 세션은 이전 세션에서 배운 것을 잊어버렸습니다. 동일한 버그가 다른 형태로 다시 나타났습니다.

모델이 틀린 것이 아니었습니다. 워크플로 (workflow)가 틀린 것이었습니다. 저는 시니어 페어 프로그래머 (senior pair programmer)를 제가 불분명하게 말하면 추측해서 행동하는 주니어처럼 취급하고 있었습니다. 그 결과, 겉보기에는 인상적이지만 실제 사용자를 만났을 때 무너져 버리는, 이른바 "바이브 코딩 (vibe-coded)" 소프트웨어를 향해 서서히 표류하게 되었습니다.

그래서 저는 각 티켓을 프롬프트 (prompt)로 취급하는 것을 멈추고, 명세서 (spec)로 취급하기 시작했습니다. 그 결과로 나온 방법론은 현재 오픈 소스로 공개되어 있습니다. 이름은 Forgekeel이며, 핵심 아이디어는 제가 KERNEL이라고 명명한 품질 게이트 (quality gate)입니다.

KERNEL: 코드 작성 전 점수를 매기는 게이트
전제 조건: 티켓이 게이트를 통과하기 전까지는 어떤 코드도 작성되지 않습니다. 이 게이트는 총 100점 만점으로, 6개의 직교하는 차원 (orthogonal dimensions)에 대해 모든 티켓의 점수를 매깁니다:

차원 (Dimension)	가중치 (Weight)	질문
질문 명확성 (Question Clarity)	20	목표가 한 문장으로 명확하게 정의되어 있는가?
범위 (Scope)	20	포함 사항과 제외 사항이 명시적인가?
컨텍스트 (Context)	15	질문 없이 실행할 수 있을 만큼 충분한 컨텍스트 (파일, 의존성, 이전 결정 사항 등)가 있는가?
리스크 (Risk)	15	리스크가 식별되고 완화되었는가? (인증, DB, 마이그레이션, 삭제, PII 등)
검증 (Validation)	15	수락 기준 (Acceptance criteria)이 검증 가능하고 재현 가능한가?
우선순위 (Priority)	15	이것이 활성 목표를 진전시키거나 중요한 경로의 차단 요소를 해소하는가?

점수에 따라 다음과 같이 결정됩니다:

• < 60 → 거절 (reject). 차원별 구체적인 플래그 (flags)와 함께 저에게 반환됩니다.
• 60–79 → 조건부 (conditional). 아키텍트 서브에이전트 (architect subagent, Opus, 읽기 전용)가 쓰기 작업 전에 계획을 초안합니다.
• ≥ 80 → 실행 (execute). 빌더 서브에이전트 (builder subagent, Sonnet)가 즉시 진행합니다.

이 6가지 차원은 서로 직교합니다.

높은 명확성 (Clarity)으로 낮은 리스크 (Risk)를 보상할 수는 없습니다. 명확성이 20이고 리스크가 5인 티켓은 수치상으로는 여전히 높게 나오지만, 낮은 리스크 수치 때문에 DB나 인증 (auth) 관련 작업을 수행하기 전에 반드시 아키텍트의 검토를 거쳐야 합니다. 이 점수는 허울 좋은 지표 (vanity metric)가 아닙니다. 루브릭 (rubric) 파일의 맨 윗줄에 적힌 내용은 다음과 같습니다: 95점을 받았지만 프로덕션 (production)을 망가뜨린 티켓은, 65점을 받았지만 플래그 (flagged)가 지정되어 먼저 계획을 세운 티켓보다 나쁩니다.

구체적인 예시: 여기 제가 스스로 거절했던 티켓이 있습니다: "비밀번호 재설정 이메일 추가".

KERNEL 통과 여부:
명확성 (Clarity) 15 / 20: "재설정 (Reset)"이 정의되지 않음 — 링크만 제공하는 것인가, 아니면 전체 흐름 (flow) + 템플릿 (template)까지 포함인가?
범위 (Scope) 10 / 20: 만료 시간, 속도 제한 (rate limits), 또는 이메일 제공자에 대한 언급 없음
컨텍스트 (Context) 8 / 15: 어떤 인증 제공자 (auth provider)를 사용하는지, 템플릿이 어디에 있는지 명시되지 않음
리스크 (Risk) 5 / 15: 인증 흐름 (auth flow) + 이메일 = 높은 리스크, 다뤄지지 않음
검증 (Validation) 8 / 15: "작동하게 만들기"는 테스트 가능하지 않음
우선순위 (Priority) 12 / 15: 활성 KPI
───── 58 / 100 → 거절 (REJECT)

Forgekeel은 코드에 손을 대는 것을 거부했습니다. 저는 주니어 개발자가 제대로 된 사양 (spec)을 요청했을 때처럼 티켓을 다시 작성했습니다:

명확성 (Clarity) 19 / 20: /reset-password 흐름 추가: 30분 만료 토큰이 포함된 이메일 링크
범위 (Scope) 18 / 20: 이 티켓의 범위: 이메일 링크만 포함. 제외 사항: SMS, 복구 코드
컨텍스트 (Context) 14 / 15: Supabase Auth resetPasswordForEmail. 템플릿은 /emails/에 위치
리스크 (Risk) 13 / 15: 이메일당 시간당 3회의 속도 제한 (rate-limit). 로그에 토큰 유출 금지. RLS 감사 (audit)
검증 (Validation) 13 / 15: Cypress: 재설정 요청, 링크 클릭, 새 비밀번호 설정, 로그인
우선순위 (Priority) 13 / 15: 로그인 유지 KPI의 병목 해소
───── 90 / 100 → 실행 (EXECUTE)

동일한 문제, 두 개의 티켓, 두 개의 결과입니다. 첫 번째 버전은 무언가를 배포했을 것입니다. 아마도 속도 제한도 없고, 토큰이 로그로 유출될 수 있는지에 대한 감사도 없으며, 검증 단계로 "수동 테스트"를 사용하는 상태였을 것입니다. 두 번째 버전은 IDE를 열기 전에 모든 공백을 강제로 메웁니다.

이것이 KERNEL의 실체입니다: 에디터에서 디버깅하는 것과 프로덕션에서 디버깅하는 것의 차이입니다.

게이트 (gate) 측면에서 KERNEL은 가장 독보적인 부분이지만, 이 방법론에는 더 많은 것이 있습니다: 읽기 전용 (read-only) 역할과 쓰기 (write) 역할이 강제된 7개의 특화된 서브에이전트 (subagents)가 존재합니다.

architect, security-auditor, 그리고 ui-reviewer는 파일을 절대 수정하지 않습니다. 이들의 역할은 타이핑하는 것이 아니라 생각하는 것입니다. builder, tester, 그리고 designer는 쓰기 (write)가 가능하지만, 오직 읽기 전용 (read-only) 리뷰를 거친 후에만 가능합니다. 프로젝트별 헌법 (constitution)에는 스택 (stack), 협상 불가능한 원칙, 디자인 토큰 (design tokens), 허용/금지된 MCP (Model Context Protocol)가 선언되어 있습니다. 모든 에이전트는 행동하기 전에 이를 읽습니다. 이것이 없다면, designer가 값을 환각 (hallucinate)할 수 있기 때문에 /design-iterate 명령은 실행을 거부합니다. 학습 루프 (learnings loop)도 존재합니다. 종료된 모든 티켓은 "무엇이 잘못되었는지 / 어떻게 해결되었는지 / 무엇을 반복하지 말아야 하는지"를 learnings.md 파일에 추가합니다. 티켓 20개 정도가 쌓이면, 프로젝트는 다시는 도입해서는 안 될 버그들에 대한 기록된 이력을 갖게 됩니다. 향후 세션에서는 이를 컨텍스트 (context)의 일부로 읽어들입니다. 자세한 분석은 README에 있습니다. 왜 스택이 고정되어 있는가 (Why it's stack-locked): Forgekeel은 주관이 뚜렷하며 Next.js + Supabase + TypeScript + Tailwind v4 + shadcn/ui + pnpm으로 스택이 고정되어 있습니다. 이는 의도된 설계입니다. 에이전트들은 특정 패턴 (Server Actions, 모든 테이블에 대한 RLS, Tailwind @theme 토큰)을 참조합니다. 만약 제가 에이전트들을 스택에 구애받지 않게 (stack-agnostic) 만들었다면, 이 방법론은 실행이 아닌 조언 수준에 머물렀을 것입니다. 다른 스택에 적응하려면 에이전트를 직접 수정해야 하며, 별도의 추상화 계층 (abstraction layer)은 계획되어 있지 않습니다. 제가 찾고 있는 것: MIT 라이선스, v0.1.0, 이번 릴리스 전에 실제 프로젝트에서 내부적으로 사용될 대상. 저장소 (Repo): https://github.com/forgekeel/forgekeel npm: https://www.npmjs.com/package/forgekeel 다음 사항에 대한 피드백을 진심으로 환영합니다: KERNEL 루브릭 (rubric) — 차원(dimensions)의 가중치를 다르게 두어야 할까요? 6가지 요소 중 놓친 부분(blind spots)이 있나요? Claude Code에서 유사한 구조화된 워크플로우를 실행 중인 분이 계신가요 — 무엇이 효과적이었고, 무엇이 그렇지 않았나요? 서브에이전트 (subagent) 설정 — 여러분의 일상적인 루프에서 무엇이 빠져 있나요? 만약 KERNEL이 단 하나의 티켓이라도 사용자에게 결함이 있는 상태로 배포되는 것을 막을 수 있다면, 저의 일주일은 가치 있는 시간이 될 것입니다.