CLAUDE CODE ARCHITECTURE · 비개발자용 정리

천재 AI에게
손과 발을 달면
벌어지는 일

요즘 화제인 Claude Code는 어떻게 "말만 하는 AI"를 실제로 일하는 일꾼으로 바꿔놓을까요?
그 속을 8개 부서로 분해해서, 코드를 몰라도 이해되게 풀어봤습니다.

원자료: AWS Korea 최우형(Solutions Architect) 발표자료 · Anthropic 공식 문서 기반 · 정리: AICONLAB

The Big Idea

"에이전트 하네스"
= 천재에게 채운 마구

하네스(harness) → 말에 씌우는 마구(馬具). AI를 실제로 "일하게 장착"시키는 장치라는 뜻이에요.

원래 AI(언어 모델)는 머리는 천재인데 방에 갇혀 말만 할 수 있는 사람과 같아요. "이렇게 하세요"라고 설명은 해주지만, 직접 하진 못하죠.

그냥 AI

  • 질문하면 답변(글)만 줌
  • 파일을 직접 못 만짐
  • 대화창 닫으면 기억 증발
  • "방법"만 알려줌

Claude Code (하네스)

  • 직접 파일을 만들고 고침
  • 명령 실행 · 결과 확인까지
  • 메모장(기억)으로 이어감
  • "결과물"을 내놓음

한 줄 요약

Claude Code = 천재 AI에게 손발(도구) + 기억(메모리) + 업무 매뉴얼(규칙)을 쥐여줘서, 실제로 일을 끝까지 하게 만든 도구.

The Heartbeat

심장은 단 하나,
"수집 → 행동 → 검증"

복잡해 보여도, 모든 작업은 결국 이 3박자를 계속 반복하는 거예요. 사람이 일하는 방식이랑 똑같아요.

① 수집 상황 파악 ② 행동 편집·실행 ③ 검증 결과 확인 → → 미흡하면 다시 ①로 (반복)
상황을 모으고 → 직접 손대고 → 잘 됐는지 확인. 안 됐으면 다시 처음으로.

작업 성격마다 비중이 달라요. 단순 질문은 ①수집만으로 끝, 버그 고치기는 3박자를 여러 번, 다듬기는 ③검증에 더 집중. (멈추고 싶으면 Esc)

The Whole Map

전체 지도 — 8개 부서가
심장을 둘러싼다

가운데 심장(3단계 루프)이 있고, 그 둘레를 8개 "부서"가 돕는 구조예요. 회사 조직도처럼 보면 돼요.

심장 (Agent Loop) 수집-행동-검증 ① 입력 (Input) 정문 · 출입증 · 세션 ② 지식 (Knowledge) 매뉴얼 · 기억 · 레시피 ⑤ 관측 (Hooks) 문지기 · CCTV ④ 위임 (Sub-agent) 부하 직원에게 분담 ③ 실행 (Tools) 공구함 ⑥ 연결 (MCP) 외부 거래처망 ⑦ 산출 (Output) 검증된 완성품
한가운데 심장 + 8개 부서. 다 외울 필요 없어요 — "심장이 일하고 부서들이 돕는다"만 기억하면 충분.
The Four Inputs · 가장 중요

AI를 움직이는
4가지 "입력 파일"

이 자료의 핵심이에요. AI의 행동은 네 가지로 제어되는데, "언제 읽히는지"가 서로 달라요.

항상 읽음

📋 CLAUDE.md

영구 규칙·구조를 적은 업무 매뉴얼. 매번 자동으로 읽혀요.

예: 코딩 규칙 · 프로젝트 구조
필요할 때

📖 SKILL.md

반복 작업의 레시피북. 그 작업이 필요할 때만 펼쳐 읽어요.

예: PR 리뷰 · 문서 작성 절차
지금

💬 Prompt

지금 사람이 치는 일회성 지시. 눈앞의 일 하나를 처리.

예: "이 함수 고쳐줘"
자동

🚪 Hook

특정 순간에 자동 발동하는 문지기. 검사·차단·기록을 강제.

예: 저장 시 자동 포맷팅

즉 — 항상 챙길 건 매뉴얼(CLAUDE.md)에, 반복 절차는 레시피북(SKILL)에, 일회성은 그냥 말(Prompt)로, 무조건 강제할 건 문지기(Hook)로. 용도가 딱딱 나뉘어요.

Why It's Light

레시피북이 수백 권이어도
안 무거운 비결

"기능을 많이 깔면 느려지지 않나요?" — 안 그래요. 3단계로 나눠서 필요한 만큼만 꺼내 읽기 때문이에요. (어려운 말로 '점진적 공개')

1

제목만 훑기

평소엔 레시피북의 제목과 한 줄 설명만 봐요. 아주 가벼움(30~50토큰).

2

필요하면 본문 펼치기

지금 할 일과 맞는 레시피만 본문 전체를 읽어요.

3

그래도 부족하면 부록

본문이 "이 스크립트 가져와" 할 때만 딸린 자료를 꺼냄.

그래서 기능(스킬)을 수백 개 붙여도
평소 머리(컨텍스트)가 안 터집니다.
— 도서관에 책이 만 권 있어도, 지금 펼친 한 권만 무거운 것과 같아요
The Building Blocks

확장 부품 4종 —
언제 뭘 쓸까?

프리미티브(primitive) → "기본 부품". 레고 기본 블록처럼 조합해서 능력을 늘리는 단위예요.

Claude Code를 키우는 부품은 딱 4가지. 고르는 기준도 단순해요 — 지식이냐, 행동이냐.

지식? vs 행동? 지식이면 행동이면 Skills 조건부 지식 · 레시피북 Subagents 격리된 위임 · 부하직원 MCP 외부 연결 · 거래처망 Hooks 자동 강제 · 문지기
지식이면 → 항상은 매뉴얼·조건부는 Skills / 행동이면 → 내부 위임은 Subagent·외부는 MCP·무조건 강제는 Hook

설계 황금률: "가장 단순한 것부터 써라." 컨텍스트는 가볍게, 경계는 명확하게, 강제는 확실하게, 그리고 관찰하며 개선.

The Rest, Quickly

나머지 부서들,
한 장으로 빠르게

① 입력 — "어디서 일하든 똑같다"

터미널·VS Code·웹·슬랙 등 들어오는 창구는 8가지+. 그래도 일하는 방식(루프)은 어디서나 동일. 작업 내역은 내 컴퓨터에 영구 저장돼요.

② 지식 — "머리가 차면 알아서 정리"

기억 공간이 꽉 차면 오래된 내용부터 자동 압축·요약. 단, 영원히 지켜야 할 규칙은 대화가 아니라 매뉴얼(CLAUDE.md)에 둬야 안 사라져요.

④ 위임 — "팀원에게 나눠주고, 요약만 받기"

큰일은 부하 직원(서브에이전트)에게 분담. 각자 따로 일한 뒤 결과 요약만 가져와서, 본인 머리는 안 어지럽혀요.

⑤⑥ 관측·연결 — "감시하고, 바깥과 잇는다"

Hooks(문지기)가 매 순간 검사·차단·기록하고, MCP가 깃허브·DB 같은 외부 도구 3000여 종과 표준 방식으로 연결돼요.

Common Pitfalls

강력한 만큼
흔한 함정도 있다

4가지 부품은 잘못 쓰면 오히려 독이 돼요. 부품마다 딱 하나씩만 조심하면 안정적으로 돌아갑니다.

Skills 함정

📖 너무 욱여넣기

레시피북에 모든 걸 담으면 머리(컨텍스트)가 무거워져요. 작게, 꼭 필요한 것만.

Subagents 함정

👥 과한 위임

아무 일이나 부하에게 넘기면 결과가 새요. 명확한 지시, 최소 결과만 받기.

MCP 함정

🔌 외부 불안정

바깥 도구는 끊기거나 느릴 수 있어요. 타임아웃·재시도를 꼭 챙기기.

Hooks 함정

🚪 위험한 자동화

문지기가 잘못 짜이면 작업을 막아버려요. 안전 기본값 + 테스트 먼저.

설계 황금률 한 줄

가장 단순한 것부터 쓰기. 컨텍스트는 가볍게, 경계는 명확하게, 강제는 확실하게 — 그리고 관찰하며 조금씩 개선.

The Takeaway

결국, 한 문장

복잡한 8레이어를 다 외울 필요 없어요.

"천재 AI에게 손발·기억·규칙을 달면,
수집-행동-검증을 스스로 반복하는
일꾼이 된다."

나머지 부품(Skills·Subagents·MCP·Hooks)은 그 일꾼을 더 똑똑하고 안전하게 만드는 액세서리일 뿐.

원자료: AWS Korea 최우형(Choi, WooHyung), Prin. Solutions Architect — "Claude Code Architecture" (45p) · 1차 출처: Anthropic Claude Docs · agentskills.io · modelcontextprotocol.io
정리: AICONLAB (AI Context Lab) · 2026.06.09 · 비개발자 친화 재구성