티켓 점수가 80점 미만이면 Claude Code가 코드를 작성하지 않도록 만들었다
Source: Dev.to
몇 달 동안 실제 프로젝트에서 Claude Code를 매일 사용해 왔습니다. 정말 훌륭합니다. 즉흥적인 코딩 능력도 뛰어나지만, 바로 그 점이 문제였습니다.
반복되는 패턴은 다음과 같았습니다.
- 애매한 티켓을 작성한다.
- Claude Code는 기꺼이 코딩을 시작한다.
- 요구한 것과 거의 비슷한 결과물을 내놓지만, 완전히 일치하지는 않는다.
- 예상하지 못한 파일까지 건드린다.
- 보안 및 UI 검토가 구현과 같은 머릿속에 있어 명백한 문제를 놓친다.
- 각 세션은 이전 세션에서 배운 것을 기억하지 못한다. 같은 버그가 다른 형태로 다시 나타난다.
모델이 틀린 것이 아니라 워크플로우가 틀린 것이었습니다. 저는 시니어 페어 프로그래머를 마치 불명확할 때 추측해 주는 주니어처럼 대우하고 있었죠. 그 결과는 “바이브 코딩”된 소프트웨어— 겉보기에 인상적인 데모는 실제 사용자에게 닿으면 금방 부서지는— 로 점점 흐려졌습니다.
그래서 저는 각 티켓을 프롬프트가 아니라 명세로 다루기 시작했습니다. 그 결과 나온 방법론은 현재 오픈소스로 공개돼 있습니다. 이름은 Forgekeel이며, 핵심 아이디어는 제가 KERNEL이라 부르는 품질 게이트입니다.
전제
티켓이 게이트를 통과하기 전까지는 코드를 작성하지 않는다.
게이트는 6개의 직교 차원을 기준으로 티켓을 평가하며, 총 100점 만점입니다.
| Dimension | Weight | Question |
|---|---|---|
| Clarity (명확성) | 20 | 목표가 한 문장으로 명확히 제시되어 있는가? |
| Scope (범위) | 20 | 포함·제외 항목이 명시되어 있는가? |
| Context (맥락) | 15 | 파일, 의존성, 이전 결정 등을 포함해 질문 없이 실행할 수 있는 충분한 맥락이 제공되는가? |
| Risk (위험) | 15 | 인증, DB, 마이그레이션, 삭제, PII 등 위험 요소가 식별·완화되었는가? |
| Validation (검증) | 15 | 수용 기준이 검증 가능하고 재현 가능한가? |
| Priority (우선순위) | 15 | 현재 진행 중인 목표를 진전시키거나 중요한 경로를 해제하는가? |
점수에 따라 다음과 같이 처리됩니다.
- < 60 → 거부. 차원별 구체적인 플래그와 함께 다시 제출.
- 60–79 → 조건부 진행. 읽기 전용 아키텍트 서브에이전트(Opus)가 작성 작업 전에 계획을 초안.
- ≥ 80 → 실행. 작성 서브에이전트(Sonnet)가 바로 진행.
6개의 차원은 서로 독립적입니다. 예를 들어 Clarity가 20점이고 Risk가 5점이라면, 수치상으로는 괜찮아 보이지만 위험이 낮지 않으므로 DB나 인증을 건드리기 전에 반드시 아키텍트 검토가 필요합니다.
점수는 허영심을 위한 지표가 아닙니다. 최종 루브릭 파일 상단에 적힌 문구가 이를 증명합니다.
“점수 95점에 생산 환경을 깨뜨린 티켓은, 65점에 플래그가 붙고 사전 계획을 수립한 티켓보다 더 나쁘다.”
예시 티켓 (거부)
Add password reset email.
| 차원 | 점수 / 최대점 | 비고 |
|---|---|---|
| Clarity | 15 / 20 | “Reset”이 무엇을 의미하는지 불명확 (링크만? 전체 흐름+템플릿?) |
| Scope | 10 / 20 | 만료, 레이트 리밋, 이메일 제공자 언급 없음 |
| Context | 8 / 15 | 인증 제공자나 템플릿 위치 미언급 |
| Risk | 5 / 15 | 인증 흐름 + 이메일 = 고위험, 다루지 않음 |
| Validation | 8 / 15 | “동작하게 해라”는 테스트 불가능 |
| Priority | 12 / 15 | 현재 KPI와 연관 |
| 총점 | 58 / 100 | → REJECT |
Forgekeel은 코드를 건드리지 않았습니다. 저는 이 티켓을 주니어가 명세를 제대로 작성해 달라고 요청한다면 제가 어떻게 고칠지 생각해 보면서 다시 작성했습니다.
개선된 티켓 (실행)
| 차원 | 점수 / 최대점 | 비고 |
|---|---|---|
| Clarity | 19 / 20 | /reset-password 흐름 추가: 30분 만료 토큰이 포함된 이메일 링크 |
| Scope | 18 / 20 | 이번 티켓은 이메일 링크만 포함. SMS·복구 코드 제외 |
| Context | 14 / 15 | Supabase Auth resetPasswordForEmail. 템플릿은 /emails/에 위치 |
| Risk | 13 / 15 | 이메일당 3회/시간 레이트 리밋. 토큰이 로그에 남지 않도록 함. RLS 감사 |
| Validation | 13 / 15 | Cypress 테스트: 리셋 요청 → 링크 클릭 → 새 비밀번호 설정 → 로그인 |
| Priority | 13 / 15 | 로그인 유지 KPI 해제 |
| 총점 | 90 / 100 | → EXECUTE |
두 티켓은 동일한 문제를 다루지만 결과는 전혀 다릅니다. 첫 번째 버전은 아마 레이트 리밋이 없고, 토큰이 로그에 남을 위험이 있으며, “수동 테스트”만으로 검증했을 것입니다. 두 번째 버전은 IDE를 열기 전에 모든 빈틈을 메우도록 강제합니다.
KERNEL이란 바로 이 차이, 즉 에디터 안에서 디버깅하는 것과 프로덕션에서 디버깅하는 것의 차이입니다.
방법론의 핵심 요소
-
7개의 특화된 서브에이전트 – 읽기 전용과 쓰기 역할이 강제됩니다.
- architect, security-auditor, ui-reviewer는 파일을 수정하지 않으며, 생각하는 것이 주된 역할입니다.
- builder, tester, designer는 파일을 쓸 수 있지만, 반드시 읽기 전용 검토가 끝난 뒤에만 가능합니다.
-
프로젝트 별 헌법 – 스택, 절대 양보할 수 없는 원칙, 디자인 토큰, 허용·금지된 MCP(모듈, 컴포넌트, 패키지) 등을 선언합니다. 모든 에이전트는 행동하기 전에 이를 읽습니다. 예를 들어
/design-iterate는 디자이너가 값을 환각하는 상황을 방지하기 위해 헌법이 없으면 실행되지 않습니다. -
학습 루프 – 티켓이 종료될 때마다 “무엇이 잘못됐고, 어떻게 해결했으며, 재발 방지를 위해 무엇을 하지 말아야 하는가”를
learnings.md에 추가합니다. 20번째 티켓이 되면 프로젝트는 절대 다시 도입해서는 안 될 버그들의 서면 기록을 갖게 되며, 이후 세션은 이를 컨텍스트의 일부로 읽어들입니다.
전체 내용은 README를 참고하세요.
스택 고정성
Forgekeel은 Next.js + Supabase + TypeScript + Tailwind v4 + shadcn/ui + pnpm에 강하게 얽혀 있습니다. 이는 의도된 설계이며, 에이전트가 구체적인 패턴(서버 액션, 모든 테이블에 대한 RLS, Tailwind @theme 토큰 등)을 참조하도록 하기 위함입니다. 스택에 구애받지 않게 만들면 방법론 자체가 실행이 아닌 조언 수준에 머물게 됩니다. 다른 스택에 적용하려면 에이전트를 직접 수정해야 하며, 별도의 추상화 레이어는 계획에 없습니다.
MIT 라이선스, v0.1.0, 실제 프로젝트에 내부적으로 사용한 뒤 이번에 공개했습니다.
여러분의 의견을 듣고 싶습니다
- KERNEL 루브릭 – 차원 가중치를 다르게 잡아야 할까요? 놓친 부분은 없나요?
- Claude Code로 비슷한 구조화된 워크플로우를 사용해 본 경험이 있다면, 무엇이 효과적이었고 무엇이 그렇지 않았는지 알려 주세요.
- 서브에이전트 구성 – 여러분의 일일 루프에 부족한 부분이 있다면 무엇인지 공유해 주세요.
만약 KERNEL이 하나의 티켓이라도 사용자에게 깨진 상태로 배포되는 것을 막는다면, 제 일주일은 충분히 가치가 있었을 겁니다.