mattpocock/skills

단순한 '바이브 코딩 (vibe coding)'이 아닌, 실제 엔지니어링을 수행하기 위해 제가 매일 사용하는 에이전트 기술들입니다.

실제 애플리케이션을 개발하는 것은 어렵습니다. GSD, BMAD, Spec-Kit과 같은 접근 방식들은 프로세스를 직접 소유함으로써 이를 도우려 노력합니다. 하지만 그 과정에서 사용자의 제어권을 앗아가며, 프로세스 중에 발생하는 버그를 해결하기 어렵게 만듭니다.

이 기술들은 작고, 적응하기 쉬우며, 조합 가능하도록 설계되었습니다. 어떤 모델과도 함께 작동합니다. 수십 년간의 엔지니어링 경험을 바탕으로 만들어졌습니다. 마음껏 실험해 보세요. 당신만의 것으로 만드세요. 즐기시기 바랍니다.

• skills.sh 설치 프로그램을 실행하세요:

npx skills@latest add mattpocock/skills

원하는 기술과 이를 설치할 코딩 에이전트를 선택하세요.

반드시 다음을 선택하세요 ./setup-matt-pocock-skills.

에이전트에서 다음을 실행하세요:

/setup-matt-pocock-skills

실행 시 다음을 수행합니다:

• 사용할 이슈 트래커(Issue Tracker)를 묻습니다 (GitHub, Linear, 또는 로컬 파일).

• 티켓을 분류(triage)할 때 어떤 라벨(label)을 적용할지 묻습니다 (/triage는 라벨을 사용합니다).

• 생성된 문서를 어디에 저장할지 묻습니다.

짠 - 이제 준비가 되었습니다.

저는 Claude Code, Codex 및 기타 코딩 에이전트에서 발생하는 일반적인 실패 모드(failure modes)를 해결하기 위한 방법으로 이 기술들을 만들었습니다.

"아무도 자신이 정확히 무엇을 원하는지 모른다"

David Thomas & Andrew Hunt, The Pragmatic Programmer

문제점. 소프트웨어 개발에서 가장 흔한 실패 모드는 불일치(misalignment)입니다. 당신은 개발자가 당신이 원하는 것을 알고 있다고 생각합니다. 그러다 그들이 만든 것을 보고 나서야, 그들이 당신을 전혀 이해하지 못했다는 사실을 깨닫게 됩니다.

AI 시대에도 마찬가지입니다. 당신과 에이전트 사이에는 커뮤니케이션 격차가 존재합니다. 이를 해결하는 방법은 그릴링 세션 (grilling session), 즉 에이전트가 당신이 무엇을 만들고 있는지에 대해 상세한 질문을 던지도록 만드는 것입니다.

해결책은 다음을 사용하는 것입니다:

/grill-me

• 코드 이외의 용도

/grill-with-docs

• /grill-me와 동일하지만, 더 많은 유용한 기능이 추가됨 (아래 참조)

이것들은 저의 가장 인기 있는 기술들입니다. 이 기술들은 작업을 시작하기 전에 에이전트와 방향을 맞추고(align), 당신이 만들려는 변경 사항에 대해 깊이 생각할 수 있도록 도와줍니다. 변경을 하고 싶을 때마다 매번 사용하세요.

보편적 언어 (ubiquitous language)가 있다면, 개발자 간의 대화와 코드의 표현은 모두 동일한 도메인 모델 (domain model)에서 파생됩니다.

— Eric Evans, Domain-Driven-Design

문제점 (The Problem): 프로젝트 시작 단계에서 개발자들과 그들이 소프트웨어를 구축해 주는 대상(도메인 전문가, domain experts)은 보통 서로 다른 언어를 사용합니다.

저는 제 에이전트 (agents)들에게서도 동일한 긴장감을 느꼈습니다. 에이전트들은 보통 프로젝트에 투입된 후, 진행하면서 전문 용어 (jargon)를 파악하라는 요청을 받습니다. 그래서 단어 하나면 충분할 상황에서 20개의 단어를 사용하곤 합니다.

이에 대한 **해결책 (The Fix)**은 공유된 언어 (shared language)입니다. 이는 에이전트가 프로젝트에서 사용되는 전문 용어를 해독하는 데 도움을 주는 문서입니다.

예시 (Example)

제 course-video-manager 리포지토리 (repo)에 있는 CONTEXT.md 예시입니다. 어떤 것이 더 읽기 쉬운가요?

이전 (BEFORE): "강좌의 섹션 내에 있는 레슨이 '실체화'될 때 (즉, 파일 시스템 내에 위치가 지정될 때) 문제가 발생합니다."
이후 (AFTER): "실체화 폭포 (materialization cascade)에 문제가 있습니다."

이러한 간결함은 세션이 거듭될수록 보상을 가져다줍니다.

이 기능은 /grill-with-docs에 내장되어 있습니다. 일종의 '그릴링 (grilling)' 세션이지만, 이는 AI와 공유된 언어를 구축하고, 설명하기 어려운 결정 사항들을 ADR (Architecture Decision Records)에 문서화하는 데 도움을 줍니다.

이것이 얼마나 강력한지 설명하기란 어렵습니다. 이 리포지토리에서 아마도 가장 멋진 단일 기술일 것입니다. 직접 시도해 보고 확인해 보세요.

팁 (Tip)

공유된 언어는 장황함을 줄이는 것 외에도 많은 이점이 있습니다:

• 변수, 함수, 파일이 공유된 언어를 사용하여 일관되게 명명됩니다.
• 결과적으로 에이전트가 코드베이스 (codebase)를 탐색하기가 더 쉬워집니다.
• 에이전트가 더 간결한 언어에 접근할 수 있으므로, 생각하는 데 사용하는 토큰 (tokens)이 줄어듭니다.

"항상 작고 의도적인 단계를 밟으세요. 피드백의 속도가 당신의 속도 제한입니다. 절대 너무 큰 작업은 맡지 마세요."

— David Thomas & Andrew Hunt, The Pragmatic Programmer

문제점 (The Problem): 당신과 에이전트가 무엇을 만들지에 대해 정렬(align)되었다고 가정해 봅시다. 그런데도 에이전트가 여전히 형편없는 결과물을 만들어낸다면 어떻게 될까요?

이제 여러분의 피드백 루프 (feedback loops)를 살펴볼 때입니다. 생성된 코드가 실제로 어떻게 실행되는지에 대한 피드백이 없다면, 에이전트는 눈을 가린 채 비행하는 것과 같습니다.

해결책 (The Fix): 정적 타입 (static types), 브라우저 접근 (browser access), 그리고 자동화된 테스트 (automated tests)와 같은 일반적인 피드백 루프 세트가 필요합니다.

자동화된 테스트의 경우, 레드-그린-리팩터 (red-green-refactor) 루프가 매우 중요합니다. 이는 에이전트가 먼저 실패하는 테스트를 작성한 다음, 그 테스트를 통과하도록 수정하는 방식입니다. 이는 에이전트에게 일관된 수준의 피드백을 제공하여 훨씬 더 나은 코드를 결과물로 만들어내는 데 도움을 줍니다.

저는 어떤 프로젝트에도 끼워 넣을 수 있는 ** /tdd skill**을 만들었습니다. 이 스킬은 레드-그린-리팩터 방식을 권장하며, 무엇이 좋은 테스트이고 나쁜 테스트인지에 대해 에이전트에게 충분한 가이드를 제공합니다.

디버깅 (debugging)을 위해, 저는 또한 최선의 디버깅 관행을 단순한 루프로 감싼 ** /diagnose** 스킬도 만들었습니다.

"매일 시스템의 설계에 투자하십시오."
— Kent Beck, Extreme Programming Explained

"최고의 모듈은 깊습니다. 그들은 단순한 인터페이스를 통해 많은 기능을 사용할 수 있게 해줍니다."
— John Ousterhout, A Philosophy Of Software Design

문제점 (The Problem): 에이전트로 구축된 대부분의 앱은 복잡하며 변경하기 어렵습니다. 에이전트는 코딩 속도를 획기적으로 높일 수 있기 때문에, 소프트웨어 엔트로피 (software entropy) 또한 가속화합니다. 코드베이스 (codebases)가 전례 없는 속도로 더 복잡해집니다.

이에 대한 **해결책 (The Fix)**은 AI 기반 개발에 대한 근본적으로 새로운 접근 방식, 즉 코드의 설계 (design)를 신경 쓰는 것입니다.

이것은 이 스킬들의 모든 계층에 내장되어 있습니다:

/to-prd

PRD (제품 요구 사항 문서)를 생성하기 전에 어떤 모듈을 수정하고 있는지 퀴즈를 통해 확인합니다.

/zoom-out

에이전트에게 전체 시스템의 맥락 (context) 안에서 코드를 설명하도록 지시합니다.

그리고 결정적으로, /improve-codebase-architecture

진흙탕 (ball of mud)처럼 변해버린 코드베이스를 구조화하는 데 도움을 줍니다. 저는 며칠에 한 번씩 여러분의 코드베이스에 이 명령을 실행하는 것을 권장합니다.

소프트웨어 엔지니어링의 기본 원칙 (fundamentals)은 그 어느 때보다 중요합니다. 이 스킬들은 이러한 기본 원칙들을 반복 가능한 관행으로 응축하여, 여러분이 커리어에서 최고의 앱을 출시할 수 있도록 돕기 위한 저의 최선의 노력입니다. 즐겁게 사용해 보세요.

코드 작업을 위해 제가 매일 사용하는 스킬들입니다.

diagnose— 까다로운 버그와 성능 퇴보 (performance regressions)를 해결하기 위한 규율 있는 진단 루프: 재현 (reproduce) → 최소화 (minimise) → 가설 설정 (hypothesise) → 계측 (instrument) → 수정 (fix) → 회귀 테스트 (regression-test).

grill-with-docs— 기존 도메인 모델에 비추어 계획을 검증하고, 용어를 정교화하며, CONTEXT.md 및 ADR (Architecture Decision Records)을 인라인으로 업데이트하는 심층 검증 (grilling) 세션.

triage— 분류 (triage) 역할의 상태 머신 (state machine)을 통해 이슈를 분류.

improve-codebase-architecture— CONTEXT.md의 도메인 언어와 docs/adr/의 결정 사항을 바탕으로 코드베이스 내에서 심화 발전시킬 기회를 탐색.

setup-matt-pocock-skills— 다른 엔지니어링 스킬들이 사용하는 저장소별 설정 (이슈 트래커, 분류 라벨 어휘, 도메인 문서 레이아웃)을 스캐폴딩 (scaffold). to-issues, to-prd, triage, diagnose, tdd, improve-codebase-architecture, 또는 zoom-out을 사용하기 전 저장소당 한 번 실행.

tdd— Red-Green-Refactor 루프를 사용하는 테스트 주도 개발 (Test-driven development). 수직적 슬라이스 (vertical slice) 단위로 기능을 구축하거나 버그를 수정.

to-issues— 모든 계획, 사양(spec), 또는 PRD (Product Requirements Document)를 수직적 슬라이스 방식을 사용하여 독립적으로 가져갈 수 있는 GitHub 이슈로 분할.

to-prd— 현재 대화 문맥을 PRD로 변환하여 GitHub 이슈로 제출. 별도의 인터뷰 없이 이미 논의된 내용을 합성.

zoom-out— 에이전트에게 줌아웃(zoom out)하여 생소한 코드 섹션에 대해 더 넓은 문맥이나 상위 수준의 관점을 제공하도록 지시.

prototype— 설계를 구체화하기 위한 일회성 프로토타입 구축 — 상태/비즈니스 로직 질문을 위한 실행 가능한 터미널 앱이거나, 하나의 경로에서 전환 가능한 여러 가지 근본적으로 다른 UI 변형 중 하나를 생성.

코드에 특화된 것이 아닌, 일반적인 워크플로우 도구들입니다.

caveman— 초압축 통신 모드. 불필요한 수식어를 제거하여 기술적 정확도는 완벽하게 유지하면서 토큰 사용량을 약 75% 절감합니다.

grill-me— 계획이나 설계에 대해 의사결정 트리의 모든 가지가 해결될 때까지 끊임없이 인터뷰를 받습니다.

handoff— 현재 대화를 인수인계 (handoff) 문서로 압축하여 다른 에이전트 (agent)가 작업을 계속할 수 있도록 합니다.

write-a-skill— 적절한 구조, 점진적 공개 (progressive disclosure), 그리고 번들링된 리소스 (bundled resources)를 갖춘 새로운 스킬 (skill)을 생성합니다.

곁에 두지만 거의 사용하지 않는 도구들입니다.

git-guardrails-claude-code— 위험한 git 명령 (push, reset --hard, clean 등)이 실행되기 전에 이를 차단하도록 Claude Code 훅 (hooks)을 설정합니다.

migrate-to-shoehorn— 테스트 파일들을 as 타입 단언 (type assertions)에서 @total-typescript/shoehorn으로 마이그레이션 (migrate) 합니다.

scaffold-exercises— 섹션, 문제, 솔루션, 그리고 설명서가 포함된 연습 문제 디렉토리 구조를 생성합니다.

setup-pre-commit— lint-staged, Prettier, 타입 체크 (type checking), 그리고 테스트가 포함된 Husky pre-commit 훅 (hooks)을 설정합니다.