[Claude Code] 3. 명령어

1. 컨텍스트를 정확히 채우는 법

'@' 파일 참조

• 특정 파일이나 디렉터리를 명확히 지정하면 불필요한 탐색을 줄이고 현재 작업에 필요한 컨텍스트를 집중적으로 제공할 수 있음

 

예시) @로 파일 참조하여 프롬프팅하기

• @spring-cloud-api-gateway/build.gradle 파일의 의존성을 설명해주세요.
• @user-service/src/main/java 아래에서 회원가입 흐름을 분석해주세요.
• @docker-compose.yml과 @.github/workflows를 비교해서 배포되는 컨테이너와 포트를 정리해주세요.

 

Lazy Loading 방식으로 컨텍스트 관리하기

• 필요한 시점에만 관련 문서를 읽게 하는 전략
• @를 사용하여 관련 문서 링크를 달아줌

 

예시) 작업 요청

이번 작업은 OAuth2 로그인 오류 수정입니다.

먼저 다음 문서만 읽어주세요.

- @docs/authentication.md
- @oauth2-client/CLAUDE.md
- @spring-cloud-api-gateway/CLAUDE.md

Kafka와 채팅 관련 문서는 읽지 마세요.

 

2. Claude Code 안에서 Bash 명령 실행하기

• 입력창에서  명령어 앞에 '!'를 붙이면 직접 셸 명령을 실행 할 수 있음
• ex) !./gradlew clean build

 

무거운 작업은 스크립트로 위임하기

• ⚠️ 대용량 데이터를 대화 안에서 직접 모두 읽으면 컨텍스트 사용량이 크게 증가함

 

예시) CSV 대용량 데이터 처리

이 CSV를 직접 전부 출력하거나 컨텍스트에 넣지 마세요.

다음 작업을 수행하는 Python 스크립트를 작성해주세요.

1. 총 행 수 계산
2. 중복 데이터 수 계산
3. 누락값 통계
4. 컬럼별 최소·최대·평균
5. 오류 행만 별도 CSV로 저장
6. 요약 결과를 JSON으로 출력

스크립트를 실행한 뒤 요약 JSON만 분석해주세요.

• 이걸 클로드가 다 읽게 하면 토큰 소모가 너무 큼

 

3. 컨텍스트 윈도우 관리

명령어	설명	사용하는 상황
/context	현재 컨텍스트 윈도우가 어떤 정보가 차지하고 있는지 확인	세션이 길어졌거나, MCP·메모리·대화 기록이 얼마나 공간을 쓰는지 보고 싶을 때
/compact	현재 세션의 중요한 내용을 요약하고, 오래된 세부 대화와 도구 출력을 줄여 공간 확보	같은 작업을 계속 이어가야 하지만 컨텍스트가 많이 찼을 때
/clear	현재 세션의 대화 기록을 비우고 새로운 컨텍스트로 시작	완전히 다른 작업으로 넘어갈 때

 

4. 프로젝트 및 환경 관리

명령어	기능	사용 상황
/memory	현재 로드된 메모리와 CLAUDE.md 등 지침 파일 확인	프로젝트 지침이 실제로 적용되었는지 확인할 때
/mcp	연결된 MCP 서버 확인	현재 사용 중인 외부 도구나 MCP 서버 연결 상태를 점검할 때
/config	Claude Code 설정 화면 열기	모델, 권한, 출력 방식 등 동작 설정을 확인하거나 변경할 때
/doctor	설치 상태와 실행 환경 진단	설치 오류, 인증 문제, 실행 문제 등이 발생했을 때
/review	현재 코드 변경사항 검토	버그, 보안 문제, 테스트 누락, 불필요한 변경을 점검할 때
/init	프로젝트 분석 후 초기 CLAUDE.md 작성 지원	Claude Code를 처음 적용하는 프로젝트에 기본 지침 파일을 만들 때
/skills	설치된 스킬 목록 확인	스킬이 자동으로 호출되지 않는 원인을 확인할 때
/goal	세션 전체에 적용할 검증 조건 설정	특정 조건이 충족될 때까지 무인 작업을 계속 수행하게 할 때
/rewind 또는 Esc 두 번	이전 체크포인트로 대화와 코드 복원	작업이 잘못된 방향으로 진행됐을 때 되돌릴 때
/rename	현재 세션에 이름 지정	여러 작업 세션이나 워크스트림을 구분해서 관리할 때
/btw	기록에 남기지 않는 사이드 질문	메인 작업의 컨텍스트를 늘리지 않고 간단한 질문을 확인할 때

 

5. 세션 관리

명령어	설명	사용하는 상황
claude -c	현재 프로젝트에서 가장 최근에 사용한 세션을 이어서 실행	직전에 하던 작업을 계속 진행할 때
claude --resume	저장된 세션 목록에서 특정 세션을 선택하여 실행	여러 세션 중 원하는 과거 작업으로 돌아갈 때
claude -p "요청"	요청 결과만 출력한 뒤 세션을 종료	간단한 질문, 일회성 분석, 스크립트 자동화에 사용할 때

 

예시) 비대화형 세션 - 파일 단위 fan-out

똑같은 작업 대량 반복

• 파일 2000개를 하나하나 마이그레이션해야 한다고 해봅시다.
• 세션 하나로 다 시키면 컨텍스트가 감당 안 돼요.

 

for file in $(cat files.txt); do
  claude -p "React에서 Vue로 $file 마이그레이션. OK/FAIL 반환." \
    --allowedTools "Edit,Bash(git commit *)"
done

• files.txt에 적힌 파일 목록을 한 줄씩 읽어서, 파일마다 새로운 Claude 세션을 짧게 하나씩 실행합니다.
• 각 세션은 파일 하나만 마이그레이션하고 끝나요. 컨텍스트가 절대 안 쌓이니 2000개든 뭐든 돌릴 수 있어요.
• --allowedTools "Edit,Bash(git commit *)": "너 이 작업 중엔 파일 수정이랑 git commit만 할 수 있어"라고 권한을 미리 제한해두는 것. 사람이 옆에서 안 지켜봐도 위험한 짓 못 하게 안전장치를 걸어두는 거예요.

 

TIP

• 한 세션에는 한 작업만 수행하기 (관련없는 걸 같이 물어보면 컨텍스트가 섞임)
• 테스트 중심으로 작은 변경과 검증 반복하기 (한 번에 크게 바꾸지 말고 작은 단위로 확인하며 진행)
• 기능 하나가 완료되면 정리하기
  • 테스트 실행
  • git diff 확인
  • 작업 결과 요약
  • TODO.md 업데이트
  • /clear로 컨텍스트 윈도우 정리
• TODO.md로 장기 작업 관리하기 (여러 세션에 걸친 작업은 진행 상황을 파일로 남겨 세션이 바뀌어도 이어갈 수 있게 하기)

 

6. Mermaid로 아키텍처 문서화하기

• 복잡한 시스템 구조나 흐름을 말로 설명하는 대신 다이어그램으로 문서화하기
• 나중에 다른 세션이나 팀원이 구조를 훨씬 빠르게 파악할 수 있음

 

 

출처

• Claude Code Docs - Claude Code의 작동 방식
• Claude Code Docs - Claude Code 모범 사례
• 실밸개발자 (youtube) - 메타 엔지니어의 클로드 코드 완벽 가이드 [입문편] - 설정부터 단축키까지 25분 총정리
• 실밸개발자 (youtube) - 메타 엔지니어의 클로드코드 완벽 가이드 [실전편] — 컨텍스트 관리, 실전 워크플로우 20분 총정리