CH 29 · 가시성과 컨텍스트 관리

전체 글자 수약 3,170자예상 소요 시간약 20분선행 학습CH 04, CH 16난이도이해 위주

이 장의 목표

Agent가 돌기 시작하면 이런 질문이 반드시 생깁니다. 방금 왜 그런 결정을 내렸지? 이번 라운드에 토큰이 얼마나 들었지? 세션이 길어질수록 느려지고 비싸지는데 어떻게 하지?

dsh의 접근은 Agent의 모든 단계를 펼쳐서 보여주는 것입니다. 무엇을 보았고, 무엇을 생각했고, 무엇을 했고, 얼마가 들었는지 전부 추적 가능하게 만듭니다. 앞서 CH 04에서 트라젝토리 인터페이스의 기초를 다루었고, CH 16에서 캐시 히트율을 언급했는데, 이 장에서는 가시성과 성능을 완전히 정리합니다. 트라젝토리 어떻게 보는지, 세션 로그는 어디에 있는지, Token과 캐시 지표 어떻게 읽는지, 컨텍스트는 어떻게 관리하는지. 이것만 익혀도 "쓸 수 있는" 수준을 넘어 "알뜰하고 안정적으로 쓰는" 단계로 올라갈 수 있습니다.

트라젝토리(Trajectory): Agent의 완전한 운영 일지

트라젝토리란

보통의 Agent 도구는 "채팅 기록"을 보여줍니다. 내가 뭐라고 했고, 모델이 뭐라고 했는지. 하지만 그 사이에서 무슨 일이 일어났는지는 안 보입니다. 어떤 파일을 읽었는지, 어떤 도구를 호출했는지, 도구가 무엇을 반환했는지, 왜 그 도구를 골랐고 다른 도구는 안 골랐는지 — 이런 것은 채팅 뷰에서는 보이지 않습니다.

트라젝토리(Trajectory)가 바로 이 문제를 해결합니다. Agent의 완전한 실행 과정을 타임라인으로 기록하며, "사용자 시각의 채팅 기록"이 아니라 "모델 시각의 운영 일지"입니다.

기록되는 내용:

분류	무엇을 기록하나
시스템 프롬프트	매 요청마다 모델에 보낸 system prompt 전체
사용자 입력	사용자가 보낸 메시지, 주입된 컨텍스트
모델 요청	모델에 보낸 내용 전체, 모델이 반환한 내용 전체
도구 호출	어떤 도구를 호출했는지, 파라미터는 무엇인지, 반환 결과는 무엇인지
서브에이전트 스케줄링	서브에이전트를 몇 개 띄웠는지, 각각 무엇을 했는지, 결과를 어떻게 합쳤는지
승인 인터랙션	어떤 작업이 승인을 요청했는지, 사용자가 허용했는지 거부했는지

이 모든 것이 추가 전용(append-only) 세션 로그에 기록됩니다. 추가만 되고 절대 수정되지 않아 기록의 완전성과 감사 가능성을 보장합니다.

트라젝토리는 어디서 보나

Web UI의 세션 화면 상단에 트라젝토리(Trajectory) 탭이 있습니다. 클릭해서 들어갑니다.

인터페이스는 브라우저 개발자 도구의 네트워크 패널과 비슷합니다.

• 상단 타임라인: 실제 시작/종료 시각을 기준으로 왼쪽에서 오른쪽으로 그려지며, 매 라운드의 요청이 한 구간을 차지함
• 좌측 이벤트 리스트: 한 줄에 한 기록, 라운드별로 그룹화, 각 줄에 타입 표시(LLM / TOOL / SUBAGENT / APPROVAL)
• 우측 상세 패널: 기록을 클릭하면 펼쳐져서 전체 내용을 볼 수 있음 — 도구 호출의 Schema / Payload / Result, 모델 요청의 prompt와 response 전체

트라젝토리로 무엇을 할 수 있나

1. 장애 진단: Agent가 예상 밖의 일을 했다면? 트라젝토리로 돌아가 그때 무엇을 받았는지, 왜 그런 결정을 했는지 봅니다. "AI가 갑자기 이상하게 움직임"의 90%는 트라젝토리에서 원인을 찾을 수 있습니다. 보통은 사용자가 못 본 파일을 읽었거나 도구가 비정상 값을 반환한 경우입니다.
2. 회고: 작업이 잘 됐든 못 됐든 트라젝토리로 돌아가 어느 단계가 결정적 전환점이었는지, 어느 단계가 토큰을 낭비했는지 봅니다. 다음에 프롬프트나 흐름을 최적화할 수 있습니다.
3. 실험 재현: Agent 연구를 할 때 트라젝토리는 완전한 실험 기록입니다. 같은 입력, 같은 도구, 같은 모델 버전으로 같은 결과를 재현할 수 있습니다.
4. 감사: 팀이 함께 쓸 때 트라젝토리는 "언제 이 파일을 바꿨고 왜 바꿨는지"에 답해줍니다. git log보다 더 세밀한데, "왜 바꿨는지"까지 기록하기 때문입니다.

세션 로그: 어디 있는지, 어떻게 쓰는지

트라젝토리 데이터는 결국 메모리가 아니라 로컬 파일에 떨어집니다.

저장 위치

모든 세션은 ~/.dsh/sessions/ 디렉터리에 저장되며(Windows: C:\Users\<사용자 이름>\.dsh\sessions\), 작업 영역별로 디렉터리가 나뉩니다.

작업 영역 디렉터리 이름은 경로를 escape한 형태입니다. --로 감싸고, 경로 구분자는 -로 바꾸며, 특수 문자는 URL 인코딩합니다. 예컨대 작업 영역 E:\software-workspace\DeepSeek harness demo의 디렉터리 이름은 --E-software-workspace-DeepSeek~0020harness~0020demo--입니다.

각 세션은 서브 디렉터리이며, 이름 형식은 session-<uuid>(Web UI에서 만든 경우) 또는 순수 <uuid>(headless로 돌린 경우)이고, 안에 session.jsonl.zstd 파일 하나가 들어 있습니다(zstd 압축 JSONL, 한 줄에 이벤트 하나).

~/.dsh/sessions/
├── --E-software-workspace-DeepSeek~0020harness~0020demo--/
│   ├── session-05da13b1-c7bf-4f42-843b-.../
│   │   └── session.jsonl.zstd
│   ├── session-06451c43-35fb-4338-bc87-.../
│   │   └── session.jsonl.zstd
│   └── 37e884fa-7c73-40fa-81fc-.../          ← headless로 돌린 세션
│       └── session.jsonl.zstd
└── --E-software-workspace-doubaowork-DeepSeekHarnessGuide--/
    └── session-f417b4dd-3c8f-4098-85.../
        └── session.jsonl.zstd

세션의 세 가지 능력

이 로그를 기반으로 dsh는 세 가지 작업을 지원합니다.

1. 재개(Resume): dsh를 껐다 다시 열면 이전 세션이 그대로 있어 대화를 이어 갈 수 있습니다. 로그가 영구 저장되기 때문이지 메모리에 있는 게 아닙니다.
2. 분기(Fork): 특정 과거 메시지 아래의 분기 아이콘을 클릭하면 그 메시지부터 새로운 갈래로 시도해 볼 수 있고 원래 세션은 그대로 보존됩니다. 예컨대 Agent가 5단계까지 갔는데 방향이 잘못됐다 싶으면, 4단계로 분기해 다른 프롬프트로 다시 시도할 수 있고 원래 세션은 보존됩니다. 분기된 새 세션 이름에는 (1), (2) 같은 접미사가 붙어 원본과 구분됩니다.
3. 재플레이(Replay): 한 세션의 이벤트 스트림을 다시 돌려서 매 단계의 입출력을 봅니다. 플러그인 디버깅이나 문제 재현에 적합합니다.

성능 지표: Token, 캐시, 컨텍스트

dsh는 인터페이스에서 몇 가지 핵심 성능 지표를 실시간으로 보여줍니다. 이것을 읽는 법을 익히면 비용과 속도를 통제할 수 있습니다.

Token 사용량

매 라운드 요청이 끝나면 인터페이스 하단에 이번 라운드의 Token 통계가 표시됩니다.

• 입력 Token: 모델에 보낸 총 token 수(시스템 프롬프트, 대화 히스토리, 도구 결과 포함)
• 출력 Token: 모델이 생성한 token 수
• 캐시 히트 Token: 입력 중 DeepSeek 컨텍스트 캐시에 적중한 부분

누적 사용량은 세션 통계에서 볼 수 있습니다. 세션 전체에서 token을 얼마나 썼는지, 비용은 얼마였는지.

컨텍스트 점유율

입력 박스 우측에 원형 게이지가 있어 현재 컨텍스트 점유율을 백분율로 보여줍니다. 이것이 dsh만의 디자인으로, "컨텍스트 공간이 얼마나 남았는지"를 실시간으로 알려줍니다.

컨텍스트는 유한합니다(모델별 윈도우 크기는 다르지만 보통 128K부터). 점유율이 100%에 가까워지면 dsh는 컨텍스트를 자동 압축합니다. 앞쪽 히스토리를 요약으로 묶어 원래의 다회차 대화를 대체하여, 윈도우 초과로 바로 에러가 나지 않고 대화를 계속 이어 갈 수 있게 합니다.

자동 압축은 최후의 안전망입니다. 더 권장하는 방법은 적절한 시점에 직접 압축을 트리거하는 것입니다. 입력 박스에 /compact 명령을 입력하면 dsh가 현재 대화를 즉시 요약으로 압축해 원래 다회차 히스토리를 대체합니다. 자신의节奏에 맞춰 압축하면 핵심 정보가 유실되지 않습니다.

점유율이 거의 가득 찼을 때 선택지는 두 가지: /compact로 수동 압축하거나 새 세션을 엽니다.

컨텍스트 관리: 긴 세션이 깨지지 않게 하는 법

Agent 세션은 본질적인 문제가 있습니다. 길게 이야기할수록 token이 더 들고, 앞부분을 모델이 점점 덜 "기억"합니다. dsh는 이를 관리할 도구 몇 가지를 제공합니다.

언제 새 세션을 열어야 하나

모든 작업을 한 세션에서 끝내야 하는 건 아닙니다. 다음 상황에는 새 세션을 여는 것이 좋습니다.

• 작업 유형이 바뀜: 방금 코드 작성이었는데 이제 PPT를 만들어야 한다면 — 새 세션을 열어 코드 컨텍스트가 PPT 작업을 오염시키지 않게 하세요
• 작업 영역이 바뀜: 프로젝트 디렉터리를 바꿨다면 — 새 세션을 여세요. dsh 세션은 작업 영역에 묶입니다
• 컨텍스트 점유율 70% 초과: 더 대화하면 모델이 앞쪽 내용을 잊고 반응도 느려집니다. 가끔 모델이 갑자기 멍청해진 것 같은 느낌이 드는 게 바로 그 이유입니다. 새 세션을 열거나 먼저 /compact로 압축하세요

비용 관리 습관 몇 가지

1. 모든 일을 한 세션에서 하지 말 것 — 작업별로 세션을 나누면 각 세션의 컨텍스트가 짧고 캐시 히트율이 높으며 비용이 낮습니다
2. 큰 파일을 반복해서 읽지 말 것 — Agent가 1000줄짜리 파일을 읽으면 매번 token이 듭니다. 한 번 읽은 후 핵심 정보를 요약 파일로 쓰게 하고, 이후에는 요약만 읽게 하세요
3. 맞는 모델을 쓸 것 — 단순 작업은 flash, 복잡한 추론은 pro, 시각 작업은 vision. 무조건 가장 비싼 모델만 쓰지 마세요
4. 누적 사용량을 정기적으로 확인할 것 — 세션 통계에서 총 token과 예상 비용을 볼 수 있습니다.月末이 돼서야 놀라지 마세요

이 장에서 배운 것

아래 항목을 스스로 완수할 수 있으면 합격입니다.

• [ ] 트라젝토리가 무엇인지, 어디서 보는지, 어떤 내용이 기록되는지 안다
• [ ] 세션 로그가 ~/.dsh/sessions/에 저장되며 재개/분기/재플레이를 지원한다는 것을 안다
• [ ] Token 통계의 입력/출력/캐시 히트가 각각 무엇인지 이해한다
• [ ] 컨텍스트 점유율이 어디에 표시되는지, 거의 가득 찼을 때 어떻게 해야 하는지 안다
• [ ] /compact 명령 사용법과 언제 수동으로 압축해야 하는지 안다
• [ ] 비용 관리 습관을 최소 3가지 이상 말할 수 있다