에이전트가 출제자이고 유저가 풀이자인, 실무 코드베이스 위의 TDD 기반 수제코딩 환경.
AI 에이전트가 코드를 완성할 때 비즈니스 로직의 특정 조각을 의도적으로 비워두고, 유저가 직접 손으로 채우는 Claude Code 플러그인입니다.
- Problem: AI가 모든 코드를 생성하면 개발자가 비즈니스 로직을 이해하지 못한 채 넘어간다. 코드를 읽기만 해서는 진짜 이해가 되지 않는다.
- Solution: 에이전트가 인프라와 보일러플레이트는 완전히 작성하되, 핵심 비즈니스 로직만 빈칸으로 남긴다. 유저는 TDD RED 상태에서 시작하여 GREEN을 달성한다.
- Scope: Claude Code 플러그인으로 동작하며, Jest, Vitest, pytest 등 기존 테스트 생태계를 그대로 활용한다.
- Claude Code CLI 설치 및 인증 완료
- Node.js 18+ (예제 실행 시)
# 1. marketplace 등록
claude plugin marketplace add ./package --scope user
# 2. 플러그인 설치
claude plugin install handcraft-coding@kanjseok --scope userclaude plugin uninstall handcraft-coding@kanjseok --scope user
claude plugin marketplace remove kanjseokclaude plugin list
# handcraft-coding@kanjseok Version: 0.2.1 Status: ✔ enabled개발 지시 끝에 /handcraft-coding:handcraft를 붙이면, 에이전트가 지시를 수행하면서 빈칸을 남깁니다.
Google OAuth 기능을 구현해줘. Next.js /api 라우팅으로
서버컴포넌트를 프록시로 활용하고, 세션 관리까지 포함해줘.
/handcraft-coding:handcraft intermediate
/handcraft-coding:handcraft intermediate 주문 검증 API 만들어줘
| 난이도 | 빈칸 복잡도 | 코드 규모 |
|---|---|---|
beginner |
변수 할당, 단일 조건 분기 | 1~3줄 |
intermediate |
유효성 검증, 상태 전환, 데이터 변환 | 3~10줄 |
advanced |
다중 도메인 규칙, 복잡한 상태 머신 | 10~25줄 |
| 명령어 | 설명 |
|---|---|
/handcraft-coding:handcraft [난이도] |
수제코딩 모드로 코드 생성 |
/handcraft-coding:handcraft-check |
빈칸 상태 확인 + 테스트 실행 |
/handcraft-coding:handcraft-hint [id] |
특정 빈칸에 대한 힌트 요청 |
유저: 개발 지시 + /handcraft-coding:handcraft intermediate
│
▼
에이전트: 코드 생성 (빈칸 포함) + 테스트 생성 + 챌린지 문서 생성
│
├─ 소스 코드에 HANDCRAFT:BEGIN/END 마커로 빈칸 표시
├─ *.handcraft.test.* 테스트 파일 생성 (모두 RED)
└─ .handcraft/challenge.md 챌린지 문서 생성
│
▼
유저: 빈칸을 직접 코딩으로 채움
│
▼
유저: /handcraft-coding:handcraft-check
│
▼
에이전트: 테스트 실행 결과 보고 (RED → GREEN)
에이전트가 코드를 생성하면 .handcraft/challenge.md가 함께 만들어집니다. 이 문서에는:
- 모든 빈칸의 파일 경로와 라인 번호
- 각 빈칸의 컨텍스트와 구현 가이드
- 빈칸 간 의존 관계를 고려한 추천 풀이 순서
package/ # marketplace 루트
├── .claude-plugin/
│ └── marketplace.json # marketplace 매니페스트 (name: kanjseok)
└── handcraft-coding/ # 플러그인
├── .claude-plugin/
│ └── plugin.json # 플러그인 매니페스트
├── skills/
│ ├── handcraft/SKILL.md # /handcraft 명령
│ ├── handcraft-check/SKILL.md # /handcraft-check 명령
│ └── handcraft-hint/SKILL.md # /handcraft-hint 명령
├── hooks/
│ └── hooks.json # 빈칸 마커 검증 + 현황 자동 출력
├── scripts/
│ ├── validate-blanks.sh # 마커 무결성 검증
│ └── count-blanks.sh # 빈칸 현황 카운트
├── templates/
│ └── blank-markers.md # 빈칸 마커 규격
├── examples/ # 예제 (주문 검증 API)
└── CLAUDE.md # 에이전트 동작 지침
- TDD 기반: 에이전트가 RED를 세팅하고, 유저가 GREEN을 달성한다
- 비즈니스 로직만 비운다: 인프라/보일러플레이트는 완전히 작성
- 복잡도가 유일한 난이도 축: 분량이나 네이밍으로 난이도를 올리지 않는다
- 기존 생태계 호환: Jest, Vitest, pytest 등 프로젝트의 테스트 프레임워크를 그대로 사용
- Design Plan — 설계 문서
- Blank Marker Specification — 빈칸 마커 규격
- Plugin CLAUDE.md — 에이전트 동작 지침
Contributions are welcome! Please read the Contributing Guide before submitting a PR.
CC BY 4.0 — Copyright (c) 2026 kanjseok
kanjseok — [email protected]