Auto-Claude 설치 및 기본 기능 사용해보기 - Spec-Driven Development: AI가 스펙 작성부터 코드 검증까지
-
728x90
안녕하세요. 갓대희 입니다.
오늘은 Auto-Claude에 대해 아주 가볍게 살펴보려고 한다. 이런 도구도 있구나 정도로 살펴보면 좋을 것 같다.
Auto-Claude: Claude Code를 자율적 멀티 에이전트(여러 AI가 동시에 작업하는 방식) 코딩 시스템으로 확장하는 오픈소스 프레임워크(소프트웨어 개발을 위한 기본 틀) 계획(Plan), 구현(Build), 검증(Verify)의 전 과정을 최소한의 인간 개입으로 처리하며, 최대 12개의 에이전트(AI 작업 단위)를 동시에 실행하고 칸반 보드(작업 카드를 배치해 진행 상황을 시각화하는 도구)를 통해 작업을 시각화할 수 있다.
AI 코딩 도구의 발전 속도가 빨라지면서, 단순한 코드 자동완성을 넘어 전체 개발 프로세스를 자율적으로 처리하는 시스템에 대한 관심이 높아지고 있다. Anthropic의 Claude Code는 터미널 기반의 강력한 AI 코딩 어시스턴트로 자리 잡았지만, 복잡한 프로젝트에서 여러 작업을 동시에 관리하고 자율적으로 실행하는 데는 한계가 있었다.
Auto-Claude는 이러한 한계를 극복하기 위해 등장한 프레임워크로, Claude Code 위에 에이전트 오케스트레이션(여러 AI 에이전트를 조율하고 관리하는 것), 계획 계층, 검증 루프, 강력한 도구를 추가하여 완전한 자율 코딩 시스템을 구현한다.
이 글에서는 Auto-Claude의 공식 문서와 커뮤니티 자료를 바탕으로 주요 기능, 설치 방법, 사용법을 정리한다.
Auto-Claude란 무엇인가?
Auto-Claude는 자율적 멀티 에이전트 코딩 프레임워크로, 사용자가 목표를 설명하면 AI 에이전트들이 자동으로 계획 수립부터 구현, 검증까지 전 과정을 처리한다. (출처: GitHub 공식 문서)
공식 문서 출처 "Autonomous multi-agent coding framework that plans, builds, and verifies software with minimal human intervention." (사람의 개입을 최소화한 상태에서 소프트웨어를 계획(Plan), 구축(Build), 검증(Verify)하는 자율형 멀티 에이전트 코딩 프레임워크(Autonomous multi-agent coding framework)) GitHub - AndyMik90/Auto-Claude
Claude Code와의 차이점
구분
Claude Code
Auto-Claude
실행 방식
단일 세션(하나의 작업 연결) CLI(명령어 입력 방식)
멀티 에이전트 GUI(시각적 인터페이스)/CLI
동시 실행
1개 세션
최대 12개 에이전트
작업 관리
수동
칸반 보드 자동화
코드 병합
수동
AI 기반 자동 머지(여러 코드를 하나로 합치기)
품질 검증
사용자 확인
자체 검증 QA(품질 보증) 루프
세션 간 기억
제한적
메모리 레이어
오픈소스 및 라이선스
Auto-Claude는 완전히 무료로 사용할 수 있는 오픈소스 프로젝트다. 단, AGPL-3.0 라이선스(오픈소스 라이선스의 한 종류)를 따르므로 수정 배포 또는 서비스 운영 시 소스 코드 공개 의무가 있다. 비공개 사용이 필요한 경우 상용 라이선스를 별도로 협의할 수 있다.
주요 기능
1. 자율 작업 처리
사용자가 프롬프트(AI에게 지시하는 명령어나 질문)로 목표를 설명하면, Auto-Claude는 자율적으로 계획 수립, 코드 구현, 품질 검증의 전 과정을 처리한다. 기존 Claude Code가 대화형으로 한 단계씩 진행했다면, Auto-Claude는 전체 워크플로우(작업 진행 흐름)를 자동으로 실행한다.
자율 작업 처리 흐름
계획(Planning): 목표를 분석하고 세부 작업으로 분해
구현(Building): 서브 에이전트(하위 작업 담당 AI)들이 병렬로 코드 작성
검증(Verifying): 자체 QA 루프로 품질 확인
병합(Merging): AI 기반 충돌 해결 및 코드 통합
2. 칸반 보드 UI
Auto-Claude는 직관적인 칸반 보드 인터페이스를 제공하여, 여러 에이전트의 작업 진행 상황을 실시간으로 시각화한다. 계획 단계부터 완료까지 각 작업의 상태를 한눈에 파악할 수 있다.
개발 팁 칸반 보드에서 수동 새로고침 버튼을 사용하여 최신 상태를 확인할 수 있다. 작업 검토 시 터미널 드롭다운 옵션을 활용하면 특정 에이전트의 출력을 직접 확인할 수 있다. (출처: v2.7.2 릴리스 노트)
3. 병렬 에이전트 실행 (최대 12개)
Auto-Claude의 핵심 기능 중 하나는 최대 12개의 Claude Code 에이전트를 동시에 실행할 수 있다는 점이다. 각 에이전트는 독립적인 터미널에서 비동기적(동시에 여러 작업을 독립적으로 처리)으로 작업을 수행하며, 원클릭 작업 컨텍스트(작업을 이해하기 위한 맥락 정보) 주입으로 빠르게 병렬 작업을 시작할 수 있다.
4. 격리된 워크스페이스
Git 워크트리(worktree)를 활용하여 각 에이전트가 격리된 환경에서 작업한다. 이를 통해 에이전트 간 코드 충돌을 방지하고, 안전하게 변경사항을 테스트할 수 있다.
5. 자체 검증 QA
내장된 품질 보증(QA) 루프가 자동으로 작성된 코드를 검증한다. 테스트 실행, 린팅(코드 스타일 및 오류 검사), 타입 체크(변수 타입 일치 확인) 등을 자동으로 수행하여 코드 품질을 보장한다.
6. AI 기반 머지
여러 에이전트가 작업한 코드를 병합할 때 발생하는 충돌을 AI가 자동으로 해결한다. 수동으로 충돌을 해결하는 시간을 절약하고, 일관된 코드 스타일을 유지할 수 있다.
7. 메모리 레이어
GRAPHITI_ENABLED 환경변수를 통해 메모리 레이어를 활성화할 수 있다. 에이전트가 세션 간에 인사이트(통찰, 학습 내용)를 유지하여, 이전 작업의 컨텍스트를 기반으로 더 나은 결정을 내릴 수 있다.
8. 플랫폼 통합
GitHub, GitLab, Linear와 통합하여 이슈 가져오기, AI 분석, 머지 요청 생성, 팀 진행 상황 추적 등을 할 수 있다. v2.7.2에서 GitLab 통합이 새롭게 추가되었다.
설치 후 Auto-Claude를 실행하고, Git이 초기화된 프로젝트 폴더를 열어 연결한다. OAuth(외부 서비스 로그인 인증 방식)를 통해 Claude 계정을 인증하면 사용 준비가 완료된다.
// 새 프로젝트를 위한 Git 초기화
mkdir my-project
cd my-project
git init
환경 설정 변수
Auto-Claude는 다양한 환경변수(운영체제에 설정하는 설정값)를 통해 동작을 커스터마이징할 수 있다. (출처: GitHub 공식 문서)
주요 환경변수
# OAuth 토큰 (Claude 인증)
CLAUDE_CODE_OAUTH_TOKEN=your_oauth_token
# 메모리 레이어 활성화
GRAPHITI_ENABLED=true
# 빌드 모델 오버라이드(강제 지정)
AUTO_BUILD_MODEL=claude-4.5-opus
# Linear 통합 (작업 동기화)
LINEAR_API_KEY=your_linear_api_key
# GitLab 토큰 (GitLab 통합 시)
GITLAB_TOKEN=your_gitlab_token
고급 설정 가이드
Auto-Claude 앱 내에서 다양한 설정을 커스터마이징할 수 있다. 설정 화면은 앱 상단 메뉴 또는 설정 아이콘을 통해 접근한다.
Auto-Claude는 추가 메모리 레이어를 활성화하여 에이전트가 세션 간 학습 내용을 유지할 수 있다. 이 기능은 Graphiti MCP 서버를 통해 구현된다.
# 환경변수로 메모리 레이어 활성화
GRAPHITI_ENABLED=true
임베딩 제공자 설정
AI가 코드와 문서를 이해하는 데 사용하는 임베딩(텍스트를 수치화하는 방식) 제공자를 선택할 수 있다:
제공자
장점
단점
Ollama (로컬)
무료, 데이터가 외부로 나가지 않음
로컬에 Ollama 설치 필요, 컴퓨터 성능 필요
OpenAI
설치 불필요, 고품질
API 비용 발생, OpenAI 계정 필요
지능형 모델 전환 (Fallback)
Claude 모델은 일일 사용량 제한이 있다. Auto-Claude는 지능형 모델 전환 기능을 제공하여, 한 모델의 한도에 도달하면 자동으로 다른 모델로 전환한다.
모델 전환 예시
Opus 4.5로 작업 시작
Opus 일일 한도 도달
자동으로 Sonnet 4.5로 전환하여 작업 계속
Sonnet 한도 도달 시 Haiku로 전환 가능
에이전트 프로필 조정 설정에서 각 에이전트의 역할(계획, 코딩, 검증 등)에 맞는 모델을 지정할 수 있다. 예를 들어 계획에는 Opus, 코딩에는 Sonnet을 사용하도록 설정하면 비용을 절약할 수 있다.
GitHub/GitLab 통합
GitHub 또는 GitLab과 연결하면 이슈를 가져오고, PR(풀 리퀘스트)을 생성하고, 팀 진행 상황을 추적할 수 있다.
# GitLab 통합 (환경변수)
GITLAB_TOKEN=your_gitlab_personal_access_token
# Linear 통합 (작업 관리 도구)
LINEAR_API_KEY=your_linear_api_key
ex)
기본 사용법
1. 프로젝트 열기
Auto-Claude를 실행하고 메인 대시보드에서 "새 프로젝트 열기" 또는 "이전 프로젝트 열기"를 선택한다. Git이 초기화된 폴더를 선택하면 프로젝트가 로드된다.
ex) 나의 경우 기존 프로젝트로 진행해보자.
2. 작업 생성
칸반 보드에서 새 작업을 추가하고, 프롬프트를 상세하게 작성한다. 예를 들어:
프롬프트 예시 1: 간단한 첫 작업 "간단한 할 일 목록(Todo List) 웹 앱을 만들어줘. 할 일을 추가하고, 완료 표시하고, 삭제할 수 있어야 해. HTML, CSS, JavaScript로 구현하고, 로컬 스토리지에 저장되도록 해줘."
프롬프트 예시 2: 복잡한 작업 "모던 금융 시그널링 앱을 구축하고 싶다. 이 앱은 라이브 API(실시간 데이터 인터페이스)를 통해 모멘텀(상승/하락 추세), 센티멘트(시장 심리), 변동성(가격 변화 폭)과 같은 시장 시그널을 집계하고, AI가 생성한 일일 시장 브리핑을 제공해야 한다."
프롬프트 작성 팁
에러 핸들링, 예외 처리는 자동 생성되지 않는 경우가 많다. 필요하다면 "에러 발생 시 사용자에게 알림 표시" 등 명시적으로 요청하자.
프론트엔드 작업 시 디자인 토큰이나 기존 디자인 시스템이 있다면 함께 전달하면 일관된 UI를 얻을 수 있다.
백엔드 API 개발 시 입출력 형식, 인증 방식 등 요구사항을 구체적으로 명시할수록 결과물의 완성도가 높아진다.
ex) 상기 프롬프트 예시1 간단한 기초 작업을 진행해보자.
- New Task 클릭 > 간단한 할 일 목록(Todo List) 웹 앱을 만들어줘. 할 일을 추가하고, 완료 표시하고, 삭제할 수 있어야 해. HTML, CSS, JavaScript로 구현하고, 로컬 스토리지에 저장되도록 해줘.
- 나의 경우 default 옵션으로 진행하도록 하겠다. > 세팅 완료 후 > Create Task 입력
- 상기 설정을 잘 살펴보면 spec 관련 설정과 모델설정 내용이 보일 것 이다.
Spec-Driven Development
커뮤니티 자료에 따르면, Auto-Claude는 Spec-Driven Development(스펙 주도 개발, 요구사항 명세를 먼저 작성하고 그에 따라 개발하는 방식) 시스템을 내장하고 있다. 이는 OpenSpec, BMAD 등의 프레임워크에서 영감을 받아 고품질 출력을 위한 최적의 워크플로우를 제공한다고 한다.
Spec-Driven Development 워크플로우
작업 설명 입력 및 에이전트 프로필 선택
단계 구성(Phase Configuration)에서 Spec-Driven 시스템 활성화
스펙 생성 단계: 상세 요구사항 명세 자동 생성
구현 단계: 스펙에 따른 코드 자동 생성
검증 단계: 스펙 대비 구현 결과 검증
ex) 이후에 끝까지 직접 진행해보면 스펙 기반으로 작업을 진행하기 위해 spec 문서 생성부터 진행하는것을 볼 수 있다.
모델 설정 및 전환
커뮤니티 자료에 따르면, Auto-Claude는 다양한 Claude 모델을 지원하며 작업 유형에 따라 모델을 지정할 수 있다:
계획(Planning): Opus 4.5 (높은 추론 능력 필요)
코딩(Coding): Opus 4.5 또는 Sonnet 4.5
빠른 작업: Haiku (비용 효율적)
지능형 모델 전환(Intelligent Fallback) 기능을 통해 한 모델의 사용량 제한에 도달하면 자동으로 다른 모델로 전환된다고 한다. 예를 들어, Opus의 일일 한도에 도달하면 Sonnet으로 자동 전환되어 작업을 계속할 수 있다.
- 일단 나의 경우는 별도 조정하지 않고 그냥 진행 해 보겠다.
- 칸반보드 > Planning 영역에 새로운 카드가 하나 추가되는것을 볼 수 있다.
3. 에이전트 실행
작업을 생성한 후 "시작" 버튼을 클릭하면 에이전트가 자율적으로 작업을 수행한다. 칸반 보드에서 진행 상황을 실시간으로 확인할 수 있으며, 에이전트 터미널에서 각 에이전트의 출력을 모니터링할 수 있다.
ex) 시작
- 플랜 모드를 통해 계획을 세우는 모습 > 클릭시 상세 로그 및 진행사항을 확인 할 수 있다.
- 한참 후 Logs살펴보면 planning 단계가 끝난것을 알 수 있다.
- 로그 가장 하단
- 이후 Subtasks (1) 을 클릭해보면 서브 태스크가 생성되어있는것을 볼 수 있다.
- 나의 경우 이때 멈췄는데 하기 트러블 슈팅처럼 다시 인증, stop후 다시 start로 진행해 보았다. 이후 코딩작업을 시작하는 모습.
- 한참 후 Human Review 단계에 와있는것을 볼 수 있다. 확인해보자.
- 다음과 같은 변경사항을 알려준다.
- 우측 상단 View를 클릭하면 변경된 파일 내역을볼 수 있다.
- Open in VS Code 를 통해 소스도 살펴보자. 상기 파일이 생성되어있고 browser로 열어 보았다.
- 정말 간단한 Todo List가 생성되어있다.
- 변경사항을 Stage 할지, 이슈에 대해 변경요청을 할지 선택가능하다. 일단 지금은 Stage Changes로 넘어가본다.
- 변경사항이 적용되었고 "Mark as Done"을 클릭해보자.
- 칸반 보드에서 완료 상태로 체크 되어있는것을 볼 수 있다.
- 최종 완료한 스펙 문서에서부터 계획, 요구사항정의 등 작업진행중에 사용했던 파일 리스트 및 상세 내용도 확인 가능하다.
- 칸반보드 이외에도 로드맵, Context, worktress, github issues 등 여러 기능이 있는데 본격적으로 사용하시는 분들은 살펴보면 좋을 것 같다.
CLI 사용법 (고급)
Auto-Claude는 GUI(시각적 인터페이스) 외에도 CLI(명령줄 인터페이스)를 통해 직접 제어할 수 있다. GUI 없이 터미널에서만 작업하고 싶거나, 자동화 스크립트를 작성할 때 유용하다.
참고 CLI는 선택사항이다. GUI 앱만으로도 모든 기능을 사용할 수 있으며, CLI는 고급 사용자나 자동화가 필요한 경우에 활용한다.
스펙 생성 (대화식)
프로젝트 요구사항을 대화형으로 정의하여 스펙 파일을 생성한다:
# apps/backend 폴더로 이동 후 실행
cd apps/backend
python spec_runner.py --interactive
이 명령어는 대화형 모드로 스펙을 생성한다. AI가 질문을 하면 답변하는 방식으로 요구사항을 정의하면, 자동으로 스펙 파일이 생성된다.
자율 빌드 실행
생성된 스펙을 기반으로 자율 빌드를 실행한다:
# 스펙 번호 001을 기반으로 자율 빌드 실행
python run.py --spec 001
# 빌드 완료 후 메인 브랜치에 병합
python run.py --spec 001 --merge
CLI 명령어 요약
명령어
설명
python spec_runner.py --interactive
대화형으로 스펙 생성
python run.py --spec [번호]
해당 스펙으로 자율 빌드 실행
python run.py --spec [번호] --merge
빌드 후 메인 브랜치에 병합
추가 기능
아이디에이션(Ideation)
커뮤니티 자료에 따르면, Auto-Claude는 아이디에이션 기능을 제공하여 코드 개선, UI/UX, 보안, 성능 등에 대한 아이디어를 자동으로 생성할 수 있다.
아이디어 카테고리
코드 (Code)
리팩토링, 중복 제거, 최적화 제안
UX/UI
사용자 경험 개선, 인터페이스 디자인 제안
문서 (Docs)
README, API 문서, 주석 추가 제안
보안 (Security)
취약점 식별, API 키 노출, 인증 문제 등
성능 (Performance)
병목 지점 식별, 캐싱, 쿼리 최적화 제안
보안 위험 자동 해결 아이디에이션에서 치명적(Critical) 보안 위험이 발견되면, 해당 작업을 "Auto(자동)" 모드로 전환하여 Auto-Claude가 자동으로 문제를 해결하도록 요청할 수 있다. 해결 작업은 칸반 보드에 자동 배포된다.
로드맵 생성 [참고: 커뮤니티 영상]
프로젝트의 기능과 우선순위를 다루는 로드맵을 자동으로 생성할 수 있다고 한다. 이를 통해 장기적인 개발 계획을 수립하고 관리할 수 있다.
Human Review 기능
에이전트가 만드는 모든 변경사항을 사용자가 검토할 수 있도록 Human Review 기능을 설정할 수 있다. 완전 자율 모드와 검토 모드 중 선택 가능하다.
주의사항 및 제한사항
주의 사항
AGPL-3.0 라이선스: Auto-Claude를 수정하여 배포하거나 서비스를 운영할 경우 소스 코드를 공개해야 한다.
API 비용: Claude Pro/Max 구독 또는 API 사용료가 발생한다. 12개 에이전트를 동시 실행하면 토큰(AI 처리 단위, 사용량 기준) 소비량이 크게 증가할 수 있다.
베타 안정성: 최신 기능을 사용하려면 베타 버전을 설치해야 하며, 일부 버그가 있을 수 있다.
Git 필수: Git 워크트리 기능을 활용하므로 Git이 초기화된 프로젝트에서만 동작한다.
주고자 하는 인사이트
아키텍처 먼저: 프로젝트 중반에 대규모 리팩토링(기존 코드의 구조를 개선하는 작업)을 시도하면 실패 확률이 높다. 초기에 구조를 잘 잡아두는 것이 중요하다.
운영 비용 고려: 개발 비용 외에 서버, 데이터베이스, 외부 API 등 운영 비용도 미리 예측해두자. 한 실전 사례에서는 AWS와 DB 비용만 월 수백 달러가 발생했다.
소규모 테스트 먼저: 대규모 작업을 실행하기 전에 작은 범위로 먼저 테스트하여 결과물의 품질과 비용을 확인하는 것이 좋다.
