MCP 서버는 아니지만, 요즘 가장 유용하게 쓰고 있는 Claude Code 전용 스킬 세트도 하나
리뷰해본다. 블로그에 시리즈 모아보기 페이지(/series)를 만들면서 쓴 방식을 정리해둔다.
코드로 바로 들어가지 않고, 대화 → 스펙 문서 → 구현 플랜 → 태스크별 서브에이전트
구현/리뷰 → 전체 브랜치 리뷰 순서로 진행했다.
이 순서 자체가 처음부터 내가 짠 건 아니고, Claude Code에 설치해서 쓰는 스킬 세트 Superpowers를 켜두면 자동으로 이 흐름을 따라가게 된다. 뭘 만들겠다는 낌새만 보여도 바로 코드부터 쓰지 않고 “지금 진짜 하려는 게 뭐냐”부터 되묻고, 대화가 어느 정도 정리되면 스펙으로, 승인되면 플랜으로, 그다음부터는 태스크마다 서브에이전트를 띄워 구현시키는 식으로 순서를 강제한다. 아래는 실제로 그 흐름을 한 번 따라가 본 기록이다.
1. 코드 전에 대화로 요구사항부터
AstroPaper 테마엔 태그 시스템만 있고 시리즈 개념이 없다는 것부터 확인하고, 바로 구현에 들어가는 대신 질문을 주고받으며 요구사항을 좁혔다. 시리즈 소속을 frontmatter 필드로 할지 제목 파싱으로 판단할지, nav에 노출할지, 페이지 내 자동 이전/다음 편 네비게이션까지 포함할지 — 이런 것들을 하나씩 정하고 나서야 “어떻게 만들지”로 넘어갔다.
2. 스펙 문서로 정리하고 커밋
대화로 정해진 내용을 문서 하나로 정리했다 — 배경, 목표, 범위 밖(일부러 안 하기로 한
것), 데이터 모델, 페이지/컴포넌트 구조, 에러 처리 방침, 테스트 계획까지. 이 저장소엔
docs/superpowers/specs/에 이런 문서를 쌓아두는 관례가 이미 있어서 그대로 따랐다.
써놓고 바로 커밋해서, 대화가 끝나도 결정 내용이 남게 했다.
3. 구현 플랜 — 태스크마다 실행 가능한 코드까지
스펙을 승인받은 다음엔 그걸 태스크 단위로 쪼갰다. 각 태스크는 건드릴 파일, 앞뒤 태스크와 주고받는 인터페이스(함수 시그니처, 타입), 그리고 실제로 붙여 넣을 수 있는 완성된 코드까지 포함한다. “적절히 처리” 같은 자리표시자는 안 쓰는 게 원칙이다 — 나중에 이 플랜만 보고 작업할 사람(혹은 에이전트)이 판단할 게 없어야 한다.
4. 태스크마다 서브에이전트 구현 → 리뷰 → (필요하면) 수정 → 다음 태스크
여기서부터가 제일 손이 많이 가는 부분이다. 태스크마다:
- 그 태스크 부분만 잘라낸 브리프 파일을 만든다.
- 새 서브에이전트를 띄워서 브리프를 주고 구현시킨다. 서브에이전트는 구현 → 타입체크 → 커밋 → 자체 리뷰까지 하고 보고서를 남긴다.
- 그 태스크의 diff만 담은 별도 파일을 만들고, 또 다른 서브에이전트(리뷰어)에게 스펙 준수 여부와 코드 품질을 보게 한다.
- 리뷰에서 문제(Critical/Important)가 나오면 수정 서브에이전트를 붙이고, 다시 리뷰. 문제없으면 다음 태스크로.
서브에이전트마다 매번 새로 시작하기 때문에, 앞 태스크에서 오간 대화나 시행착오가 다음 서브에이전트한테 그대로 안 넘어간다 — 필요한 맥락만 브리프에 정확히 담아서 넘겨야 한다. 이번 작업에서는 태스크 난이도에 따라 모델도 다르게 썼다. 스키마 필드 하나 추가하는 것처럼 기계적인 작업은 가벼운 모델로, 여러 파일을 엮는 작업은 중간 모델로 맡겼다.
작업은 별도 git worktree에서 진행해서, 다 만들다가 문제가 생겨도 원래 브랜치(main)엔
전혀 영향이 없게 했다.
5. 전체 태스크가 끝나면 브랜치 전체를 한 번 더 리뷰
개별 태스크 리뷰는 그 태스크의 diff만 본다. 다 끝나면 이번엔 가장 강력한 모델로 브랜치 전체(스펙 문서 커밋 이후 전부)를 다시 훑는 리뷰를 한 번 더 돌린다. 태스크 단위로는 안 보이던 것 — 예를 들어 여러 태스크에 걸친 가정이 틀렸다거나, 스펙엔 있는데 어느 태스크 에서도 실제로 검증되지 않은 부분 같은 것 — 은 이 단계에서만 잡힌다. 실제로 이번에도 여기서 진짜 버그가 하나 나왔다(이건 별도 글로 정리했다).
6. 병합
리뷰까지 깨끗하면 로컬 병합/PR 생성/그대로 두기/폐기 중에 고른다. 이번엔 로컬 병합으로 갔다 — 워크트리를 정리하고 브랜치를 지우는 것까지 포함해서.
왜 이렇게까지 하나
작은 수정이면 이 단계를 다 밟을 필요는 없다. 근데 여러 파일이 엮이고, 기존 코드베이스 관례를 따라야 하고, 나중에 다시 손댈 가능성이 있는 기능이면 — 처음부터 대화로 요구사항을 좁히고, 그걸 문서로 남기고, 검증 단계를 여러 겹으로 두는 쪽이 결과적으로 왔다 갔다 하는 시간을 줄여줬다. 특히 마지막 전체 리뷰 단계는, 태스크별 검증을 아무리 꼼꼼히 해도 놓칠 수 있는 것들을 잡아내는 역할을 했다.
그리고 이 모든 단계를 매번 직접 챙길 필요가 없다는 게 제일 크다. Superpowers를 켜두면 “코드부터 짜지 말고 일단 물어봐라”, “승인 없이 넘어가지 마라”, “태스크마다 새 서브에이전트를 띄우고 리뷰를 거쳐라” 같은 규율을 내가 매번 기억해서 지시하지 않아도 에이전트가 알아서 따라간다. 비슷한 규모의 작업을 자주 맡긴다면, 한 번 설치해두고 직접 겪어보는 걸 추천한다.