Spec Kit and LangGraph

phase를 한 번에 맡기면 오래 걸렸고 규칙도 빠졌습니다

SpecKit은 사양 주도 개발(SDD)을 위한 오픈 소스 툴킷입니다. 항상 지킬 규칙을 constitution에 적고 specify, plan, tasks 단계에서 사양, 구현 계획, 작업 목록을 Markdown으로 만든 뒤 implement 단계에서 코딩 에이전트가 tasks.md를 구현합니다. 산출물을 다시 점검하는 clarify와 analyze는 선택 단계입니다. Codex CLI에서 기본 템플릿을 한국어로 옮기고 CMS 프로젝트에 맞게 고쳐 썼습니다.

써 보니 SpecKit은 알아서 무언가를 만들어 주는 도구가 아니었습니다. 입력을 정해진 템플릿 프롬프트에 넣어 산출물을 만드는 파이프라인에 가까웠습니다. 5~6개 phase를 한 번에 implement에 맡겼더니 응답까지 codex 5.3 기준 53분이 걸렸습니다. 결과물에서는 constitution에 적은 규칙을 지키지 않은 곳도 꽤 나왔습니다. constitution은 에이전트에게 지키라고 건네는 문서일 뿐 구현 결과를 검사하지는 않습니다.

범위가 커지면 사람이 읽어야 할 산출물도 늘어납니다. 잘못된 구현은 대부분 산출물을 대충 읽고 구현으로 넘어갈 때 생겼습니다. 구현 전에 analyze로 정책 충돌과 보강할 부분을 한 번 더 찾게 하는 이유도 같습니다.

phase 단위로 자르고 구현, 검토, 수정을 반복했습니다

그 뒤로는 implement에 “phase 1만 구현”처럼 범위를 잘라 넘겼습니다. phase 하나를 구현하면 결과를 검토하고 고친 다음에야 phase 2로 넘어갑니다. 토큰 사용량과 응답 시간을 줄이려는 목적이었고 constitution을 지키는 데도 작은 범위를 순서대로 구현하는 편이 낫다고 봤습니다. 간단한 작업은 이 비용을 감안하면 SpecKit을 쓰기 애매했습니다.

그런데 이 반복을 지킨 쪽은 SpecKit이 아니라 저였습니다. 구현 뒤에 검토를 넣고 수정이 끝나야 다음 phase를 여는 순서는 도구가 강제하지 않았습니다. 한 번에 맡기면 규칙이 빠지고 나눠서 맡기면 사람이 매번 순서를 지켜야 했습니다. 이 순서를 사람 대신 지켜 줄 장치가 필요한지가 다음 질문이 됐습니다.

SpecKit이 남긴 것은 코드보다 문서였습니다

빈 저장소에서 시작하는 그린필드는 기획 품질이 낮으면 결과도 그만큼 나빠집니다. 코드베이스와 컨벤션이 이미 있는 프로젝트에 기능을 더할 때는 사정이 달랐습니다. 관련 파일을 참조하게 하고 요구사항을 적당히 주는 것만으로도 기능이 충분히 구현됐습니다.

다만 AI와 대화하며 기능을 추가하는 방식과 비교하면 유의미한 차이는 느끼지 못했습니다. 차이는 문서에 있었습니다. specify 단계가 기능마다 브랜치와 문서 폴더를 만들고 spec, plan, tasks가 그 안에 남습니다. 개발 중에는 늘 빠뜨리던 문서입니다. 이후 작업자가 이 기능을 누가, 왜 이렇게 고쳤는지와 애초에 왜 넣었는지를 빨리 찾을 수 있습니다. 매번 대화 맥락을 잊는 모델에게 같은 맥락을 다시 건네는 용도로도 쓸 수 있습니다.

문서는 절차를 설명하고 그래프는 절차를 실행합니다

SpecKit에서 본 문제는 SpecKit만의 문제가 아니었습니다. AGENTS.md, .workflow, SKILL.md 같은 규칙 문서를 정리해 두고 Claude Code나 Codex CLI 같은 구독형 에이전트를 쓰는 방식 전체에 해당합니다. 계획, 검토, 승인, 검증 순서를 문서에 잘 적어 둬도 모델이 매번 그 순서를 지킨다는 보장은 없습니다. 계획을 충분히 세우지 않고 수정에 들어가기도 하고 검토나 검증을 제대로 하지 않은 채 완료처럼 보이는 응답을 주기도 합니다. 같은 문서를 읽어도 모델 버전, 프롬프트 방식, 사용자의 숙련도에 따라 결과가 달라집니다.

LangGraph는 절차를 그래프의 node와 edge로 고정합니다. 어느 단계 뒤에 사람 승인을 둘지, 실패하면 몇 번까지 다시 할지, 어디서 멈출지를 실행 경로로 정하고 각 단계의 결과를 명시적인 상태로 들고 다닙니다.

어느 쪽이 절대적으로 낫다고 보기는 어려웠습니다. “AGENTS.md에 절차가 있는데 LangGraph가 왜 필요한가” 대신 “이 절차를 문서로 관리하는 것으로 충분한가, 시스템으로 강제해야 하는가”를 물어야 했습니다.

그래프로 옮길 것은 승인, 재시도, 검증 루프입니다

비교에 쓴 예제는 main graph 하나가 계획, 수정 제안, 구현, 검증 stage를 subgraph로 조립하는 구조입니다. stage는 실패하면 자기 안에서 다시 돕니다. 파일 수정을 적용하기 전과 구현, 검증의 반복 한도를 넘었을 때는 interrupt로 멈춰 사람의 답을 기다립니다.

flowchart TD
    Intake["요청 분류, 규칙 문서 선택"] --> Plan["planning: 계획과 검증 체크리스트"]
    Plan -->|"고위험 요청은 승인 뒤"| Edit["edit: 수정 제안과 검토"]
    Edit -->|"적용 승인 뒤"| Impl["implementEdit"]
    Impl --> Review{"reviewImplementation"}
    Review -->|"실패"| Repair["repairImplementation"]
    Repair --> Impl
    Review -->|"통과"| Verify{"check, build, biome"}
    Verify -->|"실패"| Fix["repairValidation"]
    Fix --> Verify
    Verify -->|"통과"| Reply["최종 응답"]

계획은 검증을 통과할 때까지 초안을 3차까지 쓰고 고위험으로 분류된 요청은 사람이 승인해야 수정 단계로 넘어갑니다. 수정 제안은 검토를 거쳐 2차까지 만들고 통과한 제안만 “실제 파일 수정을 적용할까요?”라는 승인 요청에 올립니다. 구현 검토가 실패하면 repairImplementation을 거쳐 다시 구현하고 repair를 4회 하고도 통과하지 못하면 계속할지 사람에게 묻습니다. 검증 stage는 타입 검사, 빌드, Biome 검사를 실행하고 실패하면 최대 2회 고친 뒤 사람에게 넘깁니다. 승인이 거부되거나 검토를 통과하지 못하면 바로 최종 응답으로 갑니다. interrupt로 멈춘 그래프를 이어 가려면 상태를 저장할 checkpointer가 필요해서 main graph는 MemorySaver를 붙여 compile합니다.

SpecKit에서 phase마다 손으로 돌리던 구현, 검토, 수정 루프가 implementation stage의 구현, review, repair 루프와 같은 모양입니다. 사람이 지키던 순서를 edge가 지킵니다.

그래프가 강제하는 것은 순서, 반복 한도, 멈추는 지점까지입니다. 판정의 품질은 강제하지 못합니다. 구현 검토의 통과 여부는 모델이 structured output으로 돌려준 reviewPassed 값이고 수정 제안 검증은 요약과 제안이 비어 있지 않은지만 봅니다. 같은 입력에 늘 같은 결과를 내는 판정은 검증 명령의 종료 코드뿐입니다. 검토를 건너뛰는 문제는 그래프로 막을 수 있어도 검토가 허술한 문제는 남습니다.

규칙 자체는 그래프로 옮기지 않습니다. 예제도 대상 저장소의 AGENTS.md와 .workflow 문서는 항상 읽고 요청 분류 단계에서 React, CSS, 라우팅, 테스트 규칙 문서 중 필요한 것만 고릅니다. 문서는 규칙을 설명하고 그래프는 그 규칙을 언제 읽고 어디서 확인할지 정합니다. 규칙 문서를 작업 범위에 맞게 골라 읽히는 구조는 agent conventions에서 따로 다뤘습니다.

단계를 나눌수록 요청 하나에 드는 모델 호출도 늘어납니다. 예제는 단계의 성격에 따라 role별로 모델을 나눠 두고 호출 한도에 걸려 429 오류가 나면 정해진 순서로 다른 모델을 시도합니다. 개인이 직접 붙어서 탐색하는 일이라면 이 비용과 고정된 절차가 오히려 부담입니다.

여러 사람이 같은 방식으로 쓰거나 다른 프로젝트에서 재사용하거나 승인, 재시도, 검증을 반드시 지켜야 할 때 그래프의 가치가 생깁니다. 예제 저장소의 개선 로드맵도 같은 기준을 따릅니다. 규칙 문서를 선택형 지식 팩으로 나누고 규칙 선택을 넓히며 구현과 검증 stage를 분리하는 일을 앞에 둡니다. RAG는 문서가 수십에서 수백 개로 커질 때, MCP는 여러 앱이 규칙 자산을 공유할 때, A2A는 독립된 에이전트가 협업해야 할 때로 미룹니다.

확인 방법과 한계

근거는 2026년 3월에 정리한 SpecKit 적용 기록, LangGraph 비교 문서와 예제 저장소의 코드입니다. 예제 저장소는 이 글을 쓰면서 그래프 구조와 반복 한도를 코드로 대조했을 뿐 실행하지 않았습니다.

글에 쓴 측정값은 53분 하나입니다. phase 단위로 나눴을 때의 소요 시간, constitution 준수율, 그래프의 실행 성공률과 루프 반복 횟수, API 비용은 재지 않았습니다. 그래서 phase 단위가 더 빠르다거나 그래프가 더 정확하다는 결론은 내리지 않았습니다. SpecKit 적용 뒤 과제로 잡은 implement 실행 단위(전체, phase, task) 비교, 컨벤션 준수율, constitution 미준수 시 ralph loop 같은 반복 루프 도입 검토의 결과도 확인하지 못했습니다. 명령 이름과 단계는 당시 사용한 SpecKit 기준입니다.

참고 자료

• github/spec-kit
• Spec Kit: Specification-Driven Development (SDD)
• LangGraph: Graph API overview
• LangGraph: Interrupts
• LangGraph: Persistence
• AGENTS.md