blueprint

blueprint skill 개요

blueprint가 하는 일

blueprint skill은 한 줄짜리 목표를 복잡한 엔지니어링 작업을 위한 단계별 실행 계획으로 바꿔줍니다. 여러 세션과 여러 PR에 걸쳐 진행되는 작업에서, 새로 투입된 에이전트가 추측하지 않고도 이어서 작업할 수 있을 만큼 충분한 맥락을 제공하도록 설계되었습니다. Project Setup을 위한 blueprint, 마이그레이션 로드맵, 또는 의존성이 얽힌 리팩터링 계획이 필요하다면 이 skill이 특히 잘 맞습니다.

누가 설치하면 좋은가

세션 사이에 작업을 자주 인계하거나, 병렬 하위 작업을 조율하거나, 컨텍스트가 끊겨도 유지되는 계획이 필요하다면 blueprint를 설치하는 것이 좋습니다. 특히 기존 repo 안에서 작업하는 에이전트에게 유용한데, 이 경우 핵심 난제는 아이디어를 만들어내는 것이 아니라 작업 순서를 안전하게 설계하는 데 있기 때문입니다.

무엇이 다른가

일반적인 프롬프트와 달리 blueprint에는 트리거 규칙, 의존성 순서 정렬, 병렬 가능 단계 감지, 반대 관점의 리뷰 게이트, 그리고 계획 수정 프로토콜이 내장되어 있습니다. 핵심 리스크가 코드 작성 자체보다도 잘못된 순서를 택하거나, 단계를 과소 범위로 정의하거나, 롤백 경로를 놓치는 데 있을 때 이 차이가 크게 작용합니다.

blueprint skill 사용 방법

올바르게 설치하고 필요한 상황에서만 호출하기

디렉터리의 기본 skill 설치 방식으로 blueprint skill을 설치한 뒤, 작업이 실제로 다단계일 때만 호출하세요. 이 repository의 트리거 규칙은 의도적으로 좁게 잡혀 있습니다. 작업이 여러 세션 또는 여러 PR에 걸칠 가능성이 높을 때 plan, blueprint, roadmap 용도로 사용하고, 한 번에 끝낼 수 있는 작은 변경에는 쓰지 않는 것이 좋습니다.

적절한 입력 정보를 주기

Blueprint는 목표, 대상 repo, 제약 조건, 완료 정의가 입력에 명시될 때 가장 잘 작동합니다. 약한 프롬프트는 “plan the refactor”입니다. 더 좋은 프롬프트는 다음과 같습니다. “Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.” 범위를 구체적으로 줄수록 의존성 그래프와 단계 크기 조정이 더 정확해집니다.

먼저 읽어야 할 파일

우선 SKILL.md부터 읽고, 그다음 워크플로, 관례, 기존 계획을 설명하는 repo 문서를 확인하세요. 이 repository에서는 skill 본문이 자체 완결적이므로, 핵심은 research, design, review, mutation rules로 이어지는 파이프라인을 파악하는 것입니다. 대상 코드베이스에 memory files, 아키텍처 문서, 이전 마이그레이션 노트가 있다면 blueprint 결과 품질이 눈에 띄게 좋아집니다.

더 나은 결과를 만드는 워크플로

blueprint는 세 번에 나눠 쓰는 방식이 가장 효과적입니다. 먼저 계획을 생성하고, 다음으로 각 단계가 정말 독립적으로 수행 가능한지 점검한 뒤, 마지막으로 빠진 의존성이나 위험한 병렬 작업이 없는지 수정하세요. 같은 파일, 공유 상태, 릴리스 순서에 의존하는 단계는 특히 주의해야 합니다. 보기에는 깔끔한 계획도 실제 실행에서는 이런 지점에서 무너질 수 있습니다. 좋은 blueprint 활용은 “더 자세한 계획”이 아니라 “처음 보는 사람도 실행할 수 있을 만큼의 맥락을 갖춘 올바른 순서 설계”에 가깝습니다.

blueprint skill FAQ

blueprint는 큰 프로젝트에만 적합한가?

대체로 그렇습니다. 이 skill은 단일 PR로 처리하기엔 너무 크거나, 계획 없이 진행하면 위험한 작업을 위해 만들어졌습니다. 작업이 작고 단순하거나 몇 번의 도구 호출만으로 끝낼 수 있다면, 일반 프롬프트가 보통 더 빠릅니다.

blueprint는 일반 프롬프트와 어떻게 다른가?

일반 프롬프트로도 계획을 요청할 수는 있지만, blueprint는 구조를 더합니다. 단계 간 의존성, 병렬 가능성 감지, 롤백 관점, 그리고 취약한 가정을 걸러내려는 리뷰 레이어가 포함됩니다. 그래서 Project Setup을 위한 blueprint처럼 순서와 인계 품질이 중요한 작업에서 더 신뢰할 수 있습니다.

blueprint는 초보자에게도 좋은가?

그렇습니다. 프로젝트를 관리 가능한 단계로 나누는 법을 익히려는 목적이라면 특히 도움이 됩니다. 다만 아직 “무엇을 해야 하는지” 자체가 정리되지 않은 상태라면 유용성이 떨어집니다. 이 skill은 제약 조건과 완료 경로가 있는 실제 엔지니어링 목표를 전제로 하기 때문입니다.

언제 blueprint를 쓰지 말아야 하나?

작업이 곧바로 끝낼 수 있을 만큼 작을 때, 사용자가 명시적으로 “just do it”이라고 말할 때, 또는 작업에 의미 있는 의존성 구조가 없을 때는 blueprint를 쓰지 마세요. 이런 경우에는 계획 수립 오버헤드만 늘어나고 결과는 크게 나아지지 않을 수 있습니다.

blueprint skill을 더 잘 활용하는 방법

범위를 명확하게 적기

좋은 blueprint 결과물은 범위 경계가 분명할수록 잘 나옵니다. 무엇이 반드시 바뀌어야 하는지, 무엇은 안정적으로 유지되어야 하는지, 무엇이 범위 밖인지, 무엇을 성공으로 볼 것인지를 명확히 적으세요. Project Setup을 위한 blueprint가 필요하다면 repo 부트스트래핑, 환경 설정, CI setup 중 무엇을 바꾸려는지, 혹은 셋 다 포함하는지 분명히 밝혀야 합니다. 범위가 모호하면 지나치게 크거나 너무 얕은 계획이 나오기 쉽습니다.

의존성 단서를 처음부터 제공하기

Blueprint는 어떤 요소가 다른 요소를 막는지 알고 있을 때 가장 강력합니다. 마이그레이션, shared modules, feature flags, API contracts, 릴리스 순서, 그리고 다른 단계가 시작되기 전에 먼저 반영되어야 하는 사항을 초기에 함께 적어주세요. 그래야 서로 분리된 작업 목록이 아니라 실제로 쓸 만한 의존성 그래프를 만들어낼 수 있습니다.

바로 실행 가능한 단계로 요청하기

더 좋은 blueprint skill 출력을 원한다면, 새로 투입된 에이전트도 맥락 없이 바로 수행할 수 있는 단계를 요청하세요. 각 단계에는 전체 repo를 다시 읽지 않아도 될 만큼의 배경, 기대 결과, 위험 메모가 포함되어야 합니다. 이는 특히 여러 에이전트가 함께 작업할 때 중요합니다. 단계 제목이 모호하면 재작업이 발생하기 쉽습니다.

첫 번째 계획을 반드시 다듬기

첫 blueprint는 초안으로 보고, 빠진 제약 조건이 없는지, 충돌하는 병렬 작업은 없는지, 한 PR에 담기에는 너무 큰 단계는 없는지 확인한 다음 다듬으세요. 계획이 너무 넓으면 쪼개고, 너무 세세하면 반복되는 setup 작업은 묶어 정리하세요. 목표는 더 예쁜 개요가 아니라, 실행 리스크를 낮춰주는 blueprint를 만드는 것입니다.