한 사람을 위한 앱: Devpost 스킬 팩으로 그래도 명세서를 만든 이유

AI 요약

Cuenta는 캘리포니아 산타바버라의 도매 제과점 La Condesa Baking Company를 위해 만든 앱입니다. 제과점 주인은 카페 네 곳의 진열대에 남은 제품을 종이 수첩에 세고, 납품 수량과 청구 금액을 손으로 계산했으며, 미수금도 기억에 의존해 관리했습니다. 수첩을 잃어버린 일을 계기로 만든 앱은 휴대전화에서 카페별 재고를 기록하고, 납품 내역을 입력하고, 브랜드 양식의 청구서를 출력하거나 이메일로 보내고, 미수금과 납부 상태를 확인하는 흐름을 제공합니다. 재고 집계는 무엇을 구울지 계획하는 용도이며 청구서에 직접 반영하지 않습니다.

계획을 먼저 세운 이유

개발자는 Devpost의 Build With AI: Basics 해커톤에 참가해 Devpost Learn 스킬 팩을 Claude Code에서 사용했습니다. 여섯 개의 지침 파일이 질문을 하나씩 던지고, 답변에 따라 범위, PRD, 구현 명세를 작성합니다. 다음 문서로 넘어가기 전에 각 계획을 승인하고, 승인 뒤에는 작업을 여덟 개의 작은 단계로 나눠 차례로 확인했습니다. 개발자는 계획 문서를 대화의 기억 대신 남겨두면 새 대화를 시작해도 작업을 이어갈 수 있었다고 설명합니다.

질문과 명세 작성 과정에서 몇 가지 위험을 코드 작성 전에 찾았습니다. 앱이 Vercel에서 UTC 시간으로 실행되면 산타바버라 저녁에 만든 청구서 날짜와 번호가 다음 날 기준으로 잡힐 수 있었습니다. 청구서마다 당시 가격을 복사해 저장하고 금액을 센트 단위 정수로 관리해 과거 청구서의 가격이 바뀌거나 반올림 차이가 생기는 문제도 막았습니다. 해커톤 시연 완료와 실제 사용 준비를 별도 목표로 나눴고, 재고 집계와 청구서 작성도 서로 다른 작업으로 정리했습니다. 제과점 주인에게 물을 질문은 처음 36개에서 여덟 개로 줄였습니다.

각 개발 단계의 보고서에는 계획에 없던 결정을 따로 적어 검토를 요청하는 항목이 있었습니다. 카페를 바꿀 때 입력 내용을 버릴지 묻는 확인창, 대비 검사를 통과하지 못한 브랜드 색상 대신 어두운 분홍색을 쓰는 결정, 기존 청구서의 카페를 잠그는 결정 등이 여기에 포함됐습니다. 운영 환경의 권한 검사 때문에 일반적인 방식으로 무효화 테스트를 할 수 없자 에이전트는 데이터베이스를 직접 고쳐 테스트를 통과시키지 않고, 실제 무효화 버튼을 통해 확인하도록 작업을 돌려줬습니다.

계획을 충실히 따라도 틀릴 수 있습니다

실제 사용 방식으로 앱을 시험하면서 큰 오류가 드러났습니다. 앱은 카페마다 별도의 제품 목록을 두도록 만들어졌지만, 제과점 주인은 모든 카페가 같은 메뉴에서 원하는 제품을 주문한다고 설명했습니다. 범위 문서와 PRD, 구현 명세가 모두 카페별 상시 목록을 전제로 했고, 코드와 종단 간 테스트도 그 계획을 충실히 따랐습니다. 오류의 출발점은 개발자가 샘플 청구서에서 카페마다 다른 제품을 본 뒤, 카페별로 주문 가능한 목록이 따로 있다고 추측한 데 있었습니다. 청구서는 그날 주문한 제품을 보여줄 뿐, 주문 가능한 제품의 범위를 증명하지 않았습니다. 개발자는 이 추측을 확정된 요구사항처럼 인터뷰에 가져왔고, 인터뷰 과정에서 확인하지 못했습니다.

제품을 모든 카페 목록에 추가하는 간단한 데이터 수정도 가능했지만, 개발자는 카페별 목록 테이블을 없애고 공통 메뉴를 쓰도록 명세와 코드까지 고치는 전체 수정을 택했습니다. 명세를 검증하는 테스트도 같은 명세를 토대로 작성하면 잘못된 가정을 함께 통과시킬 수 있다는 점이 이 사례에서 드러났습니다. 개발자는 요구사항을 계획에 적는 것만으로 검증이 끝나지 않으며, 실제 사용자가 실제 업무 흐름으로 앱을 써봐야 놓친 요구를 찾는다고 말합니다.

구현과 출시 준비

Cuenta는 약 20시간 동안 30회 커밋으로 만들었습니다. Next.js를 Vercel에 배포하고 Neon Postgres 데이터베이스와 Resend 이메일 서비스를 사용합니다. 실제 서비스에서는 PIN으로 접근을 제한하며, 초기 네 자리 PIN에는 추측 횟수 제한이 없다는 점을 확인한 뒤 PIN 길이를 늘리고 여러 차례 틀리면 잠그도록 바꿨습니다. 청구서는 삭제하지 않고 무효화하며, 초반 몇 주 동안 청구서 이메일은 카페가 아니라 제과점 주인의 받은편지함으로 보내 검토하게 합니다.

개발 과정에서 Google Stitch가 샘플 자료의 주소와 전화번호, 이메일을 화면 시안에 복사해 첫 커밋에 포함한 일도 있었습니다. 에이전트가 이를 찾아 커밋을 수정하고 외부에 푸시하기 전에 Git 기록에서도 지웠습니다. 서버에서 PDF를 만드는 헤드리스 브라우저에 글꼴이 없다는 문제는 구현 전 시간 제한 테스트로 발견했습니다. 앱은 아직 제품과 카페 정보를 직접 수정하거나 엑셀로 내보내는 기능, 연체 기간 보고서와 결제 알림을 제공하지 않습니다. 개발자는 현재 사용자가 한 명이고 구독료도 받지 않는다며, 여러 제과점에 맞춘 하나의 도구가 될지 여러 개의 맞춤 제작으로 남을지는 실제 사용을 거쳐 판단하려 합니다.

dev.to 반응

• @pengeszikra — 한 사람을 위해 직접 만든 프로그램에서도 솜씨와 시각적 간결함이 좋습니다. AI 시대의 좋은 점은 소규모 개발의 문턱이 낮아진 것이고, 나쁜 점은 예를 들면 이것입니다.
• @alexcodebytes — 계획이 잘못된 추측 하나를 끝까지 끌고 갔다는 점이 이 글에서 가장 가치 있습니다. AI 코딩 시연은 프롬프트에서 작동하는 앱으로 이어지는 성공 경로만 보여주고, 도메인에 관한 모델의 잘못된 가정이 알아차리기 전에 파일 열다섯 개에 반영되는 과정은 잘 보여주지 않습니다. 앱이 눈에 띄게 깨져서 잘못된 가정을 알아차렸나요, 아니면 결과는 맞아 보이는데 어딘가 이상하다고 느꼈나요? 두 번째가 더 무섭습니다. 조용히 맞지 않는 결과가 출시되는 경우니까요.
• @vladzoff — 제 댓글을 연결해줘서 고맙습니다. 만든 사람과 검사하는 사람을 분리해도 둘 다 명세에서 같은 잘못된 가정을 물려받으면 함께 틀릴 수 있다는 점이 경험에서 드러났습니다. 마지막 질문에는 실제 업무 흐름이 겹친다면 고객별 설정을 둔 예측 가능한 공통 제품 하나가 좋다고 답하겠습니다. 일반화하기 전에는 실제 사용자 몇 명에게 확인해야 합니다. E.의 작업 방식은 원래 계획만으로는 알 수 없던 종류의 근거였습니다.
• @pushpendra2011 — 가족의 가내 사업을 위한 웹사이트와 쇼핑몰을 만든 적이 있어서, 많은 일이 누군가의 머릿속에만 있다는 대목에 공감합니다. 저라면 하나의 도구를 만들겠습니다. 브랜드, 메뉴, 번호 체계, 거래 조건처럼 달라지는 부분은 코드가 아니라 설정으로 처리할 수 있습니다. 어려운 부분은 앱보다 초기 요구사항을 묻는 과정일 겁니다. "청구서는 주문 가능한 제품이 아니라 그날 주문한 제품을 보여준다"는 지적도 좋았습니다.
• @humam_moin — 아내가 쓸 방식 그대로 앱을 시험한 점이 좋았습니다. 코드가 제대로 작동해도 계획이 틀릴 수 있다는 대목이 특히 눈에 띄었습니다. 실제 사업을 위한 앱을 만들 때 실제 사용자 테스트가 중요한 이유를 보여줍니다. 저도 뭔가를 만들고 있습니다.
• @khunjua — 이런 일은 자주 일어납니다. 개발자의 주된 일은 구현만 확인하는 게 아니라 요구사항과 인수 기준도 검증하는 것 같습니다. OpenSpec을 사용해봤나요? 접근 방식이 Devpost 스킬 팩과 어떻게 다른지 궁금합니다.

원문: dev.to / 번역·요약: Trawling