Name	Name	Last commit message	Last commit date
parent directory ..
artifacts	artifacts
logs	logs
round1/src	round1/src
round2	round2
round3	round3
src	src
Justfile	Justfile
README.md	README.md

Lab 01: 컨텍스트 엔지니어링 챌린지

2교시 실습 (40분) | Session 2: 에이전틱 루프와 컨텍스트 엔지니어링

실습 목표

같은 요청, 다른 컨텍스트 — 에이전트에게 동일한 작업을 3번 요청하되, 매번 제공하는 컨텍스트를 달리한다. 결과의 차이를 직접 측정하며 컨텍스트 엔지니어링의 효과를 체감한다.

실습 구성

01-context-engineering/
├── README.md                          # 이 파일
├── Justfile                           # 환경 준비, 테스트, 서버 실행
├── src/                               # 참조용 원본 코드 (북마크 REST API)
│   ├── app.py                         # HTTP 서버 (라우팅)
│   ├── models.py                      # Bookmark dataclass
│   ├── database.py                    # JSON 저장소
│   ├── validators.py                  # 입력 유효성 검사
│   └── test_api.py                    # API 테스트
├── round1/                            # Round 1: AGENTS.md 없음
│   └── src/                           # (원본과 동일한 코드)
├── round2/                            # Round 2: 기본 AGENTS.md 있음
│   ├── AGENTS.md                      # 코딩 컨벤션 + 테스트 규칙
│   └── src/
├── round3/                            # Round 3: 풍부한 컨텍스트
│   ├── AGENTS.md                      # 상세 규칙 + 예시 참조
│   ├── architecture.md                # 아키텍처 문서
│   ├── examples/                      # 코드 예시 파일
│   │   ├── add_field.py               # 필드 추가 패턴
│   │   ├── error_handling.py          # 에러 핸들링 패턴
│   │   └── docstring_style.py         # docstring 스타일
│   └── src/
└── artifacts/
    └── comparison-template.md         # 비교 기록 양식

사전 준비

# Python 3.8 이상 필요
python3 --version

# 환경 확인
just setup
# 또는
python3 -c "import http.server, json, uuid, dataclasses; print('OK')"

I DO — 실제 세션 로그 분석 (10분)

아래는 동일한 요청을 Round 1과 Round 2에서 실행한 실제 세션 기록이다. 세션 ID와 공유 URL이 있으며, oc-trace로 직접 조회 가능하다.

실행한 프롬프트 (두 라운드 동일)

북마크에 category 필드를 추가하고, 카테고리별 필터링 API를 만들어줘.

요구사항:
- Bookmark 모델에 category 필드 추가 (선택 필드, 기본값 None)
- POST /bookmarks 시 category 값 저장 가능
- GET /bookmarks?category=tech 처럼 쿼리 파라미터로 필터링 가능
- 테스트 추가

Round 1 세션 — AGENTS.md 없음

항목	값
세션 ID	`ses_2ffb44952ffen83yt2yCA9ul6e`
공유 URL	https://opncd.ai/share/yCA9ul6e
시작	2026-03-18 18:34:15
종료	2026-03-18 18:37:00
소요 시간	2분 45초
토큰	446,704
도구 호출	22회
사용 도구	todowrite, glob, grep, read, apply_patch, bash
파일 변경	4개 (+71줄, -9줄)

에이전트 행동 타임라인

[0:00] 사용자 → "북마크에 category 필드를 추가하고..."
    │
[0:00] todowrite → 작업 계획 3개 항목 생성
    │   "Inspect bookmark model, API routes, and test structure"  [in_progress]
    │   "Add optional category field to bookmark model..."        [pending]
    │   "Update POST and GET /bookmarks to accept and filter..."  [pending]
    │
[0:00] glob **/* → 5개 파일 발견
    │   test_api.py, app.py, validators.py, database.py, models.py
    │
[0:00] grep "Bookmark|bookmarks" in round1 → 34개 매칭
    │   (파일 구조 파악 전에 키워드 검색으로 맥락 수집)
    │
[0:00] read models.py     → category 필드 없음 확인
[0:00] read app.py        → HTTP 라우팅 패턴 파악
[0:00] read database.py   → 저장소 함수 목록 확인
[0:00] read test_api.py   → 기존 테스트 구조 파악
[0:00] read validators.py → 유효성 검사 패턴 파악
    │
[0:00] todowrite → "Inspect..." [completed]
    │
[0:09] apply_patch → models.py + database.py + app.py + test_api.py 동시 수정
    │   (15.5초 소요 — 4개 파일을 한 패치에 묶어 처리)
    │
[0:25] bash "python -m unittest src/test_api.py" → 실패
    │   ImportError: 경로 오류 (src/ 서브디렉토리 방식 불가)
    │
[0:26] bash "python -m unittest test_api.py" → OK (경고 있음)
    │   ResourceWarning: HTTPError 리소스 미정리
    │   Ran 5 tests in 0.550s — OK
    │
[0:27] apply_patch → test_api.py 수정 (tearDownClass에 server_close 추가)
[0:27] bash "python -m unittest test_api.py" → OK (경고 여전히 있음)
[0:28] apply_patch → test_api.py 수정 (HTTPError e.close() 추가)
[0:29] bash "python -m unittest test_api.py" → OK, 경고 없음
    │   Ran 5 tests in 0.555s — OK (ResourceWarning 해결)
    │
[0:29] todowrite → 나머지 항목 [completed]
    │
[0:29] read models.py, app.py, database.py, test_api.py → 최종 상태 재확인
    │   (수정 완료 후 파일 전체를 다시 한 번 읽음)
    │
[2:45] 완료 답변 출력

Round 1 에이전트의 자율 판단 사항

판단 항목	선택	비고
탐색 방식	glob + grep + read 5개	구조를 모르므로 키워드 검색 먼저
필터링 위치	database 레이어 (`get_all_by_category`)	요구사항에 없는 설계 결정
validators.py	수정 안 함	category 유효성 검사 없음
docstring	미추가	기존 코드에도 없으므로 생략
logging	기존 `print()` 유지	전환 필요성 인식 못함
테스트 함수명	`test_create_bookmark_with_category`	자체 판단 (규칙 없음)
경고 수정	apply_patch 2회 추가 소비	요청 외 부가 작업

Round 2 세션 — AGENTS.md 있음

항목	값
세션 ID	`ses_2ffaf11e2ffeYS37wBg4Y9ES4v`
공유 URL	https://opncd.ai/share/g4Y9ES4v
시작	2026-03-18 18:39:57
종료	2026-03-18 18:42:06
소요 시간	2분 9초
토큰	299,831
도구 호출	18회
사용 도구	todowrite, glob, read, apply_patch, bash
파일 변경	5개 (+131줄, -23줄)

에이전트 행동 타임라인

[0:00] 사용자 → "북마크에 category 필드를 추가하고..."
    │
[0:00] todowrite → 작업 계획 4개 항목 생성
    │   "Inspect current bookmark API structure and tests"        [in_progress]
    │   "Add optional category field to model and persistence..."  [pending]
    │   "Support category in validation and HTTP handlers..."      [pending]
    │   "Add and run tests"                                       [pending]
    │   (AGENTS.md 체크리스트 순서 반영: models → validators → database → app → test)
    │
[0:00] glob **/*.py → 5개 .py 파일 발견
    │   (Round 1의 glob **/* 와 달리 .py만 명시적으로 검색)
    │
[0:00] read models.py     → [실패] 경로 오류
[0:00] read database.py   → [실패] 경로 오류
[0:00] read validators.py → [실패] 경로 오류
[0:00] read app.py        → [실패] 경로 오류
[0:00] read test_api.py   → [실패] 경로 오류
    │   (처음 경로로 /round2/ 접근 → 실패 → /round2/src/로 수정)
    │
[0:00] read models.py     → [성공] category 필드 없음 확인
[0:00] read database.py   → [성공] 저장소 함수 확인, logging 이미 있음
[0:00] read validators.py → [성공] validate_url, validate_bookmark_input 확인
[0:00] read app.py        → [성공] logging.basicConfig 이미 설정됨
[0:00] read test_api.py   → [성공] 기존 테스트 7개 구조 파악
    │
[0:00] todowrite → "Inspect..." [completed]
    │
[0:11] apply_patch → models.py + validators.py + database.py + app.py + test_api.py
    │   5개 파일 단일 패치로 동시 수정 (0.3초)
    │   AGENTS.md 체크리스트 순서대로: models → validators → database → app → test
    │
[0:11] todowrite → 나머지 항목 [completed]
    │
[0:12] bash "python -m unittest -v src/test_api.py" → 실패
    │   ImportError: 경로 오류 (Round 1과 동일한 패턴)
    │
[0:13] bash "python -m unittest -v test_api.py" → OK
    │   15개 테스트 전부 통과
    │   (Round 1: 5개 → Round 2: 15개, +10개 순증)
    │
[0:13] todowrite → 최종 [completed]
    │
[2:09] 완료 답변 출력

Round 2에서 AGENTS.md가 바꾼 것

관찰 항목	Round 1 (AGENTS.md 없음)	Round 2 (AGENTS.md 있음)
탐색 도구	glob + grep + read	glob + read (grep 없음)
탐색 방식	키워드 검색으로 맥락 수집 먼저	파일 목록 → 직접 읽기
수정 파일 수	4개 (validators.py 누락)	5개 (validators.py 포함)
validators.py	수정 안 함	`validate_category()` 추가
apply_patch 횟수	3회 (경고 수정 2회 추가)	1회 (5개 파일 한 번에)
테스트 수	5개 통과	15개 통과
테스트 함수명	`test_create_bookmark_with_category`	`test_create_bookmark_with_category_success` (패턴 준수)
docstring	미추가	Google 스타일 전체 적용
logging	`print()` 유지	`logging` 모듈 사용 (AGENTS.md 규칙)
토큰 사용	446,704	299,831 (-33%)
소요 시간	2분 45초	2분 9초 (-22%)
도구 호출	22회	18회 (-18%)

핵심 관찰 포인트

1. grep이 사라졌다 — 탐색 전략의 변화

Round 1에서 에이전트는 파일을 읽기 전에 grep "Bookmark|bookmarks"로 키워드 검색을 먼저 했다. AGENTS.md가 없으니 어떤 파일에 무엇이 있는지 알 수 없어, 검색으로 맥락을 모아야 했다.

Round 2에서는 grep이 완전히 사라졌다. AGENTS.md의 코드 구조 규칙이 파일별 역할을 명시했기 때문이다:

## 코드 구조
- `models.py`: 데이터 모델만
- `database.py`: 저장소 접근만
- `validators.py`: 유효성 검사만
- `app.py`: HTTP 라우팅 + 응답 처리

핵심: 컨텍스트가 탐색을 대체했다. 에이전트가 "무엇을 찾아야 할지" 알고 있으면 탐색 단계가 줄어든다.

2. validators.py — 누락 vs 자동 포함

Round 1에서 에이전트는 validators.py를 읽었지만 수정하지 않았다. category 유효성 검사를 추가해야 한다는 판단 근거가 없었기 때문이다.

Round 2에서는 AGENTS.md 체크리스트가 명시적으로 validators.py 수정을 요구했다:

## 신규 기능 추가 시 체크리스트
- [ ] `models.py`에 데이터 모델 변경 반영
- [ ] `validators.py`에 유효성 검사 추가   ← 이 항목
- [ ] `database.py`에 저장소 함수 추가
- [ ] `app.py`에 라우트 핸들러 추가
- [ ] `test_api.py`에 테스트 추가

결과: Round 2에서 validate_category() 함수가 자동으로 추가되었고, 100자 초과, 빈 문자열 등의 예외 케이스도 처리되었다.

3. apply_patch 3회 vs 1회 — 경고 처리의 차이

Round 1에서 에이전트는 테스트 실행 중 ResourceWarning을 발견하고, 요청에 없던 수정을 2회 더 했다. 컨텍스트가 없으면 에이전트는 "발견한 문제를 즉시 고쳐야 한다"고 판단한다.

Round 2에서는 동일한 경고가 발생했지만 에이전트가 추가 패치를 하지 않았다. AGENTS.md가 명시한 범위에만 집중했기 때문이다.

비고: Round 2에서도 ResourceWarning은 발생했다. 하지만 에이전트가 범위를 벗어나는 수정을 하지 않아 도구 호출이 더 적었다.

4. 테스트 커버리지 — 5개 vs 15개

Round 1: 요청한 기능의 성공 케이스 2개만 추가 (총 5개) Round 2: 성공 케이스 + 실패 케이스(400, 404) 모두 추가 (총 15개)

AGENTS.md 규칙: "성공 케이스와 실패 케이스를 모두 테스트한다"

WE DO: 함께 실습 (15분)

학생들이 Round 2를 직접 진행하고 결과를 기록합니다.

단계별 진행

1단계: 코드 살펴보기 (3분)

# round2/src/ 코드 구조 확인
ls round2/src/

# AGENTS.md 읽기 (중요!)
cat round2/AGENTS.md

2단계: 기존 테스트 통과 확인 (2분)

just test-r2

모든 테스트가 통과하면 준비 완료.

3단계: 에이전트에게 과제 요청 (8분)

에이전트를 round2/ 디렉토리에서 실행하고 다음 요청을 보내세요:

북마크에 category 필드를 추가하고, 카테고리별 필터링 API를 만들어줘.

요구사항:
- Bookmark 모델에 category 필드 추가 (선택 필드, 기본값 None)
- POST /bookmarks 시 category 값 저장 가능
- GET /bookmarks?category=tech 처럼 쿼리 파라미터로 필터링 가능
- 테스트 추가

4단계: 결과 확인 (2분)

# 테스트 실행
just test-r2

# 서버 실행 후 curl로 확인
just serve-r2 &
curl -s -X POST http://localhost:8002/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"파이썬","url":"https://python.org","category":"docs"}'
curl -s "http://localhost:8002/bookmarks?category=docs"
kill %1

5단계: 세션과 실제 로그 비교 (진행 중에 작성)

에이전트가 작업하는 동안 아래를 기록하세요:

항목	I DO (실제 기록)	내 세션
첫 번째 도구 호출	todowrite
grep을 사용했는가?	사용 안 함
validators.py 수정 여부	수정함
apply_patch 횟수	1회
테스트 통과 수	15개
총 도구 호출 횟수	18회

artifacts/comparison-template.md의 Round 2 섹션도 채워주세요.

세션 추적 (선택 사항)

실행 후 자신의 세션을 추적하고 싶다면:

# 세션 목록 확인
opencode session list

# 세션 추적 (oc-trace)
python3 ~/.claude/skills/oc-trace/oc_trace.py list
python3 ~/.claude/skills/oc-trace/oc_trace.py trace <session_id> -v

YOU DO: 독립 실습 (15분)

Round 3(풍부한 컨텍스트)를 직접 구성하고, 자신만의 AGENTS.md 규칙을 실험합니다.

과제 A: Round 3 실행 및 비교 (10분)

Round 3 환경 탐색

# Round 3에는 무엇이 있나?
ls round3/
cat round3/AGENTS.md
cat round3/architecture.md
ls round3/examples/

에이전트를 round3/ 디렉토리에서 실행

동일한 요청을 전달하고 아래를 관찰하세요:

examples/add_field.py를 참조하는가?
architecture.md의 확장 포인트를 따르는가?
Round 2보다 코드 품질이 개선되었는가?

테스트 확인

just test-r3

3라운드 비교 기록표 완성

artifacts/comparison-template.md의 Round 3 섹션과 "라운드 비교 요약" 섹션을 채우세요.

지표	Round 1 (기록)	Round 2 (기록)
토큰 사용량	446,704	299,831
도구 호출 횟수	22회	18회
apply_patch 횟수	3회	1회
테스트 통과 수	5개	15개
validators.py 수정	없음	있음

과제 B: 나만의 AGENTS.md 규칙 실험 (5분)

Round 2 또는 Round 3의 AGENTS.md에 자신만의 규칙을 추가하고 에이전트 동작이 달라지는지 확인하세요.

아이디어 예시:

## 추가 규칙 아이디어
- category 허용 값을 enum으로 정의하라: tech, news, blog, video, docs, other
- 북마크 URL은 중복 저장 금지
- 삭제 시 실제 삭제 대신 deleted_at 필드를 설정하는 소프트 삭제 방식 사용
- 응답에 항상 X-Total-Count 헤더 포함

추가한 규칙과 결과를 artifacts/comparison-template.md의 "나의 인사이트" 섹션에 기록하세요.

빠른 참고: curl 명령어

# 헬스 체크
curl http://localhost:8000/health

# 북마크 생성 (category 없음)
curl -X POST http://localhost:8000/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"Python","url":"https://python.org"}'

# 북마크 생성 (category 있음 - 에이전트가 기능 추가 후)
curl -X POST http://localhost:8000/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"title":"GitHub","url":"https://github.com","category":"tech"}'

# 전체 목록 조회
curl http://localhost:8000/bookmarks

# 카테고리 필터링 (에이전트가 기능 추가 후)
curl "http://localhost:8000/bookmarks?category=tech"

# 단건 조회
curl http://localhost:8000/bookmarks/{id}

# 수정
curl -X PUT http://localhost:8000/bookmarks/{id} \
  -H "Content-Type: application/json" \
  -d '{"title":"새 제목","url":"https://new.com"}'

# 삭제
curl -X DELETE http://localhost:8000/bookmarks/{id}

정리: 컨텍스트 엔지니어링의 핵심

컨텍스트 수준	에이전트에게 주어진 것	관찰된 효과
Round 1	코드만	grep으로 탐색, validators 누락, apply_patch 3회, 토큰 446K
Round 2	코드 + AGENTS.md	grep 없음, validators 자동 포함, apply_patch 1회, 토큰 300K
Round 3	코드 + AGENTS.md + 아키텍처 + 예시	직접 측정해보세요

핵심 교훈: 에이전트는 판단 비용이 높을수록 불일관하거나 틀린 선택을 한다. 컨텍스트 엔지니어링은 "에이전트가 판단해야 할 것"을 줄이는 기술이다.

세션 로그 원본은 logs/round1-log.md, logs/round2-log.md에 있다. 세션 추적 방법의 자세한 내용은 부록: 세션 추적 가이드를 참고하라.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

Lab 01: 컨텍스트 엔지니어링 챌린지

실습 목표

실습 구성

사전 준비

I DO — 실제 세션 로그 분석 (10분)

실행한 프롬프트 (두 라운드 동일)

Round 1 세션 — AGENTS.md 없음

에이전트 행동 타임라인

Round 1 에이전트의 자율 판단 사항

Round 2 세션 — AGENTS.md 있음

에이전트 행동 타임라인

Round 2에서 AGENTS.md가 바꾼 것

핵심 관찰 포인트

1. grep이 사라졌다 — 탐색 전략의 변화

2. validators.py — 누락 vs 자동 포함

3. apply_patch 3회 vs 1회 — 경고 처리의 차이

4. 테스트 커버리지 — 5개 vs 15개

WE DO: 함께 실습 (15분)

단계별 진행

세션 추적 (선택 사항)

YOU DO: 독립 실습 (15분)

과제 A: Round 3 실행 및 비교 (10분)

과제 B: 나만의 AGENTS.md 규칙 실험 (5분)

빠른 참고: curl 명령어

정리: 컨텍스트 엔지니어링의 핵심

FilesExpand file tree

01-context-engineering

Directory actions

More options

Directory actions

More options

Latest commit

History

01-context-engineering

Folders and files

parent directory

README.md

Lab 01: 컨텍스트 엔지니어링 챌린지

실습 목표

실습 구성

사전 준비

I DO — 실제 세션 로그 분석 (10분)

실행한 프롬프트 (두 라운드 동일)

Round 1 세션 — AGENTS.md 없음

에이전트 행동 타임라인

Round 1 에이전트의 자율 판단 사항

Round 2 세션 — AGENTS.md 있음

에이전트 행동 타임라인

Round 2에서 AGENTS.md가 바꾼 것

핵심 관찰 포인트

1. grep이 사라졌다 — 탐색 전략의 변화

2. validators.py — 누락 vs 자동 포함

3. apply_patch 3회 vs 1회 — 경고 처리의 차이

4. 테스트 커버리지 — 5개 vs 15개

WE DO: 함께 실습 (15분)

단계별 진행

세션 추적 (선택 사항)

YOU DO: 독립 실습 (15분)

과제 A: Round 3 실행 및 비교 (10분)

과제 B: 나만의 AGENTS.md 규칙 실험 (5분)

빠른 참고: curl 명령어

정리: 컨텍스트 엔지니어링의 핵심