mattpocock/skills

진짜 엔지니어를 위한 스킬

!skills.sh

제가 매일 사용하는 에이전트 스킬들입니다. 실제 엔지니어링을 위한 것이지, '바이브 코딩'을 위한 것이 아닙니다.

실제 애플리케이션을 개발하는 것은 어렵습니다. GSD, BMAD, Spec-Kit 같은 접근 방식은 프로세스를 소유함으로써 도움을 주려고 합니다. 하지만 그렇게 하는 동안 통제권을 빼앗고 프로세스의 버그를 해결하기 어렵게 만듭니다.

이 스킬들은 작고, 쉽게 적응할 수 있으며, 조합 가능하도록 설계되었습니다. 어떤 모델과도 작동합니다. 수십 년의 엔지니어링 경험을 바탕으로 합니다. 이것저것 실험해보고, 자신만의 것으로 만드세요. 즐기세요.

이 스킬들의 변경 사항과 제가 만드는 새로운 스킬을 계속 확인하고 싶다면, 제 뉴스레터에 가입하실 수 있습니다 (약 60,000명의 개발자 참여):

뉴스레터 가입하기

빠른 시작 (30초 설정)

1. skills.sh 설치 프로그램 실행:

npx skills@latest add mattpocock/skills

1. 원하는 스킬과 설치할 코딩 에이전트를 선택하세요. 반드시 /setup-matt-pocock-skills를 선택하세요.

1. 에이전트에서 /setup-matt-pocock-skills를 실행하세요. 다음을 수행합니다:

• 사용할 이슈 트래커를 묻습니다 (GitHub, Linear, 또는 로컬 파일)
• 티켓을 분류할 때 사용하는 레이블을 묻습니다 (/triage는 레이블을 사용합니다)
• 생성된 문서를 저장할 위치를 묻습니다

1. 준비 완료입니다.

이 스킬들이 존재하는 이유

저는 Claude Code, Codex 및 기타 코딩 에이전트에서 흔히 발생하는 실패 모드를 해결하기 위해 이 스킬들을 만들었습니다.

#1: 에이전트가 내가 원하는 대로 하지 않음

"아무도 자신이 정확히 무엇을 원하는지 알지 못한다"

David Thomas & Andrew Hunt, 실용주의 프로그래머

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

AI 시대에도 마찬가지입니다. 당신과 에이전트 사이에는 의사소통 격차가 있습니다. 이에 대한 해결책은 그릴링 세션입니다. 즉, 에이전트가 당신이 구축하려는 것에 대해 자세한 질문을 하도록 하는 것입니다.

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

• /grill-me - 코드가 아닌 용도
• /grill-with-docs - /grill-me와 동일하지만 추가 기능 포함 (아래 참조)

이것들은 가장 인기 있는 스킬입니다. 시작하기 전에 에이전트와 정렬하고, 변경 사항에 대해 깊이 생각하는 데 도움을 줍니다. 변경을 원할 때마다 매번 사용하세요.

#2: 에이전트가 너무 장황함

"보편적인 언어를 사용하면, 개발자 간의 대화와 코드 표현이 모두 동일한 도메인 모델에서 파생됩니다."

Eric Evans, 도메인 주도 설계

문제: 프로젝트 시작 시, 개발자와 소프트웨어를 구축하는 사람들(도메인 전문가)은 일반적으로 다른 언어를 사용합니다.

저도 에이전트와 같은 긴장감을 느꼈습니다. 에이전트는 일반적으로 프로젝트에 투입되어 진행하면서 전문 용어를 파악하도록 요청받습니다. 그래서 1단어로 충분할 때 20단어를 사용합니다.

해결책은 공유 언어입니다. 에이전트가 프로젝트에서 사용되는 전문 용어를 해독하는 데 도움이 되는 문서입니다.

<details> <summary> 예시 </summary>

다음은 제 course-video-manager 저장소의 CONTEXT.md 예시입니다. 어느 쪽이 더 읽기 쉬운가요?

• 전: "코스의 섹션 내에 있는 레슨이 '실제'가 될 때(즉, 파일 시스템에서 위치가 지정될 때) 문제가 있습니다."
• 후: "구체화 캐스케이드에 문제가 있습니다."

이 간결함은 세션이 거듭될수록 효과를 발휘합니다.

</details>

이 기능은 /grill-with-docs에 내장되어 있습니다. 그릴링 세션이지만, AI와 공유 언어를 구축하고 설명하기 어려운 결정을 ADR에 문서화하는 데 도움을 줍니다.

이것이 얼마나 강력한지 설명하기 어렵습니다. 이 저장소에서 가장 멋진 기술일 수도 있습니다. 시도해보세요.

[!TIP]

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

- 변수, 함수 및 파일이 공유 언어를 사용하여 일관되게 이름이 지정됩니다

- 결과적으로 에이전트가 코드베이스를 더 쉽게 탐색할 수 있습니다

- 에이전트는 또한 더 간결한 언어에 접근할 수 있기 때문에 사고에 더 적은 토큰을 사용합니다

#3: 코드가 작동하지 않음

"항상 작고 신중한 단계를 밟으세요. 피드백 속도가 속도 제한입니다. 너무 큰 작업을 맡지 마세요."

David Thomas & Andrew Hunt, 실용주의 프로그래머

문제: 당신과 에이전트가 무엇을 구축할지에 대해 합의했다고 가정해 봅시다. 에이전트가 여전히 형편없는 결과물을 내놓으면 어떻게 될까요?

피드백 루프를 살펴볼 때입니다. 에이전트가 생성한 코드가 실제로 어떻게 실행되는지에 대한 피드백이 없으면, 에이전트는 맹목적으로 작업하게 됩니다.

해결책: 일반적인 피드백 루프(정적 타입, 브라우저 접근, 자동화된 테스트)가 필요합니다.

자동화된 테스트의 경우, 레드-그린-리팩터 루프가 중요합니다. 에이전트가 먼저 실패하는 테스트를 작성한 다음 테스트를 수정하는 방식입니다. 이는 에이전트에게 일관된 수준의 피드백을 제공하여 훨씬 더 나은 코드를 만듭니다.

저는 모든 프로젝트에 적용할 수 있는 /tdd 스킬을 만들었습니다. 레드-그린-리팩터를 장려하고 좋은 테스트와 나쁜 테스트에 대한 많은 지침을 제공합니다.

디버깅을 위해, 최고의 디버깅 관행을 간단한 루프로 감싼 /diagnosing-bugs 스킬도 만들었습니다.

#4: 우리는 진흙 덩어리를 만들었습니다

"매일 시스템 설계에 투자하세요."

Kent Beck, 익스트림 프로그래밍 설명

"최고의 모듈은 깊습니다. 간단한 인터페이스를 통해 많은 기능에 접근할 수 있습니다."

John Ousterhout, 소프트웨어 설계의 철학

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

해결책은 AI 기반 개발에 대한 급진적인 새로운 접근 방식입니다: 코드 설계에 신경 쓰는 것입니다.

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

• /to-prd는 PRD를 생성하기 전에 어떤 모듈을 건드리는지 질문합니다.

그리고 결정적으로, /improve-codebase-architecture는 진흙 덩어리가 된 코드베이스를 구출하는 데 도움을 줍니다. 며칠에 한 번씩 코드베이스에서 실행하는 것을 권장합니다.

요약

소프트웨어 엔지니어링 기본기는 그 어느 때보다 중요합니다. 이 스킬들은 이러한 기본기를 반복 가능한 관행으로 압축하여, 당신의 경력 중 최고의 앱을 출시하는 데 도움을 주기 위한 최선의 노력입니다. 즐기세요.

참조

이 스킬들은 호출할 수 있는 주체에 따라 분류됩니다. 사용자 호출 스킬은 직접 입력해야만 접근할 수 있으며(예: /grill-me), 오케스트레이션 역할을 합니다. 모델 호출 스킬은 사용자가 호출하거나 작업에 적합할 때 에이전트가 자동으로 사용할 수 있으며, 재사용 가능한 규율을 담고 있습니다. 사용자 호출 스킬은 모델 호출 스킬을 호출할 수 있지만, 다른 사용자 호출 스킬은 호출할 수 없습니다.

엔지니어링

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

사용자 호출

• ask-matt — 상황에 맞는 스킬이나 흐름을 질문합니다. 이 저장소의 사용자 호출 스킬에 대한 라우터입니다.
• grill-with-docs — 프로젝트의 도메인 모델을 구축하고, 용어를 명확히 하며, CONTEXT.md와 ADR을 인라인으로 업데이트하는 그릴링 세션입니다.
• triage — 이슈를 분류 역할의 상태 머신을 통해 이동시킵니다.
• improve-codebase-architecture — 코드베이스에서 개선 기회를 스캔하고, 시각적 HTML 보고서로 제시한 후 선택한 항목에 대해 그릴링합니다.
• setup-matt-pocock-skills — 엔지니어링 스킬을 위해 이 저장소를 구성합니다 (이슈 트래커, 분류 레이블, 도메인 문서 레이아웃). 다른 엔지니어링 스킬을 사용하기 전에 저장소당 한 번 실행합니다.
• to-issues — 모든 계획, 명세 또는 PRD를 수직 슬라이스를 사용하여 독립적으로 가져갈 수 있는 이슈로 분할합니다.
• to-prd — 현재 대화를 PRD로 변환하여 이슈 트래커에 게시합니다. 인터뷰 없이 이미 논의한 내용을 종합합니다.
• prototype — 디자인을 구체화하기 위해 일회용 프로토타입을 구축합니다. 상태/비즈니스 로직 질문을 위한 실행 가능한 터미널 앱이거나, 하나의 라우트에서 전환 가능한 여러 radically 다른 UI 변형입니다.

모델 호출

• diagnosing-bugs — 어려운 버그 및 성능 회귀를 위한 체계적인 진단 루프: 재현 → 최소화 → 가설 → 계측 → 수정 → 회귀 테스트.
• tdd — 레드-그린-리팩터 루프를 사용한 테스트 주도 개발. 한 번에 하나의 수직 슬라이스로 기능을 구축하거나 버그를 수정합니다.
• domain-modeling — 프로젝트의 도메인 모델을 적극적으로 구축하고 개선합니다. 용어집에 대해 용어에 도전하고, 엣지 케이스 시나리오로 스트레스 테스트하며, CONTEXT.md와 ADR을 인라인으로 업데이트합니다.
• codebase-design — 깊은 모듈 설계를 위한 공유 규율 및 어휘: 작은 인터페이스 뒤에 많은 동작을 배치하고, 깔끔한 이음매에 배치하며, 해당 인터페이스를 통해 테스트 가능하게 합니다.

생산성

일반 워크플로 도구로, 코드에 특화되지 않았습니다.

사용자 호출

• grill-me — 결정 트리의 모든 분기가 해결될 때까지 계획이나 디자인에 대해 끊임없이 인터뷰를 받습니다.
• handoff — 현재 대화를 핸드오프 문서로 압축하여 다른 에이전트가 작업을 계속할 수 있도록 합니다.
• teach — 여러 세션에 걸쳐 사용자에게 새로운 스킬이나 개념을 가르치며, 현재 디렉토리를 상태 저장형 교육 작업 공간으로 사용합니다.
• writing-great-skills — 스킬을 잘 작성하고 편집하기 위한 참조: 스킬을 예측 가능하게 만드는 어휘와 원칙.

모델 호출

• grilling — 결정 트리의 모든 분기가 해결될 때까지 계획이나 디자인에 대해 사용자를 끊임없이 인터뷰합니다. grill-me와 grill-with-docs 뒤에 있는 재사용 가능한 루프입니다.

기타

거의 사용하지 않지만 보관해 두는 도구들입니다.

• git-guardrails-claude-code — Claude Code 훅을 설정하여 위험한 git 명령어(push, reset --hard, clean 등)가 실행되기 전에 차단합니다.
• **[migrate-to-shoehorn](