목차
개요
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에 저장되어, 대화가 끊겨도 이어서 작업할 수 있습니다.
- 팀 전체가 동일한 프로세스를 따를 수 있습니다. 플러그인을 설치하기만 하면 됩니다.
프로세스 설계
1. 개발 프로세스 분석
구체적인 프로세스를 설계하기 위해, 먼저 우리가 개발할 때 거치는 단계를 분석할 필요가 있다고 생각했습니다. 그래서 일반적인 개발 프로세스를 Claude에게 물어보았습니다.
- 요구사항 분석 (Requirements Analysis)
- 설계 (Design)
- 구현 (Implementation)
- 코드 리뷰 (Code Review)
- 테스트 (Testing)
- 배포 (Merge & Deploy)
- 모니터링 (Monitoring)
이 중 배포와 모니터링은 AI와 함께하는 작업이 아니라고 판단하여, 이 두 단계를 제외한 나머지 프로세스를 생성 AI와 함께 작업할 수 있도록 만들고자 했습니다.
2. Input과 Output 정의
다음으로 각 프로세스에서 생성 AI가 작업하기 좋은 Input과 Output을 정의했습니다. 구현 단계에서는 코드의 정확도와 품질을 위해 TDD(Test Driven Development)로 진행하기로 했습니다.
- 요구사항 분석 (Requirements Analysis)
- Input: 요구사항 정의서
- Output: 요구사항 분석 결과
- 설계 (Design)
- Input: 요구사항 분석 결과
- Output: 설계서
- 구현 (Implementation: TDD)
- Input: 설계서
- Output: 코드
- 코드 리뷰 (Code Review)
- Input: 코드
- Output: Pull Request
- 테스트 (Testing)
- Input: 요구사항 분석 결과, 설계서, 코드
- Output: E2E 테스트 코드, QA 체크리스트
3. AI와 사람의 개발 프로세스 추가
Input에서 Output까지 수행해야 하는 AI와 사람의 세부 프로세스를 추가했습니다.
1) 요구사항 분석 (Requirements Analysis)
| 순서 | 주체 | 작업 |
|---|---|---|
| Input | - | 요구사항 정의서 |
| 1 | AI | 요구사항 분석 |
| 2 | AI(Self) | 분석 결과 자체 리뷰 |
| 3 | AI(Agent) | 분석 결과 에이전트 리뷰 |
| 4 | 사람 | 분석 결과 검토 |
| Output | - | 요구사항 분석 결과 |
2) 설계 (Design)
| 순서 | 주체 | 작업 |
|---|---|---|
| Input | - | 요구사항 분석 결과 |
| 1 | AI | 설계 |
| 2 | AI(Self) | 설계 자체 리뷰 |
| 3 | AI(Agent) | 설계 에이전트 리뷰 |
| 4 | 사람 | 설계 검토 |
| Output | - | 설계서 |
3) 구현 (Implementation: TDD)
| 순서 | 주체 | 작업 |
|---|---|---|
| Input | - | 설계서 |
| 테스트 및 구현 계획 | ||
| 1 | AI | 테스트 및 구현 계획 작성 |
| 2 | AI(Self) | 계획 자체 리뷰 |
| 3 | AI(Agent) | 계획 에이전트 리뷰 |
| 4 | 사람 | 계획 검토 |
| RED: 실패하는 테스트 작성 | ||
| 5 | AI | 테스트 코드 작성 |
| 6 | AI(Self) | 테스트 코드 자체 리뷰 |
| 7 | AI(Agent) | 테스트 코드 에이전트 리뷰 |
| 8 | 사람 | 테스트 코드 검토 |
| GREEN: 테스트를 통과하는 코드 작성 | ||
| 9 | AI | 구현 코드 작성 |
| 10 | AI(Self) | 코드 자체 리뷰 |
| 11 | AI(Agent) | 코드 에이전트 리뷰 |
| 12 | 사람 | 코드 검토 |
| REFACTOR: 리팩토링 | ||
| 13 | AI | 리팩토링 수행 |
| 14 | AI(Self) | 코드 자체 리뷰 |
| 15 | AI(Agent) | 코드 에이전트 리뷰 |
| 16 | 사람 | 코드 검토 |
| Output | - | 코드 |
4) 코드 리뷰 (Code Review)
| 순서 | 주체 | 작업 |
|---|---|---|
| Input | - | 코드 |
| 1 | AI(Self) | 코드 자체 리뷰 |
| 2 | AI(Agent) | 코드 에이전트 리뷰 |
| 3 | 사람 | 코드 리뷰 |
| 4 | 사람 | PR 생성 & Merge |
| Output | - | Merged Pull Request |
5) 테스트 (Testing)
| 순서 | 주체 | 작업 |
|---|---|---|
| Input | - | 요구사항 분석 결과, 설계서, 코드 |
| 1 | AI | 요구사항과 설계서, 코드를 기반으로 E2E 테스트 코드 작성 |
| 2 | AI | 수동 테스트 체크리스트 작성 |
| 3 | AI | 작성 내용 리뷰 |
| 4 | 사람 | 작성 내용 검토 |
| 5 | 사람 | 수동 테스트 실행 |
| Output | - | E2E 테스트 코드, QA 체크리스트 |
각 단계에서 공통적으로 적용된 패턴은 AI가 작업하고, AI가 스스로 리뷰하고, 별도 AI 에이전트가 리뷰하고, 사람이 최종 확인하는 다중 검증 구조입니다.
① Input → ② AI 작업 → ③ AI 자체 리뷰 → ④ AI 에이전트 리뷰 → ⑤ 사용자 확인 → Output4. Input과 Output 관리
Input과 Output을 어떻게 관리할지 고민했습니다.
Claude는 대화가 길어지면 컨텍스트를 압축하기 때문에, 정확도가 떨어지는 문제가 있습니다. 그래서 각 단계의 산출물을 문서로 확실하게 관리할 필요가 있었습니다.
처음에는 Markdown 파일로 Git 레포지토리에서 관리하는 것을 고려했지만, GitHub Issue로 관리하는 방식을 선택했습니다. 이유는 다음과 같습니다.
- 파일로 관리하면 작은 수정에도 매번 커밋이 필요합니다.
- 일시적인 대응이나 버그 수정 등, 작업이 끝난 후에도 파일이 레포지토리에 계속 남게 됩니다.
- Issue는 작업이 끝나면 닫을 수 있어, 완료된 작업과 진행 중인 작업을 명확하게 구분할 수 있습니다.
완료
이번 포스트에서는 AI 코딩 도구의 함정, 기존 프로세스의 한계, 그리고 직접 AI와 협업해본 경험을 바탕으로 SDD Plugin을 만들게 된 배경을 정리했습니다.
핵심은 “AI가 빠르게 코드를 작성하는 것”이 아니라, **“AI가 올바른 방향으로 작업하도록 프로세스를 설계하는 것”**이었습니다.
이번 포스트에서 정리한 개발 프로세스 분석과 설계를 바탕으로, 실제로 Claude Code용 SDD Plugin을 제작했습니다. 다음 포스트에서는 완성된 플러그인의 전체 구조와 사용법을 소개합니다.
다음 포스트: SDD Plugin의 전체 구조와 사용법
제 블로그가 도움이 되셨나요? 하단의 댓글을 달아주시면 저에게 큰 힘이 됩니다!
앱 홍보
Deku가 개발한 앱을 한번 사용해보세요.Deku가 개발한 앱은 Flutter로 개발되었습니다.관심있으신 분들은 앱을 다운로드하여 사용해 주시면 정말 감사하겠습니다.
