Claude Code나 Codex에 작업을 맡기기 전에 스펙 파일 3개부터 만드세요

AI 코딩 에이전트를 일주일 이상 써보셨다면 아마 이런 경험이 있으실 겁니다. 똑같은 작업인데 월요일에는 깔끔한 결과물이 나오고, 화요일에는 엉망이 됩니다. 프롬프트는 거의 그대로고 코드베이스도 바뀐 게 없습니다. 그런데 결과는 완전히 다릅니다.

저는 거의 1년 동안 이 문제를 쫓아다녔습니다. 더 나은 프롬프트, 더 상세한 지시, 다른 모델을 시도해봤습니다. 하지만 핵심 문제는 해결되지 않았습니다. 진짜 원인은 의도를 전달하는 구조화된 방식이 없었다는 것입니다. 프로젝트 규칙, 기능 요구사항, 작업 단계, 코딩 컨벤션까지 모든 것을 프롬프트 하나에 담으려 했습니다. 단일 입력이 감당하기엔 너무 무거운 짐이었습니다.

해결책은 생각보다 단순했습니다. 지시사항을 세 가지 레이어로 나누어 각각의 파일에 담는 것이었습니다. 이 방식으로 바꾼 후 세션 간 품질 격차가 대부분 사라졌습니다.

파일 하나로는 왜 무너지는가

LLM의 지시 따르기에 관한 연구에서 “지시의 저주(Curse of Instructions)“라는 패턴이 발견된 바 있습니다. 단일 컨텍스트에 지시사항 수가 많아질수록 각 개별 지시에 대한 준수율이 급격히 떨어집니다. 직접 실험해봤을 때도 마찬가지였습니다. 프로젝트 규칙, 기능 스펙, 작업 목록을 하나의 CLAUDE.md 파일에 몰아넣었더니 에이전트는 문서 후반부 지시사항의 절반 정도를 무시했습니다.

어텐션 메커니즘을 생각해보면 이해가 됩니다. 다양한 관심사가 뒤섞인 긴 문서는 모델이 실시간으로 무엇이 중요한지 판단하게 만듭니다. 그 과정에서 잘못된 우선순위 결정이 발생합니다. 해결책은 정보를 역할별로 분리하여 각 레이어가 집중력을 유지하도록 하는 것입니다.

레이어 1: 프로젝트 헌법으로서의 CLAUDE.md

CLAUDE.md(또는 에이전트에 해당하는 파일)는 모든 세션에서 자동으로 로드됩니다. 그렇기 때문에 기능별 지시를 넣을 자리가 아닙니다. 프로젝트 전체에 걸쳐 항상 참인 것들만 담아야 합니다.

• 빌드 커맨드와 기술 스택 버전
• 폴더 구조와 네이밍 컨벤션
• 행동 규칙 세 단계: “항상 할 것”, “먼저 물어볼 것”, “절대 하지 않을 것”

처음부터 생각나는 모든 것을 이 파일에 쏟아붓지 않는 것이 중요합니다. 대신 에이전트가 반복적으로 실수하는 부분을 관찰하고 규칙을 점진적으로 추가하는 방식이 훨씬 잘 정착됩니다. 처음부터 완벽하게 명세하려는 접근보다 효과적이었습니다.

CLAUDE.md에 넣지 말아야 할 것들도 있습니다. API 키는 금방 만료됩니다. 코드 스니펫은 실제 코드와 점점 어긋납니다. 린터가 이미 처리하는 스타일 규칙, 그리고 특정 기능 하나에만 해당하는 내용은 다음 레이어에 넣어야 합니다.

레이어 2: ‘무엇’과 ‘왜’를 담은 SPEC.md

스펙 파일은 기능 하나를 설명합니다. 이 기능이 무엇을 하는지, 왜 존재하는지, 성공 기준이 무엇인지, 기술적 제약은 무엇인지, 경계는 어디까지인지를 답합니다. 딱 다섯 섹션입니다.

전통적인 PRD와의 결정적 차이점은 스펙 파일이 회의용이 아니라 에이전트 소비용으로 구조화된다는 점입니다. 그리고 의도적으로 ‘어떻게’를 생략합니다. 구현 방법은 에이전트가 기존 코드베이스를 분석해서 스스로 결정해야 합니다. 스펙에서 단계별 코딩 지시를 제공하는 방식은 역효과를 냅니다.

좋은 스펙을 작성하는 방법은 두 가지입니다. 위의 다섯 섹션 구조를 활용해 직접 작성하거나, 에이전트가 인터뷰하도록 할 수 있습니다. 인터뷰 방식은 두 가지 규칙을 지켰을 때 놀라울 정도로 잘 작동합니다. 한 번에 질문 하나씩, 그리고 개방형보다 선택형 질문을 선호하는 것입니다. 이렇게 나온 스펙은 혼자 쓸 때 놓쳤을 엣지 케이스까지 커버하는 경향이 있습니다.

완성된 스펙은 docs/specs/YYYY-MM-DD-topic.md 경로에 저장하고 커밋하는 것을 권장합니다. 에이전트가 git diff로 추적할 수 있는 이력이 생기고, 코드 리뷰어가 의도적인 결정과 실수를 구분하는 근거가 됩니다.

레이어 3: 실행 가능한 작업 단위로서의 plan.md

플랜 파일은 가장 좁은 레이어입니다. 스펙을 각각 2~5분이 걸리는 작업으로 쪼개고, 명시적인 파일 경로와 고정된 실행 순서를 포함합니다. 저는 모든 플랜을 TDD 사이클에 맞춥니다. 테스트를 먼저 작성하고, 통과에 필요한 최소한의 코드를 구현하고, 테스트 통과를 확인한 뒤 커밋하는 순서입니다.

명시적인 파일 경로가 생각보다 훨씬 중요합니다. 경로가 없으면 에이전트가 파일 위치를 추측하고, 그 추측이 세션마다 달라집니다. 경로를 고정하면 이 변동성이 제거됩니다.

품질을 높인 세션 분리 전략

몇 달 동안 제가 놓쳤던 부분이 있습니다. 세 개의 파일을 깔끔하게 준비해도, 스펙 작성과 구현을 같은 세션에서 진행하면 품질이 저하됐습니다. 이유는 단순합니다. 스펙 작성 중 이루어지는 브레인스토밍과 질의응답이 컨텍스트 윈도우의 상당 부분을 소비합니다. 구현이 시작될 때쯤이면 에이전트는 이미 앞서 내린 결정들을 잊어버리고 있습니다.

해결책은 간단합니다. 세션 1에서 SPEC.md를 작성하고 저장합니다. 세션 2에서 스펙을 기반으로 plan.md를 생성합니다. 세션 3부터 작업을 하나씩 실행합니다. 컨텍스트 윈도우가 절반 정도 찼다 싶으면 새 세션으로 전환하는 것도 습관화했습니다. 정확도 향상이 즉시 체감됩니다.

이 방식이 향하는 곳

애자일 선언문 팀이 에이전트 기반 소프트웨어 개발의 성숙도 모델을 발표한 바 있는데, 이 레이어드 접근 방식과 잘 맞아떨어집니다.

• 레벨 1: 스펙을 작성하고 구현한 뒤 스펙을 버립니다.
• 레벨 2: 스펙을 코드와 함께 진화하는 살아있는 문서로 유지합니다.
• 레벨 3: 스펙이 단일 진실 공급원이 되고, 코드는 생성된 아티팩트가 됩니다.

제가 대화를 나눈 대부분의 개발자들은 아직 레벨 1에 도달하지 못한 상태입니다. 프롬프트가 유일한 입력이고 코드가 유일한 출력인 방식으로 운용하고 있습니다. 단순한 작업에는 통하지만, 복잡도가 올라가면 무너집니다.

레벨 1에서 레벨 2로의 전환은 습관 하나입니다. 스펙 파일을 Git에 커밋하는 것입니다. 레벨 2에서 레벨 3으로의 전환은 워크플로우 변화입니다. 코드를 수정해야 할 때 스펙을 먼저 업데이트하고 재생성하는 방식으로 전환하는 것입니다.

오늘 당장 시작할 수 있습니다. 프로젝트 기본 정보로 CLAUDE.md를 만들고, 다음 기능에 대한 SPEC.md를 코드에 손대기 전에 먼저 작성해보세요. 차이는 빠르게 쌓입니다.