전체 내역

[Claude Code 스킬] brainstorming, 코드부터 짜지 않게 붙잡아 주는 법

만들 것이 흐릿한 채로 구현을 시작하면 중간에 갈아엎게 됩니다. 구현 전에 무엇을 묻고 어디서 멈추는 스킬인지, 요청 크기에 따라 세 가지 경로로 나뉘는 규칙을 설치된 스킬 원문을 읽으며 풀어 봤습니다.

"블로그에 도구 소개 섹션을 넣고 싶다" 같은 요청을 받으면 바로 코드를 짜고 싶어집니다. 에이전트도 마찬가지입니다. 요청이 한 줄이면 빠진 것을 스스로 채워 넣고 구현부터 시작하는 일이 흔합니다. 그런데 이런 요청에는 중요한 결정이 빠져 있는 경우가 많습니다. 목록 페이지로 할지, 기존 글 분류를 재활용할지, 글은 몇 편으로 시작할지 같은 것들입니다. 에이전트가 이 빈칸을 혼자 채우면 결과물이 나온 뒤에야 "그게 아닌데"가 됩니다.

이 글에서는 이런 빈칸을 구현 전에 채우게 하는 brainstorming 스킬을 다룹니다. 설치된 스킬 원문을 읽으면서, 무엇을 묻고 어디서 멈추는지, 요청의 크기에 따라 과정이 어떻게 달라지는지를 정리했습니다. Claude Code에서 스킬을 써 본 적이 있고, 기능을 만들 때 에이전트가 너무 일찍 코드를 쓰는 것이 불편했던 분을 염두에 두었습니다.

1. 어떤 스킬인가

Claude Code용 superpowers 플러그인에 들어 있는 스킬입니다. 기능을 만들거나 동작을 바꾸는 작업 전에 사용자의 의도와 요구사항, 설계를 먼저 탐색하고, 그다음에 구현으로 넘어가게 합니다. 스킬 파일의 설명(description)이 그 목적을 한 줄로 말해 줍니다.

name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."

"창작 작업 전에는 반드시 쓴다"고 되어 있어서, 기능 추가나 컴포넌트 제작, 동작 변경처럼 새로 만들거나 바꾸는 일이면 이 스킬을 먼저 거치도록 설계되어 있습니다. superpowers 플러그인은 세션이 시작될 때 이 규칙을 안내하는 내용을 불러 오기 때문에, 설치해 두면 에이전트가 스스로 이 스킬을 꺼내 드는 일이 많습니다.

승인 전에는 구현하지 않는다는 규칙

스킬 원문에는 하드 게이트(HARD-GATE)라는 표시가 붙은 대목이 있습니다. 사용자에게 하려는 일을 말하고 승인을 받기 전에는 어떤 구현 스킬도 부르지 않고, 코드를 쓰지 않고, 프로젝트를 만들지 않는다는 내용입니다. 모든 경로의 모든 작업에 적용되고, 작업이 작으면 설계 설명이 짧아질 뿐 승인 단계는 줄어들지 않습니다. 원문의 표현을 빌리면 의식(ceremony)의 크기는 작업에 따라 달라져도 승인 관문은 그렇지 않습니다.

2. 출처

항목 내용
AI 도구 Claude Code
종류 스킬 (superpowers 플러그인에 포함)
만든 사람 Jesse Vincent
저장소 https://github.com/obra/superpowers
설치 경로 obra/superpowers-marketplace 마켓플레이스
확인한 버전 6.3.0 (2026년 10월 7일 설치본 기준)
라이선스 MIT

3. 언제 쓰면 좋은가

요청이 한 줄인데 결정할 것이 여러 개일 때, 화면이나 데이터 구조가 바뀌어서 되돌리기 번거로울 때 씁니다. 오타 수정 같은 한 줄짜리 변경에도 규칙상으로는 짧은 설명과 승인이 필요하다고 되어 있지만, 실제로 의미가 큰 것은 앞의 두 경우입니다. 스킬은 이 판단을 사용자에게 맡기지 않고 요청을 세 가지로 분류해서 알아서 무게를 조절합니다. 다음 절에서 그 분류를 풀어 봅니다.

4. 사용법

만들고 싶은 것을 평소처럼 말하면 됩니다. 스킬이 켜지면 에이전트는 첫 질문을 하기 전에 요청을 분류하고, 그 분류를 소리 내어 말합니다. 원문이 예로 드는 문장은 "이 요청은 범위가 정해져 있어 보이니, 명세 문서를 쓰는 대신 짧은 설계를 여기서 보여 드리겠습니다"와 같은 식입니다. 분류를 말로 밝히는 이유는 사용자가 "아니, 그건 더 큰 일이다"라고 바로잡을 수 있게 하려는 것입니다.

세 가지 경로

요청은 세 갈래로 나뉩니다.

  • 탐색(spike): "이게 가능한가", "대충 돼도 된다"처럼 답이 목적인 질문입니다. 하려는 일을 두세 문장으로 말하고 승인을 받은 뒤, 정확성이 허락하는 한 가장 싸게 알아봅니다. 설계 문서나 명세 파일은 만들지 않고, 만든 코드는 버릴 것이라고 표시합니다.
  • 범위가 정해진 변경(bounded): 이미 저장소에 있는 흐름을 고치는 일입니다. 새 플래그, 작은 엔드포인트, 파일 하나의 수정 같은 것입니다. 원문은 앱의 종류를 안다고 해서 범위가 정해진 것이 아니라, 바꿀 흐름이 저장소에 이미 있어 읽을 수 있어야 한다고 못 박습니다. 중요한 질문만 하고, 설계를 채팅으로 짧게 보여 준 뒤 멈춥니다. 사용자가 승인해야 구현이 시작되고, 계획 문서는 만들지 않습니다.
  • 구조에 관한 변경(architectural): 새 프로젝트, 새 하위 시스템, 여러 부분이 맞물리는 방식이나 다른 코드가 의존하는 인터페이스를 바꾸는 일입니다. 질문, 접근 방법 비교, 구역별 설계, 문서 작성까지 전체 과정을 밟습니다.

두 경로 사이에서 망설여지면 더 무거운 쪽을 고르게 되어 있습니다. 일하다가 숨은 복잡도를 발견하면 경로를 위로 올리고, 반대로 내리는 일은 없습니다. 이 한 방향 규칙 덕분에 "작은 일이라고 판단해서 건너뛰었다가 커진" 상황이 줄어듭니다.

구조에 관한 변경의 단계

가장 긴 경로의 점검 목록은 아홉 단계입니다. 프로젝트 맥락을 살피고(파일, 문서, 최근 커밋), 필요한 순간에만 시각 자료를 보여 줄지 묻고, 질문을 한 번에 하나씩 하고, 두세 가지 접근을 장단점과 함께 제안하고, 설계를 구역별로 보여 주며 승인받고, 설계 문서를 쓰고, 문서를 스스로 점검하고, 사용자가 문서를 검토하고, 마지막으로 계획 작성 스킬(writing-plans)로 넘어갑니다. 설계 문서는 정해진 위치와 이름으로 저장하고 커밋합니다.

docs/superpowers/specs/YYYY-MM-DD-<주제>-design.md

원문은 이 경로의 끝에서 부를 수 있는 스킬을 계획 작성 스킬 하나로 제한합니다. 디자인이나 구현 스킬로 곧바로 건너뛰지 못하게 해서 설계와 구현 사이에 계획이라는 단계를 반드시 두는 것입니다. 질문은 한 번에 하나씩, 선택지가 있으면 추천과 함께 묻도록 되어 있어서 사용자는 긴 질문지를 한꺼번에 받지 않습니다.

스스로를 합리화하지 못하게 막는 표

스킬에는 "빨간 깃발" 표도 들어 있습니다. 에이전트가 승인을 건너뛰려고 만들 법한 생각과 그 생각이 틀린 이유를 나란히 적은 표입니다. "이건 너무 간단해서 설계가 필요 없다", "범위가 정해진 일이라고 부르고 명세는 건너뛰자", "설계가 뻔하니 읽는 동안 먼저 시작하자" 같은 문장이 실려 있습니다. 각각에 대한 답은 같은 방향입니다. 간단하면 설계가 짧아질 뿐 없어지지 않고, 관문은 설계의 길이가 아니라 승인에 있습니다. 가장 간단해 보이는 작업에서 검토되지 않은 가정이 가장 많은 낭비를 만든다는 것이 이 표의 요지입니다.

5. 적용 예시

이 블로그에 도구 섹션을 넣는 상황을 가정해 보겠습니다. 실제로 이 스킬을 돌린 기록이 아니라, 앞에서 읽은 규칙이 이 요청에 어떻게 적용될지 따라가 보려고 만든 시나리오입니다.

요청은 "AI 도구를 소개하는 섹션을 넣고 싶다"입니다. 이 블로그에는 이미 글 목록과 분류 체계가 있으므로 바꿀 흐름이 저장소에 있는 셈이지만, 새 페이지와 데이터 구조까지 건드릴 수 있어 범위가 어디까지인지 모호합니다. 두 경로 사이에서 망설여지는 경우이므로 원문 규칙대로라면 더 무거운 쪽, 곧 구조에 관한 변경으로 시작합니다.

에이전트는 먼저 저장소를 읽습니다. 글을 저장하는 테이블, 글 분류 값, 목록 페이지가 어떻게 되어 있는지 살핍니다. 그리고 질문을 하나씩 던집니다. 어디에 보여 줄지(전용 페이지인지 기존 목록의 필터인지), 데이터는 어디에 둘지, 처음 글은 몇 편으로 시작할지. 각 질문에는 장단점이 붙은 선택지가 있습니다.

질문 없이 시작했다면 저는 새 테이블부터 만들었을 것 같습니다. 하지만 위 질문들에 답하다 보면 기존 글 테이블에 분류 값 하나를 더하는 쪽이 훨씬 가볍다는 사실이 드러납니다. 목록, 필터, RSS가 이미 그 테이블을 보고 있기 때문입니다. 접근 방법을 두세 가지 비교하는 단계에서 이 차이가 숫자가 아니라 "무엇을 새로 만들지"의 목록으로 보입니다. 새 테이블 방식은 테이블, 마이그레이션, 목록, RSS 처리를 모두 새로 써야 하고, 분류 값 방식은 값 하나와 페이지 하나면 됩니다.

설계에 동의하면 설계 문서가 만들어지고, 문서를 검토한 뒤에야 계획 작성 스킬이 파일 단위 작업 계획을 만듭니다. 이 모든 과정이 끝나기 전에는 코드가 한 줄도 쓰이지 않습니다. 이 스킬이 하는 일은 결국 그 순서를 지키게 하는 것입니다.

6. 써 본 소감

구현 속도는 조금 느려 보입니다. 질문과 승인을 거치는 동안 코드는 나오지 않기 때문입니다. 하지만 갈아엎는 횟수가 줄어서 전체로는 이득이라고 느꼈습니다. 요청이 한 줄인데 영향 범위가 넓을 때 특히 쓸 만하다고 생각합니다.

반대로 아쉬운 점도 있습니다. 승인 관문이 모든 작업에 적용되다 보니, 이미 머릿속에서 정리가 끝난 작은 변경에서는 질문이 번거롭게 느껴질 수 있습니다. 원문이 분류를 소리 내어 말하게 한 것은 이 번거로움을 사용자가 바로 줄일 수 있게 하려는 장치라고 이해했습니다. 분류가 과하다 싶으면 그 자리에서 가볍게 바로잡으면 됩니다.

Comments (0)