Claude Code와 Codex를 사용하기 전에 스펙 파일 세 개를 만드십시오

AI 코딩 에이전트를 거의 1년 동안 매일 사용하면서 가장 불편했던 것은 환각 코드나 잘못된 API가 아니었습니다. 일관성이었습니다. 같은 작업인데도 표현이 조금 달라지면 어느 날은 깔끔한 결과가 나오고, 다음 날은 엉망이 됩니다. 세션이 길어질수록 상황은 악화됩니다. 스무 메시지 전에 합의한 사항을 에이전트가 서서히 잊어가기 때문입니다.

근본 원인은 구조에 있었습니다. 세션을 넘어 에이전트에게 의도를 전달하는 체계가 없었습니다. 모든 대화가 처음부터 시작했고, 예측하기 어려운 방향으로 흘러갔습니다.

결과를 바꾼 세 가지 레이어

각기 다른 역할을 가진 파일 세 개로 지시사항을 나누자 일관성 문제가 거의 하룻밤 사이에 해결됐습니다.

레이어 1, CLAUDE.md는 모든 세션에서 자동으로 로드됩니다. 빌드 커맨드, 기술 스택 버전, 폴더 구조, 코딩 컨벤션, 행동 규칙(항상 할 것, 먼저 물어볼 것, 절대 하지 않을 것)처럼 프로젝트 수준의 고정 정보를 담습니다.

레이어 2, SPEC.md는 특정 기능의 무엇과 왜를 담습니다. 목적, 요구사항, 성공 기준, 기술적 제약, 범위 경계가 들어갑니다. 구현 방법은 담지 않습니다.

레이어 3, plan.md는 스펙을 2~5분 단위의 실행 가능한 작업으로 분해합니다. 명시적인 파일 경로, 테스트 우선 순서, 커밋 체크포인트를 포함합니다.

모든 것을 파일 하나에 몰아넣으면 무너지는 이유

LLM의 지시 따르기에 관한 연구에서 “지시의 저주(Curse of Instructions)“라는 현상이 발견됐습니다. 단일 컨텍스트에 지시사항이 많아질수록 각 개별 지시에 대한 준수율이 급격히 떨어집니다. 직접 실험했을 때도 동일했습니다. 프로젝트 규칙, 기능 스펙, 작업 목록을 하나의 파일에 담자 에이전트는 문서 후반부 지시사항의 절반가량을 무시했습니다.

역할별로 분리하면 해결됩니다. 에이전트는 레이어 1에서 범용 규칙을, 레이어 2에서 기능 의도를, 레이어 3에서 실행 단계를 읽습니다. 각 파일이 짧으니 모델이 내용 전체에 충분히 집중할 수 있습니다.

CLAUDE.md는 간결하게 유지할 때 가장 효과적입니다

이 파일은 매 세션에 로드되므로 항상 적용되는 내용만 담아야 합니다. 빌드 커맨드, 스택 버전, 폴더 레이아웃, 네이밍 컨벤션이 여기에 해당합니다. 세 단계 행동 규칙도 추가하십시오. 항상 할 것, 먼저 물어볼 것, 절대 하지 않을 것입니다.

처음부터 포괄적인 CLAUDE.md를 작성하려는 시도는 역효과를 냈습니다. 에이전트가 같은 실수를 반복할 때마다 규칙을 하나씩 추가하는 방식이 훨씬 잘 작동했습니다. 처음부터 모든 것을 담으려 하면 피하려던 준수율 저하를 오히려 유발합니다.

주의해야 할 함정도 있습니다. API 키나 코드 스니펫은 금방 낡습니다. 린터가 이미 처리하는 규칙은 중복입니다. 특정 기능 하나에만 해당하는 내용은 레이어 2로 옮겨야 합니다.

스펙 파일은 무엇과 왜에 집중하고, 방법은 에이전트에게 맡깁니다

전통적인 PRD와의 차이점은 이 스펙이 회의용이 아니라 에이전트 소비용으로 구조화된다는 점입니다. 다섯 섹션이면 충분합니다. 목적, 요구사항, 성공 기준, 기술적 제약, 범위 경계입니다.

구현 결정은 에이전트에게 맡기십시오. 에이전트는 기존 코드베이스를 분석해 적절한 방법을 선택할 수 있습니다. 방법까지 지시하려 했을 때 에이전트는 기존 패턴과 충돌하더라도 그대로 따르거나, 아예 무시하거나 둘 중 하나였습니다.

스펙을 직접 작성하는 대신 에이전트가 인터뷰하도록 하는 방법도 있습니다. 두 가지 규칙을 지키면 잘 작동합니다. 한 번에 질문 하나씩, 그리고 개방형보다 선택형 질문을 선호하는 것입니다. 이렇게 나온 스펙은 혼자 쓸 때 놓쳤을 엣지 케이스까지 커버하는 경향이 있습니다.

완성된 스펙은 docs/specs/YYYY-MM-DD-topic.md에 저장하고 Git에 커밋하십시오. 에이전트가 git diff로 스펙 변경 이력을 추적할 수 있고, 리뷰어가 코드 변경 뒤의 의도를 파악하는 근거가 됩니다.

세션 분리는 가장 간과하기 쉬운 실천입니다

스펙 작성 중 이루어지는 브레인스토밍과 질의응답은 컨텍스트 윈도우의 상당 부분을 소비합니다. 같은 세션에서 바로 구현으로 넘어가면 에이전트가 앞서 내린 결정들을 서서히 잃어갑니다.

저는 세 개의 세션으로 재편했습니다. 세션 1에서 SPEC.md를 작성하고, 세션 2에서 plan.md를 만들고, 세션 3부터 작업을 하나씩 실행합니다. 첫 주 안에 정확도 향상이 체감됐습니다.

이 방식을 정착시킨 세 가지 습관도 있습니다. 모든 작업에 명시적인 파일 경로를 적어 에이전트의 추측을 없애는 것, TDD 순서(테스트 먼저, 구현, 검증, 커밋)를 plan.md에 고정하는 것, 컨텍스트 사용량이 약 50%에 달하면 새 세션을 시작하는 것입니다.

성숙도 모델이 가리키는 방향

마틴 파울러 팀이 에이전트 기반 소프트웨어 개발의 성숙도 모델을 세 단계로 정의한 바 있습니다. 레벨 1은 스펙을 작성하고 구현한 뒤 스펙을 버립니다. 레벨 2는 스펙을 코드와 함께 살아있는 문서로 유지합니다. 레벨 3은 스펙이 단일 진실 공급원이 되고, 코드가 생성된 아티팩트가 됩니다.

제가 아는 팀과 개인의 대부분은 아직 레벨 1에도 도달하지 못했습니다. 일회성 프롬프트를 보내고 결과를 기대하는 방식으로 운용하고 있습니다.

레벨 1에서 레벨 2로의 전환은 습관 하나입니다. 스펙 파일을 Git에 커밋하는 것입니다. 레벨 2에서 레벨 3으로의 전환은 코드를 바꾸기 전에 스펙을 먼저 업데이트하는 워크플로우 변화입니다. 지금 당장 시작할 수 있는 가장 작은 단계는 프로젝트에 CLAUDE.md를 만들고, 다음 기능 작업 전에 SPEC.md를 먼저 작성하는 것입니다.