Context Engineering 입문 가이드

Context Engineering(컨텍스트 엔지니어링)을 시작하기 위한 포괄적인 템플릿입니다. Context Engineering은 AI 코딩 어시스턴트가 작업을 처음부터 끝까지 완수하는 데 필요한 정보를 가질 수 있도록 컨텍스트(Context)를 설계하는 학문입니다.

Context Engineering은 프롬프트 엔지니어링(Prompt Engineering)보다 10배 더 뛰어나며, 바이브 코딩(Vibe Coding)보다 100배 더 뛰어납니다.

# 1. 이 템플릿을 클론하세요
git clone https://github.com/coleam00/Context-Engineering-Intro.git
cd Context-Engineering-Intro
...

• Context Engineering이란 무엇인가?
• 템플릿 구조
• 단계별 가이드
• 효과적인 INITIAL.md 파일 작성법
• PRP 워크플로우 (Workflow)
• 예시를 효과적으로 사용하는 방법
• 베스트 프랙티스 (Best Practices)

Context Engineering은 전통적인 프롬프트 엔지니어링으로부터의 패러다임 전환을 의미합니다:

프롬프트 엔지니어링 (Prompt Engineering):

• 영리한 단어 선택과 특정 문구에 집중합니다.
• 작업을 어떻게 표현하는지에 국한됩니다.
• 누군가에게 포스트잇을 주는 것과 같습니다.

Context Engineering:

• 포괄적인 컨텍스트를 제공하기 위한 완전한 시스템입니다.
• 문서(Documentation), 예시(Examples), 규칙(Rules), 패턴(Patterns), 그리고 검증(Validation)을 포함합니다.
• 모든 세부 사항이 담긴 전체 시나리오를 작성하는 것과 같습니다.

AI 실패 감소: 대부분의 에이전트(Agent) 실패는 모델의 실패가 아니라 컨텍스트의 실패입니다.
일관성 보장: AI가 사용자의 프로젝트 패턴과 컨벤션(Conventions)을 따르게 합니다.
복잡한 기능 구현 가능: 적절한 컨텍스트를 통해 AI가 다단계 구현을 처리할 수 있습니다.
자기 수정 (Self-Correcting): 검증 루프(Validation loops)를 통해 AI가 스스로 실수를 수정할 수 있게 합니다.

context-engineering-intro/
├── .claude/
│ ├── commands/
...

이 템플릿은 Context Engineering을 통해 RAG(Retrieval-Augmented Generation)와 도구(Tools)에 집중하지 않는데, 그 이유는 조만간 그것들에 대해 훨씬 더 많은 것을 준비하고 있기 때문입니다. ;)

CLAUDE.md 파일은 AI 어시스턴트가 모든 대화에서 따르게 될 프로젝트 전반의 규칙을 포함합니다. 템플릿에는 다음이 포함됩니다:

프로젝트 인지 (Project awareness): 계획 문서 읽기, 작업 확인
코드 구조 (Code structure): 파일 크기 제한, 모듈 구성
테스트 요구사항 (Testing requirements): 단위 테스트 (Unit test) 패턴, 커버리지 (Coverage) 기대치
스타일 컨벤션 (Style conventions): 언어 선호도, 포맷팅 규칙
문서화 표준 (Documentation standards): Docstring 형식, 주석 작성 관례

제공된 템플릿을 그대로 사용하거나 프로젝트에 맞춰 맞춤 설정할 수 있습니다.

INITIAL.md를 편집하여

구축하고자 하는 내용을 설명하세요:

## FEATURE:
[구축하고자 하는 내용을 설명하세요 - 기능과 요구사항을 구체적으로 작성하세요]
## EXAMPLES:
...

전체 예시는 INITIAL_EXAMPLE.md를 참조하세요.

PRP (Product Requirements Prompts)는 다음과 같은 내용을 포함하는 포괄적인 구현 청사진 (Implementation blueprints)입니다:

• 완전한 컨텍스트 (Context) 및 문서화
• 검증을 포함한 구현 단계
• 에러 처리 (Error handling) 패턴
• 테스트 요구사항

이는 PRD (Product Requirements Documents)와 유사하지만, AI 코딩 어시스턴트에게 지시하기 위해 더 구체적으로 제작되었습니다.

Claude Code에서 실행:

/generate-prp INITIAL.md

참고: 슬래시 명령어 (Slash commands)는 .claude/commands/에 정의된 커스텀 명령어입니다. 구현 내용은 다음에서 확인할 수 있습니다:

.claude/commands/generate-prp.md

• 어떻게 조사하고 PRP를 생성하는지 확인하세요
  .claude/commands/execute-prp.md

• PRP로부터 기능을 어떻게 구현하는지 확인하세요

이 명령어들의 $ARGUMENTS 변수는 명령어 이름 뒤에 전달하는 모든 값(예: INITIAL.md 또는 PRPs/your-feature.md)을 받습니다.

이 명령어는 다음을 수행합니다:

• 기능 요청 읽기
• 패턴 파악을 위한 코드베이스 (Codebase) 조사
• 관련 문서 검색
• PRPs/your-feature-name.md에 포괄적인 PRP 생성

생성이 완료되면, 기능을 구현하기 위해 PRP를 실행하세요:

/execute-prp PRPs/your-feature-name.md

AI 코딩 어시스턴트는 다음을 수행합니다:

• PRP의 모든 컨텍스트 읽기
• 상세한 구현 계획 수립
• 검증과 함께 각 단계 실행
• 테스트 실행 및 문제 해결
• 모든 성공 기준 충족 확인

FEATURE: 구체적이고 포괄적으로 작성하세요

• ❌ "웹 스크레이퍼 만들기 (Build a web scraper)"
• ✅ "BeautifulSoup을 사용하여 이커머스 사이트에서 상품 데이터를 추출하고, 속도 제한 (Rate limiting)을 처리하며, 결과를 PostgreSQL에 저장하는 비동기 (Async) 웹 스크레이퍼 만들기"

EXAMPLES (예시): examples/ 폴더를 활용하세요

• 관련 코드 패턴을 examples/에 배치하세요
• 따라야 할 특정 파일과 패턴을 참조하세요
• 어떤 측면을 모방해야 하는지 설명하세요

DOCUMENTATION (문서화): 모든 관련 리소스를 포함하세요

• API 문서 URL
• 라이브러리 가이드
• MCP 서버 문서
• 데이터베이스 스키마 (Database schemas)

OTHER CONSIDERATIONS (기타 고려 사항): 중요한 세부 사항을 포착하세요

• 인증 요구 사항 (Authentication requirements)
• 속도 제한 (Rate limits) 또는 할당량 (Quotas)
• 일반적인 실수 (Common pitfalls)
• 성능 요구 사항 (Performance requirements)

명령어는 다음 프로세스를 따릅니다:

• Research Phase (조사 단계)

  • 코드베이스의 패턴을 분석합니다
  • 유사한 구현 사례를 검색합니다
  • 따라야 할 컨벤션 (Conventions)을 식별합니다

• Documentation Gathering (문서 수집 단계)

  • 관련 API 문서를 가져옵니다
  • 라이브러리 문서를 포함합니다
  • 주의 사항 (Gotchas) 및 특이 사항 (Quirks)을 추가합니다

• Blueprint Creation (청사진 생성 단계)

  • 단계별 구현 계획을 생성합니다
  • 검증 게이트 (Validation gates)를 포함합니다
  • 테스트 요구 사항을 추가합니다

• Quality Check (품질 검사 단계)

  • 신뢰 수준 (Confidence level)을 점수화합니다 (1-10)
  • 모든 컨텍스트 (Context)가 포함되었는지 확인합니다

Load Context (컨텍스트 로드): 전체 PRP를 읽습니다
Plan (계획): TodoWrite를 사용하여 상세 작업 목록을 생성합니다
Execute (실행): 각 구성 요소를 구현합니다
Validate (검증): 테스트 및 린팅 (Linting)을 실행합니다
Iterate (반복): 발견된 문제를 수정합니다
Complete (완료): 모든 요구 사항이 충족되었는지 확인합니다

생성되는 결과물의 전체 예시는 PRPs/EXAMPLE_multi_agent_prp.md를 참조하세요.

examples/ 폴더는 성공을 위해 매우 중요 (Critical) 합니다. AI 코딩 어시스턴트는 따라야 할 패턴을 볼 수 있을 때 훨씬 더 나은 성능을 발휘합니다.

• Code Structure Patterns (코드 구조 패턴)

  • 모듈을 구성하는 방식
  • 임포트 (Import) 컨벤션
  • 클래스/함수 패턴

• Testing Patterns (테스트 패턴)

  • 테스트 파일 구조
  • 모킹 (Mocking) 접근 방식
  • 어설션 (Assertion) 스타일

• Integration Patterns (통합 패턴)

  • API 클라이언트 구현
  • 데이터베이스 연결
  • 인증 흐름 (Authentication flows)

• CLI Patterns (CLI 패턴)

  • 인자 파싱 (Argument parsing)
  • 출력 포맷팅 (Output formatting)
  • 에러 핸들링 (Error handling)

examples/
├── README.md # 각 예제가 무엇을 보여주는지 설명
├── cli.py # CLI 구현 패턴
...

• AI가 사용자의 선호도를 알고 있다고 가정하지 마세요

• 구체적인 요구사항(Requirements)과 제약 조건(Constraints)을 포함하세요

• 예시(Examples)를 아낌없이 참조하세요

• 더 많은 예시 = 더 나은 구현

• 해야 할 일(What to do)과 하지 말아야 할 일(What not to do)을 모두 보여주세요

• 에러 핸들링(Error handling) 패턴을 포함하세요

• PRP(Prompt Reference Patterns)에는 반드시 통과해야 하는 테스트 명령어를 포함합니다

• AI는 모든 검증(Validations)이 성공할 때까지 반복(Iterate)할 것입니다

• 이는 첫 시도에 작동하는 코드를 보장합니다

• 공식 API 문서(API docs)를 포함하세요

• MCP 서버 리소스를 추가하세요

• 특정 문서 섹션을 참조하세요

• 사용자의 컨벤션(Conventions)을 추가하세요

• 프로젝트별 규칙을 포함하세요

• 코딩 표준(Coding standards)을 정의하세요