Sana Hassan(마크텍포스트 컨설팅 인턴)이 최근 Anthropic API의 구조적 레이어인 SuperClaude 프레임워크를 활용한 고급 워크플로우 구축 튜토리얼을 공개했다. 이 프레임워크는 마크다운(Markdown) 기반의 커맨드, 에이전트, 모드를 시스템 프롬프트에 동적으로 주입하는 파이썬 브리지를 핵심으로 한다. 이를 통해 개발자는 모델 호출 전 단계에서 필요한 행동 지침을 유연하게 교체하며, 브레인스토밍부터 보안 분석, 프론트엔드 구현에 이르는 복잡한 태스크를 일관된 역할 기반으로 수행할 수 있게 되었다.

터미널 환경에서 Rich(파이썬 터미널 출력 라이브러리) 콘솔을 활용하면 Colab 출력물을 구조화할 수 있으며, 프레임워크 저장소를 로컬로 클론하여 마크다운 기반의 자산들을 스캔하는 방식이 사용된다. 세션 저장 및 로드 기능을 통해 다단계 개발 프로세스의 컨텍스트를 유지하며 작업 효율을 높이는 구조가 관찰된다는 점이 특히 주목할 만하다. 이는 단순한 일회성 프롬프팅이 아니라, 특정 목적에 최적화된 '모드'와 '에이전트'를 조합해 AI의 행동 양식을 정밀하게 제어하려는 시도로 분석된다. 본 가이드는 깃허브(GitHub) 저장소 요약 CLI 도구를 제작하는 전 과정을 통해 브레인스토밍, 설계, 구현, 테스트, 문서화로 이어지는 체인형 워크플로우의 실효성을 입증한다.

SuperClaude 프레임워크의 3대 구성 요소와 초기 설정

코드 내에 하드코딩된 텍스트가 비대해지면 유지보수가 어려워지는 문제가 발생한다. SuperClaude 프레임워크는 이 문제를 해결하기 위해 프롬프트의 구성 요소를 마크다운(Markdown, 텍스트 기반의 경량 마크업 언어) 파일로 완전히 분리하여 관리하는 모듈화 구조를 취한다. 프레임워크의 핵심은 커맨드(Commands), 에이전트(Agents), 모드(Modes)라는 세 가지 요소로 정의된다. 커맨드는 모델이 수행해야 할 구체적인 작업 지침과 단계별 절차를 정의하며, 에이전트는 모델이 취해야 할 전문적인 페르소나와 지식 범위를 설정한다. 모드는 최종 응답의 스타일, 톤, 또는 토큰 효율성을 위한 제약 조건을 결정하는 역할을 수행한다. 이러한 구조는 프롬프트 수정 시 파이썬 코드를 수정하고 재배포할 필요 없이 마크다운 파일만 편집하면 즉시 모델의 행동이 변경되는 유연한 환경을 제공한다.

파이썬 기반의 브리지(Bridge) 구현체는 이러한 정적 파일들을 실제 모델 호출과 연결하는 매개체 역할을 한다. 브리지는 실행 시점에 저장소 내의 마크다운 파일들을 스캔하여 필요한 구성 요소를 동적으로 로드하고, 이를 하나의 정교한 시스템 프롬프트로 결합한다. 이 과정에서 Anthropic API와 연결되어 모델이 현재 어떤 역할로, 어떤 지침에 따라, 어떤 형식으로 답해야 하는지를 명확히 인지하게 만든다. 단순한 텍스트 결합을 넘어, 개발자는 브리지 클래스를 통해 워크플로우를 제어하며 모델의 행동 양식을 정교하게 튜닝할 수 있다. 이는 프롬프트 엔지니어링의 단계를 단순한 텍스트 작성이 아니라, 파일 시스템 기반의 구성 관리 단계로 격상시킨 설계로 관찰된다.

출력 최적화와 세션 유지 기능은 실무적인 운영 효율을 높이기 위해 함께 구현된다. 터미널 환경에서 가독성을 높이기 위해 Rich(파이썬 기반의 풍부한 텍스트 출력 라이브러리) 콘솔 라이브러리를 사용하여 구조화된 출력을 생성한다. 이는 복잡한 로그나 다단계 응답을 분석할 때 개발자의 인지 부하를 줄이는 효과를 준다. 또한, 복잡한 다단계 개발 작업에서 컨텍스트를 유실 없이 유지하기 위해 세션 저장(save) 및 로드(load) 메서드를 포함한다. 이는 단발성 질의를 넘어 브레인스토밍, 아키텍처 설계, 구현, 테스트로 이어지는 긴 호흡의 개발 사이클을 지원하기 위한 필수 장치다. 저장된 세션을 다시 불러옴으로써 이전 단계의 맥락을 그대로 유지한 채 작업을 재개할 수 있으며, 이는 AI 보조 개발 환경에서 상태 관리의 연속성을 보장하는 핵심 기능으로 작동한다.

파이썬 브리지를 통한 시스템 프롬프트 동적 주입 메커니즘

시스템 프롬프트를 수정할 때마다 API 호출 코드를 직접 건드리는 방식은 유지보수 효율을 급격히 떨어뜨린다. SuperClaude 프레임워크는 이 지점에서 프롬프트를 코드와 완전히 분리하여 마크다운 파일 형태로 관리하는 파이썬 브리지 구조를 채택한다. 모델 호출 직전에 필요한 자산을 동적으로 결합함으로써, 정적인 프롬프트가 아니라 상황에 따라 변하는 가변적 지침 체계를 구축하는 방식이 관찰된다.

로컬 저장소의 스캔은 전체 데이터 흐름의 시작점이다. 먼저 클론된 저장소 내의 모든 마크다운 파일을 탐색하여 커맨드, 에이전트, 모드라는 세 가지 자산 버킷으로 분류하는 과정이 수행된다. 사용자가 특정 에이전트나 모드를 선택하면, 브리지는 기본 지침에 해당 마크다운 파일의 내용을 정교하게 병합하여 최종 시스템 프롬프트를 생성한다. 이렇게 생성된 프롬프트는 Anthropic API로 전송되어 모델의 페르소나와 응답 스타일을 즉각적으로 결정하며, 호출 시점마다 최적화된 지침이 주입된다.

SuperClaude 클래스는 이 메커니즘의 핵심 구현체로서 프레임워크 자산과 API 사이의 인터페이스 역할을 수행한다. 단순히 텍스트를 합치는 것을 넘어, 가이드된 워크플로우를 실행하는 run 메서드와 세션 이력을 보존하는 save 및 load 메서드를 통해 연속적인 개발 환경을 지원한다. 특히 세션 저장 및 복원 기능은 복잡한 AI 보조 소프트웨어 개발 작업에서 컨텍스트 유지 비용을 획기적으로 줄이는 실무적 장치로 작동한다. 개발자는 이를 통해 브레인스토밍부터 구현까지 이어지는 다단계 워크플로우를 단절 없이 유지할 수 있다.

python
class SuperClaude:
 def __init__(self, api_key, model="claude-3-5-sonnet"):
 self.api_key = api_key
 self.model = model
 self.assets = {"commands": {}, "agents": {}, "modes": {}}
 self.session_history = []

 def load_assets(self, repo_path):

로컬 저장소 스캔 및 버킷 분류 로직

pass

def run(self, prompt, agent=None, mode=None, command=None):

system_prompt = self.assemble_system_prompt(agent, mode, command)

Anthropic API 호출 및 응답 처리

response = self.call_anthropic_api(system_prompt, prompt)

self.session_history.append({"prompt": prompt, "response": response})

return response

def save(self, filepath):

세션 이력을 파일로 저장

pass

def load(self, filepath):

저장된 세션 이력을 불러와 복원

pass

def assemble_system_prompt(self, agent, mode, command):

기본 지침 + 선택된 자산 결합

return f"Base Instruction\n{agent}\n{mode}\n{command}"

정적 프롬프팅과 SuperClaude 구조적 레이어의 차이

LLM을 사용할 때 개발자가 가장 먼저 마주하는 제약은 매번 반복되는 시스템 프롬프트의 작성 과정이다. 기존의 정적 프롬프팅 방식은 사용자가 직접 긴 지시문을 수동으로 작성하거나, 미리 정의된 고정 템플릿에 입력값을 채워 넣는 형태로 운영된다. 이러한 방식은 프롬프트의 길이가 길어질수록 모델이 지시사항의 우선순위를 혼동하거나, 세션이 바뀔 때마다 응답의 일관성이 결여되는 문제가 빈번하게 관찰된다. 특히 복잡한 프로젝트일수록 프롬프트의 양이 방대해지며, 이는 곧 불필요한 토큰 소모와 응답 속도 저하라는 실무적 비용으로 이어진다. 반면 SuperClaude(슈퍼클로드, Anthropic API 상단에 구축된 구조적 프롬프트 레이어)는 단일 프롬프트의 한계를 넘어 역할 인식(Role-aware) 기반의 모듈형 구조로의 전환을 제안한다.

상황에 따라 최적화된 모드(Mode)를 전환하며 응답 스타일과 토큰 효율성을 정밀하게 제어하는 지점이 SuperClaude의 핵심이다. 단순히 페르소나를 부여하는 수준을 넘어, 재사용 가능한 프레임워크 자산을 통해 명령(Command), 에이전트(Agent), 모드(Mode)를 동적으로 조합하는 구조를 갖춘다. 예를 들어, 아이디어 발산이 필요한 브레인스토밍 단계에서는 창의적 사고를 유도하는 모드를 적용하고, 실제 코드 구현 단계에서는 불필요한 설명을 배제하고 정확한 구문만을 출력하는 토큰 효율적 모드로 즉시 전환하는 식이다. 이러한 구조적 레이어는 프롬프트의 파편화를 막고 조직 전체가 공유할 수 있는 일관된 행동 양식을 자산화한다는 점에서 기존의 수동 템플릿 방식과 궤를 달리한다.

복잡한 소프트웨어 개발 태스크에서 이러한 전환은 특히 실무적 가치를 발휘한다. 프론트엔드 구현, 보안 분석, 비즈니스 전략 수립과 같이 요구되는 전문성이 서로 다른 작업들을 하나의 세션 내에서 수행할 때, 각 단계에 맞는 전문화된 행동을 즉각적으로 유도할 수 있기 때문이다. 개발자는 더 이상 모델에게 매번 구체적인 역할 수행 방식을 설명하기 위해 시간을 허비할 필요가 없다. 대신 검증된 마크다운 기반의 행동 파일들을 시스템 프롬프트에 동적으로 로드함으로써, 모델이 현재 수행해야 할 작업의 맥락을 정확히 인지하게 만든다. 결과적으로 이는 프롬프트 엔지니어링의 영역을 개인의 경험적 기술에서 시스템적인 프레임워크 관리 영역으로 확장시키며, 대규모 프로젝트의 유지보수 효율성과 결과물의 예측 가능성을 동시에 높이는 결과로 이어진다.

GitHub 요약 CLI 도구 제작으로 본 다단계 워크플로우의 실효성

GitHub 저장소 요약 CLI(Command Line Interface, 명령줄 인터페이스) 도구를 제작하는 과정은 단편적인 프롬프트 입력과 구조화된 워크플로우의 차이를 명확히 보여준다. 기존의 AI 협업 방식이 개별 작업 단위로 프롬프트를 던지고 응답을 받는 파편화된 형태였다면, SuperClaude 프레임워크를 통한 접근은 설계부터 문서화까지 하나의 흐름으로 연결된다. 개발자는 브레인스토밍 단계에서 도출된 아이디어를 아키텍처 설계로 즉시 전이시키고, 이를 다시 실제 구현 코드로 연결하는 체인형 프로세스를 관찰할 수 있다. 이러한 연속성은 AI가 이전 단계의 결정 사항을 기억하고 이를 다음 단계의 제약 조건으로 활용하게 함으로써, 맥락 손실로 인해 발생하는 반복적인 수정 요청을 획기적으로 줄이는 결과로 이어진다. 이는 개발자가 AI에게 매번 배경 설명을 반복해야 했던 인지적 부하를 제거하는 실질적인 이점으로 작용한다.

브레인스토밍, 아키텍처 설계, 구현, 테스트, 그리고 최종 문서화라는 5단계의 선형적 구조를 실제 워크플로우는 따른다. 각 단계는 독립적인 세션이 아니라 단일 세션 내에서 컨텍스트를 유지하며 진행되는데, 이는 엔드투엔드(End-to-End, 전 과정 통합) 프로젝트 완성을 가능하게 하는 핵심 동력이다. 예를 들어 아키텍처 설계 단계에서 정의된 모듈 구조는 구현 단계의 함수 설계에 그대로 반영되며, 테스트 단계에서 발견된 엣지 케이스는 다시 구현 코드를 수정하는 피드백 루프로 작동한다. 마지막 문서화 단계에서는 앞선 모든 과정의 기록이 이미 컨텍스트에 포함되어 있어, 개발자가 별도로 설명하지 않아도 도구의 설계 의도와 사용법이 정확하게 기술되는 양상이 관찰된다. 결과적으로 설계와 구현 사이의 괴리가 최소화되며 전체 개발 주기의 속도가 가속화된다.

다양한 전문 영역으로 이러한 다단계 워크플로우의 실효성은 확장된다. 프론트엔드 코딩 모드에서는 UI 컴포넌트의 계층 구조를 설계하고, 보안 리뷰 모드에서는 코드의 취약점을 분석하며, 비즈니스 분석이나 딥 리서치 플래닝 모드에서는 전략적 로드맵을 수립하는 식으로 활용 모드를 유연하게 전환하며 작업할 수 있다. 실무 관점에서 이는 AI를 단순한 코드 생성기가 아니라, 프로젝트의 생애주기 전체를 함께 관리하는 가상 파트너로 격상시키는 변화를 의미한다. 6개월 뒤의 개발 환경에서는 이러한 체인형 프로세스가 표준화되어, 기획서라는 텍스트가 자동으로 아키텍처와 테스트 코드로 변환되는 파이프라인이 코드베이스에 내재화될 가능성이 높다고 제안한다. 이는 개별 개발자의 역량에 의존하던 AI 활용 능력을 조직 차원의 시스템적 워크플로우로 자산화하는 과정이 될 것이다.

한국 AI 실무 환경에서의 '에이전틱 워크플로우' 적용 가능성

동일한 프롬프트를 입력해도 모델의 업데이트나 컨텍스트의 미세한 차이에 따라 응답 품질이 불규칙하게 변하는 현상은 개발자가 체감하는 가장 큰 문제다. 단순히 질문을 잘 던지는 기법을 넘어, 정교하게 설계된 행동 지침 레이어를 구축하는 에이전틱 워크플로우(Agentic Workflow, AI가 스스로 계획을 세우고 도구를 사용하는 작업 흐름)가 실질적인 대안으로 관찰된다. 이는 실무 현장에서 개인용 개발 코파일럿이나 보안 리뷰어, 혹은 전문 리서치 어시스턴트를 구축할 때 즉각적인 효용을 제공한다. 예를 들어 보안 리뷰어 에이전트의 경우, 단순한 취약점 탐지를 넘어 특정 보안 표준 가이드라인을 모듈화된 지침으로 주입함으로써 검수 기준의 일관성을 강제할 수 있다. 특정 역할의 페르소나와 제약 사항을 마크다운 기반의 모듈로 분리해 관리하면 AI가 수행해야 할 작업의 경계가 명확해지며 결과물의 신뢰도가 비약적으로 상승한다.

기존의 많은 기업이 도입한 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 방식은 외부 지식을 제공하는 데 집중하지만, 그 지식을 어떻게 처리하고 어떤 단계로 추론할지에 대한 제어권은 여전히 모델의 확률적 생성에 의존하는 한계가 있다. 여기서 제안하는 구조적 접근은 프롬프트를 단순한 일회성 텍스트가 아니라 재사용 가능한 소프트웨어 자산으로 취급하는 것이다. 프롬프트 엔지니어링의 파편화를 막기 위해 명령어, 에이전트, 모드를 각각의 독립된 파일로 분리하고 이를 런타임에 동적으로 조합하는 방식은 현대 소프트웨어 공학의 모듈화 논리와 궤를 같이한다. 이러한 자산화 과정은 개별 개발자의 감각이나 경험에 의존하던 프롬프트 최적화 작업을 조직 차원의 표준 라이브러리로 전환하는 계기가 된다. 이는 곧 특정 인력의 이탈과 관계없이 AI 에이전트의 성능을 유지하고 지속적으로 개선할 수 있는 운영 체계를 구축하는 것과 같다.

일관된 응답 품질과 엄격한 형식이 계약의 핵심인 한국의 B2B AI 서비스 환경에서 이러한 프롬프트 모듈화의 필요성은 더욱 증대된다. 국내 기업용 솔루션 시장에서는 고객사마다 요구하는 출력 형식과 내부 비즈니스 로직이 매우 상이하기 때문에, 전체 시스템 프롬프트를 수정하지 않고도 커스텀 커맨드(Custom Command, 사용자 정의 명령어)를 추가하여 대응하는 전략이 유효하다. 또한 작업의 복잡도에 따라 모델 스위칭(Model Switching)을 수행함으로써 비용과 성능의 최적점을 찾을 수 있다. 복잡한 비즈니스 전략 수립이나 딥 리서치 계획 같은 고부하 추론 작업에는 고성능 모델을 배치하고, 단순한 텍스트 요약이나 형식 변환에는 경량 모델을 연결하는 유연한 운용이 가능해진다. 결국 정교하게 설계된 행동 지침 레이어는 AI 에이전트가 예측 불가능한 응답을 내놓는 리스크를 줄이는 실질적인 안전장치로 작동하며, 이는 곧 B2B 제품의 상용화 수준을 결정짓는 핵심적인 기술 경쟁력이 된다.