개요
Claude Code와 같은 AI 코딩 도구를 실무에서 사용하다 보면, 빠르게 코드를 작성할 수 있다는 장점 뒤에 숨겨진 여러 문제들을 만나게 됩니다. 이번 포스트에서는 그 문제들을 정리하고, SDD(Spec-Driven Development) Plugin을 만들게 된 배경을 공유합니다.
이 포스트는 SDD Plugin 시리즈의 일부입니다. 완성된 플러그인의 구조와 사용법은 SDD Plugin의 전체 구조와 사용법에서, 개발 과정은 프로토타입에서 완성까지에서, 적용한 엔지니어링 원리는 AI 엔지니어링 4가지 패러다임으로 분석에서 다루고 있습니다.
AI 코딩의 함정
Claude Code를 사용하면 놀라운 속도로 코드를 작성할 수 있습니다. “이 기능 만들어 줘”라고 한마디 하면 순식간에 코드가 생성됩니다. 처음에는 감탄했지만, 실무에서 반복적으로 사용하다 보니 몇 가지 문제가 눈에 들어오기 시작했습니다.
요구사항 분석 없이 바로 코딩
AI에게 “이 기능 만들어 줘”라고 하면, AI는 바로 코드를 작성합니다. 하지만 **What(무엇을)**과 **Why(왜)**가 명확하지 않은 상태에서 만들어진 코드는 원하는 방향과 다를 수 있습니다. 그리고 방향이 어긋났다는 걸 깨달았을 때는 이미 꽤 많은 코드가 작성된 후입니다.
설계 없이 구현
기존 코드베이스에는 나름의 아키텍처와 패턴이 있습니다. 하지만 AI는 이를 무시하고 자기만의 방식으로 구현하는 경우가 많습니다. 결과적으로 기존 코드와 스타일이 다른 코드가 섞이게 되고, 유지보수가 어려워집니다.
테스트 부재
빠르게 만들었지만 테스트 코드가 없어서, 나중에 수정할 때 사이드 이펙트를 파악하기 어렵습니다. AI가 만든 코드라서 본인도 정확히 어떤 로직인지 다 파악하지 못하는 경우도 있습니다.
대화 유실
Claude Code의 대화가 길어지면 컨텍스트가 압축되고, 대화가 끊기면 이전 맥락이 사라집니다. 어디까지 진행했는지, 어떤 결정을 내렸는지 기억에 의존해야 하는 상황이 반복됩니다.
기존 개발 프로세스의 한계
팀에서 이미 개발 프로세스를 갖추고 있더라도, AI 코딩 도구를 사용할 때는 그 프로세스를 따르기 어렵습니다.
AI에게 “이 프로세스를 따라줘”라고 매번 설명하는 것은 비효율적이고, 사람마다 설명하는 방식이 달라 일관성도 떨어집니다. 결국 프로세스가 있어도 AI와 함께 일할 때는 무시되기 쉽습니다.
Claude로 어디까지 할 수 있을까
이런 문제를 인식한 후, 먼저 AI와 함께 개발하는 프로세스를 직접 시도해 보았습니다. GitHub CLI를 설치하고, 저는 Claude Code와 함께 다음과 같은 흐름으로 작업했습니다.
- 작업 분석: GitHub Issue나 요구사항을 Claude에게 전달하고 “이 내용을 분석해서 문제점과 할 일을 정리해 줘”라고 요청
- 작업 내용 확인: Claude가 분석한 내용을 검토하고, 맞지 않는 부분은 “여기는 이렇게 수정해야 하지 않아?”라고 피드백
- 구현: 분석 결과에 만족하면 구현을 지시
- AI 코드 리뷰: 구현이 끝나면 “수정 내용을 리뷰해 줘”, “리팩토링할 부분 있어?” 등으로 코드 품질을 높임
- 셀프 코드 리뷰: AI 리뷰 결과를 확인하고, 추가로 직접 리뷰
- 코드 리뷰 대응: 다른 팀원의 리뷰 코멘트도 Claude에게 전달해서 대응 방법을 분석
이 과정을 반복하면서 몇 가지를 알게 되었습니다.
- AI는 의외로 신뢰할 수 있다. 분석과 리뷰 결과가 상당히 정확했습니다.
- 거의 모든 개발 단계에서 AI를 활용할 수 있었습니다.
- 하지만 100% AI에게 맡기는 것은 무리였습니다. 사람이 작업을 설명하고, 결과를 검토하고, 적절히 판단하는 과정이 반드시 필요했습니다.
코드 자동생성 도구에서 SDD로
처음에는 AI와 별개로, 설계서를 기반으로 Boilerplate 코드를 자동 생성하는 도구를 만들고 있었습니다. Drawio로 화면을 그리고, 스프레드시트로 컴포넌트를 정의하고, 코드 생성기로 기본 코드를 만드는 방식이었습니다.
하지만 이 도구를 개발하면서, Claude Code의 Skill 기능만으로도 코드 자동생성 도구 수준의 결과를 만들 수 있다는 이야기를 들었습니다. 그래서 방향을 전환했습니다. 별도의 도구를 만드는 대신, AI가 작업하기 좋은 개발 프로세스 자체를 설계하자는 것이었습니다.
이미 Spec-Driven Development(SDD)라는 접근 방식이 존재했습니다. 사양(Specification)을 먼저 정의하고, 그 사양을 기반으로 AI가 자동으로 개발하는 방법론입니다.
이런 오픈소스들을 참고하면서, 제 실무 경험에 맞는 Claude Code용 SDD Plugin을 만들기로 결정했습니다.
해결 방향
개발 프로세스 자체를 Claude Code의 플러그인으로 만들면 다음과 같은 장점이 있다고 판단했습니다.
- 명령어 하나로 프로세스를 실행할 수 있습니다. 매번 AI에게 프로세스를 설명할 필요가 없습니다.
- 모든 산출물이 GitHub에 저장되어, 대화가 끊겨도 이어서 작업할 수 있습니다.
- 팀 전체가 동일한 프로세스를 따를 수 있습니다. 플러그인을 설치하기만 하면 됩니다.
프로세스 설계
구체적인 프로세스를 설계하기 위해, 먼저 일반적인 개발 프로세스를 분석했습니다.
- 요구사항 분석
- 설계
- 구현
- 코드 리뷰
- 테스트
- 배포
- 모니터링
이 중 배포와 모니터링은 AI와 함께하는 작업이 아니므로 제외하고, 나머지 단계를 AI와 사람이 협업하는 구조로 만들기로 했습니다. 또한 코드 리뷰는 구현 단계에 통합하여, 최종적으로 4단계 프로세스로 정리했습니다.
1. 요구사항 분석 (What/Why)
2. 설계 (How)
3. 구현 (TDD + 코드 리뷰)
4. 테스트 (E2E/QA)각 단계에서 AI가 작업하고, AI가 자체 리뷰하고, 사람이 최종 확인하는 이중 검증 구조를 기본 패턴으로 잡았습니다.
① 입력 → ② AI 작업 → ③ AI 자체 리뷰 → ④ 사용자 확인 → 다음 단계완료
이번 포스트에서는 AI 코딩 도구의 함정, 기존 프로세스의 한계, 그리고 직접 AI와 협업해본 경험을 바탕으로 SDD Plugin을 만들게 된 배경을 정리했습니다.
핵심은 “AI가 빠르게 코드를 작성하는 것”이 아니라, **“AI가 올바른 방향으로 작업하도록 프로세스를 설계하는 것”**이었습니다.
다음 포스트: SDD Plugin의 전체 구조와 사용법
제 블로그가 도움이 되셨나요? 하단의 댓글을 달아주시면 저에게 큰 힘이 됩니다!
앱 홍보
Deku가 개발한 앱을 한번 사용해보세요.Deku가 개발한 앱은 Flutter로 개발되었습니다.관심있으신 분들은 앱을 다운로드하여 사용해 주시면 정말 감사하겠습니다.
