코딩 에이전트와 spec-kit 그리고 SDD
Claude Code, Gemini, Copilot, Codex 등 수많은 코딩 에이전트들이 있지만, 코딩 에이전트를 사용하며 개발을 하다보면 수렴적으로 알게되는 문제가 있음.
전통적인 개발 방식에서는 사람이 개발 의도를 기억하거나, 이미 만들어진 개발 명세서가 있기 때문에 문제가 없으나 코딩 에이전트를 사용하면 소스 코드들의 개발 의도를 기억하지 못하게 됨.
개발 의도를 기억하지 못하는 코딩 에이전트들은 요구 사항에만 맞춰서 개발하는 경향이 있기 때문에 설계 의도를 따르지 않고 반드시 필요한 코드를 파괴하거나, 수정해버리는 문제가 빈번히 발생하곤 함.
이에 따라서 명세 주도 개발(SDD) 도입의 필요성이 두각 되었고 spec-kit 이라는 시도가 등장
spec-kit 은 “코드 보다 명세서를 먼저” 라는 워크플로우를 제시하여, 우선 개발 명세를 작성한 후에 명세서에 따라서 계획, 작업 구체화, 구현을 일관적으로 진행하도록 만듦
설치 방법
해당 글은 모두 MacOS/Linux 를 기준으로 작성.
Windows 환경에서 npm 명령어를 이용하면 Codex CLI 를 설치할 순 있으나, 필자가 직접 사용해본 결과, 버그와 오류가 많기 때문에 아직 사용하기엔 매우 부적절한 상태라고 판단됨.
이에 따라 OpenAI 에서도 Windows 환경에서는 WSL 를 사용하도록 권장하고 있으므로 WSL Linux 환경에서 사용할 것.
Codex CLI 설치
npm install -g @openai/codex
Shell
복사
spec-kit 설치
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Shell
복사
프로젝트 초기화
# 새로운 프로젝트를 만들면서 초기화
specify init <PROJECT_NAME> --ai codex
# 혹은 기존 프로젝트에서 spec-kit 초기화
cd <PROJECT_NAME>
specify init . --ai codex
# 커맨드 및 플러그인 설치가 제대로 이루어졌는지 확인
specify check
Shell
복사
사용 방법
Start Codex CLI
작업할 프로젝트 경로에서 이하의 명령어를 실행
#
# CODEX_HOME 환경변수를 지정하지 않으면,
# `/` 기반의 spec-kit 커스텀 커맨드를 사용할 수 없음.
#
# 이 내용은 Codex 개발자들이 지원 가능하도록 개발 중인 기능이므로,
# 릴리즈가 될 때 까진 CODEX_HOME 환경변수를 지정해야 함.
#
export CODEX_HOME=$PWD/.codex
codex
Shell
복사
이후 최초 1회 혹은 거버넌트 수정이 필요할 때만 개발 지침 정의 단계를 수행하며, 개발은 기능 명세 정의 → 작업 계획 → 작업 목록 작성 → 구현 단계를 계속 반복하며 개발하면 됨.
다른 에이전트에는 명령어 사용을 위해서 /prompts: 접두사를 사용할 필요가 없으나, 현재 Codex CLI 에서는 커스텀 커맨드를 사용하기 위해서 접두사가 필요
개발 지침 정의
앞으로의 모든 개발을 이끌 개발 지침을 정의
/prompts:speckit.constitution "항상 TDD 규칙을 준수, 유닛 테스트 필수, 테스트 커버리지 >= 80% 유지, 논리 작업 단위로 커밋, 린트/포맷/유닛/통합테스트를 모두 통과할 때만 커밋"
Shell
복사
기능 명세 정의
만들고자 하는 것을 서술하여 기능 명세를 정의
기술 스택을 적지 않고 무엇을 할지, 왜 하는 지에 초점을 맞춰서 작성
/prompts:speckit.specify "JSON 요청을 받으면 요청 내용을 그대로 반환하는 에코 서버의 개발"
Shell
복사
기능 명세 구체화
이 단계는 필수는 아니지만 진행하면 좋음
기능 명세를 정의하는 과정에서 모호한 기능이 존재한다면, 사용자와의 질의/응답을 통해 기능 명세를 명확하게 구체화
/prompts:speckit.clarify
Shell
복사
작업 계획
기능을 만들 기술 스택과 아키텍처를 제시
/prompts:speckit.plan "백엔드는 Go 언어 기반, 서버 프레임워크는 gin-gonic 사용, 도메인 주도 설계 아키텍처 적용"
Shell
복사
작업 목록 작성
계획 단계에서 만든 구현 계획을 바탕으로 실행 가능한 작업 목록을 생성
/prompts:speckit.tasks
Shell
복사
구현
모든 작업 목록을 실행하고 계획에 따라서 기능을 개발
/prompts:speckit.implement
Shell
복사
