Claude가 생성한 코드가 작동한다. 그것이 바로 문제다.

당시에는 실패처럼 느껴지지 않기 때문에 인식하기 어려운 특정한 종류의 프로젝트 실패가 있습니다.

Claude를 엽니다. 필요한 것을 설명합니다. 코드가 나타납니다. 실행됩니다. 커밋합니다. 반복합니다.

6주 후, 당신은 기술적으로는 작동하지만 당신을 포함해 그 누구도 안전하게 건드릴 수 없는 코드베이스를 바라보고 있습니다. 기능을 추가하는 것은 폭탄을 해체하는 것처럼 느껴집니다. 테스트는 통과하지만 당신은 그것을 신뢰하지 않습니다. 모든 것이 당신이 완전히 파악할 수 없는 방식으로 연결되어 있기 때문에 리팩터링(Refactor)하는 것이 두렵습니다.

이것이 AI 보조 기술 부채(AI-assisted technical debt)의 가장 흔한 형태이며, 이는 잘못된 프롬프트(Prompt) 때문에 발생하는 것이 아닙니다. 그것은 Claude에게 무엇을 요청하느냐뿐만 아니라, Claude와 어떻게 협업할지에 대한 명확한 프로세스가 없기 때문에 발생합니다.

신뢰의 격차 (The confidence gap)

Claude는 자신감이 있습니다. 거의 항상 말이죠. 그것이 맞든 틀리든, Claude는 동일하게 확신에 찬 어조로 답변합니다. 이는 빠르게 진행하는 데 진정으로 유용하지만, 당신이 검증할 수 있는 위치에 있지 않을 때는 진정으로 위험합니다.

문제는 Claude가 틀린 답을 내놓는다는 것이 아닙니다. 출력물만 보고서 언제 그것을 믿어야 하고 언제 반박해야 하는지를 알 수 없다는 점입니다.

Claude를 잘 사용하는 개발자들은 다음과 같은 개념을 내면화하고 있습니다: Claude의 출력물을 유능하지만 지나치게 자신만만한 주니어 엔지니어의 초안(First draft)으로 취급하라. 당신은 그 엔지니어의 PR(Pull Request)을 검토 없이 머지(Merge)하지 않을 것입니다. Claude의 출력물도 동일한 규율 없이 머지해서는 안 됩니다.

하지만 대부분의 사람들은 이를 위한 시스템을 가지고 있지 않습니다. 그들은 그저 느낌(Vibes)에 의존합니다.

"작동한다"는 함정 ("it works" trap)

"작동한다"는 AI 보조 개발에서 가장 위험한 수용 기준(Acceptance criterion)입니다.

배포 압박을 받고 있을 때, "작동한다"는 것은 충분해 보입니다. Claude가 수동 테스트를 통과하는 무언가를 만들어냈다면, 다음 단계로 넘어갑니다. 하지만 "작동한다"는 다음 사항들을 알려주지 않습니다:

• 예외 케이스(Edge cases)를 처리하는지 여부
• 요구 사항이 변경될 때 추상화(Abstractions)가 유지될지 여부
• 명명 규칙(Naming)과 구조가 3개월 후에도 말이 될지 여부
• 프로덕션(Production) 환경에서만 나타나는 미묘한 버그를 유발했는지 여부

이것들은 Claude가 만들어낸 문제들이 아닙니다. 모든 소프트웨어 개발 과정에 존재하는 문제들입니다. 하지만 AI 보조 코딩 (AI-assisted coding)은 결과물이 완벽하고 권위 있게 느껴지기 때문에, 평소라면 이러한 문제들을 잡아냈을 검토 과정을 건너뛰게 만드는 압박을 가합니다.

실제 워크플로우 (Workflow)의 모습

몇몇 프로젝트에서 이 과정을 고통스럽게 겪어본 후, 가장 큰 차이를 만들어낸 구조는 다음과 같습니다:

1. 생성하기 전에 정의하라

Claude에게 무언가를 작성해 달라고 요청하기 전에, 해당 함수가 무엇을 해야 하는지, 무엇을 해서는 안 되는지, 그리고 무엇이 좋은 결과물인지 평이한 언어로 적어두세요. 이는 당연해 보이지만, 거의 아무도 일관되게 수행하지 않습니다. 이 과정이 없다면, 당신은 오직 당신의 머릿속에만 존재하는 모호한 명세 (Spec)를 기준으로 Claude의 결과물을 평가하게 됩니다.

2. 생성과 검증을 분리하라

동일한 세션에서 생성과 병합 (Merge)을 동시에 하지 마세요. 최소한 잠시라도 — 심지어 10분이라도 — 시간을 두고 새로운 시각으로 결과물을 다시 확인하십시오. 마치 다른 사람의 코드를 리뷰하는 것처럼 읽으세요. 그리고 스스로에게 물으세요: "만약 내가 Claude가 이것을 작성했다는 사실을 모른다면, 이 PR (Pull Request)을 승인할 것인가?"

3. 불확실성을 가시화하라

Claude가 당신이 완전히 이해하지 못하는 영역에서 작업하고 있다면, 이를 표시하세요. 주석을 달거나, 노트를 작성하거나, 무엇이라도 하세요. 위험한 것은 당신이 확신하지 못하는 영역에서 AI를 사용하는 것이 아니라, 코드베이스의 어느 부분이 "당신이 확신하지 못했던 영역"인지 잊어버리는 것입니다.

4. 컨텍스트 (Context)를 타이트하게 유지하라

Claude는 제한적이고 범위가 잘 정해진 작업 (Task)에서 가장 잘 작동합니다. 당신이 제공하는 컨텍스트가 커질수록 Claude는 더 많은 것을 추론해야 하며, 당신이 실제로 원하는 것에서 더 많이 벗어날 수 있습니다. 좋은 결과를 얻기 위해 문단 단위의 긴 컨텍스트를 작성하고 있다면, 그것은 작업을 더 작게 나누어야 한다는 신호입니다.

5. 아키텍처 (Architecture)를 소유하라

Claude가 구현 세부 사항(implementation details)을 처리하게 하세요. 기본적으로 Claude가 구조적 결정(structural decisions)을 내리게 해서는 안 됩니다. "이것을 어떻게 구조화해야 할까요?"라고 물을 때마다 첫 번째 답변을 그대로 수용한다면, 당신은 나중에 되돌리기 어려운 결정을 넘겨주고 있는 것입니다. 구조적 결정은 Claude의 정보를 바탕으로 당신이 내려야 하며, 그 반대가 되어서는 안 됩니다.

이 모든 것의 본질

제가 본 개발자 중 Claude를 가장 잘 활용하는 사람들은 최고의 프롬프트(prompts)를 찾아낸 사람들이 아닙니다. 그들은 Claude를 승수 효과(force multiplier)로 사용하면서도, 자신의 프로젝트에 대한 통제권을 유지하는 방법을 터득한 사람들입니다.

이는 생성을 시작하기 전에 당신이 무엇을 만들고 있는지에 대한 명확한 그림을 가지고 있어야 함을 의미합니다. 또한, 외부 기여자가 작성한 코드를 검토할 때와 동일한 회의적인 시각으로 Claude의 출력물을 검토해야 함을 의미합니다. 어떤 결정이 당신의 몫이고, 어떤 결정에 Claude의 도움을 받을 수 있는지 알고 있어야 한다는 뜻입니다.

이것은 기술의 문제라기보다 태도(posture)의 문제입니다. Claude는 당신이 지시를 내릴 때 매우 유용합니다. 하지만 Claude가 지시를 내리게 되면 — 시간, 재작업, 혼란 측면에서 — 비용이 많이 들게 됩니다.

저는 최근 이 점에 대해 많은 생각을 해왔으며, Claude와 함께 빠르게 움직이면서도 나중에 두려워하게 될 코드베이스(codebase)를 만들지 않기를 원하는 빌더들을 위해 무료 스타터 팩(starter pack) — 프롬프트, 출시 체크리스트, 그리고 워크플로우 구조 — 을 준비했습니다. 이 팩은 단순히 실험만 하는 것이 아니라 실제로 무언가를 출시(ship)하려는 인디 빌더(indie builders)와 학생들을 대상으로 합니다.

이 내용 중 공감 가는 부분이 있다면, 여기서 무료로 받으실 수 있습니다: Ship With Claude — Starter Pack

이메일 입력도 필요 없고, 다운로드 시 추가 판매(upsell)도 없습니다. 오직 팩만 제공됩니다.

다른 사람들은 어떤 패턴을 발견했는지 궁금합니다. AI 보조 개발(AI-assisted development)이 당신의 워크플로우에 마침내 딱 맞아떨어지게 만든 결정적인 요소는 무엇이었나요?