앱 빌더은(는) 무엇을 하나요?
어떤 스택에서든 아이디어를 배포되고 테스트된 안전한 웹 앱으로 만드는 반복 가능한 방법입니다. 이 방법은 실제 프로젝트(AI 토론장: Next.js, Drizzle, Better Auth, Vercel, Turso, QStash, Vitest, Playwright)를 처음부터 끝까지 구축하면서 만든 모든 실수로부터 정제되었습니다. 핵심(이 파일, profiles/, reference/)은 스택에 독립적입니다. 특정 제품이나 프레임워크에 특화된 것은 stacks/에 있으며, 해당 프로젝트에서만 읽습니다. 이 방법을 따르십시오. 절차를 즉흥적으로 바꾸지 마십시오.
여기서 시작하세요 (매 세션)
- 프로젝트의 상태를 확인합니다.
docs/plan.md파일이 있으면 먼저 읽으십시오. 여기에는 프로필, 결정된 사항 및 현재 마일스톤이 기록되어 있습니다. 그곳에서 계속 진행하며, 이미 정해진 질문을 다시 묻지 마십시오. - 프로필을 선택합니다 (새 프로젝트만 해당). 일반 언어로 한 번만 물어보십시오:
"기술적 선택(코드, 호스팅, 데이터베이스)에 참여하시겠습니까, 아니면 제가 처리하고 앱의 기능과 디자인에 대해서만 질문해도 될까요?"
- 참여 →
profiles/technical.md를 읽습니다. - 비관여 →
profiles/guided.md를 읽습니다. 답변을docs/plan.md의 "How we work" 섹션에 기록합니다. 프로필은 질문하고 설명하는 방식을 결정합니다. 아래의 프로세스와 품질 기준은 동일합니다.
- 참여 →
- 프로젝트가 사용하는 스택 노트를 읽습니다 (아래 "스택 노트" 참조).
reference/process.md를 읽고 그 단계를 순서대로 따릅니다. 단계에서 가리킬 때 다른 참조 파일을 로드하고, 처음부터 모두 로드하지 마십시오.
스택 노트
stacks/ 디렉토리에는 기술별로 하나의 파일이 있습니다: 실제 프로젝트에서 배운 설정 단계, 함정 및 해결책이 포함되어 있습니다.
- 읽을 파일: 계획의 "How we work" 섹션에 나열되어 있습니다 ("스택 노트: nextjs, vercel, …"). 각 세션 시작 시 정확히 해당 파일들을 읽으십시오. 또한 프로젝트의 매니페스트(
package.json,vercel.json,docker-compose.yml…)와 사용자의 OS를 살펴보십시오. 사용자가 계획에 나열되지 않은 노트가 있는 무언가를 사용한다면, 해당 노트를 읽고 목록에 추가하십시오. 새 프로젝트는 스택이 결정될 때(프로세스 2단계) 자신의 노트를 선택합니다. - 놓치지 않도록: 프로젝트 지침 파일(
CLAUDE.md또는AGENTS.md)은 매 세션 시작 시docs/plan.md와 해당 스택 노트를 읽도록 지시합니다. 그렇지 않으면 이 스킬을 트리거하지 않는 세션은 목록을 보지 못합니다. 이 스킬은 저장소 외부에 있으므로, "app-builder 스킬이 설치된 경우에만" 스택 노트를 읽는다고 표현하여 우아하게 저하되도록 작성하십시오. - 새 서비스나 라이브러리를 도입하기 전에, 해당 노트가 존재하는지 확인하십시오.
- 새로운 교훈을 기록할 곳: 제품을 사용할 때만 적용된다면 해당 제품의 노트에 기록합니다(없으면
stacks/<product>.md를 생성하고 "다음의 경우 로드…"로 시작). 어디에나 적용된다면 제품을 예시로 사용하고 해당 제품의 노트를 가리키는 일반적인 용어로reference/에 기록합니다. 예: "원격 서비스가 유휴 연결을 끊을 때 한 번 재시도"는reference/lessons.md에 있고, 이를 수행하는 libSQL fetch 래퍼는stacks/turso-libsql.md에 있습니다. - 노트는 학습 시점의 날짜가 있는 사실(제한, 모델 목록, 가격)을 기록합니다. 필요할 때 다시 확인하십시오.
기존 프로젝트 감사
이미 존재하는 프로젝트에 이 스킬을 적용하라는 요청을 받으면(또는 큰 변경 후), 프로세스를 다시 시작하지 말고 감사 및 보고를 수행하십시오:
docs/plan.md를templates/plan.md와 비교하고 누락된 섹션을 나열합니다.reference/quality-gates.md를 섹션별로 살펴봅니다 (보안, 탄력성, 실제 측정 및 Lighthouse를 통한 성능, UI 체크리스트, 두 테마의 접근성, 운영 및 할당량).reference/lessons.md와 프로젝트의 스택 노트에 있는 안티패턴을 코드에서 검색합니다.- 프로젝트가 답하지 않은 시작 질문을 묻습니다 (예: 계정 수명 주기, 할당량 남용).
- 격차를 순위별로 보고합니다 (실제 격차, 계획 격차, 낮은 우선순위, 이미 잘된 점). 수정 사항을 포함합니다. 소유자가 거부하는 격차는 계획의 "수용된 위험" 테이블에 기록합니다. 소유자가 동의할 때까지 아무것도 변경하지 마십시오.
비협상 조건 (두 프로필 모두)
- 단계 및 마일스톤:
reference/process.md의 단계를 통해 작업하며, 각 마일스톤이 실행 가능하고, 테스트되고, 시연되고, 커밋된 후 다음 마일스톤으로 넘어가는 작은 마일스톤으로 구축합니다. 시작 시 사용자와 마일스톤 목록에 동의하고docs/plan.md에서 최신 상태를 유지하십시오. - 앱이 의도한 대로 작동: 모든 마일스톤은 실행 가능하고 실제 브라우저에서 시연되며 결과가 사용자에게 표시됩니다.
- 탄력성: 모든 외부 종속성 및 장기 실행 프로세스는 "실패하면 어떻게 할까?"에 대한 계획된 답변(다운, 느림, 속도 제한, 중간에 충돌, 두 번 전달)을 계획의 실패 모드 테이블에 기록하고, 코드에서 처리하며, 일반 언어로 사용자에게 표시되고, 테스트되어야 합니다.
- 성능: 합의된 목표(예: 대상 사용자 근처에서 1초 이내 페이지 응답)는 배포 후 측정됩니다. 명백히 비효율적인 작업(인덱싱되지 않은 쿼리, 불필요한 폴링, 과도한 페이로드)은 없어야 합니다.
- 품질: 각 마일스톤은
reference/quality-gates.md의 게이트(린트, 타입, 단위 테스트, 종단간 테스트, 빌드, CI, UI 검토 체크리스트)를 통과해야 합니다. 알려진 주요 결함은 열려 있어서는 안 됩니다. - 보안:
reference/quality-gates.md의 보안 체크리스트는 최종 점검이 아닌 모든 마일스톤에서 유지됩니다. - 유지보수 가능한 설계: 비즈니스 규칙은 단위 테스트가 있는 일반적이고 프레임워크에 의존하지 않는 모듈에 위치합니다. 외부 서비스는 작은 연결 지점(교체할 하나의 파일) 뒤에 있습니다. 계획과 README는 최신 상태를 유지합니다.
- 적절한 수준의 테스트: 규칙에 대한 단위 테스트, 사용자 흐름에 대한 종단간 브라우저 테스트, 유료 또는 느린 외부 서비스(AI 모델, 결제)에 대한 스크립트 기반 가짜 객체.
- 통제된 비용: 사용자의 예산은 계획에 명시됩니다. 비용이 발생할 수 있는 모든 항목에는 상한선, 카드가 연결되지 않은 무료 티어, 또는 사용자 자신의 키가 있어야 합니다.
- 비밀은 채팅을 통해 전달되지 않음: 사용자는
.env.local및 호스팅 대시보드에 직접 비밀을 넣거나, 마켓플레이스 통합이 주입합니다 (reference/third-party-setup.md참조). - 먼저 직접 확인: 변경 또는 배포 후, 보고하거나 사용자에게 살펴보라고 요청하기 전에 직접 결과를 확인하십시오(브라우저, 호스팅 플랫폼의 로그 및 CLI를 통한 배포 상태, 프로브 스크립트). 사용자에게는 사용자만 필요한 것(로그인, 비밀, 돈, 승인)에 대해서만 요청하십시오. 프로덕션을 직접 확인하는 것이 숨은 버그를 찾는 방법입니다.
- 정직한 보고: 무엇을 어떻게 확인했는지, 무엇을 확인하지 않았는지, 무엇이 실패했는지 말하십시오. 실행하지 않은 검사를 확인했다고 주장하지 마십시오.
- 변경되는 사실 확인: 가격, 무료 티어 한도, 라이브러리 API 및 버전은 의존하기 전에 현재 출처(
node_modules의 문서, 공식 페이지)와 비교하여 확인하고 출처를 인용하십시오.
이 스킬의 파일
| 파일 | 용도 |
|---|---|
profiles/technical.md | 기술적 소유자와 작업하는 방법: 무엇을 물어볼지, 무엇을 결정하고 알릴지 |
profiles/guided.md | 비기술적 소유자와 작업하는 방법: 언어, 선택, 클릭별 지침 |
reference/process.md | 시작부터 인계까지의 단계, 각 단계가 무엇을 산출해야 하는지 |
reference/quality-gates.md | 완료 정의, 테스트 전략, 탄력성, 성능, 보안 및 UI 검토 체크리스트 |
reference/stack-defaults.md | 기본 스택 및 아키텍처, 예산 티어, 이탈 시기 |
reference/environment.md | 대부분의 중단을 제거하는 사전 점검 및 권한 설정 |
reference/third-party-setup.md | 계정, 비밀 및 최소한의 수동 작업으로 호스팅/데이터베이스/큐 구성 |
reference/lessons.md | 이미 한 번 부딪힌 구체적인 함정과 그 해결책 (스택 독립적 용어). 각 마일스톤 전에 훑어보십시오 |
templates/plan.md | 프로젝트의 docs/plan.md를 위한 뼈대 |
스택 노트 (프로젝트가 사용할 때만 읽음):
| 파일 | 내용 |
|---|---|
stacks/nextjs.md | Next.js App Router, 캐시 컴포넌트, 프록시, 라우트 핸들러, 서버 액션, React 19 폼, 개발 서버 |
stacks/vercel.md | Vercel 호스팅: 리전, 환경 변수 및 재배포, CLI, 로그, 빌드 타임 설정 |
stacks/turso-libsql.md | Drizzle을 사용한 SQLite/libSQL, Turso: 설정, 마이그레이션, 원격 가져오기, 데드 유휴 연결 |
stacks/better-auth.md | Better Auth: 이메일 확인, 비밀번호 재설정, 계정 연결, 세션 함정 |
stacks/upstash-qstash.md | Upstash QStash: 로컬 개발 서버, 서명, 지연, 스케줄, 할당량 |
stacks/ai-providers.md | Vercel AI SDK, Groq, Google AI Studio, OpenRouter (연결 흐름, 무료 모델), Ollama |
stacks/gmail-smtp.md | 도메인 없이 Gmail을 통해 계정 이메일 보내기 |
stacks/playwright.md | Playwright 종단간 테스트: 선택자, 숨겨진 페이지, 로컬 가짜 객체 |
stacks/github.md | GitHub 저장소, Actions CI, GitHub 로그인 |
stacks/google-oauth.md | Google 로그인: Cloud 프로젝트, 동의 화면, 브랜딩, 로컬 및 프로덕션용 단일 클라이언트 |
stacks/windows.md | Windows에서 개발: Smart App Control, PowerShell, Docker, CLI |