[Claude] 플랜 모드로 설계하고 에이전틱 루프로 구현하기

---

단순히 질문에 답하는 챗봇의 시대를 지나, 이제는 코드를 직접 수정하고 터미널 명령을 실행하는 '에이전틱(Agentic)' AI의 시대가 왔다. 그 중심에 있는 Claude Code는 사용자의 파일을 읽고, 복잡한 문제를 스스로 계획하여 구현까지 마치는 능동적인 개발 환경을 제공한다.

하지만 이러한 강력한 권한 뒤에는 '컨텍스트 윈도우'라는 명확한 자원 제한과 보안이라는 숙제가 따라온다. 단순히 도구를 실행하는 것을 넘어, 어떻게 하면 AI가 내 의도를 정확히 파악하게 할지, 그리고 안전하게 로컬 환경을 제어하게 할지 고민하며 공부한 내용을 상세히 정리해 보았다.

 

1.  주요 특징 및 핵심 로직: 에이전틱 루프

Claude Code는 스스로 계획을 세우고 실행하는 '에이전틱 루프'를 통해 작동한다. 무작정 코딩을 시키기보다 다음의 4단계 워크플로우를 따를 때 가장 안정적인 결과를 얻을 수 있다.

• 탐색(Explore): Plan Mode에서 파일을 읽고 구조를 파악한다. 이 단계에서는 코드를 수정하지 않아 안전하다.
• 계획(Plan): 상세한 구현 계획을 세우게 한 뒤, Ctrl+G를 눌러 텍스트 편집기에서 직접 내용을 검토하고 수정한다.
• 구현(Implement): Normal Mode로 돌아와 실제 코드를 작성하고 테스트를 실행하며 작업을 검증한다.
• 커밋(Commit): 작업이 완료되면 설명이 포함된 커밋 메시지와 PR 생성을 요청하여 마무리한다.

 

2. 플랜 모드(Plan Mode): 설계와 탐색의 핵심

플랜 모드는 Claude Code가 코드를 직접 수정하기 전, 문제의 본질을 파악하고 실행 전략을 수립하는 '사고 중심'의 모드다.

왜 플랜 모드를 사용해야 하는가?

무작정 코딩을 시작하면 Claude가 잘못된 문제를 해결하거나 예상치 못한 사이드 이펙트를 발생시킬 수 있다. 플랜 모드를 사용하면 탐색과 실행을 분리하여 시행착오를 줄일 수 있다.

플랜 모드의 주요 메커니즘

• 읽기 전용 탐색: 플랜 모드에서 Claude는 파일을 읽고 분석하며 답변할 뿐, 파일을 쓰거나 명령을 실행하여 시스템을 변경하지 않는다.
• 인터랙티브 계획 수립: 사용자가 "OAuth 기능을 추가해줘"라고 요청하면, Claude는 변경이 필요한 파일 목록과 세션 흐름을 포함한 구체적인 계획안을 제시한다.
• 직접 편집과 피드백: 생성된 계획은 Ctrl+G 단축키를 통해 기본 텍스트 편집기(Vim, VS Code 등)에서 열어 직접 수정하거나 보완할 수 있다. 사용자가 이 계획을 최종 수락(Accept)해야만 비로소 구현 단계로 넘어간다.
• 지능형 제안: 플랜 모드에서는 대화 기록이나 Git 히스토리를 기반으로 다음 단계에 대한 자연스러운 제안이 나타나 워크플로우를 가속화한다.

언제 플랜 모드를 생략해도 될까?

모든 작업에 계획이 필요한 것은 아니다.

• 생략 가능: 오타 수정, 로그 라인 추가, 변수명 변경 등 변경 범위가 명확하고 한 문장으로 설명 가능한 간단한 작업.
• 권장: 접근 방식이 불확실할 때, 여러 파일을 동시에 수정해야 할 때, 혹은 처음 접하는 코드베이스를 다룰 때.

 

3. 상세 가이드: 단축키 및 고급 명령어 백과사전

실전에서 생산성을 결정짓는 핵심 단축키와 명령어들을 세부 기능별로 정리했다.

⌨️ 입력 및 대화 제어

단축키	설명	비고
Ctrl+G	기본 텍스트 편집기에서 프롬프트/계획 편집	Ctrl+X Ctrl+E와 동일
Esc + Esc	되돌리기(Rewind) 또는 요약 메뉴 호출	코드/대화 상태를 이전으로 복원
Ctrl+R	역방향 명령 기록 검색	이전 입력 명령어를 대화형으로 검색
Option+P	모델(Model) 전환	프롬프트를 지우지 않고 즉시 교체
Option+T	확장 사고(Extended Thinking) 토글	모델의 추론 깊이를 활성화/비활성화
Ctrl+O	트랜스크립트 뷰어(Transcript Viewer) 토글	상세 도구 사용 이력 및 MCP 호출 확인

 

🛠️ 고급 실행 및 검색 명령어

명령어	설명	활용 팁
/btw	대화 기록에 남지 않는 측면 질문	컨텍스트 낭비 없이 빠른 질문 가능
/compact	대화 기록 요약 및 컨텍스트 최적화	/compact Focus on API 처럼 사용
/model	사용할 AI 모델 선택	sonnet, haiku 등으로 변경 가능
/rewind	특정 메시지 지점으로 상태 복구	실패한 접근법을 빠르게 폐기할 때 유용
! (접두사)	Bash 모드 직접 실행	Claude를 거치지 않고 직접 셸 명령 수행
@	파일 경로 언급 및 자동 완성	특정 파일을 컨텍스트로 바로 추가

🖥️ Vim 편집기 모드 (NORMAL 모드 기준)

editorMode: "vim" 설정 시 터미널 내에서 강력한 편집이 가능하다.

• 탐색: h/j/k/l (이동), w/e/b (단어 단위 이동), gg/G (시작/끝 이동)
• 편집: x (삭제), dd (줄 삭제), yy (줄 복사), p (붙여넣기), u (실행 취소)
• 객체: iw (내부 단어), i" (큰따옴표 안쪽 문자열) 등 연산자 조합 지원

 

4.  핵심 설정 3요소

Claude Code의 정체성을 결정짓는 세 가지 핵심 설정(권한, 워크트리, 확장 사고)을 깊게 파헤쳐 보았다.

① 권한 체계 (Permissions)

Claude가 내 시스템을 제어하는 '안전장치'다. allow, ask, deny의 세 가지 규칙이 순서대로 평가되며 첫 번째 일치 규칙이 적용된다.

• Bash 제어: Bash(npm test *)처럼 특정 명령어 패턴만 허용할 수 있다.
• 파일 접근: Read(./.env)를 deny 배열에 넣어 민감 정보 노출을 원천 차단해야 한다.

② 워크트리 및 플랜 (Worktree & Plans)

대규모 모노레포에서 성능과 격리를 동시에 잡는 기능이다.

• worktree.sparsePaths: 필요한 패키지만 체크아웃하여 시작 속도를 극대화한다.
• worktree.symlinkDirectories: node_modules 등을 메인 저장소와 공유해 리소스를 절약한다.

③ 확장 사고 (Extended Thinking)

복잡한 추론이 필요한 작업에서 모델이 더 오래 생각하게 만드는 옵션이다.

• effortLevel: low, medium, high, xhigh 단계로 조절하여 비용과 정확도 사이의 균형을 맞춘다.

 

5. 실전 코드 예시: settings.json 최적화

공부한 내용을 바탕으로 구성한 실무형 설정 가이드다. 주석을 통해 각 설정의 의미를 상세히 적어두었다.

 

{
  "$schema": "https://code.claude.com/docs/settings.schema.json",
  "editorMode": "vim", // 터미널 프롬프트를 Vim 스타일로 사용 [cite: 367]
  "language": "korean", // Claude가 기본적으로 한국어로 답변하도록 설정 [cite: 322]
  "alwaysThinkingEnabled": false, // 비용 관리를 위해 기본 사고 모드는 OFF [cite: 266, 533]
  "effortLevel": "medium", // 사고 모드 활성화 시 중간 정도의 깊이 유지 [cite: 301, 535]
  
  "permissions": {
    "deny": [
      "Read(./.env)", // 환경 변수 파일 읽기 거부 
      "Bash(rm -rf /)", // 위험한 명령어 실행 차단 [cite: 385]
      "WebFetch(domain:internal.vault.com)" // 내부 보안 도메인 접근 차단 [cite: 397]
    ],
    "ask": [
      "Bash(git push *)", // 푸시 전에는 항상 확인 요청 [cite: 383]
      "Bash(npm publish)" // 패키지 배포 전 확인 [cite: 383]
    ],
    "allow": [
      "Bash(npm test *)", // 테스트 실행은 항상 허용 [cite: 381]
      "Edit(./src/**)" // 소스 디렉토리 편집 허용 [cite: 381, 407]
    ]
  },

  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"], // 공통 디렉토리 심볼릭 링크 공유 
    "sparsePaths": ["packages/core", "shared/utils"] // 필요한 경로만 체크아웃 
  },

  "attribution": {
    "commit": "🤖 Co-authored by Claude Code", // 커밋 메시지에 AI 기여 표시 [cite: 269, 539]
    "pr": "This PR was generated by Claude Code." [cite: 269]
  }
}

6. 실무 팁 및 주의사항

• CLAUDE.md의 전략적 관리: 이 파일은 매 세션 로드되는 '지속적 메모리'다. 너무 길어지면 실제 지침이 무시되므로, Claude가 코드를 통해 스스로 알 수 있는 정보는 과감히 삭제(Pruning)해야 한다.
• 교정의 늪 피하기: Claude가 같은 실수를 두 번 이상 반복한다면 컨텍스트가 오염된 상태다. 계속 수정하기보다는 /clear로 세션을 초기화하고, 실패 경험을 포함한 더 구체적인 프롬프트로 다시 시작하는 것이 훨씬 효율적이다.
• 검증 수단 마련: AI에게 작업을 맡길 때는 반드시 테스트 코드나 린터 같은 '성공 기준'을 함께 제시해야 한다. 스스로 검증할 방법이 없을 때 AI는 겉보기만 멀쩡한 코드를 만들 위험이 높다.

7. 마무리

Claude Code는 단순한 도구를 넘어 개발자의 의도를 실현하는 강력한 실행 파트너다. 공부를 통해 느낀 점은, 도구의 강력함만큼이나 사용자가 설정하는 '권한의 경계'와 ' 텍스트 관리 능력'이 생산성을 결정짓는 핵심이라는 사실이다. 특히 플랜 모드를 통해 신중하게 설계하고 에이전틱 루프로 구현을 위임하는 방식은 생산성을 획기적으로 높여준다. 오늘 정리한 계층적 설정 구조와 효율적인 워크플로우를 통해, 각자의 환경에 최적화된 AI 협업 시스템을 구축해 보길 바란다.