1. 왜 코드보다 문서가 먼저인가

AWS의 시니어 개발자 애드보킷 에릭 핸쳇이 *명세 주도 개발을 소개한다. 정의는 한 줄이다. 코드를 한 줄도 쓰기 전에 요구사항과 설계 문서를 마크다운 파일로 먼저 만든다.

왜 그래야 하는지를 발표자는 인턴에 빗댄다. 코딩 어시스턴트는 AI 인턴이고, 여지를 조금만 주면 궤도를 벗어난다는 것이다. 자기 첫 직장 이야기를 든다. 부사장이 돌아다니며 즉흥적으로 아이디어를 던지면 하던 일을 다 놓고 그것부터 했다. 나중에 상사한테 들은 것은 받아 적어 일정에 넣고 매니저와 먼저 상의하라는 말이었다. 지금 언어 모델이 하는 짓이 그때 자기가 한 짓이라고 말한다.

최신 프런티어 모델이면 다 알아서 해 주지 않느냐는 물음도 자주 받는다고 한다. 모델이 해마다 좋아지고 있지만 아직 완벽하지 않고, 소프트웨어와 요구사항이 계속 바뀌므로 맥락을 더 주는 일이 방향을 잡는 데 쓸모가 있다는 답이다. 일부 모델과 하네스가 코드를 쓰기 전에 생각하거나 계획하는 모드를 넣기 시작했지만, 문서를 실제로 만들어 놓고 사람이 그 사이에 들어가는 것만 한 것은 없다고 말한다.

2. 맥락은 많이 줄수록 좋은가

발표자는 여기부터가 자기 의견이라고 미리 못 박는다.

첫째가 맥락이다. 명세 주도 개발이 모델에 맥락을 많이 넣어 주는 방식인데, 좋은 것도 지나치면 문제가 된다고 말한다. 보통 시작할 때 agents.md 같은 파일에 정보를 적어 두는데, 너무 많이도 너무 적게도 넣지 않는 골디락스 존을 지키라는 것이다. 키로에서는 이 파일을 *스티어링 문서라고 부른다.

둘째가 *스킬이다. 키워드가 잡히면 켜지거나 슬래시 명령으로 직접 부르는 지시 파일인데, 설계 문서를 만들 때든 작업을 구현할 때든 명세 주도 개발과 함께 쓰라고 권한다.

셋째가 신뢰다. 이 흐름 전체에서 생성된 코드의 리뷰어는 사람이고, 문제가 생기면 비난받는 쪽도 에이전트가 아니라 사람이다. 그래서 설계 문서와 요구사항 문서를 계속 들여다봐야 한다고 말한다. 사람 혼자 다 보라는 뜻은 아니고, 평소 쓰던 AI 리뷰 도구로 풀 리퀘스트를 검토하는 것은 그대로 하라고 덧붙인다.

셋을 한 줄로 묶으면 이렇다. 맥락은 사람이 재고, 코드도 사람이 보고, 책임도 사람이 진다.

3. 키로 없이 하려면 무엇을 시키나

AWS가 키로를 만든 배경을 발표자는 이렇게 말한다. 팀과 고객들이 *바이브 코딩을 쓰고 있었지만 원하는 결과가 안 나왔고, 그러다 보니 고객들이 저마다 에이전트에게 요구사항 문서와 설계 문서를 먼저 쓰게 하는 패턴을 만들어 쓰고 있었다. 그것을 대신 해 주는 애플리케이션을 만들기로 한 것이 키로다. 작년 말 일반 공개로 나왔고 CLI 버전도 함께 냈다. 지금은 IDE보다 CLI를 쓰는 쪽이 늘고 있다고 말한다.

kiro.dev를 열었을 때 다운로드가 수만 건 몰렸고, 프리뷰 때는 신청이 너무 많아 게이트를 걸었는데 사람들이 우회하는 길을 찾아냈다고 한다. 이 발표에서 나오는 유일한 숫자다.

발표자는 이 자리가 키로 홍보로만 끝나는 것을 원하지 않는다며 도구 없이 하는 길을 먼저 댄다. 어시스턴트에게 사용자 요구사항을 만들라고 시키거나 내가 쓴 요구사항을 근거로 주고, 그것을 확인한 다음 설계 문서를 만들게 하고, 다시 확인한 다음 요구사항과 설계를 근거로 작업 목록을 만들게 한다. 깃허브가 낸 오픈소스 방식인 스펙 킷도 여러 코딩 어시스턴트에 설치해 쓸 수 있다고 소개한다.

4. 키로가 더한 것은 무엇인가

키로 IDE에서는 스펙을 고르고, CLI에서는 계획 모드를 쓴다. 프롬프트는 「본 영화를 기록하는 무비 MCP 서버를 만들어 줘」 정도로 넣으면 된다.

새 프로젝트에만 맞는 방식이 아니냐는 물음에는 아니라고 답한다. 몇 년 된 앱에 스펙 파일이 수십 개씩 쌓여 있는 것을 봤다고 말한다. 깊이 있는 기능이나 사전 계획이 더 필요한 프로젝트에 맞고, 버그 수정용 스펙 모드도 붙였지만 작은 건은 그냥 바이브 코딩이 나을 수 있다고 말한다.

스펙 모드가 만드는 문서 셋

셋 다 발표자가 화면으로 보여 준 것이고, 재서 낸 값은 아니다. 요구사항과 설계 중 어느 쪽부터 시작해도 되고 둘을 합쳐 쓰는 사람도 있다고 한다. 최근에는 확인 질문의 답을 근거로 문서를 한 번에 뽑아 주는 퀵 플랜 모드도 붙였다.

발표자가 문서를 손보라고 말하는 대목의 근거는 한 문장이다. 넣은 만큼만 나온다는 것이다.

데모는 시간 관계상 새 프로젝트를 만들지 않고 미리 만들어 둔 영화 데이터베이스로 돌린다. 이번에는 요구사항 대신 설계부터 시작하라고 시켰고, 아키텍처와 시퀀스를 그린 머메이드 다이어그램이 여러 장 나왔다. 문서 아래쪽에 붙은 속성 기반 테스트는 타입스크립트·노드 쪽의 fast-check로 값을 바꿔 가며 수십 번에서 수백 번씩 돈다. 요구사항 문서에는 「요구사항 1, 영화 데이터 로딩 — 애플리케이션이 초기화되면 필터 엔진이 로드된다」처럼 적힌다.

MVP를 만들어 달라고 하자 작업 목록이 다시 짜였고, 「1번부터 4번까지가 동작하는 MVP를 만든다 — 검색·장르 필터링·정렬이 되는 영화 그리드와 80년대풍 신스웨이브 테마 전체」라고 목록에 그대로 적혔다. 장르 필터링에 붙은 속성 기반 테스트는 어떤 영화 데이터셋을 넣어도 뽑힌 장르 목록이 정렬된 고유 장르 집합이어야 한다는 조건을 건다.

5. 남이 써 둔 요구사항은 어떻게 들어오나

발표자는 *MCP를 명세 주도 개발에 붙이는 이유를 하나로 든다. 지라나 아사나에 쌓인 티켓과 요구사항 문서를 스펙을 만들 때 그대로 끌어올 수 있다는 것이다. 프로덕트 매니저가 이미 써 놓은 요구사항 문서가 있으면 그것을 가져다 쓴다. 어느 프로젝트 관리 서비스든 마찬가지라고 말한다.

가져오게 시키는 방법은 둘이다. 스티어링 문서나 agents.md에 이 MCP 서버에서 정보를 가져오라는 규칙을 넣어 두거나, 첫 걸음에서 요구사항을 만들 때 이 서버를 보라고 직접 지정한다.

MCP가 나온 지 여섯 달인데 벌써 끝난 것 아니냐는 물음도 받는다고 한다. 명령줄 도구만으로 비슷한 것을 할 수 있다는 의견이 있다는 것도 안다면서, 아직 성숙해 가는 중이고 특히 보안 쪽으로 갈 길이 멀다고 답한다.

6. 발표가 밝히지 않은 것

성능·비용·지연·정확도 수치가 하나도 없다. 명세를 먼저 쓰면 품질이 올라간다는 것이 발표의 주장인데, 그렇게 만든 코드가 무엇을 기준으로 얼마나 나아졌는지 재서 보여 준 자리가 없다. 견주는 기준선도 없다. 바이브 코딩과 명세 주도 개발을 같은 과제에 나란히 놓고 잰 결과는 나오지 않는다. 발표 전체에서 나온 숫자는 다운로드 수만 건, 경력 15년, MVP 작업 네 개, MCP가 나온 지 여섯 달뿐이다.

골디락스 존의 경계도 없다. 정보를 너무 많이도 너무 적게도 넣지 말라는 말은 있는데, 무엇을 보고 많다고 판단하는지가 없다. 이 방식에서 사람이 제일 자주 헤매는 자리가 여기라 아쉬운 대목이다.

문서를 만들고 손보는 데 드는 시간도 다루지 않는다. 요구사항과 설계를 사람이 앞뒤로 오가며 고치라는 것이 이 방식의 핵심인데, 그 시간이 바로 코드를 짜는 것보다 얼마나 더 걸리는지, 언제 그 시간이 아깝지 않은지가 발표에 없다. 깊이 있는 기능과 복잡한 프로젝트에 좋다는 말이 그 자리를 대신한다.

속성 기반 테스트가 요구사항 문서를 근거로 만들어진다는 설명도 그 이상 들어가지 않는다. 요구사항 문장이 어떻게 테스트 조건으로 바뀌는지, 문서 자체가 틀렸을 때 그 테스트가 무엇을 지켜 주는지는 발표가 설명하지 않는다.

데모는 실패 없이 지나갔고, 발표자가 스스로 밝힌 한계는 「넣은 만큼만 나온다」 한 문장이다.