인터넷의 Claude Code 글은 대부분 「CLI 설치, diff 스크린샷」에서 멈춥니다. 실제 팀에 넣어보면 금방 드러납니다: 최상급 AI 코딩 도구의 핵심 아키텍처는 터미널 안 Agent 프로세스 하나가 아닙니다——Cloud Mac AI Stack 안에서 Diff, Fact, Context, Workflow가 어떻게 역할을 나누고 폐루프를 닫는지가 전부입니다.
본문은 L6-Q02 아키텍처 맵(L6-Q02)입니다. Claude Code를 진입점으로 Stack 전체 아키텍처, 5모듈 연결 순서, 시스템 폐루프를 그립니다. 운용 핸드북은 L6-Q01 완전 핸드북, 권한 문턱은 L3 결정 입문——본문은 맵만 다룹니다.
한 줄 아키텍처
Claude Code가 Diff를, GitHub Runner가 Fact를 만듭니다. MCP는 Context를 확장하고, Ollama는 선택 Inference, OpenHands는 Workflow를 조율합니다——모두 Cloud Mac(L0) 위에서 동작합니다.
Claude Code 본체: 10% 분해(나머지 90%는 Stack)
Claude Code 자체를 먼저 정의한 뒤, 어느 계층에 앉는지 봅니다. IDE 플러그인이 아니라 터미널 코딩 Agent입니다:
단일 Agent loop(여러 번 반복 가능) CLAUDE.md + 저장소 Context 읽기 │ ▼ 계획(어떤 파일, 어떤 명령) │ ▼ 실행(Write / Edit / Bash / 선택 MCP Tool) │ ▼ 검증(지정한 test / lint) │ └──► Diff 산출(git으로 감사 가능한 변경)
- 경계 —
CLAUDE.md와 권한 정책이 「무엇을 건드릴 수 있는지」를 정합니다; 핸드북 · 프로젝트 경계 참고 - 확장 감각 — MCP가 GitHub Issue, CodeGraph, API를 Context로 연결; MCP 트리플 연결 허브 참고
- Cursor와의 역할 분담 — 에디터 내 자동완성 vs 다중 파일 + shell Agent; vs Cursor 참고
여기까지가 L3뿐입니다. 조직이 실제로 신뢰하는 「핵심 아키텍처」는 아래 Stack 전체 맵입니다.
Cloud Mac AI Stack 전체 맵(역할 계층)
본 사이트의 통합 L0–L5 모델입니다——어떤 전문 글을 읽든 여기로 돌아와 대조하세요. 중요: 이것은 역할 계층이지, 런타임 호출 순서가 아닙니다.
Stack ≠ 호출 순서
Claude Code는 Ollama에 의존하지 않습니다. 구조도에서 MCP가 L3 위에 있는 것은 Context가 코딩을 지원한다는 뜻이지, MCP가 CLI보다 먼저 떠야 한다는 뜻이 아닙니다. 배포 순서는 § 연결 순서를 보세요.
산출물: Inference · Diff · Fact · Context · Workflow
┌──────────────┐
│ OpenHands │ L5 · Workflow(전체 요구가 끝났나?)
└──────┬───────┘
│
┌──────▼───────┐
│ MCP │ L4 · Context(Agent가 무엇을 볼 수 있나?)
└──────┬───────┘
│
┌──────▼───────┐
│ Claude Code │ L3 · Diff(이번 변경은 무엇?) ← 본문 진입점
└──────┬───────┘
│
┌──────▼───────┐
│ Ollama │ L2 · Inference(선택 · 로컬 프라이빗 연산)
└──────┬───────┘
│
┌──────▼───────┐
│ GitHub Runner│ L1 · Fact(조직이 믿을 수 있나?)
└──────┬───────┘
│
┌──────▼───────┐
│ Cloud Mac │ L0 · 인프라(24/7 macOS 노드)
└──────────────┘
L0가 연산을, L1이 Fact를 받치고, 그 위에 Diff·Context·Workflow가 올라갑니다. Claude Code가 아무리 강해도 L1이 없으면 Diff는 개발 머신 위 자기만족에 그칩니다.
5모듈(+ 기반) 역할과 산출물
| 계층 | 모듈 | 산출물 | 답하는 질문 | 심화 읽기 |
|---|---|---|---|---|
| L0 | Cloud Mac | 기반 | macOS / Apple Silicon은 어디서? | 구매 vs 대여 |
| L1 | GitHub Runner | Fact | push 이후 누가 xcodebuild / 테스트를 돌리나? | 실행 엔진 |
| L2 | Ollama | Inference | 로컬 embedding / 소형 모델이 필요한가? | 프라이빗 추론 계층 |
| L3 | Claude Code | Diff | 누가 코드를 고치고 shell을 돌리며 테스트 루프를 도나? | 완전 핸드북 |
| L4 | MCP | Context | Issue / 그래프 / API는 Agent에 어떻게 들어가나? | 트리플 연결 허브 |
| L5 | OpenHands | Workflow | 전체 요구를 무인으로 끝낼 수 있나? | Agent 플랫폼 |
Workflow(L5)와 Fact(L1)의 관계: OpenHands는 작업 주기 동안 Context를 반복 소비하고, Diff를 산출하고, Fact로 검증합니다——「Workflow가 끝난 뒤에야 CI」가 아닙니다. OpenHands · 산출물 관계 참고.
권장 연결 순서: Fact를 먼저, Diff는 그다음
유행하는 순서는 보통 Claude Code → MCP → 마지막에 CI입니다. 우리가 권장하는 배포 순서는 아래와 같습니다(구조도 계층 순서와 다름):
① Cloud Mac(L0 기반)
│ 상시 macOS · SSH · egress IP
▼
② GitHub Runner(L1 · Fact)
│ push → 반복 가능한 그린/레드 · workspace 격리
▼
③ Ollama(L2 · Inference, 선택)
│ 로컬 embedding / 소형 모델 · L1/L3 메모리 배분 주의
▼
④ Claude Code(L3 · Diff)
│ CLAUDE.md · 권한 · 첫날 시범 운용
▼
⑤ MCP(L4 · Context)
│ GitHub / CodeGraph / Fetch · 최소 권한
▼
⑥ OpenHands(L5 · Workflow)
│ 다단계 issue · agent loop · L3 위에 겹침
▼
⑦ 시스템 폐루프
위임 → Diff → PR → Runner Fact → review → merge
- ① L0 — 24/7 macOS 노드가 없으면 Runner와 Agent가 노트북 메모리를 다툽니다; 구매 vs 대여 참고
- ② L1 — 먼저 조직이 신뢰할 Fact를 확보; 격리는 1 job 1 workspace 참고
- ③ L2 — 선택; Claude Code·Runner와 동일 호스트면 병행 스케줄링 참고
- ④–⑥ — Fact가 안정된 뒤 AI 계층을 겹침; 핸드북은 L6-Q01
- ⑦ 폐루프 — 다음 절 참고
시스템 폐루프: Claude Code 위임에서 PR 그린까지
「핵심 아키텍처」의 마지막 조각은 데이터가 어떻게 되돌아오는지입니다——Agent는 고립된 터미널에 살 수 없습니다:
사람 개입 · L3 개발자 ──위임──► Claude Code(+ MCP Context) │ │ Diff(commit) ▼ feature 브랜치 / PR │ 기계 검수 · L1 ▼ GitHub Runner(Fact) xcodebuild / test / lint │ ├── 레드 ──► Agent에 피드백( Diff ↔ Fact ) │ └── 그린 ──► 수동 review ──► merge 선택 · L5 OpenHands가 야간에 issue 큐 정리 ──► 동일 PR + Runner 폐루프
폐루프가 성립하는 세 가지 필수 조건: Runner와 Agent 환경 격리, PR은 반드시 CI 통과, 프로덕션 secrets는 Agent shell에 넣지 않음. 프로덕션 체크리스트는 L6-Q01 · 프로덕션급 참고.
사이트 전체 내부 링크 허브: 계층별 이동
본문은 Stack 시리즈의 맵 페이지입니다. 현재 막힌 지점에 맞춰 진입하세요:
| 해결하려는 것 | 읽을 글 |
|---|---|
| Cloud Mac 필요 여부 / 대여 방법 | L0 구매 vs 대여 · M4/M5 선택 |
| CI 대기열 / Runner 가치 | L1 대기열과 TCO · L1 실행 엔진 |
| Swap / Ollama와 Agent 동일 호스트 | L2 병행 스케줄링 |
| Claude Code 설치 / 프로덕션 워크플로 | L6-Q01 핸드북 · L3 권한 결정 |
| MCP / CodeGraph 연결 | L4 허브 · MCP 설치 튜토리얼 |
| 무인 다단계 작업 | L5 OpenHands |
자주 묻는 질문
Claude Code의 핵심 아키텍처는? 터미널 Agent loop가 Diff를 산출; 프로덕션급에는 CLAUDE.md, MCP Context, 독립 Runner Fact가 추가됩니다.
Claude Code 전에 Ollama를 먼저 설치해야 하나요? 아닙니다. L2는 선택; 구조도는 호출 순서가 아니라 역할 계층입니다.
본문과 L6-Q01 핸드북의 차이는? Q01은 운용 메인 라인(설치→CI); Q02는 Stack 전체 맵(본문)입니다.
OpenHands가 Claude Code를 대체할 수 있나요? 아닙니다. L5는 Workflow를 조율하고, L3는 Diff를 함께 만듭니다——겹쳐 쓰세요.
ZavCloud
맵대로 Stack을 쌓으세요——Cloud Mac 한 대부터
L0 기반 → L1 Runner → L3 Claude Code. 네이티브 macOS에서 연결 순서대로 전체 폐루프를 시험할 수 있습니다.
Cloud Mac 요금제 보기