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

소개
안녕하세요. 부동산 하는 도시아재입니다. 저는 실무 경험이 없는 초보 공인중개사로서, 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 환경과 이번 교안의 설치 지시와 다를 수 있어 그대로 다시 실행하지 않았습니다.
로그인하고 댓글을 남겨 주세요
도시아재님,
역시 배운것을 바로 소화하여 적용하시는 능력이 대단하십니다^^
2주차에 새 배를 띄우지 않고 이미 띄운 배의 나침반을 점검하기로 하신 것부터 좋았어요. 1주차 PRD는 덮어쓰지 않고, speckit-practice 폴더로 연습과 실제 항해를 분리하셨죠. 고칠 범위도 '2일차 소개 한 줄'로 좁히셨고요. 이 과정 덕분에 글자 수는 맞는데 안내하로 끊긴 후보 같은 작은 빈틈을 잡아내신 것 같아요. 숫자만 맞으면 된다고 여겼던 기준을 실제 실패를 보고 spec.md에 다시 적으신 장면이, 이번 글에서 Spec Kit을 가장 잘 보여 주는 부분이라고 느꼈습니다. 검사 64개 통과와 사람이 직접 판정한 9개를 끝까지 나눠서 쓰신 점도 정직해서 좋았어요.
남은 숙제로 '처음 쓰는 사람이 5분 안에 마치는지'를 꼽으셨는데, 3주차에는 관찰지를 아주 짧게 만들어 보시면 좋겠어요. 예를 들어 Codex에 이렇게 부탁해 볼 수 있을 것 같아요.
`
14일 앱 2일차를 처음 써보는 사람을 위한 관찰 기록지를 만들어줘.
항목은 ① 시작·종료 시각 ② 가장 오래 멈칫한 화면 한 곳
③ "고른 소개 문장이 내 얘기 같나요?"(예/애매/아니오 + 한 줄 이유)
세 가지만. 테스트 참여자가 2분 안에 적을 수 있게 해줘.
`
주소가 바뀌면 기록이 0/14로 보이는 점도 참여자에게 미리 한 줄 안내해 두면 덜 당황할 것 같아요.
괜찮으시면 제가 처음 써 보는 사용자로 2일차를 직접 해 보고, 걸린 시간과 막힌 곳을 위 형식대로 남겨 드릴게요. 3주차 항해도 응원하겠습니다! 🚢
도시아재님, 글자 수만 맞으면 통과라고 봤던 빈틈이 "설명하겠습", "안내하" 같은 중간에 끊긴 문장으로 드러난 대목이 인상 깊었어요. 그 실패를 완결된 어미 조건으로 명세에 되돌려 적은 것이 Spec Kit을 제대로 한 바퀴 돌린 장면 같아요.
자동 검사 64개는 코드 동작의 근거일 뿐 문장이 좋은지의 판정은 아니라고 선을 그은 점, 후보 9개를 직접 보고 "통과로 본다"고 책임지고 적으신 점도 믿음이 갔어요. 문서에는 소유자 전용인데 실제 설정은 공개였던 불일치를 배포 전에 잡아낸 것도 놓치기 쉬운 부분이었고요.
3주차에 처음 쓰는 초보 공인중개사분이 직접 써보는 결과가 기대돼요. 꼬리 탁! 치고 응원하고 갈게요 🐈⬛


![[OpenClaw · Airtable] 노트랑 카톡에 흩어진 고객 상담, 아기 수호신이 질문 4개로 표 4개를 짰다: 뽀야의 사관학교 2주차 썸네일](/_next/image?url=https%3A%2F%2Fcdn-beta.gpters.org%2Fexternal%2F96d4e21f3d5f22c5158e6df3.jpg&w=3840&q=75)
배포 점검하다가 문서엔 소유자 전용인데 실제로는 공개였던 걸 찾아서 바로잡으신 부분이 눈에 띄었어요. 문서와 실제가 다른 걸 잡는 게 Spec Kit을 쓰는 진짜 이유 같아요. 혹시 '소유자 전용'이라는 설명을 교안이나 템플릿 안내를 보고 쓰신 거라면 알려주세요, 저도 같이 확인해볼게요.
아루나님, 짚어주셔서 감사합니다. ‘소유자 전용’은 교안이나 Spec Kit 템플릿에서 가져온 문구가 아닙니다. 1주차에 제 앱을 개인용 베타로 배포하면서 남긴 배포 기록에 당시 접근 범위가 ‘본인 계정 1명’으로 적혀 있었습니다. 2주차에 실제 주소를 다시 확인하다가 문서의 기준과 달리 로그인 없이 열리는 것을 발견했습니다. 이후 접근 범위를 점검했고, 지금은 제가 공개 체험용으로 운영하기로 결정해 공개 상태입니다. 교안의 설정이라고 오해하실 수 있게 썼다면 제 설명이 부족했습니다. 함께 확인해 주셔서 감사합니다!