ClaudeQ - 무인 개발 자동화 시스템
문제: Claude Code는 수동이다
Claude Code는 강력하다. 하지만 한 가지 불편한 점이 있다. 내가 계속 붙어 있어야 한다.
나: 이거 만들어줘
(5분 대기)
Claude Code: 완료
나: 다음 이거 해줘
(3분 대기)
Claude Code: 완료
나: 이번엔 이거...
작업 하나하나마다 지시하고 기다려야 한다. 밤새 돌려놓고 아침에 확인하고 싶은데, 그게 안 된다.
ClaudeQ의 탄생
그래서 만들었다. ClaudeQ.
핵심 아이디어는 간단하다:
- 지시서 폴더에 작업들을 쌓아둔다
- 워커가 주기적으로 폴더를 스캔한다
- 새 지시서가 있으면 Claude Code를 호출해서 처리한다
- 결과를 리포트로 남긴다
이제 여러 작업을 한꺼번에 던져놓고, 나중에 결과만 확인하면 된다.
시스템 구조
claudeq/
├── instructions/ # 지시서 폴더
│ ├── pending/ # 대기 중
│ ├── processing/ # 처리 중
│ └── completed/ # 완료
├── reports/ # 결과 리포트
├── worker.py # 워커 스크립트
└── config.yaml # 설정
지시서는 마크다운 파일이다. pending 폴더에 넣어두면 워커가 가져간다.
지시서 형식
---
id: task-001
project: ~/projects/my-app
priority: normal
timeout: 30m
---
# 사용자 프로필 페이지 추가
## 요구사항
1. /profile 라우트 추가
2. 현재 로그인한 사용자 정보 표시
3. 프로필 이미지 업로드 기능
## 기술 스택
- Next.js 14 App Router
- Tailwind CSS
## 완료 조건
- npm run build 성공
- /profile 접속 시 정상 렌더링
YAML frontmatter에 메타데이터, 본문에 실제 지시 내용을 적는다.
워커 동작 방식
1. 스캔
def scan_pending():
files = os.listdir('instructions/pending')
return sorted(files, key=get_priority)
pending 폴더를 스캔하고, 우선순위 순으로 정렬한다.
2. 처리
def process_instruction(file):
# 파일 이동: pending -> processing
move(file, 'processing')
# Claude Code 호출
result = run_claude_code(
project=instruction.project,
prompt=instruction.content,
timeout=instruction.timeout
)
return result
지시서를 processing으로 옮기고, Claude Code를 호출한다.
3. 검증
def verify_result(instruction, result):
# 빌드 테스트
if instruction.requires_build:
build_result = run_build(instruction.project)
if not build_result.success:
return False
# 커스텀 검증
if instruction.verify_command:
verify_result = run_command(instruction.verify_command)
if not verify_result.success:
return False
return True
완료 조건을 검증한다. 빌드가 성공하는지, 테스트가 통과하는지.
4. 리포트 생성
# Report: task-001
## Status: SUCCESS
## Summary
사용자 프로필 페이지를 추가했습니다.
## Changes
- src/app/profile/page.tsx (새 파일)
- src/components/ProfileImage.tsx (새 파일)
- prisma/schema.prisma (수정)
## Build Result
SUCCESS
## Duration
12분 34초
성공하면 completed로 이동, 실패하면 리포트에 에러 내용을 남긴다.
실패 처리
모든 작업이 성공하진 않는다. 실패했을 때가 중요하다.
실패 리포트
# Report: task-002
## Status: FAILED
## Error
빌드 실패: Type error in src/components/ProfileImage.tsx
## Error Details
Type 'string' is not assignable to type 'File' at line 23, column 15
## Attempted Fixes
1. 타입 수정 시도 (실패)
2. 타입 단언 추가 (실패)
## Recommendation
수동 개입 필요. 파일 업로드 로직 재검토 권장.
실패 원인과 시도한 수정, 권장 조치를 남긴다.
재시도
# 지시서에 재시도 설정
retry:
max_attempts: 3
backoff: exponential
설정에 따라 자동 재시도도 가능하다. 간헐적인 실패는 재시도로 해결되기도 한다.
실제 사용 예
아침에 지시
출근하기 전, 오늘 할 일을 지시서로 작성한다.
# 지시서 3개 작성
vim instructions/pending/001-fix-login-bug.md
vim instructions/pending/002-add-profile-page.md
vim instructions/pending/003-update-api-docs.md
# 워커 시작
python worker.py --daemon
저녁에 확인
퇴근 후에 결과를 확인한다.
ls reports/
# 001-fix-login-bug.md - SUCCESS
# 002-add-profile-page.md - SUCCESS
# 003-update-api-docs.md - FAILED
3개 중 2개가 성공했다. 실패한 건 리포트를 보고 수동으로 처리한다.
장점
시간 절약
대기 시간이 없다. 지시만 해놓으면 알아서 처리된다.
병렬 처리
워커를 여러 개 돌리면 동시에 여러 작업을 처리할 수 있다.
기록 자동화
모든 작업이 리포트로 남는다. 나중에 뭘 했는지 추적하기 좋다.
재현 가능
지시서가 남아있으니, 같은 작업을 다시 할 때 참고할 수 있다.
한계
복잡한 작업은 어렵다
여러 단계로 나뉘는 복잡한 작업은 중간에 실패하기 쉽다. 작은 단위로 쪼개는 게 좋다.
컨텍스트 공유 안 됨
각 작업이 독립적이다. 앞 작업의 결과를 다음 작업이 참고하려면 명시적으로 적어야 한다.
디버깅이 어렵다
실시간으로 보면서 "아 이거 아닌데" 할 수가 없다. 결과만 보고 판단해야 한다.
비용
Claude API를 많이 호출하면 비용이 나온다. 불필요한 작업은 피해야 한다.
개선 계획
의존성 관리
작업 간 의존성을 정의해서, 순서대로 실행하게 하고 싶다.
id: task-003
depends_on: [task-001, task-002]
웹 대시보드
진행 상황을 웹에서 모니터링하고 싶다.
알림
실패하면 슬랙이나 이메일로 알림을 받고 싶다.
결론
ClaudeQ는 "출근 전에 지시, 퇴근 후에 확인"을 가능하게 해준다.
물론 모든 작업이 자동화되는 건 아니다. 복잡한 건 여전히 수동으로 해야 한다. 하지만 반복적이고 단순한 작업들, 예를 들어 새 페이지 추가, API 엔드포인트 작성, 문서 업데이트 같은 건 충분히 자동화할 수 있다.
AI 개발의 다음 단계는 자동화다. Claude Code가 "말 잘 듣는 주니어 개발자"라면, ClaudeQ는 "24시간 일하는 개발팀"에 가깝다. 물론 아직 팀장(나)의 관리가 필요하지만.
결국 개발자의 역할은 점점 "직접 코드를 짜는 사람"에서 "무엇을 만들지 결정하고 검증하는 사람"으로 바뀌고 있다. 그 변화에 적응하는 게 중요하다.