서론

"가설 검증이 중요하다는 건 알고 있다. 하지만 정신을 차려보면 오늘도 feature를 만들고 있다"

이건 바로 제 이야기입니다.

kaizen-lab이라는 가설 검증 플랫폼을 직접 만들어서 스스로 도그푸딩 (Dogfooding)을 해왔습니다. 그럼에도 불구하고 개발에 탄력이 붙으면 가설 검증을 위한 동작은 허무하게 사라져 버립니다. 도구가 있더라도, "사용한다"라는 의지에 의존하는 한, 동작은 지속되지 않습니다.

그래서 발상을 전환했습니다. 가설 검증을 "의지"가 아니라 "시스템"으로 강제하는 것입니다. 게다가 이제는 개발의 모든 입구가 된 AI 코딩 에이전트 (Claude Code) 측에 거주하게 만드는 것입니다.

feature 구현 요청도, 티켓 기표(Ticket creation)도, 지금은 Claude Code를 경유하는 일이 늘었습니다. 그렇다면 그곳에 게이트를 설치하면, 프로덕트 개발의 거의 모든 입구에서 "그 가설은 무엇인가?"라고 물을 수 있을 것입니다.

만든 것은 이것입니다.

이 기사에서는 이 플러그인(이름은 hdd = Hypothesis-Driven Development)의 설계와, 만드는 과정에서 생각했던 것들을 정리합니다.

어떤 플러그인인가

한마디로 말하면, 프로덕트 개발의 모든 입구에 가설 검증 게이트를 두는 플러그인입니다.

• feature 구현을 요청하면 "이 feature는 어떤 가설에 기반하고 있습니까?"라고 질문함
• 가설·검증 계획이 없는 티켓은 그대로 만들 수 없음 (hooks가 물리적으로 차단)
• "이 태스크는 정말 지금 할 가치가 있는가"를 우선순위 스코어(Priority score)로 질문함
• 검증에 필요한 계측이 없다면, 데이터 수집 기반(Data collection infrastructure) 정비부터 제안함

설치는 Claude Code 내에서 2개의 명령어로 가능합니다.

/plugin marketplace add toshipon/hypothesis-driven-development-skills
/plugin install hdd@hdd

대상 사용자는 PdM과 프로덕트 엔지니어입니다. 그리고 중요한 설계 방침으로서, 특정 프로덕트 관리 도구에 의존하지 않습니다. GitHub Issues에서도 JIRA에서도 Linear에서도, 심지어 "리포지토리 내의 markdown 파일만" 있어도 동작합니다 (이 이야기는 후술하겠습니다).

강제의 3층 구조

이 플러그인의 핵심은 강제력이 다른 3가지 레이어를 겹친 것입니다.

Layer 1: commands ── 동작을 정의하다

8개의 명령어로 가설 → 검증 → 학습 → 의사결정의 루프를 한 바퀴 돌 수 있도록 구성했습니다.

그중에서도 /hdd:grill은 이 플러그인의 사상이 가장 잘 드러나는 명령어입니다. 착수하려는 feature에 대해 4단계 결정 트리(Decision tree)로 추궁해 옵니다.

• 과제의 실재성: 그 과제를 가진 사람을 직접 관측한 적이 있는가? ("있을 것 같다"는 관측이 아님)
• 해결책의 타당성: 만들지 않고도 검증할 수 있는 수단은 없는가?
• 가치와 임팩트: 성공하면 어떤 지표가 얼마나 움직이는가? 실패라고 판단하는 기준은?
• 검증 계획: 최소 비용의 검증 수법·성공 기준·철수 기준·필요한 계측

포인트는 사실(관측된 데이터)과 의견(추측·원망)을 엄격히 구분하게 만드는 것입니다. "사용자는 원할 것이다"라고 답하면 근거를 요구받습니다. 대답에 막히면, 그것이야말로 검증해야 할 가설로서 기록됩니다.

따져 물은 결과 "이 시책은 지금 실행해서는 안 된다"라는 결론에 도달한다면, 그것은 실패가 아니라 가장 저렴한 검증 성공으로 취급합니다.

Layer 2: skills ── 문맥에 따라 자동 개입한다

명령어를 입력하는 것은 결국 "의지"이기 때문에, 의지에 의존하지 않는 계층이 필요합니다.

hypothesis-first라는 skill은 기능 추가(feature addition)나 기능 개선 구현 요청을 감지하면, 코드를 작성하기 전에 가설의 유무를 확인하러 갑니다. 가설이 없다면 /hdd:grill 실행, 티켓화, 최소한의 검증안 2~3개 제시까지를 세트로 제안합니다.

또 다른 issue-hypothesis-gate는 티켓 생성 작업(gh issue create 또는 JIRA의 MCP 도구 등)을 감지하면, 생성 전에 본문을 체크리스트로 검사합니다.

Layer 3: hooks ── 물리적으로 차단한다

최후의 보루는 PreToolUse hooks입니다. gh issue create나 MCP 티켓 생성 도구를 실행할 때, 본문에 가설 마커(가설·검증 방법·성공 기준)가 포함되어 있지 않으면, exit code 2로 실행 자체를 차단합니다. AI가 실수로 그냥 통과시키더라도 셸(shell) 레벨에서 멈춥니다.

다만 "강제"와 "독재"는 다르다고 생각하기에, 도망갈 길은 마련해 두었습니다.

• 사용자가 "가설 불필요"라고 명시하면 [no-hypothesis] 마커를 붙여 생성할 수 있습니다 (단, 판단 기록은 남습니다).
• 버그 수정, CI 수정 등의 기술적 태스크는 게이트 대상에서 제외됩니다.
• HDD_HOOK_DISABLE=1로 전부 중단할 수 있습니다.
• jq가 없는 환경에서는 페일 오픈(fail-open)됩니다.

"검증하지 않았다면 만들지 마라"가 아니라, **"검증하지 않았음을 자각하고, 기록하고, 계측을 심어놓은 뒤에 만들어라"**라는 설계입니다.

티켓을 「실험 카드」로 만들기

티켓 생성 시의 체크리스트는 다음 6개 항목입니다.

• 누구의 어떤 과제인지 명문화되어 있는가
• 과제의 근거(관측된 사실)가 적혀 있는가
• 성공 지표와 목표치가 있는가
• 검증 방법과 성공 기준·철수 기준이 있는가
• 계측 수단이 존재하는가
• "이 태스크를 수행하지 않을 경우 잃게 되는 것"이 적혀 있는가

여기에 더해, 태스크의 상대적 가치를 수치화합니다.

우선순위 스코어 = Impact × Confidence × Risk ÷ Effort (각 1~5)

Confidence(가설의 확실성)가 낮은데 Effort가 큰 태스크는 스코어가 낮아지므로, "이 티켓보다 먼저 해야 할 저렴한 검증이 있을 것이다"라는 대화가 자연스럽게 발생합니다. 이는 kaizen-lab의 실험 백로그(experiment backlog)에서 사용하던 스코어링 모델을 이식한 것입니다.

검증을 돌리기 위한 데이터 기반도 「AI가 가져올 수 있는 형태」로

가설 검증이 지속되지 않는 또 다른 이유는, 검증 결과를 확인하는 것이 번거롭기 때문입니다. 계측이 심어져 있지 않거나, 심어 놓았더라도 대시보드를 보러 가지 않습니다.

/hdd:data-infra는 검증에 필요한 계측을 3단계로 제안합니다.

• Level 1: 기존 데이터 활용 (DB 쿼리, 기존 로그. 추가 구현 제로)
• Level 2: 이벤트 계측 추가 (이벤트 설계표 포함)
• Level 3: AI가 데이터를 취득할 수 있는 경로 정비 ── read-only API 또는 MCP 서버화

Level 3가 이 플러그인의 핵심 추천 사항입니다. get_metric(name, period)나 run_funnel(steps, period)와 같은 read-only MCP 도구를 정비해 두면, AI 에이전트가 검증 결과를 자율적으로 취득하여 판정할 수 있게 되어, /hdd:verify → 검증 실시 → /hdd:learn의 루프가 사람의 손을 거치지 않고 돌아가기 시작합니다.

한 번의 계측 정비 비용으로 이후의 모든 검증 사이클이 빨라집니다. AI 에이전트 시대의 데이터 기반은 "인간이 대시보드를 본다"는 전제가 아니라 "AI가 질의한다"는 전제로 설계하는 것이 좋다는 것이 kaizen-lab의 MCP 운용을 통해 얻은 실감입니다.

(물론, 집계된 데이터만을 반환하고 가공되지 않은 PII(개인 식별 정보)를 넘기지 않는 등의 설계 지침도 플러그인 내의 knowledge base에 넣어 두었습니다.)

프로덕트에 의존하지 않기 위한 설계

원천은 kaizen-lab이지만, 플러그인은 kaizen-lab 없이도 완결됩니다. 여기서 핵심이 된 것은 두 가지 설계입니다.

1. 가설의 저장소는 리포지토리 내의 markdown

docs/hypotheses/
├── README.md # 운용 규칙
├── LEARNINGS.md # 학습 시계열 인덱스
...

외부 서비스가 필요 없습니다. 가설 카드는 frontmatter가 포함된 markdown이므로, AI와 인간 모두 다루기 쉽습니다.

2. 트래커는 「능력 기반」으로 검출한다

프롬프트에 "JIRA라면" 혹은 "kaizen-lab라면"과 같이 제품명을 하드코딩하는 대신, 실행 시점에 사용할 수 있는 능력으로부터 판단하도록 했습니다.

gh auth status

가 통과되면 GitHub Issues를 사용 - 연결된 MCP 도구에
issue / backlog / verification

등의 이름 패턴이 있으면 그것을 사용 - 둘 다 없으면 markdown으로 폴백(fallback)

이렇게 작성해 두면, 향후 어떤 도구가 MCP로 연결되더라도 플러그인 측의 변경 없이 통합됩니다.

또한, 학습 카테고리 분류(validated / invalidated / insight / pattern / risk)나 의사결정의 4가지 선택지(persevere / pivot / kill / pause), 검증 모드의 prove / explore와 같은 어휘는 kaizen-lab에서 실제로 운용하며 손에 익은 모델을 일반 용어로서 도입했습니다.

source

주의할 점: marketplace의 Claude Code 플러그인을 마켓플레이스 형식으로 배포할 경우, marketplace.json의 source에 . (리포지토리 루트)를 지정하면 유효성 검사(validation)에서 거부됩니다. 플러그인 본체는 plugin/ 서브 디렉토리에 두고 "source": "./plugin"으로 설정하는 것이 안전합니다.

리포지토리/
├── .claude-plugin/marketplace.json # "source": "./plugin"
└── plugin/
...

commands / skills / hooks는 디렉토리 배치만으로 자동 검출되므로, plugin.json에 나열할 필요는 없었습니다.

마치며

가설 검증은 「지식」의 문제가 아니라 「습관」의 문제이며, 습관은 의지보다 시스템(仕組み)에 맡기는 것이 더 지속된다 ── 이것이 이 플러그인의 도박입니다.

그리고 개발의 모든 입구가 AI 에이전트를 경유하게 되고 있는 지금은, 시스템을 심어 넣는 장소로서 AI 에이전트가 가장 가성비가 좋은 타이밍이라고 생각합니다. 에이전트는 문맥을 읽고 "되묻기"를 할 수 있기 때문에, 단순한 lint나 템플릿 강제화보다 훨씬 유연하면서도 확실하게 강제할 수 있습니다.

• 리포지토리: https://github.com/toshipon/hypothesis-driven-development-skills
• 설치: /plugin marketplace add toshipon/hypothesis-driven-development-skills → /plugin install hdd@hdd

「가설 없는 티켓」을 만들 수 없게 된 생활, 꽤 괜찮습니다.

Discussion