학습 목표(Achievement Goals)

1. 에이전트 루프 이해

   • 컨텍스트 수집, 작업 수행, 결과 검증의 3단계 과정

2. 내장 도구 이해

   • 파일 작업, 검색, 실행, 웹, 코드 인텔리전스 5가지 범주

3. Claude Code가 프로젝트와 상호작용하는 방식 이해

   • 프로젝트 파일, 터미널, git 상태, CLAUDE.md, 자동 메모리 등에 대한 접근

4. 세션 관리

   • 세션 재개, 포크, 컨텍스트 윈도우 관리 방법

5. 안전 메커니즘

   • 체크포인트와 권한 시스템 이해

6. 효과적인 사용법

   • 대화형 접근, 구체적인 프롬프트 작성, 위임 방식

세션으로 작업

세션이란?

세션은 Claude Code와의 작업 단위이다. 한 번의 대화에서 주고받은 모든 메시지, 도구 사용, 결과가 로컬에 저장된다. 이를 통해 되돌리기, 재개, 포크가 가능하다.

• 되돌리기 : 이전 상태로 복구 (코드 바꾸기 전에 스냅샷을 찍기 때문에 가능)

• 재개 : 중단한 작업 시작

• 포크 : 특정 지점에서 새로운 분기 생성

각 세션은 독립적이기 때문에 이전 대화 기록이 없다. 그렇기에, 중요한 것은 CLAUDE.md 파일에 지속적으로 백업을 해 준다면 다음 세션에도 참고가 가능하다.

단, 중요하다고 판단이 되는 것은 Claude가 알아서 자동 메모리로 저장해 놓는다.

브랜치 간 작업

세션은 디렉토리에 묶여 있다. 폴더 구조가 아래와 같다고 가정하면,

📁 my-project/      ← 여기서 Claude Code 실행
📁 other-project/   ← 다른 폴더

my-project 폴더에서 작업했을 경우 해당 대화 세션은 my-project와 묶인다. 재개할 때도 마찬가지로, 해당 폴더의 세션만 표시된다.

또한 Claude는 현재 브랜치의 파일을 본다. 이 말은, 브랜치를 전환하게 되면 새로운 브랜치의 파일을 보게 되지만 대화 기록은 동일하게 유지된다는 것이다. 그렇기에 작업 시 내가 어떤 폴더에서, 어떤 브랜치로 작업하고 있었는지 파악하는 게 중요하다.

여기에서 조금 아리까리했다. 세션이 어디에서 저장이 되지?

> 홈 디렉토리의 .claude 내에 project 별로 .jsonl 파일로 저장된다.

그렇다면 각각의 세션 목록이 있다는 건데, 세션 목록은 어디에서 보는 걸까.

> 대화 중에 확인하기는 /session 명령어 입력으로, 혹은 터미널에서 claude --list

세션 ID와 마지막 미리보기가 뜨는데, 특정 세션을 재개하려면 claude --resume <session-id> 사용하면 된다.

(물론 resume 아니고 continue여도 됨.)

세션이 디렉토리에 연결되어 있기 때문에, git worktrees를 사용하면 병렬로 Claude 세션을 실행할 수 있고, 또한 개별 브랜치에 대해서도 별도 디렉토리를 생성한다.

세션 재개 또는 포크

세션을 재개하고 싶다면...

• claude --continue(가장 최근 세션 이어가기)

• claude --resume(선택해서 이어가기)로 가능하다.

세션을 더럽히고 싶지 않지만 다른 접근 방식을 시도하고 싶을 경우에는...

• --fork-session

이 경우, 대화 내용을 유지하면서 새 세션 ID를 생성하게 된다.

fork, 대체 언제 사용하는 거야? 예시

1) 여러 터미널에서 사용하고 싶을 때.

하나의 파일에 대해 파일 구조도 알고 싶고, 버그도 수정하고 싶을 경우. 같은 세션 안에서 두 개의 질문을 다른 터미널에서 했을 경우 인터리브(interleave: 끼워넣기, 번갈아 섞이기)가 되어 대화가 뒤섞인다. 각각의 터미널은 당장이야 본인의 메시지만 보겠지만 나중에 해당 세션을 재개하면 복잡도가 높아질 수 있다.

2) A도 해 보고 싶고 B도 해 보고 싶을 때.

하나의 결정보다는 두 가지 경우의 수를 띄우고 싶을 때. 같은 맥락 방식에서 여러 가지 방향을 시도해 볼 수 있다.

하지만 이건 모두 세션을 새로 열면 되는 것 아닌가? 한다면 그렇다에 동의한다. 다만, CLAUDE.md나 기본적인 문서가 부실하고, 맥락에 대해 해당 세션만 인지하고 있을 경우(어떤 태스크 작업을 하다가 나온 일시적 주제일 경우 같음) fork를 사용해 볼 수 있다.

다만 이 세션을 소중하게 다루기에 fork를 사용한다, 이것보다는 한정적으로 유용하게 사용이 가능하다. 어차피 컨텍스트는 너무 빨리 차 버리고, /compact에 대한 신뢰가 아직 두텁지 않다고 느끼며, CLAUDE.md가 잘 구성되어 있다면 새로운 세션에서 새롭게 시작하는 법도 나쁘지 않기 때문.......

컨텍스트 윈도우

Claude Code는 한 번에 기억할 수 있는 용량이 정해져 있다. 컨텍스트 윈도우는 Claude의 단기 기억이라고 할 수 있다.

Claude Code를 통해 작업을 하면 할수록 아래의 것들이 쌓이게 된다. 컨텍스트가 채워진다는 것.

• 지금까지 나눈 대화

• 읽은 파일 내용

• 명령어 실행 결과

• CLAUDE.md

• 시스템 지침, 스킬 등

컨텍스트가 채워질 때

한 세션에서 컨텍스트가 꽉 차게 되면 Claude는 알아서 정리를 하게 된다.

1. 오래된 도구 출력(파일 내용, 명령어 결과) 손실한다.

   • (*대화의 자세한 초반 지침 손실 가능성 있음)

2. 그래도 꽉 찬다면 대화 요약 압축

초반에 했던 지시 사항이 휘발될 수 있기 때문에, 만약 중요한 규칙이었다면 꼭 CLAUDE.md 등에 문서화를 해야 한다.

결국 컨텍스트가 채워진다는 건 압축(compact)이 필수불가결하게 들어가야 한다는 말씀.

100%를 사용하여 대화 요약을 자동적으로 압축당하든지, 수동으로 제어해 압축을 스스로 하든지, 이외에도 컨텍스트 관리에 힘쓰든지 하는 방식을 통해 세션 내 기억 유지에 힘써야 한다.

컨텍스트와 유용한 명령어

• /compact

  • 수동으로 대화를 압축시킬 수 있다.

• /compact focus on the API changes

  • API 관련 내용 위주로 살리고 나머지는 압축한다. (압축 중 보존되는 것을 제어함)

• /context

  • 컨텍스트를 뭐가 얼마나 차지하고 있는지 보여 준다.

• /mcp

  • 연결된 MCP 서버들이 컨텍스트를 얼마나 먹고 있는지 확인한다.

Skills과 Subagents로 컨텍스트를 관리하자

압축 이외에도 컨텍스트에 불필요하게 로드되는 것을 제어할 수 있다. 스킬과 서브에이전트를 사용하는 것이다.

skills는 간단하게 프롬프트 매뉴얼이라고 보면 좋다. 요청에 의해서 로드가 된다. 물론 Claude는 Skills이 있다는 건 안다. 즉, 설명만 미리 보고, 실제 내용은 필요할 때만 로드된다는 것. 자동으로 호출되는 스킬 말고 수동으로만 불어올 스킬이라면 disable-model-invocation: true를 설정하여 설명조차 올리지 않아도 된다. 컨텍스트에서 완전히 분리한다.

subagents는 별도 공간에서 일하는 부하 직원이라고 생각하자. 완전히 컨텍스트를 분리하여 본인만의 별도의 컨텍스트를 가지게 된다. 서브에이전트의 작업은 컨텍스트를 키우지도 않는다. 작업이 끝나면 결과 요약만 돌려 준다. 긴 호흡의 세션에서 subagents가 도움이 많이 된다.

체크포인트 및 권한으로 안전 유지

Claude는 파일 변경을 취소할 수 있고, 요청 없는 변경에 대해 허락을 구하게 할 수 있다.

체크포인트로 변경을 취소함

Claude는 파일을 편집하기 전에 자동으로 스냅샷을 찍고, 그것을 체크포인트라고 한다. 문제가 발생하거나 되돌리고 싶을 때는 Esc를 두 번 눌러 이전 상태로 되돌릴 수 있으며, 직접 요청할 수도 있다. 그렇기에, Claude는 결국 모든 파일의 편집은 되돌릴 수 있다.

이 체크포인트(스냅샷)은 Claude가 내부적으로 관리하는 복원 지점이다.

[체크포인트 1] 원본 상태
    ↓
Claude가 파일 A 수정
    ↓
[체크포인트 2] 파일 A 수정된 상태
    ↓
Claude가 파일 B도 수정
    ↓
[체크포인트 3] 파일 A, B 둘 다 수정된 상태

다만, 원격 시스템에 영향을 주는 작업은 체크 포인트가 불가하다. (DB, API, 배포)

변경에 대한 제어

권한은 3가지 모드가 있다. Shift+Tab을 눌러 권한을 바꿀 수 있다.

• 기본값: 파일 편집, 셸 명령 전 요청

• 자동 수락 편집: 파일 편집은 자동으로, 명령은 여전히 요청

• 계획 모드: 읽기 전용 모드만 사용하여 계획을 생성함

.claude/settings.json에서 특정 명령을 허용하여 매번 요청하지 않게 할 수 있다.

Claude Code를 효과적으로 사용

1. Claude Code에게 물어보라.

> hooks 설정 어떻게 해염?

> CLAUDE.md를 구조화하는 최선의 방법은 뭐예염?

2. 내장 명령을 사용하라.

• /init : 프로젝트를 위한 CLAUDE.md 생성 안내

• /agents: 사용자 정의 subagents 구성

• /doctor: 설치의 일반적인 문제 진단

3. 대화하라.

Claude Code는 대화형이기 때문에 완벽한 프롬프트가 필요가지 않다. 원하는 것으로 시작한 다음 개선하면 된다. 언제든지 Claude를 중단할 수 있고, 잘못된 경로라면 수정 사항 입력 후 Enter 누르면 된다. 알아서 입력된 걸 바탕으로 접근 방식을 조정한다. 다 끝날 때까지 기다리거나, 다시 시작할 필요가 없다.

4. 처음부터 구체적으로 말해라.

초기 프롬프트가 정확할수록 필요한 수정이 적다. 모호한 프롬프트보다 구체적인 프롬프트가 더 시간이 짧게 걸린다.

• 특정 파일 참조

• 제약 조건 언급

• 예제 패턴 지적

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

5. Cladue에게 검증할 수 있는 기회를 제공하라.

자신의 작업을 확인할 수 있을 때 더욱 잘 수행하기 때문에, 테스트 케이스를 포함하거나 예상 UI의 스크린샷을 붙이거나, 원하는 출력을 정의하면 좋다.

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

6. 구현 전에 탐색하라.

복잡한 문제의 경우 연구와 코딩을 분리한다. 코드 베이스 분석 후 구현하는 2단계 접근 방식은 코드로 바로 뛰어드는 것보다 더 나은 결과를 생성한다.

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

7. 지시하지 말고 위임하라

능력있는 동료에게 위임하는 것처럼 생각해야 한다. 컨텍스트와 방향을 제공한 다음, Claude가 세부 사항을 파악하도록 신뢰한다. 이게 가장 중요한 것 같다.

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