AI 코딩 어시스턴트가 망가졌다는 것을 깨달은 순간

저는 사이드 프로젝트인 간단한 할 일 관리(task manager) 앱을 만들고 있었습니다. Claude Code를 열고 다음과 같이 입력했습니다.

"이메일과 비밀번호 로그인을 통한 사용자 인증 기능을 추가해줘"

…그리고 엔터를 눌렀습니다.

20분 후, 코드가 생성되었습니다. 아주 많은 코드였습니다. 인증 로직(Authentication logic), 라우트(routes), 미들웨어(middleware), 심지어 기본적인 테스트 코드까지 포함되어 있었습니다.

하지만 문제가 있었습니다.

프론트엔드(다른 날의 저 자신)는 다른 API 형태(API shape)를 가정하고 있었습니다. 테스트는 오직 해피 패스(happy path)만을 다루고 있었습니다. 참조할 만한 아키텍처 결정(architecture decision)도 없었습니다. 저는 그저 느낌이 좋아서 JWT를 선택했을 뿐입니다. 그리고 docker-compose.yml은요? 아직 존재하지도 않았습니다.

AI가 생성한 코드는 있었지만, 실제 소프트웨어 개발 워크플로우(software development workflow)는 없었습니다.

실제로 부족했던 것

좋은 소프트웨어는 단순히 코드만으로 이루어지지 않습니다. 단 한 줄의 코드를 쓰기 전에 다음과 같은 것들이 필요합니다:

• 모든 사람(미래의 당신을 포함하여)이 동의하는 명세서(spec)
• '왜' 그렇게 했는지를 설명하는 아키텍처 결정(architecture decision)
• 서로 통신할 수 있도록 설계된 백엔드(Backend)와 프론트엔드(Frontend)
• 실제로 작동함을 증명하는 테스트(Tests)
• 배포 전 보안 취약점을 잡아내는 코드 리뷰(code review)
• 누군가가 실제로 실행할 수 있는 배포 설정(deployment config)

보통은 팀이 이 모든 것을 처리합니다. PM(Product Manager)이 명세서를 작성합니다. 아키텍트(Architect)가 옵션을 제안합니다. 엔지니어(Engineers)가 구현하고 서로의 작업을 리뷰합니다. DevOps 담당자가 CI/CD를 설정합니다.

만약 AI가 이 모든 역할을 수행할 수 있다면 어떨까요?

파이프라인 구축하기

저는 **claude-dev-pipeline**을 구축했습니다. 이는 각각 특정한 직무를 가진 전문화된 AI 에이전트(AI agents) 팀을 오케스트레이션(orchestrates)하는 Claude Code 플러그인입니다.

GitHub logo airwaves778899 / claude-dev-pipeline

Claude Code를 위한 7개 에이전트 풀스택 개발 파이프라인 플러그인 — PM → Architect → Backend → Frontend → QA → Reviewer → DevOps

claude-dev-pipeline

요구사항 분석부터 프로덕션 배포(production deployment)까지, 사용자의 기능 요청을 완수하기 위해 **7개의 특화된 AI 에이전트 (AI agents)**를 오케스트레이션하는 Claude Code 플러그인입니다. 모든 단계에는 인간 참여형 체크포인트(human-in-the-loop checkpoint)가 포함되어 있습니다.

中文說明

왜인가요? (Why?)

기능을 구현하는 것은 단순히 코드만 작성하는 것 이상의 과정이 필요합니다. 다음과 같은 요소들이 필요합니다:

• 모두가 동의할 수 있는 명확한 사양 (spec)
• 단 한 줄의 코드를 쓰기 전의 아키텍처 결정 (architecture decision)
• 실제로 서로 잘 맞물려 돌아가는 백엔드 (Backend)와 프론트엔드 (Frontend)
• 기능이 작동함을 증명하는 테스트 (Tests)
• 보안 취약점을 잡아내는 코드 리뷰 (code review)
• 실제로 실행 가능한 배포 설정 (deployment config)

claude-dev-pipeline은 이러한 워크플로우 (workflow)를 Claude Code 플러그인으로 인코딩합니다. 각 에이전트는 전문가이며, 당신은 모든 관문(gate)에서 제어권을 유지합니다.

7개의 에이전트 (The 7 Agents)

View on GitHub

아이디어는 간단했습니다. 모든 것을 수행하는 하나의 거대한 AI 대신, 각 작업의 전문가인 여러 에이전트를 순차적으로 사용하되, 당신이 모든 중요한 관문에서 출력물을 승인하도록 하는 것입니다.

9개의 에이전트, 9개의 단계:

#	에이전트 (Agent)	역할 (Role)	출력물 (Output)
0	Discovery	대화를 통해 모호한 요구사항을 명확히 함	확정된 요구사항
...
Nine agents and their roles

단계 4a와 4b는 병렬로 실행됩니다.

전체 흐름 (Full flow):

사용자 요구사항 (User requirement)
│
[Discovery]    ← 모호할 경우 명확화 질문을 던짐
...

제가 자랑스럽게 생각하는 몇 가지 설계 결정 사항들

모든 중요한 관문에서의 Human-in-the-loop (인간 참여형 구조).
아키텍처 (Architecture) 설계가 시작되기 전에 사용자가 제품 요구사항 문서 (PRD)를 승인합니다. 코드가 작성되기 전에 세 가지 아키텍처 옵션 중 하나를 선택합니다. 리뷰어 (Reviewer)는 3개 이상의 심각한 문제를 발견하면 모든 과정을 일시 중단합니다. AI가 작업을 수행하지만, 제어권은 사용자가 유지합니다.

백엔드 (Backend)와 프론트엔드 (Frontend)의 병렬 실행.
두 에이전트 (Agent) 모두에게 동일한 아키텍처 문서를 제공했기 때문에, 서로 완벽하게 맞물려 돌아갑니다. 이는 파이프라인 (Pipeline)의 실제 소요 시간을 단축하며

지원됨: ts-node (기본값), ts-react, python, go, flutter.

예상치 못한 어려운 부분

저는 에이전트 프롬프트 (Agent Prompts)를 작성하는 것이 가장 어려운 부분일 것이라고 생각했습니다. 하지만 그렇지 않았습니다.

가장 어려운 부분은 바로 **핸드오프 (Handoffs, 업무 인계)**였습니다.

각 에이전트는 이전 에이전트가 무엇을 결정했는지 정확히 알아야 합니다. PM 에이전트의 출력물은 아키텍트 (Architect)가 실제로 파싱 (Parse)할 수 있는 방식으로 구조화되어야 합니다. 아키텍트의 결정은 백엔드 (Backend)와 프론트엔드 (Frontend)가 서로 모순되지 않게 구현할 수 있을 만큼 충분히 구체적이어야 합니다.

저는 수많은 반복 과정을 거쳤습니다. 현재의 해결책은 다음과 같습니다: 모든 에이전트가 이전의 .pipeline/*.md 파일들을 컨텍스트 (Context)로 읽고, 문서화된 스키마 (Schema)에 따라 자신의 출력물을 작성하는 것입니다. 느낌 (Vibes)이 아닌, 구조화된 핸드오프입니다.

두 번째로 어려운 부분은 프롬프트에 **저 자신의 의견을 인코딩 (Encoding)**하는 것이었습니다. 혼자 코드를 작성할 때, 저는 수십 가지의 미세한 결정들을 자동으로 내립니다. 에이전트에게 동일한 결정을 일관되게 내리고, 그 추론 과정을 설명하도록 가르치는 데는 상당한 노력이 필요했습니다. 이는 본질적으로 각 역할에 대해 매우 주관적인 스타일 가이드 (Style Guide)를 작성하는 것과 같습니다.

배운 점

구조가 원시 지능 (Raw Intelligence)을 이깁니다. 항상 특정 출력 형식을 생성하는 잘 설계된 프롬프트의 에이전트가, 매번 다른 결과물을 내놓는 강력한 모델보다 더 유용합니다.

승인 게이트 (Approval Gates)는 마찰이 아니라, 그 자체가 핵심입니다. 이 파이프라인 (Pipeline)의 가치는 속도에 있지 않습니다. 그것은 내려진 모든 결정을 당신이 이해하고 있다는 점에 있습니다. 당신은 PRD를 승인했습니다. 당신이 아키텍처를 선택했습니다. 당신이 테스트를 검토했습니다. 운영 환경 (Production)에서 무언가 고장 나더라도, 당신은 그 이유를 알고 있습니다. 모든 결정 과정에 당신이 참여했기 때문입니다.

AI 에이전트는 쓰기 전에 읽어야 합니다. 탐색 (Exploration) 에이전트는 나중에 추가되었지만, 결과적으로 필수적인 요소임이 밝혀졌습니다. 이 에이전트가 없었다면, 백엔드 에이전트는 코드베이스에 이미 존재하는 패턴, 명명 규칙 (Naming Conventions), 또는 아키텍처 선택 사항을 인지하지 못한 채 코드를 생성했을 것입니다. 먼저 읽는 것이 모든 것을 바꾸어 놓았습니다.

다음 단계

이 프로젝트는 오픈 소스 (MIT)이며 활발하게 진화하고 있습니다.

v3.0.0에서 최근 추가된 사항은 다음과 같습니다:

• Security Agent (보안 에이전트) — QA와 Reviewer(검토자) 사이에서 OWASP Top 10 감사를 실행합니다.
• Troubleshooter Agent (트러블슈터 에이전트) — 구조화된 버그 수정 루프(Reproduce(재현) → Isolate(격리) → Diagnose(진단) → Fix(수정) → Verify(검증))를 수행하며, /dev-pipeline fix "버그 설명" 명령어로 트리거됩니다.

저는 멀티 레포지토리 (multi-repo) 파이프라인 지원과 웹 기반 진행 상황 대시보드를 추가할 계획입니다.

⭐ 이 프로젝트가 공감된다면, 별(Star)을 눌러주세요:
github.com/airwaves778899/claude-dev-pipeline

궁금합니다: 여러분의 개발 워크플로우에서 AI가 대신 처리해주었으면 하는 가장 고통스러운 부분은 무엇인가요? 댓글로 남겨주세요.

이 플러그인은 Anthropic의 에이전트 기반 코딩 (agentic coding)용 CLI 도구인 Claude Code를 기반으로 구축되었습니다. 플러그인 시스템을 통해 Claude Code가 로드하고 오케스트레이션 (orchestrate)할 수 있는 커스텀 에이전트와 슬래시 명령어를 정의할 수 있습니다.