Opus로 계획하고, Sonnet으로 구축하며, Slash Command로 확장하기

내 Kubernetes Operator의 첫 번째 버전은 제대로 작동했습니다.

그것은 하나의 데이터베이스 플랫폼과 하나의 고객 문제를 위해 구축되었으며, 필요한 기능을 정확히 수행했습니다. 하지만 밑바닥까지 모두 구체적(concrete)이었습니다. 밀접하게 결합(tightly coupled)되어 있었고, 확장할 수 없었으며, 실제 인프라 없이는 테스트가 불가능했습니다.

만약 다른 데이터베이스 플랫폼을 지원하고 싶다면, 코어 전체를 리팩터링(refactoring)해야 했습니다. 구체적인 구현체를 인터페이스(interface)로 교체해야 합니다. 로직이 다양한 구현체 사이에서 재사용될 수 있도록 코드베이스를 재구성해야 합니다.

이것이 바로 AI 지원 개발(AI-assisted development)에서 아무도 이야기하지 않는 부분입니다. 아무것도 없는 상태에서의 구축(greenfield build)이 아니라, 그 다음에 일어나는 일 말입니다. 프로덕션 코드(production code)를 가져와서 망가뜨리지 않고 더 개선하는 과정입니다.

제가 사용한 워크플로우는 다음과 같습니다.

1단계 - Opus를 이용한 사양 정의 (Specification with Opus)

코드 한 줄을 건드리기 전에, 저는 Claude Opus에게 Markdown 문서로 된 상세한 리팩터링 계획을 생성해 달라고 요청했습니다.

모호한 개요가 아니었습니다. 어떤 파일이 생성될지, 어떤 코드 세그먼트가 어디로 이동할지, 새로운 인터페이스는 어떤 모습일지, 그리고 추상화(abstraction)가 향후 데이터베이스 구현체들 사이에서 어떻게 재사용을 가능하게 할지에 대한 정밀한 사양(spec)이었습니다.

저는 이 단계에서 특별히 Opus를 사용했습니다. 더 유능하지만 느리고 비용이 많이 드는 모델이지만, 회귀(regression)를 일으키지 않고 구조적 리팩터링을 계획하는 데 필요한 추론 깊이를 고려하면 그만한 가치가 있었습니다. 목표는 구현을 시작하기 전에 계획을 올바르게 세우는 것이었습니다.

저는 계획을 검토하고, 특정 결정에 대해 이의를 제기하며, 접근 방식이 잘못되었다고 느껴지는 부분에 대해 대안을 요구했습니다. MD 파일은 제가 만족할 때까지 여러 번의 반복(iteration)을 거쳤습니다.

그 문서는 이후 진행되는 모든 작업의 단일 진실 공급원(single source of truth)이 되었습니다.

2단계 - Plan Mode의 Sonnet을 이용한 구현 (Implementation with Sonnet in Plan Mode)

사양이 확정되자, 저는 Claude Sonnet으로 전환하여 Plan Mode를 실행했습니다. 이는 변경 사항을 실행하기 전에 완전한 구현 계획을 제안하는 Claude Code의 내장 기능입니다.

이것은 대부분의 사람들이 건너뛰는 매우 중요한 단계입니다.

Plan Mode는 사양(specification)을 읽고, 이를 기존 코드베이스(codebase)와 매핑하며, 단 한 줄의 코드를 작성하기 전에 정확히 무엇을 할 것인지에 대한 상세한 제안(파일별, 변경 사항별)을 생성합니다. 사용자는 이를 검토하고 승인합니다. 그 후에 실행됩니다.

Opus로 작성한 사양이 입력값이었습니다. Plan Mode의 제안은 모델이 사양을 정확하게 이해했는지 확인하는 검증(verification) 단계였습니다. 구현(Implementation)은 두 가지가 모두 일치할 때 비로소 시작되었습니다.

리팩터링(refactor)은 단 한 번의 실행으로 완료되었습니다. 깔끔한 인터페이스(interface), 재사용 가능한 코어(core), 그리고 실제 인프라 없이도 테스트 가능한 구조를 갖추게 되었습니다.

3단계 - 슬래시 커맨드 (slash command)

아키텍처(architecture)가 올바르게 잡힌 후, 저는 새로운 데이터베이스 통합을 위한 스캐폴딩(scaffold)을 수행하는 커스텀 Claude Code 슬래시 커맨드(slash command)를 구축했습니다.

이제 새로운 플랫폼에 대한 지원을 추가해야 할 때, 저는 해당 명령어를 실행합니다. 그러면 API 레이어(layer), 컨트롤러(controller) 구조, 인터페이스 구현체(interface implementations)가 생성됩니다. 이 모든 것은 리팩터링된 아키텍처와 일치하며, 동일한 패턴을 따릅니다.

이전에는 전체 코드베이스를 이해하고 새로운 로직을 조심스럽게 끼워 넣어야 했던 작업이 이제는 단 몇 분 만에 끝납니다.

전체 워크플로(workflow)를 간단히 정리하면 다음과 같습니다:

Opus → 깊게 생각하고, 정밀하게 계획하며, 사양(spec)을 생성합니다.

Sonnet + Plan Mode → 이해도를 검증하고, 사양에 따라 실행합니다.

커스텀 슬래시 커맨드 (custom slash command) → 투자를 복리로 쌓고, 패턴을 영구적으로 재사용 가능하게 만듭니다.

각 단계는 적재적소에 맞는 도구를 사용합니다. 추론(reasoning)에는 Opus, 실행(execution)에는 Sonnet, 확장(scale)에는 슬래시 커맨드를 사용합니다.

이것이 바로 AI 네이티브(AI-native) 개발이 프로토타입 단계를 넘어 성숙해졌을 때의 모습입니다.

2주간의 MVP(Minimum Viable Product)가 속도에 집중했다면, 이것은 차원이 다른 이야기입니다. 이는 계획과 실행 사이에 검증 단계(verification step)를 두어, 이미 운영 중인 서비스의 아키텍처를 책임감 있게 개선하기 위해 AI를 사용하는 것입니다.

사양(spec)은 단순한 프롬프트(prompt)가 아닙니다. 그것은 사용자와 모델 사이의 계약(contract)입니다. Plan Mode는 모델이 행동에 옮기기 전에 그 계약을 제대로 이해했는지 확인하는 방법입니다.

그러한 규율(먼저 명세(spec)를 작성하고, 실행 전 검증하며, 해결된 모든 문제로부터 재사용 가능한 패턴을 구축하는 것)이야말로 AI를 활용하여 지속적으로 결과물을 출시하는 팀과, 인상적인 데모를 만들어낸 뒤 몇 주 동안 뒷정리를 하는 데 시간을 허비하는 팀을 가르는 차이점입니다.

단순한 신규 구축(greenfield builds)이 아닌, 기존 프로덕션 코드(production code)에 AI를 사용하는 여러분만의 워크플로우(workflow)는 무엇인가요?