동적 컨텍스트 주입: Contexts 사용법
이 수업을 마치면 할 수 있는 것
동적 컨텍스트 주입을 배운 후에는 다음을 수행할 수 있습니다.
- 현재 작업 모드에 따라 AI의 동작 전략을 전환 (개발, 리뷰, 연구)
- Claude가 다른 시나리오에서 다른 우선순위와 도구 선호도를 따르도록 설정
- 동일한 세션에서 작업 목표를 혼동하는 것을 방지하여 집중도 향상
- 다른 단계의 작업 효율성 최적화 (빠른 구현 vs 심층 리뷰)
현재 겪고 있는 문제
개발 과정에서 다음과 같은 문제를 겪었나요?
- 빠르게 개발하려 할 때, Claude가 항상 과도하게 분석하고 너무 많은 제안을 해서 진도를 늦춤
- 코드 리뷰할 때, Claude가 코드를 꼼꼼히 읽고 문제를 발견하기보다 급하게 코드를 수정하려 함
- 새로운 문제를 연구할 때, Claude가 이해하지 못했는데도 바로 코드를 작성해서 방향이 잘못됨
- 동일한 세션에서, 한 번은 개발하고 한 번은 리뷰해서 Claude의 동작 패턴이 혼란스러움
이러한 문제의 근본 원인은 Claude에게 명확한 "작업 모드" 신호가 없어서 현재 우선적으로 무엇을 해야 할지 모르는 것입니다.
언제 이 기술을 사용할까요
- 개발 단계: AI가 기능을 우선 구현하고, 나중에 세부 사항을 논의하도록 함
- 코드 리뷰: AI가 먼저 충분히 이해한 다음 개선 제안을 하도록 함
- 기술 연구: AI가 먼저 탐색하고 학습한 후 결론을 내리도록 함
- 작업 모드 전환 시: AI에게 현재 목표가 무엇인지 명확하게 알림
핵심 아이디어
동적 컨텍스트 주입의 핵심은 AI가 다른 작업 모드에서 다른 동작 전략을 갖도록 하는 것입니다.
세 가지 작업 모드
Everything Claude Code는 세 가지 미리 정의된 컨텍스트를 제공합니다.
| 모드 | 파일 | 초점 | 우선순위 | 적용 시나리오 |
|---|---|---|---|---|
| dev | contexts/dev.md | 기능 구현, 빠른 반복 | 먼저 돌아가게 하고, 나중에 개선 | 일일 개발, 새로운 기능 구현 |
| review | contexts/review.md | 코드 품질, 보안, 유지보수성 | 먼저 문제를 발견하고, 나중에 수정 제안 | Code Review, PR 리뷰 |
| research | contexts/research.md | 문제 이해, 솔루션 탐색 | 먼저 이해하고, 나중에 실행 | 기술 조사, Bug 분석, 아키텍처 설계 |
동적 컨텍스트가 필요한 이유는?
컨텍스트 vs 시스템 프롬프트
시스템 프롬프트는 Claude Code가 시작될 때 로드되는 고정된 지시사항입니다 (예: agents/, rules/ 디렉토리의 내용). AI의 기본 동작을 정의합니다.
컨텍스트는 현재 작업 모드에 따라 동적으로 주입하는 임시 지시사항입니다. 시스템 프롬프트를 덮어쓰거나 보완하여 AI가 특정 시나리오에서 동작을 변경하도록 합니다.
시스템 프롬프트는 "전역 기본값", 컨텍스트는 "시나리오 덮어쓰기"입니다.
작업 모드 비교
동일한 작업이 다른 모드에서 AI가 어떻게 다르게 동작하는지 비교:
### 작업: 로그인 실패를 유발하는 버그 수정
#### dev 모드 (빠른 수정)
- 빠르게 문제 위치 파악
- 직접 코드 수정
- 테스트 실행하여 검증
- 먼저 돌아가게 하고, 나중에 최적화
#### review 모드 (심층 분석)
- 관련 코드를 충분히 읽기
- 경계 조건과 오류 처리 확인
- 수정 방안의 영향 평가
- 먼저 문제를 발견하고, 나중에 수정 제안
#### research 모드 (철저한 조사)
- 가능한 모든 원인 탐색
- 로그와 오류 메시지 분석
- 가설 검증
- 먼저 근본 원인을 이해하고, 나중에 솔루션 제시🎒 시작 전 준비
함께 해보기: 동적 컨텍스트 사용
1단계: 세 가지 컨텍스트의 작동 방식 이해
먼저 각 컨텍스트의 정의를 이해해 보세요:
dev.md - 개발 모드
목표: 기능을 빠르게 구현, 먼저 돌아가게 하고 나중에 개선
우선순위:
- Get it working (작동하게 만들기)
- Get it right (올바르게 만들기)
- Get it clean (깔끔하게 만들기)
동작 전략:
- Write code first, explain after (먼저 코드 작성, 나중에 설명)
- Prefer working solutions over perfect solutions (완벽한 솔루션보다 작동하는 솔루션 선호)
- Run tests after changes (변경 후 테스트 실행)
- Keep commits atomic (커밋을 원자적으로 유지)
도구 선호도: Edit, Write (코드 수정), Bash (테스트/빌드 실행), Grep/Glob (코드 검색)
review.md - 리뷰 모드
목표: 코드 품질 문제, 보안 취약점, 유지보수성 문제 발견
우선순위: Critical (치명적) > High (높음) > Medium (중간) > Low (낮음)
동작 전략:
- Read thoroughly before commenting (충분히 읽고 나서 주석 작성)
- Prioritize issues by severity (심각도별로 문제 우선순위 지정)
- Suggest fixes, don't just point out problems (수정 방안 제안, 문제만 지적하지 않기)
- Check for security vulnerabilities (보안 취약점 확인)
리뷰 체크리스트:
- [ ] Logic errors (논리 오류)
- [ ] Edge cases (경계 조건)
- [ ] Error handling (오류 처리)
- [ ] Security (injection, auth, secrets) (보안)
- [ ] Performance (성능)
- [ ] Readability (가독성)
- [ ] Test coverage (테스트 커버리지)
출력 형식: 파일별 그룹화, 심각도 우선
research.md - 연구 모드
목표: 문제를 깊이 이해하고, 가능한 솔루션 탐색
연구 프로세스:
- Understand the question (질문 이해)
- Explore relevant code/docs (관련 코드/문서 탐색)
- Form hypothesis (가설 수립)
- Verify with evidence (증거로 검증)
- Summarize findings (발견 사항 요약)
동작 전략:
- Read widely before concluding (결론 내리기 전에 널리 읽기)
- Ask clarifying questions (명확화 질문하기)
- Document findings as you go (탐색하면서 발견 사항 기록)
- Don't write code until understanding is clear (이해가 명확해질 때까지 코드 작성하지 않기)
도구 선호도: Read (코드 이해), Grep/Glob (패턴 검색), WebSearch/WebFetch (외부 문서), Task with Explore agent (코드베이스 문제)
출력 형식: 먼저 발견, 나중에 제안
2단계: 컨텍스트 선택 및 적용
현재 작업 시나리오에 따라 적절한 컨텍스트를 선택하세요.
시나리오 1: 새로운 기능 구현
적용 컨텍스트: dev.md
적용 방법:
@contexts/dev.md
사용자 인증 기능을 구현해 주세요:
1. 이메일 비밀번호 로그인 지원
2. JWT 토큰 생성
3. 라우트 보호를 위한 미들웨어 구현Claude가 어떻게 동작할지:
- 핵심 기능을 빠르게 구현
- 과도하게 설계하지 않음
- 구현 후 테스트를 실행하여 검증
- 커밋을 원자적으로 유지 (각 커밋이 작은 기능 완료)
당신이 보게 될 것:
- 빠르게 실행 가능한 코드 획득
- 테스트 통과
- 기능이 작동하지만, 우아하지 않을 수 있음
시나리오 2: 동료의 PR 리뷰
적용 컨텍스트: review.md
적용 방법:
@contexts/review.md
이 PR을 리뷰해 주세요: https://github.com/your-repo/pull/123
중점 확인:
- 보안 (SQL 인젝션, XSS, 인증)
- 오류 처리
- 성능 문제Claude가 어떻게 동작할지:
- 먼저 모든 관련 코드를 충분히 읽음
- 심각도별로 문제 정렬
- 각 문제에 대한 수정 제안 제공
- 코드를 직접 수정하지 않고, 제안만 제공
당신이 보게 될 것:
- 구조화된 리뷰 보고서 (파일별, 심각도별)
- 각 문제에 대한 구체적인 위치와 수정 제안
- Critical 수준 문제 우선 표시
시나리오 3: 새로운 기술의 통합 솔루션 조사
적용 컨텍스트: research.md
적용 방법:
@contexts/research.md
프로젝트에 ClickHouse를 분석 데이터베이스로 통합하려고 합니다. 다음을 조사해 주세요:
1. ClickHouse의 장점과 단점
2. 기존 PostgreSQL 아키텍처와의 통합 방법
3. 마이그레이션 전략과 위험
4. 성능 벤치마크 결과
코드는 작성하지 말고, 솔루션을 명확히 조사해 주세요.Claude가 어떻게 동작할지:
- 먼저 ClickHouse 공식 문서와 베스트 프랙티스 검색
- 관련 마이그레이션 사례 읽기
- 기존 아키텍처와의 호환성 분석
- 탐색하면서 발견 사항 기록
- 마지막에 종합 제안 제시
당신이 보게 될 것:
- 상세한 기술 비교 분석
- 위험 평가 및 마이그레이션 제안
- 코드 없이, 솔루션과 결론만
3단계: 동일 세션에서 컨텍스트 전환
동일한 세션에서 컨텍스트를 동적으로 전환하여 다른 작업 단계에 맞출 수 있습니다.
예시: 개발 + 리뷰 워크플로우
#### 1단계: 기능 구현 (dev 모드)
@contexts/dev.md
사용자 로그인 기능을 구현해 주세요. 이메일 비밀번호 인증을 지원해야 합니다.
...
#### Claude가 기능을 빠르게 구현
#### 2단계: 자기 리뷰 (review 모드)
@contexts/review.md
방금 구현한 로그인 기능 코드를 리뷰해 주세요:
...
#### Claude가 리뷰 모드로 전환하여 코드 품질을 심층 분석
#### 심각도별로 문제와 개선 제안 나열
#### 3단계: 리뷰 결과에 따른 개선 (dev 모드)
@contexts/dev.md
위 리뷰 의견에 따라 Critical과 High 수준의 문제를 수정해 주세요.
...
#### Claude가 문제를 빠르게 수정
#### 4단계: 다시 리뷰 (review 모드)
@contexts/review.md
수정된 코드를 다시 리뷰해 주세요.
...
#### Claude가 문제가 해결되었는지 확인당신이 보게 될 것:
- 각 단계에서 명확한 작업 초점
- 개발 단계에서는 빠른 반복
- 리뷰 단계에서는 심층 분석
- 동일 모드에서의 동작 충돌 방지
4단계: 사용자 정의 컨텍스트 생성 (선택 사항)
미리 정의된 세 가지 모드가 요구사항을 충족하지 않는다면, 사용자 정의 컨텍스트를 만들 수 있습니다.
컨텍스트 파일 형식:
#### My Custom Context
Mode: [모드 이름]
Focus: [초점]
## Behavior
- 동작 규칙 1
- 동작 규칙 2
## Priorities
1. 우선순위 1
2. 우선순위 2
## Tools to favor
- 추천 사용 도구예시: debug.md - 디버깅 모드
#### Debug Context
Mode: Debugging and troubleshooting
Focus: Root cause analysis and fix
## Behavior
- 증거 수집으로 시작 (로그, 오류 메시지, 스택 트레이스)
- 수정 제안 전에 가설 수립
- 수정을 체계적으로 테스트 (변수 제어)
- 향후 참조를 위해 발견 사항 기록
## Debug Process
1. 일관되게 문제 재현
2. 진단 정보 수집
3. 가능한 원인 좁히기
4. 가설 테스트
5. 수정이 작동하는지 확인
## Tools to favor
- 코드 검사를 위한 Read
- 테스트 실행 및 로그 확인을 위한 Bash
- 오류 패턴 검색을 위한 Grep사용자 정의 컨텍스트 사용:
@contexts/debug.md
프로덕션 환경에서 이 문제가 발생했습니다:
[오류 메시지]
[관련 로그]
디버깅을 도와주세요.체크포인트 ✅
위 단계를 완료한 후, 다음을 수행할 수 있어야 합니다.
- [ ] 세 가지 미리 정의된 컨텍스트의 작동 방식과 적용 시나리오 이해
- [ ] 작업 시나리오에 따라 적절한 컨텍스트 선택 가능
- [ ] 세션에서 컨텍스트를 동적으로 전환 가능
- [ ] 사용자 정의 컨텍스트 생성 방법 알기
- [ ] 다른 컨텍스트에서 AI 동작의 명확한 차이 경험
주의할 점
❌ 오류 1: 컨텍스트를 전환하지 않고 AI가 자동으로 적응하기를 기대
문제: 동일한 세션에서 한 번은 개발하고 한 번은 리뷰하면서, 현재 목표를 AI에게 알리지 않음.
증상: Claude의 동작이 혼란스러워서, 때로는 과도하게 분석하고 때로는 급하게 코드를 수정함.
올바른 방법:
- 명확하게 컨텍스트 전환:
@contexts/dev.md또는@contexts/review.md - 각 단계 시작 시 현재 목표 선언
## X단계: [목표]로 단계 명확화
❌ 오류 2: research 모드로 빠른 개발 수행
문제: 30분 안에 빠르게 기능을 구현해야 하는데 @contexts/research.md를 사용함.
증상: Claude가 조사, 토론, 분석에 많은 시간을 쓰고, 코드 작성을 지연함.
올바른 방법:
- 빠른 개발은
dev모드 사용 - 심층 조사는
research모드 사용 - 시간 압박과 작업 복잡도에 따라 모드 선택
❌ 오류 3: dev 모드로 중요 코드 리뷰
문제: 보안, 돈, 개인정보와 관련된 중요 코드를 리뷰하는데 @contexts/dev.md를 사용함.
증상: Claude가 빠르게 훑어보고, 심각한 보안 취약점을 놓칠 수 있음.
올바른 방법:
- 중요 코드 리뷰는 반드시
review모드 사용 - 일반 PR 리뷰는
review모드 사용 - 자기 빠른 반복일 때만
dev모드 사용
이 수업 요약
동적 컨텍스트 주입은 현재 작업 모드를 명확히 하여 AI가 다른 시나리오에서 동작 전략을 최적화하도록 합니다.
세 가지 미리 정의된 모드:
- dev: 빠른 구현, 먼저 돌아가게 하고 나중에 개선
- review: 심층 리뷰, 문제를 발견하고 수정 제안
- research: 충분한 조사, 이해 후 결론
사용 포인트:
- 작업 단계에 따라 컨텍스트 전환
@contexts/xxx.md로 명확하게 컨텍스트 로드- 동일 세션에서 여러 번 전환 가능
- 사용자 정의 컨텍스트를 생성하여 특정 요구사항 충족 가능
핵심 가치: AI 동작 혼란을 방지하고, 다른 단계에서의 집중도와 효율성을 높임.
다음 수업 예고
다음 수업에서는 **구성 파일 상세: settings.json 완전 참조**를 학습합니다.
배우게 될 것:
- settings.json의 완전한 구성 옵션
- Hooks 구성을 사용자 정의하는 방법
- MCP 서버 활성화 및 비활성화 전략
- 프로젝트 수준 및 전역 수준 구성의 우선순위
부록: 소스 코드 참조
클릭하여 소스 코드 위치 확인
업데이트 시간: 2026-01-25
| 기능 | 파일 경로 | 행 번호 |
|---|---|---|
| dev 컨텍스트 정의 | contexts/dev.md | 1-21 |
| review 컨텍스트 정의 | contexts/review.md | 1-23 |
| research 컨텍스트 정의 | contexts/research.md | 1-27 |
핵심 컨텍스트 파일:
dev.md: 개발 모드 컨텍스트, 기능 빠른 구현 우선review.md: 리뷰 모드 컨텍스트, 코드 품질 문제 발견 우선research.md: 연구 모드 컨텍스트, 문제 심층 이해 우선