gepetto

gepetto skill 개요

gepetto가 하는 일

gepetto skill은 대략적인 기능 아이디어를 코딩에 들어가기 전에 상세한 구현 패키지로 정리해 주는 구조화된 계획 수립 워크플로입니다. 짧은 프롬프트에서 바로 코드로 뛰어들기보다, gepetto는 조사, 요구사항을 분명히 하기 위한 인터뷰 질문, 스펙 통합, 구현 계획 수립, 외부 리뷰, 섹션별 작업 분해까지 단계적으로 진행합니다.

gepetto skill이 가장 잘 맞는 사용자

이 gepetto skill은 다음과 같은 경우에 특히 잘 맞습니다.

• 범위가 아직 불명확한, 가볍지 않은 기능을 계획 중일 때
• backend, frontend, infra, integrations를 함께 다뤄야 할 때
• 구현 전에 재작업 가능성을 줄이고 싶을 때
• AI를 단순 코드 생성이 아니라 Requirements Planning 용도로 쓰고 싶을 때
• markdown spec 파일을 제공하고, 후속 질문에 답할 의향이 있을 때

반대로 빠른 코드 스니펫 하나나 파일 하나만 고치는 수준의 작은 작업이라면, gepetto는 필요 이상으로 무거운 선택일 가능성이 큽니다.

실제로 해결하는 핵심 문제

대부분의 사용자가 필요한 것은 추상적인 의미의 “더 많은 AI planning”이 아닙니다. “인증 만들기”, “결제 붙이기”, “파일 동기화 지원”처럼 모호한 요청을, 엣지 케이스·의존성·롤아웃 이슈·구현 순서까지 담긴 실행 가능한 계획으로 바꾸는 방법이 필요합니다. 바로 이 지점에서 gepetto는 일반적인 프롬프트보다 강점을 보입니다.

gepetto가 다른 점

gepetto의 차별점은 실무적인 부분에 있습니다.

• spec 파일을 필수로 받아, 워크플로의 기준점이 오래 유지됩니다
• 빠진 요구사항을 임의로 가정하지 않고, 명시적으로 확인 질문을 던집니다
• 최종 계획을 확정하기 전에 조사를 수행할 수 있습니다
• 가능하다면 다른 model CLI를 활용한 external review 단계를 포함합니다
• 결과물을 긴 에세이 하나가 아니라, 실제 실행을 염두에 둔 섹션 단위 출력으로 만듭니다

이 조합 덕분에 gepetto skill은 일반적인 “계획 좀 써줘” 프롬프트보다 훨씬 의사결정 중심적입니다.

설치 전에 사용자가 확인해야 할 점

gepetto를 도입하기 전에 대부분의 사용자가 먼저 확인해야 할 것은 네 가지입니다.

1. markdown spec 파일이 있는가? 이 skill은 이를 전제로 합니다.
2. planning 디렉터리에 파일이 생성되는 방식을 원하는가? gepetto는 파일 출력 중심입니다.
3. 현재 환경이 이 워크플로를 지원하는가? 일부 단계는 조사와 선택적 external review 도구를 가정합니다.
4. 이 작업이 이 과정을 정당화할 만큼 충분히 복잡한가? 기능이 복잡할수록 투자 대비 효과가 커집니다.

gepetto skill 사용 방법

skill 환경에 gepetto 설치하기

toolkit의 일반적인 설치 패턴을 쓰고 있다면, 저장소에서 다음처럼 skill을 추가하면 됩니다.

npx skills add softaworks/agent-toolkit --skill gepetto

그다음 slash-skill 사용을 지원하는 agent 세션에서 이 skill을 호출하면 됩니다. 저장소 경로는 다음과 같습니다.

skills/gepetto

환경에 다른 skill 로딩 메커니즘이 있다면, repo 파일을 직접 사용하되 동일한 invocation contract를 맞춰 주세요.

반드시 알아야 할 입력 계약

도입 시 가장 중요한 포인트는 gepetto가 호출 시점에 markdown spec 파일 경로를 요구한다는 점입니다. 이 skill은 .md로 끝나는 @file 입력이 있는지 검사하고, 없으면 중단한 뒤 올바른 입력을 다시 요청합니다.

실무적으로는, 느슨한 채팅 요청만으로 gepetto를 시작하면 안 됩니다. 다음처럼 시작해야 합니다.

/gepetto @planning/auth-spec.md

이때 해당 spec의 상위 디렉터리가 gepetto가 추가 .md 결과물을 쓰는 planning workspace가 됩니다.

spec 파일에 들어가야 할 내용

시작용 spec이 완벽할 필요는 없지만, 입력 품질이 좋을수록 계획 결과물의 품질도 눈에 띄게 좋아집니다. 좋은 초기 파일에는 보통 다음이 포함됩니다.

• 기능 또는 문제 정의
• 사용자 유형과 핵심 워크플로
• 이미 알고 있는 제약사항
• 기술 스택
• 기존 시스템 맥락
• 미확정 사항이나 열린 질문
• 성공 기준
• 비목표

다소 거친 spec도 괜찮지만, 운영 맥락이 구체적일수록 gepetto가 누락된 가정을 복구하느라 쓰는 시간이 줄어듭니다.

gepetto spec 템플릿을 강하게 만드는 구성

gepetto를 더 잘 활용하려면, spec에 아래처럼 짧은 섹션을 미리 넣어 두는 것이 좋습니다.

• Goal: 완료 시 어떤 상태가 되어 있어야 하는지
• Users: 누가 이것과 상호작용하는지
• Current system: 관련 서비스, repos, modules
• Constraints: 마감, compliance, 성능, 예산
• Interfaces: APIs, events, storage, third-party dependencies
• Risks/unknowns: 아직 확신이 없는 요소
• Definition of done: 이 계획이 실제로 실행 가능하다고 볼 기준

보통 이 정도만 있어도 첫 번째 결과물의 품질이 상당히 높아집니다.

gepetto skill 워크플로에서 실제로 일어나는 일

저장소 내용을 보면, gepetto는 비교적 명확한 순서로 진행됩니다.

1. spec 파일 입력 검증
2. planning session 설정
3. 조사가 필요한지 판단
4. 조사 수행 및 결과 통합
5. 사용자에게 초점을 맞춘 질문 진행
6. 통합된 구현 계획 작성
7. 계획에 대해 external review 수행
8. 작업을 구현 섹션 단위로 분할

이 흐름 덕분에 gepetto는 숨겨진 엣지 케이스나 아키텍처 트레이드오프가 많은 요구사항에서 특히 유용합니다.

대략적인 목표를 실제로 쓸 수 있는 호출로 바꾸는 법

약한 시작점:

Build authentication

gepetto에 더 적합한 강한 시작점:

Create email/password and Google OAuth login for our SaaS app. Stack: Next.js, Postgres, Stripe, existing RBAC. Need session handling, audit logging, admin user provisioning, password reset, account lockout, and migration plan from legacy auth. Must support SOC 2 audit needs. Unknown: whether to use our current session store or move to JWT.

이렇게 쓰면 더 좋은 이유는 다음과 같습니다.

• 조사할 대상을 분명히 잡아 줍니다
• integration 지점을 드러냅니다
• compliance와 migration 이슈를 조기에 드러냅니다
• 더 좋은 인터뷰 질문을 만들 수 있습니다
• 일반론적인 planning 문구를 줄입니다

Requirements Planning을 위한 gepetto 최적 워크플로

gepetto for Requirements Planning을 제대로 활용하려면, 보통 아래 순서가 가장 효율적입니다.

1. 거칠더라도 실제 내용이 있는 spec 파일을 작성한다
2. 그 파일에 대해 gepetto를 실행한다
3. 확인 질문에 구호가 아니라 운영 디테일로 답한다
4. 생성된 계획에서 빠진 business rule이 없는지 검토한다
5. 섹션 결과물을 구현 단위나 티켓으로 사용한다
6. 요구사항이 크게 바뀌면 다시 실행하거나 이어서 진행한다

한 번에 거대한 최종 spec 하나를 뽑으려 하기보다, 이런 방식이 훨씬 효과적입니다.

먼저 읽어볼 저장소 파일

전면 도입 전에 이 skill을 판단해 보고 싶다면, 다음 순서로 읽는 것이 좋습니다.

1. skills/gepetto/SKILL.md
2. skills/gepetto/README.md
3. skills/gepetto/references/research-protocol.md
4. skills/gepetto/references/interview-protocol.md
5. skills/gepetto/references/external-review.md
6. skills/gepetto/references/section-index.md
7. skills/gepetto/references/section-splitting.md

이 순서로 읽으면 메인 README만 대충 훑는 것보다 실제 동작 방식을 훨씬 잘 파악할 수 있습니다.

출력 파일과 그 중요성

gepetto는 단순한 대화형 프롬프트가 아닙니다. 선택한 디렉터리에 planning artifact를 실제 파일로 기록하도록 설계되어 있습니다. repo를 보면 다음과 같은 출력이 예상됩니다.

• research notes
• main implementation plan
• sections/index.md
• 개별 section 파일들

이 점이 중요한 이유는, 이런 워크플로가 일회성 채팅 출력보다 이어서 작업하기 쉽고, 다른 사람에게 넘기기도 수월하기 때문입니다.

External review는 강력하지만 실무에서는 선택 사항일 수 있음

gepetto의 가장 좋은 아이디어 중 하나는 external review 단계입니다. references를 보면 Gemini나 Codex 같은 다른 model CLI를 통해 생성된 계획을 검토하는 흐름을 전제로 합니다. 이 단계는 다음과 같은 문제를 드러내며 계획 품질을 실제로 끌어올릴 수 있습니다.

• 보안 공백
• 엣지 케이스
• 성능 문제
• 모호한 요구사항
• 아키텍처상 위험한 선택

다만 이것은 곧, gepetto를 최대한 활용하려면 환경이 이를 뒷받침해야 한다는 뜻이기도 합니다. 외부 도구가 없다면 나머지 planning 워크플로만으로도 충분히 유용할 수 있지만, review 레이어는 별도 방식으로 보완해야 할 수 있습니다.

첫 실행 품질을 높이는 실전 팁

아래 몇 가지는 gepetto 결과 품질을 크게 바꿉니다.

• 이미 코드베이스가 있다면 기존 패턴이나 파일 경로를 함께 적기
• 예상 규모, 트래픽, 장애 처리 방식을 명시하기
• 바뀌면 안 되는 것을 분명히 적기
• compliance, privacy, audit 요구사항을 나열하기
• 인터뷰 질문에 “보통 하는 방식대로”가 아니라 구체적으로 답하기
• 실행 전에 생성된 sections의 의존 순서를 검토하기

gepetto는 모호함을 숨기는 것보다 초기에 드러낼 수 있을 때 가장 좋은 성능을 냅니다.

gepetto skill FAQ

gepetto는 일반 planning 프롬프트보다 더 나은가?

단순한 작업에서는 꼭 그렇다고 할 수 없습니다. 하지만 여러 단계가 얽힌 기능이라면, gepetto가 대체로 더 강합니다. spec 검증, 조사, 인터뷰, 통합, 리뷰, 섹션 분할이라는 계획 프로세스를 강제하기 때문입니다. 일반 프롬프트는 더 빨라 보일 수 있지만, 숨은 가정을 건너뛸 가능성도 더 큽니다.

gepetto는 초보자도 쓰기 쉬운가?

기본적인 markdown spec을 작성할 수 있고 후속 질문에 답할 수 있다면, 그렇습니다. 처음부터 완벽한 spec이 필요한 것은 아닙니다. 다만 완전 초보자라면, 결과 계획이 실제 엔지니어링 제약과 맞는지 판단하는 데 여전히 도움이 필요할 수 있습니다.

어떤 경우에는 gepetto skill을 쓰지 말아야 하나?

다음 경우에는 gepetto를 건너뛰는 편이 낫습니다.

• 작업이 아주 작고 리스크가 낮을 때
• 이미 승인된 구현 계획이 있을 때
• spec 파일을 제공할 수 없을 때
• 파일 기반 출력 자체를 원하지 않을 때
• 필요한 워크플로를 환경이 지원하지 못할 때

이 오버헤드는 의도된 설계이므로, 일회성 작은 작업에는 잘 맞지 않습니다.

gepetto는 코드베이스 접근이 꼭 필요한가?

항상 그런 것은 아니지만, 있으면 도움이 됩니다. product 스타일의 요구사항 문서만으로도 skill은 동작할 수 있습니다. 다만 실제 repo나 프로젝트 맥락에서 기존 패턴과 아키텍처를 조사할 수 있을 때 가치가 더 커집니다.

도입 시 가장 큰 장애물은 무엇인가?

대개 입력 품질과 호출 형식입니다. 많은 사용자가 gepetto를 자유형 챗봇처럼 시작하려고 합니다. 하지만 그렇지 않습니다. 이 skill은 markdown spec 경로와 planning 파일을 쓸 디렉터리를 기대합니다.

gepetto는 주로 Requirements Planning용인가, 구현용인가?

핵심 강점은 구현에 가까운 Requirements Planning입니다. 단순한 product discovery 도구도 아니고, 단순한 코드 생성 도구도 아닙니다. 요구사항과 제약을 개발자가 더 적은 변수로 실행할 수 있는 계획으로 바꾸는, 그 중간 지점에 있습니다.

gepetto skill 개선 방법

더 긴 spec보다 더 나은 spec으로 시작하기

gepetto 출력 품질을 높이는 가장 좋은 방법은 입력 spec의 신호 품질을 높이는 것입니다. 분량을 늘리기보다 구체성을 더하세요. 특히 아래 정보가 큰 도움이 됩니다.

• 현재 아키텍처
• 영향받는 시스템
• 예상 규모
• 보안/compliance 요구사항
• migration 또는 rollout 제약
• 중요하게 보는 failure modes

구체적인 한 페이지짜리 spec이, 모호한 다섯 페이지짜리 문서보다 대개 더 낫습니다.

gepetto가 추론할 수 없는 제약은 직접 넣기

gepetto는 확인 질문을 던질 수는 있지만, 숨겨진 business rule을 안정적으로 추론하지는 못합니다. 예를 들어 아래 같은 내용은 직접 명시해야 합니다.

• “기존 API 클라이언트와의 하위 호환성을 반드시 유지해야 함”
• “관리자 액션의 audit log는 1년간 보관해야 함”
• “이번 분기에는 새로운 인프라 벤더를 도입할 수 없음”
• “provider X 장애 시 기능이 graceful degradation 방식으로 동작해야 함”

이런 제약은 계획의 현실성을 크게 높여 줍니다.

인터뷰 단계에서 더 강한 답변 주기

인터뷰 프로토콜은 gepetto에서 가장 가치가 높은 부분 중 하나입니다. 대충 넘기지 말고 진지하게 대응하세요. 약한 답변은 일반적인 계획을 만들고, 정밀한 답변은 실제 실행 가능한 섹션을 만듭니다.

덜 유용한 답변:

• “standard auth”
• “make it scalable”
• “just follow best practices”

더 유용한 답변:

• “session invalidation must be immediate after password reset”
• “org admins can invite users, but only owners can change billing”
• “we expect 50k monthly active users within 6 months”

계획에서 빠진 운영 디테일이 없는지 검토하기

gepetto의 첫 결과물이 나오면, 계획이 아래 항목을 다루고 있는지 확인해 보세요.

• monitoring and alerting
• rollback 또는 migration 전략
• data model 변경
• permissions와 abuse case
• test 전략
• deployment 순서
• documentation 업데이트

초기 프롬프트가 기능 중심일수록 이런 부분이 빠지기 쉽습니다.

section 파일을 실행 단위로 활용하기

sectioning 시스템은 gepetto에서 가장 실용적인 부분 중 하나입니다. 결과를 더 좋게 만들려면, 각 section이 다음 조건을 만족하는지 확인하세요.

• 이름이 명확할 것
• 의존성을 반영할 것
• 문서 설명용이 아니라 실제 구현 가능한 크기일 것
• 가능하면 병렬 진행이 가능할 것

하나의 section이 너무 많은 다른 작업을 막거나, 서로 무관한 이슈를 섞고 있다면 코딩 agent에 넘기기 전에 먼저 쪼개는 편이 좋습니다.

실제 도구 체인에 맞게 external review 조정하기

references는 CLI 도구를 통한 external review를 가정합니다. 환경이 다르더라도, 메커니즘만 바뀔 뿐 같은 리뷰 의도는 유지하는 것이 좋습니다. 중요한 것은 특정 도구가 아니라, 구현에 들어가기 전에 생성된 계획에 대해 독립적인 비판과 검토를 받는 일입니다.

gepetto 사용에서 자주 발생하는 실패 패턴

가장 흔한 문제는 대체로 예측 가능합니다.

• .md spec 파일 없이 시작하는 경우
• 구호 수준의 기능 요청만 주는 경우
• 인터뷰 단계에서 구체적인 답변을 생략하는 경우
• 첫 계획 초안을 최종본처럼 다루는 경우
• section 간 의존성을 무시하는 경우
• repo별 관례를 빼먹는 경우

이 문제의 대부분은 모델 temperature를 바꾸는 것보다, 설정과 입력을 개선하는 쪽으로 해결됩니다.

첫 gepetto 결과물 이후 반복 개선하는 법

좋은 두 번째 패스는 보통 이렇게 진행됩니다.

1. 계획에서 불분명하거나 틀린 가정을 표시한다
2. 빠진 business rule을 spec에 추가한다
3. gepetto를 다시 실행하거나 이어서 진행한다
4. 수정된 sections를 실제 구현 현실과 비교한다
5. 그다음에야 sections를 티켓이나 코딩 작업으로 바꾼다

바로 이 반복 루프에서 gepetto 가이드의 진가가 드러납니다. 실제 개발을 시작하기 전에 비용이 큰 모호함을 줄여 주기 때문입니다.

gepetto에서 장기적으로 가치를 얻는 가장 좋은 방법

gepetto를 일회성 아이데이션 도구로만 쓰지 마세요. 중간 규모 이상 기능에 대한 반복 가능한 planning 표준으로 활용하는 것이 좋습니다. 팀 차원에서는 다음을 표준화할 때 가장 큰 가치를 얻습니다.

• spec을 어디에 둘지
• spec에 최소한 어떤 디테일이 들어가야 하는지
• review 코멘트를 어떻게 다시 반영할지
• section 파일을 구현 작업과 어떻게 매핑할지

이렇게 해야 gepetto가 단순히 영리한 프롬프트가 아니라, 신뢰할 수 있는 planning workflow로 자리잡습니다.