Claude Code를 위한 에이전트 워크플로우 (Agentic Workflows) 스캐폴딩 CLI를 구축했습니다

Claude Code를 사용하는 대부분의 개발자들은 동일한 방식으로 작업합니다: 하나의 긴 대화, 작업 사이의 수동 프롬프팅 (Manual Prompting), 그리고 모델이 무엇을 하고 있었는지 놓칠 정도로 커져 버리는 컨텍스트 (Context). 이 방식도 작동은 하지만, 확장성 (Scale)이 없습니다.

저는 이를 해결하기 위해 AgentKit을 구축했습니다. 이는 모든 프로젝트를 위한 오케스트레이션 레이어 (Orchestration Layer)를 생성하는 CLI입니다. 즉, Claude Code에게 누가 되어야 하는지, 무엇을 구축해야 하는지, 그리고 전문화된 에이전트 (Agents) 간에 어떻게 자동으로 업무를 인계할지를 알려주는 파일들을 생성합니다.

작동 방식

사용자는 구축하고자 하는 내용을 설명하는 평문 형태의 청사진 (Blueprint)을 작성합니다:

# Todo App — Blueprint

## Goal
...

그리고 명령어 하나를 실행합니다:

npx @patricksardinha/agentkit-cli init --blueprint PROJECT_BLUEPRINT.md

AgentKit은 네 개의 파일을 생성합니다:

• CLAUDE.md — 모든 에이전트가 시작하기 전에 읽는 상시 브리핑 (Standing Brief)
• AGENT_WORKFLOW.md — Claude Code가 Phase 0 단계에서 채워 넣을 플레이스홀더 (Placeholder)
• PLAYBOOK.md — 자율 실행 엔진 (Autonomous Execution Engine)
• README.md — 청사진에서 추출된 프로젝트 문서

그 다음 Claude Code를 열고 하나의 지시사항을 입력합니다:

Read PLAYBOOK.md and execute the procedure.

이후에 일어나는 일

Claude Code는 자동으로 세 단계에 걸쳐 실행됩니다.

Phase 0 — 분해 (Decomposition): 청사진을 읽고 전문화된 에이전트 목록을 제안합니다. 무언가가 구축되기 전에 사용자가 이를 검증합니다.

기술 강화 일시 중지 (Skills enrichment pause): Claude Code가 에이전트 폴더를 생성하고 대기합니다. 실행이 시작되기 전에 API 문서, 스키마 (Schemas), 또는 기타 컨텍스트 파일들을 관련 에이전트 폴더에 넣을 수 있습니다.

Phase 1 — 실행 (Execution): 각 에이전트가 순차적으로 실행되며, 성공 기준을 검증하고, 실패 시 재시도하며, 진정으로 막혔을 때만 사용자에게 에스컬레이션 (Escalation)합니다.

실제 사례

저는 AgentKit을 사용하여 Ollama를 통한 로컬 RAG (Retrieval-Augmented Generation) 기능이 포함된 Tauri v2 앱인 DevLog Desktop을 구축했습니다.

Claude Code 세션 한 번 이후의 결과:

• 6개의 에이전트가 자율적으로 실행됨
• 68개의 테스트 통과
• Windows 설치 프로그램 생성 (MSI + NSIS)
• 전체 영어/프랑스어 국제화 (i18n), 다크 모드, 시맨틱 검색 (Semantic Search) 지원

설계 선택 사항 (Design choices)

도구 내부에 AI가 없습니다. AgentKit은 순수하게 구조적입니다 — 즉, 마크다운 (Markdown) 파일을 생성할 뿐입니다. 지능은 AgentKit이 아닌 Claude Code에 존재합니다. 이는 API 키가 필요 없고, 비용이 발생하지 않으며, 특정 벤더 종속 (Vendor lock-in)이 없음을 의미합니다.

Phase 0는 항상 실행됩니다. 대부분의 개발자는 작업을 에이전트 (Agents)로 어떻게 최적으로 분할해야 하는지 알지 못합니다. AgentKit은 사용자가 청사진 (Blueprint)을 제공하든 아니든, 매번 그 결정을 Claude Code에 위임합니다. 사용자가 의도 (Intent)를 설명하면, Claude Code가 구조를 설계합니다.

스택 감지 우선, 대화형 폴백 (Fallback). AgentKit은 프로젝트 디렉토리를 읽어 스택 (Stack)을 감지합니다. 만약 아무것도 발견되지 않으면 (새로운 빈 프로젝트인 경우), 지원되는 스택 목록인 React, Next.js, Tauri, FastAPI, Express, Node.js 중에서 사용자에게 대화형으로 질문합니다.

사용해 보기

# 모든 프로젝트에서 (빈 프로젝트 또는 기존 프로젝트)
npx @patricksardinha/agentkit-cli init

...

GitHub: https://github.com/patricksardinha/agentkit-cli

npm: https://www.npmjs.com/package/@patricksardinha/agentkit-cli

피드백을 환영합니다.