CLAUDE Code 기본 사용법 및 에이전트에게 컨텍스트 제공하기.

이번에는 주요 명령어 및 단축키를 소개하고, Prompt Engineering 과 Context Engineering 차이를 알아보려 한다.

 

특히 Context Window 개념을 바탕으로 에이전트의 성능을 향상시키는 3가지 원칙을 제공하고,

AI 에게 프로젝트 배경지식을 제공하는 md 파일의 효과적인 작성 및 관리 기준을 다룬다.

---

1. 기본 인터페이스 익히기

먼저 나는 Claude 를 사용하고 있는데, 그중에서 자주 사용되는 몇가지만 언급하려고 한다.

조작	기능
텍스트 입력 후 Enter	사용자가 작성하는 프롬프트를 제출한다.
Shift + Enter	제출하지 않고 줄바꿈을 삽입한다.
Esc	대답중인 패널을 중지시킨다.
Esc + Esc	입력된 모든 텍스트를 삭제한다.
/model	모델을 변경한다.
Shift+Tab	플래닝 모드로 변경한다.
/context	현재 세션 토큰 사용량 확인한다.
/compact	대화를 요역한다.
/init	CLAUDE.md 를 자동으로 생성한다.

 

혹시 추가적인 command 및 단축키에 대해서 알고 싶다면 아래 링크를 참고하면 좋을것 같다.

https://code.claude.com/docs/en/slash-commands

2. 프롬프트 엔지니어링과 Context Engineering의 차이

그렇다면 이전 포스팅에서 농수산물 웹페이지를 만들어봤는데, 이렇게 일회성으로

프롬프트 기반으로 개발하는 것은 "프롬프트 엔지니어링"이라고 볼 수 있다.

 

이러한 프롬프트 엔지니어링은 Gemini, Chatgpt 등 웹 기반의 챗봇에서는 유의미하지만

Antigravity CLI, Claude code, Codex 와 같은 코딩 에이전트에서는 다르다.

 

파일을 읽고, 명령을 실행하고, 코드를 수정하는 에이전트는 프롬프트보다는 배경지식에 결과가 달라진다.

 

이를 Context Engineering 이라고 하는데, 해당 프로젝트에 대한 배경지식이나 제약사항 등을

md 파일을 통해 제공하고, AI 가 이를 참고하여 프로젝트 문맥을 이해할 수 있다.

 

여기서 또하나 중요한 개념이 들어가는데, Context Window 이다.

3. 컨텍스트 윈도우: AI의 RAM

AI 모델의 연산 능력을 CPU에 비유한다면, 컨텍스트 윈도우는 한 번에 처리할 수 있는 정보량을 의미하는 RAM에 해당한다.

 

만약 내가 Claude 를 사용한다는 가정 하에, 무언가를 요청한다면 Claude 는

프롬프트, Claude.md 의 마크다운 파일, 직접 읽은 소스 코드, 이전 명령 실행 결과 및 대화내용을

전부 읽고 동작하는데, 이때 Claude 가 읽는 모든 내용을 Context Windows 라고 한다.

 

다만 Context Windows 는 한계가 있어서 대화가 길어지면 성능 저하, 혹은 실수가 늘어난다.

그래서 꼭 필요한 정보만 넣고, 대화가 길어지면 대화가 길어지는 경우 /compact 기능을 활용해야 한다.

4. AI 에이전트 성능을 높이는 3가지 원칙

Context Engineering 에서 AI agent 성능을 높이기 위한 원칙은 총 세가지가 있다.

1. 검증 수단 제공: 테스트 코드, 스크린샷, 기대 결과물 등을 함께 제공하여 AI가 자신의 작업을 스스로 검증하게 한다.
2. 단계적 접근 (탐색 > 설계 > 구현 > 커밋): 즉시 코드를 작성하게 하지 않고, 계획 모드로 탐색과 설계를 마친 뒤 구현한다.
3. 구체적인 컨텍스트 제공: 프로젝트의 목적과 기대하는 사용자 경험, 구체적인 제약조건을 명확히 제시한다.

예를 들자면 " 농수산물 웹페이지를 만들어줘" 라고 말하기보다는,

"coupang 스타일의 농수산물 웹페이지를 만들거야. 그런데 카테고리 별로 상품이 분리되어야 하고, 상품을 선택하면 상품 상세 페이지로 이동하도록 구현해줘"

라고 구체적인 컨텍스트를 제공했을 때, 조금 더 기대하는 것과 동일한 결과가 나올 수 있다.

5. CLAUDE.md 작성 및 관리 가이드

그렇다면 이제 Context Engineering 의 꽃, md 파일에 대해서 이야기를 해보려고 한다.

 

md 파일이란 예전에는 "매번 프롬프트에 추가하기 귀찮으니까 미리 만들어둔 파일" 이라고 생각했는데

어느정도 맞지만, 굳이 이야기하자면 AI 에게 제공하는 배경지식, 지침가이드라고 볼 수 있다.

 

이런 md 파일에는 포함해야 할 부분과 불필요한 부분이 있는데, 위에서 언급했다시피

컨텍스트 윈도우에는 한계가 있기 때문에 최소한의 데이터로 최고의 효율을 내도록 작성해야 한다.

 

예를 들어, 프로젝트의 목적이나 AI 가 예측하지 못하는 한계사항 등에 대해서는 작성하되,

AI 가 이미 문서를 통해 유추할 수 있는 부분이나 추상적인 부분, 일회성의 요청 등은 지양하는 것이 좋다.

 

아래는 Claude 개발사, Anthropic 에서 제안한 "효과적인 CLAUDE.md" 작성하기 기준이다.

✅ 포함	❌ 제외
Claude가 추측할 수 없는 Bash 명령	Claude가 코드를 읽어서 파악할 수 있는 것
기본값과 다른 코드 스타일 규칙	Claude가 이미 알고 있는 표준 언어 규칙
테스트 지시사항 및 선호하는 테스트 러너	상세한 API 문서(대신 문서 링크)
저장소 에티켓(분기 이름 지정, PR 규칙)	자주 변경되는 정보
프로젝트에 특정한 아키텍처 결정	긴 설명 또는 튜토리얼
개발자 환경 특이성(필수 환경 변수)	자명한 관행(예: “깨끗한 코드 작성”)
일반적인 함정 또는 명백하지 않은 동작	파일별 코드베이스 설명

 

여기에 추가로 정말 중요한것은 모순되지 않도록 해야한다는 점이다.

 

예를 들어, md 파일 상단에 "농수산물 판매 페이지를 만들 것입니다. 카테고리 별로 분류하겠습니다." 라고 적고

하단에는 "카테고리 구분 없이 농수산물을 확인할 수 있습니다." 라고 작성한다면 혼란이 올 수 있다.

 

동시에 md 파일중 정말 중요하다고 생각하는 부분에 대해서는 강조 표현을 사용하여 우선순위를 높일 수 있다.

 

이렇듯 AI 코딩 에이전트의 성능은 프롬프트의 길이나 단순 지시가 아닌, 컨텍스트의 품질에 의해 결정된다.

 

제한된 컨텍스트 윈도우 내에서 중복과 모순을 제거하고 핵심적인 배경지식과 제약사항만을

명확하게 전달하는 Context Engineering을 통해 에이전트의 정확도와 프로젝트 구현 효율을 극대화할 수 있다.