컨텍스트 엔지니어링 실무 가이드: 프롬프트보다 먼저 정리해야 할 것들

요즘 AI 실무에서 자주 나오는 말이 프롬프트 엔지니어링보다 컨텍스트 엔지니어링입니다. 이유는 단순합니다. 좋은 모델도 맥락이 엉망이면 계속 헛다리를 짚기 때문입니다. 같은 모델인데 어떤 팀은 생산성이 올라가고, 어떤 팀은 “생각보다 별로네”에서 멈추는 이유도 여기 있습니다. 결국 차이는 질문 재능이 아니라, 모델이 참고할 정보를 어떻게 정리해 넣느냐에 달려 있습니다.

프롬프트 엔지니어링만으로는 왜 한계가 있나

짧은 데모에서는 한 줄 프롬프트가 잘 먹힙니다. 하지만 실제 업무는 다릅니다. 모델은 작업 지시만 필요한 게 아니라 아래 정보가 같이 필요합니다.

• 이 작업의 목표와 성공 조건
• 현재 시스템 구조와 제약
• 이미 시도한 방법과 실패 이유
• 수정하면 안 되는 파일이나 규칙
• 출력 형식과 리뷰 기준

이게 빠지면 모델은 그럴듯한 일반론을 내놓습니다. 문제는 실무에서는 일반론이 가장 비싼 실패라는 점입니다. 다시 설명해야 하고, 다시 수정해야 하고, 결국 사람이 직접 정리하게 됩니다.

그래서 이제 중요한 건 “어떻게 질문할까”보다 “어떤 맥락을 어떤 순서로 넣을까”입니다.

실무에서 바로 먹히는 컨텍스트 구성 5단계

1) 목표를 한 문장으로 고정한다

좋은 컨텍스트의 시작은 길고 친절한 설명이 아닙니다. 목표를 좁게 고정하는 것입니다. 예를 들어 “로그인 기능 개선해줘”는 너무 넓습니다. 대신 “이메일 로그인 실패 시 사용자에게 이유를 보여주고, 서버 에러 메시지는 노출하지 않도록 React 화면과 API 응답 매핑을 수정해줘”처럼 써야 합니다.

목표가 좁을수록 모델이 불필요한 파일을 덜 건드리고, 결과 검증도 쉬워집니다.

2) 제약 조건을 먼저 준다

모델은 가능한 해법을 많이 떠올리지만, 팀은 가능한 해법이 아니라 허용된 해법이 필요합니다. 그래서 아래 제약을 먼저 주는 게 중요합니다.

• 사용 가능한 언어와 프레임워크 버전
• 수정 가능한 파일 범위
• 금지 패턴과 팀 규칙
• 성능, 보안, 접근성 요구사항
• 테스트 통과 조건

이 부분이 빠지면 모델은 “맞는 것 같은데 우리 팀에서는 못 쓰는 답”을 자주 냅니다.

3) 참고 자료는 길게 말고 계층적으로 준다

컨텍스트를 많이 넣는다고 좋은 게 아닙니다. 핵심은 계층화입니다.

1. 작업 목표
2. 제약 조건
3. 관련 파일 요약
4. 필요한 원문 코드 일부
5. 기대 출력 형식

이 순서를 지키면 모델이 중요한 정보를 먼저 잡습니다. 반대로 긴 로그, 긴 문서, 긴 코드부터 넣으면 정작 핵심 목표를 흐리게 읽는 경우가 많습니다.

4) “무엇을 하지 말아야 하는지”를 꼭 적는다

실무에서 가장 자주 터지는 문제는 과도한 수정입니다. 작은 버그 하나 고치라고 했는데 모델이 구조를 통째로 바꾸는 경우가 대표적입니다. 그래서 금지 항목이 꼭 필요합니다.

예를 들면 이런 식입니다.

• API 스키마는 바꾸지 말 것
• CSS 리팩터링은 이번 작업 범위에서 제외
• 새 라이브러리 추가 금지
• 테스트 코드가 없으면 생성만 하고 기존 로직은 건드리지 말 것

하지 말아야 할 일을 먼저 정하면, 모델이 과하게 똑똑해지려는 문제를 줄일 수 있습니다.

5) 출력 형식을 정해준다

“수정해줘”보다 “원인 3줄, 수정 파일 목록, 패치 내용, 테스트 방법 순서로 답해줘”가 훨씬 낫습니다. 출력 형식이 고정되면 사람이 검토하기 쉽고, 다음 자동화 단계로 넘기기도 좋아집니다. 특히 팀 단위로 쓸 때는 출력 템플릿 통일이 중요합니다.

컨텍스트 품질을 높이는 운영 습관

첫째, 반복되는 프로젝트 정보는 별도 파일로 뺍니다. 아키텍처 요약, 코딩 규칙, 배포 금지 사항, 자주 틀리는 패턴을 문서로 만들어두면 매번 다시 설명할 필요가 없습니다.

둘째, 실패한 지시문도 저장합니다. 잘 먹힌 프롬프트만 모으는 팀보다, 어디서 실패했는지 기록하는 팀이 더 빨리 좋아집니다. 모델은 비슷한 실수를 반복하기 때문입니다.

셋째, 사람이 읽어도 좋은 컨텍스트를 목표로 해야 합니다. 너무 복잡한 프롬프트는 사람도 못 읽습니다. 사람이 이해하기 어려운 구조라면 모델도 흔들릴 가능성이 큽니다.

넷째, 긴 대화보다 작업 단위를 자주 끊는 게 낫습니다. 한 세션에서 모든 걸 해결하려고 하면 앞뒤 맥락이 섞이고 품질이 떨어집니다. 작업을 쪼개고, 각 작업에 필요한 맥락만 넣는 편이 안정적입니다.

자주 나오는 안 좋은 예

나쁜 예는 보통 이렇습니다. “이 코드 좀 개선해줘. 성능도 올리고, 리팩터링도 하고, 버그도 잡고, 보기 좋게 정리해줘.” 이 문장에는 목표도 없고, 범위도 없고, 성공 조건도 없습니다. 모델 입장에서는 아무거나 해도 맞는 것처럼 보입니다.

좋은 예는 이렇게 바뀝니다. “상품 목록 페이지에서 필터 변경 시 중복 요청이 발생한다. ProductList.tsx와 관련 hook만 수정하고, API 스펙은 바꾸지 말 것. 목표는 필터 1회 변경당 요청 1회만 나가게 하는 것. 수정 이유, 변경 파일, 테스트 방법 순서로 답할 것.”

둘의 차이는 문장력보다 운영 사고방식입니다.

지금 바로 적용할 체크리스트

• 작업 목표를 한 문장으로 좁게 정의했는가
• 제약 조건을 목표보다 뒤가 아니라 앞에서 제시했는가
• 관련 자료를 목표 → 제약 → 파일 요약 → 원문 순으로 정리했는가
• “하지 말 것” 항목을 별도로 적었는가
• 출력 형식을 고정했는가
• 반복 프로젝트 정보는 별도 문서로 분리했는가
• 실패한 컨텍스트 예시도 기록하고 있는가
• 한 번에 너무 많은 작업을 한 세션에 넣고 있지 않은가

컨텍스트 엔지니어링은 거창한 기술이 아닙니다. 모델이 덜 틀리게 만드는 정보 정리 습관입니다. 프롬프트를 더 세게 쓰는 것보다, 목표·제약·자료·금지·출력 형식을 잘 정리하는 편이 실무 성과가 훨씬 큽니다. AI가 기대보다 덜 유용했다면, 모델 탓보다 먼저 컨텍스트 설계를 점검해보는 게 맞습니다.