Part1. Claude Code라는 건 뭐고, 어떻게 동작하는가?

1. Claude의 멘탈 모델 : Agentic loop

Claude Code를 이애하기에 필수적인 핵심 멘탈 모델 (agentic loop = Model + Tools)

요청 사항이 들어오면 (1) 맥락을 파악하고 (2) 액션을 취하고 (3) 결과를 검증하고, “업무가 완전히 완료될 때까지” 반복하게 됨. 이러한 루프를 agentic loop 라고 표현을 함. 그리고 이 loop 과정에서 사용자는 언제든 중간에 개입을 해서 방향을 바꾸거나, 추가 컨텍스트를 줄 수 있음.

• 예를 들어서 “이 github 레포를 바탕으로 코드가 어떻게 관리되고 있어?” - 이런 질문은 맥락을 파악하는 Gather context 단계만으로 충분함
• “이 레포에서 버그를 찾아 고쳐줘” - 이런 질문은 (1) 맥락을 파악하여 버그 원인을 찾은 다음에 (2) 이를 해결할 수 있도록 코드를 수정하고 (3) 의도한 대로 잘 동작하여, 버그가 고쳐졌는지를 파악하는 세 단계를 완료할 때까지 반복해야 함
• “이 레포에서 코드 리팩토링 해줘” - 이런 질문의 경우에는 3단계를 “반복” 하고, 검증 단계(verify)가 특히 많아진다

그리고 agentic loop 를 실행하기 위해서는 (추론을 하기 위한) 모델, (실제 액션을 하기 위한) 도구가 필요하다

모델 (Model)

• 보통 “Claude chooses” 혹은 “Claude decides” 라고 표현이 되는 경우에는 “모델이 추론을 하고 있다” 라고 이해하면 됨
• Claude 에서는 Fable, Opus5, Sonnet 5 등의 모델이 있고 모델을 선택할 때에는 /model 혹은 claude --model <name> 이렇게 선택하면 됨

도구 (Tools)

• Claude가 “실행”할 수 있도록 하는 것이고, 이게 바로 “agentic” 한 특징을 만들 수 있다
• “실행”에 대한 항목으로는 .. (base capabilites)
  • 코드를 읽고 (File operations, Search)
  • 파일을 수정하고 (File operations)
  • 커맨드를 실행하고 (Execution)
  • 웹에서 직접 서치를 해보고 (Web)
  • Code intelligence : 코드를 수정하고 타입 에러나 경고를 보여주고, 정의로 점프하거나 참조를 찾아주는 기능
  • spawning subagents
  • 되묻기
  • orchestration 업무를 실행하기
• 기본 능력에서 더 확장해보면
  • skills를 이용해서 Claude에게 지식을 확장해줄 수 있고
  • MCP를 이용해서 외부 서비스와 연결할 수 있고
  • hooks를 이용해서 워크플로우를 자동화할 수 있고
  • subagents를 이용해서 작업을 위임할 수 있음
• “실행”에 대한 결과로는 다음 루프를 돌릴 때 필요한 정보를 리턴하게 됨

2. 그러면 Claude는 루프를 돌 때 무엇을 볼 수 있는가? 👀

• 프로젝트
• 터미널
• git 상태 : 현재 브랜치, 커밋되지 않은 변경 사항, 최근 커밋 기록
• CLAUDE.md : 프로젝트별 지침, 규칙, Claude가 “매 세션마다” 알아야 하는 컨텍스트를 저장한 마크다운
• 자동 메모리 : Claude가 작업을 하면서 자동으로 저장하는 학습 내용, Memory.md 파일에서 처음 200줄 또는 25KB 중 먼저 도달하는 것이 각 세션 시작 시 로드가 됨
• 확장된 외부 서비스 : MCP servers, Claude in Chrome, ..

3. Claude가 루프를 돌 때 어디에서 돌 수 있는가? (공간축) 🏠

4. Session : Claude는 여러 루프에 걸친 대화 기록을 어떻게 저장하고 이어갈까?

• 대화는 ~/.claude/projects/ 아래에 일반 텍스트 JSONL 파일에 기록이 됨
• Claude가 코드를 바꿀때마다 파일 버전 스냅샷을 찍기 때문에, 필요하면 그 때의 대화로 돌아가서 코드를 다시 살려둘 수 있음
• 세션을 새로 생성할 때에는 (1) CLAUDE.md 지침을 가져오고 (2) 자동 메모리를 통해서 세션 간에 학습을 유지할 수 있다고 함

브랜치 간 작업하기

• git worktrees를 사용하여 병렬 Claude 세션을 실행

세션 재개 또는 포크

• claude --resume 은 세션을 이어서 하는 것. claude --continue는 안 써봤는데 resume이랑 동일한건가?
• --fork-session은 보통 언제 사용하는거지?

컨텍스트 윈도우

• Claude 모델이 가진 최대 용량 (ex. Claude 3.5 Sonnet은 200K 토큰)
• 세션을 켰을 때 나오는 ctx는 현재 세션에서 사용 중인 컨텍스트 양을 보여주는 지표
• 컨텍스트를 관리하는 방법으로 압축, skills, subagents를 통해 가능하다고 함
  1. 압축 (/compact) : 전체 대화 기록을 요약하여 기록하는 방식
  2. Skills : Claude 세션을 시작할 때에는 스킬에 대한 설명은 로드되지만, 스킬을 지정하는 md 파일 자체가 로드되지 않음. 그래서 수동으로 호출하는 Skills의 경우에는 disable-model-invocation : true로 설정해서 필요할 때까지 설명을 컨텍스트 밖으로 유지해야 함
  3. Subagents : 메인 세션의 대화와 분리되어서 에이전트마다 새로운 컨텍스트를 얻게 됨

5. Claude 안전하게 사용하기 : 체크포인트 & 권한 부여

Claude가 알아서 작업을 할 때 사람의 작업을 몽땅 날려먹거나 잘못 했을 때의 불상사를 막기 위해서 안전 장치를 도입하고 있음. 그래서 버전 관리를 하고 있고, Claude가 “얼마나” 알아서 할 것인지를 사용자가 직접 제어하도록 하고 있음. 이를 각각 “체크포인트”, “권한 부여” 라고 말 하고 있음

체크포인트로 변경 취소하기

• Esc를 두 번 누르면 대화 목록들이 나와서 내가 원하는 상태로 되돌아갈 수 있음

권한 제어하기

• Auto 상태일 때에는 Claude가 안전 검사로 모든 작업을 평가하고, 필요한 것만 물어보게 됨
• Plan 상태일 때에는 Claude가 파일을 수정하지 않고 계획을 탐색하고 제안함

Part2. 그럼 Claude Code를 어떻게 잘 써야 할까?

6. Claude Code를 효과적으로 일 시키는 방법

그걸 클로드한테 물어보기

• what’s the best way to structure my CLAUDE.md?
• how do I set up hooks
• /init 으로 CLAUDE.md 를 만들 때 사용하거나, /doctor로 클로드를 사용하는 전반에 대해 진단받을 수 있음

대화하듯 이야기하기

• 꼭 완벽하게 프롬프트를 작성하지 않고 fix the login bug 이렇게 지시를 해도 된다고 함
• Esc를 클릭해서 중단하고 중간 개입을 해서 다시 디렉팅을 해도 됨
• 처음에 지시하는 프롬프트가 더 정확할수록 나중에 고쳐야 할 부분이 적다 특정 파일을 참조하고, 제약 조건을 언급하고, 예제 패턴을 지적해야 함

체크아웃 흐름이 만료된 카드를 가진 사용자에게 손상되었습니다.
문제를 찾기 위해 src/payments/를 확인하세요. 특히 토큰 새로고침.
먼저 실패하는 테스트를 작성한 다음 수정하세요.

Claude가 검증할 수 있는 것을 제공하기

• Claude가 자기가 한 일을 직접 검증할 수 있도록 도구를 쥐어주어야 함.
• 테스트 케이스를 포함하고 스크린샷을 붙여 넣거나 원하는 출력을 정의해야함
• 시각 작업을 한 경우에는 디자인 스크린샷을 붙여넣고 Claude에게 구현을 비교하도록 하는 방법도 있음

validateEmail을 구현하세요. 테스트 케이스: 'user@example.com' → true,
'invalid' → false, 'user@.com' → false. 후에 테스트를 실행하세요.

구현을 하기 전에 탐색 먼저 하기

• 복잡한 일의 경우에는 plan mode를 이용해서 코딩 작업을 하기 전에 리서치 먼저 시키기
• 계획을 검토 -> 대화를 통해서 계획을 개선 -> 구현

src/auth/를 읽고 세션을 처리하는 방법을 이해하세요.
그런 다음 OAuth 지원 추가를 위한 계획을 생성하세요.

지시하기 말고 위임하기

• 읽을 파일이나 실행할 명령을 지정할 필요 없이 Claude가 알아서 파악하도록
• 능력있는 동료에게 일을 맡기는 것처럼

체크아웃 흐름이 만료된 카드를 가진 사용자에게 손상되었습니다.
관련 코드는 src/payments/에 있습니다. 조사하고 수정할 수 있나요?

Part3. 문서를 읽으면서 내가 생각한 것들

• 사람들이 “agentic coding, agentic builder, .. ” 이렇게 agentic 이라는 표현을 사용하는데, 그 정의는 무엇인가? -> 스스로 판단을 하고, 계획을 하고, 실행을 하는 형태의 AI를 agentic AI 라고 부름 (하나의 테스크를 end-to-end 업무 처리, “자발성” 이 특징)
• 그러면 이제까지 나의 개발 과정은 과연 agentic 한가?도 돌아볼 수 있을 것 같음.
  • claude가 명시하는 테스트 케이스들에 대해서 신뢰하는가?
  • claude가 개발한 기능 단위의 PR이 끝나고나서 이후에 버그 픽스 등을 얼마나 붙이고 있는가?
  • 하나의 세션에서 Claude에게 얼마나 지시하고, 중간에 얼마나 개입을 하는가?
• 세션을 시작할 때 “/model” 커맨드를 입력하여 모델을 변경하는데, 새로운 세션을 열 때에는 default 모델이 이전에 사용했던 모델임. 그래서 의도하지 못하고 단순한 작업인데 Fable로 돌리게 되면 너무 아까웠던 때가 있었음. 테스크에 따라서 자동으로 모델을 설정할 수 있는 기능은 없나?
• CLAUDE.md 또는 Memory.md의 200줄이 처음 세션을 생성할 때 자동으로 로드됨 -> 그러면 세션 내의 토큰을 최대한 줄이기 위해서 이 둘의 파일이 최대한 가벼워야 하는게 아닌가? (매 세션별로 사용하는 토큰의 수라던지, 토큰을 절약하기 위해 필요한 건 뭐가 더 있을까?)
• 클로드한테 진단받기 -> /doctor 로 새 모델이 나올 때마다 세팅을 초기화한다는 이야기가 있었는데 찾아보고 적용해보기
• 검증할 수 있는 방법에 대한 고민 - 테스트 케이스를 어떻게 작성해야 하고, Claude가 구현을 잘 했다라는 것을 한 번에 검증할 수 있게 하려면 어떻게 해야 할까?
• 공식 문서에서 말하는 지시하는 것 vs 위임하는 것 차이는?
• 자동 메모리를 사용하고 있다고 하는데, 매 번 작업을 할 때마다 워크트리를 생성해서 작업하라고 명령하게 되면 -> 이것도 메모리에 자동으로 적용이 되는걸까?