명세서(Spec)가 결코 핵심이 아니었던 이유

🦄 이곳에 글을 쓴 지 꽤 시간이 흘렀습니다. 주로 어떤 주제가 머릿속을 스쳐 지나가지만, 완성하기도 전에 지루해지기 때문입니다. 그래서 이번 글은 제 코드 계획(code-planning) 워크플로우가 작성 단계에서도 유효한지 확인하기 위한 테스트로서 Claude에게 맡겨보았습니다. 스포일러를 하자면: 당신이 이 글을 읽고 있다면, 그것은 이미 성공했다는 뜻입니다.

우리는 사고 파트너(thought partner)를 고용하고 체크리스트(punch list)를 건네주었습니다 🪧

여기 우리 모두가 성숙한 방식이라고 동의한 워크플로우가 있습니다:

• 명세서(spec)를 작성한다.
• 에이전트(agent)에게 전달한다.
• 문서에 따라 빌드하도록 한다.
• 완료되면 차이점(diff)을 검토한다.

Spec Kit은 이 모든 과정을 위한 스캐폴딩(scaffolds)을 제공하며, Kiro는 이를 중심으로 전체 흐름을 구축합니다. 프롬프트를 입력하면 spec.md를 얻고, 계획을 얻고, 코드를 얻습니다. 이는 깔끔하고 추적 가능하며, 바이브 코딩(vibe-coding)과는 정반대의 모습입니다. 바로 그 점 때문에 판매하기가 매우 쉽습니다.

문제는 명세서(specs)가 아닙니다. 문제는 디자인을 가장한 일괄적 사고(batch thinking)입니다.

그러한 사고방식은 모델을 자판기처럼 취급합니다. 명세서를 입력하면 아래로 기능이 떨어져 나오고, 당신이 고민해야 할 유일한 것은 버튼을 제대로 눌렀는지 여부뿐입니다. 하지만 모델이 실제로 잘하는 것은 그런 것이 아닙니다. 모델은 아이디어가 여전히 모호하고 반쯤 형성된 초기 단계에서, AI가 당신과 함께 아이디어를 분해하기 시작할 때 훨씬 더 유용합니다. 모델은 당신이 생각하지 못한 사례를 지적하거나, 당신의 세 가지 계획 중 어떤 것이 나중에 문제를 일으킬지 알려줍니다.

우리는 추론(reasoning)에 진정으로 뛰어난 도구를 가져와 타이핑 업무에 투입했습니다.

우리가 건너뛴 단계 🪜

"문제가 있다"와 "이 기능을 빌드하라" 사이에는 대화라는 단계가 존재합니다. 당신의 원래 생각에 반론을 제기하는 대상과의 실시간 대화 말입니다. 바로 그 지점에서 실제 문제들을 발견하게 됩니다. 널 입력(null input) 문제나, "잠깐, 이 두 개가 동시에 실행되면 어떻게 되지?"와 같은 문제들입니다. 수정 비용이 저렴할 때는 좀처럼 질문할 생각을 못 하는 것들 말이죠. 그 단계를 건너뛴다면, 당신은 가장 중요한 부분을 건너뛴 것입니다.

알림 설정은 단순해 보이지만, 방해 금지 시간(quiet hours), 계정 수준의 기본값(account-level defaults), 프로젝트별 재정의(per-project overrides), 그리고 "그래도 중요한 알림은 보내줘"라는 설정이 모두 충돌하게 되면 상황이 달라집니다. 이때 생성된 명세서(spec)는 그중 하나를 조용히 왕으로 추대해 버립니다.

명세서를 사고의 기록(record of thought)이 아닌 사고 그 자체(the thinking)로 취급할 때 발생하는 일이 바로 이것입니다. 명세서는 당신이 어려운 부분에 부딪히기도 전에, 단 한 번의 시도로 모든 것을 적어 내려갑니다. 그러고 나면 사람들은 그 명세서가 '완료되었다'고 말하는 반짝이는 새 파일이 있다는 이유만으로, 사고 과정이 이미 끝났다고 간주해 버립니다. 채팅을 통한 계획 수립(Planning in chat)은 당신이 논쟁하도록 강제합니다. 하지만 생성된 명세서는 그저 받아쓰기(dictation)를 할 뿐입니다.

물론, 인간이 당신과 논쟁하는 것이 더 낫습니다. 하지만 반박(push back)을 하는 AI가, 마크다운(Markdown) 형식으로 그저 행복하게 고개를 끄덕이기만 하는 생성된 문서보다 훨씬 낫습니다.

생략이 드러나는 지점 🪞

모델은 50개의 포인트를 독립적으로 결정하지 않습니다. 모델은 초기에 하나의 경로를 결정하고, 그 이후의 모든 내용을 그 경로에 맞게 작성합니다. 따라서 그 명세서 문서가 검토를 위해 당신에게 도달했을 때쯤이면, 상단에 있는 하나의 잘못된 가정(assumption)이 이미 그 아래의 모든 내용에 영향을 미친 상태가 됩니다. 당신은 실제로 50개의 결정을 검토하는 것이 아니라, 하나의 결정을 50번 반복해서 검토하고 있는 셈입니다.

채팅에서는 갈림길(forks)을 실시간으로 하나씩 마주하게 됩니다. 모델이 초기에 방향을 잡으면, 당신은 모델이 멍청한 곳으로 향하는 것을 보고 그 즉시 방향을 재설정할 수 있습니다. 다음 10개의 결정이 잘못된 결정 위에 쌓이기 전에 말이죠. 이는 결국 검토 과정에서 잡아내게 될 문제와 동일하지만, 지금은 대충 훑고 지나간 50개 중 3번째 항목이 아니라 당신 앞에 놓인 유일한 과제가 됩니다.

일괄 생성된 명세서(batch spec)는 오류를 내포한 채 구워집니다. 대화는 갈림길에서 오류를 바로잡습니다.

당신이 강요하지 않으면 AI는 싸우지 않습니다 🥊

이 부분은 이미 제 모든 채팅에 녹아들어 있어서 거의 빼놓을 뻔했습니다. 저에게는 너무나 당연한 기본값이라 누군가에게 이를 명시적으로 설명할 필요가 있다고 생각조차 못 했습니다. 하지만 그러한 본능은 공짜로 얻어지는 것이 아닙니다. 기본 설정에 맡겨두면, 모든 모델은 '예스 머신 (yes-machine)'이 됩니다. 모델은 당신의 최악의 아이디어를 기꺼이 긍정하고 그 주변에 아름다운 명세서 (spec)를 구축할 것입니다. 왜냐하면 논쟁하는 것보다 동의하는 것이 더 쉽기 때문입니다. 그리고 상대방은 우연히 생기는 것이 아닙니다. 의도적으로 만들어지는 것입니다.

저는 제 설정이 이미 이 문제를 해결했다고 생각했습니다. 제 CLAUDE.md 파일에는 제가 남몰래 자랑스럽게 여겨온 한 줄이 있습니다:

틀렸을 때는 반박할 것. 예스 머신이 아닌 협업자(Collaborator)가 될 것.

그러고 나서 실제로 다시 읽어보니, 그 파일의 모든 규칙은 사후 반응적 (reactive)이었습니다. '틀렸을 때' 반박하고, '당신이 옳다는 것을 알 때' 크게 목소리를 내라는 식이었죠. 이 모든 것은 논쟁할 잘못된 답이 이미 존재할 때만 작동합니다. 설계가 아직 공중에 떠 있을 때, 즉 계획이 아직 실행되지 않아 실패조차 하지 않은 상태에서 모델에게 저와 싸우라고 지시하는 내용은 그 어디에도 없었습니다. 그 습관은 제가 실제로 일하는 방식에 들어있었을 뿐, 제가 기록한 것에는 없었습니다. 저는 파일에 넣지도 않은 기본값을 제가 만들어낸 것처럼 착각하고 있었던 것입니다.

그래서 저는 하나의 제한된 적대적 규칙 (adversarial rule)을 작성했습니다:

## 적대적 사고 (Adversarial Thinking)

- 계획 단계에서의 역할: 속기사(stenographer)가 아닌 반대자(opponent). 구현 이후가 아니라, 결정되지 않은 설계를 구현 전에 도전할 것.
...

'제한(bound)'은 이 규칙을 계속 사용할 수 있게 만드는 핵심입니다. 정지 조건이 없다면 '적대적'인 태도는 그저 '지치는' 태도로 변질될 뿐이며, 이미 결정된 모든 사항을 다시 재판(re-litigate)하는 모델은 모든 것에 동의하는 모델만큼이나 쓸모가 없기 때문입니다. 문제는 동일하지만, 기분만 더 나빠질 뿐이죠.

먼저 생각하고, 어쨌든 출시하라 🪶

명세서 (Spec)는 계약입니다. 다만 그것이 항상 사고(thinking)를 하기에 적절한 장소는 아닐 뿐입니다.

이것은 1인 플레이어의 논쟁입니다. 설계를 책임지는 한 명의 개발자가 전체 문제를 자신의 머릿속과 단 하나의 대화 속에 담아두는 상황 말입니다. 이는 12개의 서비스 마이그레이션이나 4개 팀 간의 인수인계처럼, 단 하나의 두뇌가 전체를 담을 수 없어 사람들이 논의할 공통의 장소가 필요한 상황이 아닙니다.

하지만 대화 속에 담길 수 있는 작업의 경우, 해결책은 명세서 (spec)를 금지하거나 더 많이 작성하는 것이 아닙니다. 대신 논쟁 (argument)을 다시 전면에 내세우는 것입니다.

• 모델이 실제로 잘하는 부분에 모델을 활용하세요.
• 기능을 명명하기 전에 디자인에 대해 논쟁하세요.
• 명세서가 포착해야 했던 사고 과정을 대신하는 대용품이 아니라, 사고의 부산물로서 자연스럽게 도출되도록 하세요.

생성된 spec.md가 당신에게 제공해 줄 것으로 기대되는 규율 (discipline) 말인가요? 모델이 너무 일찍 당신에게 동의하는 것을 거부하는 것만으로도 그 규율은 공짜로 얻을 수 있습니다.

이제 제가 실제로 답을 가지고 있지 않은 단 하나의 질문이 남았습니다. 가짜 답을 내놓는 대신 여러분께 넘기겠습니다. 이 방식이 단 한 명을 넘어 어떻게 확장 (scale)될 수 있을까요? 팀 단위의 규모에서 명세서는 단순한 빌드 대상 (build target)이 아닙니다. 그것은 채팅에 참여하지 않았던 모든 사람이 여전히 동의해야 하는 대상입니다. 저는 모델이 '나'와 싸우게 만드는 법은 압니다. 하지만 대화가 계약 (contract)의 역할을 수행하게 만드는 법은 아직 알아내지 못했습니다. 만약 여러분이 그 부분을 해결했다면, 꼭 듣고 싶습니다.

왜냐하면 핵심적인 부분은 결코 깔끔한 문서 안에 있었던 것이 아니라, 그 과정에서 우리가 나누었던 대화 속에 있었기 때문입니다.

🛡️ 논쟁을 통해 존재하게 함 (Argued Into Existence)

이 글은 이 글이 주장하는 바로 그 설정, 즉 제가 글로 써서 '나에게 동의하는 것을 멈추라'고 명령한 AI가 실제로 그렇게 하는 것을 지켜보며 압력 테스트 (pressure-tested)를 거쳤습니다. AI는 두 가지 취약점을 포착했고, 형태에 대해 논쟁했으며, 심지어 면책 조항 (disclaimer)을 쓰는 데 도움을 주는 뻔뻔함까지 보였습니다. 무례하지만 유용했습니다. 대부분의 문장은 AI가 작성했지만, 의견은 제 것입니다.