Spec-Driven Development 실전 운영법: spec.md와 plan.md를 에이전트의 단일 진실로 쓰기

Google은 2026년 7월 16일 Conductor가 Gemini CLI extension에서 plugin으로 진화했고, Antigravity CLI 같은 다른 도구에서도 Spec-Driven Development를 지원한다고 발표했다. 글의 핵심은 명령어 몇 개가 아니다. AI 코딩 작업의 컨텍스트를 ephemeral chat log가 아니라 version-controlled markdown artifact로 옮기는 방식이다. spec.md와 plan.md가 repository 안의 단일 진실이 되는 구조다.

실무 개발팀에게 이 변화는 꽤 중요하다. 코딩 에이전트는 긴 대화에서 쉽게 방향을 잃고, 세션이 바뀌면 이전 결정을 잊고, 같은 요구사항을 다르게 해석한다. Spec-Driven Development는 이 문제를 “프롬프트를 더 길게 쓰기”가 아니라 “결정을 파일로 남기기”로 푼다.

왜 채팅 로그만으로는 부족한가

채팅 로그는 협업 기록으로 좋지만, 코드베이스의 진실로 쓰기에는 약하다. 길어질수록 읽기 어렵고, 특정 결정이 언제 바뀌었는지 추적하기 어렵고, 다른 도구나 에이전트가 이어받기 힘들다. 무엇보다 git review 대상이 아니다.

반면 spec.md와 plan.md는 repository에 남는다. PR diff로 볼 수 있고, branch마다 다르게 유지할 수 있으며, 코드 변경과 함께 리뷰할 수 있다. 에이전트가 바뀌어도 같은 파일을 읽고 작업을 이어갈 수 있다. Google의 Conductor Plugin 설명도 이 지점을 강조한다. 프로젝트 아키텍처, 가이드라인, 목표를 담은 foundational document가 tool을 넘어 유지되는 것이다.

spec.md에 들어가야 할 것

좋은 spec은 요구사항 목록이 아니다. 구현자가 헷갈리지 않도록 의사결정과 제약을 담아야 한다. 최소 항목은 다음이다.

문제 정의: 사용자가 겪는 구체적 문제
목표: 이번 변경으로 달성할 결과
비목표: 이번에 하지 않을 일
사용자 흐름: 입력, 상태, 출력
데이터 모델: 새 필드, 변경 필드, migration 필요 여부
API 계약: request, response, error shape
UI 상태: loading, empty, error, success
접근성·보안 제약
성능 기준
테스트 기준

중요한 건 비목표다. 에이전트는 목표를 넓게 해석하는 경향이 있다. “결제 화면 문구 수정”을 맡겼는데 pricing logic까지 건드리면 사고다. spec에 비목표를 명시해야 범위가 닫힌다.

plan.md는 task list가 아니라 실행 순서다

plan.md는 체크박스 목록이지만, 단순 TODO가 아니다. 의존성 순서와 검증 단계를 포함해야 한다. 좋은 plan은 이렇게 생겼다.

현재 코드 경로와 관련 테스트를 찾는다.
데이터 모델 변경이 필요한지 확인한다.
UI 상태별 변경 범위를 쪼갠다.
가장 작은 파일부터 수정한다.
unit test를 추가하거나 기존 테스트를 갱신한다.
lint, typecheck, targeted test를 실행한다.
diff를 읽고 spec 충족 여부를 확인한다.
PR 설명에 변경점과 미해결 리스크를 쓴다.

에이전트에게 중요한 건 “다음에 뭘 해야 하는지”가 항상 파일에 남아 있다는 점이다. 세션이 끊기거나 다른 도구로 넘어가도 plan에서 복구할 수 있다.

자연어 대화와 절차적 엄격함을 같이 가져간다

Conductor Plugin은 strict command sequence를 줄이고 자연어 대화로 spec과 plan을 업데이트한다고 설명한다. 이 방향은 맞다. 개발자가 매번 /spec, /plan, /task 같은 절차를 외우면 도구가 부담이 된다. 대신 대화 중 요구사항이 정해지면 플러그인이 파일을 갱신하고, 완료된 task를 체크하고, architecture context를 보존하는 편이 낫다.

하지만 자연어가 편해졌다고 절차가 사라지는 것은 아니다. 오히려 파일이 자동 갱신되기 때문에 리뷰 기준이 더 중요해진다. spec 변경과 코드 변경이 같은 PR에 섞이면, reviewer는 “요구사항을 바꿔서 통과시킨 것인지”를 봐야 한다. 에이전트가 테스트에 맞춰 spec을 후퇴시키는 상황도 막아야 한다.

여러 도구를 쓰는 팀의 포터빌리티 전략

실제 팀은 하나의 AI 도구만 쓰지 않는다. 어떤 개발자는 Claude Code를 쓰고, 어떤 개발자는 Gemini CLI를 쓰고, 어떤 자동화는 GitHub Copilot을 쓴다. tool-specific memory에 의존하면 컨텍스트가 분산된다. repository 내부 markdown artifact는 이 문제를 줄인다.

리뷰에서 봐야 할 항목

Spec-Driven Development는 문서가 늘어나는 방식이 아니다. 코드 리뷰 품질을 올리는 방식이어야 한다. PR reviewer는 다음을 확인한다.

spec의 목표와 code diff가 일치하는가
비목표를 건드린 파일이 없는가
plan의 완료 체크가 실제 테스트 결과와 일치하는가
API 계약 변경이 문서와 테스트에 반영됐는가
에이전트가 임의로 scope를 늘리거나 줄이지 않았는가
실패한 테스트를 spec 변경으로 회피하지 않았는가

이 확인이 없으면 spec 파일은 장식이 된다. 파일은 만들었지만 의사결정은 여전히 채팅방에 떠다니는 상태가 된다.

실행 체크리스트

새 기능마다 spec.md와 plan.md를 먼저 만든다.
spec에는 목표보다 비목표를 더 명확히 쓴다.
plan에는 수정 순서와 검증 명령을 포함한다.
코드 변경 PR에는 spec·plan diff를 같이 올린다.
요구사항 변경은 별도 커밋으로 분리한다.
reviewer는 코드뿐 아니라 spec 후퇴 여부를 본다.
여러 AI 도구가 읽을 공통 문서는 repository 안에 둔다.
작업 종료 시 plan의 남은 항목과 미해결 리스크를 남긴다.

출처: Google Developers Blog, “Evolving Spec-Driven Development: Conductor Now Supports Antigravity”