작은 대시보드로 떠난 두 번째 항해 — Spec Kit으로 소개 문장의 기준을 찾았습니다

소개

안녕하세요. 부동산 하는 도시아재입니다. 저는 실무 경험이 없는 초보 공인중개사로서, AI 실무자동화 수업에 들어가기 전 작은 결과를 직접 만들어 보며 AI와 친해질 수 있는 개인용 14일 미션 대시보드를 만들고 있습니다.

1주차에는 첫 미션의 다짐을 이미지로 만드는 장면에서 출발해 14일 대시보드까지 키웠습니다. 2주차에는 새 배를 만들지 않았습니다. 이미 띄운 배의 나침반을 점검하듯, 2일차 ‘나를 소개하는 한 줄’이 정말 제 입력을 따라가는지 다시 살폈습니다.

이번 글은 완성품 소개보다 그 항해의 기록입니다. 길이만 맞고 문장 끝이 잘린 후보를 만났고, 기준을 고쳐 다시 확인했습니다. 중간에 제가 직접 결정해야 할 일도 있었습니다.

사진 1. 1주차에 만든 14일 대시보드의 당시 화면입니다. 입력 원문을 가린 과거 캡처이며, 지금 배포된 2주차 버전의 화면 증거로 쓰지 않습니다.

두 번의 항해를 한눈에 보면

살핀 것

1주차: 배를 띄우기

2주차: 항로를 고치기

목표

초보 공인중개사가 하루 한 가지씩 AI를 연습할 14일 개인용 대시보드

같은 앱의 2일차 소개 후보가 입력에 충실하고 완결된 문장이 되게 하기

시작점

다짐 입력 → AI 이미지 한 장의 첫 장면, 이후 14일로 확장

이미 작동하는 앱과 1주차 PRD를 그대로 기준으로 사용

문서

만들 대상과 사용 장면을 PRD에 정리

별도 연습 폴더로 순서를 익힌 뒤 기준 명세·Day 2 개선 명세·계획·작업 목록을 작성

확인한 결과

첫 이미지 미션의 사용자 직접 평가, 앱의 입력·결과·저장 동작

자동 검사 64개 통과, 실제 후보 9개에 대한 사용자 직접 판정, 기존 주소에 개선판 공개

남은 숙제

실제 수강생이 14일을 어떻게 쓰는지

처음 쓰는 사람이 2일차를 5분 안에 마치는지와 문장을 쉽게 이해하는지

이 표의 ‘1주차’와 ‘2주차’는 앱 안의 1~14일 미션 번호가 아니라 제작 교안의 주차입니다. 14일 앱을 다 사용했다는 뜻도 아닙니다.

진행 방법

1. 출발 전, 빈 연습 섬에서 지도를 읽었습니다

Spec Kit은 AI에게 일을 맡기기 전에 목적과 기준을 문서로 남기도록 돕는 도구입니다. 모험에 비유하면 prd.md는 어디로 갈지, constitution.md는 여행 중 지킬 규칙, spec.md는 도착했다고 판정할 조건, plan.md는 갈 길과 장비, tasks.md는 오늘부터 밟을 순서입니다.

먼저 별도의 speckit-practice 폴더에서 교안과 같은 ‘프롬프트 모음집’을 연습 주제로 삼아 이 다섯 문서의 역할을 익혔습니다. 이미 만든 1주차 앱이나 학습허브를 그 폴더 안에 옮기지 않았습니다. 연습용 지도와 실제 항해 기록이 섞이면 무엇을 비교하는지 알기 어려워지기 때문입니다.

그다음 실제 14일 앱의 기존 동작을 기준 명세로 남겼습니다. 1주차에 쓴 docs/prd.md는 당시의 생각을 보여주는 기록이어서 덮어쓰지 않았습니다. 이번에 고칠 범위도 ‘앱 전체’가 아니라 2일차 소개 문장 하나로 좁혔습니다.

2. 첫 번째 섬은 ‘그럴듯한 문장’이었습니다

1주차에는 사용자가 누구를, 어떤 방식으로 돕고 싶은지 떠올리도록 2일차 입력 화면에 조언을 더했습니다. 하지만 조언이 있다는 사실과 AI가 그 입력에 맞는 문장을 낸다는 사실은 다릅니다. 이번에는 그 사이를 직접 확인하기로 했습니다.

사진 2. 1주차에 추가한 2일차 조언 화면입니다. ‘누구를, 어디에 집중해, 어떻게 도울까’를 적도록 안내합니다. 결과가 나오기 전 화면입니다.

좋은 소개 후보의 조건을 구체적으로 적었습니다. 사용자가 입력한 태도 두 가지, 돕고 싶은 고객 또는 분야, 실제로 도울 방법이 보여야 합니다. 입력하지 않은 지역·경력·실적을 만들어서는 안 됩니다. 후보는 세 개이고, 각각 공백 포함 35~55자의 끝까지 읽히는 1인칭 다짐이어야 합니다.

AI에게는 이런 방향으로 요청했습니다. 아래는 당시 명세와 작업 지시를 독자가 다시 써볼 수 있게 묶은 정리한 프롬프트이며, 한 번 입력한 원문 그대로라고 주장하지 않습니다.

기존 앱의 2일차 소개 후보만 개선해줘.
입력한 태도 두 가지와 업무 대상·방법을 반영하고,
입력하지 않은 지역·경력·실적은 만들지 마.
후보 세 개는 각각 35~55자의 완결된 1인칭 다짐으로 써줘.
기존 선택·수정·확인·저장 흐름은 유지해줘.

이 요청의 핵심은 ‘멋진 표현’이 아니라 입력에 근거한 표현입니다. AI가 대신 경력을 꾸며 주면 더 근사해 보일 수는 있어도 제 소개는 아니니까요.

3. 길이는 맞았는데, 문장이 바다 한가운데서 멈췄습니다

첫 실제 생성에서 두 후보가 설명하겠습, 안내하로 끝났습니다. 글자 수는 범위 안이었지만 사람에게 보여 줄 완결된 문장은 아니었습니다. 숫자만 통과하면 된다고 여겼던 기준의 빈틈이 드러났습니다.

그래서 문장 끝맺음을 품질 조건에 추가하고, 입력에 없는 사실을 보태지 않는 검사도 보강했습니다. 중간 재시도 한 번은 기준을 다시 통과하지 못해 앱이 결과 표시를 보류했습니다. 이때의 422를 성공으로 포장하지 않고 실패 기록에 남긴 뒤 다시 확인했습니다.

모험 영화라면 암초가 나왔다고 지도를 버리지 않습니다. 암초의 위치를 지도에 적어야 다음 항해가 안전해집니다. 이번에는 실제 실패가 spec.md와 검사 조건을 고치는 이유가 됐습니다.

4. 다시 항로를 정하고, 마지막 선택은 제가 했습니다

작업은 T001~T016으로 나눠 한 단계씩 확인했습니다. 후보의 길이와 차이를 검사하고, 없는 사실·과장 표현을 걸러 내고, 빈 입력과 800자 초과 입력은 생성 전에 멈추게 했습니다. 이후 후보 선택, 직접 수정, 확인 항목, 완료 기록과 새로고침 복원이 그대로 되는지 살폈습니다.

자동 검사 64개가 모두 통과했고 Sites 빌드와 비공개 파일 제외 검사도 끝냈습니다. 자동 검사는 길이·저장·오류 처리 같은 동작을 확인합니다. ‘이 문장이 내가 되고 싶은 공인중개사를 제대로 말하는가’는 숫자가 대신 판정하지 못합니다.

실제 입력 세 세트에서 나온 후보 9개는 제가 직접 읽고 태도·업무 반영과 자연스러움을 확인해 “통과로 본다”고 판단했습니다. 선택한 최종 소개에도 입력하지 않은 사실을 지울 필요가 없다고 확인했습니다.

사진 3. 2주차에 실제로 본 2일차 후보와 최종 소개 입력 화면입니다. 후보를 읽고 고르거나 직접 고칠 수 있습니다. 사진 속 문장 품질은 위의 사용자 판정과 구분해 보아 주세요.

5. 항구에 도착해도, 다른 여행자의 짐은 저절로 옮겨지지 않습니다

앱은 방문자 각자의 브라우저에 학습 기록을 저장합니다. AI 생성에는 방문자가 자신의 OpenAI API 키를 입력하며, 생성 비용은 그 키의 계정에서 발생할 수 있습니다. 이번에는 로그인이나 서버 저장, 기기 간 동기화를 만들지 않았습니다.

처음에는 배포 문서의 ‘소유자 전용’ 설명과 실제 공개 설정이 달라 접근 범위를 바로잡았습니다. 이후 공개 체험용으로 배포하자는 결정을 내리고, Day 2 개선판을 기존 주소의 버전 3으로 올렸습니다. Windows에서 배포 포장 경로 오류가 있었지만 Git Bash 경로 방식으로 같은 소스를 포장했습니다.

공개 화면과 14개 미션 목록, 변경 파일, 키 없는 생성 차단, 비공개 문서 경로의 차단을 확인했습니다. 새 공개 주소의 브라우저에는 기록이 0/14로 보였고, 이전 로컬 주소의 2/14 기록은 그대로 남았습니다. 주소마다 브라우저 저장 공간이 달라 자동 이전되지 않는 것입니다.

사진 4-1. 390px 폭에서 입력 항목과 AI 생성 버튼이 화면 밖으로 넘치지 않는지 확인했습니다.

사진 4-2. 모의 응답으로 후보 세 개와 최종 소개 입력 영역이 작은 화면에서도 읽히는지 확인했습니다.

사진 4-3. 확인 항목 두 개와 완료 버튼의 모바일 배치를 확인했습니다. 화면 속 문장은 실제 AI 품질의 증거가 아닌 동작 검사용 모의 응답입니다.

공개 앱: 초보 공인중개사를 위한 14일 AI 학습 챌린지

결과와 배운 점

이번 항해에서 Spec Kit은 마법 지도가 아니었습니다. 문서에 적힌 기준이 실제 입력과 결과를 만날 때 어디가 비어 있는지 보여 주는 고쳐 쓸 수 있는 지도에 가까웠습니다. 저는 이번에 ‘명세 → 계획 → 작업 → 검증 → 명세 수정’의 한 바퀴를 돌렸고, 다음 개선을 처음부터 다시 설명하지 않고 시작할 수 있다고 직접 판단했습니다.

Codex에는 문서 정리, 좁은 코드 변경, 검사와 배포 확인을 맡겼습니다. 어떤 소개가 제 태도와 업무를 정직하게 말하는지, 또 다음 단계로 가도 되는지는 제가 판단했습니다. 이 경계가 흐려지면 검사 통과 숫자가 사람의 만족을 대신하는 실수를 하기 쉽습니다.

아직 남은 질문도 있습니다. 처음 쓰는 사람이 2일차를 5분 안에 마치는지, 문장을 쉽게 이해하는지, 다른 입력과 모델에서도 같은 품질이 나오는지는 확인하지 못했습니다. 에이전트가 빠르게 조작한 시간은 사람의 사용 시간으로 세지 않았습니다. 3주차에는 실제 사용자에게 앱을 맡겨 이 부분을 살펴보려 합니다.

처음 시작하시는 분께 제가 권하고 싶은 순서는 세 가지입니다. 이미 있는 결과를 먼저 열어 보고, 고칠 부분을 한 가지로 좁히고, 성공 기준을 사람이 직접 판정할 문장으로 적어 보세요. 저는 그 순서 덕분에 잘린 어미라는 작은 문제를 놓치지 않았습니다.

함께 볼 자료

아래 자료는 이번 실습에서 따른 교안과, 글을 정리하며 확인한 공식 안내를 구분해 적었습니다. 최신 설치·명령·요금 정보는 링크를 여는 시점에 다시 확인해 주세요.

결과물과 지난 이야기 — 공개 대시보드에서 앱을 열 수 있습니다. 1주차 사례글에는 첫 장면에서 14일 대시보드로 확장한 과정이 있습니다.
실습 교안 — 아루나님의 1주차 교안 시작과 2주차 라이브 교안을 참고했습니다. 2주차 페이지 오른쪽의 참고자료 13~19에는 날짜별 실습이 있습니다.
Spec Kit을 처음 볼 때 — Spec Kit GitHub 저장소는 도구의 전체 소개, 공식 Quickstart는 문서에서 작업으로 가는 순서를 보여 줍니다. 기존 프로젝트 적용 안내는 이미 만든 앱에서 한 가지 개선을 시작할 때 참고했습니다. 공식 안내의 예시 명령은 제 Windows 환경과 이번 교안의 설치 지시와 다를 수 있어 그대로 다시 실행하지 않았습니다.

📢 AI스터디는 24기를 끝으로 방학에 들어가요