notes

하네스 엔지니어링 — 개념과 세팅

2026-05-16수정 2026-09-269 min read

하네스 엔지니어링의 개념·도구 세팅과 AI 작업 환경 구성 메모.

Kim mr.

프론트엔드 · 기술 블로그

1. 하네스 엔지니어링이 뭔가

프롬프트·컨텍스트 다음 단계다. 모델이 실제로 일하게 만드는 런타임 을 설계하는 일.

한 문장: 좋은 모델보다, 모델이 틀려도 시스템이 덜 무너지는 구조가 결과를 좌우한다.

flowchart TB
  ORCH["Orchestrator<br/>에이전트 루프 · 누가 언제 무엇을"]
  TOOL["Tool 레이어<br/>NotebookLM / Notion / Figma MCP"]
  GATE["Gate<br/>코드 폴링 · lint · 테스트"]
  NEXT["다음 단계<br/>구현 · PR · 문서"]
  ORCH --> TOOL
  TOOL --> GATE
  GATE -->|"통과"| NEXT
  GATE -->|"실패"| ORCH

2. 왜 NotebookLM이 나오나

NotebookLM이 “더 똑똑한 모델”이라서가 아니다. 하네스 안에 꽂는 조사 도구이기 때문이다.

패턴: 조사·요약은 NotebookLM, 에이전트는 orchestration(조율)에 집중.

NotebookLM = RAG/리서치 레이어를 이미 만들어 둔 managed tool

하네스 = 그 tool을 언제, 어떻게, 검증과 함께 쓸지 설계하는 것

3. 하네스 관점에서 왜 이 도구인가

(1) 환각 줄이기 = 검증 가능한 서브시스템

일반 LLM: 아는 척할 수 있음
NotebookLM: 소스에 grounded → 인용·근거

조사 단계 출력을 “이 단계는 신뢰 가능”이라고 설계할 수 있다.

(2) 역할 분리

[Orchestrator]  Cursor / CrewAI / 에이전트 루프     ← 누가, 언제, 무엇을
        |
[Tool]         NotebookLM MCP / API              ← 조사·요약·아티팩트
        |
[Gate]         Python polling / CLI / lint       ← 소스 로딩됐나? 테스트 통과?
        |
[Next]         구현 · 문서 · PR

게이트는 LLM이 아니라 코드. “노트북 준비됐어?” → subprocess / API 폴링. 토큰 0, 환각 0. 준비 안 됐으면 다음 Phase 안 넘김.

이게 하네스 = LLM + deterministic verification.

(3) 컨텍스트·토큰 최적화

하네스는 컨텍스트 엔지니어링의 상위 개념이기도 하다.

PDF 100페이지를 매번 LLM에 넣지 않음
NotebookLM이 인덱싱·검색·요약
에이전트에는 짧은 grounded 답 + 인용만

비용·속도·품질이 모두 하네스 목표와 맞다.

(4) MCP = 표준 플러그

NotebookLM MCP, notebooklm-py 같은 게 Tool Contract를 채운다.

어떤 에이전트든 query_notebook() 같은 방식으로 호출
인증·세션은 MCP 서버가 담당
에이전트는 비즈니스 로직 + 오케스트레이션만

Obsidian MCP, Notion MCP와 같은 층위. 개인 지식 베이스를 노트북으로 둔 버전.

4. Cursor는 이미 하네스다

모델 + 하네스는 Cursor 안에 이미 있다. NotebookLM을 붙이면 코드 하네스 + 문서/리서치 하네스를 합치는 그림.

역할 나누기: NotebookLM = 조사·근거, Cursor / Claude Code = 실행·코드. Cursor 하나로 NotebookLM 웹 UI 전체를 대체하진 않는다.

5. Claude vs Cursor (왜 Claude 글이 더 많나)

NotebookLM 연동 글이 대부분 Claude Code / Claude Desktop + MCP 기준인 이유: Claude 쪽에서 훨씬 먼저·자주 쓰였기 때문이다. “Claude만 된다”가 아니라 “Claude 문서·튜토리얼이 먼저 나왔다”에 가깝다.

Claude에서 되는 것

흐름은 Cursor와 같다.

Claude Agent → MCP: notebooklm → Google NotebookLM → grounded 답 + 인용

커뮤니티 MCP(notebooklm-mcp, notebooklm-mcp-2026 등) README에 Claude Code / Desktop / Cursor를 같이 적는 이유도, Claude가 MCP를 일찍·본격적으로 썼기 때문이다.

느낌 차이

NotebookLM 연동 자체는 둘 다 MCP만 넣으면 비슷하다. “Claude에서 된다” = 주로 Claude Desktop/Code + MCP 조합을 말하는 경우가 많다.

왜 Claude 얘기가 더 많은가

MCP를 Anthropic이 밀었던 쪽 — 도구 연결 패턴이 Claude 글/데모에 많음
NotebookLM MCP 만든 사람들이 Claude Code 사용자 타깃으로 README·Skill을 올림
Cursor Plugins에 NotebookLM이 없고, Claude도 공식 NotebookLM 플러그인은 없음 → 둘 다 커뮤니티 MCP 경로

옮기기

Claude Desktop / Claude Code → 글·예제 많음
Cursor → 같은 MCP를 ~/.cursor/mcp.json에 넣으면 동일 (지금 적용됨)
Google 공식 NotebookLM 플러그인은 Claude·Cursor 둘 다 없음

Claude에서 쓰던 notebooklm-mcp 설정을 Cursor mcp.json에 그대로 옮기면 거의 같은 방식으로 쓴다.

6. 세팅 — Cursor에 녹이는 방법

6-1. NotebookLM MCP (Cursor에 이미 넣음)

커뮤니티 서버 notebooklm-mcp@latest (확인: v2.0.0, Node v22.22.2). 기존 telegram-notifier는 그대로 둠.

Cursor Agent
  → MCP: notebooklm
  → Google NotebookLM
  → grounded 답 + 인용
  → 코드/문서 작성

적용된 설정 (~/.cursor/mcp.json)

"notebooklm": {
  "command": "npx",
  "args": ["-y", "notebooklm-mcp@latest"]
}

처음 쓸 때

Cursor 완전 재시작 (MCP 설정 반영)
Settings → MCP 에서 notebooklm 이 Connected 인지 확인
처음 사용 시 Google 로그인 — 브라우저 창이 뜨면 NotebookLM 계정으로 인증

인증이 안 되면 Agent 채팅에서:

NotebookLM 로그인해줘 / list notebooks 해줘

라고 하면 MCP 도구가 auth를 진행한다.

에이전트가 쓰는 tool

주의

비공식 커뮤니티 MCP. Google 정책·UI 변경 시 동작이 바뀔 수 있음
Chrome 프로필: ~/Library/Application Support/notebooklm-mcp/
재시작 후 MCP가 Error 이면 Settings → MCP 로그를 보고 이어가기
코드베이스 대체가 아님 — 문서/리서치 레이어

6-2. Notion / Obsidian MCP (PKM)

NotebookLM 대신 내 노트를 쓰려면:

셋 다 “LLM의 장기 기억/조사를 외부 subsystem으로 분리” 한다는 점에서 같다.

6-3. Rules + Skills (NotebookLM 없이도 하네스)

자세한 파일 형식은 Harness Engineering - Cursor: Skill.md / Rules로 작업 가이드 붙이기.

“에이전트가 같은 실수를 반복하지 않게” = Hashimoto / Osmani가 말하는 ratchet.

6-4. 게이트를 코드로

세팅의 핵심은 MCP를 다는 것만으로 끝나지 않는다. 다음 단계로 넘기기 전에 결정적 체크를 둔다.

노트북/소스 인덱싱 끝났는지 API 폴링
lint / 테스트 실패면 커밋·PR 안 함
헬스체크 실패 노드는 타겟에서 빼기 (서버 대장 구조와 같은 발상)

LLM에게 “준비됐어?”라고 묻지 말 것. 코드가 yes/no를 말하게.

7. 실무 조합

패턴 A — 코드 + 문서 분리

[Cursor codebase index]  → 구현·리팩터
[NotebookLM MCP]         → 기획서·API PDF 질의
[.cursor/rules]          → UI / 코딩 규칙

패턴 B — 리서치 후 구현

NotebookLM에 BE API 문서·Figma 설명 업로드
Cursor에서 “노트북 기준으로 member favorite API 타입 맞춰줘”
Rules로 UI는 건드리지 않기

패턴 C — Obsidian 위키 + Cursor (NotebookLM 없이 grounded)

docs/architecture/ 를 Obsidian과 git 공유
Cursor @docs/... 로 참조

8. thankq에 바로 쓸 것

이미 있는 것:

.cursor/rules — steamed UI-only, SectionCard 등
Skills — reserve flow, auth 등
MCP — Notion / Figma + notebooklm (~/.cursor/mcp.json)

추가로 하려면:

BE API PDF / 기획 Notion → NotebookLM 또는 Notion MCP (둘 중 하나부터)
“찜한 숙소 API 스펙” 노트북 하나 만들고 Cursor MCP 연결
스펙 질의는 NotebookLM, 구현은 Cursor

9. 세팅 체크리스트

Cursor 완전 재시작 후 Settings → MCP 에서 notebooklm 이 Connected
첫 사용 시 Google 로그인 (안 되면 채팅에서 list notebooks)
Cursor MCP에 조사 도구가 보인다 (NotebookLM 또는 Notion)
인증이 한 번 되어 에이전트가 query / fetch를 실제로 친다
소스 로딩 완료를 코드 게이트로 확인한다
.cursor/rules 에 “스펙은 tool 결과만, 추측 금지” 한 줄
큰 PDF를 채팅에 직접 붙이지 않고 노트북/페이지로 뺀다
구현은 코드 인덱스, 조사는 외부 tool — 역할이 섞이지 않는다

10. 한 줄

범용 LLM 하나로 조사·근거·요약까지 다 하지 말고, grounded research는 NotebookLM 같은 전문 도구로 빼고, 에이전트 하네스는 orchestration · 검증 · 권한 · 재시도에 집중하자.

Cursor에서 NotebookLM · Obsidian · Notion을 MCP / Skills / Rules로 붙이면 이 패턴을 그대로 쓴다. Claude에서 쓰던 notebooklm-mcp는 Cursor mcp.json에 그대로 옮기면 되고, 지금 그 설정이 들어가 있다. Google 공식 플러그인은 둘 다 없다.