mattpocock Skills 입문 가이드: AI가 TDD와 구조화된 디버깅을 배우게 하세요

프로젝트 소개

mattpocock/skills는 AI 프로그래밍 도구를 위한 “엔지니어링 방법론 스킬킷”입니다. 핵심 출발점은 아주 단순합니다. AI 코딩 도구는 빠르지만, AI 코딩 도구가 곧 신뢰할 수 있다는 뜻은 아닙니다.

Matt Pocock은 수많은 실습을 통해 AI 코딩에서 자주 발생하는 실패 패턴을 네 가지로 정리했습니다.

• 요구사항이 불일치: AI가 이해했다고 생각했는데, 실제로는 다른 길로 갑니다
• 출력이 너무 장황함: AI가 20개의 단어로 1개의 단어로도 충분한 내용을 말합니다
• 코드가 작동하지 않음: 피드백 루프가 없어, AI가 블랙박스에서 맹목적으로 코드를 작성합니다
• 아키텍처가 빠르게 무너짐: AI가 개발 속도를 높이는 만큼 소프트웨어의 엔트로피(혼란)도 함께 가속합니다

이 네 가지 문제는 도구의 버그가 아니라, 방법론의 부재에서 비롯됩니다. mattpocock/skills는 그 원인을 정확히 겨냥해, 수십 년의 엔지니어링 경험을 조합 가능한 한 묶음의 스킬(Skills)로 압축합니다. 그 결과, 어떤 모델을 쓰더라도 AI가 동일한 엔지니어링 규율을 따르게 됩니다.

난이도 / 소요 시간 / 기대 효과

난이도: 입문급 — TDD 경험이 없어도 됩니다. 명령줄을 사용할 줄 알고 AI 코딩 도구를 다룰 수 있으면 충분합니다
소요 시간: 전체 과정을 처음부터 끝까지 한 번 돌리면 약 30분
기대 효과: 요구사항 정렬 → 테스트 주도 개발(TDD) → 구조화된 디버깅 → 아키텍처 회고까지 이어지는 완전한 워크플로를 정립합니다

대상 독자

• 백엔드/풀스택 개발자(경력 1~5년)
• Claude Code, Codex 또는 유사한 AI 코딩 도구를 이미 사용해 본 사람
• “사용은 되는데 불안정한” AI가 생성한 코드를 경험했고, 통제 가능한 개발 리듬을 만들고 싶은 사람
• TDD에 관심은 있지만 계속 적절한 진입점을 찾지 못한 사람

핵심 의존 요소와 환경

전체 프로젝트 구조 트리

skills/
├── CLAUDE.md                          # 스킬 디렉터리 규격 안내
├── README.md                          # 개요 및 사용 문서
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # 구조화된 디버깅 프로세스
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # 문서 기반 심층 인터뷰
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # 아키텍처 개선 진단
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # 초기 설정 진입점
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # TDD 수직 슬라이스 워크플로
│   │   │   ├── tests.md               # 좋은/나쁜 테스트 예시
│   │   │   ├── mocking.md             # Mock 모범 사례
│   │   │   ├── refactoring.md         # 리팩터링 시점 판단
│   │   │   ├── deep-modules.md        # 딥 모듈 설계 원칙
│   │   │   └── interface-design.md    # 테스트 가능한 인터페이스 설계
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # 요구사항을 GitHub Issues로 분해
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # PRD 생성
│   │   ├── triage/
│   │   │   └── SKILL.md               # Issue 분류 상태 머신
│   │   └── zoom-out/
│   │       └── SKILL.md               # 코드에 대한 전역 관점 해석
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # 압축 커뮤니케이션 패턴, 토큰 75% 절감
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # 요구사항 심층 인터뷰
│   │   └── write-a-skill/
│   │       └── SKILL.md               # 커스텀 스킬 작성 가이드
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Git 안전 가드레일
│       └── scaffold-exercises/
│           └── SKILL.md               # 연습 디렉터리 스캐폴딩
└── .claude-plugin/
    └── plugin.json                    # 플러그인 메타데이터

단계별 안내

1단계: mattpocock Skills 설치

Skills를 지원하는 어떤 AI 코딩 도구에서든 아래 명령을 실행해 설치를 완료하세요.

npx skills@latest add mattpocock/skills

설치 스크립트는 활성화할 스킬을 선택하고, 해당 스킬들이 어떤 AI 도구에 바인딩될지 안내합니다. 핵심 단계: /setup-matt-pocock-skills를 선택했는지 확인하세요. 이것이 이후 모든 스킬의 초기화 진입점입니다.

2단계: 초기 설정

설치가 끝나면 AI 코딩 도구에서 다음을 실행합니다.

/setup-matt-pocock-skills

이 스킬은 순서대로 다음을 질문합니다.

1. Issue Tracker: Issues를 어떤 도구로 관리할지 선택(GitHub / Linear / 로컬 파일)
2. Triage Labels: Issue에 태그를 달 때 어떤 단어를 쓸지(/triage 스킬에서 사용)
3. 문서 저장 경로: 생성된 ADR과 문서는 어디에 둘지

설정을 마치면, 프로젝트 루트 디렉터리에 CONTEXT.md가 생성되며, 이는 AI와 당신 사이의 “공유 언어 사전” 역할을 합니다. 이 파일은 매우 중요합니다. 프로젝트에서 용어가 사용되는 방식을 통일해 주며, 이후 AI의 모든 네이밍과 주석은 이 파일을 기반으로 이루어집니다.

3단계: /grill-me로 요구사항 정렬

새 요구사항이나 설계안을 AI에게 맡기고 싶을 때, 바로 시작하지 마세요. 먼저 아래를 실행합니다.

/grill-me

AI는 질문을 하나씩 던지며 의사결정 트리의 각 분기를 전부 따져봅니다. 예를 들어 “결제 모듈에 환불 기능을 추가”하려 한다면 AI는 이렇게 되묻습니다.

• 환불은 전액인가요, 부분인가요?
• 환불이 트리거되는 조건은 무엇인가요(사용자 수동 / 리스크 제어 자동 / 고객센터 수동)?
• 환불 후 재고는 어떻게 처리하나요?
• 환불 로그를 영속화해야 하나요?

각 질문마다 추천 답변을 제시하므로, 당신은 그에 대해 확인하거나 수정만 하면 됩니다. 이 과정은 구조화된 인터뷰처럼 진행되며, AI가 당신이 하려는 일을 ‘문자 그대로의 뜻’으로 오해하지 않고 실제로 이해했는지 보장합니다.

4단계: /tdd로 수직 슬라이스 테스트 주도

요구사항이 정렬되면 개발 단계로 들어갑니다. 여기서 mattpocock/skills의 핵심이 드러납니다. 수평 슬라이스는 금지입니다.

수평 슬라이스란 무엇인가요? 먼저 모든 테스트를 다 작성한 뒤, 그다음 모든 코드를 다 작성하는 방식입니다. TDD를 오해하는 대표적인 함정이며, AI가 특히 이렇게 하려는 경향이 있습니다. 그 결과 테스트가 ‘상상한 행동’을 검증하게 되고, 실제 행동이 검증되지 않습니다.

올바른 방법은 한 번에 오직 하나의 수직 슬라이스만 하는 것입니다.

RED:   테스트 하나를 작성하고 첫 번째 행동을 설명 → 테스트 실패
GREEN: 테스트를 통과시키는 최소 코드 작성 → 테스트 통과
REFACTOR: 리팩터링(선택)

이 루프를 반복하세요. AI가 테스트 하나를 완성할 때마다 이미 그 구현 코드가 “거쳐 갔기” 때문에, AI가 검증하는 것은 예상 행동이 아니라 실제 행동입니다.

구체적인 예를 볼까요. 장바구니 결제 기능을 구현한다고 가정해 봅시다.

// 첫 번째 라운드: “장바구니에 상품을 추가할 수 있다”만 테스트
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 입문', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — 테스트가 통과할 정도로 최소만 구현
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// 두 번째 라운드: “장바구니가 총액을 계산한다”를 테스트
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 입문', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 실전', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — totalPrice 메서드 추가
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

각 라운드는 항상: 테스트 실패 → 최소 코드로 통과 → 다음 라운드입니다. 이것이 수직 슬라이스의 핵심 리듬입니다.

5단계: /diagnose로 구조화된 디버깅

코드에 문제가 생겼다면, AI에게 “버그를 고쳐줘”라고 바로 맡기지 마세요. 먼저 피드백 루프를 만들어야 합니다. 다음을 실행하세요.

/diagnose

/diagnose는 AI가 여섯 단계의 디버깅 루프를 반드시 거치도록 강제합니다.

이 과정이 중요한 이유는? AI가 가장 흔하게 하는 디버깅 방식은 “찍어 고쳐 보고, 결과가 안 나오면 또 찍어 고쳐 보는” 형태입니다. 피드백 루프가 없다면 이는 어둠 속에서 다트를 던지는 것과 같습니다. /diagnose는 디버깅을 마법이 아니라 엔지니어링 학문으로 바꿉니다.

전형적인 상황을 하나 들어볼게요. 결제 인터페이스에서 갑자기 500 오류가 난다고 가정합니다.

// 1단계: 피드백 루프 구성 — 특정 인터페이스로 실패를 고정하는 테스트를 작성
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // 현재 실패, 실제로는 500을 반환
  });
});

3단계에서는 가설 목록을 생성합니다.

1. “재고 서비스 타임아웃으로 인해 포착되지 않은 예외가 발생”이라면, 재고 서비스를 성공으로 mock하면 500이 사라집니다
2. “DB 트랜잭션이 커밋되지 않음”이라면 transaction.commit() 호출을 확인해 문제가 있음을 발견할 수 있습니다
3. “결제 게이트웨이가 포맷 파싱 오류를 반환”이라면, 게이트웨이 mock 데이터 포맷이 문제를 재현하는지 검증하면 됩니다

AI는 수정들을 한꺼번에 다 쌓아 올리지 않고, 가설 하나씩 검증합니다.

6단계: /write-a-skill로 커스텀 스킬을 만들기

어떤 프로젝트에서 쌓인 전용 워크플로가 있다면, 이를 Skill로 포장해 해당 프로젝트에서 AI가 언제든 호출할 수 있게 만들 수 있습니다.

/write-a-skill

AI가 순서대로 질문합니다.

1. 이 Skill은 어떤 영역을 다루나요?
2. 구체적인 사용 시나리오는 무엇인가요?
3. 스크립트를 첨부해야 하나요, 아니면 순수 명령만으로 충분한가요?
4. 참고할 만한 자료가 있나요?

그다음 표준 구조를 생성합니다.

my-custom-skill/
├── SKILL.md              # 메인 지시 파일(필수)
├── REFERENCE.md          # 상세 문서(내용이 100줄을 넘으면 분리)
├── EXAMPLES.md           # 사용 예시
└── scripts/
    └── helper.ts         # 도구 스크립트(선택)

SKILL.md의 description 필드는 이 Skill을 AI가 인지하는 유일한 진입점이며, 형식에 엄격한 요구사항이 있습니다.

---
name: my-custom-skill
description: JSON Schema로부터 타입 안전한 API 클라이언트를 생성하고, Mock 데이터를 주입합니다.
              Use when user mentions "API client", "generate types", or "mock data".
---

description의 첫 문장은 “무엇을 하는지”를 말하고, 둘째 문장은 “어떤 상황에서 트리거되는지”를 말합니다. 트리거 단어를 넣어 AI가 자동으로 로딩하도록 유도하세요.

자주 발생하는 문제 해결

1. AI가 테스트를 실행하지 않고 바로 코드를 작성

현상: /tdd를 호출했는데도 AI가 구현으로 바로 뛰어들며 RED 단계를 건너뜁니다.

해결:

• CONTEXT.md에 프로젝트의 테스트 프레임워크와 테스트 규약이 정의되어 있는지 확인
• /tdd 시작 시 “테스트 하나만 작성하고, 다른 코드는 작성하지 말 것”을 명확히 말하기
• AI가 여전히 건너뛴다면, 대화에서 직접 “먼저 실패하는 테스트를 하나 작성해”라고 입력해 RED로 돌아오게 유도

원인: TDD 개념을 글자 그대로 이해하는 문제입니다. AI는 “테스트를 썼으니 TDD다”라고 생각하고, ‘테스트 실패 자체가 신호’라는 점을 이해하지 못합니다.

---

2. 수평 슬라이스 함정 — 한 번에 모든 테스트 작성

현상: AI가 /tdd에서 테스트 파일 10개를 한 번에 만들고, 그다음 구현을 한 번에 작성합니다.

해결:

• 직접 개입: AI에게 “첫 번째 테스트만 쓰고, 그걸 구현하라”고 지시
• CONTEXT.md에 반패턴 경고 추가: “수평 슬라이스 금지. 매번 수직 슬라이스 하나만 수행”

원인: AI가 “한 번에 끝내는” 환상을 좋아하기 때문입니다. 수평 슬라이스는 완성도 있어 보이지만 실제 산출물은 취약해집니다.

---

3. 디버깅 루프에 피드백 신호가 없음

현상: /diagnose를 호출했는데도 AI가 코드를 반복해서 바꾸기만 하고, 반복 가능한 실패 신호를 만들지 않습니다.

해결:

• Phase 1이 통과되지 않았으면 Phase 2로 가지 마세요. AI에게 “아직 반복 가능한 실패 신호가 없으니, 피드백 루프를 계속 구성해라”라고 분명히 말하기
• mock이 아니라 node-fetch와 실제 HTTP 요청을 사용해 end-to-end 신호를 구성해 보세요

원인: 피드백 루프가 디버깅의 핵심입니다. 이것이 없으면 이후의 모든 조치가 맹목적으로 됩니다.

---

4. 스킬 설명이 실패 — Skill이 자동으로 트리거되지 않음

현상: 커스텀 Skill을 작성했지만 AI가 로딩하지 않습니다.

해결:

• plugin.json에서 해당 Skill이 등록되어 있는지 확인
• description에 트리거 단어(사용자가 실제로 말할 법한 표현)가 포함되어 있는지 확인
• SKILL.md의 name과 description 형식이 요구사항을 만족하는지 확인(YAML frontmatter)

원인: Skills 로딩은 description 안의 키워드 매칭에 의존합니다. 설명이 정확하지 않으면 트리거되지 않습니다.

---

5. /grill-me 인터뷰가 단방향 보고가 됨

현상: /grill-me를 실행하면 AI가 당신의 정보를 받기만 하고, 능동적으로 질문하지 않습니다.

해결:

• AI가 질문할 때만 자신이 인터뷰 모드에 들어갔다고 설명하면, 계속 응답하고 중단하지 말기
• AI가 3라운드 이상 침묵하면, 직접 “계속 질문해 주세요. 더 많은 정보가 있어요”라고 말하기
• 보통 AI가 “이미 이해했다”고 생각해서 실제로는 문자 그대로만 이해한 경우가 원인입니다

원인: AI는 “이해한 것처럼 보이는 상태”로 빠르게 수렴하는 경향이 있으며, 모든 분기를 끝까지 열거하지는 않습니다.

---

6. CONTEXT.md가 너무 커서 토큰이 폭발

현상: 프로젝트가 진행되면서 CONTEXT.md가 계속 커지고, AI가 컨텍스트 초과를 겪거나 응답이 느려지기 시작합니다.

해결:

• 정기적으로 CONTEXT.md를 리팩터링하세요. “이미 안정화된 범용 용어”는 유지하고, “임시 의사결정 기록”은 docs/adr/ 디렉터리로 옮기기
• /improve-codebase-architecture는 어떤 내용을 CONTEXT.md에서 추출해야 하는지 식별하는 데 도움을 줄 수 있습니다

원인: CONTEXT.md는 동적으로 커지는 파일입니다. 유지보수를 하지 않으면 결국 두 번째 모노레포가 됩니다.

확장 읽기 / 고급 방향

방법론 확장: Matt Pocock 본인은 TypeScript 타입 체조(타입 조작) 운동가이며, 그의 Total TypeScript 강의는 타입 기반 개발을 이해하는 데 훌륭한 보충 자료입니다.

TDD에서 아키텍처 개선으로: 코드베이스가 몇 라운드의 TDD 리팩터링을 거친 뒤에는 /improve-codebase-architecture로 아키텍처 진단을 할 수 있습니다. 이 스킬은 CONTEXT.md의 도메인 언어와 docs/adr/의 의사결정 기록을 기반으로 “얕은 모듈”(인터페이스는 복잡하지만 기능은 적음)과 리팩터링 기회를 식별합니다.

커스텀 스킬 생태계: mattpocock/skills의 설계 철학은 “작고, 조합 가능”입니다. 제공되는 스킬 전체를 다 쓸 필요는 없습니다. 예를 들어 /tdd와 /diagnose만 설치하고, 일상 개발에서 점진적으로 도입해도 됩니다. 커뮤니티에도 이 프레임워크를 기반으로 만든 다른 스킬 세트가 있으니 주목할 만합니다.