다섯 층의 엔지니어링 — 메시지에서 조정까지

10주차에서 우리는 임베딩·벡터 DB·그래프 DB를 개념으로 배웠습니다. 뜻을 좌표로 바꾸고, 그 좌표를 어디에 저장하며, "비슷한가"와 "이어지는가"가 어떻게 다른 질문인지를 봤습니다. 이번 주는 그 개념들이 프레임워크로 내려앉는 주입니다. 벡터 DB 위에는 랭체인(LangChain) 이 올라가고, 그래프 DB 위에는 랭그래프(LangGraph) 가 올라갑니다. 개념이 라이브러리 이름을 얻습니다.

그리고 3주차부터 이 교재에 계속 나온 단어, 하네스(Harness) 가 드디어 정확한 자리 번호를 받습니다. 하네스는 전부가 아니라 다섯 층 중 세 번째 층이었습니다. 그 위아래에 무엇이 있는지가 이번 주에 밝혀집니다.

---

이 장을 다 읽으면

1. "모델이란 무엇인가"에 데이터 + 알고리즘이라고 답하고, 그 둘이 각각 무엇을 정하는지 말할 수 있다.
2. 에이전트를 만드는 다섯 층의 엔지니어링을 순서대로 대고, 각 층이 무엇을 다루는지 한 단어로 말할 수 있다.
3. 왜 그 순서여야 하는지를 판별 축이 하나씩 켜지는 방식으로 설명할 수 있다.
4. 3주차부터 나온 하네스가 다섯 층 중 어디에 놓이는지, 그 위아래와 무엇이 다른지 말할 수 있다.
5. MCP = Model + Context + Protocol 로 풀어 쓰고, 그것이 CLI·API와 무엇으로 갈리는지 판별할 수 있다.
6. 랭체인에 랭그래프를 더하는 네 가지 이유를 대고, 어떤 요청이 체인으로 가고 어떤 요청이 그래프로 가야 하는지 고를 수 있다.
7. langchain ↔ 벡터 DB / langgraph ↔ 그래프 DB 의 대응이 왜 우연이 아닌지 설명할 수 있다.
8. EC2 위에 도커 → 깃 → nginx 순서로 서버를 세우고, 그 순서가 왜 그 순서인지 근거를 댈 수 있다.
9. 원격 서버 안에서 에이전트를 돌릴 때 생기는 문제(세션 끊김·이미지 전달·MCP 미설치)를 각각 어떻게 해결하는지 안다.

---

0. 이 장의 판별 축

앞에서 배운 대로, 새 용어를 만나면 비유를 찾기 전에 아래 축 중 어디에 꽂히는지부터 정하세요.

축 1·2·3이 이 장의 중심입니다. 이 세 축이 순서대로 켜지는 과정이 곧 다섯 층의 엔지니어링입니다.

• 축 1을 왼쪽에 두면 프롬프트 엔지니어링, 오른쪽으로 넘기면 컨텍스트 엔지니어링입니다.
• 축 2를 오른쪽으로 넘기면 루프 엔지니어링입니다.
• 축 3을 오른쪽으로 넘기면 그래프 엔지니어링입니다.
• 그 사이에서 도구와 권한과 안전장치를 만드는 일이 하네스 엔지니어링입니다.

앞 장에서 이어집니다 — 축 4는 10주차의 축 4와 같은 축입니다. 그때는 "어떤 저장소를 고를 것인가"라는 DB 선택 이야기였고, 이번에는 "그 저장소 위에 어떤 프레임워크를 얹을 것인가"라는 코드 이야기로 한 층 내려옵니다. 축 2는 10주차 축 3(무상태 ↔ 상태 유지)의 시간축 버전입니다. 상태를 들고 있어야 반복이 의미를 가집니다.

---

1. 모델 = 데이터 + 알고리즘 ⭐

1.1 정의

이번 주에 처음 던져진 질문은 아주 짧습니다. "모델이 무엇인가?"

답도 짧습니다.

모델(Model) = 데이터(Data) + 알고리즘(Algorithm)

유(類)와 종차(種差) 형식으로 다시 쓰면 이렇습니다.

• 모델(Model) — [입력을 받아 출력을 내는 함수]인데, [그 함수의 계수를 사람이 쓴 것이 아니라 데이터에서 알고리즘이 찾아냈다]는 점에서 일반 프로그램과 구별된다.
• 데이터(Data) — [모델의 재료]인데, [무엇을 배울 것인가를 정한다]는 점에서 알고리즘과 구별된다.
• 알고리즘(Algorithm) — [모델의 절차]인데, [어떻게 배울 것인가를 정한다]는 점에서 데이터와 구별된다.

3주차에서 배운 정의가 여기서 회수됩니다. 알고리즘 = 문제 해결을 위한 유한하고 명확한 단계별 지침. 그 지침이 데이터를 통과하면 모델이 나옵니다.

1.2 뺄셈으로 확인하기

3주차에서 객체·개체·함수를 뺄셈으로 외웠던 방식이 여기에도 그대로 적용됩니다.

모델        = 데이터 + 알고리즘
데이터만    = 그냥 파일 (아무것도 예측하지 못함)
알고리즘만  = 빈 뼈대 (학습되지 않은 초기 가중치)

• 데이터가 없으면 알고리즘은 무엇을 배울지를 모릅니다.
• 알고리즘이 없으면 데이터는 어떻게 정리될지를 모릅니다.

⭐ 그래서 "모델 성능이 나쁘다"는 진단은 항상 두 갈래로 쪼개야 합니다. 데이터 문제인가, 알고리즘 문제인가. 이 둘을 안 쪼개면 GPU만 계속 삽니다.

1.3 "모델을 바꾼다"는 말의 두 가지 뜻

실무 순서는 프롬프트 → RAG → 파인튜닝입니다. 대부분 2단계에서 끝납니다. "우리 회사 규정을 알게 하고 싶다"는 RAG이고, "무조건 이 JSON 형식으로만 답해라"는 프롬프트입니다. 프롬프트로 안 될 때에야 파인튜닝을 봅니다.

앞에서 배운 대로, RTX 3050(VRAM 6~8GB) 환경에서 Qwen2.5-1.5B-Instruct 를 고른 이유가 바로 알고리즘 축의 선택이었습니다. 시맨틱 인텐트 분류(라우팅)에서는 3B와 정확도 차이가 거의 없으면서 VRAM은 1.8GB만 쓰기 때문입니다. 그리고 어댑터 패턴을 썼기 때문에 나중에 베이스 모델 이름만 3B로 교체하면 됩니다.

1.4 모델은 에이전트가 아니다

10주차에서 못 박은 문장을 다시 꺼냅니다.

딥러닝이 지능을 처리하는 '뇌'라면, 에이전트는 그 뇌를 탑재하고 도구를 사용하며 스스로 행동하는 '몸'입니다.

여기에 이번 주의 공식을 겹칩니다.

에이전트(Agent) = 모델(Model) + 하네스(Harness)
모델(Model)     = 데이터(Data)  + 알고리즘(Algorithm)

두 식을 합치면 이렇게 됩니다.

에이전트 = (데이터 + 알고리즘) + 하네스

즉 에이전트를 잘 만든다는 것은 세 곳 중 어디를 손볼지 고르는 일입니다. 그리고 실무에서 손보게 되는 곳은 대부분 세 번째, 하네스입니다.

"좋은 하네스가 좋은 모델을 이긴다." 모델의 지능만으로는 일을 끝낼 수 없습니다. 도구·상태·권한·평가가 실행 품질을 결정합니다.

1.5 흔한 오해 — 모델 크기가 성능이다

⚠️ 파라미터 수는 알고리즘 축의 한 숫자일 뿐입니다. 7B 모델이 사내 규정을 모르면 규정 질문에서는 규정을 RAG로 받은 1.5B보다 못하고(데이터 축), 아무리 큰 모델도 파일을 못 읽고 명령을 못 돌리면 일을 끝내지 못합니다(하네스 축).

---

2. 에이전트의 5단계 엔지니어링 ⭐⭐

이 장의 중심입니다. 그리고 이 교재 전체에서 흩어져 있던 단어들이 하나의 사다리로 정렬되는 자리입니다.

2.0 한 장으로 보기

각 단계의 오른쪽 단어(메시지 → 메모리 → 기계 → 시스템 → 조정)를 외우면 사다리 전체가 복원됩니다.

⭐ 다섯 단계는 "더 좋은 방법"의 목록이 아니라 "쌓이는 층"입니다. 5단계를 한다고 1단계를 안 하는 게 아닙니다. 그래프 안의 각 노드는 여전히 프롬프트를 씁니다. 아래 층이 부실하면 위층은 그 부실을 반복해서 증폭합니다.

2.1 1단계 · 프롬프트 엔지니어링 → 메시지

정의 — [에이전트 설계 단계]인데, [대화창에 넣는 한 번의 글을 다듬는다]는 점에서 나머지 네 단계와 구별된다.

• 다루는 것: 메시지(Message). 대화창에 넣어서 쓰는 글.
• 수명: 그 대화 한 번. 창을 닫으면 사라집니다.
• 저장 위치: 없음(휘발). 굳이 말하면 사람의 머릿속과 클립보드.

이 단계에서 하는 일은 지시를 명확하게 만드는 일입니다. 역할을 주고, 출력 형식을 정하고, 하지 말아야 할 것을 적습니다.

requirements.txt 에 langchain 을 추가해줘. 파이썬·토치 버전을 먼저 확인하고,
충돌이 나면 어느 패키지 때문인지 알려줘. 다른 파일은 건드리지 마.

한계가 분명합니다. 이 글은 다음 대화에 남지 않습니다. 같은 지시를 내일 또 써야 하고, 팀원은 그 글을 못 봅니다. 그리고 사람이 매번 붙어 있어야 합니다.

이 한계를 넘는 방법은 하나뿐입니다. 글을 파일로 옮기는 것. 그것이 2단계입니다.

2.2 2단계 · 컨텍스트 엔지니어링 → 메모리

정의 — [에이전트 설계 단계]인데, [지시를 대화창이 아니라 파일에 적어 반복해서 읽히게 한다]는 점에서 프롬프트 엔지니어링과 구별된다.

• 다루는 것: 메모리(Memory). md 파일로 써서 작성합니다.
• 수명: 파일이 있는 한 계속. 대화가 끝나도 남습니다.
• 저장 위치: 저장소(레포지토리) 안. 그래서 버전 관리가 되고 팀과 공유됩니다.

여기서 축 1이 왼쪽에서 오른쪽으로 넘어갑니다.

3주차의 디스크 ↔ 메모리 축이 여기서 그대로 반복됩니다. 프롬프트는 RAM이고 컨텍스트 문서는 디스크입니다. 같은 구조가 층만 바꿔 되풀이되는 것, 앞에서 배운 프랙탈입니다. 이번 주에 실제로 쌓은 파일들이 전부 이 단계의 산출물입니다.

_docs/003-langchain-harness.md          ← 랭체인 작업 시 지킬 규칙
_docs/004-langgraph-harness.md          ← 랭그래프로 넘길 조건과 규칙
_docs/005-langchain-morningstar-strategy.md
_docs/006-langchain-ncl-strategy.md
_docs/008-neo4j-strategy.md
.claude/rules/typescript.md             ← 파일 패턴별 규칙
.claude/projects/.../memory/MEMORY.md   ← 자동 메모리
CLAUDE.md                               ← 최상위 규칙

⚠️ AI 지침 파일이 .md 인 이유는 취향이 아닙니다. 마크다운은 3주차에서 배운 대로 사람을 위한 간결한 표기이면서 동시에 헤딩으로 구조가 드러나는 형식입니다. 사람이 읽고 고칠 수 있어야 규칙이 유지되고, 구조가 있어야 모델이 필요한 절만 골라 읽습니다.

💡 토큰 절약과 직결됩니다. 큰 작업을 한 번에 몰아서 시키기보다 _docs 나 CLAUDE.md 에 맥락을 적어 두고 참조시키는 편이 훨씬 쌉니다. 매번 같은 배경 설명을 대화창에 다시 붙여넣는 것이 가장 비싼 방식입니다.

2.3 3단계 · 하네스 엔지니어링 → 기계

정의 — [에이전트 설계 단계]인데, [모델이 실제로 행동할 수 있게 하는 실행 구조 자체를 만든다]는 점에서 글을 다듬는 앞의 두 단계와 구별된다.

• 다루는 것: 기계(Machine). 모델을 감싸고 실제 행동을 가능하게 하는 실행 구조.
• 구성: 프롬프트 + 도구 + 상태 + 권한 + 평가 + 복구

앞의 두 단계는 글을 다뤘습니다. 이 단계는 글이 아닌 것을 다룹니다. 도구를 붙이고, 권한을 자르고, 결과를 검사하는 장치를 답니다.

왜 "기계"인가

하네스(Harness)라는 단어의 원래 뜻은 마구(馬具) 이자 전선 다발을 묶어 규격화한 배선 묶음입니다. 4주차에서 배운 대로 하네스 엔지니어링은 데이터 통로를 규격화하는 일이었습니다. 말은 여전히 말이지만, 마구를 채우면 마차를 끌 수 있게 됩니다. 모델을 바꾸지 않고도 할 수 있는 일이 늘어납니다.

카파시의 원칙이 이 단계의 한 줄 요약입니다.

"LLM을 절대 날것(Raw)으로 세상과 직접 부딪히게 두지 말고, 외부에서 통제하는 규칙과 환경틀을 짜라."

좋은 하네스가 다루는 7가지

1. 도구(Tools) — 무엇을 호출할 수 있는가
2. 컨텍스트(Context) — 무엇을 읽을 수 있는가
3. 권한(Permissions) — 무엇까지 허용되는가
4. 샌드박스(Sandbox) — 실패해도 안전한 공간이 있는가
5. 관측성(Observability) — 무슨 일이 있었는지 볼 수 있는가
6. 복구(Recovery) — 실패했을 때 되돌릴 수 있는가
7. 외부 루프(Outer Loop) — 완료를 누가 판정하는가

⚠️ 한 요소의 빈틈이 전체 실패가 됩니다. 여섯 개가 완벽하고 권한 하나가 열려 있으면, 그 하나로 사고가 납니다.

가이드와 센서 — 하네스의 두 축

9주차에서 이미 만난 구분입니다.

작동 흐름: 사람의 조타 → 가이드 → 에이전트 생성 → 센서 피드백 → 에이전트 수정(루프)

가이드와 센서, 둘 다 있어야 제대로 된 하네스입니다. 가이드만 있으면 잘못된 길로 갔을 때 바로잡을 방법이 없고, 센서만 있으면 시행착오가 너무 많아 비효율입니다.

⭐ 여기서 2단계와 3단계의 경계가 보입니다. 가이드(md 문서)는 컨텍스트 엔지니어링의 산출물이고, 센서(테스트·린터·로그)는 하네스 엔지니어링의 산출물입니다. 문서만 잔뜩 쓰고 검증 장치가 없으면 아직 2단계에 머물러 있는 것입니다.

실수를 영구적으로 불가능하게 만들기

하네스 엔지니어링의 가장 중요한 실천 지침은 이것입니다.

★ 에이전트가 실수하면, 그 실수가 영구적으로 불가능하도록 환경을 고쳐라.

두 가지 방법이 있습니다.

• ① 지침 파일 개선 — 규칙 파일의 각 줄이 실제 나쁜 행동에서 나온 것이어야 합니다.
• ② 실제 도구 제작 — 스크린샷 자동화, 필터링된 테스트 스크립트처럼 손으로 만드는 도구.

이번 주 자료 중 fastapi/_docs/docker-rules.md 에 "동일한 DB·백엔드 생성 요청이 와도 기존 것이 있으면 체크해 승인받으라"는 룰을 넣은 것이 정확히 ①입니다. 컨테이너를 중복 생성한 사고가 먼저 있었고, 그 사고가 다시 안 나도록 환경을 고친 것입니다.

2.4 4단계 · 루프 엔지니어링 → 시스템

정의 — [에이전트 설계 단계]인데, [한 번의 실행이 아니라 같은 절차가 선형으로 지속 반복되도록 만든다]는 점에서 하네스 엔지니어링과 구별된다.

• 다루는 것: 시스템(System). 스킬(Skills) 등, 선형으로 지속 반복하는 것.
• 여기서 축 2(한 번 ↔ 반복) 가 오른쪽으로 넘어갑니다.

에이전트의 본체는 루프다

   [추론] ──▶ [도구] ──▶ [관찰] ──▶ [반복]
      ▲                              │
      └──────────────────────────────┘

10주차의 에이전트 루프(환경 인지 → 계획 → 도구 활용 → 실행 → 결과 확인 → 경로 수정)와 같은 그림입니다. 이 루프를 설계 대상으로 삼는 것이 4단계입니다.

스킬(Skill) — 하네스의 재사용 단위

스킬은 긴 프롬프트가 아닙니다. 업무 절차와 실행 자원을 묶어 필요할 때 불러오는 이식 가능한 패키지입니다. 구성: 지침 + 문서 + 스크립트 + 평가

skill-name/
  SKILL.md        ← 절차
  references/     ← 근거
  scripts/        ← 계산
  evals/          ← 회귀

업무 지식과 검증 코드를 함께 버전 관리한다는 점이 핵심입니다. 절차만 있고 검증이 없으면 스킬이 아니라 그냥 문서입니다.

필요할 때만 지식을 엽니다 — ① 메타데이터 인덱스 → ② SKILL.md → ③ 리소스 라이브러리. 세 단으로 여는 이유는 컨텍스트 오염과 토큰 비용을 줄이기 위해서입니다. 전부 미리 읽으면 정작 중요한 내용이 묻힙니다.

⚠️ 스킬도 공급망 자산입니다. 지침뿐 아니라 스크립트와 외부 자료를 실행하므로 출처·버전·권한을 검토해야 합니다. 승인된 저장소, 해시 확인, 최소 권한이 원칙입니다. 출처가 불분명한 스킬은 설치 후 작은 작업으로 먼저 테스트하고, 비밀번호·API 키·개인정보는 절대 넣지 않습니다.

외부 루프 — 완료는 누가 판정하는가

에이전트 밖에 또 하나의 루프가 있습니다.

빌드 → 테스트 → 벤치마크 → 재시도 게이트 → 새 세션 시작
              (안쪽에 내부 에이전트 루프)

⭐ 모델의 "완료했습니다" 선언 대신 빌드·테스트·벤치마크가 종료를 판정합니다.

앞에서 배운 pre-commit 훅 + 린터 자동 실행이 바로 이 외부 루프의 가장 작은 구현입니다.

자율 루프에는 경계가 필요하다

⚠️ 반복은 공짜가 아닙니다. 비용도, 위험도 같이 반복됩니다.

• 비용 한도 — 이 작업에 쓸 토큰·달러의 상한
• 시간 한도 — 몇 분까지 돌 것인가
• 스텝 한도 — 몇 번 반복하면 멈출 것인가
• 진전 없음 감지 — 같은 자리를 맴돌면 끊는다
• 구조화 체크포인트 — 중간 상태를 기록해 다시 시작할 수 있게

장기 작업은 인수인계가 핵심

세션이 바뀔 때 다음 세션에 넘겨야 하는 5항목입니다.

같은 실패를 반복하지 않게 하는 체크포인트입니다. 그리고 이 인수인계 문서 자체가 2단계(메모리)의 산출물입니다. 4단계는 2단계를 재료로 씁니다.

2.5 5단계 · 그래프 엔지니어링 → 조정

정의 — [에이전트 설계 단계]인데, [여러 노드의 실행 순서를 조건과 상태에 따라 조정한다]는 점에서 선형 반복인 루프 엔지니어링과 구별된다.

• 다루는 것: 조정(Orchestration). 무엇을 언제 누구에게 시킬지 정하는 일.
• 여기서 축 3(선형 ↔ 그래프) 이 오른쪽으로 넘어갑니다.

4단계까지의 루프는 선형으로 지속 반복됩니다. 같은 절차를 계속 도는 것입니다. 그런데 실제 업무는 이렇게 생기지 않았습니다.

• 검색 결과가 부실하면 다시 검색해야 합니다. (되돌아가는 화살표)
• 질문 종류에 따라 다른 경로로 가야 합니다. (분기)
• 어떤 지점에서는 사람의 승인을 받아야 합니다. (중단과 재개)
• 어떤 작업은 여러 에이전트가 나눠서 해야 합니다. (병렬과 합류)

선형 체인으로는 이 네 가지가 표현되지 않습니다. 표현하려면 노드와 엣지가 필요합니다. 그것이 그래프 엔지니어링이고, 그 구현체가 다음 절에서 볼 랭그래프(LangGraph) 입니다.

      ┌──────────────┐
      │  질문 분류    │
      └───┬──────┬───┘
   RAG    │      │   추론
          ▼      ▼
    ┌────────┐ ┌──────────┐
    │ 벡터검색│ │ 그래프탐색│
    └───┬────┘ └────┬─────┘
        │           │
        ▼           ▼
     ┌───────────────┐
     │   근거 평가    │──── 부족 ──┐
     └───────┬───────┘            │
             │ 충분               │
             ▼                    │
         ┌───────┐                │
         │  생성  │                │
         └───────┘   ◀────────────┘  (재검색 루프)

이 그림에서 화살표가 뒤로 갈 수 있다는 것과 갈래가 있다는 것이 4단계와 5단계를 가릅니다.

2.6 왜 이 순서인가

다섯 층은 임의의 나열이 아닙니다. 축이 하나씩 켜지는 순서입니다.

건너뛰면 무너집니다. 그 이유는 각 층이 아래층을 재료로 쓰기 때문입니다.

• 2단계 없이 4단계를 하면: 반복할 때마다 지시가 조금씩 달라져 결과가 흔들립니다. 반복은 편차를 증폭합니다.
• 3단계 없이 4단계를 하면: 검증 장치가 없는 채로 자동 반복이 돕니다. 틀린 결과가 빠르게 많이 쌓입니다.
• 4단계 없이 5단계를 하면: 그래프는 그렸는데 각 노드 안에서 무슨 일이 벌어지는지 아무도 모릅니다. 관측성 없는 분기는 디버깅이 불가능합니다.

⭐ 한 문장으로: 글을 고정하고(2), 손발을 달고(3), 스스로 돌게 하고(4), 그다음에야 길을 갈라(5)줍니다.

2.7 다섯 층과 판별 축의 대응

표의 볼드 칸이 각 층에서 새로 켜지는 것입니다. 한 번에 한 칸씩만 바뀝니다. 이런 식으로 정리해 두면 어떤 새 도구를 만나도 "이건 몇 층짜리인가"를 바로 물을 수 있습니다.

2.8 하네스가 드디어 자리를 잡는다 ⭐

이 교재에서 하네스라는 단어는 3주차부터 계속 나왔습니다. 그런데 나올 때마다 조금씩 다른 것을 가리키는 것처럼 보였습니다. 그 이유는 하네스가 전부인 것처럼 쓰였기 때문입니다. 이번 주에 그 단어의 정확한 자리가 정해집니다.

⭐ 하네스는 에이전트의 전부가 아니라, 다섯 층 중 세 번째 층입니다. 위로는 루프(4층)와 그래프(5층)가 있고, 아래로는 컨텍스트(2층)와 프롬프트(1층)가 있습니다.

"에이전트 = 모델 + 하네스" 라는 공식은 여전히 맞습니다. 다만 그 식의 하네스는 넓은 뜻이고(모델이 아닌 나머지 전부), 5단계의 하네스는 좁은 뜻입니다(도구·권한·검증). 같은 단어의 두 축척입니다.

둘 중 어느 쪽인지는 문장에서 옆에 무엇이 있는지로 판별합니다. "모델 + 하네스"라면 넓은 뜻이고, "컨텍스트 다음, 루프 이전"이라면 좁은 뜻입니다.

2.9 실패했을 때 어느 층을 고칠 것인가

⚠️ 실패를 모델 탓으로 묶지 마세요. 원인을 먼저 네 갈래로 분류합니다.

도구 설명 오류라면 모델 교체가 답이 아닙니다. 이 문장이 이 절의 전부입니다.

평가는 20~50개에서 시작한다

실제 사례 20~50개 (사람이 직접 읽기) → 오류 분류 → 자동 평가기

순서가 중요합니다. 오류를 분류한 뒤에 자동 평가기를 만듭니다. 무엇이 틀리는지 모르는 채로 만든 평가기는 엉뚱한 것을 잽니다.

Trace만으로는 학습이 안 됩니다. TRACE(무엇이 일어났는지)와 FEEDBACK(결과가 좋았는지)이 연결돼야 다음 실행이 개선됩니다: TRACE + FEEDBACK → AI → NEXT RUN

평가가 어렵다면 출력을 바꾸세요. 답만 주지 말고 출처·정의·계산·가정·실행 기록을 함께 내보내면, 사용자가 검증할 수 있게 되고 그때부터 평가도 가능해집니다.

2.10 어느 층에서 멈춰야 하는가

⚠️ 다섯 층을 다 올라가는 것이 목표가 아닙니다.

한 층 올라갈 때마다 만들어야 할 것과 관리해야 할 것이 늘어납니다. 3층에서 끝나는 일에 5층을 지으면 복잡도만 사고 얻는 게 없습니다.

---

3. MCP — Model + Context + Protocol ⭐

3.1 이름을 풀면 구조가 보인다

MCP 는 세 단어의 머리글자입니다.

MCP = Model + Context + Protocol

⭐ 클로드 같은 모델이 컨텍스트(깃허브 등)를 불러오는 주소이고, 프로토콜로 연결됩니다.

세 단어를 하나씩 봅니다.

정의로 다시 쓰면 이렇습니다.

• MCP — [연결 규격]인데, [모델이 외부 컨텍스트를 불러오는 방식을 표준화한다]는 점에서 개별 API 연동과 구별된다.

3.2 프로토콜이라는 말에 걸리지 마세요

앞에서 이미 여러 프로토콜을 만났습니다. HTTP(웹), SMTP(메일), FTP(파일), SSH(원격 접속), DNS(이름 풀이). 전부 "이런 순서로, 이런 형식으로 말을 걸자"는 약속입니다.

MCP도 정확히 같은 종류입니다. 다만 말을 거는 주체가 사람이나 브라우저가 아니라 모델이라는 점이 다릅니다.

[브라우저] ──HTTP──▶ [웹 서버]
[메일 앱]  ──SMTP──▶ [메일 서버]
[모델]     ──MCP───▶ [깃허브 · 드라이브 · DB · 캘린더]

⭐ 프로토콜이 표준이라서 얻는 것: 도구가 100개여도 모델은 연결 방식 하나만 알면 됩니다. 도구마다 다른 연동 코드를 쓰지 않아도 됩니다. 5주차에서 배운 포트&어댑터가 프로토콜 층위로 올라온 모습입니다.

3.3 CLI ↔ MCP — 누가 부르는가 (축 5)

계속 헷갈리는 삼총사입니다. 누가 그것을 쓰는가로 가르면 한 번에 정리됩니다.

셋은 경쟁 관계가 아닙니다. 한 줄로 이어집니다.

사람 → CLI 실행 → AI 도구 → MCP 연결 → 파일/GitHub/검색/DB → 결과 확인

사람이 CLI로 AI 도구를 실행하고, AI 도구는 MCP로 외부 도구를 연결해 일합니다. 그리고 그 외부 도구의 내부는 대개 API로 되어 있습니다.

3.4 MCP 용어 네 개

Tool과 Connector의 관계는 5주차의 포트와 어댑터와 같습니다. Tool은 "무엇을 할지"의 명세이고 Connector는 "그 서비스에서 실제로 어떻게 하는지"의 구현입니다.

3.5 스코프 — local 과 project

MCP 서버를 등록할 때 어디까지 유효한가를 정합니다.

⭐ 팀과 공유할 MCP 서버는 .mcp.json 으로 관리합니다. 이 파일이 레포에 들어가면 팀원이 클론했을 때 같은 도구 목록을 갖게 됩니다. 2층(컨텍스트 엔지니어링)의 원리가 도구 목록에도 그대로 적용되는 것입니다. 도구 구성도 버전 관리 대상입니다.

이번 주에는 .mcp.json 에서 github만 남기고 나머지를 삭제한 뒤 gmail을 추가했고, .claude.json 도 프로젝트에 맞게 정리했습니다. claude mcp list 에서 ✓ Connected 가 보이면 완료입니다.

⚠️ .mcp.json 에 등록만 해서는 안 됩니다. 그 서버의 실행 파일이 그 머신에 실제로 있어야 합니다. 로컬에서 잘 되던 MCP 서버가 EC2에서 연결 실패하는 흔한 이유가 이것입니다. which <실행파일> 이 not found 면 등록이 아무리 맞아도 연결되지 않습니다.

3.6 안전하게 쓰는 4원칙

1. 최소 권한 원칙 — 필요한 기능만 허용
2. 읽기 전용부터 시작 — 익숙해진 뒤 쓰기. 삭제 권한은 초보자에게 비추천
3. API Key 안전 관리 — 키는 공유하지 않기
4. 사용자 통제 — 보내기·삭제·수정은 사람이 마지막 승인

10주차에서 배운 원칙과 같습니다. 되돌릴 수 없는 작업은 루프 안에서 자동 실행하지 않습니다.

3.7 MCP는 다섯 층 중 어디인가

3층(하네스) 입니다. 정확히는 하네스가 다루는 7가지 중 ① 도구와 ③ 권한에 해당합니다. MCP를 붙이는 일은 에이전트에게 손을 달아주는 일이고, MCP 권한을 자르는 일은 그 손이 닿을 범위를 정하는 일입니다. 그래서 MCP 이야기는 항상 보안 이야기와 붙어 다닙니다. 손이 길어질수록 사고 반경도 넓어지기 때문입니다.

3.8 A2A — 에이전트끼리의 프로토콜

MCP가 에이전트 ↔ 도구의 프로토콜이라면, A2A(Agent2Agent) 는 에이전트 ↔ 에이전트의 프로토콜입니다.

여러 에이전트가 각자 판단하며 협업하려면 누가 언제 무엇을 하는지 조정해야 합니다. 그래서 A2A는 그래프 엔지니어링의 문제입니다.

---

4. 랭체인과 랭그래프 — 선형에서 그래프로

4.1 랭체인 — 체인은 선형이다

랭체인(LangChain) — [LLM 애플리케이션 프레임워크]인데, [모델·프롬프트·도구·메모리·저장소를 갈아끼울 수 있는 부품으로 만들어 사슬처럼 잇는다]는 점에서 직접 API를 호출하는 코드와 구별된다.

10주차에서 이미 못 박은 문장을 다시 씁니다.

LangChain의 존재 이유는 "LLM 호출을 편하게"가 아니라 모델·프롬프트·도구·메모리·저장소를 갈아끼울 수 있는 부품으로 만드는 것이며, 3주차에서 배운 전략 패턴과 포트&어댑터가 라이브러리 형태로 구현된 것이라고 보면 정확합니다.

체인(Chain)이라는 이름이 구조를 그대로 말해 줍니다.

[질문] ─▶ [프롬프트 템플릿] ─▶ [검색] ─▶ [LLM] ─▶ [출력 파서] ─▶ [답변]

A → B → C. 한 방향으로 흐르고, 갈라지지 않고, 돌아오지 않습니다.

4.2 왜 랭체인에 랭그래프를 더하는가 ⭐

선형 체인의 한계를 넘기 위해서입니다. 이유는 네 가지입니다.

Human-in-the-Loop는 이 교재에서 이미 나온 개념입니다. 2D 이미지 기반 영양소 정량 분석에서 체적 측정에 한계가 있으므로 시스템 DB 기준량을 우선 제시하고 사용자가 최종 정량(g)을 직접 확정하게 강제했던 그 설계입니다. 자동화의 반대말이 아니라 자동화 안에 사람 확인 지점을 명시적으로 박는 설계입니다.

4.3 상태(State) — 그래프가 들고 있는 것

체인과 그래프를 가르는 진짜 차이는 화살표 모양이 아니라 상태를 들고 있는가입니다.

10주차에서 배운 페널티 에어리어(무상태) ↔ 넓은 필드(상태 유지) 축이 여기서 프레임워크 선택으로 내려앉습니다. 체인은 페널티 에어리어이고 그래프는 넓은 필드입니다.

State에 흔히 들어가는 필드입니다.

class AgentState(TypedDict):
    question: str            # 원래 질문
    documents: list          # 검색해 온 근거
    generation: str          # 지금까지 만든 답
    retry_count: int         # 몇 번 다시 시도했는가
    route: str               # 어느 갈래로 갈 것인가

retry_count 한 줄이 4단계의 스텝 한도를 구현합니다. 상태가 있어야 경계를 걸 수 있습니다.

4.4 langchain → 벡터 DB / langgraph → 그래프 DB ⭐

이 대응이 이번 주의 가장 중요한 연결입니다.

langchain  ──▶  vector DB   (pgvector, Qdrant …)
langgraph  ──▶  graph DB    (Neo4j)

우연이 아닙니다. 각 프레임워크가 다루는 질문의 종류가 저장소의 질문과 같기 때문입니다.

⭐ 랭그래프와 그래프 DB가 짝인 진짜 이유: 둘 다 "노드와 엣지"라는 같은 구조를 씁니다. LangGraph는 에이전트의 실행 흐름을 그래프로 표현하고, 그래프 DB는 지식을 그래프로 저장합니다. 구조가 같으니 흐름과 지식을 같은 언어로 다룰 수 있습니다.

한 문장으로 외우세요.

랭체인은 "가까운 것"을 잘 다루고, 랭그래프는 "이어진 것"을 잘 다룹니다.

4.5 Neo4j와 Multi-hop Reasoning

Neo4j 는 엔티티와 관계를 노드/엣지로 저장해 GraphRAG의 Multi-hop Reasoning(다단계 추론) 을 지원하는 핵심 인프라입니다.

Multi-hop이란 한 번의 검색으로는 못 닿는 곳을 여러 걸음으로 가는 것입니다.

벡터 검색은 한 걸음이고(질문 벡터에서 가까운 것을 한 번에), 그래프 탐색은 여러 걸음입니다. 그래서 "왜 그런가"를 물을 수 있게 됩니다.

4.6 랭스미스 — 3층의 관측성

세 형제를 한 표로 정리합니다.

랭스미스가 3층인 이유는 명확합니다. 하네스가 다루는 7가지 중 ⑤ 관측성이 랭스미스의 일이기 때문입니다. TRACE를 남기는 도구입니다. 그리고 앞에서 배운 대로 TRACE 혼자서는 학습이 안 되므로, 거기에 FEEDBACK(좋았는가)을 붙여야 다음 실행이 나아집니다.

⚠️ 세 패키지는 한 번에 넣지 말고 순차적으로 추가합니다.

langchain
langsmith
langgraph

의존성 충돌이 났을 때 어느 패키지가 원인인지 즉시 알 수 있기 때문입니다. 파이썬·토치 버전을 먼저 확인한 뒤 하나씩 넣습니다.

4.7 시맨틱 라우터 — 어느 쪽으로 보낼 것인가

체인과 그래프가 둘 다 있으면, 들어온 질문을 어느 쪽으로 보낼지 정하는 문지기가 필요합니다. 그것이 시멘틱 라우터(Semantic Router) 입니다.

전송 버튼을 누르면 이런 경로를 지납니다.

[프론트 전송 버튼]
      │
      ▼
star_craft/adapter/inbound/api/v1/semantic_router.py   ← 시멘틱으로 의도 판단
      │
      ├── 단순 검색·요약  ──▶ 랭체인 챗봇 엔진 ──▶ 벡터 DB
      └── reasoning 질문 ──▶ 랭그래프        ──▶ 그래프 DB
      │
      ▼
[repository 계층]

앞에서 배운 게이트웨이의 시멘틱 인텐트 분류가 여기서 확장된 모습입니다. 그때는 ① RAG ② CRUD ③ Gemini API 세 갈래였고, 이번에는 ① 체인 ② 그래프로 한 축이 더 갈립니다.

⭐ 위치가 adapter/inbound/api/v1/ 인 것에 주목하세요. 5주차에서 배운 대로 라우터는 인바운드 어댑터입니다. 판단은 여기서 하고, 실제 일은 유스케이스가 합니다. 시맨틱 라우팅이 들어와도 계층 규칙은 그대로입니다.

4.8 언제 체인이고 언제 그래프인가

⚠️ 처음부터 그래프로 시작하지 마세요. 체인으로 만들어 보고 되돌아가는 화살표가 필요해지는 순간 그래프로 승격합니다. 2.10절과 같은 원리입니다.

---

5. RAG가 프레임워크로 내려앉는 자리

5.1 10주차에서 배운 것 회수

[적재]  문서 → 청킹 → 임베딩 → 벡터DB 저장
[질의]  질문 → 임베딩 → 유사 청크 top-k 검색 → 프롬프트에 주입 → 생성

그리고 RAG의 정의도 다시 확인합니다.

RAG는 저장소 종류로 정의되지 않습니다. RAG의 정의는 "검색 결과를 프롬프트에 넣는다" 이고, 무엇으로 검색하는지는 그 아래 선택지입니다.

RAG (Retrieval-Augmented Generation)
├── Vector RAG   : 질문 임베딩 → 벡터 DB 유사도 검색 → 상위 k개 청크   → 랭체인
├── Graph RAG    : 질문에서 엔티티 추출 → 그래프 DB 탐색 → 관계 경로   → 랭그래프
└── (그 외)       : 키워드 검색, SQL 조회, 웹 검색 …

오른쪽 화살표가 이번 주에 새로 붙은 부분입니다. 개념이 프레임워크 이름을 얻었습니다.

5.2 같은 데이터를 두 저장소에 넣는 이유

이번 주 실습의 핵심 과제가 이것이었습니다. users 와 jobs 같은 두 테이블을 pgvector에도 넣고 Neo4j에도 넣습니다.

users(id, name, email, age)
jobs(id, title, company, userid)

중복 저장이 낭비가 아닙니다. 두 저장소는 서로 다른 질문에 답하는 인덱스입니다. 4주차에서 배운 대로, 인덱스는 원본을 대체하는 것이 아니라 특정 질문을 빠르게 만드는 재배열입니다.

앞에서 배운 폴리글랏 퍼시스턴스(Polyglot Persistence) — 서비스마다 다른 DB를 쓰는 전략 — 가 여기서 한 서비스 안으로 들어옵니다. 한 데이터를 목적별로 다른 모양으로 갖는 것입니다.

5.3 GraphRAG — 둘을 합치는 방식

GraphRAG = 의미 유사도 + 관계로 근거를 모으는 방식입니다.

질문
 │
 ├─▶ 임베딩 ─▶ 벡터 DB ─▶ 진입점이 될 청크 몇 개 찾기      (뜻으로 들어감)
 │                              │
 │                              ▼
 └─▶ 엔티티 추출 ─▶ Neo4j ─▶ 그 청크의 엔티티에서 관계 따라가기  (관계로 넓힘)
                                │
                                ▼
                        모은 근거를 프롬프트에 주입 ─▶ 생성

뜻으로 진입점을 찾고, 관계로 연쇄를 따라간다. 이 한 줄이 GraphRAG의 전부입니다.

requirements.txt 에 neo4j-graphrag 를 추가하는 것이 이 구조의 시작점입니다.

5.4 응답 지연은 단계별로 재야 한다

⚠️ RAG가 느릴 때 "모델이 느리다"고 결론 내리면 대개 틀립니다. 구간별로 시간을 찍어야 합니다.

앞에서 배운 pgvector의 HNSW 인덱스가 두 번째 줄의 해법입니다. 인덱스가 없으면 벡터 검색은 전수 조사가 됩니다. 품질 디버깅 요령도 같습니다.

답이 이상하면 모델을 바꾸기 전에 검색된 청크를 눈으로 보세요. 근거가 틀렸으면 검색 문제, 근거는 맞는데 답이 틀렸으면 프롬프트·모델 문제입니다.

5.5 전략 문서 두 편 — 도메인이 다르면 파이프라인도 다르다

이번 주에 쓴 두 전략 문서는 같은 랭체인을 쓰지만 다루는 데이터의 성격이 정반대입니다.

⭐ 같은 프레임워크라도 도메인이 다르면 청킹 기준과 top-k와 프롬프트가 전부 달라집니다. 그래서 코드를 짜기 전에 전략 문서를 먼저 씁니다. 이것이 2층(컨텍스트 엔지니어링)이 코드보다 앞서는 이유입니다.

---

6. 문서가 먼저다 — 전략과 하네스를 나눠 쓰기

6.1 이번 주에 쌓인 문서들

번호(003, 004, …)를 파일명 앞에 붙인 이유는 읽는 순서가 곧 의존 순서이기 때문입니다. 파일명 자체가 인덱스 역할을 합니다.

6.2 전략 문서와 하네스 문서는 다른 것이다

⭐ 하네스 문서의 각 줄은 실제 나쁜 행동에서 나와야 합니다. 상상으로 쓴 규칙은 지켜지지 않고 토큰만 먹습니다.

6.3 "하네스 md만 작성하고 코딩은 금지"

이번 주에 반복해서 나온 지시입니다. langchain + pgvector에서 langgraph + neo4j로 확장할 때, 하네스 md만 작성하고 코딩은 금지했습니다.

이 규칙이 이상해 보일 수 있습니다. 하지만 이유가 분명합니다.

1. 큰 변경은 방향이 먼저입니다. 코드부터 나오면 그 코드에 끌려다니게 됩니다.
2. 문서는 리뷰가 쉽습니다. 사람이 읽고 틀린 방향을 잡아낼 수 있습니다.
3. 문서가 있으면 코드는 다시 만들 수 있습니다. 반대는 어렵습니다.
4. 토큰이 절약됩니다. 방향이 틀린 코드를 만들고 지우는 비용이 가장 큽니다.

⭐ 7주차에서 배운 AI 코딩 발전단계 ③이 정확히 이 모습입니다. "사람이 구조·규칙·테스트를 만들고, AI가 그 안에서 자유롭게 구현한다." 하네스 md를 쓰는 시간은 코딩을 미루는 시간이 아니라 ③단계를 하는 시간입니다.

6.4 클로드 코드 룰 파일 — 파일 패턴별 규칙

CLAUDE.md 는 프로젝트 전역 규칙입니다. 그런데 특정 파일에만 적용하고 싶은 규칙이 있습니다. 그럴 때 .claude/rules/ 아래에 파일을 만들고 frontmatter로 적용 범위를 지정합니다.

---
paths: ["**/*.ts", "**/*.tsx"]
---

# TypeScript 규칙

- strict mode 필수
- any 지양
- 인터페이스보다 타입 별칭 선호

paths 가 하는 일은 컨텍스트 절약입니다. 파이썬 파일을 만질 때 타입스크립트 규칙을 읽을 이유가 없습니다. 4단계에서 배운 "필요할 때만 지식을 연다" 는 원리가 규칙 파일에도 적용된 것입니다.

6.5 MEMORY.md — 자동 메모리

.claude/projects/<프로젝트>/memory/MEMORY.md

자동 메모리(Auto Memory) 는 에이전트가 세션을 넘기며 스스로 기록하는 메모리입니다. 사람이 쓰는 CLAUDE.md 와는 쓰는 주체가 다릅니다.

4단계에서 배운 인수인계 5항목(목표/완료/실패/위험/다음 행동) 이 실제로 적히는 자리가 여기입니다.

---