SDLC 2.0으로 아이디어에서 코드까지: GitHub Spec Kit 방법론을 통한 커스텀 AI 에이전트 오케스트레이션

SDLC 2.0으로 아이디어에서 코드까지: GitHub Spec Kit 방법론을 통한 커스텀 AI 에이전트 오케스트레이션

"바이브 코딩 (Vibe Coding)"의 시대에 오신 것을 환영합니다. 우리는 더 이상 단순히 코드를 작성하는 것이 아니라, 오케스트라를 지휘하고 있습니다. AI 코딩 어시스턴트(AI coding assistants)가 진화함에 따라, 이들을 단순한 자동 완성 도구로 취급하는 것은 잠재력을 엄청나게 낭비하는 일입니다.

AI 환각 (hallucinations)에 빠지지 않고 복잡하고 확장 가능한 애플리케이션을 구축하고 싶다면, 시스템이 필요합니다. GitHub Spec Kit 방법론과 결합된 SDLC 2.0 (Software Development Life Cycle 2.0)을 소개합니다.

모든 것을 수행하기 위해 혼란스러운 단일 AI 프롬프트에 의존하는 대신, 우리는 소프트웨어 개발 프로세스를 전문화된 "커스텀 에이전트 (Custom Agents)"로 세분화합니다. 각 에이전트는 뚜렷한 페르소나 (persona), 엄격한 경계, 그리고 구체적인 결과물을 가집니다.

🌟 빠른 링크: 이 글에서 논의된 모든 에이전트 템플릿, .agent.md 및 .skill.md 파일은 오픈 소스입니다! **GitHub의 Awesome Copilot ID Repository**에서 찾아 클론(clone)할 수 있습니다.

다음은 여러분만의 가상 엔지니어링 팀을 오케스트레이션하는 방법입니다.

커스텀 에이전트의 구조
GitHub Spec Kit 방법론에서 에이전트는 두 개의 별도 Markdown 파일로 정의됩니다:

두뇌 (.agent.md): 페르소나 (persona), 핵심 지침, 그리고 행동 제약 사항을 정의합니다 (예: "당신은 시니어 아키텍트입니다. 코드를 작성하지 말고 명세서(specifications)만 작성하십시오.").

표준 운영 절차 (.skill.md): 에이전트가 결과물을 출력하기 위해 반드시 사용해야 하는 단계별 워크플로 (workflow)와 필수 문서 템플릿을 정의합니다.

"두뇌"와 "SOP (Standard Operating Procedure)"를 분리함으로써, 우리는 AI 에이전트가 결정론적(deterministically)이고 전문적으로 행동하도록 보장합니다. 이제 팀을 만나고 SDLC 2.0 파이프라인을 살펴보겠습니다.

Phase 0: Discovery & Onboarding (탐색 및 온보딩)
@BrainstormingExplorerAnalyst 소개

만약 처음부터 시작하는 것이 아니라, 문서화가 전혀 되어 있지 않은 레거시 코드베이스 (legacy codebase)에 뛰어들어야 한다면 어떨까요? 바로 이 지점에서 Phase 0가 시작됩니다.

AI에게 맹목적으로 기능을 추가하라고 요청하는 대신, 우리는 @BrainstormingExplorerAnalyst를 배치합니다. Senior Staff Engineer (수석 스태프 엔지니어)의 페르소나로 동작하는 이 에이전트는 엄격한 읽기 전용 (read-only) 모드로 작동합니다.

이 에이전트의 초능력은 다음과 같습니다: 엔트리 포인트 (entry points)를 매핑하고, 데이터 흐름 (data flows)을 추적하며, 현재 아키텍처 (architecture)를 비판적으로 분석합니다. 또한 비즈니스 로직 (business logic)이 UI 레이어 (UI layer)로 유출되어 Clean Architecture (클린 아키텍처)를 위반하고 있다면 이를 적극적으로 지적합니다. 브레인스토밍 세션이 완료되면, 이 에이전트는 기술 부채 (tech debts)와 경계 사항을 정리한 가공되지 않은 요약본인 "Project Discovery Draft (프로젝트 탐색 초안)"를 선제적으로 생성하여 Product Manager (제품 관리자)에게 전달합니다.

Phase 1: Requirement Definition (요구사항 정의)
@ProductManagerPRD 소개

Discovery Draft를 손에 쥐었거나 머릿속에 가공되지 않은 아이디어가 있다면, 이제 Product Manager 에이전트가 바통을 이어받습니다. 이 에이전트의 유일한 목적은 인간의 아이디어를 구조화된 PRD (Product Requirements Document, 제품 요구사항 문서)로 번역하는 것입니다. 이 에이전트는 사용자 스토리 (user stories), 비즈니스 목표 (business goals), 그리고 성공 지표 (metrics of success)를 정의하여, 단 한 줄의 코드가 작성되기 전에 "왜 (Why)"라는 목적이 확고히 수립되도록 보장합니다.

Phase 2: Interrogation & Edge Cases (심문 및 엣지 케이스)
*@ClarificationAnalyst 소개 ("Grill Me" 프로토콜 탑재)
*
이 단계는 게이트키퍼 (gatekeeper) 역할을 합니다. Clarification Analyst는 PRD를 읽고 이를 무너뜨리려고 시도합니다. AI가 쏟아내는 텍스트의 벽에 사용자가 압도당하는 것을 방지하기 위해, 이 에이전트에는 두 가지 엄격한 규칙을 강제하는 혁신적인 "Grill Me" 프로토콜이 탑재되어 있습니다:

1. 단 하나의 질문만: 질문은 반드시 순차적으로 던져야 합니다. 기관총처럼 질문을 퍼부어서는 안 됩니다.

2. 힘든 작업 수행: "에러를 어떻게 처리해야 할까요?"와 같이 게으르고 개방적인 질문을 던지는 것은 금지됩니다. 대신, 구체적인 트레이드오프 (trade-offs)를 제안해야 합니다: "타임아웃 에러의 경우, (A) 조용히 3번 재시도할까요, 아니면 (B) '다시 시도' UI를 보여줄까요? 저는 A를 추천합니다. 동의하십니까?"

Phase 3: Architecture & Data Contracts (아키텍처 및 데이터 계약)
@SpecificationArchitect를 만나보세요

PRD (제품 요구사항 문서)가 완벽해지면, Specification Architect가 바통을 이어받아 "어떻게(How)" 구현할지를 정의합니다. 이 에이전트는 일관성을 유지하기 위해 기존 코드베이스를 조사합니다.

적응형 파일 전략 (Adaptive File Strategy): 기능이 작다면 기존 파일에 명세(spec)를 추가합니다. 만약 거대한 시스템이라면, 이를 여러 개의 모듈형 파일(예: spec-auth.md, spec-db.md)로 분할하고 spec-index.md를 통해 서로 연결합니다.

아키텍처 결정 기록 (ADRs, Architecture Decision Records): 이 단계에서 내려진, 되돌리기 어려운 기술적 결정들은 영구적으로 문서화됩니다.

Phase 4: Roadmap Generation (로드맵 생성)
@PlannerArchitect를 만나보세요

이제 PRD와 기술 명세(Tech Specs)가 준비되었습니다. 이제 Planner Architect가 이 방대한 마크다운(markdown) 문서들을 원자 단위의 실행 가능한 단계별 작업으로 분해합니다. 이는 개발 에이전트들이 문맥(context)을 잃지 않고 순차적으로 실행할 수 있는 로드맵을 생성합니다.

Phase 5 & 6: Execution and Remediation (실행 및 수정)
Dev, QA, 그리고 Bug Remediation Squad를 만나보세요

God Mode Dev: 이 에이전트는 실행자입니다. 플래너(planner)의 로드맵을 따라 실제 애플리케이션 코드를 번개 같은 속도로 작성합니다.

@ExpertCodeReviewer: 명세(specifications)를 바탕으로 코드를 검증합니다. Dev 에이전트가 실제로 Phase 3에서 정의된 스키마(schema)를 따랐는지 확인합니다.

@BugRemediationArchitect: 문제가 발생했을 때, 이 에이전트는 추측하지 않습니다. 에러 로그를 추적하고, 스택 트레이스(stack trace)를 분석하며, 주변 아키텍처를 파괴하지 않고 정밀한 수정(surgical fixes)을 적용합니다.

🛠️ 이 에이전트들을 IDE에 통합하는 방법
"이 마크다운 기반의 에이전트들을 어떻게 내 코드 에디터로 가져올 수 있을까?"라는 의문이 들 수도 있습니다. 이는 놀라울 정도로 간단하며, 현대적인 AI 워크플로우(workflows)와 환상적으로 작동합니다.

방법 1: GitHub Copilot (Workspace Instructions)
GitHub Copilot Chat과 함께 VS Code를 사용한다면, 이러한 에이전트들을 특정 프로젝트에 바인딩(bind)할 수 있습니다.

프로젝트 루트(root)에 .github 폴더를 생성합니다.

그 안에 copilot-instructions.md 파일을 생성합니다.

원하는 에이전트의 시스템 프롬프트(System Prompt)(예: Clarification Analyst의 핵심 지침 및 기술 템플릿)를 이 파일에 붙여넣습니다.
Copilot은 이 파일을 자신의 시스템 가드레일(guardrails)로 자동 인식하여, 채팅 동작을 해당 에이전트의 페르소나(persona)에 맞게 변환합니다.

방법 2: Google Antigravity (Standalone Setup)
Google Antigravity와 같이 방해 요소가 없는 비동기식(asynchronous) 작성 환경을 선호한다면 다음과 같이 진행합니다.

워크스페이스에 .agents 또는 docs/agents 폴더를 생성합니다.

그곳에 .agent.md 및 .skill.md 파일을 저장합니다.

이 파일들을 수동적인 표준 운영 절차(SOPs)로서 사이드바에 유지합니다. prd.md를 작성할 때, 이 에이전트 파일들은 AI 작업에 대한 컨텍스트 참조(context reference) 역할을 수행합니다.

방법 3: OpenCode (Terminal Executor)
궁극의 바이브 코딩(Vibe Coding) 설정을 원한다면, 메인 화면에서 코드를 작성하는 동안 터미널에서 에이전트를 직접 실행하십시오.

에이전트 마크다운(markdown) 파일들을 다운로드합니다.

시스템 프롬프트 플래그(system prompt flag)를 사용하여 터미널 세션에 에이전트를 로드합니다. 예시:
opencode --system-prompt .agents/BrainstormingExplorerAnalyst.md
대화하듯 명령하십시오: "프로젝트 파일들을 읽고, 내 최신 PRD 초안에 대해 Grill Me 프로토콜을 시작해줘."

결론 및 리소스
SDLC 2.0은 단순히 코드를 더 빨리 쓰는 것에 관한 것이 아니라, 소프트웨어를 더 스마트하게 작성하는 것에 관한 것입니다. GitHub Spec Kit 방법론을 활용하고 커스텀 에이전트(Custom Agents)에 엄격한 페르소나를 부여함으로써, 우리는 AI 환각(hallucinations)을 제거하고, 아키텍처의 무결성(architectural integrity)을 유지하며, 우리의 역할을 "프로그래머(Programmers)"에서 "시스템 디렉터(System Directors)"로 진정하게 격상시킵니다.

오늘 바로 자신만의 AI 엔지니어링 팀을 오케스트레이션(orchestrating)하고 싶다면, 제 리포지토리(repository)에서 모든 템플릿, 에이전트 파일, 기술 문서를 직접 가져가시기 바랍니다:

👉 Awesome Copilot ID 리포지토리 살펴보기

로컬 워크스페이스에서 여러 AI 에이전트를 오케스트레이션(orchestrating)해 보셨나요? 여러분의 워크플로(workflow)를 아래 댓글로 알려주세요!

방법 3: OpenCode (터미널 실행기)
궁극의 바이브 코딩 (Vibe Coding) 설정을 원한다면, 메인 화면에서 코드를 작성하는 동안 터미널에서 에이전트를 직접 실행하세요.

1. 에이전트 마크다운 (markdown) 파일을 다운로드합니다.

2. 시스템 프롬프트 (system prompt) 플래그를 사용하여 터미널 세션에 에이전트를 로드합니다. 예시:
   opencode --system-prompt .agents/BrainstormingExplorerAnalyst.md

3. 대화하듯 지시합니다: "프로젝트 파일들을 읽고, 내 최신 PRD 초안에 대해 Grill Me 프로토콜을 시작해 줘."

결론 및 리소스
SDLC 2.0은 단순히 코드를 더 빨리 작성하는 것에 관한 것이 아니라, 소프트웨어를 더 스마트하게 작성하는 것에 관한 것입니다. GitHub Spec Kit 방법론을 활용하고 커스텀 에이전트 (Custom Agents)에 엄격한 페르소나 (personas)를 부여함으로써, 우리는 AI 환각 (hallucinations)을 제거하고, 아키텍처의 무결성 (architectural integrity)을 유지하며, 우리의 역할을 "프로그래머 (Programmers)"에서 "시스템 디렉터 (System Directors)"로 진정하게 격상시킵니다.

오늘 바로 여러분만의 AI 엔지니어링 팀을 오케스트레이션하기 시작하고 싶다면, 제 리포지토리 (repository)에서 모든 템플릿, 에이전트 파일, 기술 문서를 직접 가져가시기 바랍니다:

👉 Awesome Copilot ID 리포지토리 살펴보기

로컬 워크스페이스에서 여러 AI 에이전트를 오케스트레이션(orchestrating)해 보셨나요? 여러분의 워크플로 (workflow)를 아래 댓글로 알려주세요!