---
title: Claude Code 핵심 도구 6개 + HTML 문서화 전환 인사이트
type: research
author: nano
status: done
date: 2026-05-20
---

# Claude Code 핵심 도구 6개 + HTML 문서화 전환 인사이트

> 출처: YouTube 두 편
> - [400시간 만에 알게 된 Claude Code의 진짜 핵심 도구 6개](https://www.youtube.com/watch?v=BZPaZzjLIOY)
> - [Anthropic 엔지니어가 마크다운 버린 5가지 이유](https://www.youtube.com/watch?v=CLI95vLlkxY)

---

## Part 1. Claude Code 핵심 도구 6개

### 영상 개요

Claude Code를 10개월 이상 실제로 운영하면서 검증한 6개의 실용 도구 큐레이션. GitHub Star 수와 실제 효용성의 괴리를 지적하며, **매일 켜서 쓰는 것들의 패턴**에 집중. 별점 조작(README에 프롬프트 인젝션 심어 에이전트가 자동으로 Star 누르게 유도)도 실제로 존재한다는 경고 포함.

---

### 핵심 도구 목록

#### 1. Superpowers (플러그인)

- **출처**: Claude Code 공식 마켓플레이스
- **핵심 기능**: 계획 → 테스트 작성 → 코드 구현 → 이중 리뷰(스펙/품질) 워크플로우 자동화
- **해결하는 문제**: 급하게 짜는 코드의 엣지 케이스 실패 패턴. 단계 건너뛰기 방지
- **자주 쓰는 서브 스킬 2개**:
  - `brainstorming` — 기능 개발 전 요구사항 명확화 질문 세트
  - `sub-agent driven development` — 큰 일을 서브 에이전트에 분배, 메인 컨텍스트 보존
- **우리 시스템과의 연관성**: `/spec` → `/implement` → `/code-review` 파이프라인과 직접 매칭. SDD 워크플로우(ADR-003)가 이 패턴을 이미 내재화함

#### 2. G-Stack (Y Combinator)

- **출처**: Gary Tan(YC) 공개 셋업
- **자주 쓰는 서브 스킬 2개**:
  - `office` — 새 아이디어를 YC 오피스아워 방식의 6가지 질문으로 검증 (수요, 기존 해결법, 가장 좁은 진입점 등)
  - `browse` — 백그라운드 Chrome 세션 유지. 명령 하나당 100-200ms, 기존 대비 20배 빠름
- **해결하는 문제**: 모호한 아이디어 구체화 / 브라우저 작업 성능 저하
- **우리 시스템과의 연관성**: Jarvis 자율 루프(HAN-62)에서 장시간 세션 유지 필요. Browse 도구로 30분 → 2시간+ 연장 가능성 있음

#### 3. Grill Me (매퍼 제작)

- **출처**: 커뮤니티 제작자 "매퍼"
- **핵심 기능**: 코드/설계를 제출하면 "이거 왜 이렇게 했어요?" 방식으로 동료 코드 리뷰 시뮬레이션
- **해결하는 문제**: 1인 개발자의 코드 리뷰 부재. PR 전 실수 사전 차단
- **우리 시스템과의 연관성**: `/code-review:code-review` 스킬과 보완적. PR 머지 전 체크포인트로 활용 가능

#### 4. Improvement Architecture (매퍼 제작)

- **핵심 기능**: 기존 코드베이스 구조 전체 재검토. "여기 이렇게 분리하면 테스트 쉬워져" 식의 리팩토링 방향 제시
- **해결하는 문제**: 리팩토링 범위와 방향 판단 불명확
- **우리 시스템과의 연관성**: 큰 리팩토링 전 아키텍처 검토 단계에 삽입 가능

#### 5. Codex Review (OpenAI 플러그인)

- **핵심 기능**: Claude가 짠 코드를 OpenAI 모델 관점에서 재검토. 단일 모델 사각지대 보완
- **워크플로우 위치**: Superpowers로 짜고 → 마지막에 Codex Review로 마무리
- **우리 시스템과의 연관성**: 멀티 LLM 비전과 일치. 현재 Gemini cross-check MCP 보유 — Codex Review와 역할 중복 검토 필요

#### 6. Vercel React Best Practices

- **핵심 기능**: React 코드 작성 시 Vercel 권장 모범 사례 자동 강제 (Server Component, useClient, 레거시 패턴 제거 등)
- **우리 시스템과의 연관성**: 나혼렙(DAV) 프로젝트 Next.js 기반 → 즉시 적용 가능

#### 보너스. PPTX / PDF 스킬

- 발표자료/보고서 자동 생성
- **주의**: 한 번에 다 깔지 말 것. 컨텍스트 무게만 늘어남

---

### 메타 인사이트

- **별점 ≠ 품질**: GitHub Star는 마케팅 신호. 프롬프트 인젝션 심은 README 실제 존재. 일일 사용 빈도와 엣지 케이스 안정성이 실질 지표
- **Claude를 느리게 만드는 도구가 더 좋은 결과**: 즉시 코드 뱉는 것보다 계획→테스트→코드→리뷰 강제가 디버깅 시간 90% 절감
- **컨텍스트 효율 우선**: 개별 스킬 화려함보다 세션 수명 연장(browse, sub-agent 분리)이 더 중요

---

### 우선 도입 검토 항목

| 우선순위 | 도구 | 이유 |
|---------|------|------|
| 1 | Browse (G-Stack) | HAN-62 자율 루프 세션 수명 연장 직결 |
| 2 | Codex Review | Gemini cross-check MCP와 비교 후 선택 |
| 3 | Grill Me | `/code-review` 스킬과 병행 평가 |
| 4 | Vercel React BP | DAV 프로젝트 즉시 적용 |

---

## Part 2. HTML 문서화 전환 인사이트

### 영상 핵심 주장 (Tariq Shifa, Claude Code 팀 엔지니어)

"100줄 넘는 마크다운 파일은 나도 안 읽는다. 동료에게 읽으라고 시키는 건 거의 불가능하다."

**마크다운 → HTML 전환 이유 5가지**:

1. **정보 밀도**: MD는 색·SVG·애니메이션·인터랙션 불가. HTML은 전부 가능
2. **시각적 명확성**: 탭 구분, 모바일 대응, 일러스트 → 끝까지 읽힐 확률 ↑
3. **공유 용이**: S3 업로드 + 링크 하나. 브라우저 바로 열림
4. **양방향 인터랙션**: 슬라이더로 파라미터 튜닝 → Copy-as-prompt 버튼으로 다시 AI에 전달
5. **Claude Code 컨텍스트 활용**: 로컬 파일·MCP 데이터 모두 끌어와 HTML 한 페이지로 시각화

**Karpathy 동조**: "HTML은 단순 트릭이 아니라 AI 출력의 진화 단계다. 텍스트(1차선) → MD(2차선) → HTML(4차선 고속도로) → Interactive Neural Video"

**단점**:
- 토큰 2-4배 더 소비
- git diff 노이즈 (HTML 한 줄 바꿔도 줄바꿈 diff 많음)

---

### 우리 hangman-docs HTML 시스템 현황 진단

**현재 상태**: 설계는 존재, 실행은 거의 없음

| 항목 | 상태 |
|------|------|
| render.py | 존재, 미실행 |
| base.html | 템플릿 존재 |
| 실제 HTML 파일 | triage-board.html 1개뿐 |
| reports/ HTML | 0개 (전부 .md만) |
| 자동화 | 없음 (수동 실행만) |

**영상 주장 달성도**:

| 주장 | 달성 여부 | 비고 |
|------|----------|------|
| 정보 밀도 ↑ | ✗ | 자동화 없음 |
| 시각적 명확성 | △ | base.html 있으나 미적용 |
| 공유 용이 | ✗ | 배포 파이프라인 없음 |
| 양방향 상호작용 | ✗ | MD가 canonical 유지 |
| Claude Code 활용 | ✗ | .md만 컨텍스트에 포함 |

---

### 개선 선택지

**옵션 A: Dual-Format 컨벤션 폐기 (현실주의)**
- 7개월째 "선언만 있는" 상태 → 인지 비용만 발생
- `.md` 단일 채널로 정리, README에 폐지 기록
- 필요시 "HTML로 만들어줘" 한 줄로 일회성 생성

**옵션 B: 최소 자동화 (투자 회수)**
- post_write_hooks에 render.py 연결 → .md 저장 시 자동 HTML 생성
- pandoc 의존 제거: `python-markdown2` (순수 Python, 경량)
- base.html 다크모드 + 모바일 반응형 강화

**권고**: 현재는 **옵션 A**. 면접 준비 기간에 시스템 정비 작업 불필요. 2-3개월 후 자율 루프(HAN-62) 안정화 시점에 옵션 B 재검토.

---

## 결론

- **Claude Code 도구**: Browse(G-Stack) + Codex Review가 현재 시스템에 가장 직접적 가치
- **HTML 문서화**: 좋은 아이디어지만 자동화 없으면 의도 선언에 그침. 현 시점 폐기 후 재검토 권고
- **공통 교훈**: 도구는 자동화까지 완성되어야 실제 사용. 선언적 컨벤션만으론 채택 안 됨