duthaho/claudekit

Claude Code를 위한 **검증 우선 엔지니어링 툴킷 (verification-first engineering toolkit)**입니다. 이미 프로덕션 코드를 배포하는 방법을 알고 있으며, 방해받지 않으면서도 엄격한 규율을 유지하는 워크플로우를 원하는 시니어 IC (Individual Contributor) 및 테크 리드(tech leads)를 위해 구축되었습니다.

15개의 기술(skills), 8개의 에이전트(agents), 그리고 하나의 철학: 모든 주장에는 증거가 있어야 한다.

• 테스트 통과했으니 믿어줘는 없습니다.
• 내 IDE에서는 잘 돌아가도 없습니다.
• 캐시가 오래된 것 같아라는 말도 없습니다.
• 기술(skills)은 코드 리뷰에 바로 붙여넣을 수 있는 결과물(artifacts)을 생성합니다.

모든 기술에는 **합리화 테이블 (Rationalizations tables)**이 포함되어 있습니다. 엔지니어가 단계를 건너뛰기 위해 만드는 변명(

단계	기술 (Skills)	강제 사항
조사 (Investigate)	investigate-root-cause, map-codebase, audit-dependencies	시스템에 대한 모든 주장은 <file:line> 인용을 포함해야 함. 기억에 기반한 단언 금지.
설계 (Design)	shape-spec, write-plan, plan-review, plan-review-architecture, plan-review-experience	계획에는 파일 경로, 정확한 테스트 명령, 반증 가능한 수락 기준 (acceptance criteria), 명명된 롤백 (rollbacks)이 포함되어야 함. 구현 전 검토 필수.
구현 (Implement)	test-first, incremental-shipping	실행기 (runner) 출력을 붙여넣는 Red-green-refactor 방식 적용. 기능 플래그 (feature flags) 뒤에 수직 슬라이스 (Vertical slices) 배치. 리팩터링 시 테스트/성능 차이 (deltas)를 통해 동작 보존을 증명해야 함.
검증 (Verify)	verification-gate, evidence-driven-debugging	완료 전 필수 검증 게이트 (gate) 통과. 능동적인 디버깅을 통해 기록 (paper trail)을 유지함.
배포 (Ship)	code-review-loop, release-and-changelog	검증 증거가 붙여넣어진 검토 가능한 PR. 차이점(diff) 기반으로 생성된 변경 로그 (changelog)를 포함한 원자적 배포 (Atomic releases).
설정 (Setup, 오프스파인)	init	프로젝트 수준 설정을 위한 일회성 스캐폴딩 (scaffolding) 위저드.

15개의 모든 기술은 /claudekit:<name> 형식으로 사용자가 호출할 수 있습니다.

플러그인에는 다섯 가지 Claude Code 출력 스타일이 포함되어 있습니다. 이 스타일들은 Claude Code에 의해 자동으로 검색되므로 별도의 초기화 단계가 필요하지 않습니다. /config를 사용하거나 .claude/settings.local.json에서 outputStyle을 설정하여 전환할 수 있습니다.

스타일	사용 시기
브레인스토밍 (Brainstorm)	창의적 탐색 — 코드 작성 전 발산적 사고, 다양한 대안, 구조화된 트레이드오프 (trade-offs) 분석
심층 조사 (Deep Research)	철저한 조사 — 속도보다 완결성 중시, 신뢰 수준이 포함된 증거 인용 결과물
구현 (Implementation)	코드 중심 실행 — 최소한의 산문, 행동 중심의 업데이트, 확립된 패턴 준수
검토 (Review)	비판적 분석 — 문제점 우선 발견, 심각도 태그가 지정된 결과, 실행 가능한 제안
토큰 효율적 (Token Efficient)	압축된 출력 — 최소한의 산문, 코드 우선, 서문 없음

모든 스타일은 keep-coding-instructions: true를 사용하므로, 내부적으로는 Claude의 기본 코딩/테스트/검증 규율이 여전히 적용됩니다.

각 에이전트(Agent)는 단일 디스패처(Dispatcher)와 명확한 업무를 가집니다. 에이전트 비대화(Agent-bloat)는 없습니다.

에이전트 (Agent)	업무 (Job)	디스패치 주체 (Dispatched by)
claudekit:planner	사양(Specs)을 실행 가능한 계획으로 분해	write-plan
claudekit:architect	계획의 아키텍처 차원 점수 산정	plan-review-architecture
claudekit:experience-reviewer	계획의 UX + DX 차원 점수 산정	plan-review-experience
claudekit:investigator	증거 체인(Evidence chain)을 통한 근본 원인 조사	investigate-root-cause , evidence-driven-debugging
claudekit:tester	Red-Green 규율에 따른 테스트 설계 및 작성	test-first
claudekit:code-reviewer	머지(Merge) 전 차이점(Diffs)에 대한 구조적 검토	code-review-loop
claudekit:security-auditor	민감한 경로에 대한 OWASP 준수 검토	code-review-loop (민감한 경로)
claudekit:scout	코드베이스 매핑 및 의존성 감사	map-codebase , audit-dependencies

카테고리 (Category)	내용 (What)	위치 (Location)
규칙 (Rules)	API, 프론트엔드 (Frontend), 마이그레이션 (Migrations), 보안 (Security), 테스트 (Testing)	.claude/rules/
훅 (Hooks)	자동 포맷팅 (Auto-format), 위험한 명령 차단 (Block-dangerous-commands), 알림 (Notifications)	.claude/hooks/ + settings.local.json
MCP 서버 (MCP Servers)	Context7, Sequential, Playwright, Memory, Filesystem	.mcp.json

출력 스타일(Output styles)은 플러그인과 함께 제공되며 (output-styles/ 내 위치), Claude Code에 의해 자동으로 검색됩니다. 별도의 초기화(Init) 단계는 필요하지 않습니다.

모든 claudekit 스킬(Skill)은 8개의 필수 섹션을 포함합니다:

Frontmatter (프런트매터)— 이름(name), 사용자 호출 가능 여부(user-invocable), 트리거 키워드가 포함된 설명(description).
Overview (개요)— 한 단락: 스킬이 무엇을 하는지, 누구를 위한 것인지, 무엇이 강제되는지.
When to Use / When NOT to Use (사용 시기 / 사용하지 말아야 할 시기)— 구체적인 트리거 조건.
Process (프로세스)— 명시적인 목표(Goal) / 입력(Inputs) / 작업(Actions) / 출력(Output)을 포함한 번호가 매겨진 단계 또는 절차.
Rationalizations (합리화)— 원문 그대로의 인용구, 강화된 논거(steelmanned reasoning), 명명된 실패 모드(failure modes), 구체적인 대안을 포함한 변명 테이블.
Evidence Requirements (증거 요구사항)— 각 체크포인트가 생성해야 하는 산출물(artifact)과, 게으른 버전(lazy version)이 거부하는 내용.
Red Flags (레드 플래그)— 중단하고 재평가해야 함을 의미하는 구체적인 관찰 사항.
References (참고 문헌)— 직접적으로 관련이 있는 인용 저작물 (Software Engineering at Google, A Philosophy of Software Design, The Pragmatic Programmer 등).

당신의 작업에 맞는 체인(chain)을 선택하세요. 각 체인은 실제 중단 지점에서 종료됩니다 — 모든 프로젝트에 모든 단계가 필요한 것은 아닙니다.

"요청이 있습니다. 아직 코드는 없습니다."

shape-spec → write-plan → plan-review → [test-first + incremental-shipping] → verification-gate → code-review-loop

test-first (테스트 우선)

및

incremental-shipping (점진적 배포)

은 순차적인 것이 아니라 쌍으로 이루어집니다 — 모든 작업은 전체 슬라이스가 기능 플래그(feature flag) 뒤에서 배포되는 동안 red-green-refactor 과정을 거칩니다. 태그된 버전을 배포하는 라이브러리, 플러그인 또는 CLI 작업의 경우 → release-and-changelog (릴리스 및 변경 로그)를 추가하세요.

"무언가 고장 났습니다. 증상이 아니라 원인을 고치세요."

investigate-root-cause → test-first (regression test) → verification-gate → code-review-loop

evidence-driven-debugging (증거 기반 디버깅)은 가설을 테스트하기 위해 런타임 계측(runtime instrumentation: 로그, 중단점, 프로브)이 필요할 때 investigate-root-cause의 3단계 내에서 활성화됩니다.

"구조를 개선하세요. 동작을 보존하세요. 보존되었음을 증명하세요."

map-codebase → incremental-shipping (refactor-with-evidence 섹션) → verification-gate → code-review-loop

refactor-with-evidence (증거를 통한 리팩터링) 섹션은 전/후 테스트 차이(test deltas)를 요구합니다 (성능에 민감한 경우 성능 수치 포함). 그것이 이 규율의 전부입니다 — 측정된 증거 없이는 동작 보존을 주장할 수 없습니다.

"X는 어떻게 작동하나요? 무엇이 Y를 호출하나요? 영향 범위(blast radius)는 어디까지인가요?"

map-codebase

독립형(Standalone). 출력물은 계획(plan)에 첨부하거나 팀원에게 전달할 수 있는 증거가 인용된 지도(map)입니다. 탐색 과정에서 명세화(specifying)할 가치가 있는 실제 문제가 발견된 경우에만 shape-spec으로 체이닝(chain)하세요.

"CVE가 발생했습니다. 또는 분기별 보안 점검(hygiene) 시기입니다. 혹은 새로운 패키지를 추가하고 있습니다."

audit-dependencies

독립형(Standalone). 의존성별 테이블(선언됨 / 임포트됨 / 판정)과 도달 가능성 증명(reachability proof)이 포함된 권고 판정(advisory verdicts)을 생성합니다. 조치 사항(Action items)은 후속 PR로 넘어갑니다.

"이 디프(diff)는 인증(auth), 결제(payments), 암호화(crypto), 세션(sessions) 또는 토큰(tokens)을 건드립니다."

code-review-loop (민감한 경로에 대해 security-auditor를 자동 배정)

사전 준비 기술이 필요하지 않습니다. code-review-loop는 디프(diff)에서 민감한 경로를 감지하여 code-reviewer와 security-auditor를 모두 자동으로 배정합니다. 구조적인 결과와 함께 OWASP 기준에 부합하는 결과물을 얻을 수 있습니다.

"라이브러리, 플러그인 또는 CLI의 태그된 버전을 출시하려 합니다."

audit-dependencies → release-and-changelog

태그를 달기 전 라이브러리/플러그인 제작자를 위한 단계입니다. 감사(audit)를 통해 오래된 의존성(stale deps)과 파악되지 않은 CVE를 잡아내며, 릴리스(release) 기술은 (기억이 아닌) 실제 디프(diff)로부터 변경 로그(changelog)를 작성하고 릴리스 커밋을 원자적(atomic)으로 만듭니다.

실무에서 개발자들은 사소한 작업의 경우 단계를 건너뛰기도 합니다. 체이닝(chains)은 전체적인 규율(discipline)을 보여주며, 작업의 중요도에 따라 필요한 것을 사용하세요.

• Claude Code 1.0+
• Git
• Node.js 또는 Python (사용 중인 스택에 따라 다름)

MIT

Built by duthaho.