[독서노트] 클로드 코드 제대로 시작하기

지은이 주홍철, 황진성

출판 (주)도서출판 길벗

발행 2026.8.5

 

 이제는 프로그래밍을 해보지 않은 비개발자인 일반 사람들도 바이브코딩하면 클로드 코드를 사용하는 시대가 되었다. 본인도 작년 이맘때와 비교해보면 인텔리 제이 같은 통합 IDE 안에서 깃허브 코파일럿 같은 코드 추천 기능에도 만족하다가 LLM 모델들이 점점 성능이 좋아지면서 채팅이나 프롬프트로 코드를 생성해보면서 신기해했지만 아직 완성도는 멀었구나 싶었다. 그러다가 커서같은 툴이 나오면서 프롬프트만 입력해서 내가 잘 모르는 게임엔진에서도 바로 게임하나가 만들어지고 디버깅도 다 해주는 것을 보고 편한 시대가 되었구나 생각했다. 그렇게 AI 와 공존하는 환경이 되어 가고 있었는데 그래도 마음으로는 개발 마무리는 사람이 해야지라는 자존심만 가지고 있었다.  그런데 올초에 회사에서 적극적으로 클로드 코드를 지원해주기 시작해서 사용하고 나서부터는직접 코딩하는 횟수가 날이 갈수록 적어지고 있다. 코드 품질도 내가 작성한거 보다 훨씬 낫고 잘 모르는 레거시 코드 분석도 빨라져서 레거시 프로젝트 운영중에 문제가 생겨도 예전같은 이전 코드 분석하고 확인하는데만 반나절 걸렸을텐데, 클로드 코드를 믿고 바로 수정/배포를 진행할 수 있는 상황이 되었다. 이제는 클로드 코드 없던 시절도 다시 돌아갈 수 있을까 싶은 AI 종속 시대에 살고 있는게 아닌가하는게 요새 드는 생각이다.

 클로드 코드와 매일 채팅하면서 프롬프터 입력하고 결과를 기다리면서 작업하는 방식이 과연 맞는걸까? (AI 로 작업하는 방식에 대한 회의가 아니라) 그냥 머 해줘, 이거 고쳐줘 라는 식으로 해서 작업 진행을 하다보니 한참 대화하면서 시간이 흘러보면  원래 하려고 했던 방향이 아닌거 같은데 하면서 새로 세션을 열어서 채팅을 다시 진행하면서 결국은 해결하지만 먼가 이런 방식이 아닌거 같다는 느낌이 들때가 있다. chatGPT 나 제미나이로 채팅 질문하듯이 문제점 해결을 하니보니 생긴 나쁜 습관인데 바로 이책이 그러한 문제점을 해결해주는 내용으로 되어 있어서 책을 읽는 내내 감탄하고 있다) 

---

 이책은 크게 2개로 구분이 되는게 앞부분은 일반인들이 쉽게 따라할 수 있는 바이브 코딩으로 실제 앱을 만들며서 온라인 배포까지 진행한다.

 클로드 코드 가입 방법, 자주 사용되는 슬래시 명령어 설명으로 시작해서 실습 프로젝트로 자기 소개 페이지를 제작하면서 CLAUDE.md, PRD.md 가 왜 필요한지 설명하며 깃허브에 클로드 코드로 생성한 소스를 push 하고 Vercel, mongoDB 서비스를 사용하기 위해 하나씩 캡쳐와 함께 상세히 설명한다. OMC(오 마이 클로드코드) 를 사용해서 작업의 효율과 결과물 품질을 올리는 방법을 소개하고 플랜모드를 사용해서 TODO 앱을 제작하는 과정을 설명한다. 숏폼 제작을 위해 ElevenLabs  API 를 통해 오디오를 생성하는 방법과 함께 docs/ 폴더에 여러 설정 파일(AGENTS.md, architecture.md, PRD.md, commit.md, memory.md) 을 이용해서 숏폼 생성하는 프로그램을 제작한다. 이 short2MD 을 이용해서 생성된 동영상을 미세조정하는 방법으로 동영상을 완성한다. 디스코드 봇을 로컬 PC 의 클로드 코드와 연동해서 모바일에서 채팅으로 PC 의 클로드 코드에게 명령어를 전달하는 예제도 설명한다.

 (OMC 는 나도 이번에 처음 들어보는 거였지만 포함된 기능 랄프 모드를 이용하면 맨처음 수립한 계획으로 코딩을 한번의 사용자 개입없이 완성할 수 있게 된다. 이렇게 AI 에이전트만 오케이스트레이션하는 해커톤 대회도 있다고 한다.)

 

 뒷부분은 클로드 코드를 사용해본 개발자들을 위한 설명들로 프롬프트 엔지니어링, 컨택스트 엔지니어링, 클로드 코드 심화(settings.json, 도구, Hooks, Skiils, Custom Agents, MCP, 동적 워크플로 오케스트레이션, SSD (스펙 주도 개발), 하네스 엔지니어링 으로 내용이 이어진다. 각 항목마다 실제 예제가 있어서 이해하기 쉽게 구성되어 있다.

 

 프롬프트 엔지니어링 : 좋은 프롬프트는 모델이 오해 없이 일관되게 작업을 수행할 수 있도록 구조를 명확히 정의한 프롬프트이다.

- 역할(Role), 지시(Instruction), 입력데이터(Input Data), 배경 정보(Context), 출력 형식(Output Format), 예시(Example). 보통은 역할, 지시, 입력 데이터만으로도 충분하다. 섹션마커는 [역할] 대신 [Role] 처럼 영문으로 쓰는 것이 관행이다.

- 프롬프트챗(https://github.com/f/prompts.chat) : 프롬프트를 탐색하고 복사할 수 있는 오픈소스 라이브리리. 디자인 프롬프트. 이미지 생성 프롬프트.

 

컨텍스트 엔지니어링 : 에이전트가 도구를 호출하고 여러 번의 대화를 이어 가면서 입력에 들어가는 내용이 이제는 시스템 프롬프트, 도구 정의와 호출 결과, 이전 대화 기록, 외부 문서까지 불어난 입력을 설계하는 일. 하나의 텍스트 덩어리로 토큰 열안에 들어가기 때문에 그 텍스트에 무엇을 담아 건네느냐가 조립하는 기술이다.

- 시스템 프롬프트 : 컨택스트 윈도우의 가장 앞자리 차지. 사용자의 매 요청마다 가장 먼저 처리된다. CLAUDE.md 이 자동로드된다.

- 도구 실행 결과 : 에이전트가 도구를 호출하면 읽은 내용, 실행한 명령의 출력, 검색한 결과가 컨텍스트에 남아 다음 추론의 재료가 된다.

- 검색된 지식 : (책 내용에 해당하는 부분이 없다!)

- 외부 문서 : 외부 파일을 직접 전달 또는 파일에서 마크다운만 추출해서 에이전틱 검색에 맡기던지 또는 RAG 파이프라인 구축

 

클로드 코드 심화

- CLAUDE.md : 모든 프로젝트에 적용되는 사용자 CLAUDE.md(~/.claude/CLAUDE.md), 팀이 공유하는 프로젝트 CLAUDE.md(./ CLAUDE.md or ./claude/CLAUDE.md), 나에게만 적용된 로컬 오버라이드(./CLAUDE.local.md) 는 덮어쓰지 않고 모든 위치의 내용을 합쳐서 컨택스트에 올린다. 현재 작업 디렉토리에서 위쪽으로 올라가며 발견되는 CLAUDE.md 파일을 세션 시작시 로딩한다. 하위 디렉토리의 CLAUDE.md 는 클로드 코드가 해당 디렉토리를 읽는 그 시점에 로딩한다(지연로딩)

- 잘 쓰는 법 : 200줄 이하로 유지한다. 추상적인 표현이 아닌 구체적으로 작성한다. 충돌하는 규칙을 만들지 않는다. 마크다운 구조로 쓴다(제목(##), 블릿(-), 코드 블록으로 구조화하는게 효과적이다. 그리고 덜 써야한다. ETH 취리히와 LogicStar.ai 연구진이 발표한 논문에서 벤치마크를 다음 조건으로 비교했을때 "1.컨택스트 파일 없음", "2. AI 가 자동생성한 파일(/init)", "3. 사람이 직접 작성한 파일" 중에서 2번 AI 가 자동 생성한 파일이 파일없는 경우보다  작업 성공률이 -5% 하락하고 추론 비용이 20% 이상 증가했다. 물론 3번 직접 작성한 파일로 했을때는 작업 성공률은 4% 상승하고 추론 비용은 증가했다.

(이 논문 부분에서 충격을 받았는데, 레거시 프로젝트에서 CLAUDE.md 파일 생성을 위해 매번 /init 로 작성해왔었다. 습관을 바꿔야겠더라.)

- settings.json : permissions(허용과 차단), env(환경 변수 주입), hooks(이벤트 기반 자동화)

- tools : 클로드 코드에서 30개 이상의 내장 도구를 제공한다.

- hooks : 결정론적(deterministic) 제어를 위해 필요. LLM 은 토큰을 확률적으로 생성하지만 훅은 LLM 의 판단을 거치지 않고 정해진 코드를 그대로 실행. 같은 조건이면 언제나 같은 결과.

- skills : 반복 워크플로를 SKILL.md 파일에 담아서 슬래시 명령어로 실행 가능.

- Custom Agents : 스킬이 "무엇을 해라"는 레시피를 정의한다면 서브에이전트는 "누가 할것인지"를 정의한다.

자체 컨택스트 윈도우에서 독립적으로 작업하는 전문 AI 에이전트를 서브 에이전트라고 하는데, 각 에이전트는 "자체 시스템 프롬프트", "자체 도구 접근 권한", "독립된 컨택스트", "결과 반환" 을 독립적으로 가진다. .claude/agents/<name>.md 처럼 파일을 구성하고 /agents 명령어로 에이 전트를 관리한다.

- MCP : 클로드 코드가 외부 시스템까지 직접 다룰 수 있게 해주는 연결 표준.

-- mcp 서버 추가 방식 : HTTP 방식 (클라우드 호스팅 서비스 연결), STDIO 방식 (내 컴퓨터에서 로컬 프로세스로 실행) 

 

 SSD : 에이전트는 스펙을 계약처럼 따르며 결과물 또한 스펙을 기준으로 검증받는다. 요구 사항의 동작 방식, 제약 조건, 검증 기준을 명확하게 정의하고 PRD 에 담긴 의도를 실행 가능한 형태로 구체화하여 코드 생성을 주도한다.

- 같은 프롬프트, 다른 결과 : "로그인 만들어줘" 프롬프트를 클로드 코드에 각각 3번 입력해보면 서로 다르게 구현하는 것을 볼 수 있다. 모호한 프롬프트로 만들어진 코드는 보기에는 맞는거 같지만 정확히 동작하지 않는다(것허브)

- 스펙은 프롬프트가 아니라 계약이다. 구조화된 프롬프트라고 이해하자.

-- 영속성. specs/login.md 같은 파일로 영속되면 한달 뒤 그 코드를 다시 만질때 한 달전의 의도를 읽을 수 있다.

-- 계약성. 개발자의 기억이나 채팅 로그가 아니라 저장소 안의 스펙 문서에 있다.

-- 재현성. 명시한 항목이 고정되어 있어서 같은 입력으로 같은 결과을 얻을 가능성이 크다.

-- SDD 도구 : GSD Redux, OpenSpec, GitHub Spec Kit

 

 하네스 엔지니어링 : 장기 작업을 진행하는 AI 에이전트의 상태, 메모리, 실행 흐름을 관리하는 시스템. OMC, 우로보로스, OMX 같은 오픈 소스가 있다. 에이전트의 역할 분리와 장기 작업이 가능하도록 만드는 마크다운 기반 구조이다.

- Planner - Generator - Evaluator 의 멀티 에이전트 구조로 진행한다.

 (주식 분석 리포트를 생성하는 하네스를 제작하고 이미 작성한 하네스 내용을 설명하는데 느낌상 내용이 급하게 마무리된 느낌이다. 하네스 관련된 내용이 더 많이 할당이 되었어야 할듯한데  조금 아쉽다)

 

 마지막 문구가 기억에 남는데, 앞으로는 AI 가 더 쉽게 일하는 있는 환경을 만들어주기 위해 필요한 기술들을 배워야 한다고 본다. 

과거의 시대는 사람의 시선을 설계하는 시대였다면 AX의 시대는 에이전트의 작업 흐름을 설계하는 시대입니다.