"하네스 엔지니어링 기초 (3/4) — 프롬프트보다 중요한 컨텍스트 설계와 지시 파일"

-

많은 팀이 에이전트 품질 문제를 "프롬프트를 더 길게 쓰면 되나?"로 접근한다. 하지만 실전에서 더 자주 중요한 것은 문장을 늘리는 일이 아니라, 어떤 규칙은 항상 보이게 두고 어떤 정보는 필요할 때만 읽히게 만드는 구조다. 좋은 지시 파일은 백과사전이 아니라 표지판에 가깝다.

핵심 요약

  • 프롬프트 엔지니어링이 한 번의 입력 문장을 다듬는 일이라면, 컨텍스트 설계는 작업 전체에서 어떤 정보가 언제 들어오는지 설계하는 일이다.
  • AGENTS.md, CLAUDE.md, 스킬, handoff 문서는 같은 역할을 하지 않는다. 공유 규칙, 런타임 규칙, 반복 절차, 변하는 상태를 분리해야 한다.
  • 컨텍스트는 희소 자원이므로, 많이 넣는 것보다 필요한 시점에 필요한 것만 보여 주는 구조가 더 강하다.
  • 긴 지시 파일은 안정감을 주는 것처럼 보여도, 실제로는 중요한 규칙을 묻히고 세션 시작 비용을 키우기 쉽다.
  • 따라서 좋은 지시 구조는 "무엇을 쓰느냐"보다 "무엇을 어디에 두느냐"의 문제다.

1. 왜 프롬프트보다 구조가 먼저인가

A2에서 본 것처럼 에이전트는 한 번의 질문과 답변으로 끝나지 않는다. 여러 턴을 돌면서 자료를 읽고, 도구를 호출하고, 결과를 다시 판단한다. 이때 성능을 좌우하는 것은 멋진 한 문장보다 입력이 반복적으로 조립되는 방식이다.

그래서 컨텍스트 설계는 프롬프트의 확장판이 아니다. 오히려 프롬프트를 포함한 더 큰 작업 설계에 가깝다.

질문 긴 프롬프트 중심 접근 컨텍스트 설계 중심 접근
목표 한 번에 다 설명한다 필요한 정보를 층별로 배치한다
기본 가정 많이 말하면 더 잘 안다 많이 넣으면 오히려 묻힐 수 있다
실패 방식 장황하고 충돌하는 지시 필요한 자료를 늦게 보거나 못 본다
개선 방식 문장 추가 구조 분리, 참조화, 필요 시 로드

즉, 좋은 에이전트는 장문 프롬프트를 가진 에이전트가 아니라, 정확한 컨텍스트 배선을 가진 에이전트에 가깝다.

2. 지시 파일은 같은 문서가 아니라 역할이 다른 층이다

활용 노트와 시리즈 설계 문서가 공통으로 강조하는 부분은 분명하다. 지시와 문맥과 메모리를 한 파일에 다 쌓으면 안 된다. 이유는 성격이 다르기 때문이다.

이 저장소 기준으로 보면 최소한 네 층으로 나누는 편이 자연스럽다.

층 대표 예시 역할
공유 규칙 AGENTS.md 프로젝트 경계, 금지사항, 역할 정책
런타임 규칙 CLAUDE.md 계열 작업 흐름, 우선순위, 실행 습관
반복 절차 스킬, 체크리스트, 템플릿 자주 반복되는 절차의 캡슐화
변하는 상태 tasks/plan.md, tasks/handoffs/, tasks/sessions/ 현재 진행 상태와 다음 재개 지점

이 구분은 문서 분류 취미가 아니라 성능 문제다.

  • 공유 규칙은 자주 바뀌면 안 된다.
  • 런타임 규칙은 작업 방식을 안내하지만 너무 길면 안 된다.
  • 반복 절차는 필요할 때만 불러오면 된다.
  • 변하는 상태는 오래 남아야 하지만 항상 상시 주입할 필요는 없다.

이 층을 섞어 두면 에이전트는 "항상 봐야 할 것"과 "이번에만 필요한 것"을 구분하기 어려워진다.

3. 좋은 지시 파일은 백과사전이 아니라 지도다

기존 초안과 활용 노트에서 특히 반복되는 문장이 있다. AGENTS.md나 CLAUDE.md는 백과사전이 아니라 지도여야 한다는 점이다.

왜 그럴까.

3.1 긴 문서는 시작 비용을 계속 올린다

상시 읽히는 문서가 길면, 매 세션마다 중요한 토큰 예산을 먼저 소비한다.

3.2 중요한 규칙이 묻힌다

정말 지켜야 할 한두 개의 원칙이 수십 개의 부가 설명 속으로 숨어 버린다.

3.3 변하는 내용을 넣기 시작하면 빠르게 낡는다

상태 정보, 임시 결정, 예외 상황까지 지시 파일에 밀어 넣으면 문서는 금방 신뢰를 잃는다.

그래서 좋은 지시 파일은 대체로 다음 특징을 가진다.

  • 짧다
  • 역할이 분명하다
  • 금지와 우선순위가 선명하다
  • 세부 절차는 별도 문서나 스킬로 보낸다
  • 변하는 상태는 handoff나 plan 문서로 분리한다

즉, 지시 파일의 목적은 모든 걸 설명하는 일이 아니라, 에이전트가 길을 잃지 않게 하는 것이다.

4. 컨텍스트는 "항상 보이는 것"과 "필요할 때 읽는 것"으로 나뉜다

좋은 컨텍스트 설계는 정보량 경쟁이 아니다. 정보 배치 설계다. 가장 실용적인 구분은 아래 두 가지다.

구분 무엇이 들어가나 설계 원칙
항상 보이는 컨텍스트 핵심 역할, 금지사항, 출력 규칙, 현재 작업 목표 짧고 안정적이어야 한다
필요할 때 읽는 컨텍스트 상세 문서, 긴 참고 자료, 과거 세션 기록, 대용량 결과 참조 경로를 주고 필요한 순간에만 로드한다

이 구분이 중요한 이유는 에이전트가 모든 것을 동시에 가장 잘 이해하지 못하기 때문이다. 많은 경우 더 잘하는 방식은 "지금 당장 꼭 필요한 것만 앞에 두고, 나머지는 경로로 연결하는 것"이다.

우리 저장소 문서 구조도 같은 방향이다.

  • 지금 해야 할 일은 tasks/plan.md
  • 기억 지점은 docs/memory-map.md
  • 이전 세션 상태는 tasks/sessions/
  • 장기 규칙은 AGENTS.md

이렇게 나뉘어 있으면 새 세션도 비교적 빠르게 재진입할 수 있다.

5. 무엇을 어디에 둘 것인가

지시 구조를 설계할 때 가장 자주 나오는 질문은 이것이다. "도대체 이 내용은 어느 파일에 둬야 하나?"

실전에서는 아래 기준이 가장 단순하고 강하다.

AGENTS.md에 둘 것

  • 프로젝트 전체 금지사항
  • 역할 정책
  • 언어 규칙
  • 절대 넘으면 안 되는 경계

CLAUDE.md 계열에 둘 것

  • 작업 순서
  • 우선 읽을 문서
  • 수정/검증 습관
  • 도구 사용 기본 규칙

스킬이나 별도 문서에 둘 것

  • 긴 절차
  • 드문 작업 플로우
  • 예시가 많은 작업
  • 필요 시만 불러오면 되는 운영 지식

tasks/ 계열에 둘 것

  • 지금 진행 중인 상태
  • 다음 세션이 이어받을 포인트
  • 열린 리스크와 미해결 질문

이 구분이 깔끔할수록 에이전트는 현재 턴에서 중요한 것에 더 집중할 수 있다.

6. 나쁜 컨텍스트 설계가 만드는 흔한 증상

컨텍스트 설계가 잘못되면 모델이 이상해 보이지만, 실제 원인은 구조에 있다. 자주 보이는 증상은 다음과 같다.

6.1 자꾸 규칙을 놓친다

핵심 규칙이 상시 문맥에서 묻혔거나, 여러 파일에 충돌 형태로 흩어져 있을 가능성이 높다.

6.2 쓸데없는 긴 답을 만든다

입력이 길고 우선순위가 불명확하면, 모델도 무엇을 핵심으로 압축해야 할지 헷갈린다.

6.3 매 세션이 워밍업처럼 느리다

항상 읽는 지시 파일이 너무 크거나, 지금 안 필요한 자료까지 상시 주입하고 있을 수 있다.

6.4 이전 작업을 매번 다시 추론한다

상태를 handoff 파일로 남기지 않고 대화 이력에만 의존하면 이런 현상이 반복된다.

7. 실무 적용: 지시 구조를 설계할 때의 체크리스트

입문 단계에서는 복잡한 프레임워크보다 아래 질문이 더 유용하다.

  1. 이 규칙은 항상 보여야 하나, 필요할 때만 읽히면 되나?
  2. 이 내용은 프로젝트 공통 규칙인가, 이번 작업의 상태인가?
  3. 이 절차는 매번 장문으로 설명할 일인가, 별도 스킬로 분리할 일인가?
  4. 이 문서는 지금 길어서 좋은가, 아니면 핵심 규칙을 가리고 있는가?
  5. 다음 세션이 이 문서만 보고도 재개할 수 있는가?

이 질문만으로도 문서 구조가 상당히 정리된다.

8. 결국 프롬프트보다 중요한 것은 배치다

프롬프트 엔지니어링이 쓸모없다는 뜻은 아니다. 다만 에이전트 환경에서는 프롬프트를 잘 쓰는 것만으로는 충분하지 않다. 좋은 문장도 잘못된 구조 안에 들어가면 효과가 약해진다.

반대로 구조가 좋으면 짧은 지시도 강해진다.

  • 상위 규칙은 짧게 고정하고
  • 자주 변하는 상태는 별도 ledger로 분리하고
  • 세부 절차는 스킬이나 참조 문서로 빼고
  • 필요 시 로드 구조를 만들면

에이전트는 훨씬 적은 토큰으로도 더 안정적으로 움직일 수 있다.

이 지점이 바로 "프롬프트 엔지니어링"에서 "하네스 엔지니어링"으로 넘어가는 분기점이다.

참고 자료

  • docs/blog_series_하네스엔지니어링_총괄_design.md
  • sources/260518_하네스엔지니어링_15장_블로그활용노트.md
  • drafts/blog/260429_하네스시리즈02_컨텍스트엔지니어링_블로그.md
  • WikiDocs, 하네스 엔지니어링 백과사전 3장 활용 메모

이 글은 하네스 엔지니어링 기초 시리즈의 3/4 편입니다. 다음 편: MCP와 도구 엔지니어링, 그리고 도구 표면을 설계하는 법.

시리즈 전체 안내: 하네스 엔지니어링 시리즈 안내

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »