Spec Kit으로 작은 개선의 명세부터 작업 목록까지 만들기
2026.10.14

코덱스(Codex)와 스펙킷(Spec Kit)으로 구매 분석 앱의 개선 명세를 만들었습니다. 2026년 10월 14일, 보완점 5개를 찾아 문서를 수정했고 기능 구현은 아직입니다.
구매 분석 앱의 수정 기준부터 정했다
앞서 ERP 구매 엑셀을 넣으면 당월과 누적 구매를 분석하고 Word 보고서를 만드는 작은 앱을 만들었습니다.
저는 지피터스 24기 AI놀이터 멤버 신정균이에요. 일반 회사 구매팀에서 일하고 있어요.
이번에는 그 앱을 고치기 전에 기준을 정리해 보고 싶었다. 기존에 무엇을 만들기로 했는지, 코드가 지금 무엇을 하는지, 다음 수정에서 어디까지 바꿀지를 문서로 연결하는 작업입니다. 스펙킷은 이번에 처음 사용했어요.
처음 코덱스에 보낸 요청은 짧았습니다.
speckit 초기화해줘. 요 폴더에서 작업할거야
초기화 뒤 현재 상태를 Git에 커밋했습니다. 다음에는 기존 사례글을 읽고 프로젝트 원칙을 만들도록 요청했다. 이때 ‘새 PRD를 만들지 말고 기존 PRD를 근거로 써줘’라는 조건을 넣었습니다. PRD는 무엇을 만들고 어떤 업무 기준을 지킬지 정한 문서입니다.
원칙에는 원본을 바꾸지 않기, 금액, 수량, 요청횟수 구분하기, 모르는 값을 추측하지 않기, 실제로 확인한 범위만 완료로 보고하기를 담았습니다. 다음 수정의 출발점은 이미 합의한 요구와 현재 코드로 정했다.
코덱스로 현재 동작 명세를 남겼다
작업을 시작한 폴더에는 실제 앱 코드와 정본 PRD가 없었습니다. 처음 알려준 참고 폴더에는 사례글과 작업 기록이 있었고, 그 기록과 기존 README를 따라 별도 MVP 폴더의 PRD를 찾았습니다.
코덱스가 읽을 문서와 실행할 앱의 위치를 구분하는 안내를 만들었다. 새 작업 폴더에 앱이 복사되었다고 간주하지 않았고, 기존 PRD도 복제하지 않았습니다. 폴더를 구별한 뒤 코드에서 확인할 수 있는 내용을 기준 명세로 정리했습니다.
제가 요청한 기준은 다음과 같습니다.
지금 이 프로젝트가 실제로 하는 일을 기준 명세로 작성해줘. 새 기능을 추가하지 마.
코드에 없는 기능을 있는 것처럼 쓰지 말고, 확인하지 못한 부분은 미확인으로 표시해줘.
기준 명세에는 기능 14개, 직접 확인 행동 25개, PRD와 코드의 차이 14개가 들어갔다. 예를 들어 현재 코드에서 같은 연도의 다른 월과 요청번호가 겹치면 등록을 막는다는 점, 벤더 거래처 별칭을 바꾸는 화면이 없다는 점을 구분했습니다.
여기서 ‘코드가 있다’와 ‘직접 실행해서 확인했다’를 나눴습니다. 입력부터 분석과 보고서 출력으로 이어지는 코드를 읽었지만, 이번 작업에서는 실제 여러 월 자료의 합계 대조나 Word 전체 페이지 점검을 수행하지 않았다. 명세에도 실행 미확인으로 적었습니다.
이번에는 월 교체 전 차이 표시 하나만 골랐다(증감표시 기능 구현)
개선 후보를 비교한 뒤 제가 고른 것은 ‘월 자료 교체 화면에 기존 대비 증감액, 증감수량을 표시한다’였습니다. 현재는 기존 월과 새 자료의 합계가 나란히 나와 사용자가 직접 차이를 계산해야 합니다.
변경 명세에는 이번 범위만 담았다. 정상 입력에서는 새 합계에서 기존 합계를 뺀 값을 보여줍니다. 신규 월은 비교할 기존 자료가 없다고 표시하고, 빈 파일이나 잘못된 금액은 기존 입력 점검으로 막도록 적었습니다.
숫자 계산도 구체적으로 정했습니다. 원본의 정밀값을 먼저 빼고, 화면에서만 소수점 아래를 버립니다. 표시된 정수끼리 빼면 작은 소수 차이가 다르게 나올 수 있기 때문입니다. 차이가 0이 아니지만 표시하면 0인 경우에는 ‘소수점 차이 있음’을 붙이기로 했습니다.
이번 주 제외 범위에는 증감률, 품목별 변경 목록, Word에 차이 추가, 전년도 비교, ERP 자동 연결을 넣었다. 기능 하나를 고쳤다고 다른 기능까지 넓히지 않도록 경계를 적어 둔 것입니다.
코덱스로 저장과 로그인 선택을 정했다
코드를 읽은 결과, 기존 미리보기 응답에 새 합계와 기존 합계가 모두 있었습니다. 이 두 값을 사용하면 화면에서 차이를 계산할 수 있어 새 데이터 저장 항목이나 외부 연결을 추가할 필요가 없었다.
로컬 앱과 배포용 앱의 기존 화면을 각각 조금씩 바꾸는 계획을 세웠습니다. 새 프레임워크로 옮기지 않고 기존 로그인과 월 교체 방식을 유지하는 선택입니다. 로컬 화면을 배포용 화면에 통째로 복사하면 배포용 저장 버전 정보와 차트 처리가 빠질 수 있다는 위험도 기록했다.
작업은 입력, 바꿀 파일, 결과물, 제가 확인할 방법을 붙여 순서대로 나눴습니다. 처음에는 33개 작업이 나왔다. 첫 작업은 코드를 수정하는 일이 아니라 실제 앱 위치와 변경 전 상태를 기록하는 5분짜리 작업으로 잡았습니다.
여기까지 문서를 만들었다고 바로 구현에 들어가지는 않았습니다. 다음 요청에서 명세, 계획, 작업 목록이 서로 맞는지 먼저 점검하도록 했습니다.
스펙킷 분석에서 보완점 5개가 드러났다
분석을 요청하면서 문서를 제 확인 없이 고치지 말라는 조건을 함께 줬습니다.
프로젝트 원칙과 충돌하는 부분도 확인해줘.
고칠 것이 있으면 어느 문서를 어떻게 고쳐야 하는지 제안만 하고, 내 확인 없이 고치지 마.
기능 요구사항에는 모두 작업이 연결되어 있었습니다. 그래도 시험 준비와 최종 확인에는 빠진 부분이 있었다. 코덱스가 제안한 보완점은 다섯 가지입니다.
시험마다 원래 월 자료로 돌아가는 준비 절차를 추가한다.
잘못된 서버 응답과 등록 통신 실패도 확인한다.
마지막 코드 수정 뒤 정상, 빈 입력, 오류, 충돌 시험을 다시 한다.
동일 파일 재등록에는 부서 재선택을 요구하지 않되 기존 서버의 버전 확인은 유지한다.
한 작업에 묶인 여러 시험을 작은 단위로 다시 나눈다.
특히 동일 파일 처리 조건이 눈에 들어왔다. 기존 코드는 동일 파일이면 다시 합산하지 않고 안내하는데, 새 화면 점검을 모든 파일에 적용하면 부서를 다시 고르라고 할 수 있었습니다. 새 표시 기능이 기존 사용 흐름을 불편하게 만들 가능성을 구현 전에 발견한 것입니다.
제안을 확인한 뒤 ‘수정해줘’라고 했습니다. 계획과 확인 절차를 고치고 작업 목록을 67개로 다시 나눴다. 이 숫자는 실행한 작업 수가 아니라 미착수 작업 항목 수입니다. 목표 시간은 작업별 5분에서 20분이며, 전체 추정은 약 16.5시간으로 늘었습니다. 실제 시간을 측정한 값은 아닙니다.
수정 기준과 미완료 범위가 남았다
스펙킷을 처음 사용한 뒤 학습일지에는 이렇게 적었습니다.
speckit이라는 것을 처음 사용해서 수정할 때 뭔가 전문적으로 수정해 주고 충돌이나 문제점도 자연스럽게 알 수 있었다
이번에 남은 결과물은 프로젝트 원칙, 현재 동작 기준 명세, 작은 변경의 명세, 구현 계획, 작업 목록과 확인 안내입니다. 같은 개선을 설명하는 문서끼리도 서로 맞지 않을 수 있다는 것을 실제 점검에서 보았습니다.
작업을 더 잘게 나누면서 해야 할 항목은 늘었다. 아직 코드를 구현하지 않았고 시험 환경도 준비하지 않았습니다. 개선 버전을 배포하거나 작성 시간을 얼마나 줄였는지 측정한 상태도 아닙니다.
다음에는 첫 작업부터 실제 파일과 대조해 진행하려고 합니다. 앱 위치와 변경 전 상태를 기록하고, 끝낸 작업의 결과를 직접 확인한 뒤 체크할 예정입니다.
같은 기존 앱을 고칠 때 다시 쓸 요청
이번 작업에서 사용한 순서는 원칙 만들기, 현재 동작 명세 쓰기, 개선 하나 고르기, 계획 세우기, 작업 나누기, 문서 비교입니다. 기존 앱과 PRD가 있는 상태에서 작은 수정을 준비할 때 다시 사용할 수 있는 흐름입니다.
아래 문장은 실제 요청들의 조건을 모은 재사용용 문안입니다. 처음 보낸 원문과는 구분했습니다.
기존 PRD와 코드를 읽고 [증감표시 기능 구현]의 범위만 정리해줘.
정상, 빈, 잘못된 입력에서 기대하는 동작과 내가 확인할 행동을 적어줘.
기존 기술을 유지하고 작업을 30분 이하로 나눠줘.
명세, 계획, 작업 목록의 누락과 충돌을 점검하고, 내 확인 전에는 고치지 마.이번에는 그 요청으로 만든 문서를 실제로 비교하고, 동일 파일 처리와 빠진 시험을 보완하는 데까지 진행했습니다. 현재는 문서 보완까지 끝낸 상태이며, 첫 작업을 실제로 실행한 결과는 아직 없습니다.
로그인하고 댓글을 남겨 주세요
정균님, Spec Kit을 처음 써 보셨는데 흐름이 정말 탄탄해요. 특히 기준 명세에서 '코드가 있다'와 '직접 실행해서 확인했다'를 구분하고, 여러 월 합계 대조나 Word 전체 점검처럼 하지 않은 부분은 '실행 미확인'으로 남기신 점이 인상 깊었습니다. 원본의 정밀값을 먼저 빼고 화면에서만 소수점을 버리는 규칙, 표시값이 0이어도 차이가 있으면 '소수점 차이 있음'을 붙이는 규칙은 구매 숫자를 매일 다루는 분이라서 잡아낼 수 있는 디테일 같아요. 동일 파일 재등록 때 부서를 다시 고르게 될 수 있는 문제를 구현 전에 발견하신 것도 문서 점검의 효과를 제대로 보여 준 장면이었습니다.
다만 작업이 33개에서 67개로 늘면서 시작이 무겁게 느껴질 수도 있을 것 같아요. 그럴 때는 전체를 순서대로 하기보다 '첫 화면 결과'까지 가는 짧은 경로를 먼저 뽑아 보시면 좋겠어요. 예를 들면 이렇게 요청해 볼 수 있습니다.
> "tasks 목록에서 로컬 앱의 월 교체 화면에 증감액·증감수량이 처음 표시되는 데까지 꼭 필요한 작업만 골라줘. 나머지는 그대로 두고, 고른 작업마다 내가 확인할 방법을 한 줄씩 붙여줘. 목록은 고치지 말고 제안만 해줘."
첫 작업(앱 위치와 변경 전 상태 기록)을 해 보시고 결과를 공유해 주시면 다음 단계로 넘어가도 될지 같이 봐 드릴게요. 확인 기록 양식이 필요하시면 제가 쓰는 걸 나눠 드려도 됩니다. 구현 후기도 기대하고 있을게요! 🙂


![[OpenClaw · Airtable] 노트랑 카톡에 흩어진 고객 상담, 아기 수호신이 질문 4개로 표 4개를 짰다: 뽀야의 사관학교 2주차 썸네일](/_next/image?url=https%3A%2F%2Fcdn-beta.gpters.org%2Fexternal%2F96d4e21f3d5f22c5158e6df3.jpg&w=3840&q=75)
작업 67개 중 첫 번째인 '변경 전 상태 기록' 때 지난달 실제 자료로 앱 합계와 기존 보고서 총액을 한 번만 맞춰보세요. 증감액은 그 숫자가 맞아야 믿을 수 있거든요.