pstack 사용설명서: AI가 코드를 빠르고 제대로 쓰게 만드는 Cursor 플러그인
Cursor 및 Claude Code에서 AI 에이전트가 품질 높은 코드를 작성하도록 돕는 pstack 플러그인의 설치 방법, /poteto-mode, 23가지 플레이북, 전체 스킬과 24가지 핵심 원칙을 정리했습니다.
목차
pstack이란?
- 만든 사람 —
poteto. Meta, Netflix, Cursor에서 수백만 줄의 코드를 다뤘고, React 코어 팀에서 React Compiler를 개발하고 있는 엔지니어입니다. - 왜 만들었나 — "AI가 쓰레기(slop) 코드를 너무 많이 만든다"는 인식에 동의하면서, 그대로 두고 싶지 않았습니다. 속도만 높이고 품질을 놓치는 것은 목표가 아니라고 생각했죠.
- 해결책 — 자신이 Cursor에서 매일 쓰는 스킬들을 그대로 공개한 것이
pstack입니다. 목표는 더 많은 코드가 아니라, 그 반대 — 더 적지만 품질 높은 코드입니다.
설치하기
사용 중인 에디터/에이전트 환경 탭을 선택해 설치 명령을 복사하세요.
/add-plugin pstack시작하기 (2단계)
- 1역할별 모델 및 예산 설정
/setup-pstack추론 예산(reasoning budget)을 고르고, 어떤 모델을 역할별로 쓸지 선택합니다. 기본 설정은 코드·판단·리뷰 패널 역할별로 모델을 나눠 배치합니다.
- 2첫 작업 시작 및 도움말 호출
/poteto-mode처음이라면 pstack 가이드가 실제 작업 하나를 처음부터 끝까지(설치 → 프롬프트 → 검증 → 야간 실행) 안내해 줍니다. 어떤 스킬을 써야 할지 모르겠으면 /poteto-help를 입력하세요.
기본 모델 구성
코드 작업(기능·리팩터링·버그 수정·성능·힐클라임), 글쓰기, 판단은 Opus 5.5가 맡고, 가장 어려운 변경은 Fable 5.2가 맡습니다. 기본 리뷰 패널은 Fable 5.2 / Opus 5.5 / Gemini 4 Carbon이며, 전부 /setup-pstack에서 변경할 수 있습니다.
핵심: /poteto-mode
/poteto-mode는 pstack의 메인 관문입니다.
사용법
/메뉴에서/poteto-mode를 먼저 선택한 뒤 작업 내용을 입력합니다(스킬이 메시지에 첨부됩니다).- 모드가 작업에 맞는 플레이북을 매칭하고, 절차가 담긴 할 일 목록을 만듭니다.
- 진행하면서 필요한 다른 스킬들로 라우팅하고, 사람이 읽기 좋게 정돈된 답변을 돌려줍니다.
/poteto-mode 이 PR에는 아무것도 안 해도 750ms마다 스크롤이 흐르는 미묘한 버그가 있다.
재현부터 하고, 고친 다음 검증까지 해줘./poteto-mode 나 잘 자. CI가 깜빡거려도 스택을 머지해. 아침까지 전부 머지돼 있길 원해.23가지 플레이북
"/poteto-mode가 상황에 따라 무엇을 고를까?"를 미리 찾고 싶다면 아래 탐색기에서 그룹을 고르거나 상황 키워드로 바로 검색해 보세요.
빠른 선택 & 전체 23개 플레이북 탐색기
- 버그가 보인다 / 잘못된 동작을 고쳐야 한다1순위· 1. 코드 변경
결함을 재현하고, 근본 원인을 찾고, 런타임 증거를 들어 고칩니다. 증상이 살아있는데 재현이 안 잡히면 runtime forensics로 전환하세요.
1순위:bug fix대안:runtime forensics - 새 기능을 만들어야 한다1순위· 1. 코드 변경
이름 붙은 데이터 구조에서 출발해 새 동작을 만들거나 변경합니다. 설계 갈림길이 애매하면 prototype을 먼저 실행하세요.
1순위:feature대안:prototype - 동작은 그대로, 구조만 고치고 싶다1순위· 1. 코드 변경
외부 동작을 그대로 유지한 채 코드 구조와 형태만 깔끔하게 정리합니다.
1순위:refactoring - 느리다·뚝뚝 끊긴다2순위· 1. 코드 변경
측정된 느림을 추적해 기준선(baseline) 대비 개선합니다. 이미 캡처한 프로파일 파일이 있으면 trace forensics가 적합합니다.
1순위:perf대안:trace forensics - 핵심 지표 하나를 목표치까지 끌어올리고 싶다2순위· 1. 코드 변경
가설 → 전후 측정 → 승인된 승리마다 커밋 1개 사이클을 반복하며 지표를 과학적으로 개선합니다.
1순위:hillclimb - 설계 갈림길을 싸게 실험해 보고 싶다3순위 (조건부)· 1. 코드 변경
본 코드를 짜기 전에 설계·동작 결정을 실험으로 해소하기 위한 버리는 스케치입니다.
1순위:prototype - 두 구현의 픽셀 단위 UI 일치를 맞춰야 한다3순위 (조건부)· 1. 코드 변경
디자인 검수나 마이그레이션 검증 등 픽셀 단위 일치가 꼭 필요할 때만 사용합니다.
1순위:visual parity - 재현은 어렵지만 살아있는 런타임 증상이 있다1순위· 2. 원인 진단
메모리 누수, idle CPU 점유, 간헐적 글리치 등 살아있는 증상을 계측으로 진단합니다.
1순위:runtime forensics - 이미 수집한 프로파일 산출물이 있다2순위· 2. 원인 진단
cpuprofile, trace, spindump, 힙 스냅샷 등 캡처된 프로파일링 산출물을 정밀 진단합니다.
1순위:trace forensics - 이미 만들어진 걸 검토·이해하고 싶다유일· 3. 이해·조사
코드를 바꾸지 않고 '어떻게 동작하지?', '왜 이렇게 만들었지?'를 파헤칩니다. '왜?'에 집중되면 /why 스킬이 더 적합합니다.
1순위:investigation대안:/why - PR이 리뷰·CI·충돌로 멈춰 있다1순위· 4. PR·머지 운영
PR/스택의 충돌, 리뷰 스레드, CI 실패, 상태 확인을 처리해 머지 준비 상태로 끌어올립니다. 스택 전체 머지라면 shipping을 쓰세요.
1순위:babysit대안:shipping - 그린 상태의 PR 스택을 안전하게 착지시켜야 한다1순위· 4. PR·머지 운영
그린 스택을 독립적으로 검증한 뒤, 검증된 연속 구간을 GitHub(origin)에 아래부터 순서대로 착지합니다.
1순위:shipping - 독립적인 PR 다수를 머지까지 일괄 처리해야 한다2순위 (대량용)· 4. PR·머지 운영
PR마다 소유자 1명을 두고, 검증 스웜이 헤드마다 검증해 머지까지 자동 처리합니다.
1순위:autopilot-full - 검증된 PR 스택만 쌓아두고 머지는 직접 하고 싶다2순위 (대량용)· 4. PR·머지 운영
autopilot-full에서 머지 단계만 뺀 워크플로우로, 운영자가 직접 리뷰·착지할 수 있도록 검증된 PR 스택을 쌓습니다.
1순위:autopilot-stack - 작업 완료 후 정돈된 PR을 열어야 한다자동 호출· 4. PR·머지 운영
작은 순서 커밋들 + 컨벤셔널 커밋 제목 + 브리핑 본문으로 PR을 생성합니다(다른 플레이북 마지막에 자동 호출).
1순위:opening a PR - 자리를 비운 사이에 하나의 목표를 끝내야 한다1순위· 5. 장기·자율 실행
멈추지 않고 하나의 긴 작업을 완주합니다. 여러 날짜·여러 PR 규모라면 orchestrate를 선택하세요.
1순위:autonomous run대안:orchestrate - 여러 날·여러 스택 PR 규모의 상설 프로젝트다2순위 (대규모)· 5. 장기·자율 실행
서브에이전트 부대와 다계층 코디네이션이 필요한 대형 프로젝트를 코디네이터 채팅 하나에 맡깁니다.
1순위:orchestrate - 여러 단계에 걸친 작업의 구조를 먼저 잡아야 한다3순위 (설계 단계)· 5. 장기·자율 실행
여러 단계 또는 스택 PR에 걸치는 작업의 구조와 순서를 잡을 때 쓰는 사전 계획 플레이북입니다.
1순위:multi-phase plan - 어제의 작업을 이어서 해야 한다1순위· 6. 수명주기 관리
이전 에이전트가 진행하던 작업을 이어받아 매끄럽게 재개합니다. 넘기기 전 깨끗이 멈춰야 하면 pause safely를 쓰세요.
1순위:session pickup대안:pause safely - 진행 중인 작업을 나중에 이어받기 좋게 중단해야 한다2순위· 6. 수명주기 관리
진행 중이던 작업 상태와 맥락을 손실 없이 정리해 안전하게 중단합니다(session pickup의 짝).
1순위:pause safely - 디스크 용량이 부족하고 낡은 worktree가 쌓였다3순위 (가끔)· 6. 수명주기 관리
머지·폐기된 Git worktree와 낡은 iOS 시뮬레이터를 정리해 디스크 공간을 회수합니다.
1순위:worktree cleanup - 새 SKILL.md를 작성하거나 기존 스킬을 고쳐야 한다1순위· 7. 메타 작업
pstack 내부 또는 프로젝트용 SKILL.md 문서를 설계·수정할 때 사용합니다.
1순위:authoring a skill - 스킬·프롬프트 변경 효과를 객관적으로 검증하고 싶다2순위· 7. 메타 작업
스킬이나 프롬프트 변경이 실제 에이전트 행동에 미치는 영향을 블라인드로 테스트합니다.
1순위:eval
헷갈리기 쉬운 3형 비교: autonomous run / autopilot-full / orchestrate
- 한 줄 요약: 하나의 목표를 끝까지 밀면
autonomous run, 확정된 독립 PR 대기열이면autopilot-full, 설계부터 필요한 상설 프로그램이면orchestrate. - 원문 경계 정의: "하나의 과제를 한 개의 완료 조건까지 끌고 가는 것은 Autonomous run. 며칠짜리 상설 프로그램(many stacked PRs, 수십~수백 서브에이전트)은 Orchestrate. 한 에이전트가 세션 예산 안에서 끝낼 수 있는 일은 프로그램이 아니다."
autonomous run완료 조건을 정의하고 멈추지 않고 추진
“You own the exit condition”
- 작업 단위
- 목표 1개 + 검증 가능한 완료 조건 1개
- 실행 주체
- 에이전트 자신이 반복하며 직접 수정
- PR 구조
- 완료 조건에 포함될 뿐 구조 제약 없음
- 검증 방식
- 매 반복 완료 조건 대조, 진전 없으면 되돌림
- 규모·기간
- 세션 안에서 /loop로 돌리는 시간 단위
autopilot-full판정은 코디네이터가, PR은 각 오너가 소유
“You own the verdicts, never the PRs”
- 작업 단위
- 운영자가 넘겨준 독립 PR 대기열
- 실행 주체
- PR마다 오너 1명 + 코드를 안 쓴 검증 스웜
- PR 구조
- trunk에서 병렬, 절대 스택 없음
- 검증 방식
- 풀 스웜 1회 + 실제 화면 라이브 검증 (그린 CI만으론 머지 불가)
- 규모·기간
- 대기열 크기만큼 (보통 몇 시간~하루)
orchestrate코드는 안 쓰고 누가 무엇을 할지 프로그램 운영
“You run the program, never the code”
- 작업 단위
- 여러 영역·여러 스택 PR — 분해·순서·의존 관계까지 설계
- 실행 주체
- 코디네이터 → 서브코디네이터 → 워커 (최대 3계층)
- PR 구조
- 스택 PR·의존 관계 관리 포함
- 검증 방식
- 작성자와 다른 모델 계열의 검증자 통과 필요, diff·산출물 직접 판독
- 규모·기간
- 며칠 이상, 수십~수백 서브에이전트
전체 스킬 목록
원하는 슬래시 명령 칩을 클릭하면 바로 클립보드에 복사됩니다.
도움말 & 시작
이해하기
설계 & 병렬 작업
검증 & 리뷰
검증 스킬 만들기
글쓰기 & 유지보수
기타
/how 취소 기능은 어떻게 동작해? 취소를 위해 모든 런을 조회하면 n+1 문제가 있는 거 아냐?/interrogate 이 PR 리뷰해 줘.서브에이전트
| 서브에이전트 | 설명 |
|---|---|
subagent_type: "poteto-agent" | poteto-mode가 내부적으로 사용하는 기본 에이전트 래퍼입니다. 일반 generalPurpose로 대체하면 규칙 읽기를 건너뛰어 품질이 흐려질 수 있습니다. |
subagent_type: "comment-sicko" | 읽기 전용 주석 리뷰어입니다. 보통 직접 호출하지 않고 /no-comments를 통해 동작합니다. |
24가지 원칙
/poteto-mode는 작업 성격에 맞는 원칙을 적용하며, 4개 주제(원문 5개 그룹 분류 기반)로 탐색할 수 있습니다.
laziness-protocol코어삭제와 '문제를 푸는 가장 작은 변경'을 선호하라.
foundational-thinking코어로직 전에 핵심 타입·자료구조를 고민하라. 자료구조가 맞으면 이후 코드는 자명해진다.
redesign-from-first-principles코어요구사항을 1일차 기본 가정이었던 것처럼 재설계하라. 덧붙이기 금지.
attack-the-premise코어같은 전제를 공유한 수정 2개 이상이 같은 관문에서 실패하면, 그 전제를 직접 시험하라.
subtract-before-you-add코어죽은 코드·중복 검증기·스텁 참조를 먼저 빼고, 더 단순한 기반 위에 쌓아라.
minimize-reader-load코어질문과 답 사이의 계층 수를 세고, 읽는 사람 머릿속의 숨은 상태를 줄여라.
outcome-oriented-execution코어계획된 재작성·마이그레이션에서는 목표 아키텍처로 수렴하라.
experience-first코어구현 편의보다 사용자의 즐거움을 택하라. 대충 많이보다 완성도 있게 적게.
exhaust-the-design-space코어확정 전에 경쟁 프로토타입 2–3개를 만들어 나란히 비교하라.
build-the-lever코어사소하지 않은 일에는 손으로 하지 말고 도구(codemod, 스크립트, 생성기, 스킬)를 만들어라.
model-the-domain아키텍처흩어진 조건문 대신 도메인을 구조에 새겨라.
boundary-discipline아키텍처가드는 시스템 경계(CLI, 설정, 네트워크, 외부 API)에 모으고, 내부 타입은 신뢰하며, 비즈니스 로직은 순수 함수로 작성하라.
type-system-discipline아키텍처불가능한 상태를 표현 불가능하게 만들고, 외부 데이터는 경계에서 파싱하라.
make-operations-idempotent아키텍처부분 실행 이력과 무관하게 같은 최종 상태로 수렴하게 만들어라.
migrate-callers-then-delete-legacy-apis아키텍처호출부를 옮기고 같은 파도에서 옛 API를 지워라. 호환 계층을 남기지 마라.
separate-before-serializing-shared-state아키텍처공유를 먼저 없애고, 공유 쓰기 주체가 하나라는 게 진짜 불변식일 때만 직렬화하라.
prove-it-works검증'끝났다'고 말하기 전에 실제 산출물로 검증하라. '컴파일된다'는 검증이 아니다.
fix-root-causes검증증상을 시스템이 처음 잘못된 지점까지 추적해 거기서 고쳐라.
sequence-verifiable-units검증작업을 각자 검증 가능한 상태로 끝나는 작은 단위로 쪼개고 순서대로 검증하며 쌓아라.
test-behavior-not-implementation검증테스트는 사용자가 관찰할 수 있는 것을 단언하라.
explain-the-number검증측정한 숫자를 믿거나 보고하기 전에 제한 요인을 찾고 잘못 측정했을 가능성을 배제하라.
guard-the-context-window위임 & 메타대량 작업은 서브에이전트로 돌리고, 원시 페이로드가 아닌 요약만 메인 스레드에 남겨라.
never-block-on-the-human위임 & 메타진행하고, 결과를 보여주고, 사람은 나중에 방향을 고쳐라. 확인은 되돌릴 수 없는 행동에만.
encode-lessons-in-structure위임 & 메타교훈은 더 많은 글자가 아니라 린트·메타데이터 플래그·런타임 체크·스크립트로 새겨라.
내 것으로 만들기
- 모델 바꾸기 (
/setup-pstack): 내가 쓸 수 있는 모델을 감지해 역할(코드·판단·리뷰 패널)별로 모델을 매핑하는 규칙을 기록합니다. - 나만의 모드 (
/automate-me):/poteto-mode가 만든 사람의 스타일이라면,/automate-me는 최근 트랜스크립트를 분석해 내가 실제로 일해 온 방식으로<내-이름>-mode스킬을 초안해 줍니다.
자주 묻는 질문
Q1. pstack에 없는 것도 있나요?
Q2. 왜 계획(planning) 스킬이 없나요?
Q3. 자동화(automations)도 되나요?
Q4. 고치거나 확장해도 되나요?
Q5. 뭘 써야 할지 모르겠어요.
Hafuture 텍스트 & JSON 포맷터로 설정 파일 검증하기
Cursor·Claude Code 설정이나 JSON/프롬프트 텍스트를 다룰 때 브라우저에서 100% 로컬로 포맷·검증할 수 있습니다.