Claude와 함께 Spec-Driven Development를 할 때 절대 하지 말아야 할 것들
Source: Dev.to
위의 링크에 있는 전체 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. (코드 블록, URL 및 마크다운 형식은 그대로 유지됩니다.)
Introduction
AI‑지원 워크플로우를 도입한 시니어 엔지니어들은 그 약속을 알고 있습니다: 더 빠른 반복, 오해 감소, 그리고 즉흥이 아닌 의도를 반영하는 코드베이스. Claude와 함께하는 스펙‑드리븐 개발은 그 플레이북에서 가장 강력한 패턴 중 하나입니다. 하지만 가장 남용하기 쉬운 패턴이기도 합니다. 여기서는 Claude를 수정하는 데 더 많은 시간을 쓰는 팀과 일관된 프로덕션‑품질 결과물을 얻는 팀을 구분 짓는 요소를 살펴봅니다.
1. 모호한 사양을 쓰고 Claude가 빈틈을 메우길 기대하지 마라
Claude는 뛰어난 추론 엔진이지만 마음 읽는 사람은 아니다. 사양에 “사용자 관리 시스템을 구축한다” 라고만 적혀 있으면, Claude는 합리적인 가정—일반적인 모범 사례에 기반한—을 할 것이지만, 여러분의 상황에 맞지 않을 가능성이 높다.
아키텍트로서 여러분의 역할은 암묵적인 것을 명시적으로 만드는 것이다. 즉, 경계 컨텍스트, 데이터‑소유 규칙, 실패 모드, 비기능 요구사항을 사양 자체에 명시하는 것을 의미한다. 그것이 쓰여 있지 않다면, 긴 세션 동안 Claude가 올바르게 추론해줄 것으로 기대하지 마라.
해결책
사양을 RFC처럼 다뤄라. 조직의 결정, 제약 조건, 관행에 대한 전혀 배경 지식이 없는 사람을 위해 작성하라.
2. 도메인 입력 없이 Claude에게 사양을 작성하게 하지 마세요
매력적인 워크플로가 있습니다: 문제 진술을 Claude에 던지고, 사양을 생성하도록 요청한 다음, 그 사양을 구현에 활용합니다. 순진하게 하면 순환 논리가 발생합니다—Claude는 당신이 원하는 것을 추측해 사양을 작성하고, 그 사양을 구현하지만 실제 도메인 문제에 기반하지 않습니다.
Claude는 도메인 지식을 제공받은 후 사양을 구조화하고 형식화하는 데 뛰어납니다. 그 지식의 출처가 되어서는 안 됩니다.
The fix
- You bring the domain.
- Claude brings the structure.
핵심 결정과 제약 조건을 먼저 평이한 언어로 초안 작성한 뒤, Claude에게 섹션, 엣지 케이스, 수용 기준을 포함한 사양으로 형식화하도록 요청하세요.
3. 수용 기준을 놓치지 마세요
이것은 사양‑주도 워크플로우로 전환할 때 시니어 엔지니어들이 가장 흔히 저지르는 실수입니다. 그들은 훌륭한 기능 설명을 작성하지만 “완료”가 어떤 모습인지를 생략합니다.
수용 기준이 없으면 Claude는 자신이 이해한 대로 작업을 끝까지 구현합니다—기술적으로는 올바를 수 있지만 여러분의 기대와는 완전히 어긋날 수 있습니다. 이런 문제는 리뷰 시점에야 비로소 드러나며, 이는 사양‑주도 접근 방식의 목적을 완전히 무너뜨립니다.
해결책
사양에 포함된 모든 기능은 테스트 가능하고 구체적인 형태로 최소 세 개 이상의 수용 기준으로 마무리해야 합니다.
- ✅ 좋은 예: “필수 필드가 누락된 경우 엔드포인트가 구조화된 오류 본문과 함께 422 상태 코드를 반환한다.”
- ❌ 나쁜 예: “오류를 우아하게 처리한다.”
4. 구현을 과도하게 지정하지 말 것
모호함의 반대쪽에도 실패 모드가 있다: 사양 안에서 구현을 세세하게 관리하는 것. Claude에게 어떤 디자인 패턴을 사용할지, 클래스 계층 구조를 어떻게 구성할지, 어떤 라이브러리 메서드를 호출할지 지시하면 사양이 번역 레이어가 되어버리고 Claude가 제공하는 가장 가치 있는 것이 사라진다.
사양은 무엇과 왜를 포착해야 한다. 구현 결정은 별도의 대화에서, 혹은 사양이 검증된 후에만 기술 설계 문서에 포함되어야 한다.
해결책
사양 안에 메서드 시그니처나 SQL 쿼리를 작성하고 있다면 멈추라. 대신 적용하려는 비즈니스 규칙이나 제약조건을 작성하고, 구현에 관한 논의는 별도로 진행하도록 하라.
5. Claude가 세션 간에 컨텍스트를 유지한다고 가정하지 말 것
Claude의 컨텍스트 윈도우는 대화 사이에 지속되지 않습니다. 지난 화요일에 기본 사양을 작성했더라도 Claude는 오늘 그것을 기억하지 못합니다. 컨텍스트를 다시 고정하지 않고 그 위에 구축하면 드리프트가 발생합니다—각 세션이 약간씩 기반을 재해석하고, 시간이 지남에 따라 구현이 원래 의도와 멀어집니다.
해결 방법
사양을 활생 문서로 취급하고, 관련 세션이 시작될 때마다 Claude에게 전달하십시오. 버전 관리에 보관하고 명시적으로 참조하십시오. 사양이 너무 길어 매번 전달하는 것이 비용이 많이 든다면, 이는 도구 문제라기보다 범위 문제입니다.
Source: …
6. 하나의 스펙에 여러 관점을 섞지 말 것
API 계약, 데이터 영속성 레이어, 비즈니스 규칙, UI 동작을 동시에 다루는 스펙은 스펙이 아니라 정체성 문제가 있는 설계 문서입니다. Claude가 이를 모두 만족시키려 하면서 실제로 아키텍트가 신경 써야 할 경계를 위반하는 밀접하게 결합된 구현이 만들어집니다.
스펙에서 관점을 섞는 것은 협업 위험 요소이기도 합니다. 여러 팀이 같은 스펙을 기반으로 작업하면 각 팀이 Claude를 서로 다른 방향으로 끌어당기게 됩니다.
해결 방법
- 경계가 있는 관점당 하나의 스펙.
- API 동작
- 도메인 로직
- 데이터 계약
- 인프라 기대치
Claude에게는 언제든지 현재 세션에서 작동하고 있는 스펙을 명시적으로 알려줘야 합니다.
7. Claude의 명확화 질문을 무시하지 마세요
Claude가 사양 중간이나 구현 중간에 명확화 질문을 할 때, 그 질문은 방해가 아니라 신호입니다. 이는 사양에 모호함이 있어 해결되지 않으면 암묵적으로 결정이 내려진다는 의미이며, 코드베이스에서의 암묵적인 결정은 숨은 기술 부채와 같습니다.
즉시 답변하고 넘어가고 싶어지지만, 더 좋은 방법은 사양을 업데이트하여 모호함을 해결한 뒤 답변하는 것입니다. 이렇게 하면 질문이 한 번만 제기됩니다—새로운 엔지니어나 새로운 Claude 세션이 같은 공백을 마주할 때마다 반복되지 않게 됩니다.
The fix
모든 명확화 질문을 사양 결함으로 간주하십시오. 사양을 수정한 뒤 진행합니다.
8. 사양이 안정되기 전에는 코딩을 시작하지 말 것
Spec‑driven development는 규율을 요구한다: 구현 코드를 한 줄이라도 작성하기 전에 사양이 완전하고, 검토되었으며, 승인되어야 한다. 이것은 여러분이 반드시 지켜야 할 프로세스 경계이다.
그러한 마찰 없는 접근은 함정이다. 초안 사양에 맞춰 구현 코드를 생성하면 사양이 변경될 때마다 코드를 수정하게 된다. 복잡한 시스템에서는 이는 오래된 구현, 일관성 없는 동작, 그리고 기대했던 생산성 향상을 모두 무색하게 만드는 재작업을 초래한다.
The fix
해결책
사양 작업과 구현 작업을 별개의 대화로 구분하라. 사양을 만들어내는 대화는 안정적이고 검토된 산출물로 마무리되어야 한다. 그 산출물을 시작점으로 하는 새로운 대화가 구현을 진행한다.
9. 범위 외 항목 정의를 잊지 말자
시니어 엔지니어들은 RFC와 설계 문서를 작성하면서 이것을 알고 있다: 구축하지 않기로 선택한 것이 구축하기로 한 것만큼 중요하다. 명시적인 범위 경계가 없는 사양은 Claude가 포함 여부에 대해 판단하도록 만들며, 그 판단은 보통 낙관적이다.
범위 외 섹션은 자신의 사고를 강제하는 기능이기도 하다. 이 사양이 다루지 않는 부분을 명확히 설명하지 못한다면, 시작하기에 충분히 깨끗한 경계가 없는 것이다.
The fix
Every spec needs a “Non‑Goals” or “Out of Scope” section. Be explicit.
“This spec does not address multi‑tenancy, audit logging, or soft‑delete behavior.”
That kind of precision keeps implementations lean and reviewable.
10. 구현이 시작되면 사양을 불변으로 여기지 말라
사양은 진화합니다. 요구사항이 바뀝니다. 구현 과정에서 설계 단계에서는 보이지 않았던 엣지 케이스를 발견하게 됩니다. 이것 자체는 문제가 되지 않으며—그렇지 않다면, 클로드에게 사양을 우회하도록 요구하는 대신 사양을 업데이트해야 합니다.
우회 방법이 쌓이게 됩니다. 구현이 사양에서 점점 멀어집니다. 사양은 진실의 원천이라기보다 과거의 산물로 전락합니다. 사양‑주도 접근 방식의 전체 가치를 잃게 되는 것이죠.
해결책
구현 중에 틈이나 모순이 드러나면 즉시 중단하고 사양을 업데이트합니다. 클로드를 최신 버전의 사양에 다시 맞춥니다. 이는 단기적으로는 마찰을 발생시키지만, 장기적으로는 엔트로피(혼돈)를 방지합니다.
기본 원리
Spec‑driven development with Claude는 사양이 언제나 그래왔듯이 구현이 제한되고 검증 가능한 과정이 되도록 충분히 정확하게 의도를 인코딩할 때 작동합니다. Claude는 그 과정을 증폭시킬 뿐이며, 사양을 처음 작성하게 만드는 사고 자체를 대체하지 않습니다.
위의 안티‑패턴들은 공통된 근원을 가지고 있습니다: Claude를 불명확함을 보완해 주는 시스템으로 취급한다는 점입니다. 실제로 Claude는 주어진 내용을 놀라운 정확도로 실행할 뿐이며, 따라서 출력물의 품질은 사양의 품질에 직접적으로 비례합니다.