컨텍스트 엔지니어링 실패모드 위키

Manus 실전 교훈 — KV-캐시 · 파일시스템 · 로짓 마스킹 · Attention Recitation

10 min read

상위: 06_00_MOC

Manus 실전 교훈 — KV-캐시 · 파일시스템 · 로짓 마스킹 · Attention Recitation

한 줄 요약

Manus(Yichao ‘Peak’ Ji, 2025)는 프로덕션 에이전트를 운영하며 얻은 가장 실용적인 컨텍스트 엔지니어링 교훈을 공개했다. KV-캐시 히트율을 가장 중요한 단일 지표로 삼고, 파일시스템을 무한 컨텍스트로 취급하며, 실패 흔적을 일부러 남겨 두는 반직관적 원칙이 그 핵심이다.

“The KV-cache hit rate is the single most important metric for a production-stage AI agent.” — Yichao ‘Peak’ Ji, Manus, 2025

1. KV-캐시 — 프로덕션의 경제적 핵심

1-1. 비용 구조

트랜스포머의 Key-Value 캐시는 이전 토큰들의 어텐션 계산 결과를 재사용해 비용을 절감한다. Claude Sonnet 기준:

상태비용상대 비율
캐시 적중 (Hit)$0.30/MTok1×
캐시 미적중 (Miss)$3.00/MTok10×

Manus의 입출력 토큰 비율은 100:1로 입력이 압도적이다. 이런 환경에서는 캐시 히트율이 비용과 지연 시간을 동시에 좌우한다.

1-2. KV-캐시 보존 4원칙

flowchart LR
    P1["① 시스템 프롬프트<br/>앞부분 안정화<br/>타임스탬프 등 금지"]
    P2["② Append-Only 컨텍스트<br/>과거 내용 절대 수정 금지"]
    P3["③ 결정론적 직렬화<br/>JSON 필드 순서 고정"]
    P4["④ 도구 목록 고정<br/>+ 로짓 마스킹<br/>(디코딩 단계)"]

    P1 --> P2 --> P3 --> P4 --> RESULT["캐시 히트율 최대화<br/>비용 10× 절감"]

원칙 ① — 시스템 프롬프트 앞부분 안정화

캐시는 프롬프트의 접두사(prefix)가 동일할 때 적중한다. 흔히 저지르는 실수는 다음과 같다.

  • 시스템 프롬프트 첫 줄에 현재 시각: {datetime}을 삽입하면 매 요청마다 캐시가 깨진다.
  • 동적 사용자 ID나 세션 토큰을 끼워 넣어도 결과는 같다.

원칙 ② — Append-Only 컨텍스트

과거의 액션과 관측값은 절대 수정하지 않고, 새 내용은 항상 끝에만 덧붙인다. 중간 토큰이 한 번 바뀌면 그 뒤의 캐시가 연쇄적으로 무효화된다.

원칙 ③ — 결정론적 직렬화

같은 데이터라도 직렬화 형태가 달라지면 캐시 미적중이 발생한다.

  • JSON 필드 순서가 바뀌면 미적중.
  • 공백이나 줄바꿈이 어긋나도 미적중.
  • 언어 모델이 생성한 JSON은 특히 주의해야 한다.

원칙 ④ — 로짓 마스킹 (Logit Masking)

도구 목록을 컨텍스트에서 동적으로 빼고 더하는 대신, 디코딩 단계에서 특정 토큰의 logit 점수를 억제해 해당 도구 호출 자체를 막는다.

  • 컨텍스트 자체는 건드리지 않으므로 KV-캐시가 보존된다.
  • 도구 정의가 늘 컨텍스트에 남아 있어 모델이 도구 목록을 항상 인식한다.

한계: 서버사이드 디코딩 개입이 필요하다. logit_bias API 파라미터가 없는 폐쇄형 환경이라면 출력을 파싱한 뒤 재시도하는 클라이언트사이드 대안을 고려한다.

2. 파일시스템 — 무한 컨텍스트

“We treat the file system as the ultimate context in Manus: unlimited in size, persistent by nature.” — Ji, Manus, 2025

2-1. 복원 가능한 압축 (Restorable Compression)

flowchart LR
    OBS["대용량 관측값<br/>(웹페이지·PDF·이미지<br/>수천 토큰)"] -->|"파일 저장"| FS["파일시스템<br/>(무제한·영속적)"]
    FS -->|"경로·URL만"| CTX["컨텍스트 창<br/>(수 토큰)"]
    CTX -->|"필요 시 복원"| FS

일반 압축과의 차이는 이렇다.

  • 일반 Compress: 요약하면 원본을 복원할 수 없고 정보가 손실된다.
  • Restorable Compression: 파일로 저장하고 경로만 남기므로 언제든 원본을 복원할 수 있고 손실이 없다.

“The content of a web page can be dropped from the context as long as the URL is preserved.” — Ji, 2025

2-2. 파일시스템이 제공하는 4가지 속성

속성설명
무제한 크기컨텍스트 창과 달리 이론적 상한 없음
영속성세션 간 지속, 에이전트 재시작 후에도 유지
복원 가능성경로로 언제든 원본 접근
에이전트 학습모델이 파일 읽기/쓰기를 on-demand로 수행하도록 훈련

3. Attention Recitation — todo.md 패턴

“Lost-in-the-Middle” 문제(05 부패)에 대한 Manus의 실용적 해법이다.

“By reciting its objectives and progress into the end of the context, the model’s attention is biased towards its global plan.” — Ji, Manus, 2025

sequenceDiagram
    participant A as Agent
    participant T as todo.md
    participant C as Context Window (끝부분)

    A->>T: 초기 목표 작성
    loop 각 실행 단계
        A->>T: 진행상황 업데이트 (완료 항목 체크)
        A->>C: todo.md 내용을 컨텍스트 끝에 재기록
        Note over C: 모델 어텐션이 전역 계획으로 편향
        Note over C: 긴 컨텍스트 중간 정보 무시 방지
    end

효과는 50단계가 넘는 복잡한 태스크에서 특히 두드러진다. 트랜스포머의 어텐션은 최근 토큰에 더 높은 가중치를 두는 경향이 있어서, 목표를 끝부분에 다시 적어 두면 전역 계획이 늘 “최근 정보”로 남는다.

4. 실패 흔적 보존 — 반직관적 원칙

“Erasing failure removes evidence. And without evidence, the model can’t adapt.” — Ji, Manus, 2025

실패한 액션과 스택 트레이스를 컨텍스트에서 지우지 않는다. 그러면 모델이 오류 패턴을 암묵적으로 학습해 비슷한 실수를 피한다.

01 오염과의 경계는 다음과 같다.

유형처리기준
실패 흔적·스택 트레이스보존모델 적응에 도움이 되는 증거
환각·잘못된 사실제거모델을 오도하는 허위 정보

가르는 기준은 하나다. 그 정보가 모델의 올바른 적응을 돕는가, 아니면 엉뚱한 방향으로 이끄는가.

5. 직렬화 변이 — 과일반화 방지

반복 태스크에서 같은 직렬화 템플릿을 계속 쓰면 모델이 그 패턴을 모방해 비최적 행동을 보인다.

“Introduce structured variation in serialization templates and phrasing to break the pattern and tweak the model’s attention, preventing drift during batch operations.” — Ji, Manus, 2025

  • 의미가 같더라도 표현 방식에 의도적으로 약간의 변이를 준다.
  • 특히 대량 배치 작업에서 어텐션 패턴이 굳는 것을 막는다.

6. Manus 교훈 종합 — 프로덕션 체크리스트

원칙구현 방법관련 전략
KV-캐시 히트율 최우선시스템 프롬프트 안정화, Append-only, 결정론적 직렬화Compress
파일시스템 = 무한 컨텍스트대용량 관측값 외부화, 경로만 컨텍스트에Write
실패 흔적 보존오류·스택 트레이스 삭제 금지Write
Attention Recitationtodo.md를 컨텍스트 끝에 재기록Write + Compress
로짓 마스킹도구 목록 고정, 디코딩 단계 토큰 억제Compress + Isolate
직렬화 변이반복 태스크에서 phrasing 소변이Write

참고문헌

관련 노트

그래프 뷰

백링크