클로드 코드 잘 사용하기

2026-04-16
session
'클로드 코드 잘 사용하기' 세미나 자료를 읽고

김영동 님이 링크드인에 올려주신 ‘클로드 코드 잘 사용하기’ 세미나 자료를 읽고 인상적이었던 것과 배운 것을 정리함

Section 1

추상화의 역사 -> (대공감)

기계어에서 고급언어로 추상화

메모리를 직접 다루던 C에서 언어 차원에서 가비지 컬렉션을 제공하는 Java로 추상화

일일이 필요한 기능을 구현하던 것에서 외부 라이브러리를 적극적으로 사용하는 Python으로 추상화

직접 구현하는 것에서 ‘이 함수를 리팩토링하고 테스트 코드를 작성해줘’로 추상화

개발자의 능력의 정의가 변하고 있다

코드를 잘 짜는 능력 → 문서를 잘 쓰는 능력 → 컨텍스트를 설계하는 능력

역설적으로 중요해진 능력 ➡️ 기초 지식

보안이나 동시 접속 이슈, DB 스키마 등의 지식을 갖고 있어야 질문을 할 수 있다. 뭘 모르는지를 알아야 한다.

Section 2

AI 코딩 도구의 진화

[자동완성] : 초기 코파일럿. 반복 작업에 유용했음 
↓
[대화형] : GUI 사용. 코드나 문맥을 복붙해야 했음
↓
[에이전틱] : 지금 여기. 전체 코드베이스를 이해하고 작업

Claude Code, Codex

아래 루프를 작업이 완료될 때 까지 반복한다.

  1. 작업에 필요한 Context 수집
  2. 작업
  3. 결과 검증

Claude Code

확장 레이어 구조 ➡️ 필요에 따라 확장해나간다.

[기초] : CLAUDE.md 
↓
[자동화] : skills, hooks
↓
[연결] : MCP
↓
[확장] : SubAgent, Agent teams, Plugins

실무에 사용 가능한 이유

생태계가 빠르게 발전해나가는 중 (ex.awesome-claude-code)

문제가 생겼을 때 검색해서 해결할 수 있는 것이 실무에 적용하기 위한 중요 조건 중 하나. 나 혼자 쓰게 된다면 리스크가 크다.

Section 3

TDD

  1. 인간이 테스트 코드를 작성한다.
  2. AI가 그 테스트 코드에 맞추도록 구현한다.
  3. 인간이 리뷰한다
  4. AI가 리뷰한다.

AI가 테스트 코드를 수정하거나, 건너뛰지 않도록 제약을 걸어야 한다.

SDD

  1. 인간이 스펙을 정의한다.
  2. AI가 그 스펙을 구현하기 위한 plan을 제안한다.
  3. 인간이 승인한다
  4. AI가 plan을 task 단위로 쪼개서 병렬로 수행한다.

AI가 작업할 때 모호한 부분은 [NEED CLARIFICATION] 마커를 찍고 구현을 중단하도록 제약을 걸어야 한다

SDD + TDD

SDD와 TDD를 함께 사용하는게 이상적인 개발 방법론

SDD는 신규 기능을 추가하거나 대규모 설계를 해야 할 때 최적 TDD는 기존 코드를 수정해야 할 때 최적이다.

Section 4

엔지니어링의 진화

[프롬프트 엔지니어링] : 무엇을 말할 것인가
↓
[컨텍스트 엔지니어링] : 무엇을 보여줄 것인가
↓
[하네스 엔지니어링] : 무엇을 구축할 것인가

프롬프트로 부족한 이유 : 같은 프롬프트를 써도 같은 결과물이 안나옴

하네스 엔지니어링

하네스 ➡️ 날뛰는 말(LLM)을 올바른 길로 이끈다.

프롬프트만으로는 LLM이 항상 균일한 결과를 내지 않기 때문에

  • 읽고 보는 것을 정의하고 (context)
  • 뭘 할 수 있는지 제한하고 (도구, 권한)
  • 언제 멈춰야 하는지 정의하고 (제약)
  • 잘못되었을 때 어떻게 해야 하는지 정의 (복구)

6대 구성요소

  1. 컨텍스트 엔지니어링
  2. 도구 오케스트레이션
  3. 상태와 메모리
  4. 검증 루프
  5. 오류 복구
  6. 인간 개입 제거

에이전트 루프의 4단계

  1. Context 수집
  2. Action 수행
  3. 작업 검증
  4. 결과를 다음 루프 컨텍스트로

이 각 단계를 신뢰성 있게 만드는 작업이 하네스 엔지니어링!

지시문의 고도화

너무 낮아도, 너무 높아도 안된다.

올바른 고도 공식 : 원칙 1줄, 이유 1줄, 예시 1~2개

새로운 상황에서도 일반화가 가능하도록

CLAUDE.md

CLAUDE.md는 계속 업데이트해야 하는 문서

이 안에는 지시가 아닌 context를 검증 가능하고 구체적으로 담는다.

- 페이지 규격
- 종결 어미는 명사로
- 금지: -합니다 같은 공손체
- 디자인 토큰 : bg=#faf8f5

짧을수록 좋다. 문서가 비대해지면 모듈화를 한다.

plugin

CLAUDE.md를 포함해서 skills, hooks, subagent같은 하네스를 plugin으로 묶어서 팀의 자산으로 만들 수 있다.

Plan-Critic-Build

에이전트는 계획 없이 바로 코드를 작성해서 문제가 생긴다. => 계획 단계를 쓰기 권한 없는 모드로 분리해서 쓰게 한다.

  1. plan : 읽기만 가능한 모드에서 검색과 질문만 하게 한다. => 계획 문서 산출
  2. critic : 리뷰 전용 에이전트 - 사용자가 보지 못한 곳을 짚는 목적
  3. build : 승인된 계획 링크만 컨텍스트로 제공받는다. 쓰기 권한을 갖고 있음

planner와 critic을 같은 컨텍스트에 두지 않는다. 자가비평하면 blind spot이 여전히 남아 있음

암묵지를 파일로 뽑아내기

리뷰로 수정했거나, 버그를 겪고 수정하던 것들을 파일로 추출한다. => 같은 실수를 반복하지 않는다.

결정의 이유까지 함께 남긴다 => 여러 상황에서도 활용할 수 있게 일반화가 된다.

Section 5

실패 패턴 5가지

  1. 컨텍스트 과부하
  2. 불명확한 요구사항
  3. 검증 없는 자동 수락
  4. 긴 세션 드리프트
  5. 권한 과다

그래도 여전히 기초가 중요하다

AI가 자신감 있게 틀린 코드 제시 - 틀린게 틀린건줄은 알아야 한다.

추상화 수준만 올라갔을 뿐 문제 해결, 시스템 사고, 디버깅은 인간의 영역

Section 6

Subagent vs Agent Team

  • Subagent : 격리. 주 컨텍스트가 일을 시키면 독립적인 컨텍스트에서 작업하고 summery만 전달한다.
  • Agent Team : 같이 토론하고 합의한다. 3명까지는 이득이지만 더 많으면 대기 시간이 길어진다.

Section 7

실전 세팅 - 다중 세션 병렬

cmux + Git worktree

  • 창 1 : 메인 작업 - 현재 이슈를 구현하고 수정, 핵심 컨텍스트 보호
  • 창 2 : 조사와 탐색 - 코드베이스를 탐색하고 문서 검색. Explore 서브에이전트 활용
  • 창 3 : 감시 - 테스트와 빌드 로그 실시간 확인, 알림 수신
  • 창 4 : 이슈와 PR - 이슈 확인, PR 생성, git 상태와 브랜치 관리

Git worktree를 이용해서 창마다 독립 작업 디렉토리를 만든다.

Appendix

레퍼런스 : GitHub - Youngdong2/claude-seminar-references: 클로드코드 잘 사용하기 — 전사 세미나 참고 자료 모음 · GitHub