Learn-claude-code 19개 항목으로 이해하는 에이전트 하네스 설계

요즘 “AI 에이전트”라는 말이 너무 쉽게 쓰입니다.
하지만 실제로 Claude Code 같은 도구를 뜯어보면 핵심은 생각보다 단순합니다.

모델이 똑똑한 것이고, 우리가 만드는 것은 그 모델이 움직일 수 있는 작업 환경입니다.
learn-claude-code 저장소는 이 관점을 아주 명확하게 설명합니다. 이 저장소의 핵심 문장은 다음과 같습니다.

에이전트 = 모델 + 하네스

여기서 모델은 판단하고 추론하는 두뇌이고, 하네스(harness)는 모델에게 도구, 파일 시스템, 터미널, 권한, 메모리, 작업 공간을 제공하는 실행 환경입니다. 저장소는 Claude Code를 “그대로 복제하라”는 목적보다, Claude Code류 제품을 가능하게 하는 구조를 0부터 학습하는 데 초점을 둡니다. 원문도 Claude Code의 본질을 “하나의 에이전트 루프, 도구, 스킬 로딩, 컨텍스트 압축, 서브에이전트, 작업 시스템, 권한, 훅, 메모리, MCP” 등으로 설명합니다. (GitHub)

저장소에는 현재 s01부터 s20까지 20개 학습 챕터가 있지만, 여기서는 요청하신 대로 s01부터 s19까지 19개 항목을 외부 공개용 글 형태로 정리하겠습니다. 참고로 원문은 s20을 앞의 모든 메커니즘을 합친 종합 예제로 둡니다. (GitHub)

---

먼저 핵심 구조: 에이전트 루프

Claude Code류 에이전트의 기본 구조는 복잡한 워크플로우 엔진이 아닙니다.

사용자의 메시지를 모델에 보내고,
모델이 도구 사용을 요청하면 실행하고,
그 결과를 다시 모델에게 돌려주고,
모델이 더 이상 도구를 쓰지 않으면 답변을 반환합니다.

원문은 이를 messages → LLM → tool_use 여부 확인 → tool 실행 → 결과 추가 → 다시 messages 흐름으로 설명합니다. 중요한 점은 “모델이 도구 호출 여부를 결정하고, 코드는 모델이 요청한 일을 실행한다”는 것입니다. (GitHub)

이제 19개 항목을 하나씩 보겠습니다.

---

1. Agent Loop

하나의 루프와 Bash만으로 에이전트가 시작된다

첫 번째 항목은 가장 기본입니다.
에이전트는 거대한 프레임워크가 아니라 반복 루프에서 출발합니다.

모델에게 메시지를 보냅니다.
모델이 “터미널 명령을 실행해 달라”고 하면 실행합니다.
실행 결과를 다시 모델에게 줍니다.
이 과정을 반복합니다.

예를 들어 사용자가 이렇게 말합니다.

“현재 폴더에 어떤 파일이 있는지 확인하고 README를 요약해줘.”

에이전트는 먼저 ls를 실행하고, 그다음 cat README.md를 실행한 뒤, 내용을 요약합니다.

여기서 중요한 것은 개발자가 “먼저 ls 하고, 그다음 cat 하라”는 절차를 하드코딩하지 않는다는 점입니다.
모델이 상황을 보고 필요한 도구를 선택합니다.

원문에서도 s01은 messages, while True, stop_reason을 핵심 개념으로 설명합니다. (GitHub)

---

2. Tool Use

도구가 늘어나도 루프는 바꾸지 않는다

두 번째는 도구 확장입니다.

처음에는 Bash 하나만 있어도 됩니다.
하지만 실제 코딩 에이전트라면 파일 읽기, 파일 쓰기, 검색, 수정, 브라우저 접근, 데이터베이스 조회 같은 도구가 필요합니다.

핵심은 도구가 늘어나도 메인 루프를 바꾸지 않는 것입니다.
대신 TOOL_HANDLERS 같은 dispatch map에 새 도구를 등록합니다.

예를 들어:

TOOL_HANDLERS = {
    "bash": run_bash,
    "read_file": read_file,
    "write_file": write_file,
    "grep": grep_files,
}

이 구조에서는 새로운 도구를 추가할 때 루프 자체를 고치지 않습니다.
read_file이라는 핸들러만 추가하면 됩니다.

외부 서비스로 확장하면 이런 식입니다.

“Notion 문서를 읽는 도구”
“Supabase에서 사용자 데이터를 조회하는 도구”
“브라우저에서 특정 페이지를 열어 확인하는 도구”

도구는 에이전트의 손과 눈입니다.
모델은 판단하고, 하네스는 실행합니다.

---

3. Permission System

자유를 주기 전에 경계를 먼저 만든다

에이전트에게 Bash를 주는 순간 위험이 생깁니다.

ls는 괜찮습니다.
cat README.md도 괜찮습니다.
하지만 rm -rf / 같은 명령은 막아야 합니다.
배포 서버에서 DROP DATABASE를 실행하는 것도 막아야 합니다.

그래서 세 번째 항목은 권한 시스템입니다.

명령을 세 종류로 나눌 수 있습니다.

분류예시처리

안전	ls, pwd, cat README.md	자동 실행
주의	npm install, git commit	사용자 승인 후 실행
위험	rm -rf, 프로덕션 DB 삭제	차단

예를 들어 에이전트가 이렇게 요청했다고 합시다.

rm -rf ./dist

이 명령은 프로젝트 빌드 폴더를 지우는 정상 작업일 수도 있습니다.
하지만 무조건 실행하면 안 됩니다.
하네스는 “이 명령은 삭제 작업입니다. 실행할까요?”라고 승인을 요청해야 합니다.

원문에서도 s03은 PermissionRule과 approval pipeline을 핵심 개념으로 둡니다. (GitHub)

---

4. Hook System

루프를 고치지 말고, 루프 주변에 확장 지점을 둔다

훅은 에이전트 실행 과정의 특정 시점에 끼어드는 장치입니다.

예를 들어 도구 실행 전에는 PreToolUse, 실행 후에는 PostToolUse 같은 훅을 둘 수 있습니다. 원문도 s04의 핵심 개념으로 PreToolUse, PostToolUse, extension points를 제시합니다. (GitHub)

예시는 이렇습니다.

도구 실행 전:

에이전트가 npm install을 실행하려고 함
→ PreToolUse 훅에서 위험도 검사
→ 승인 필요 판단

도구 실행 후:

테스트 명령 실행 완료
→ PostToolUse 훅에서 실패 로그 수집
→ 에이전트에게 요약 전달

훅의 장점은 메인 루프를 더럽히지 않는다는 것입니다.

나중에 로그 수집, 비용 추적, 보안 검사, 사용자 알림, 실행 기록 저장을 붙이고 싶을 때 루프를 계속 수정하지 않아도 됩니다.
훅만 추가하면 됩니다.

---

5. TodoWrite

계획 없는 에이전트는 쉽게 흘러간다

다섯 번째는 작업 계획입니다.

사람 개발자도 큰 작업을 바로 코딩하지 않습니다.
먼저 할 일을 쪼갭니다.

예를 들어 사용자가 말합니다.

“로그인 기능을 추가해줘.”

에이전트가 바로 코드를 쓰기 시작하면 중간에 빠뜨리는 일이 생깁니다.
그래서 TodoWrite가 필요합니다.

예시:

[ ] 현재 인증 구조 확인
[ ] 로그인 API 설계
[ ] 로그인 UI 추가
[ ] 토큰 저장 방식 구현
[ ] 에러 처리 추가
[ ] 테스트 실행

이렇게 계획을 만들면 에이전트가 지금 어디까지 했는지 추적할 수 있습니다.
사용자도 진행 상태를 이해하기 쉽습니다.

원문은 s05를 “An agent without a plan drifts”라고 설명하며, TodoItem과 plan-then-execute를 핵심 개념으로 둡니다. (GitHub)

---

6. Subagent

큰 작업은 작은 에이전트에게 나눠 맡긴다

서브에이전트는 말 그대로 하위 에이전트입니다.

하나의 메인 에이전트가 모든 일을 다 하면 컨텍스트가 지저분해집니다.
조사, 분석, 테스트, 리팩터링 같은 부업은 별도 에이전트에게 맡기고 결과만 받는 편이 깔끔합니다.

예를 들어 메인 에이전트가 앱 리팩터링을 맡고 있다고 해봅시다.

메인 에이전트:

“현재 결제 모듈의 문제점을 조사해줘.”

서브에이전트:

“결제 관련 파일 8개를 확인했습니다. 중복 검증 로직이 3곳에 있고, 에러 메시지 처리가 일관되지 않습니다.”

메인 에이전트는 긴 파일 분석 과정 전체를 들고 있을 필요가 없습니다.
최종 요약만 받아서 다음 결정을 내리면 됩니다.

원문도 s06의 핵심을 fresh messages[]와 context isolation으로 설명합니다. (GitHub)

---

7. Skill Loading

모든 지식을 처음부터 넣지 말고, 필요할 때 불러온다

스킬 로딩은 매우 중요합니다.

많은 사람이 에이전트를 만들 때 시스템 프롬프트에 모든 규칙을 넣으려고 합니다.

“React 규칙도 넣고, Supabase 규칙도 넣고, 디자인 시스템도 넣고, 배포 규칙도 넣고, 글쓰기 톤도 넣고…”

이렇게 하면 컨텍스트가 금방 무거워집니다.

Skill Loading은 반대로 접근합니다.

처음에는 스킬 목록만 보여줍니다.

사용 가능한 스킬:
- react-component-skill
- supabase-query-skill
- blog-writing-skill
- test-debugging-skill

그리고 실제로 필요할 때만 상세 내용을 불러옵니다.

예를 들어 사용자가 “Supabase RLS 정책을 점검해줘”라고 하면 그때 supabase-query-skill을 로딩합니다.

원문도 s07을 “Load knowledge on demand, not upfront”이라고 설명하며, SkillManifest와 on-demand injection을 핵심 개념으로 둡니다. (GitHub)

---

8. Context Compact

긴 대화는 반드시 압축 장치가 필요하다

에이전트를 오래 실행하면 컨텍스트가 계속 쌓입니다.

파일 내용, 명령 결과, 에러 로그, 사용자 요청, 중간 계획, 테스트 결과가 모두 대화 기록에 들어갑니다.
그러면 중요한 현재 작업이 과거 로그에 묻힙니다.

Context Compact는 이 문제를 해결하는 장치입니다.

예를 들어 이런 긴 로그가 있다고 합시다.

npm test 실행 결과 300줄

에이전트에게 300줄 전체가 계속 필요하지는 않습니다.
필요한 것은 보통 이런 요약입니다.

테스트 3개 실패.
1. LoginForm.test.tsx: 토큰 저장 mock 누락
2. AuthProvider.test.tsx: refresh 함수 undefined
3. api/auth.test.ts: 401 처리 기대값 불일치

원문은 s08의 핵심으로 snipCompact, microCompact, toolResultBudget, autoCompact를 제시합니다. (GitHub)

실무적으로 말하면, 좋은 에이전트는 많이 기억하는 에이전트가 아니라 필요한 것을 남기고 나머지를 줄이는 에이전트입니다.

---

9. Memory System

기억할 것과 잊을 것을 구분한다

메모리는 단순히 모든 것을 저장하는 기능이 아닙니다.

좋은 메모리 시스템은 세 가지를 해야 합니다.

1. 무엇을 기억할지 선택한다.
2. 기억할 내용을 추출한다.
3. 기존 기억과 합쳐 정리한다.

원문도 s09를 selection, extraction, consolidation 세 가지 개념으로 설명합니다. (GitHub)

예를 들어 사용자가 반복해서 이렇게 말한다고 합시다.

“우리 프로젝트는 Next.js App Router를 써.”
“스타일은 Tailwind와 shadcn/ui 기준으로 해.”
“API는 Supabase Edge Functions로 갈 거야.”

메모리 시스템은 이것을 다음처럼 정리할 수 있습니다.

프로젝트 기본 스택:
- Next.js App Router
- Tailwind CSS
- shadcn/ui
- Supabase Edge Functions

다음 작업에서 에이전트는 이 정보를 다시 물어보지 않고 적용할 수 있습니다.

다만 주의할 점이 있습니다.
민감한 개인정보나 일시적인 정보까지 모두 저장하면 안 됩니다.
메모리는 “많이 저장하는 기능”이 아니라 “장기적으로 유용한 맥락을 정리하는 기능”에 가깝습니다.

---

10. System Prompt

시스템 프롬프트는 고정 문자열이 아니라 런타임 조립물이다

많은 에이전트 프로젝트가 거대한 시스템 프롬프트 하나로 시작합니다.

하지만 실제 제품에서는 사용자, 작업, 권한, 도구, 프로젝트 상태에 따라 시스템 프롬프트가 달라져야 합니다.

예를 들어 코딩 작업일 때는:

너는 코드베이스를 분석하고 수정하는 개발 에이전트다.

글쓰기 작업일 때는:

너는 외부 공개용 기술 글을 쓰는 에디터다.

운영 서버 접근이 포함되면:

운영 데이터 삭제 작업은 반드시 사용자 승인을 받아야 한다.

이처럼 시스템 프롬프트는 여러 섹션을 조립해서 만들어야 합니다.

원문도 s10을 runtime assembly와 section concatenation으로 설명합니다. (GitHub)

실무 예시는 다음과 같습니다.

[기본 역할]
[프로젝트 규칙]
[사용 가능한 도구]
[권한 정책]
[현재 작업 목표]
[출력 형식]

이 구조가 있어야 에이전트를 다양한 도메인에 재사용할 수 있습니다.

---

11. Error Recovery

에러는 종료 신호가 아니라 다음 행동의 출발점이다

에이전트가 명령을 실행하면 실패는 반드시 발생합니다.

패키지가 설치되지 않을 수 있습니다.
테스트가 실패할 수 있습니다.
토큰이 부족할 수 있습니다.
권한이 막힐 수 있습니다.
외부 API가 응답하지 않을 수 있습니다.

좋은 에이전트는 실패했다고 멈추지 않습니다.
실패 유형을 보고 다음 행동을 선택합니다.

예를 들어:

npm test 실패
→ 실패 로그 요약
→ 관련 파일 검색
→ 수정
→ 다시 테스트

또는:

컨텍스트 초과
→ 오래된 로그 압축
→ 현재 작업 요약 유지
→ 다시 진행

원문도 s11의 핵심 개념으로 token escalation, fallback model, retry strategies를 제시합니다. (GitHub)

실무적으로는 “재시도”보다 “어떤 방식으로 재시도할지”가 중요합니다.
같은 실패를 같은 방식으로 반복하면 비용만 낭비됩니다.

---

12. Task System

큰 목표는 디스크에 남는 작업 그래프로 관리한다

TodoWrite가 단기 계획이라면, Task System은 더 구조화된 작업 관리입니다.

예를 들어 사용자가 말합니다.

“이번 주 안에 MVP를 만들 수 있게 기능을 쪼개줘.”

이 경우 단순 체크리스트보다 작업 간 의존성이 중요합니다.

Task A: DB 스키마 설계
Task B: 로그인 API 구현
Task C: 로그인 UI 구현
Task D: 배포 설정

B는 A 이후 가능
C는 B와 병렬 일부 가능
D는 A, B 이후 가능

이런 구조를 파일로 저장하면 세션이 끊겨도 이어갈 수 있습니다.

원문은 s12의 핵심으로 TaskRecord, blockedBy, disk persistence를 제시합니다. (GitHub)

이 개념은 나중에 멀티에이전트 협업의 기반이 됩니다.
각 에이전트가 작업 보드를 보고 자신이 맡을 일을 판단할 수 있기 때문입니다.

---

13. Background Tasks

오래 걸리는 작업은 백그라운드로 보내고, 에이전트는 계속 생각한다

어떤 작업은 오래 걸립니다.

npm install
npm run build
pytest
docker build

이런 명령을 실행하는 동안 에이전트가 아무것도 못 하면 비효율적입니다.

Background Tasks는 느린 작업을 별도 스레드나 프로세스로 보내고, 에이전트는 다른 일을 계속하게 합니다.

예를 들어:

1. 테스트 실행을 백그라운드로 시작
2. 기다리는 동안 실패 가능성이 높은 코드 검토
3. 테스트 완료 알림 수신
4. 결과를 바탕으로 수정

원문도 s13의 핵심을 threaded execution과 notification queue로 설명합니다. (GitHub)

이 구조는 실제 개발 에이전트에서 매우 중요합니다.
빌드와 테스트는 자주 오래 걸리기 때문입니다.

---

14. Cron Scheduler

사람이 시키지 않아도 정해진 시간에 실행된다

Cron Scheduler는 시간 기반 실행입니다.

예를 들어:

매일 오전 9시: 어제 실패한 테스트 확인
매주 월요일: 의존성 업데이트 체크
매일 밤: 로그 요약 생성

이런 기능이 있으면 에이전트는 대화형 도구를 넘어 운영 자동화 도구에 가까워집니다.

원문은 s14를 durable scheduling과 session-scoped triggers로 설명합니다. (GitHub)

예시:

매일 아침 GitHub Issue를 확인하고,
새 버그가 있으면 우선순위를 분류한 뒤,
수정 가능한 작은 작업으로 쪼갠다.

다만 실서비스에서는 권한과 알림 정책이 중요합니다.
자동 실행이 가능한 작업과 반드시 사람 승인이 필요한 작업을 분리해야 합니다.

---

15. Agent Teams

하나의 에이전트로 부족하면 팀을 만든다

복잡한 프로젝트에서는 하나의 에이전트가 모든 역할을 맡기 어렵습니다.

그래서 Agent Teams가 등장합니다.

예를 들어 다음처럼 역할을 나눌 수 있습니다.

Planner Agent: 전체 계획 수립
Coder Agent: 코드 구현
Reviewer Agent: 코드 리뷰
Tester Agent: 테스트 실행 및 실패 분석
Writer Agent: 문서 작성

이들은 서로 메시지를 주고받아야 합니다.
그래서 mailbox나 message bus가 필요합니다.

원문은 s15의 핵심으로 MessageBus, inbox, permission bubbling을 제시합니다. (GitHub)

예를 들어 Reviewer Agent가 말합니다.

Coder에게: auth.ts의 refresh token 처리에서 예외 처리가 빠졌습니다. 수정 요청합니다.

Coder Agent는 수정 후 다시 답합니다.

Reviewer에게: 예외 처리 추가했고 테스트 통과했습니다.

이 구조가 되면 에이전트는 단일 채팅봇이 아니라 작은 개발팀처럼 움직일 수 있습니다.

---

16. Team Protocols

팀원 에이전트에게는 공통 대화 규칙이 필요하다

여러 에이전트가 함께 일하려면 자유롭게 말하게 두는 것만으로는 부족합니다.

요청 형식, 응답 형식, 승인 방식, 종료 방식이 정해져야 합니다.

예를 들어 요청 형식은 이렇게 만들 수 있습니다.

{
  "type": "request",
  "from": "planner",
  "to": "coder",
  "task_id": "TASK-12",
  "goal": "로그인 API 구현",
  "expected_output": "수정된 파일 목록과 테스트 결과"
}

응답 형식은 이렇게 만들 수 있습니다.

{
  "type": "reply",
  "from": "coder",
  "to": "planner",
  "task_id": "TASK-12",
  "status": "done",
  "summary": "로그인 API 구현 완료",
  "files_changed": ["api/auth.ts"]
}

원문은 s16의 핵심으로 shutdown handshake와 plan approval을 제시합니다. (GitHub)

프로토콜이 없으면 에이전트끼리 대화는 하지만 협업은 약해집니다.
프로토콜이 있어야 작업 상태를 추적하고, 실패를 복구하고, 결과를 검증할 수 있습니다.

---

17. Autonomous Agents

리더가 하나씩 지시하지 않아도 스스로 작업을 가져간다

Autonomous Agents는 한 단계 더 나아갑니다.

이전 단계에서는 메인 에이전트가 각 팀원에게 일을 나눠줬다면, 여기서는 팀원 에이전트가 작업 보드를 보고 스스로 할 일을 가져갑니다.

예를 들어 작업 보드가 있습니다.

TASK-1: 로그인 UI 구현
TASK-2: 인증 API 테스트
TASK-3: README 업데이트
TASK-4: 배포 설정 확인

Tester Agent는 TASK-2를 보고 이렇게 판단합니다.

나는 테스트 담당이므로 TASK-2를 claim한다.

Writer Agent는 TASK-3을 가져갑니다.

원문은 s17의 핵심을 idle cycle, auto-claim, self-organization으로 설명합니다. (GitHub)

이 구조는 작은 조직처럼 작동합니다.
중앙 리더가 모든 것을 지시하지 않아도, 각 에이전트가 자기 역할에 맞는 일을 찾아 수행합니다.

---

18. Worktree Isolation

각 에이전트는 자기 작업 공간에서 일해야 한다

여러 에이전트가 동시에 같은 폴더에서 코드를 수정하면 충돌이 생깁니다.

Coder Agent가 auth.ts를 수정하는 동안, Reviewer Agent나 다른 Coder Agent가 같은 파일을 수정하면 결과가 꼬일 수 있습니다.

그래서 Worktree Isolation이 필요합니다.

각 작업은 별도 디렉터리나 Git worktree에서 진행됩니다.

/worktrees/task-101-login-api
/worktrees/task-102-login-ui
/worktrees/task-103-readme-update

이렇게 하면 병렬 작업이 가능해집니다.
작업이 끝난 뒤에는 diff를 검토하고 병합하면 됩니다.

원문은 s18의 핵심으로 WorktreeRecord와 task-directory binding을 제시합니다. (GitHub)

실무적으로 이 항목은 매우 중요합니다.
멀티에이전트 개발에서 격리 없이 병렬 실행을 하면 파일 충돌, 상태 오염, 테스트 결과 혼동이 쉽게 발생합니다.

---

19. MCP Plugin

기능이 부족하면 MCP로 외부 도구를 연결한다

마지막 19번째 항목은 MCP Plugin입니다.

MCP는 Model Context Protocol의 약자로, 모델이나 에이전트가 외부 도구와 연결되는 표준화된 방식으로 이해할 수 있습니다.

예를 들어 기본 에이전트에는 파일 읽기와 Bash만 있다고 합시다.
하지만 실제 업무에서는 더 많은 외부 능력이 필요합니다.

GitHub Issue 읽기
Notion 문서 검색
Slack 메시지 확인
Figma 디자인 읽기
Database 조회
브라우저 자동화

MCP Plugin은 이런 외부 기능을 에이전트의 도구 풀에 연결하는 방식입니다.

원문은 s19를 “Not enough capability? Plug in more via MCP”라고 설명하며, multi-transport, channel routing, tool pool assembly를 핵심 개념으로 둡니다. (GitHub)

예를 들어 에이전트가 이렇게 판단할 수 있습니다.

이 작업은 코드만 봐서는 부족하다.
관련 GitHub Issue와 Figma 디자인을 함께 확인해야 한다.

그러면 MCP를 통해 GitHub 도구와 Figma 도구를 호출하고, 그 결과를 바탕으로 코드를 수정합니다.

이 단계까지 오면 에이전트는 단순 코딩 도우미가 아니라 회사 내부 시스템과 연결된 작업 실행자가 됩니다.

---

이 19개 항목을 한 문장으로 정리하면

learn-claude-code의 19개 항목은 Claude Code 같은 에이전트를 “마법 같은 AI 제품”이 아니라 모델이 일할 수 있는 운영 환경을 점진적으로 구축하는 과정으로 보여줍니다.

정리하면 흐름은 이렇습니다.

1단계: 모델이 행동하게 한다
Agent Loop → Tool Use → Permission → Hooks

2단계: 복잡한 일을 처리하게 한다
TodoWrite → Subagent → Skill Loading → Context Compact

3단계: 오래 일하게 한다
Memory → System Prompt → Error Recovery → Task System

4단계: 비동기·자동화를 붙인다
Background Tasks → Cron Scheduler

5단계: 팀처럼 일하게 한다
Agent Teams → Team Protocols → Autonomous Agents → Worktree Isolation

6단계: 외부 세계와 연결한다
MCP Plugin

원문도 학습 경로를 “act → handle complex work → remember and recover → run long tasks → collaborate → extend and assemble”로 설명합니다. (GitHub)

---

개발자 관점에서 가장 중요한 포인트

이 저장소를 보고 얻어야 할 핵심은 “나도 Claude Code를 똑같이 만들 수 있다”가 아닙니다.

더 중요한 것은 이것입니다.

에이전트 제품의 본질은 프롬프트 체인이 아니라 하네스 설계다.

좋은 하네스는 모델에게 다음을 제공합니다.

도구: 읽기, 쓰기, 검색, 실행
지식: 문서, 규칙, 스킬
관찰: 로그, diff, 테스트 결과
행동: CLI, API, 브라우저, DB
권한: 승인, 차단, 격리
메모리: 중요한 맥락 유지
협업: 작업 보드, 메시지, 역할 분담
확장: MCP 기반 외부 도구 연결

원문도 하네스를 Tools, Knowledge, Observation, Action Interfaces, Permissions로 구성된 환경으로 설명합니다. (GitHub)

결국 AI 에이전트 개발에서 우리가 만드는 것은 “두뇌”가 아닙니다.
두뇌는 모델입니다.
우리가 만드는 것은 그 두뇌가 안전하고 효율적으로 움직일 수 있는 몸, 도구, 작업장, 규칙입니다.

---

실전 적용 예시: 교과서 예습·복습 에이전트에 붙인다면

예를 들어 초등·중학생용 교과서 공부 에이전트를 만든다고 해봅시다.

이 19개 항목은 그대로 적용됩니다.

Agent Loop:
학생 질문을 받고 필요한 도구를 호출하는 기본 루프

Tool Use:
교과서 검색, 문제 생성, 오답 분석, 음성 읽기 도구

Permission:
외부 링크 이동, 개인정보 저장, 학부모 리포트 전송 전 승인

Hooks:
학습 완료 후 기록 저장, 퀴즈 종료 후 점수 계산

TodoWrite:
“오늘 3단원 복습하기”를 작은 학습 단계로 분해

Subagent:
문법 설명 에이전트, 문제 출제 에이전트, 오답 분석 에이전트 분리

Skill Loading:
수학, 국어, 영어, 한국어 문법 스킬을 필요할 때만 로딩

Context Compact:
긴 학습 대화를 “오늘 배운 것 / 자주 틀린 것”으로 요약

Memory:
학생이 자주 틀리는 개념과 선호 학습 방식 저장

System Prompt:
학년, 과목, 난이도에 따라 프롬프트 조립

Error Recovery:
틀린 답이 반복되면 더 쉬운 설명으로 전환

Task System:
한 주 학습 계획을 작업 그래프로 관리

Background Tasks:
학습 리포트 생성은 백그라운드 처리

Cron Scheduler:
매일 저녁 복습 알림 또는 주간 리포트 생성

Agent Teams:
개념 설명, 문제 생성, 채점, 리포트 에이전트 분리

Team Protocols:
각 에이전트의 요청·응답 형식 표준화

Autonomous Agents:
학생 취약 단원을 보고 자동으로 복습 과제 생성

Worktree Isolation:
과목별·학생별 작업 공간 분리

MCP Plugin:
Google Drive, Notion, LMS, 캘린더, 교재 DB와 연결

이렇게 보면 learn-claude-code는 단순히 Claude Code 학습 자료가 아니라, 거의 모든 AI 에이전트 제품에 적용할 수 있는 설계 패턴 모음에 가깝습니다.

---

마무리

앞으로 에이전트 개발의 경쟁력은 “모델을 몇 번 호출하느냐”보다 “모델이 일할 수 있는 환경을 얼마나 잘 설계하느냐”에서 갈릴 가능성이 큽니다.

파일을 읽고, 명령을 실행하고, 권한을 확인하고, 계획을 세우고, 기억을 정리하고, 실패를 복구하고, 다른 에이전트와 협업하고, 외부 도구까지 연결하는 구조.

그게 바로 하네스입니다.

learn-claude-code의 19개 항목은 이 하네스를 아주 작은 루프에서 시작해 실제 에이전트 제품 구조까지 확장하는 과정을 보여줍니다.
AI 에이전트를 만들고 싶다면, 먼저 “에이전트를 만든다”는 표현을 조금 바꿔보는 것이 좋습니다.

우리가 만드는 것은 지능 그 자체가 아니라,
지능이 제대로 일할 수 있는 세계입니다.

GitHub - shareAI-lab/learn-claude-code: Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1