Context Engineering 완전 정복 (4): 실전 - 개발 워크플로우

"AI는 도구가 아니라 협업자입니다. 협업자에게는 맥락이 필요합니다."

들어가며

이전 글에서 프로젝트 셋업을 완료했습니다. CONTEXT.md가 있고, .cursorrules가 있습니다.

이제 질문은: 매일 어떻게 사용하는가?

이 글에서는 일상 개발에서 Context Engineering을 적용하는 구체적인 워크플로우를 다룹니다.

Part 1: 맥락 우선 대화 패턴

1.1 기본 원칙

Before (맥락 없음):

"로그인 기능 만들어줘"

After (맥락 우선):

"우리 시스템에서 인증 관련 작업을 하려고 해.

[현재 상황]
- Express + PostgreSQL 기반
- 현재 세션 기반 인증 사용 중
- 모바일 앱 출시 예정

[목표]
JWT 기반 인증으로 전환

[제약]
- 기존 사용자 세션 마이그레이션 필요
- 다운타임 최소화

어떤 접근이 좋을까?"

1.2 상황별 대화 패턴 10가지

1. 새 기능 구현

[맥락]
- 현재 시스템 상태
- 관련 기존 코드 위치
- 비즈니스 요구사항 배경

[요청]
"이 맥락에서 [기능]을 어떻게 구현하면 좋을까?
먼저 접근 방식을 제안해줘."

2. 버그 수정

[증상]
- 에러 메시지 또는 예상치 못한 동작
- 재현 단계

[맥락]
- 관련 코드 파일
- 최근 변경 사항

[요청]
"이 버그의 원인이 뭘까? 
수정 방향을 제안해줘."

3. 리팩토링

[현재 상태]
- 문제가 있는 코드와 그 위치
- 왜 리팩토링이 필요한지

[목표]
- 개선하고 싶은 점

[제약]
- 변경하면 안 되는 것 (API, 동작)

[요청]
"이 코드를 어떻게 개선할 수 있을까?"

4. 코드 리뷰 요청

[맥락]
- 이 코드가 하는 일
- 구현 시 고민했던 점

[요청]
"이 구현을 리뷰해줘.
특히 [성능/보안/가독성]에 대해 피드백 부탁해."

5. 아키텍처 결정

[상황]
- 해결해야 할 문제
- 고려 중인 옵션들

[제약]
- 기술적/비즈니스적 제약

[요청]
"각 옵션의 장단점을 분석해줘.
우리 상황에서 어떤 게 나을까?"

6. 테스트 작성

[대상]
- 테스트할 코드/기능

[맥락]
- 기존 테스트 패턴
- 테스트 프레임워크

[요청]
"이 기능에 대한 테스트를 작성해줘.
엣지 케이스도 포함해서."

7. 문서화

[대상]
- 문서화할 코드/API/기능

[독자]
- 누가 읽을 문서인지

[요청]
"이 [코드/API]에 대한 문서를 작성해줘.
[개발자/사용자]가 이해할 수 있도록."

8. 성능 최적화

[현재 상태]
- 성능 문제 증상
- 측정 데이터

[목표]
- 목표 성능 수치

[요청]
"이 성능 문제를 어떻게 해결할 수 있을까?
원인 분석부터 시작해줘."

9. 에러 핸들링

[맥락]
- 현재 에러 처리 방식
- 문제점

[요청]
"이 모듈의 에러 핸들링을 개선해줘.
우리 프로젝트의 에러 처리 패턴을 따라서."

10. 의존성 업데이트

[상황]
- 업데이트할 의존성
- 현재 버전 → 목표 버전

[우려]
- Breaking changes 가능성

[요청]
"이 업데이트의 영향을 분석해줘.
마이그레이션 가이드도 제안해줘."

1.3 AI가 질문하게 만들기

핵심: 불완전한 맥락을 인정하고, AI에게 질문을 요청

"사용자 프로필 수정 기능을 구현하려고 해.

내가 제공한 맥락이 충분한지 확인해줘.
구현 전에 알아야 할 것이 있으면 질문해줘."

AI의 응답 예시:

구현 전에 몇 가지 확인이 필요합니다:

1. 어떤 필드를 수정할 수 있나요? (이름, 이메일, 아바타 등)
2. 이메일 변경 시 확인 절차가 필요한가요?
3. 프로필 이미지 업로드가 포함되나요?
4. 변경 이력을 저장해야 하나요?
5. 실시간 유효성 검사가 필요한가요?

Part 2: 4단계 워크플로우

2.1 개요

Phase 1: 맥락 구축 (Context Building)
    ↓
Phase 2: 탐색적 대화 (Exploratory Conversation)
    ↓
Phase 3: 점진적 구현 (Incremental Implementation)
    ↓
Phase 4: 가드레일 구축 (Guardrails)

2.2 Phase 1: 맥락 구축

목표: AI가 효과적으로 추론할 수 있는 기반 마련

체크리스트:

□ 프로젝트 배경 설명
  - 이 프로젝트가 무엇인지
  - 현재 어떤 단계인지

□ 현재 아키텍처 공유
  - 관련 파일/모듈 구조
  - 기존 패턴

□ 문제 정의
  - 해결하려는 것이 무엇인지
  - 왜 이것이 필요한지

□ 제약 조건 명시
  - 기술적 제약
  - 비즈니스 제약
  - 시간 제약

□ 과거 시도와 결과
  - 이전에 시도한 것
  - 왜 실패했거나 변경했는지

예시:

"새 프로젝트를 시작하기 전에 맥락을 공유할게.

[프로젝트]
StoniStudio - Next.js 14 기반 기술 블로그
현재 기본 기능 완성, 검색 기능 추가 예정

[아키텍처]
- App Router 사용
- MDX로 콘텐츠 관리
- 정적 생성 (SSG)

[이번 작업]
블로그 포스트 검색 기능 구현

[제약]
- 서버리스 환경 (외부 검색 엔진 X)
- 빌드 타임에 인덱스 생성 필요
- 한글 검색 지원 필수

[과거 시도]
- Algolia 검토했으나 비용 문제로 제외
- 클라이언트 사이드 전체 검색은 번들 크기 문제"

2.3 Phase 2: 탐색적 대화

목표: 최적의 접근 방식 찾기

단계:

1. 접근 방식 제안 요청

"이 맥락에서 검색 기능을 구현하는 방법을 제안해줘.
여러 옵션이 있다면 각각의 장단점도 설명해줘."

2. 장단점 논의

"Fuse.js 방식의 단점을 더 자세히 설명해줘.
특히 한글 검색에서 문제가 될 수 있는 부분은?"

3. 추가 질문 유도

"이 접근 방식을 선택하기 전에,
내가 고려해야 할 다른 요소가 있을까?"

4. 합의 도출

"좋아, 그러면 [선택한 방식]으로 진행하자.
구현 전에 확인할 것이 더 있어?"

2.4 Phase 3: 점진적 구현

목표: 작은 단위로 구현하며 피드백 루프 유지

원칙:

한 번에 하나의 작은 단위
각 단계 후 리뷰
피드백을 다음 맥락으로

예시 흐름:

Step 1: 핵심 로직

"먼저 검색 인덱스 생성 로직부터 구현해줘.
빌드 타임에 실행되는 스크립트로."

→ 리뷰 → 피드백

Step 2: 검색 함수

"인덱스가 잘 생성되네. 
이제 이 인덱스를 사용하는 검색 함수를 만들어줘.
한글 초성 검색도 지원해야 해."

→ 리뷰 → 피드백

Step 3: UI 컴포넌트

"검색 로직이 잘 동작해.
이제 검색 UI 컴포넌트를 만들어줘.
기존 디자인 시스템을 따라서."

→ 리뷰 → 피드백

Step 4: 통합

"각 부분이 잘 동작하네.
이제 전체를 통합하고, 
헤더에 검색 버튼을 추가해줘."

2.5 Phase 4: 가드레일 구축

목표: 품질과 유지보수성 보장

체크리스트:

□ 테스트 작성
  - 단위 테스트
  - 통합 테스트
  - 엣지 케이스

□ 문서화
  - 코드 주석 (왜를 설명)
  - README 업데이트
  - API 문서 (필요시)

□ 코드 리뷰
  - 스타일 가이드 준수
  - 성능 검토
  - 보안 검토

□ 에러 핸들링
  - 예외 상황 처리
  - 사용자 친화적 에러 메시지
  - 로깅

예시:

"검색 기능 구현이 완료됐어.
이제 가드레일을 구축하자.

1. 먼저 테스트를 작성해줘
   - 검색 결과 정확성
   - 한글 초성 검색
   - 빈 결과 처리
   - 특수문자 입력

2. 그 다음 에러 핸들링을 추가해줘
   - 인덱스 로드 실패
   - 검색 타임아웃"

Part 3: Iteration에서 맥락 연속성

3.1 왜 연속성이 중요한가

문제:

세션 1: "JWT 인증 구현해줘" → 구현
세션 2: "리프레시 토큰 추가해줘" → 다른 스타일로 구현
세션 3: "로그아웃 구현해줘" → 또 다른 스타일

결과: 일관성 없는 코드, 중복, 충돌

3.2 피드백을 맥락으로 전환

패턴:

[이전 피드백]
- "에러 응답 형식을 { error: { code, message } }로 통일해줘"
- "async/await 대신 try-catch 패턴 사용"

[이번 요청]
로그아웃 API를 구현해줘.
위의 피드백을 반영해서.

3.3 결정 로그 유지

형식:

## Decision Log

### 2024-12-13: 토큰 저장 방식
**결정:** httpOnly 쿠키 사용
**이유:** XSS 방어, 자동 전송
**대안:** localStorage (보안 취약)

### 2024-12-13: 토큰 만료 시간
**결정:** Access 1시간, Refresh 7일
**이유:** 보안과 UX 균형

활용:

"로그아웃 구현 전에 우리의 결정 로그를 확인해줘.
토큰 저장 방식과 일관되게 구현해야 해."

3.4 세션 간 맥락 이어가기

세션 종료 시:

"오늘 작업을 마무리하기 전에,
다음 세션을 위한 요약을 만들어줘.

포함할 것:
- 완료한 작업
- 다음에 할 작업
- 미해결 이슈
- 주요 결정 사항"

다음 세션 시작 시:

"이전 세션 요약이야:

[완료]
- JWT 인증 기본 구조
- 로그인/로그아웃 API

[다음]
- 리프레시 토큰 로직
- 토큰 갱신 미들웨어

[미해결]
- Redis 연결 설정 필요

[결정]
- httpOnly 쿠키 사용
- Access 1시간, Refresh 7일

이 맥락에서 리프레시 토큰 로직을 구현하자."

Part 4: 실제 시나리오 워크스루

4.1 시나리오: 새 기능 개발

상황: 블로그에 댓글 기능 추가

Phase 1: 맥락 구축

"댓글 기능을 추가하려고 해.

[현재 상태]
- Next.js 14 정적 블로그
- 서버리스 환경 (Vercel)
- 인증 시스템 없음

[요구사항]
- 익명 댓글 허용
- 스팸 방지 필요
- 실시간 업데이트 불필요

[제약]
- 서버리스이므로 DB 연결 제한
- 비용 최소화
- 관리 부담 최소화"

Phase 2: 탐색적 대화

AI: "몇 가지 옵션을 제안합니다:

1. Giscus (GitHub Discussions 기반)
   - 장점: 무료, 관리 불필요, 마크다운 지원
   - 단점: GitHub 계정 필요

2. Utterances (GitHub Issues 기반)
   - 장점: 무료, 간단
   - 단점: GitHub 계정 필요, 기능 제한

3. 자체 구현 + Supabase
   - 장점: 완전한 제어
   - 단점: 구현/관리 비용

어떤 방향이 좋을까요?"

나: "Giscus가 좋겠어. GitHub 계정 요구는 스팸 방지에도 도움이 될 것 같아."

Phase 3: 점진적 구현

나: "Giscus를 설정해줘. 먼저 GitHub Discussions 설정부터."

AI: [설정 가이드 제공]

나: "좋아, 이제 React 컴포넌트를 만들어줘."

AI: [컴포넌트 코드 제공]

나: "다크 모드 지원도 추가해줘. 우리 블로그 테마와 연동되게."

AI: [수정된 코드 제공]

Phase 4: 가드레일

나: "잘 동작해. 마무리하자.
- 로딩 상태 처리
- 에러 시 폴백 UI
- 접근성 확인"

결론

핵심 요약

맥락 우선 대화
- 요청 전에 맥락 제공
- AI가 질문하게 유도
- 10가지 상황별 패턴 활용
4단계 워크플로우
- 맥락 구축 → 탐색 → 점진적 구현 → 가드레일
- 각 단계에서 피드백 루프
맥락 연속성
- 피드백을 맥락으로 전환
- 결정 로그 유지
- 세션 간 요약 전달

다음 글 미리보기

Article 5: Context Engineering 고급 - 팀과 시스템에서는:

팀 레벨 Context Engineering
복잡한 시스템에서의 맥락 관리
Reference Application 패턴
Team of Agents 패턴

이 워크플로우를 적용해보셨나요? 어떤 패턴이 가장 효과적이었나요? 경험을 공유해주세요.