Matt Pocock은 TypeScript 교육으로 유명한 개발자입니다. 그의 skills 레포지토리는 AI 에이전트(Claude 등)가 반복적인 엔지니어링 작업을 자동화할 수 있도록 설계된 재사용 가능한 에이전트 스킬 모음입니다. 각 스킬은 AI가 특정 태스크를 어떻게 수행해야 하는지 명확한 프로세스와 철학을 담은 마크다운 문서입니다.
이 글에서는 레포지토리의 핵심 스킬들을 카테고리별로 정리합니다.
레포지토리 구조
skills/
├── engineering/ # 일상적인 코드 작업
├── productivity/ # 비코드 워크플로우 도구
├── misc/ # 가끔 쓰는 유틸리티
├── personal/ # 개인 설정
├── in-progress/ # 개발 중인 스킬
└── deprecated/ # 더 이상 사용하지 않는 스킬
각 스킬은 SKILL.md 파일로 구성되며, YAML frontmatter에 이름, 설명, 트리거 조건이 정의됩니다.
Engineering 스킬
1. diagnose — 버그 및 성능 진단
핵심 철학: 피드백 루프 구축이 전부다. 빠르고 결정론적인 pass/fail 신호가 있으면 버그는 90% 해결된 것이다.
진단 4단계:
- 피드백 루프 구축 — 실패를 재현할 수 있는 테스트/스크립트 만들기
- 재현 — 루프를 통해 버그 확인
- 최소화 & 가설 수립 — 원인 범위 좁히기
- 수정 & 회귀 테스트
피드백 루프 구축 우선순위:
1. 실패 테스트
2. curl/HTTP 스크립트
3. CLI 호출 + stdout diff
4. 헤드리스 브라우저 스크립트 (Playwright)
5. 캡처된 트레이스 재현
6. 임시 테스트 하니스
7. Property/Fuzz 루프
8. Git bisect 자동화
루프 없이 가설을 세우는 것은 금지. 재현이 되지 않으면 사용자에게 환경 접근권이나 로그 덤프를 요청해야 합니다.
2. tdd — 테스트 주도 개발
핵심 철학: 테스트는 구현이 아닌 동작(behavior) 을 검증해야 한다.
올바른 TDD vs 잘못된 TDD
잘못된 방법 (수평 슬라이스):
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
올바른 방법 (수직 슬라이스):
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3
수평 슬라이스는 상상한 동작을 테스트하게 되어 실제 동작 변화를 감지 못하는 나쁜 테스트를 만들어냅니다.
좋은 테스트 vs 나쁜 테스트:
- 좋은 테스트: 공개 인터페이스를 통해 동작 검증, 내부 구현 변경에 불변
- 나쁜 테스트: 내부 구현에 결합, 리팩토링 시 깨짐
3. improve-codebase-architecture — 아키텍처 개선
고유한 용어 체계를 사용합니다:
| 용어 | 정의 |
|---|---|
| Module | 인터페이스와 구현을 가진 모든 것 |
| Depth | 인터페이스 대비 동작의 레버리지. Deep = 작은 인터페이스, 많은 동작 |
| Seam | 인터페이스가 위치하는 지점, 동작을 직접 수정 없이 바꿀 수 있는 곳 |
| Adapter | Seam에서 인터페이스를 구현하는 구체적인 것 |
삭제 테스트(Deletion Test): 모듈을 삭제하면 복잡성이 사라지는가, 아니면 N개의 호출자에 재분산되는가? 후자라면 그 모듈은 가치 있는 deep module입니다.
결과물: Tailwind + Mermaid로 구성된 HTML 아키텍처 리뷰 리포트 (/tmp/architecture-review-<timestamp>.html)
4. prototype — 프로토타이핑
질문 유형에 따라 두 가지 브랜치:
- "이 로직/상태 모델이 맞는가?" → 인터랙티브 터미널 앱 (LOGIC 브랜치)
- "이게 어떻게 보여야 하는가?" → URL 파라미터로 전환 가능한 여러 UI 변형 (UI 브랜치)
프로토타입의 원칙:
- 처음부터 throwaway로 표시
- 한 명령으로 실행 가능해야 함
- 기본적으로 영속성 없음 (상태는 메모리에)
- 완료 후 반드시 삭제하거나 흡수
5. to-prd / to-issues — PRD와 이슈 생성
to-prd: 현재 컨텍스트에서 PRD를 작성하고 이슈 트래커에 게시. 인터뷰 없이 이미 아는 내용을 종합합니다.
to-issues: PRD나 계획을 수직 슬라이스(Tracer Bullet) 이슈로 분해:
각 이슈의 특성:
- HITL (Human In The Loop): 아키텍처 결정, 디자인 리뷰 등 인간 개입 필요
- AFK (Away From Keyboard): AI 에이전트가 독립적으로 구현 및 머지 가능
각 슬라이스는 스키마 → API → UI → 테스트를 모두 관통하는 얇지만 완전한 수직 경로여야 합니다.
6. triage — 이슈 트리아지
이슈 상태 머신:
needs-triage → needs-info (정보 필요)
→ ready-for-agent (AI 에이전트 처리 가능)
→ ready-for-human (인간 구현 필요)
→ wontfix (처리하지 않음)
모든 트리아지 코멘트는 > *This was generated by AI during triage.* 로 시작해야 합니다.
7. grill-with-docs — 문서 기반 계획 검증
도메인 글로서리(CONTEXT.md)와 ADR에 기반해 계획을 검증하는 인터뷰 스킬. 계획에서 기존 용어와 충돌하는 표현을 즉시 지적합니다.
8. zoom-out — 코드 컨텍스트 파악
모르는 코드 영역을 만났을 때 사용. AI에게 추상화 레이어를 올라가서 관련 모듈과 호출자의 전체 맵을 그려달라고 지시합니다.
Misc 스킬
git-guardrails-claude-code — 위험한 git 명령 차단
Claude Code에서 실행되는 PreToolUse 훅으로 위험한 git 명령을 차단합니다:
차단 목록:
git push(force push 포함)git reset --hardgit clean -f / -fdgit branch -Dgit checkout . / git restore .
프로젝트 전용(.claude/settings.json) 또는 전역(~/.claude/settings.json) 설치 가능.
migrate-to-shoehorn — TypeScript 테스트 개선
as 타입 어서션을 @total-typescript/shoehorn으로 교체합니다.
// Before: as 어서션 사용
getUser({
body: { id: "123" },
headers: {},
cookies: {},
// ...20개의 필드를 모두 채워야 함
} as Request);
// After: fromPartial 사용
import { fromPartial } from "@total-typescript/shoehorn";
getUser(fromPartial({
body: { id: "123" },
// 필요한 필드만 지정
}));
적용 범위: 테스트 코드만. 프로덕션 코드에는 절대 사용 금지.
setup-pre-commit — Pre-commit 훅 설정
Husky + lint-staged를 설정합니다:
# 설치
npm i -D husky lint-staged prettier
npx husky init
.husky/pre-commit:
npx lint-staged
npm run typecheck
npm run test
.lintstagedrc:
{
"*": "prettier --ignore-unknown --write"
}
scaffold-exercises — 연습 문제 스캐폴딩
AI Hero CLI 형식의 연습 문제 디렉토리 구조를 생성합니다:
exercises/
└── 01-section-name/
└── 01.01-exercise-name/
├── problem/ # 학생 워크스페이스 (TODO 포함)
├── solution/ # 참조 구현
└── explainer/ # 개념 설명
Productivity 스킬
caveman — 압축 통신 모드
토큰 사용량을 ~75% 줄이는 압축 통신 모드. 기술적 정확성은 유지하면서 불필요한 표현을 제거합니다.
일반 모드:
"Sure! I'd be happy to help you with that. The issue you're
experiencing is likely caused by..."
Caveman 모드:
"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
/caveman 또는 "caveman mode"로 활성화, "stop caveman"으로 비활성화.
grill-me — 계획 검토 인터뷰
계획이나 설계를 하나씩 질문하며 철저히 검토합니다. 각 질문에 권장 답변을 함께 제시하며, 코드베이스 탐색으로 답할 수 있는 질문은 탐색을 우선합니다.
handoff — 대화 요약 문서
현재 대화를 다른 에이전트가 이어받을 수 있도록 핸드오프 문서로 압축합니다. OS 임시 디렉토리에 저장하며, 민감한 정보(API 키, 비밀번호)는 제거합니다.
write-a-skill — 스킬 작성
새로운 에이전트 스킬을 올바른 구조로 작성하는 스킬입니다.
skill-name/
├── SKILL.md # 메인 지시사항 (필수)
├── REFERENCE.md # 상세 문서 (선택)
├── EXAMPLES.md # 사용 예시 (선택)
└── scripts/ # 유틸리티 스크립트 (선택)
좋은 스킬의 조건:
- YAML frontmatter에 명확한 트리거 조건 명시
- 500줄 초과 시 별도 파일로 분리
- 결정론적 작업은 스크립트로 번들링
핵심 철학 요약
Matt Pocock의 스킬 시스템이 강조하는 공통 원칙들:
- 도메인 언어 우선 — 모든 스킬은
CONTEXT.md의 글로서리와 ADR을 먼저 확인 - 수직 슬라이스 — 계층별 수평 분할이 아닌 기능별 수직 분할
- 피드백 루프 — 어떤 작업이든 빠르고 결정론적인 검증 루프 구축
- Throwaway 명시 — 프로토타입은 처음부터 버릴 것으로 표시
- AFK 우선 — 인간 개입 없이 AI가 처리할 수 있는 작업을 최대화
이 스킬 시스템은 단순한 프롬프트 모음이 아니라, AI 에이전트와 함께하는 소프트웨어 엔지니어링 워크플로우를 체계화한 시도입니다.
댓글 없음:
댓글 쓰기