Claude Code 오케스트레이션
한 줄 정의
Claude Code 오케스트레이션은 Claude Code를 단순 코딩 도구가 아니라 GitHub, Sentry, Slack, Figma, CLI, MCP 서버를 연결하는 업무 조율 도구로 쓰는 관점이다.
핵심 요지
- Claude Code의 가치는 코드 생성만이 아니라 여러 도구 사이의 작업 흐름을 연결할 때 커진다.
- 오케스트레이션에는 반드시 Claude Code 권한 설계가 따라야 한다.
- 반복되는 흐름은 slash command, hook, MCP 같은 작은 자동화로 고정한다.
상세
보리스 자료는 Claude Code를 다양한 workflow를 통제하는 오케스트레이터로 설명한다. 예를 들어 Sentry에서 최근 에러를 확인하고, 관련 로그로 원인을 추정하고, GitHub 이슈를 만들고, 수정 PR을 준비하는 흐름은 여러 도구를 넘나드는 업무다.
이 관점은 Agent Native Infrastructure와 이어진다. 사람이 클릭해서 서비스 연결, 설정, 배포를 처리하는 대신 에이전트가 텍스트 지시와 CLI/API를 통해 실행할 수 있는 환경일수록 오케스트레이션이 쉬워진다. 실무에서는 에이전트 확장 3계층처럼 Skill·MCP·tool의 역할을 분리할수록 오케스트레이션 경계도 선명해진다.
Ralph Loop는 Claude Code 오케스트레이션을 phase queue와 headless 세션 실행으로 확장한 패턴이다. 메인 세션은 전체 구현 context를 모두 품지 않고 phase 상태를 추적하며, 각 phase는 별도 claude -p 실행처럼 신선한 context에서 구현과 검증을 수행한다.
개인 지식 관리에서도 같은 원리가 적용된다. Obsidian vault용 Slash Command 운영처럼 vault 루트에 CLAUDE.md와 .claude/commands/를 두면, /sync, /connect, /inbox 같은 명령어가 반복적인 지식 정리 루프를 오케스트레이션한다.
raw/Claude Code를 6개월 동안 잘못 썼다. 모든 걸 바꾼 14가지 명령어.md는 이 층위의 기본기를 보여 준다. Claude Code 세션 운영 명령어처럼 /init, /compact, !, /review, /doctor를 세션 상태 관리 명령으로 이해하면, Claude Code는 단순 채팅창이 아니라 작업 환경 전체를 조율하는 인터페이스가 된다.
메시징 서버 스트레스 테스트 노하우도 같은 패턴이다. /deploy-target, /deploy-stress, /run-stress, /render-dashboard, /make-report처럼 반복 작업을 명령 단위로 묶고, subagent와 background task로 분리하면 Claude Code가 배포·측정·리포트 흐름을 오케스트레이션하는 역할을 할 수 있다.
5대 보리스 실무 오케스트레이션 핵심 규칙
- 느려도 덜 헤매는 모델이 결과적으로 더 빠르다: 보리스는 세션 운영 시 거의 모든 복잡한 설계/작업에 Opus 모델을 선호한다. 빠르게 틀려 리셋하는 것보다, 느리더라도 실수가 없어 롤백과 설명 시간을 아끼는 모델이 경제성(Total Cost) 측면에서 압도적이기 때문이다.
- 현실적인 단계별 도입 순서: 처음부터 모든 복잡한 자동화를 붙이려 하지 말고 아래 순서로 단계를 밟아야 한다.
- 1단계:
CLAUDE.md생성 ➡️ 2단계: Plan Mode로 계획 수립 ➡️ 3단계: 테스트/린트 자동 실행 ➡️ 4단계: 위험 명령어 권한 제한 ➡️ 5단계: 자주 쓰는 작업 슬래시 커맨드화 ➡️ 6단계: 필요한 경우에만 서브 에이전트/MCP 추가.
- 1단계:
- 서브 에이전트는 최소화하고 역할만 분리: 여러 비즈니스 검토용 에이전트(시장조사, 카피라이팅 등)를 과하게 늘리면 관리 비용만 늘어난다. 완전히 다른 관점의 검토가 요구될 때만 서브 에이전트(코드 아키텍처 검토, 리팩토링 검토, 테스트 검증, 빌드 확인 에이전트 등)를 제한적으로 도입해야 한다.
- 장시간/오래 걸리는 작업의 3대 관리 장치:
- 스스로 검증할 테스트 코드를 구현과 동시에 작성하게 강제한다.
- *스톱훅(Stop Hook)*을 활성화하여 출력이 정지되는 순간 자동으로 빌드/테스트/린팅(
npm run build && npm test && npm run lint)을 실행하게 한다. - UI/브라우저 검증 장치(Playwright, 스크린샷 캡처 등)를 두어 디자인 준수 여부를 에이전트가 검증하게 한다.
- 린터와 포매터는 최종 안전장치: AI가 작성한 코드의 스타일이나 포맷 결함이 CI/CD 파이프라인에서 터져 흐름을 끊는 것을 막기 위해, 매 세션 종료 전 린터와 포매터(
prettier,eslint,black,ruff)를 사용해 마지막 10%의 코드를 정돈하게 만든다.
예시
- 장애 대응: Sentry 에러 확인 → 로그 분석 → GitHub 이슈 생성 → 수정 브랜치 작성 → 테스트 실행
- 콘텐츠 운영: Obsidian 아이디어 DB 조회 → 후보 주제 선정 → 제목/훅/구성안 생성
- 개발 반복:
/test,/review,/deploy-check같은 slash command로 반복 프롬프트를 줄인다.
CC101 보강: Headless 모드와 CI/CD 연동
Headless 모드 (-p 옵션)
터미널에서 Claude Code를 대화형이 아닌 명령형으로 실행한다. 자동화와 파이프라인에 필수적이다.
# 답변만 출력하고 종료
claude -p "이 함수 설명해줘"
# 파일 분석 후 보고서 생성
claude -p "src/ 폴터 코드 품질 분석하고 보고서 작성"
# 예산 한도 설정
claude -p --max-budget-usd 1.00 "질문"GitHub Actions 연동
PR이 올라올 때마다 자동으로 코드 리뷰를 수행한다:
# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Claude Code Review
run: |
claude -p "이 PR의 변경사항을 리뷰해줘. 보안 취약점과 코드 품질 문제를 중점적으로 확인해줘."GitLab CI/CD 연동
GitLab에서도 유사하게 파이프라인에 Claude Code를 통합할 수 있다:
# .gitlab-ci.yml
claude_review:
stage: test
script:
- claude -p "변경된 파일들을 분석하고 잠재적 버그를 찾아줘"
only:
- merge_requests이러한 연동은 Claude Code 권한 설계를 통해 --dangerously-skip-permissions 사용을 제한하고 안전하게 실행해야 한다.
충돌
현재 확인된 충돌 없음.