msd-core/docs/ko-KR/explanation/context-engineering.md

컨텍스트 엔지니어링

MSD Core가 존재하는 이유와 해결하고자 하는 문제.

---

문제: 컨텍스트 부패

모든 AI 코딩 세션은 새롭게 시작된다. 모델은 질문을 읽고, 추론하고, 답변을 돌려준다. 그러나 하나의 세션이 단 한 번의 교환으로 끝나는 경우는 드물다. 추가 질문을 던지고, 오류 메시지를 붙여넣고, 코드를 반복적으로 개선하며, 모델이 엉뚱한 방향으로 흘러갈 때 방향을 바로잡는다. 각 대화 차례마다 토큰이 컨텍스트 윈도우에 쌓인다 — 모델이 한 번에 "볼 수" 있는 유한한 텍스트 버퍼.

이 윈도우가 채워지면 미묘한 일이 벌어진다. 모델은 요란하게 실패하지 않는다. 계속해서 답변을 생성한다. 하지만 답변의 품질은 서서히 저하된다. 초반에 주어진 지시 사항이 모델이 집중할 수 있는 범위의 가장자리로 밀려난다. 처음 몇 번의 교환에서 다뤘던 뉘앙스들 — 제시했던 제약 조건, 합의한 아키텍처, 언급했던 엣지 케이스들 — 이 이후에 쌓인 모든 내용과 주의를 경쟁하게 된다. 연구자들은 이를 **컨텍스트 부패(context rot)**라고 부른다.

컨텍스트 부패는 여러 형태로 나타난다.

• 모델이 이전에 인정했던 결정들을 모순되게 다루기 시작한다.
• 코드 스타일이 세션 초반에 확립한 컨벤션에서 벗어난다.
• 계획이 명확하게 명시되었지만 이제 깊이 묻혀버린 요구 사항들을 무시하기 시작한다.
• 모델이 20개의 메시지 전에는 정확히 알고 있던 파일 이름이나 함수 시그니처를 환각으로 만들어낸다.

이것은 모델 버그가 아니다. 긴 시퀀스에서 트랜스포머 어텐션이 작동하는 방식의 근본적인 특성이다. 모델은 "잊어버리는" 것이 아니다 — 인간적 의미에서의 "기억"은 애초에 없었다. 유한한 윈도우 안에서 관련성에 가중치를 부여하고 있으며, 누적된 노이즈로 윈도우가 채워질수록 신호 대 잡음비가 저하된다.

단순한 대응책은 /clear로 세션을 초기화하는 것이다. 그러나 그러면 연속성을 잃는다. 컨텍스트를 다시 설명하고, 관련 파일을 다시 붙여넣고, 제약 조건을 다시 명시해야 한다. 세션이 사실상 제로부터 다시 시작된다.

---

MSD Core의 답: 신선한 컨텍스트 서브에이전트

MSD Core의 핵심적인 통찰은 코딩 세션에서 이루어지는 작업의 대부분이 메인 컨텍스트에서 이루어질 필요가 없다는 것이다. 리서치, 계획 수립, 코드 작성, 검증은 각각 독립적이고 범위가 한정된 작업들이다. 각각을 깔끔하고 신중하게 범위가 지정된 컨텍스트 윈도우로 시작하는 전문화된 서브에이전트에게 넘기고 — 결과를 효율적으로 유지되는 얇은 오케스트레이터에게 보고할 수 있다.

이것은 컨텍스트 부패를 위한 임시방편이 아니다. 구조적인 해결책이다.

오케스트레이터 — 메인 세션 — 는 소스 파일을 직접 다루지 않는다. 에이전트를 생성하고, 결과를 수집하며, 공유 상태를 업데이트하고, 다음 단계로 라우팅한다. 오케스트레이터가 스스로 하는 작업이 매우 적기 때문에 컨텍스트 윈도우가 느리고 예측 가능하게 증가한다. 무거운 작업은 각각 신선하게 시작하고, 자신의 작업에 필요한 정확한 컨텍스트만 받고, 완료 시 종료하는 에이전트에서 수행된다.

실제로 어떤 의미인지 생각해보자. /msd-plan-phase를 실행하면 오케스트레이터는:

1. 압축된 JSON 컨텍스트 페이로드(프로젝트 요약, 단계 목표, 관련 설정)를 로드한다.
2. 200k 토큰의 깨끗한 윈도우로 리서처 에이전트를 생성한다.
3. 리서치 출력물과 단계 요구 사항을 가진 플래너 에이전트를 생성한다.
4. 실행 전에 계획을 검증하는 계획 검사기 에이전트를 생성한다.

각 에이전트는 세션의 누적된 이력으로 부담받지 않고, 최대 능력으로 작동한다. 플래너가 PLAN.md 파일들을 .planning/phases/에 작성할 때, 그 출력물은 내구성 있는 결과물이 된다 — 공유 컨텍스트 윈도우 속에서 깨지기 쉬운 기억이 아니라.

---

명세 주도 개발과 메타 프롬프팅

컨텍스트 엔지니어링만으로는 충분하지 않다. 에이전트가 신선하게 시작하더라도 모호한 지시 사항을 받으면 모호한 결과물을 생성한다. MSD Core는 신선한 컨텍스트 서브에이전트와 두 가지 보완적인 원칙을 함께 사용한다.

명세 주도 개발은 모든 단계가 실행 전에 구조화된 결과물을 생성한다는 것을 의미한다. CONTEXT.md는 논의 단계의 구현 결정 사항들을 캡처한다. RESEARCH.md는 리서처가 발견한 내용을 기록한다. PLAN.md는 명시적인 수락 기준을 가진 개별적인 의존성 순서의 작업들로 작업을 분해한다. 실행 에이전트가 파일에 손을 대는 시점에는 긴 대화의 재해석이 아닌 정확한 명세를 가지고 있다.

메타 프롬프팅은 에이전트 정의 자체가 애드혹 지시 사항이 아닌 신중하게 설계된 프롬프트라는 것을 의미한다. msd-core/workflows/와 agents/의 파일들은 작업의 범위를 지정하는 방법, 무엇을 검증해야 하는지, 언제 사람에게 체크포인트를 요청해야 하는지에 대한 소중한 지식을 담고 있다. 사용자는 매 세션마다 이 지식을 다시 설명할 필요가 없다; 그것은 시스템 자체의 프롬프트에 이미 내장되어 있다.

이 조합은 의도적이다. 신선한 컨텍스트는 각 에이전트가 명확하게 추론하도록 보장한다. 명세 주도 결과물은 각 에이전트가 올바른 것에 대해 추론하도록 보장한다. 메타 프롬프팅은 각 에이전트가 어떻게 잘 추론해야 하는지 알도록 보장한다.

---

.planning/의 역할

컨텍스트 엔지니어링은 지식이 컨텍스트 리셋을 통해 살아남아야 한다는 것을 요구한다. MSD Core는 이를 위해 파일 시스템을 사용한다. 모든 의미 있는 출력물은 사람이 읽을 수 있는 마크다운 또는 JSON으로 .planning/에 작성된다. 이것은 다음을 의미한다.

• 세션을 다시 시작하거나 모델이 충돌해도 작업이 손실되지 않는다.
• 모든 이후 에이전트는 공유 대화 이력에 의존하지 않고 이전 결과물을 직접 읽을 수 있다.
• 계획 결과물을 git에 검사, 편집 또는 커밋할 수 있다 — 데이터베이스의 불투명한 상태가 아닌 평문 텍스트이다.

STATE.md는 이 시스템의 중추이다. 프로젝트의 현재 위치(어느 마일스톤, 어느 단계, 어느 계획이 완료되었는지), 활성 결정 사항과 장애물, 진행 지표를 기록한다. 모든 워크플로우가 시작될 때 STATE.md를 읽어 방향을 잡는다. 모든 워크플로우가 의미 있는 단계를 완료할 때 STATE.md에 다시 기록한다. 에이전트는 기억에 의존하지 않는다; 파일에 의존한다.

---

트레이드오프

여기서 트레이드오프에 대한 솔직함이 중요하다.

오버헤드. 단계 루프는 실제 마찰을 야기한다. /msd-discuss-phase, /msd-plan-phase, /msd-execute-phase를 별도의 단계로 실행하는 것은 단순 세션에 "이 기능을 작성해줘"라고 입력하는 것보다 더 많은 경과 시간이 걸린다. 작고 잘 이해된 변경의 경우 그 오버헤드는 정당화되지 않는다.

지연. 신선한 컨텍스트로 여러 서브에이전트를 생성하는 것은 단일 인-컨텍스트 편집보다 느리다. 리서치, 계획 수립, 실행 각각에 왕복 비용이 발생한다.

단순한 작업에 대한 의례. 변수 이름을 바꾸거나, 오타를 수정하거나, 누락된 임포트를 추가해야 할 때 단계 루프는 과도하다. MSD Core는 전체 단계를 필요로 하지 않는 임시 작업을 위해 /msd-quick과 /msd-fast를 제공한다. 빠른 작업 처리하기를 참조하라.

단계 루프는 컨텍스트 부패가 실제 위험인 만큼 복잡한 작업 — 다중 파일 기능, 횡단 관심사 리팩터링, 몇 시간 또는 여러 세션에 걸친 작업 — 에서 그 가치를 발휘한다. 그 외의 경우에는 더 가벼운 기본 도구를 사용하라.

유용한 경험 법칙: 단일 짧은 프롬프트로 완전히 명시되고 더 이상의 설명 없이 에이전트 한 번의 작업으로 완료될 수 있다면, 단계 루프를 건너뛰어라. 리서치가 필요하거나, 최근에 읽지 않은 파일이 포함되거나, 아직 결정되지 않은 사항에 의존한다면, 단계 루프가 보호해준다.

---

Related

• 단계 루프 — 논의 → 계획 → 실행 → 검증 → 출시 사이클이 컨텍스트 엔지니어링을 실천에 옮기는 방법
• 다중 에이전트 오케스트레이션 — 서브에이전트가 생성, 범위 지정, 조율되는 방법
• 아키텍처 — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
• 문서 인덱스