한빛미디어

한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 

책을 협찬 받아 작성된 서평입니다.

도서링크: https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

얼마 전 젠슨 황이 유퀴즈에 출연한 영상을 보았다. 여러 이야기 중 가장 인상 깊었던 말은 "코딩은 어렵지만 AI는 쉽다."라는 문장이었다. AI가 기술의 격차를 줄여 누구나 자신만의 웹사이트를 만들 수 있는 시대가 올 것이라는 설명도 덧붙였다.

절반은 공감했고, 절반은 의아했다.

실무를 하다 보면 외부 연동 기술 문서에서도 "AI에게 물어보며 따라 해보세요."라는 안내를 어렵지 않게 볼 수 있다. 토스페이, 네이버페이 같은 서비스도 예외가 아니다. 이런 흐름을 보다 보면 문득 '정말 앞으로도 나 같은 개발자가 필요할까?'라는 생각이 들기도 한다.

하지만 기술의 진입 장벽이 낮아졌다고 해서 모두가 같은 품질과 속도로 서비스를 만들 수 있는 것은 아니라고 생각한다. 실제 서비스는 요구사항을 정의하고, 설계하고, 구현하고, 테스트하고, 운영하는 과정이 유기적으로 연결되어 있다. 각 단계마다 필요한 관점도, 경험도 다르다.

결국 AI를 잘 활용하는 능력은 단순히 프롬프트를 잘 작성하는 것이 아니라, 어떤 일을 누구에게 맡길지, 어떤 순서로 진행할지, 그리고 결과를 어떻게 검증할지를 설계하는 능력에 더 가까운 것이 아닐까.

이 책을 읽기 전까지 내가 가장 막막했던 부분도 바로 그것이었다.

챗GPT나 클로드와 코딩을 하다 보면, 결국 나보다 조금 더 능숙한 동료 한 명과 짝코딩을 하는 느낌이 들곤 했다. 물론 가끔은 내가 방향을 잡아줘야 하는 순간도 있었다. IT 커뮤니티에서 "이제 비개발자도 AI로 코딩합니다!"라는 이야기를 볼 때마다 속으로 '당신의 클로드와 저의 클로드는 다른 것입니까...?' 하고 생각했던 것도 사실이다.

그러던 중 AI로 하나의 팀을 만들고, 그 팀을 잘 운영하는 방법이 하네스 엔지니어링이라는 것을 알게 되었다. 마침 요즘 꽤 뜨거운 주제라 주변에서도 스터디를 하는 분들이 많았다. 스터디에 참여하려면 적어도 기본 개념은 알아야 할 것 같았고, 마침 한빛미디어를 통해 좋은 기회로 이 책을 읽게 되었다.

이 책은 하네스 엔지니어링을 처음 접하는 사람, 그리고 Claude Code의 강력한 기능인 에이전트와 오케스트레이터를 아직 활용해보지 않은 사람도 이해할 수 있도록 기초부터 차근차근 설명해 준다.

책에서 정의하는 하네스는 다음과 같다.

하네스는 누가(Agent), 어떻게(Skill), 언제, 누구와(Orchestrator)라는 세 가지 요소로 나뉘며, 이들은 독립적으로 설계되고 실행 시점에만 맞물린다.

책은 이 세 가지 요소를 중심으로 예제를 풀어간다. 먼저 포맷과 원칙을 설명하고, 좋은 예와 나쁜 예를 항상 함께 보여준다. 

단순히 따라 하게 만드는 것이 아니라 왜 이렇게 설계해야 하는지를 비교하며 설명해 주기 때문에 이해가 훨씬 쉬웠다.

좋았던 점은 개념 설명을 꽤 자세하게 해준다는 것이었다. 단순히 "AI에게 일을 시킨다." 정도에서 끝나는 것이 아니라, 역할을 왜 나누는지, 어떤 도구를 써야 하는지, 어떤 산출물이 나와야 하는지 하나씩 설명해 준다. 구현자와 검증자를 분리하는 부분도 실제 개발 프로세스와 닮아 있어서 특히 흥미로웠다.

덕분에 처음 접하는 내용인데도 고개를 끄덕이며 읽을 수 있었다. 방법론을 다루는 책은 개념을 따라가지 못해 결국 예제만 훑고 덮는 경우도 많았는데, 이 책은 적어도 '왜 이런 구조를 사용하는지'는 이해하고 넘어갈 수 있었다. AI를 단순한 질의응답 도구가 아니라 하나의 팀으로 바라보게 된 것도 큰 변화였다.

개인적으로는 초반 Chapter 4가 특히 재미있었다. 하네스를 설명하는 예시가 세계관 생성(World Builder), 캐릭터 설계(Character Designer) 같은 창작 영역이었기 때문이다. 만약 처음부터 프로그래밍 예시만 나왔다면 조금 덜 흥미로웠을지도 모르겠다. 오히려 일상적인 예시 덕분에 개념을 부담 없이 받아들일 수 있었고, 개발뿐 아니라 글쓰기나 영화 감상 같은 취미에도 적용해 보고 싶다는 생각이 들었다. 개발자를 대상으로 쓰인 책이지만, AI를 조금 더 체계적으로 활용해보고 싶은 비개발자에게도 충분히 도움이 될 것 같다.

책의 후반부에는 상황별 실습 예제가 준비되어 있다. 코드 리뷰 자동화 팀, 풀스택 기능 구현 팀, 레거시 마이그레이션 팀, 디버깅 및 RCA 팀까지 실제 업무에 응용할 수 있는 예제들이라 개발자인 내 입장에서는 꽤 흥미롭게 읽혔다.

다만 아쉬운 점도 있었다. 예제와 설명, GitHub 소스는 제공되지만 책만으로는 어떤 순서로 실행해야 하는지 바로 감을 잡기 어려웠다. 하네스 엔지니어링이나 Claude Code에 익숙한 사람이라면 자연스럽게 따라갈 수도 있겠지만, 처음 접하는 입장에서는 프로젝트를 실행하기까지 시행착오가 있었다.

또 개념 설명과 예제가 자연스럽게 이어지는 구성이다 보니, 처음에는 어디서부터 실습을 시작해야 하는지 조금 헷갈리기도 했다. 실습 예제의 시작 지점이나 준비 과정을 조금 더 명확하게 안내해 주었다면 초반 진입 장벽이 더 낮아졌을 것 같다.

처음에 조금 헤매긴 했어도 개발자로써 바로 접목 시켜볼 예제를 해볼 수 있어서 몹시 흥미로웠다. 가장 흥미로웠던 것은 '풀스택 기능 구현 팀' 예제였다. 하지만 막상 수행하다보니 또 하나의 고민이 생겼다.

이 구조를 내가 사용하는 Spring Boot와 Vue 프로젝트에는 어떻게 적용해야할까.

결국 그 답은 직접 해보는 수밖에 없었다. 그래서 책의 예제를 그대로 따라 하기보다, 내가 가장 익숙한 기술 스택으로 조금 단순화해서 구현해 보기로 했다. 거창한 서비스를 만드는 대신, JWT 인증이 포함된 로그인 기능 하나만이라도 하네스 엔지니어링 방식으로 만들어보자는 것이 이번 실습의 목표였다.

가장 처음에는 프로젝트 구조를 만들었다. 그리고 사람이 보는 프로젝트 소개인 README.md, AI가 읽는 프로젝트 가이드인 CLAUDE.md, 그리고 팀 구성과 Phase를 정의하는 문서들을 먼저 작성했다.

README.md

# Spring Boot + Nuxt JWT Login Harness

책의 풀스택 에이전트 예제를 Spring Boot + Nuxt 3 + MySQL + JWT 로그인 기능에 맞게 변형한 실습용 하네스.

## 목표

- 회원가입
- 로그인
- JWT access token 발급
- `/api/me` 내 정보 조회
- Nuxt 화면 연동

  

## 기술 스택

Backend
- Java 17
- Spring Boot 3
- Gradle
- Spring Security 6
- MyBatis
- MySQL 8
- JWT

 
Frontend
- Nuxt 3
- Vue 3
- JavaScript
- Pinia
- Axios 또는 $fetch/useFetch


Database
- MySQL
- host: localhost
- port: 3306
- database: login_demo
- username: root
- password: test1234

  

## 실습 범위

포함:
- 회원가입
- 로그인
- JWT 발급
- `/api/me` 조회
- Nuxt 로그인/회원가입/마이페이지

제외:
- Refresh Token
- OAuth
- Redis
- 권한(Role) 관리

처음이라 욕심내기보다 책의 구조를 그대로 따라가는 데 집중했다.

프로젝트 구조

login-harness-demo/
├── README.md
├── CLAUDE.md
├── 00_team_table.md -- 팀 에이전트 표
├── 01_phase_matrix.md -- 단계별 매트릭스
└── .claude/
    └── agents/
        ├── feature-pm.md
        ├── api-designer.md
        ├── ui-designer.md
        ├── db-migrator.md
        ├── backend-impl.md
        ├── frontend-impl.md
        ├── boundary-verifier.md
        └── mentor-reviewer.md

책에서는 통합테스트를 위한 에이전트가 있지만 나는 단순한 로그인 기능 구현이기 때문에 통합테스트 에이전트 대신 구현 이후 회고를 남겨주는 mentor-reviewer 에이전트를 추가했다. 사이드 프로젝트를 하다 보면 기능 구현에만 집중하느라 회고를 가장 먼저 미루게 되는 경우가 많았기 때문이다.

에이전트를 만들면서 가장 신경 쓴 부분은 책에서 여러 번 강조했던 프론트매터와 역할 정의, 에러 핸들링이었다. 역할이 명확하지 않으면 결국 AI도 사람이 시키는 대로 중구난방으로 움직인다는 걸 조금씩 느끼고 있었기 때문이다. 혹시 잘 작성했는지 확신이 서지 않을 때는 그 부분도 Claude에게 검토를 부탁했다.

이후에는 PM 에이전트에게 프로젝트를 맡겼다. 처음에는 프롬프트도 한 줄씩 보내려고 했다. 그런데 하다 보니 이것도 결국 요구사항을 전달하는 일이라는 것을 깨달았다. 실무에서도 요구사항이 명확할수록 설계가 쉬워지는 것처럼 AI도 마찬가지였다. 어떤 기능을 만들 것인지, 어디까지 구현할 것인지, 무엇을 제외할 것인지 자세하게 적어줄수록 결과가 훨씬 안정적이었다. 이 때문에 최대한 상세하게 정리해서 요구한 후에 설계로 넘어가도록 지시했다.

Phase 1에서는 API, 화면, DB 설계가 순식간에 만들어졌다. 놀라운 것은 그 다음이었다. Phase 2가 시작되자 백엔드와 프론트엔드 에이전트가 각자 역할을 나눠 구현을 시작했다. 사이드 프로젝트를 하면 환경을 잡는 데만 며칠이 걸리는 경우도 많은데, 몇 분 만에 Spring Boot와 Nuxt 프로젝트가 구성되고 JWT 로그인 기능까지 만들어지는 모습을 보니 꽤 신기했다. package.json부터 Gradle 설정까지 알아서 맞춰가는 모습을 보고 있으니 정말 여러 명의 개발자가 동시에 일하는 것 같은 기분이 들었다.

물론 한 번에 모든 것이 완벽하게 끝나지는 않았다. 백엔드 소스를 IntelliJ에서 실행해 보니 빌드가 되지 않는 문제가 생겼다. 그런데 이것도 Claude에게 그대로 보여주니 Gradle 버전을 수정하고 필요한 부분을 다시 맞춰 빌드가 가능하도록 수정해 주었다. 개발하면서 당연하게 겪던 삽질들이 꽤 많이 줄어드는 느낌이었다.

Phase 3에서는 내가 가장 기대했던 검증 단계가 시작됐다. 설계 기준과 다른 부분을 찾아 수정하는 과정이었다. 실제로 403을 반환하던 부분을 401로 수정하는 등, 검증 에이전트가 기준에 맞지 않는 부분을 찾아 다시 구현 에이전트에게 수정하도록 하는 작업이 인상적이었다.

마지막으로는 내가 추가한 mentor-reviewer 에이전트가 학습 회고를 작성해 주었다. 사이드 프로젝트를 하다 보면 기록은 항상 마지막으로 미루게 되는데, 구현이 끝난 직후 회고까지 이어지는 결과물이 공부용 프로젝트를 만들 때 특히 유용하겠다는 생각이 들었다.

짠, 결과적으로는 조금 엉성하지만 JWT 인증이 포함된 회원가입, 로그인, 로그아웃 기능이 완성됐다.

흥미로웠던 건 여기서 끝이 아니라는 점이었다. 실행도 Claude가 직접 진행했고, Playwright로 화면을 테스트한 뒤 스크린샷까지 남겨주었다. 혹시 결과가 의심스러워 DB도 확인해 달라고 했더니 회원 정보도 정상적으로 저장되어 있었다.

실습을 하고 나니 가장 크게 바뀐 건 AI를 바라보는 관점이었다.

그동안은 AI에게 "로그인 기능 만들어줘."처럼 한 번에 요청하는 경우가 많았다. 원하는 결과가 나오지 않으면 프롬프트를 조금씩 수정하고 방향을 잡아주면서 같이 짝코딩을 하는 느낌이었다. 능숙한 동료 한 명과 계속 대화를 이어가는 것 같기도 했고, 가끔은 내가 리딩을 해줘야 하는 순간도 있었다.

그런데 하네스 엔지니어링은 접근 방식 자체가 달랐다. 먼저 역할을 나누고, 각 역할이 무엇을 해야 하는지 정의한 다음 일을 맡긴다. 요구사항을 정리하는 PM이 있고, 설계하는 에이전트가 있고, 구현하는 에이전트가 있고, 마지막에는 검증하는 에이전트가 있다. 사람끼리 프로젝트를 진행할 때의 흐름을 AI에게도 그대로 가져온 느낌이었다.

이번 실습에서도 가장 신기했던 건 로그인 기능이 만들어진 것보다, 설계 기준과 맞지 않는 부분을 검증 에이전트가 찾아내고 다시 수정한 뒤 한 번 더 확인하는 과정이었다. 처음에는 로그인 하나 만드는데 이렇게까지 해야 하나 싶었는데, 기능이 조금만 복잡해져도 이런 방식이 훨씬 힘을 발하겠다는 생각이 들었다. 회사에서 운영하는 서비스처럼 여러 사람이 함께 만드는 프로젝트라면 더더욱 그럴 것 같았다.

물론 내가 만든 하네스도 아직은 많이 부족하다. 어떤 역할을 더 나누면 좋을지, 검증은 어디까지 시켜야 할지 고민도 많이 남아 있다. 그래도 한 가지는 확실히 알게 됐다. AI에게 일을 잘 시킨다는 건 프롬프트를 길게 쓰는 것이 아니라, 누구에게 어떤 일을 맡길지, 어떤 순서로 진행하고 어떻게 검증할지를 먼저 설계하는 일이라는 것을. 그동안 막연하게만 느껴졌던 하네스 엔지니어링이 이번 실습을 통해 조금은 손에 잡히는 개념이 된 것 같다.

60대인 아버지는 아직도 키오스크 사용을 어려워하신다. 하지만 제미나이로 난초 키우는 방법을 찾아보고, 영어 공부도 책보다 AI와의 대화를 더 편하게 활용하신다. 이제 AI는 누구나 큰 부담 없이 사용할 수 있는 '도우미'가 되었다.

그렇다면 앞으로는 일반인도 전문가의 도움을 받지 않고 서비스를 만드는 시대가 올지도 모른다. 하지만 그 과정에서도 결국 중요한 것은 무엇을 만들지, 왜 만들어야 하는지, 그리고 어떻게 만들어갈지를 정의하는 일이라고 생각한다.

이 책을 읽으며 AI를 사용하는 답답함이 조금씩 해소되기 시작했다. 단순히 질문을 던지는 수준을 넘어 역할을 나누고, 팀을 구성하고, 각 단계를 관리하는 방식으로 접근하니 이제는 AI 한 명이 아니라 PM도 있고, 개발자도 있고, 검증자도 있는 하나의 팀을 꾸릴 수 있겠다는 생각이 들었다.

AI와 협업하는 방법이 막연하게 느껴졌던 사람이라면, 그리고 하네스 엔지니어링의 기초를 익혀 자신만의 개발 프로세스를 만들어보고 싶은 사람이라면 이 책을 추천하고 싶다.

#한빛미디어#나는리뷰어이다#하네스엔지니어링with클로드코드