본문으로 건너뛰기

spec-kit 단계 기준으로 자동 발행 허브의 문서 점검하기

Fri-mer

2026.10.14

spec-kit 단계 기준으로 자동 발행 허브의 문서 점검하기 본문 이미지

소개

2주차 강의에서 배운 spec-kit의 일곱 단계(헌법, 명세, 계획, 작업 목록, analyze, implement, converge)와 명세 템플릿의 필수 요소를 기준으로, 매일 자동 발행되는 제 경제 브리핑 허브(econ-radar)의 문서가 실제 동작과 얼마나 맞는지 명령으로 재 본 기록입니다. 1주차 계획 여섯 가지의 실행 여부와 같은 명령으로 다시 잰 값도 함께 실었습니다. 에이전트가 만든 결과물을 몇 달째 운영하면서 그 문서를 어디까지 믿어도 되는지 궁금한 분께 도움이 될 것 같습니다.

AI놀이터 2주차(10월 7일)는 PRD.md 하나를 만들어 spec-kit의 스킬을 차례로 부르는 실습이었습니다. 스터디장은 AI로 만든 것도 결국 코드여서, "해 줘"만 반복하면 잘 만들다가도 구조가 없어 어느 순간 틀어진다고 했습니다. 버디(황금호랑이)는 올해 초부터 spec-kit으로 개발해 왔다며, 큰 조직에서는 소스와 문서가 바로 갱신되지 않아 시간이 지나면 인수인계에서 문제가 된다는 점을 이유로 들었습니다. 이 말이 제 허브에도 해당하는지 확인하고 싶었습니다.

저는 이번 기수에 이 스터디를 청강합니다. 연습용 PRD 앱을 새로 만드는 대신, 6월 9일부터 매일 돌아가는 econ-radar에 같은 기준을 대 보기로 했습니다. 이 허브는 클라우드의 Claude Code가 만들어 발행하고, 문서(CLAUDE.md, HANDOFF.md, 스킬과 에이전트 정의)가 그 일을 시키는 지시서 역할을 합니다. 저장소는 읽기만 했고 아무것도 고치지 않았습니다.


진행 방법

사용 도구: Claude Code, Python 3, git, gh(GitHub CLI), uv와 spec-kit v1.1.1

측정은 2026-10-13에 했고, 대상은 원격 저장소 origin/main입니다(마지막 커밋은 10월 12일자 데일리 발행).

Step 1. 강의가 정한 기준의 정리

스터디장이 보여 준 순서는 이렇습니다. 지침(헌법)으로 프로젝트 전체의 원칙을 정하고, 명세로 기능의 요구를 쓰고, 계획으로 구현 방법을 정하고, 작업 목록으로 나눈 뒤, analyze로 문서끼리 맞는지 점검하고, implement로 구현하고, converge로 명세대로 구현됐는지 다시 확인합니다. 수업 시간에는 명세를 보여 주는 데까지만 갔습니다.

스터디장이 읽어 준 명세 문서는 유저 스토리, 독립 테스트 방법, 인수 시나리오, 예외 상황, 번호가 붙은 기능 요구사항으로 이루어져 있었습니다. 버디는 PRD가 비즈니스 요구를 개발자에게 전하는 중간 문서라면, 명세는 AI가 코딩할 수 있게 실행 가능한 형태로 쓴 요구 문서라고 구분했습니다. 이 구분이 제게는 점검 기준이 됐습니다. 사람이 읽는 설명이 아니라 "무엇이 되면 끝인지"가 적혀 있는지를 보면 되기 때문입니다.

Step 2. spec-kit의 설치와 초기화

수업의 설치 순서를 임시 폴더에서 그대로 따라 했습니다. 먼저 사전 도구 세 가지를 확인했습니다.

node --version; git --version; uv --version; specify --version
v24.12.0
git version 2.24.3 (Apple Git-128)
uv: command not found
specify: command not found

uv가 없어서 임시 가상환경에 uv를 받은 뒤, 강의 채팅에 올라온 명령(버전 1.1.1 고정)으로 설치했습니다. 설치 위치는 환경 변수로 임시 폴더에 바꿔 두었습니다.

uv tool install specify-cli --force --from git+https://github.com/github/[email protected]
specify --version
specify 1.1.1

이어서 빈 폴더를 git 저장소로 만들고 코덱스용 스킬 방식으로 초기화했습니다.

git init -q . && specify init --here --force --non-interactive --integration codex --integration-options="--skills"
find . -path ./.git -prune -o -type f -print | wc -l
ls .agents/skills
30
speckit-analyze speckit-checklist speckit-clarify speckit-constitution speckit-converge
speckit-implement speckit-plan speckit-specify speckit-tasks speckit-taskstoissues

만들어진 파일이 30개로, 수업에서 코덱스가 "파일 30개를 스테이징했다"고 한 것과 같았습니다. 스킬은 10개이고, 1주차에 확인한 학습허브 템플릿의 spec-kit 스킬 10개와도 같습니다. 여기까지가 제가 한 실습의 끝입니다. PRD 작성부터 이어지는 스킬 실행은 코딩 에이전트의 입력창에서 슬래시로 불러야 해서 이번에는 하지 못했습니다. 대신 초기화로 생긴 .specify/templates/spec-template.md(131줄)를 열어 필수 요소를 확인했습니다. 필수 절은 사용자 시나리오와 테스트(스토리마다 우선순위, 독립 테스트, Given/When/Then 인수 시나리오), 예외 상황, 요구사항(FR-001 식 번호), 성공 기준(SC-001 식 수치 기준)입니다.

Step 3. 명세 템플릿 기준의 문서 점검

필수 요소를 econ-radar의 문서에서 찾았습니다. 범위는 CLAUDE.md, HANDOFF.md, TODO.md, vault/README.md와 스킬 7개, 에이전트 17개를 합친 28개 파일입니다. 표현이 있는지만 정규식으로 세었고 내용의 질은 읽지 않았습니다.

kw = {"사용자 스토리": r"사용자 스토리|[Uu]ser [Ss]tory",
      "인수 시나리오": r"인수 시나리오|인수 기준|[Aa]cceptance|Given",
      "예외 상황": r"예외|[Ee]dge case|엣지 케이스|실패 시",
      "번호 붙은 요구사항": r"FR-\d|REQ-\d",
      "성공 기준": r"성공 기준|Success Criteria|SC-\d|완료 기준|완료 조건"}
{'files': 28, '사용자 스토리': 0, '인수 시나리오': 0, '예외 상황': 8, '번호 붙은 요구사항': 0, '성공 기준': 0}

다섯 요소 중 예외 상황만 8개 파일에 있었고 나머지 네 가지는 0개였습니다. 헌법에 해당하는 CLAUDE.md는 55줄에 안전선 세 항목이 있어 원칙은 갖췄지만, 변경 이력의 마지막 항목이 6월 13일입니다. 7월 5일에 추가한 안전선 규칙은 이력에 없습니다.

Step 4. 문서와 실제의 대조

analyze 단계가 하는 일을 손으로 해 봤습니다. 문서가 말하는 것을 저장소의 실제 파일과 실행 기록에 대 보는 일입니다.

유망 기업 분석 파일의 이름. 일일 발행 스킬의 산출물 계약 표와 에이전트 정의는 vault/analysis/company-날짜.md로 적습니다. 발행한 122일의 실제 이름을 셌습니다.

git -c core.quotepath=off ls-tree -r --name-only origin/main | grep '^vault/analysis/' | sed -E 's#vault/analysis/##; s/[0-9]{4}-[0-9]{2}-[0-9]{2}//' | sort | uniq -c
   2 career-.md
  85 companies-.md
  34 company-.md
   1 company-analysis-.md
   1 index.md
 121 market-.md
   1 market-analysis-.md

날짜 기준으로 정리하면 계약대로 company-인 날이 34일, 복수형 companies-인 날이 85일, 그 밖이 3일입니다. 복수형은 6월 14일에 처음 나타났고 10월 10일에도 있습니다. 이름이 달라서 본문이 빠졌는지도 확인했습니다. 날짜별 데일리 본문에 "Companies to Watch" 또는 "유망 기업"이 든 날을 세니 company- 34일 중 34일, companies- 85일 중 85일이었습니다. 그 밖 3일은 2일입니다. 이름은 어긋났지만 발행물에는 영향이 없었습니다.

발행 122일을 달력으로 나타낸 그림. 파란 칸 34일은 문서와 같은 company 이름, 주황 칸 85일은 복수형 companies 이름, 회색 3일은 그 밖, 빨간 테두리 4일은 발행 파일이 없던 날

발행 시각과 이름이 문서에 나오는 비율. CLAUDE.md는 데일리 루틴을 "18:30 KST"로 적습니다. 9월 14일 이후 "날짜 자동 생성" 커밋 메시지가 있는 25일의 첫 커밋 시각을 KST로 바꿔 보았습니다. 커밋 시각이 UTC(+0000)로 찍혀 처음에는 10시대로 읽혔기 때문에 TZ=Asia/Seoul을 지정했습니다.

TZ=Asia/Seoul git log -1 --format='%ad' --date=format-local:'%H:%M' <커밋>
25일, 가장 이른 18:57, 가장 늦은 19:48, 중앙값 19:24

18:30 이전에 끝난 날은 0일입니다. 다만 문서의 18:30이 루틴의 시작 시각인지 완료 시각인지 적혀 있지 않고, 실제 예약 시각은 저장소 밖(클라우드 설정)에 있어 이 값만으로 어긋났다고 단정할 수 없습니다. 문서 네 개(CLAUDE.md, HANDOFF.md, TODO.md, vault/README.md)에 이름이 나오는 비율도 셌습니다.

대상

이름이 나오는 수

문서 속 파일 경로

16개 중 16개가 실제로 존재

에이전트

17개 중 12개

스킬

7개 중 4개

워크플로

4개 중 3개 (daily-watchdog만 없음)

왼쪽은 날짜별 첫 발행 커밋 시각 25개를 점으로 나타낸 그림으로 18:57부터 19:48까지 퍼지고 중앙값은 19:24. 오른쪽은 문서에 이름이 나오는 비율로 경로 16/16, 에이전트 12/17, 스킬 4/7, 워크플로 3/4

Step 5. 1주차 계획의 실행 확인과 재측정

1주차 참고 계획 여섯 가지를 파일 수정 이력, 워크플로 정의, 실행 기록으로 확인했습니다. 실행은 하나, 미실행은 넷, 확인하지 못한 것이 하나입니다.

1주차 다음 주 계획 여섯 가지의 판정표. 로드맵과 계획 칸, 학습일지 칸 위치, 알림 문구 구분, 빠진 날 원인 확인은 미실행, 재시도 루틴 동작은 확인 불가, 재측정은 실행

재시도 루틴은 10월 5일 이후 빠진 날이 없어 빠진 날에 실제로 동작하는 모습을 볼 기회가 없었습니다. 루틴의 실행 기록은 클라우드 화면에만 있어 열어 보지도 못했습니다.

같은 방식으로 다시 센 값은 아래와 같습니다. 1주차에 쓴 hub_check.py는 글에 일부만 실었기 때문에, 같은 정의로 새로 짜서 실행했습니다.

python3 -I measure.py

출력은 줄여서 옮겼습니다.

daily 122 / 126일, 빠진 날 ['2026-06-12', '2026-07-22', '2026-08-01', '2026-10-01']
topics 114, reports 18주(W24~W41), 이름에 로드맵, 계획이 든 파일 []
1주차와 같은 항목을 다시 잰 표. daily 날짜 파일이 115개에서 122개, topics가 99개에서 114개, 주간 동향이 17주에서 18주로 늘었고 빠진 날은 같은 4일, 로드맵과 계획 파일은 0개

빠진 날은 1주차와 같은 4일이고 새로 빠진 날은 없습니다. 그런데 새로 만든 22시 감시 워크플로가 매일 실행됐는지 확인하다가 이상한 점을 찾았습니다.

gh run list --workflow=daily-watchdog.yml --limit 20
gh run view <실행 번호> --log

예약 실행 7번이 모두 예약 시각(13:00 UTC, 22:00 KST)보다 4.7시간에서 8.0시간 늦게 시작했습니다. 시작 시각이 이미 다음 날 새벽이라 감시 스크립트는 그날 날짜의 데일리를 찾았고, 데일리는 그날 저녁 19시대에 올라오므로 7번 모두 "MISSING"으로 판정하고 텔레그램으로 알림을 보냈습니다. 7번 모두 로그에 "DM 발송 완료"가 찍혀 있습니다. 실제로 빠진 날은 이 기간에 없으므로 7건이 모두 오경보입니다.

감시 워크플로 예약 실행 7번의 지연 시간 막대 그림. 예약보다 4.7시간부터 8.0시간까지 늦게 시작했고 모두 다음 날 날짜를 점검해 MISSING으로 판정하고 DM을 보냈음

결과와 배운 점

측정 결과

항목

값

점검 대상

econ-radar 허브의 문서 28개(스킬 7, 에이전트 17, 최상위 문서 4)와 저장소 파일, 원격 저장소 기준

spec-kit 일곱 단계 대응

있음 1, 일부 5, 없음 1

명세 템플릿 필수 5요소

예외 상황만 8개 파일, 나머지 4요소는 0개

company 파일 이름

122일 중 계약과 같은 날 34일, 복수형 85일, 그 밖 3일. 본문 영향 없음

문서에 이름이 나오는 비율

에이전트 12/17, 스킬 4/7, 워크플로 3/4

테스트 파일

0개 (스크립트 8개)

1주차 계획 실행

6개 중 실행 1, 미실행 4, 확인 불가 1

감시 워크플로

예약 실행 7번 중 7번이 4.7~8.0시간 늦게 시작해 오경보

배운 점

  1. 문서가 정한 계약은 아무도 모르게 달라졌습니다. 파일 이름 company-가 6월 14일부터 companies-로 갈리기 시작해 122일 중 85일이 문서와 다릅니다. 본문에는 유망 기업 절이 모두 들어 있어서 넉 달 가까이 눈에 띄지 않았습니다. 왜 복수형이 늘었는지는 확인하지 못했습니다. 에이전트가 이름을 매번 새로 짓는다면 문서와 파일이 점점 어긋날 텐데, analyze 단계는 바로 이런 어긋남을 사람이 눈치채기 전에 찾는 장치였습니다.

  2. 문서에는 왜 그렇게 정했는지는 많은데 무엇이 되면 끝인지는 없습니다. CLAUDE.md의 변경 이력은 결정의 이유를 꼼꼼히 남겼지만, 명세 템플릿이 요구하는 인수 시나리오와 성공 기준은 28개 파일 어디에도 없었습니다. 그래서 22시 감시 워크플로를 만들 때도 "예약 시각이 실제 실행 시각과 다를 수 있다"는 예외가 적혀 있지 않았습니다.

  3. 시험한 경로와 실제로 도는 경로가 달랐습니다. 1주차 글에서 감시를 10월 1일과 3일 두 날짜로 시험했습니다. 두 번 모두 날짜를 직접 지정해 수동으로 실행한 것이어서, 예약 실행이 제때 도는지는 확인하지 않았습니다. converge 단계에서 "명세대로 구현됐나"를 보는 것은 시험한 경로가 아닌 실제 경로여야 합니다. 이번에 확인한 오경보 7건이 그 차이입니다. GitHub이 부하가 큰 시간대에 예약 실행을 늦출 수 있다고 안내하는 것으로 알고 있으나, 이번 지연의 원인이 그것인지는 확인하지 못했습니다.

  4. 1주차의 "계획 칸이 비었다"는 지적은 그대로입니다. 이름에 로드맵이나 계획이 든 파일은 여전히 0개이고, 계획 여섯 가지 중 실행한 것은 재측정 하나입니다. 다음에 할 일을 적어 두었어도 TODO.md처럼 한 달 넘게 갱신되지 않으면 계획의 구실을 못 합니다. TODO.md는 열린 항목 13개 중 "오늘 밤(7/5) 데일리 확인"이 100일째 열려 있고 마지막 수정이 7월 5일입니다.

시행착오

  • 문서 속 경로를 처음에는 손으로 세어 21개 중 20개가 존재한다고 보았습니다. 문서마다 중복이 들어 있었고 benchmarks.md 하나는 vault/_meta/ 아래의 상대 경로라서 없다고 잘못 나온 것이었습니다. 중복을 없애고 상대 경로를 풀어 다시 센 값이 16개 중 16개입니다.

  • 1주차 글의 "topics 9월 28일 이후 15개 갱신"은 이번에 같은 정의로 재현하지 못했습니다. 같은 기간(10월 6일까지)을 git log --name-only로 세면 21개가 나와서 정의가 다르다고 보고 비교표에서 뺐습니다. topics 개수(99개에서 114개)만 비교했습니다.

  • 커밋 시각이 UTC로 찍혀 처음에는 문서의 18:30보다 8시간 일찍 발행한다고 읽을 뻔했습니다. KST로 바꾼 뒤에야 19시대로 맞았습니다.

이 점검은 2026년 10월 13일에 ~/projects/econ-radar(origin/main)의 문서 28개와 파일 이름, 커밋 이력, 감시 워크플로 실행 기록 7건을 읽어 낸 결과입니다. 문서의 내용이 맞는지는 읽지 않았고 표현의 유무만 세었으며, 클라우드 루틴의 설정과 실행 기록은 저장소 밖이라 보지 못했습니다. spec-kit은 임시 폴더에서 설치와 초기화까지만 했고 명세 작성과 그 뒤 단계는 실행하지 못했습니다.


도움 받은 글

  • 24기 AI놀이터 2주차 강의 (아루나, 황금호랑이): spec-kit의 단계 순서, 명세 문서의 구성, PRD와 명세의 차이, 소스와 문서가 어긋나면 인수인계에서 문제가 된다는 설명

  • 도시아재 님의 "작은 대시보드로 떠난 두 번째 항해, Spec Kit으로 소개 문장의 기준을 찾았습니다" (24기 AI놀이터 게시판): prd, constitution, spec, plan, tasks 다섯 문서의 역할을 비유로 정리한 설명과, 길이 조건만 통과한 결과를 명세의 기준으로 고쳐 다시 확인한 과정

  • GitHub spec-kit v1.1.1이 초기화로 만든 spec-template.md와 constitution-template.md: 명세와 헌법의 필수 요소

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

아루나 프로필 이미지
아루나2026.10.14

감시 장치가 7번 다 오경보였다는 걸 실행 기록까지 열어서 찾아내신 게 대단해요. GitHub Actions 예약 실행은 몇 시간씩 늦게 도는 일이 흔해서, 실행 시각의 '오늘' 대신 예약된 날짜(또는 최근 24시간 안에 데일리가 있는지)로 판정하게 바꾸면 오경보가 바로 사라질 것 같아요. 명세 다섯 요소 중 성공 기준이 0개였던 것도, 이 감시 규칙부터 '무엇이면 정상'을 한 줄로 적어보시면 좋은 첫 칸이 될 것 같아요.

황금호랑이 프로필 이미지
황금호랑이2026.10.14

Fri-mer님, 연습용 앱 대신 넉 달째 매일 도는 econ-radar에 spec-kit 기준을 대 보신 선택 자체가 정말 좋았어요. 수업에서 제가 "큰 조직에서는 소스와 문서가 바로 갱신되지 않아 인수인계에서 문제가 된다"고 말씀드렸는데, 그 말을 company- 34일 / companies- 85일이라는 숫자로 바로 확인해 주셨네요. 이름은 어긋났어도 유망 기업 본문은 모두 들어 있었다는 것까지 확인하셔서 "영향 없음"을 짐작이 아닌 측정으로 말씀하신 점, 커밋 시각을 KST로 바꿔 18:30 문제를 단정하지 않은 점, 경로 21개 중 20개를 16개 중 16개로 바로잡은 시행착오까지 그대로 적어 주신 점이 정말 믿음직해요. 가장 큰 수확은 역시 감시 워크플로 오경보 7건이에요. 1주차에 날짜를 직접 지정해 수동으로 시험한 경로와 실제 예약 경로가 달랐다는 정리는 converge 단계를 설명하는 가장 좋은 예시라고 생각해요. 고칠 때는 코드보다 명세를 먼저 써 보시면 어떨까요? 코딩 에이전트에 이렇게 부탁해 보셔도 좋아요. > "daily-watchdog 워크플로 하나만 대상으로 .specify/templates/spec-template.md 형식의 명세를 역으로 써 줘. 코드는 고치지 마. 예외 상황에 '예약 시각보다 몇 시간 늦게, 날짜가 바뀐 뒤 실행되는 경우'를 꼭 넣고, Given/When/Then 인수 시나리오와 SC-001: 실제로 빠진 날이 없으면 오경보 0건 같은 성공 기준을 포함해 줘." 이렇게 해 보면 "점검할 날짜를 실행 시각이 아니라 예약 시각(KST) 기준으로 정한다" 같은 요구사항이 자연스럽게 FR-001로 나올 거예요. 그다음 수정은 수동 실행이 아니라 예약 실행 며칠치 로그로 확인하시면 converge까지 한 바퀴를 도는 셈이에요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기