pstack 활용: Claude Code로 Todo 앱을 설계하고 검증하는 순서
Todo 앱 개발을 예제로 요구사항 정리, how 조사, architect 설계, 구현 위임, 검증 스킬 생성, 리뷰까지 이어갑니다. 단계별로 복사해 쓸 수 있는 Claude Code 요청문을 담았습니다.
Todo 앱을 코딩 에이전트에게 맡길 때 “할 일 앱 만들어줘”라고만 요청하면 결과를 판단하기 어렵다. 추가와 삭제는 되는데 새로고침하면 데이터가 사라질 수도 있고, 완료 필터에서 수정한 항목이 엉뚱한 위치에 반영될 수도 있다.
pstack을 활용하려면 만들 기능과 완료 조건을 먼저 정하고, 조사·설계·구현·검증 과정에서 그 조건을 계속 사용하면 된다. 이 글에서는 브라우저에 데이터를 저장하는 개인용 Todo 앱을 예로 들어 Claude Code에서 사용할 요청문을 단계별로 작성한다.
이 글은 pstack 소스에 근거한 개발 활용 가이드다. 아래 Todo 앱을 실제로 구현하거나 테스트한 결과 보고서는 아니다. 프롬프트와 데이터 타입은 실습을 위한 제안이며, 설치·스킬 동작은 커밋
0b8e952052d4기준이다.
1. 이번에 만들 Todo 앱의 범위
실습의 기본 구성은 React, TypeScript, Vite다. 이미 프로젝트가 있다면 기존 도구를 유지하고, 비어 있는 저장소라면 에이전트가 실행 환경을 확인한 뒤 초기화하도록 한다.
데이터는 브라우저의 localStorage에 저장한다. 서버, 로그인, 기기 간 동기화는 이번 범위에 넣지 않는다. 따라서 다른 브라우저나 기기에서 같은 목록이 보이지 않으며, 사이트 데이터를 지우면 저장한 할 일도 사라진다.
| 기능 | 완료를 판단할 기준 |
|---|---|
| 할 일 추가 | 제목 앞뒤 공백을 제거하고, 빈 제목은 저장하지 않는다 |
| 제목 수정 | 지정한 항목만 바뀌고 기존 ID를 유지한다 |
| 완료 전환 | 완료와 미완료를 오갈 수 있다 |
| 항목 삭제 | 선택한 ID의 항목만 삭제한다 |
| 목록 필터 | 전체·진행 중·완료를 선택할 수 있다 |
| 새로고침 후 복원 | 저장된 제목과 완료 상태가 유지된다 |
| 빈 목록 | 현재 필터에 해당하는 항목이 없다는 안내가 나온다 |
| 저장 실패 | 저장에 실패했는데 성공한 것처럼 안내하지 않는다 |
필터는 이번 실습에서 화면 상태로만 둔다. 새로고침하면 전체 목록으로 돌아와도 된다. 이렇게 정해 두면 “데이터가 유지된다”와 “모든 화면 상태가 유지된다”를 혼동하지 않는다.
첫 요청에 붙일 작업 명세
개인용 Todo 앱을 만든다.
기본 구성:
- React + TypeScript + Vite
- 기존 프로젝트가 있으면 현재 구성을 먼저 확인하고 유지
- localStorage에 할 일을 저장
- 로그인, 서버, 기기 간 동기화는 제외
기능:
- 추가, 제목 수정, 완료 전환, 삭제
- 전체 / 진행 중 / 완료 필터
- 새로고침 후 데이터 복원
규칙:
- 제목은 앞뒤 공백 제거 후 1~100자
- 항목의 식별자는 생성 시 한 번 만든 고유 ID
- 목록 필터는 새로고침 시 전체로 초기화해도 됨
- 저장 실패를 사용자가 알 수 있어야 함
이번 작업은 로컬 구현과 검증까지다.
PR 생성, 원격 푸시, 배포는 포함하지 않는다.
pstack의 Feature playbook에는 PR을 여는 단계도 포함되어 있다. 로컬 실습만 할 때는 위처럼 작업 경계를 명시하는 편이 좋다.
2. Claude Code에 설치하고 작업 시작하기
작업할 저장소를 Claude Code로 연 다음 대화창에 입력한다. 아래 명령은 터미널 셸 명령이 아니다.
/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins
/pstack:setup-pstack
setup-pstack은 현재 환경에서 사용할 모델과 추론 수준을 확인하고 역할별 설정을 작성한다. Claude Code용 설정 파일은 ~/.claude/rules/pstack-models.md다.
Cursor에서 진행한다면 설치 명령은 /add-plugin pstack이고, 이후 명령의 pstack: 접두사를 뺀다. 예를 들어 /pstack:poteto-mode는 /poteto-mode가 된다.
이제 앞에서 작성한 명세와 함께 다음을 요청한다.
/pstack:poteto-mode
위 명세의 Todo 앱을 개발하려고 한다.
먼저 현재 저장소와 실행 환경을 조사해줘.
확인할 내용:
- 기존 프레임워크와 의존성
- 앱 진입점, 상태 관리, 테스트 구성
- 실행 명령과 빌드 명령
- Todo 기능과 연결할 기존 코드가 있는지
빈 저장소라면 그 사실을 확인하고 최소 구성을 제안해줘.
아직 파일을 수정하지 말고 조사 결과와 설계안을 먼저 보여줘.
내가 설계를 확인하면 구현을 시작한다.
pstack은 기본적으로 매 단계마다 사람의 승인을 기다리는 방식이 아니다. 이 실습에서는 설계를 읽어 보기 위해 사전 확인을 명시했다.
3. how로 현재 구조를 확인한다
how는 코드베이스의 구조와 실행 흐름을 조사하는 스킬이다. poteto-mode가 필요한 단계에서 사용하도록 둘 수도 있고, 조사만 하고 싶다면 직접 호출할 수도 있다.
/pstack:how
현재 앱에서 사용자 입력이 화면 상태로 반영되는 흐름을 설명해줘.
Todo 기능을 넣을 위치를 판단할 수 있도록
진입점, 컴포넌트 책임, 저장 코드, 테스트 경로를 짚어줘.
코드를 수정하지 말고 실제 파일을 근거로 설명해줘.
없는 구성은 없다고 표시해줘.
새 저장소에서 기존 상태 관리 코드를 찾을 수 없는 것은 정상이다. 이때 필요한 결과는 존재하지 않는 구조에 대한 설명이 아니라, 무엇부터 만들어야 하는지 판단할 근거다.
조사 결과를 읽을 때는 파일 개수보다 책임의 위치를 본다. 상태를 바꾸는 함수가 여러 화면에 흩어져 있는지, 저장 처리를 한곳에 모을 수 있는지 정도면 작은 Todo 앱의 첫 설계에 충분하다.
4. architect로 데이터와 변경 규칙을 정한다
화면을 구현하기 전에 할 일 하나의 형태와 변경 규칙을 정한다. 이 글에서 제안하는 최소 타입은 다음과 같다.
type Todo = {
id: string;
title: string;
completed: boolean;
};
type TodoFilter = "all" | "active" | "completed";
type StoredTodos = {
version: 1;
items: Todo[];
};
active는 별도로 저장하는 상태가 아니라 completed === false인 항목을 보여 주는 필터다. 전체 목록과 진행 중 목록을 각각 저장하면 둘이 어긋날 수 있으므로, 원본 배열에서 화면에 보일 항목을 계산한다.
저장 데이터에 version을 두는 이유는 나중에 형식을 바꿀 때 구분하기 위해서다. 숫자 하나를 붙였다고 마이그레이션이 구현되는 것은 아니다. 이번에는 지원하지 않는 버전을 만나면 어떻게 안내하고 복구할지까지 설계에서 결정한다.
/pstack:architect
Todo 앱의 데이터 구조와 변경 경계를 설계해줘.
검토할 내용:
- Todo, TodoFilter, 저장 데이터 형식
- 추가 / 수정 / 완료 전환 / 삭제의 입력과 결과
- 필터는 원본 목록에서 계산
- localStorage 읽기와 쓰기를 분리할 위치
- 잘못된 JSON, 잘못된 데이터 구조, 지원하지 않는 버전 처리
- 쓰기 실패 시 화면 상태와 저장 상태를 일치시키는 방법
작은 앱에 맞는 구조를 제안해줘.
공개 함수나 모듈 뼈대 수준으로 설명하고 구현은 기다려줘.
이 실습에서는 저장에 성공한 뒤 화면 상태를 확정하는 방식을 선택할 수 있다. 저장에 실패하면 기존 목록을 유지하고 오류를 보여 준다. 입력 중이던 제목은 보존해 다시 시도할 수 있게 한다.
이것은 pstack이 지정한 정답이 아니라 이 예제의 설계 선택이다. 에이전트가 다른 방식을 제안한다면 실패했을 때 화면에 무엇이 남는지까지 비교하면 된다.
arena는 언제 쓰나
모듈 경계나 오류 처리에 서로 다른 설계가 실제로 경쟁할 때 arena로 대안을 비교할 수 있다.
/pstack:arena
Todo 앱의 상태 변경과 저장 실패 처리를 설계해줘.
공통 조건:
- localStorage 사용
- 저장 실패 시 기존 목록 유지
- 입력 중인 제목 보존
- 실패 처리를 테스트할 수 있어야 함
같은 조건으로 서로 다른 설계 후보를 비교해줘.
최종 결과는 선택한 구조와 선택 이유로 정리해줘.
아직 제품 코드는 수정하지 말아줘.
후보를 늘리면 호출량과 검토할 내용도 늘어난다. 다만 분석한 버전의 Feature playbook은 구현에 여러 유효한 형태가 있을 때 arena를 사용하도록 규정한다. 따라서 직접 명령을 입력하지 않아도 poteto-mode의 절차에서 호출될 수 있다.
5. 구현은 한 기능씩 확인할 수 있게 나눈다
설계를 검토했다면 구현을 승인한다. 작은 Todo 앱에서 UI, 상태, 저장 코드를 여러 작업자가 동시에 수정하면 공유 파일 충돌이 더 커질 수 있다.
Feature playbook은 먼저 선행 작업, 독립 작업, 공유 상태, 가장 작은 안전한 분할을 검토한다. 이 예제에서는 하나의 구현 담당자가 코드 변경을 맡고, 검토와 검증을 분리하는 구성이 이해하기 쉽다.
| 구현 단위 | 이번 단계에서 확인할 내용 |
|---|---|
| 데이터와 저장 경계 | 입력 검증, 읽기·쓰기 실패 처리 |
| 추가와 목록 표시 | 첫 항목 생성, 빈 제목 거부 |
| 수정·완료·삭제 | ID 기준으로 정확한 항목 변경 |
| 필터와 빈 상태 | 원본 목록에서 표시 항목 계산 |
| 새로고침과 오류 안내 | 저장 복원, 실패 시 사용자 안내 |
/pstack:poteto-mode
설계안을 승인한다. 앞서 정한 Todo 명세로 구현해줘.
진행 방식:
- 먼저 선행 작업, 공유 파일, 작업 분할을 짧게 정리
- 작은 앱이므로 코드 구현은 한 담당자가 맡는 구성을 우선 검토
- 기능 단위로 구현하고 확인한 다음 다음 단계로 이동
- 기존 프로젝트의 스타일과 테스트 도구를 우선 사용
이번에 선택한 저장 정책:
- 저장에 성공한 뒤 화면 목록을 확정
- 저장 실패 시 기존 목록 유지
- 입력 중인 제목은 보존
- 오류 메시지 표시
완료 시 변경 파일, 실행한 검사, 남은 문제를 보고해줘.
PR 생성, 원격 푸시, 배포는 하지 말아줘.
이 요청에서 중요한 부분은 기능 이름보다 실패 정책이다. “오류 처리도 해줘”보다 “저장 실패 시 기존 목록을 유지하고 입력은 남겨줘”가 구현과 검증 양쪽에서 확인하기 쉽다.
6. 테스트는 상태 규칙과 실제 사용 경로를 나눈다
Todo 앱의 테스트는 함수 이름을 그대로 따라 만드는 것보다, 잘못되면 사용자가 곤란해질 동작을 확인하는 편이 낫다.
| 검증할 동작 | 확인 방법 |
|---|---|
| 공백뿐인 제목을 저장하지 않음 | 제목 검증 로직이나 입력 화면에서 확인 |
| 완료 필터에서 수정해도 같은 ID만 변경 | 필터 상태에서 항목을 수정하고 전체 목록과 대조 |
| 삭제가 다른 항목에 영향을 주지 않음 | 항목 여러 개를 만들고 하나만 삭제 |
| 저장 실패 후 목록이 바뀌지 않음 | 저장 경계에 실패를 주입해 확인 |
| 잘못된 저장 데이터에서 앱이 멈추지 않음 | 별도 테스트 환경에 손상 데이터를 넣고 확인 |
| 새로고침 후 복원 | 실제 브라우저에서 저장 후 새로고침 |
TypeScript 타입은 localStorage에서 읽은 JSON이 올바른지 보장하지 않는다. 배열인지, 각 항목에 올바른 ID·제목·완료 값이 있는지 실행 중 검사해야 한다.
손상된 데이터는 빈 배열로 덮어써 버리기 전에 사용자에게 알리는 정책을 둘 수 있다. 이 실습에서는 원문을 보존하고 오류를 표시한 뒤, 명시적인 초기화 동작으로만 지우도록 정한다. 테스트에는 실제 개인 데이터가 없는 별도의 브라우저 프로필이나 격리된 저장소를 사용한다.
프로젝트 전용 검증 스킬 만들기
/pstack:create-verification-skill
Todo 앱의 실제 사용자 동작을 검증하는 스킬을 만들어줘.
포함할 경로:
1. 빈 목록에서 제목이 있는 할 일 추가
2. 제목 앞뒤 공백 처리와 빈 제목 거부
3. 항목 두 개 중 하나만 완료 처리
4. 완료 필터에서 제목 수정
5. 전체 필터에서 원래 ID의 변경 확인
6. 새로고침 후 제목과 완료 상태 복원
7. 항목 하나만 삭제
저장 실패와 손상 데이터는 별도의 격리 환경에서 검증해줘.
손상 데이터는 자동으로 덮어쓰지 않는 정책을 확인해줘.
실행 명령, 준비 상태 확인, 사용자 조작,
성공 조건, 증거 위치, 정리 절차를 남겨줘.
작성한 절차로 기능 하나 이상을 실제 실행해줘.
실행할 수 없는 단계는 이유와 함께 미검증으로 표시해줘.
Claude Code 어댑터를 따르면 프로젝트 스킬은 .claude/skills/ 아래에 생성된다. 실행하지 않은 검증 문서는 아직 초안이다. 브라우저를 조작할 도구가 없다면 UI 확인은 미검증으로 남겨야 한다.
7. 버그가 나오면 재현 조건을 다음 요청에 넘긴다
완료 필터에서 두 번째 항목을 수정했는데 첫 번째 항목이 바뀌었다고 가정해 보자. 배열의 현재 위치를 항목 식별자로 사용했을 때 의심할 수 있는 문제다. 실제 원인은 코드를 확인하기 전까지 단정하지 않는다.
/pstack:poteto-mode
Todo 앱에서 다음 문제를 조사하고 수정해줘.
재현:
1. A, B, C 세 항목을 만든다.
2. B와 C를 완료 상태로 바꾼다.
3. 완료 필터를 연다.
4. 화면의 두 번째 항목 C의 제목을 수정한다.
관찰한 결과:
다른 항목의 제목이 바뀐다.
기대 결과:
C의 ID에 해당하는 항목만 바뀐다.
우선 동일 경로에서 재현해줘.
표시 배열의 위치와 원본 ID를 혼동했는지 확인하되
그것을 원인으로 미리 단정하지 말아줘.
수정 후 같은 경로와 새로고침 후 복원까지 확인해줘.
위 증상은 설명을 위해 만든 가상 사례다. 실제 작업에서는 자신이 관찰한 결과와 재현 조건으로 바꿔야 한다.
pstack의 Bug fix playbook은 재현과 실행 증거를 중심으로 진행한다. 수정한 함수가 그럴듯해 보이는 것과 사용자가 겪은 문제가 사라진 것은 따로 확인한다.
8. interrogate로 마지막 변경을 검토한다
기능 검증을 마쳤다면 현재 diff에 대한 독립적인 검토를 요청할 수 있다. interrogate는 지적을 분류하는 단계이며, 자동 수정까지 맡기는 명령은 아니다.
/pstack:interrogate
현재 Todo 앱 변경을 검토해줘.
변경 목적:
개인용 Todo의 추가, 수정, 완료 전환, 삭제,
필터, localStorage 저장을 제공한다.
중점:
- 필터된 목록에서도 ID 기준으로 수정되는지
- 저장 실패 시 화면과 저장 데이터가 어긋나지 않는지
- JSON 파싱 이후 구조 검증이 있는지
- 손상 데이터를 자동으로 덮어쓰지 않는지
- 모바일에서 입력과 버튼을 조작할 수 있는지
- 키보드로 주요 기능을 사용할 수 있는지
근거와 함께 지적을 분류해줘.
정적 검토로 확인한 것과 실제 실행한 것을 구분해줘.
이번 단계에서는 코드를 수정하지 말아줘.
받아들일 지적을 정한 뒤 수정하고, 영향받은 경로를 다시 확인한다. 리뷰 이후 변경한 코드에 대해 이전 테스트 결과만 제시하면 최종 결과의 증거가 되지 않는다.
9. 완료 보고는 이 정도면 판단할 수 있다
에이전트에게 긴 작업 일지보다 완료 조건별 결과를 요청한다.
최종 결과를 아래 항목으로 정리해줘.
- 구현한 기능과 제외한 기능
- 완료 조건별 통과 / 실패 / 미검증
- 검사 대상 커밋 또는 변경 상태
- 실제 실행한 명령과 사용자 경로
- 확인 가능한 증거 파일
- 남아 있는 제한과 다음 작업
실행하지 않은 테스트를 통과로 적지 말아줘.
예를 들어 빌드가 통과했지만 브라우저를 열 수 없었다면, “빌드 통과, 사용자 경로 미검증”이 맞는 보고다. 테스트 수가 많더라도 새로고침 후 복원 경로를 확인하지 않았다면 해당 완료 조건은 남아 있다.
이 Todo 앱의 다음 확장으로 기기 간 동기화를 넣는다면 저장 구조와 사용자별 데이터 접근 범위가 바뀐다. 그때는 기존 검증 스킬을 유지하면서 how로 현재 저장 흐름을 다시 읽고, architect로 서버 저장과 인증 경계를 설계하는 작업부터 시작하면 된다.