Post

Repo Deep Dive: mattpocock/skills로 요구사항부터 코드 검토까지 협업하기

2026-07-26 08:07 · github-repo-analysis

AI 에이전트에게 기능을 만들어 달라고 했는데, 결과물을 보고서야 서로 다른 기능을 생각했다는 사실을 깨닫는 경우가 있다. 요구사항을 길게 쓰는 것만으로는 해결하기 어렵다. 어떤 결정을 먼저 확인할지, 구현 중 무엇을 테스트할지, 마지막에 어떤 기준으로 검토할지가 빠져 있기 때문이다.

mattpocock/skills는 이 협업 과정을 잘게 나눈 에이전트용 스킬 모음이다. Matt Pocock이 사용하는 질문, 설계, 구현, 진단, 검토 절차를 SKILL.md에 담았다. 사용자는 현재 문제에 맞는 스킬을 호출하고, 에이전트는 그 문서에 적힌 순서와 기준을 따른다. 이미 사용하는 코딩 에이전트에 작업 방식을 더하는 도구라고 보면 된다.

이 글은 2026년 10월 16일 재검토 기준으로 공식 저장소의 커밋 49dd158을 확인했다. 해당 플러그인 명세는 버전 1.3.1과 27개 스킬을 선언한다. 저장소의 실험용 스킬까지 모두 같은 배포 범위로 보지 않고, 공식 배포 목록과 개별 문서가 안내하는 흐름을 살펴본다.

시작할 때는 설치 방식과 저장 위치를 정한다

공식 README는 플러그인 설치와 편집 가능한 파일 설치를 구분한다. 플러그인은 에이전트의 관리 방식에 따라 갱신하고, skills.sh 방식은 복사한 스킬을 직접 수정할 수 있다. 같은 에이전트에 두 방식을 함께 적용하면 중복되므로 하나를 고르도록 안내한다. 여러 에이전트를 지원하더라도 호출과 업데이트 방법은 도구에 맞춰 확인해야 한다.

편집 가능한 파일이 필요한 사용자를 위해 README가 제시하는 명령은 다음과 같다. 공식 설치 예시이며, 이번 글 작성 중 실행하지는 않았다.

npx skills@latest add mattpocock/skills -a <agent>

<agent>에는 대상 에이전트를 넣고, 옵션을 생략하면 설치 과정에서 선택한다. 갱신 방법과 에이전트별 플러그인 명령은 공식 설치 안내를 따른다.

엔지니어링 흐름을 시작하기 전에는 /setup-matt-pocock-skills를 저장소마다 한 번 실행하도록 문서가 요구한다. 이때 정하는 것은 이슈를 GitHub, GitLab, 로컬 Markdown 중 어디에 기록할지, 분류 라벨은 무엇인지, 용어집과 설계 결정 문서를 어디에 둘지다. 다른 이슈 관리 도구도 사용자가 설명한 절차를 문서로 기록하는 방식으로 다룬다.

setup 스킬은 기존 저장소를 조사하고 설정 초안을 보여 준 다음 확인을 거쳐 기록하는 대화형 절차다. 기본 구성은 GLOSSARY.md와 docs/adr/를 사용한다. 모노레포 징후가 있을 때 문맥을 나누는 방식을 제안한다. 모든 스킬에 필요한 별도 실행 환경이라기보다, 이슈와 문서를 다루는 엔지니어링 스킬들이 공유할 저장소별 약속이다.

만들 것이 흐릿하면 질문하는 스킬부터 고른다

가령 “주문 취소 기능을 만들어 달라”는 요청에는 아직 결정하지 않은 부분이 많다. 주문 전체를 취소하는지 일부 상품만 취소하는지, 배송 준비 이후에도 가능한지, 취소와 환불을 같은 상태로 볼지에 따라 구현이 달라진다. 이 상황은 사용법을 설명하기 위해 구성한 예시다.

작업 디렉터리가 있는 개발 대화라면 /grill-with-docs가 출발점이다. 질문 절차인 grilling과 도메인 모델을 다듬는 domain-modeling을 함께 사용한다. 선행 결정이 해결되어 지금 답할 수 있는 질문끼리 묶고, 각 질문에 권장 답을 덧붙인다. 답변에 따라 다음 질문을 구성하므로, 아직 정하지 않은 정책을 에이전트가 조용히 가정하고 구현하는 일을 줄이려는 절차다.

개발자가 답할 것은 사업 정책과 선택이다. 저장소에서 확인할 수 있는 사실은 에이전트가 조사한다. 코드가 주문 전체 취소만 지원하는데 사용자가 부분 취소를 말한다면 그 차이를 드러내야 한다. 질문 절차와 도메인 모델링 문서에 이 역할 분담이 명시되어 있다.

합의한 개념은 용어집에 남긴다. 용어집은 구현 계획을 모아 두는 노트가 아니라 “취소”와 “환불”처럼 뜻을 맞춰야 할 말을 정의하는 문서다. 되돌리기 어렵고, 배경 없이 보면 의아하며, 실제 대안을 비교해 내린 결정은 ADR로 남긴다. 모든 대화에 ADR을 만들지는 않는다. 현재 규약은 GLOSSARY.md다. README의 CONTEXT.md 링크는 이전 이름을 사용하던 과거 예제다.

작업 디렉터리 없이 기획이나 글쓰기의 생각을 점검하려면 /grill-me를 고를 수 있다. 같은 질문 절차를 사용하지만 로컬 용어집과 ADR을 만드는 역할은 없다. 스킬 선택부터 막히면 /ask-matt에 현재 상황을 설명한다. 공식 흐름 안내는 작은 기능, 여러 세션이 필요한 작업, 어려운 버그를 서로 다른 진입점으로 구분한다.

합의한 대화를 구현 가능한 일로 바꾼다

한 세션에서 끝날 정도로 정리되었다면 같은 대화에서 /implement로 넘어갈 수 있다. 여러 세션이 필요한 기능은 합의 내용을 남기는 단계가 필요하다. /to-spec은 대화를 문제, 해결 방향, 사용자 이야기, 구현 결정, 테스트 결정, 범위 밖 항목으로 정리하고 설정한 이슈 관리 위치에 게시한다.

to-spec 문서는 요구사항 인터뷰를 다시 시작하지 말고 기존 대화를 종합하라고 지시한다. 다만 테스트할 공개 경계는 사용자와 확인한다. 주문 취소 API의 결과를 관찰할지, 더 높은 수준의 사용자 흐름을 검사할지 합의해야 중요한 동작을 테스트로 붙잡을 수 있기 때문이다.

이후 /to-tickets는 명세를 독립적으로 확인할 수 있는 작은 작업으로 나눈다. 데이터베이스, API, 화면을 각각 따로 떼기보다 좁은 기능 하나가 필요한 계층을 끝까지 통과하도록 나눈다. 예를 들어 “배송 준비 전 주문을 취소하고 상태를 조회할 수 있다”가 한 작업이 될 수 있다. 다음 정책을 붙이기 전에 이 동작을 확인한다.

작업마다 먼저 끝나야 할 작업을 표시한다. 로컬 파일을 택했다면 작업마다 Markdown 파일을 하나씩 만들고, 실제 이슈 관리 도구라면 지원하는 차단 관계나 본문 참조로 의존성을 남긴다. 초안을 보여 주고 크기와 관계를 확인받은 뒤 게시한다. 광범위한 이름 변경처럼 중간 상태가 깨지는 작업은 기존 형태와 새 형태를 공존시킨 뒤 옮기는 예외도 있다. 작업 분할 기준을 읽으면 단순 할 일 목록과 다른 점이 드러난다.

구현에서는 테스트 하나가 다음 행동을 정한다

/implement는 전달받은 명세나 작업을 구현하면서 합의한 경계에서 /tdd를 사용하고, 타입 검사와 개별 테스트를 자주 실행하도록 한다. 마지막에는 전체 테스트와 코드 검토를 거친다. 현재 문서에는 현재 브랜치에 커밋하는 단계도 있으므로 조언만 받는 호출로 생각해서는 안 된다. implement 원문을 읽고 작업 범위와 브랜치를 맞춰 사용한다.

현재 /tdd의 핵심은 한 경계에서 실패하는 테스트 하나를 쓰고, 통과에 필요한 최소 구현을 한 뒤 다음 동작으로 넘어가는 것이다. 모든 테스트를 먼저 작성하고 구현을 몰아서 진행하는 방법을 피한다. 리팩터링도 이 반복 안에 넣지 않고 검토 단계로 넘기도록 명시한다. 테스트 수보다 어떤 행동을 관찰하는지에 무게를 둔다.

공식 테스트 예제는 장바구니를 결제한 결과가 확정 상태인지 확인하는 테스트를 좋은 예로 든다. 내부 결제 서비스가 호출되었는지만 검사하면 사용자가 원하는 결과보다 구현 구조에 테스트가 묶인다. 다른 예제에서는 사용자를 만든 뒤 SQL로 행을 찾아보는 대신 공개 조회 기능으로 다시 얻을 수 있는지 확인한다. 내부 구조가 바뀌어도 유지할 수 있는 관찰 지점을 고르라는 뜻이다.

테스트할 경계는 작성 전에 사용자와 합의한다. 기대값도 구현과 같은 계산식을 복사해 만들면 안 된다. 이미 알고 있는 결과나 명세에서 가져와야 코드가 잘못되었을 때 테스트가 반대 결과를 낼 수 있다. 이 기준은 tdd 스킬에 구체적으로 적혀 있다.

여러 작업을 사람이 하나씩 진행할 때는 /implement를 사용한다. 전체 명세를 맡기는 /implement-spec은 선행 작업이 끝난 항목을 찾아 하위 에이전트와 개별 worktree로 구현하고 하나의 통합 브랜치에 합치는 방식이다. 병렬 실행 환경과 이슈 관리 연결을 사용하는 경로이므로 단일 기능을 구현하는 호출과 운영 범위가 다르다.

이미 고장 난 기능은 재현 명령부터 만든다

원인을 모르는 어려운 오류에는 /diagnosing-bugs가 맞는다. 그럴듯한 원인을 나열하기 전에 보고된 증상에서 실패하는 반복 가능한 검증 수단을 만들라고 요구한다. 테스트, HTTP 요청, CLI 입력, 브라우저 자동화, 기록한 요청 재생 중 문제를 잡아낼 방법을 고른다.

명령이 성공적으로 끝나는지보다 사용자가 보고한 잘못된 결과를 판별하는지가 중요하다. 주문이 두 번 취소되는 문제라면 서버 기동 확인으로는 부족하다. 같은 취소 요청을 보낸 결과와 관찰 가능한 상태를 검사해야 한다. 성능 문제라면 먼저 측정 기준을 만든다.

실패를 확인한 뒤 입력과 조건을 줄이고, 반증 가능한 가설을 세워 하나씩 조사한다. 수정 후에는 회귀 테스트와 함께 처음 문제가 나타난 시나리오도 다시 실행한다. 재현 수단을 만들 수 없다면 시도한 내용과 필요한 환경이나 자료를 밝혀야 한다. 진단 문서는 이 단계들을 통과 기준과 함께 제시한다. 스킬을 호출했다는 사실만으로 수정이 검증되는 것은 아니다.

마지막 검토에서는 요구사항과 코드 기준을 따로 본다

/code-review는 비교 기준 커밋이나 브랜치를 고정한 뒤 변경분을 두 방향으로 검토한다. Standards는 저장소의 작성 규칙과 설계상 의심 지점을 살피고, Spec은 요구한 기능이 빠지거나 잘못 구현되었는지, 요청하지 않은 동작을 추가했는지 확인한다. 두 검토를 병렬 하위 에이전트로 수행하고 결과도 구분해 제시한다.

스타일과 구조가 훌륭해도 부분 취소 요청을 전체 취소로 구현했다면 요구사항 검토에서 실패해야 한다. 기능이 맞더라도 저장소 규약을 깨뜨렸을 수 있다. 명세를 찾지 못하면 Spec 검토를 생략했다고 보고하며, 코드 냄새는 무조건적인 위반이 아닌 판단이 필요한 후보로 다룬다. code-review 문서가 검토 범위를 설명한다.

작업 후 /retro는 코드 자체보다 에이전트의 작업 환경을 돌아본다. 찾기 어려웠던 파일에 탐색 경로가 필요한지, 반복 실수를 린트나 CI로 잡을 수 있는지, 규칙 문서가 지나치게 커졌는지를 검토해 개선 후보를 제시한다.

어떤 기대를 가지고 도입할 것인가

요구사항 합의와 테스트 피드백이 부족한 개발자에게 읽어 볼 만한 저장소다. 현재 막힌 지점을 먼저 정하면 선택이 쉬워진다. 무엇을 만들지 불명확하면 질문하고, 합의가 끝났으면 명세와 작업으로 남기고, 동작 하나를 검증하려면 TDD를 쓰고, 어려운 오류라면 재현 수단부터 만든다.

Markdown 지침이 실행 환경을 대신하지는 않는다. 테스트 명령이 있어야 하고, 이슈 게시에는 도구 접근이 필요하며, 병렬 검토에는 하위 에이전트 기능이 필요하다. 이번 검토는 문서와 배포 명세를 읽은 결과다. 설치, 기능 실행, 이슈 생성, 병렬 구현을 직접 시험하지는 않았다.