에이전트에게 주는 명세서: 아이디어를 작업으로 바꾸는 법

에이전트에게 요청을 두 번 연달아 보냅니다. 첫 번째는 "SPEC_LANDING.md 파일의 명세서대로 페이지를 만들어 주세요". 몇 분 뒤 폴더에 index.html이 생기고, 생각했던 모습 그대로입니다. 두 번째는 같은 날 저녁, "2048 게임 만들어 주세요". 그러자 에이전트는 질문을 다섯 개 연달아 던지거나, 아무 말 없이 5×5 판에 아무도 요청하지 않은 되돌리기 버튼까지 달아서 만들어 버립니다.

차이는 에이전트에 있지 않습니다. 에이전트가 입력으로 무엇을 받았느냐에 있습니다. 이 글에서는 작은 작업용 명세서가 무엇으로 이루어지는지, 거기에 적을 내용은 어디서 얻는지, 방향만 알고 있을 때는 어떻게 하는지, 그리고 "완료" 뒤에 왜 시작 전에 적어 둔 바로 그 줄들로 결과를 확인하는지 살펴봅니다.

1. 아이디어는 아직 작업이 아니다

"2048 만들고 싶어요". "예쁜 페이지 만들어 주세요". "좀 더 재미있는 새 게임 만들어 주세요". 모두 아이디어이고, 공통된 문제가 하나 있습니다. 여러분 머릿속에는 완성된 그림이 있는데, 글로 적힌 건 두 단어뿐이라는 점입니다. 에이전트가 보는 것은 글뿐입니다.

요청에 빈칸이 있으면 에이전트가 갈 수 있는 길은 두 가지입니다. 하나는 물어보는 것. 다른 하나는 스스로 채우는 것입니다. 판 크기를 고르고, 규칙을 만들어 내고, 버튼을 덧붙이는 식으로요. 두 번째 길은 조용하고, 그래서 더 위험합니다. 결과를 보기 전까지는 누군가 여러분 대신 결정했다는 사실을 알아채지 못합니다. 요청의 빈칸 하나하나가 누군가 내리게 될 결정이고, 기본적으로 그 사람은 여러분이 아닙니다.

"2048 하는 법은 누구나 안다"는 건 여러분 머릿속 이야기입니다. 에이전트는 그 "누구나 안다"를 읽지 못합니다. 판은 몇 칸인가? 새 타일은 어디서, 언제 나오나? 어떤 타일이 합쳐지고, 합쳐지면 무엇이 되나? 언제 이기고, 언제 끝나나? 여러분에게는 단어 하나지만, 에이전트에게는 규칙으로 풀어 적기 전까지 빈칸입니다. 채팅에서는 이렇게 보입니다.

나:       2048 게임 만들어 주세요
에이전트: 시작하기 전에 확인할게요.
          1. 판은 4×4인가요?
          2. 무엇을 승리로 볼까요?
          3. 되돌리기 기능이 필요한가요?

이건 좋은 경우입니다. 같은 요청에 이런 결과가 나올 때도 있습니다.

나:       2048 게임 만들어 주세요
에이전트: 완료했습니다. 게임은 index.html 파일에 있습니다.
          - 5×5 판
          - 마지막 수 되돌리기 버튼
          - localStorage에 저장되는 최고 기록표

에이전트의 실수가 아닙니다. 여러분이 남긴 빈칸 세 개가 여러분 없이 채워진 것입니다.

아이디어에서 믿을 수 있는 결과까지 가는 길은 이렇게 생겼습니다. 이 글도 이 길을 따라 왼쪽에서 오른쪽으로 진행합니다. 그리고 마지막 단계는 세 번째 단계로 돌아갑니다. 확인하고, 빈틈을 찾고, 명세서에 한 줄을 더 적고, 다시 에이전트에게 넘기는 거죠.

2. 내용은 어디서 오는가

페이지나 게임의 뼈대는 에이전트가 몇 분이면 만들고, 솔직히 그게 가장 어려운 부분은 아닙니다. 어려운 건 페이지에 무엇이 있어야 하는지, 애초에 무슨 게임을 하는지 아는 일입니다. 그건 코드 안에 없습니다. 사람들의 머릿속에 있고, 때로는 여러분 자신의 머릿속에 있으며, 일부는 에이전트도 압니다. 이것을 끌어내는 수단은 질문이고, 출처는 세 곳입니다. 사람들, 여러분 자신, 에이전트.

사람들이란 일을 맡긴 사람과 결과를 쓸 사람입니다. 이들에게는 질문을 한꺼번에 묶어서 하는 편이 좋습니다. 하루에 질문 하나씩이 아니라, 대여섯 개 항목을 목록으로 한 번에. 한꺼번에 보내면 귀찮게 구는 것처럼 보이죠, 압니다. 실제로는 모두에게 일주일 치 메시지 왕복을 줄여 줍니다.

의뢰인이 여러분 자신일 때(내 게임, 내 페이지)는 스스로에게 질문하게 되는데, 여기서 가장 큰 유혹은 "그건 당연하잖아"라고 넘기는 것입니다. 당연한 것도 당연하지 않은 것과 똑같이 적습니다. "판은 4×4"는 적는 데 2초면 되지만, 에이전트에게는 고민할 갈림길 하나를 통째로 없애 줍니다.

세 번째 출처는 에이전트인데, 여기에는 미리 알아 두면 좋은 함정이 있습니다. 모르는 것에 대해서는 질문할 수가 없습니다. 아무것도 움직이지 않은 수도 한 수로 칠까? 휴대폰에서 스와이프가 필요할까? 점수를 보여 줄까? 이런 질문은 게임이 눈앞에 놓이기 전까지 떠오르지 않습니다. 반면 에이전트는 이런 게임을 수천 개 봤고, 보통 어디서 막히는지 압니다. 그래서 "만들어 주세요" 대신 "먼저 같이 이야기해 봐요"로 시작하는 편이 나을 때가 있습니다.

브라우저에서 돌아가는 2048 게임을 만들고 싶어요. 아직 아무것도 작성하지 마세요.
시작하는 데 꼭 필요한 질문을 해 주세요. 한꺼번에, 목록으로.
제가 답하면, 그다음에 명세서를 SPEC_2048.md 파일로 정리해요.

이런 대화에는 규칙이 두 가지 필요합니다. 그렇지 않으면 끝나지 않습니다. 첫째, 대화는 다음 장에서 다룰 네 가지 기둥이 채워지면 끝나고, 그 결과물은 채팅이 아니라 파일입니다. 둘째, 에이전트의 질문은 선택지이지 요구 사항이 아닙니다. 에이전트는 "최고 기록표도 만들까요?"라고 기꺼이 묻겠지만, "아니요"도 정상적인 답입니다. 그 "아니요" 역시 명세서의 한 줄이 됩니다. 다만 "하지 않음"에 들어갈 뿐이죠.

그리고 어느 경우든, 여러분이 물었든 에이전트가 물었든, 답은 채팅 속 한마디로 남겨 두지 말고 명세서 파일에 적습니다. 그러지 않으면 다음 요청이 같은 빈틈에서 다시 시작됩니다.

왼쪽에 출처 세 곳, 오른쪽에 도착지 하나. 아래로 향하는 점선 화살표는 답이 가장 자주 빠져나가는 길입니다. 채팅에 남았다가 메시지 열 개쯤 지나면 더는 찾을 수 없게 되죠. 도식에 화살표는 있지만, 그 끝에 파일은 없습니다.

에이전트에게는 더 많은 것도 부탁할 수 있습니다. 질문만 하는 게 아니라, 여러분의 답을 바탕으로 여러분이 말하지 않은 부분까지 채워서 명세서 초안을 직접 써 달라고요. 에이전트가 덧붙여 채운 부분을 그다음에 어떻게 할지는 4장에서 다룹니다. 먼저 명세서가 무엇으로 이루어지는지부터 보겠습니다.

3. 명세서의 네 가지 기둥

작은 작업이라면 명세서는 6~8줄입니다. 이 줄들은 네 가지 기둥 위에 섭니다. 목표, 무엇이 일어나야 하는지, 첫 버전에 넣지 않을 것, 어떻게 확인할지. 게임용 명세서 전체는 이렇습니다.

# 명세서: 2048

목표:      브라우저 게임 2048, 파일에서 바로 열림, 설치 없음.
           HTML, CSS, JavaScript, 빌드 없음

규칙:      4×4 판
           시작할 때와 매 수 뒤에 새 타일이 나타남: 2 또는 4
           화살표 키로 모든 타일이 한 방향으로 끝까지 이동
           같은 타일 두 개가 부딪히면 합이 적힌 타일 하나로 합쳐짐
           승리: 판에 2048 타일이 나타남
           패배: 둘 수 있는 수가 없음, 판이 가득 차고 합칠 타일이 없음

하지 않음: 최고 기록표, 애니메이션, 되돌리기

확인:      브라우저에서 index.html을 열고 판과 시작 타일을 확인
           화살표 키로 세 수를 두고, 매번 새 타일이 나타나는지 확인
           2 두 개를 합쳐서 4를 만든다
           끝까지 플레이해서 패배 화면을 확인

이제 기둥을 하나씩, 그리고 각각을 두 작업에 적용해 보겠습니다. 게임, 그리고 보드게임 동호회 모임 초대 페이지입니다.

목표

첫 줄입니다. 이 줄을 읽은 사람이 코드가 아니라 결과를 떠올릴 수 있어야 합니다. "브라우저 게임 2048, 파일에서 바로 열림, 설치 없음". "동호회 모임 초대 페이지: 보는 사람이 어떤 모임인지 이해하고, 버튼으로 참가 신청을 한다".

목표를 점검하는 방법은 이렇습니다. 읽었을 때 사람이 보게 될 화면이 아니라 코드가 떠오른다면, 그건 이미 목표가 아닙니다. "타일 합치기 함수 만들기"는 목표가 아니라 작업의 한 조각입니다.

여기에 "무엇으로 만드는지"도 한 줄 넣습니다. HTML, CSS, JavaScript, 빌드 없음. 이 줄이 없으면 에이전트가 알아서 고르는데, 여러분이 실행할 줄 아는 것을 고른다는 보장은 없습니다.

반면 "예쁘게 만들어 주세요"는 목표가 될 수 없습니다. 누구 눈에 예쁜지, 어디서 그걸 확인할지 알 수 없으니까요.

무엇이 일어나야 하는가

가장 긴 기둥이고, 게임의 경우는 위에 이미 적혀 있습니다. 규칙은 하나입니다. 실행한 뒤에 보고 "예" 또는 "아니요"로 답할 수 있으면 좋은 줄입니다. "4×4 판"은 예 아니면 아니요. "같은 타일 두 개가 합이 적힌 타일 하나로 합쳐짐"도 예 아니면 아니요. "좀 더 재미있게"는 예도 아니요도 아니고, 그런 줄은 명세서에 있을 자리가 없습니다.

한 줄에 생각 하나. "타일이 나타나고 합쳐진다"는 확인 항목이 두 개이니, 줄도 두 개입니다.

페이지도 마찬가지인데, 규칙 대신 페이지에 무엇이 있는지를 적습니다. "이름과 날짜가 있는 헤더", "세 블록: 무엇을 하는지, 누구를 위한 모임인지, 어디서 하는지", "참가 신청 버튼을 누르면 신청 폼 주소로 이동". 하나하나 열어서 눈으로 볼 수 있습니다.

아이디어와 나란히 놓으면 이런 목록은 지루해 보입니다. 지루한 게 바로 좋은 겁니다. 지루한 건 확인할 수 있으니까요.

첫 버전에 넣지 않을 것

보통 잊어버리는 유일한 기둥이고, 그래서 가장 값진 기둥입니다. 빈칸은 에이전트가 스스로 채우는데, 가장 즐겨 쓰는 방법이 무언가를 덧붙이는 것입니다. 최고 기록표, 타일 애니메이션, 되돌리기 버튼, 다크 테마. 전부 쓸모 있고, 전부 여러분이 요청하지 않은 것입니다.

이름을 하나하나 적습니다. "쓸데없는 건 빼고"가 아니라(이건 경계가 아니라 바람일 뿐입니다) "하지 않음: 최고 기록표, 애니메이션, 되돌리기". 페이지라면 "하지 않음: 신청 폼 자체, 결제, 사진 갤러리". 보통 이름 세 개면 충분하고, 어차피 열 개씩 적는 사람은 없습니다.

이게 에이전트가 아니라 여러분에게 왜 필요한가. 만든 게 적을수록 확인할 것도 적습니다. 그리고 무언가 망가졌을 때 어디서 왔는지 알기 쉽습니다. 여섯 화면보다 여섯 줄에서 찾는 편이 쉬우니까요. 경계가 없다는 신호는 이것입니다. 여러분의 요청이나 에이전트의 답에 "하는 김에"라는 말이 자꾸 등장한다면요.

어떻게 확인할 것인가

"무엇이 일어나야 하는가"의 줄 하나하나가 에이전트가 "완료"라고 말한 뒤에 할 확인 하나입니다. 게임을 열었다. 4×4 판, 예. 화살표 키를 눌렀다. 타일이 움직이고 새 타일이 나타났다, 예. 2 두 개를 합쳤다. 4, 예. 확인 목록을 따로 쓸 필요가 없습니다. 이미 써 두었으니까요.

여기에 명세서 안에 "확인" 줄을 두세 개 더 적습니다. 손으로 정확히 무엇을 해 볼지입니다. "브라우저에서 파일을 열고, 세 수를 두고, 질 때까지 플레이한다". 이 줄은 요청 전에 적지, 요청 뒤에 적지 않습니다. 결과를 본 뒤에 적으면 나온 결과에 맞춰 슬그머니 고쳐 쓰게 됩니다. 저절로 그렇게 되고, 여러분도 예외는 아닐 겁니다.

에이전트의 "완료"는 한마디 말이지 확인이 아닙니다. 확인은 여러분이, 여러분이 적은 줄로 합니다.

이제 연습해 봅시다. "보드게임 동호회 모임용으로 예쁜 페이지 만들어 주세요"라는 요청을 네 가지 기둥으로 나눠 보세요. 기둥마다 한두 줄씩. 답은 바로 아래에 있으니 맞춰 보세요.

# 명세서: 초대 페이지

목표:        보드게임 동호회 모임 초대 페이지:
             보는 사람이 어떤 모임인지, 언제 어디서 하는지 이해하고 버튼으로 참가 신청을 한다.
             HTML 파일 하나, 스타일은 파일 안에

페이지 구성: 동호회 이름과 모임 날짜가 있는 헤더
             세 블록: 무엇을 하는지, 누구를 위한 모임인지, 어디서 하는지
             "참가 신청" 버튼을 누르면 신청 폼 주소로 이동

하지 않음:   신청 폼 자체, 결제, 사진 갤러리

확인:        브라우저에서 열고 헤더와 세 블록을 확인
             버튼을 눌러 신청 폼 주소로 이동하는지 확인

"예쁜"이라는 말은 명세서에 아예 들어가지 않았다는 점에 주목하세요. 확인할 수가 없기 때문입니다. 정말로 보기 좋은 게 중요하다면, 그것도 다른 것과 똑같이 줄로 풀어 적습니다. "헤더에 이미지 하나", "색은 두 가지 이하", "휴대폰 화면에 전부 들어감". 이제는 열어서 확인할 수 있습니다.

두 예시에서 블록 이름은 다릅니다. 게임은 "규칙", 페이지는 "페이지 구성". 이건 중요하지 않으니 편한 대로 이름을 붙이세요. 중요한 건 어느 쪽에나 네 가지 기둥이 있다는 점입니다.

4. 누구의 결정인가

명세서에는 아무도 합의하지 않은 결정이 들어가게 되는데, 그 경로는 두 가지입니다. 첫째, 답을 화요일까지 기다리지 않고 지금 초안을 받으려고, 빈틈을 "적당히 합리적인 것"으로 채우라고 에이전트에게 허락한 경우. 둘째, 물어볼 사람이 없거나 물어볼 시간이 없어서 여러분이 의뢰인 대신 직접 정한 경우.

두 경우 모두 괜찮습니다. 괜찮지 않은 건 그게 가정이라는 사실을 잊는 것입니다. 일주일만 지나도 버튼이 폼이 아니라 이메일로 연결되게 한 게 누구 생각이었는지 아무도 기억하지 못하고, 논쟁은 바로 그 지점에서 벌어집니다.

첫 번째 경우라면 에이전트에게 이렇게 요청합니다.

이 답변들을 바탕으로 초대 페이지 명세서 초안을 만들어 주세요.
답이 없는 부분은 합리적으로 정하고, 직접 정한 것은
별도 목록으로 정리해 주세요. SPEC_INVITE.md 파일에 저장해 주세요.

덧붙여 정한 것들의 목록은 명세서 본문보다 먼저 읽습니다. 여러분 대신 내려진 결정들이니까요. 각 항목은 사정을 아는 사람에게 확인을 받으러 가거나, 표시를 단 채로 명세서에 남습니다.

두 번째 경우에는 파일 안에 직접 표시합니다. 결정 앞에 "가정:"이라고 적거나, 그냥 줄 끝에 물음표를 붙입니다. "버튼은 동호회 이메일로 연결 (?)". 답이 오면 무엇을 고쳐야 할지 바로 보입니다. 이게 어디서 나왔는지 떠올릴 필요도 없고요.

이 표시는 양쪽 모두에게 효과가 있습니다. 물음표가 달린 명세서를 받은 에이전트는 보통 그 부분부터 먼저 묻습니다. 에이전트에게도 여러분에게와 똑같은 신호이기 때문입니다.

5. 질문 대신 샌드박스

아무리 붙잡고 있어도 네 가지 기둥이 써지지 않을 때가 있습니다. "2048 비슷한 걸 원하는데, 점수가 필요한지, 스와이프가 필요한지, 애초에 4×4인지도 모르겠다". 이건 명세서가 아니고, 흔히 말하는 아이디어조차 아닙니다. 그저 방향입니다. 어느 쪽으로 갈지는 알지만 결과는 모르는 상태. 여기서는 질문이 도움이 되지 않습니다. 여러분에게도 의뢰인에게도 아직 답이 없고, 에이전트가 내놓는 선택지는 비교할 기준이 없으니까요.

이럴 때는 직접 보는 게 가장 싸게 먹힙니다. 샌드박스를 만드는 겁니다. 보고, 만져 보고, 실제로 무엇을 원하는지 알 수 있는 가장 단순한 버전이요. 에이전트와 함께라면 10분이면 되고, 10분짜리라서 결과물을 버려도 아깝지 않습니다.

샌드박스에도 네 가지 기둥으로 된 명세서를 씁니다. 목표만 다를 뿐입니다.

# 명세서: 2048 샌드박스

목표:      브라우저에서 2048이 어떻게 플레이되는지 보고, 내가 무엇을 원하는지 파악한다.
           HTML, CSS, JavaScript, 빌드 없음

규칙:      4×4 판
           화살표 키로 타일이 움직이고, 같은 타일은 합쳐짐
           수를 둔 뒤 새 타일이 나타남

하지 않음: 나머지 전부: 승리, 패배, 점수, 스와이프, 디자인

확인:      5분 동안 플레이하고, 부족한 것과 필요 없는 것을 적는다

무엇이 달라졌는지 보세요. 목표는 게임이 아니라 이해입니다. "하지 않음"이 가장 긴 줄이고, 확신이 없는 건 전부 여기에 들어갑니다. 그리고 확인은 "동작하는가"가 아니라 "이제 무엇을 알게 됐는가"입니다. 5분만 플레이해 보면 처음에는 할 수 없었던 질문이 저절로 떠오릅니다. 스와이프는 필요 없다, 컴퓨터에서는 화살표 키로 한다. 점수는 필요하다, 없으면 지루하다. 4×4는 작다, 5×5도 해 보고 싶다. 패배는 보여 줘야 한다, 안 그러면 게임이 끝났는지 알 수 없다.

이게 바로 샌드박스의 결과물입니다. 코드가 아니라 답. 이 답으로 진짜 명세서를 쓰고, 진짜 버전은 깨끗한 폴더에서 처음부터 한 문장으로 만듭니다. "파일에 있는 명세서대로 게임을 만들어 주세요". 샌드박스는 제 할 일을 다 했습니다.

1장에서 본 것과 같은 흐름인데, 여기서는 "질문" 단계를 루프가 대신합니다. 물어볼 것이 없을 때는 먼저 보고, 그다음에 적습니다. 아래의 명세서로 내려가는 것은 딱 하나, 답입니다. 샌드박스에서 에이전트로 가는 화살표가 없는 건 빠뜨려서가 아닙니다. 에이전트는 진짜 버전을 깨끗한 폴더에서 처음부터 만듭니다. 그다음은 전부 흐름대로입니다.

6. 명세서는 파일에 둔다

왜 대화가 아니라 파일인가. 대화는 흘러가 버립니다. 메시지 열 개만 지나도 타일 합치기 규칙을 더는 찾을 수 없습니다. 파일은 프로젝트 폴더 안 코드 옆에 있고, 여러분이 가리키면 에이전트가 직접 읽으며, 고친 뒤에는 같은 한 문장으로 다시 넘길 수 있습니다. 이름은 아무거나 괜찮습니다. SPEC_2048.md, SPEC_LANDING.md, 심지어 task.txt여도 됩니다. 평범한 텍스트 파일이고, 특별한 형식 같은 건 없습니다.

넘길 때는 한 문장이면 됩니다. 비교해 보세요.

이전: "2048 게임 만들어 주세요, 무슨 말인지 아시죠, 좀 더 재미있게".

이후: "SPEC_2048.md 파일의 명세서대로 게임을 만들어 주세요".

두 번째 요청은 첫 번째보다 짧지만, 담긴 정보는 열 배쯤 많습니다. 정보가 파일에 있으니까요. 명세서 내용을 채팅에 복사해 붙일 필요는 없습니다. 에이전트가 파일을 직접 엽니다.

무엇은 파일에서 고치고, 무엇은 채팅으로 말해도 될까. 기준은 이렇습니다. 규칙이나 경계가 바뀌었다면 파일을 고치고 다시 넘깁니다("승리는 1024가 아니라 2048에서"는 파일로). 규칙에 영향을 주지 않는 겉모습의 사소한 변경이라면 채팅으로 말해도 됩니다("버튼을 파란색으로 해 주세요"). 애매하면 파일로. 한 줄 더 적는 편이 규칙 하나를 잊는 것보다 쌉니다.

분량에 대해서. 작은 작업이라면 위의 2048 블록처럼 6~8줄입니다. 하룻저녁에 만들 게임의 명세서가 두 페이지로 늘어났다면, 아마 "하지 않음"에 들어가야 했을 것이 들어가 있을 겁니다.

그리고 마지막으로, 파일을 에이전트에게 넘기기 전에 남이 쓴 글처럼 한 번 읽어 보세요. 확인할 수 없는 줄이 거의 언제나 하나쯤은 나옵니다. 제 명세서에서도 매번 나옵니다.

7. 에이전트가 명세서로 하는 일, 여러분에게 남는 일

전부 정리해 봅시다. 이 흐름에서 Claude Code가 하는 일과 여러분 쪽에 남는 일을 짝지어 보면 이렇습니다.

명세서의 핵심은 에이전트가 알아듣게 하는 데 있지 않습니다. 에이전트는 두 단어만 받아도 뭔가를 만들어 냅니다. 핵심은 여러분 스스로 무엇을 요청했는지 알고, 그것을 확인할 수 있게 하는 데 있습니다.