Matt Pocock의 스킬을 작은 기능에 적용하기: 질문·용어·테스트의 연결

AI가 만든 코드가 마음에 들지 않을 때 ‘기본기가 중요하다’고 말하기는 쉽다. 다음 요청에서 무엇을 바꿔야 하는지는 여전히 남는다. 질문을 더 해야 하는지, 테스트를 먼저 써야 하는지, 이미 복잡해진 코드를 정리해야 하는지 판단할 기준이 필요하다.

Matt Pocock의 공개 스킬은 이 문제를 작업 절차로 읽어 볼 만한 자료다. 여기서는 발표의 인기를 소개하거나 검증하지 못한 인용을 재현하지 않는다. 2026년 9월 8일에 확인한 저장소와 스킬 문서를 바탕으로, 예약 변경 기능 하나에 적용하는 예시를 만든다. 실제 서비스에 적용해 성과를 측정한 기록은 아니다. Matt Pocock의 스킬 저장소

질문의 목표는 개수가 아니라 서로 다른 기대를 찾는 것이다

‘사용자가 예약을 변경할 수 있게 해 줘’라는 요청부터 시작해 보자. 구현자는 날짜 입력창을 만들 수 있다. 운영자는 승인받은 예약만 변경해야 한다고 생각할 수 있다. 사용자는 날짜 변경과 취소 후 재예약을 같은 행동으로 볼 수 있다. 화면이 빨리 나와도 이 차이가 남으면 잘못된 제품이 된다.

질문은 결과를 바꾸는 순서로 해야 한다. 누가 변경할 수 있는가. 언제까지 가능한가. 다른 사람이 같은 시간대를 선택하면 어떻게 되는가. 변경 실패 시 원래 예약은 남는가. 요금이 달라지면 이 기능의 범위에 결제까지 포함되는가. 마지막 질문의 답에 따라 단순한 날짜 수정과 새로운 업무 흐름이 갈린다.

여기서 질문을 40개나 100개 해야 한다는 규칙은 두지 않겠다. 불확실성이 적은 수정까지 긴 인터뷰로 만들면 작업만 늦어진다. 반대로 데이터 손실이나 권한을 바꾸는 결정을 추측으로 넘기면 안 된다. 코드에서 확인할 수 있는 현재 동작은 먼저 읽고, 사용자의 선택이 필요한 질문에 시간을 쓰는 편이 낫다.

질문 뒤에 남길 것은 대화 전문보다 결정 목록이다. 예시에서는 ‘변경 실패 시 원래 예약을 유지한다’, ‘다른 사용자의 예약은 변경할 수 없다’, ‘이번 작업에 결제는 넣지 않는다’가 남는다. 이 문장을 검토자가 읽고 구현의 옳고 그름을 판단할 수 있어야 한다.

같은 단어가 같은 상태를 가리키는지 확인한다

이제 ‘예약’이라는 단어를 쪼개 보자. 임시 선택과 확정 예약이 같은 객체인가. 취소된 예약을 조회할 수 있는가. 변경 요청이 대기 중일 때 사용자에게 보이는 날짜는 어느 쪽인가. 말로는 다 예약이라고 부르지만 코드에서는 서로 다른 상태가 필요할 수 있다.

Pocock의 domain-modeling 문서는 용어를 구체적 사례와 기존 코드에 대조하고, 합의한 뜻을 기록하는 절차를 제시한다. 용어집을 구현 메모나 모든 결정의 저장소로 쓰지 않는다는 구분도 있다. domain-modeling 원문

예시 용어집에는 세 단어만 먼저 넣을 수 있다. ‘확정 예약’은 사용자와 시간대가 확정된 상태다. ‘변경 요청’은 확정 예약의 새 시간대를 제안하는 입력이다. ‘변경 완료’는 새 시간대를 확보하고 원래 예약과의 관계를 갱신한 결과다. 이 정의가 실제 서비스 규칙과 맞는지는 담당자가 결정해야 한다.

용어를 정했다고 상태 모델이 자동으로 완성되지는 않는다. 변경 요청이 거절됐을 때 확정 예약이 취소되는 설계라면 앞서 합의한 조건과 충돌한다. 코드의 상태 전이와 용어집을 나란히 놓고 반례를 만들어 본다. 정의를 읽었을 때 오류가 보이는 정도로 구체화돼야 문서가 제 역할을 한다.

파일명이나 클래스명까지 무조건 새 용어로 바꿀 필요는 없다. 이미 쓰는 이름과 뜻이 같으면 연결 관계만 문서화할 수 있다. 이름 변경을 별도 작업으로 분리해야 기능 수정의 diff가 불필요하게 커지지 않는다. 용어를 맞추려는 목적이 대규모 리팩터링의 자동 승인으로 바뀌어서는 안 된다.

테스트는 구현 순서가 아니라 사용자가 관찰할 결과를 고정한다

첫 테스트로 무엇을 고를까. 내부 함수가 세 번 호출됐다는 검사보다 정상 예약을 새 시간대로 변경했을 때 조회 결과가 바뀌는 검사가 사용자 요구와 가깝다. 다음에는 이미 찬 시간대로 변경을 요청하면 거절되고 기존 예약이 남는지 본다. 성공만 검사하면 중요한 보존 조건을 놓친다.

tdd 스킬 문서는 공개 인터페이스를 통해 동작을 확인하고, 내부 구조를 그대로 따라 하는 테스트를 피하라고 설명한다. 현재 문서에서는 작은 수직 단위로 실패하는 테스트와 구현을 이어 가며, 리팩터링은 검토 단계로 구분한다. 스킬 버전에 따라 세부 절차는 바뀔 수 있으니 오래된 영상의 단계 이름을 그대로 적용하기 전에 설치한 파일을 읽어야 한다. tdd 스킬 원문

아래 표는 구현 전 합의할 예시다. 실제 저장소의 테스트 실행 결과가 아니다.

예상 결과는 구현에서 계산해 복사하지 않는다. 사람이 확인한 예시와 명세에서 가져와야 같은 버그를 테스트가 되풀이하지 않는다. 실제 시간과 외부 서비스에 의존하는 부분은 통제 가능한 시험 환경을 준비한다. 모든 의존성을 가짜로 바꾸면 실제 저장 동작의 문제가 가려질 수 있으므로 어느 경계를 검사하는지도 적어 둔다.

AI에게 맡길 수 있는 것은 이 합의된 사례의 구현과 검증이다. 테스트가 실패했을 때 기대 결과부터 바꾸려 한다면 요구사항 변경인지 단순 오류 수정인지 구분해야 한다. 원하는 동작이 바뀌었다면 테스트와 명세를 함께 검토하고, 그렇지 않다면 구현을 고친다.

깊은 모듈은 큰 파일이나 만능 서비스가 아니다

예약을 변경하려면 호출자가 시간대 확인, 기존 예약 잠금, 갱신, 실패 복구의 순서를 모두 알아야 한다고 가정해 보자. 화면마다 그 순서를 복사하면 한 곳에서 실수하기 쉽다. 하나의 변경 요청 인터페이스 뒤에 일관된 처리를 모으는 편이 나을 수 있다.

codebase-design 문서가 말하는 깊이는 구현 줄 수가 아니라 호출자가 배울 인터페이스에 비해 얼마나 많은 동작을 안전하게 사용할 수 있는지에 가깝다. 인터페이스에는 타입뿐 아니라 오류 방식과 순서 제약도 포함된다. codebase-design 원문

예시 함수 requestReschedule은 예약 식별자와 새 시간대를 받고 성공 또는 거절 이유를 반환하도록 생각할 수 있다. 이름만 그럴듯한 함수 하나를 추가하고 내부 처리는 그대로 호출자에 남긴다면 깊이가 생기지 않는다. 호출자가 실패 시 무엇을 해야 하는지, 재요청해도 되는지까지 설명할 수 있어야 한다.

반대로 사용자 관리, 요금 계산과 알림 발송을 전부 하나의 거대한 모듈에 넣는 것도 답이 아니다. 서로 다르게 바뀌는 정책이 한곳에 얽히면 작은 변경을 검증하기 어려워진다. 모듈을 없앴을 때 복잡한 규칙이 여러 호출자로 흩어지는지, 아니면 불필요한 전달 계층만 사라지는지 살펴보겠다.

아직 실제로 필요하지 않은 확장 지점을 미리 만들 필요도 없다. ‘나중에 모든 결제사를 지원할 것’이라는 상상만으로 여러 추상 계층을 쌓으면 검토할 코드가 늘어난다. 현재 기능에서 무엇이 변하고 무엇이 고정되는지를 먼저 보겠다. 설계에 쓰는 시간을 줄이기 위해 추상화를 늘렸는데 읽는 시간이 더 늘어나는 일을 피하고 싶다.

사람의 검토를 인터페이스 설명만으로 끝내지 않는다

인터페이스를 합의하고 구현을 위임하더라도 보안과 데이터 변경의 책임은 남는다. 결과가 맞아 보여도 권한 확인을 우회하거나 실패 복구를 빠뜨릴 수 있다. 테스트의 관찰 지점은 공개 인터페이스로 정할 수 있지만, 필요한 코드 검토까지 내부를 보지 않는 방식으로 제한할 이유는 없다.

작은 기능 하나가 끝나면 처음의 질문으로 돌아간다. 다른 사용자 예약을 바꿀 수 없는가. 실패해도 원래 예약이 남는가. 결제는 범위 밖으로 남았는가. 수정한 파일마다 이 요구와 연결되는 이유를 설명해 본다. 관련 없는 정리는 다른 변경으로 미룰 수 있다.

스킬을 평가하는 기준도 이렇게 잡겠다. 질문 뒤에 결정이 남았는지, 용어가 테스트 이름과 코드에서 이어지는지, 같은 오류를 잡는 검사가 생겼는지 확인한다. 설치한 스킬 수나 대화 길이로는 이 결과를 알 수 없다. 절차가 과하면 줄이고, 반복해서 놓치는 문제가 있다면 해당 단계의 입력과 검사 기준을 보완한다.

이 예시에서 얻고 싶은 산출물은 예약 변경 기능의 결정 목록, 작은 용어집, 행동 테스트와 검토 기록이다. 이 네 가지가 서로 같은 요구를 설명하면 다음 에이전트도 현재 상태를 읽고 이어 갈 수 있다. 기본기를 작업에 적용한다는 말을 그 정도로 구체화하고 싶다.

참고자료

• Matt Pocock — Skills for Real Engineers: 전체 스킬의 목적과 현재 구성.
• domain-modeling: 용어 정의와 구체적 사례의 대조.
• tdd: 행동 중심 테스트와 작은 구현 단위.
• codebase-design: 모듈 인터페이스, 깊이와 변경의 집중도.