Claude Code에 "버그 고쳐줘"라고 입력하면 내부에서 무슨 일이 일어날까요. 단순히 답변을 출력하는 것이 아닙니다. 여러 단계를 거쳐 실제로 파일을 수정하고 검증합니다.
Prompt → Planning → Tool Use → Reflection → Completion
사용자 입력과 현재 컨텍스트를 모두 수집합니다.
수집하는 정보:
- 사용자 메시지
- CLAUDE.md 내용
- 이전 대화 기록
- Hook이 주입한 컨텍스트 (브랜치 정보 등)
- /memory에 저장된 프로젝트 메모리
Hook의 UserPromptSubmit이 이 단계에서 실행됩니다.
요청을 분석하고 어떤 도구를 어떤 순서로 사용할지 계획합니다.
요청: "getUserById에 Redis 캐시 추가해줘"
계획:
1. Grep으로 getUserById 위치 파악
2. Read로 해당 파일 읽기
3. Read로 Redis 설정 파일 확인
4. Edit으로 캐시 로직 추가
5. Bash로 테스트 실행
/plan 명령으로 실행 전에 계획을 먼저 확인할 수 있습니다.
claude> /plan "getUserById에 Redis 캐시 추가해줘"
계획에 따라 도구를 순서대로 호출합니다.
Grep("getUserById")
→ "src/user/user.service.ts:45"
Read("src/user/user.service.ts")
→ 파일 내용 반환
Read("src/app.module.ts")
→ RedisModule 설정 확인
Edit("src/user/user.service.ts", ...)
→ 캐시 로직 추가
Bash("npm run test user")
→ 테스트 결과 반환
각 도구 호출 전후로 Hooks(PreToolUse, PostToolUse)가 실행됩니다.
각 도구의 결과를 보고 계획을 수정하거나 추가 작업을 결정합니다.
테스트 실패 → 원인 분석 → 수정 → 재실행
에러 발생 → 다른 접근 시도
예상과 다른 결과 → 계획 수정
단순히 도구를 나열해서 실행하는 것이 아니라, 결과를 보고 다음 행동을 결정합니다. 이 단계가 에이전트가 단순 스크립트와 다른 점입니다.
도구 실행 → 결과 확인 → 충분한가?
아니오 → 추가 도구 실행 → 결과 확인 → ...
예 → Completion 단계로
목표가 달성되면 결과를 사용자에게 보고합니다.
완료 보고:
- 무엇을 변경했는지
- 테스트 결과
- 추가로 확인할 사항 (있는 경우)
Stop Hook이 이 단계에서 실행됩니다. 알림 발송, 로그 기록 등에 씁니다.
사용자: "user.service.ts의 타입 오류 고쳐줘"
[Prompt]
- 사용자 메시지 수신
- CLAUDE.md 로드
- UserPromptSubmit Hook 실행
[Planning]
- 어떤 파일의 타입 오류인지 파악 필요
- tsc 실행으로 오류 목록 확인 계획
[Tool Use]
Bash("npx tsc --noEmit")
→ error TS2345: ... user.service.ts:80
Read("src/user/user.service.ts", offset=75, limit=15)
→ 해당 부분 확인
PostToolUse Hook 실행 (Read 완료)
Edit("src/user/user.service.ts", ...)
→ 타입 오류 수정
PostToolUse Hook 실행 (Edit 완료 → lint 실행)
Bash("npx tsc --noEmit")
→ 오류 없음
[Reflection]
- tsc 통과 확인
- lint 결과 확인
- 추가 수정 불필요
[Completion]
- "user.service.ts 80번째 줄의 타입 오류를 수정했습니다."
- Stop Hook 실행 (알림 발송)
작업 완료 후 명시적으로 검증 단계를 실행합니다.
claude> /verify
테스트, 빌드, 린트 등 정의된 검증 명령을 실행하고 결과를 보고합니다.