파일시스템 기반 컨텍스트 엔지니어링
컨텍스트 윈도우는 제한되어 있지만 작업에는 단일 윈도우에 맞지 않는 더 많은 정보가 필요한 경우가 많으므로, 파일시스템을 에이전트 컨텍스트의 기본 오버플로 계층으로 사용하십시오. 파일을 통해 에이전트는 단일 인터페이스를 통해 사실상 무제한의 컨텍스트를 저장, 검색, 업데이트할 수 있습니다.
정적 포함보다는 관련 컨텍스트를 요청 시 가져오는 동적 컨텍스트 발견을 선호하십시오. 정적 컨텍스트는 관련성과 관계없이 토큰을 소비하고 작업별 정보를 위한 공간을 잠식하기 때문입니다.
활성화 시기
다음과 같은 경우 이 스킬을 활성화하십시오:
- 도구 출력이 컨텍스트 윈도우를 비대하게 만드는 경우
- 에이전트가 긴 궤적 동안 상태를 유지해야 하는 경우
- 하위 에이전트가 직접 메시지 전달 없이 정보를 공유해야 하는 경우
- 작업에 윈도우 용량보다 더 많은 컨텍스트가 필요한 경우
- 자체 지침을 학습하고 업데이트하는 에이전트를 구축하는 경우
- 중간 결과를 위한 스크래치 패드를 구현하는 경우
- 터미널 출력이나 로그를 에이전트가 접근할 수 있어야 하는 경우
다른 스킬이 담당하는 인접 작업에는 이 스킬을 활성화하지 마십시오:
- 의미론적 세션 간 메모리, 엔티티 추적, 시간적 지식 그래프:
memory-systems. - 대화 요약, 압축, 지속적인 핸드오프 문구:
context-compression. - 파일 기반 저장소가 필요하지 않은 토큰 효율성 전술:
context-optimization. - 다중 에이전트 토폴로지 또는 핸드오프 프로토콜 설계:
multi-agent-patterns. - 라이브 윈도우 자체에서 콘텐츠를 제거하는 모델 편집:
self-managed-context.
핵심 개념
다음 네 가지 모드에 대해 컨텍스트 실패를 진단하십시오. 각각은 서로 다른 파일시스템 해결책이 필요하기 때문입니다:
- 누락된 컨텍스트 -- 필요한 정보가 사용 가능한 전체 컨텍스트에 없습니다. 도구 출력과 중간 결과를 파일에 저장하여 아무것도 손실되지 않도록 수정하십시오.
- 과소 검색된 컨텍스트 -- 검색된 콘텐츠가 에이전트가 필요한 것을 포괄하지 못합니다. 대상 검색에 용이하도록 파일을 구조화하여 수정하십시오(grep 친화적 형식, 명확한 섹션 헤더).
- 과다 검색된 컨텍스트 -- 검색된 콘텐츠가 필요한 것보다 훨씬 많아 토큰을 낭비하고 주의력을 저하시킵니다. 대량 콘텐츠를 파일로 오프로드하고 간결한 참조를 반환하여 수정하십시오.
- 매몰된 컨텍스트 -- 특정 정보가 여러 파일에 흩어져 있습니다. 구조적 검색을 위해 glob과 grep을 결합하고 개념적 쿼리를 위해 의미 검색을 결합하여 수정하십시오.
네 가지 모두를 해결하는 지속적 계층으로 파일시스템을 사용하십시오: 한 번 쓰기, 영구 저장, 선택적 검색.
세부 주제
정적 vs 동적 컨텍스트 트레이드오프
정적 컨텍스트(시스템 명령어, 도구 정의, 중요 규칙)를 값비싼 자산으로 취급하십시오. 이는 관련성과 관계없이 모든 턴에서 토큰을 소비합니다. 에이전트가 기능을 축적함에 따라 정적 컨텍스트는 증가하고 동적 정보를 위한 공간을 잠식합니다.
대신 동적 컨텍스트 발견을 사용하십시오: 최소한의 정적 포인터(이름, 한 줄 설명, 파일 경로)만 포함하고 관련이 있을 때 검색 도구로 전체 콘텐츠를 로드하십시오. 이는 토큰 효율성이 더 높고 종종 윈도우의 모순적이거나 관련 없는 정보를 줄여 응답 품질을 향상시킵니다.
트레이드오프를 수용하십시오: 동적 발견은 모델이 더 많은 컨텍스트가 필요할 때를 인식해야 합니다. 최신 프론티어 모델은 이를 잘 처리하지만, 덜 강력한 모델은 로드를 트리거하지 못할 수 있습니다. 의심스러운 경우 중요한 안전 또는 정확성 제약 조건을 정적으로 포함시키는 쪽으로 오류를 범하십시오.
패턴 1: 파일시스템을 스크래치 패드로 사용
대용량 도구 출력을 컨텍스트에 직접 반환하지 말고 파일로 리디렉션하십시오. 단일 웹 검색이나 데이터베이스 쿼리가 수천 개의 토큰을 메시지 기록에 덤프하여 전체 대화 동안 지속될 수 있기 때문입니다.
출력을 스크래치 파일에 쓰고, 간결한 요약을 추출한 다음 파일 참조를 반환하십시오. 그러면 에이전트는 대상 검색(패턴에 대한 grep, 줄 범위로 읽기)을 사용하여 필요한 것만 접근합니다.
def handle_tool_output(output: str, threshold: int = 2000) -> str:
if len(output) < threshold:
return output
file_path = f"scratch/{tool_name}_{timestamp}.txt"
write_file(file_path, output)
key_summary = extract_summary(output, max_tokens=200)
return f"[Output written to {file_path}. Summary: {key_summary}]"
grep을 사용하여 오프로드된 파일을 검색하고 read_file을 줄 범위와 함께 사용하여 대상 섹션을 검색하십시오. 이렇게 하면 전체 출력을 나중에 참조할 수 있도록 보존하면서 활성 컨텍스트에는 약 100개의 토큰만 유지됩니다.
패턴 2: 계획 영속화
계획을 파일시스템에 작성하십시오. 장기 작업은 계획이 주의력에서 벗어나거나 요약될 때 일관성을 잃기 때문입니다. 에이전트는 어느 시점에서든 계획을 다시 읽어 목표와 진행 상황에 대한 인식을 복원합니다.
사람이 읽을 수 있고 기계가 구문 분석할 수 있도록 계획을 구조화된 형식으로 저장하십시오:
# scratch/current_plan.yaml
objective: "인증 모듈 리팩토링"
status: 진행 중
steps:
- id: 1
description: "현재 인증 엔드포인트 감사"
status: 완료
- id: 2
description: "새 토큰 검증 흐름 설계"
status: 진행 중
- id: 3
description: "변경 사항 구현 및 테스트"
status: 대기
각 턴 시작 시 또는 컨텍스트 새로 고침 후 계획을 다시 읽어 방향을 재설정하십시오. 이는 '암송을 통한 주의력 조작' 역할을 합니다.
패턴 3: 파일시스템을 통한 하위 에이전트 통신
메시지 전달 대신 파일시스템을 통해 하위 에이전트의 결과물을 라우팅하십시오. 다중 홉 메시지 체인은 각 홉에서 요약을 통해 정보를 저하시키기 때문입니다('전화 게임').
각 하위 에이전트가 자체 작업 공간 디렉토리에 직접 쓰도록 하십시오. 코디네이터는 이러한 파일을 직접 읽어 완전한 충실도를 유지합니다:
workspace/
agents/
research_agent/
findings.md
sources.jsonl
code_agent/
changes.md
test_results.txt
coordinator/
synthesis.md
에이전트별 디렉토리 격리를 적용하여 쓰기 충돌을 방지하고 각 출력 아티팩트의 명확한 소유권을 유지하십시오.
패턴 4: 동적 스킬 로딩
스킬을 파일로 저장하고 정적 컨텍스트에는 스킬 이름과 간단한 설명만 포함하십시오. 모든 지침을 시스템 프롬프트에 채워 넣으면 토큰이 낭비되고 모순된 지침으로 모델을 혼란시킬 수 있기 때문입니다.
사용 가능한 스킬 (관련 시 read_file로 로드):
- database-optimization: 쿼리 튜닝 및 인덱싱 전략
- api-design: REST/GraphQL 모범 사례
- testing-strategies: 단위, 통합, E2E 테스트 패턴
현재 작업에 필요한 경우에만 전체 스킬 파일(예: skills/database-optimization/SKILL.md)을 로드하십시오. 이렇게 하면 O(n) 정적 토큰 비용이 작업당 O(1)로 변환됩니다.
패턴 5: 터미널 및 로그 영속화
터미널 출력을 자동으로 파일에 저장하고 선택적 검색을 위해 grep을 사용하십시오. 장기 실행 프로세스의 터미널 출력은 빠르게 축적되고 수동 복사-붙여넣기는 오류가 발생하기 쉽습니다.
terminals/
1.txt # 터미널 세션 1 출력
2.txt # 터미널 세션 2 출력
전체 터미널 기록을 컨텍스트에 로드하는 대신 대상 grep(grep -A 5 "error" terminals/1.txt)으로 쿼리하십시오.
패턴 6: 자기 수정을 통한 학습
에이전트가 학습된 선호도와 패턴을 자체 지침 파일에 기록하여 후속 세션이 이 컨텍스트를 자동으로 로드하도록 하십시오. 수동 시스템 프롬프트 업데이트가 필요하지 않습니다.
def remember_preference(key: str, value: str):
preferences_file = "agent/user_preferences.yaml"
prefs = load_yaml(preferences_file)
prefs[key] = value
write_yaml(preferences_file, prefs)
자기 수정은 시간이 지남에 따라 부정확하거나 모순된 지침을 축적할 수 있으므로 이 패턴을 검증으로 보호하십시오. 실험적인 것으로 간주하고 주기적으로 저장된 선호도를 검토하십시오.
파일시스템 검색 기술
컨텍스트 발견을 위해 ls/list_dir, glob, grep, read_file(줄 범위 포함)을 결합하십시오. 모델은 특히 파일시스템 탐색에 대해 훈련되었으며 이러한 조합은 구조적 패턴이 명확한 기술 콘텐츠에 대해 의미 검색보다 성능이 뛰어난 경우가 많습니다.
ls/list_dir: 디렉토리 구조 발견glob: 패턴과 일치하는 파일 찾기(예:**/*.py)grep: 파일 내용 검색, 컨텍스트가 있는 일치하는 줄 반환read_file(범위 포함): 전체 파일을 로드하지 않고 특정 섹션 읽기
구조적 및 정확한 일치 쿼리에는 파일시스템 검색을 사용하고 개념적 쿼리에는 의미 검색을 사용하십시오. 포괄적인 발견을 위해 둘을 결합하십시오.
실용적인 지침
파일시스템 컨텍스트를 사용해야 하는 경우
상황이 이러한 기준과 일치할 때 파일시스템 패턴을 적용하십시오. I/O 오버헤드는 토큰 절약 또는 지속성 요구에 의해서만 정당화되기 때문입니다:
다음과 같은 경우 사용:
- 도구 출력이 약 2000 토큰을 초과하는 경우
- 작업이 여러 대화 턴에 걸쳐 있는 경우
- 여러 에이전트가 공유 상태를 필요로 하는 경우
- 스킬이나 지침이 편안한 시스템 프롬프트 크기를 초과하는 경우
- 로그나 터미널 출력에 선택적 쿼리가 필요한 경우
다음과 같은 경우 피할 것:
- 작업이 단일 턴으로 완료되는 경우(오버헤드가 정당화되지 않음)
- 컨텍스트가 윈도우에 편안하게 맞는 경우(해결할 문제 없음)
- 지연 시간이 중요한 경우(파일 I/O는 측정 가능한 지연을 추가함)
- 모델에 파일시스템 도구 기능이 없는 경우
파일 구성
에이전트가 검색할 수 있도록 파일을 구조화하십시오. 에이전트는 디렉토리 이름을 나열하고 읽어 탐색하기 때문입니다:
project/
scratch/ # 임시 작업 파일
tool_outputs/ # 대용량 도구 결과
plans/ # 활성 계획 및 체크리스트
memory/ # 지속적인 학습 정보
preferences.yaml # 사용자 선호도
patterns.md # 학습된 패턴
skills/ # 로드 가능한 스킬 정의
agents/ # 하위 에이전트 작업 공간
일관된 명명 규칙을 사용하고 스크래치 파일에 타임스탬프나 ID를 포함시켜 명확하게 구분하십시오.
자율 연구 루프의 경우, 원시 검색 증거를 이를 소비한 실행 아래에 저장하십시오(예: researcher/runs/<run-id>/sources/evidence/raw/). 원시 연구 덤프를 저장소 루트에 남겨두지 마십시오. 루트 수준 아티팩트는 감사가 어렵고 출처 없이 인용하기 쉽습니다.
토큰 회계
파일시스템 패턴을 적용하기 전과 후에 토큰이 어디서 발생하는지 측정하십시오. 측정 없이 최적화하면 노력이 낭비되기 때문입니다:
- 정적 vs 동적 컨텍스트 비율 추적
- 오프로딩 전후 도구 출력 크기 모니터링
- 동적으로 로드된 컨텍스트가 실제로 사용되는 빈도 측정
예시
예시 1: 도구 출력 오프로딩
입력: 웹 검색이 8000 토큰 반환
이전: 8000 토큰이 메시지 기록에 추가됨
이후:
- scratch/search_results_001.txt에 기록
- 반환: "[Results in scratch/search_results_001.txt. Key finding: API rate limit is 1000 req/min]"
- 에이전트가 특정 세부 정보가 필요할 때 파일을 grep
결과: 컨텍스트에 약 100 토큰, 8000 토큰은 요청 시 접근 가능
예시 2: 동적 스킬 로딩
입력: 사용자가 데이터베이스 인덱싱에 대해 질문
정적 컨텍스트: "database-optimization: 쿼리 튜닝 및 인덱싱"
에이전트 작업: read_file("skills/database-optimization/SKILL.md")
결과: 관련된 경우에만 전체 스킬 로드
예시 3: 파일 참조로 채팅 기록
트리거: 컨텍스트 윈도우 한계 도달, 요약 필요
작업:
1. 전체 기록을 history/session_001.txt에 기록
2. 새 컨텍스트 윈도우에 대한 요약 생성
3. 참조 포함: "Full history in history/session_001.txt"
결과: 에이전트가 기록 파일을 검색하여 요약에서 손실된 세부 정보 복구
지침
- 대용량 출력은 파일에 쓰고 요약과 참조를 컨텍스트에 반환하십시오
- 계획과 상태를 구조화된 파일에 저장하여 다시 읽을 수 있도록 하십시오
- 메시지 체인 대신 하위 에이전트 파일 작업 공간을 사용하십시오
- 모든 것을 시스템 프롬프트에 채워 넣지 말고 스킬을 동적으로 로드하십시오
- 터미널 및 로그 출력을 검색 가능한 파일로 유지하십시오
- 포괄적인 발견을 위해 grep/glob과 의미 검색을 결합하십시오
- 명확한 명명으로 에이전트 검색 가능성을 위한 파일을 구성하십시오
- 파일시스템 패턴이 효과적인지 확인하기 위해 토큰 절약을 측정하십시오
- 스크래치 파일의 무제한 증가를 방지하기 위해 정리를 구현하십시오
- 자기 수정 패턴을 검증으로 보호하십시오
- 원시 증거를 이를 사용한 실행, 평가, 제안 옆에 보관하십시오
주의사항
- 스크래치 디렉토리 무제한 증가: 에이전트는 정리 없이 임시 파일을 생성하여 결국 디스크를 소비하고 디렉토리 목록을 복잡하게 만듭니다. 보존 정책(기간 기준 또는 개수 기준)을 구현하고 세션 경계에서 정리를 실행하십시오.
- 다중 에이전트 파일 접근의 경합 조건: 동일한 파일에 대한 동시 쓰기는 상태를 자동으로 손상시킵니다. 에이전트별 디렉토리 격리를 적용하거나 에이전트 접두사가 있는 항목으로 추가 전용 파일을 사용하십시오.
- 이동/이름 변경 후 오래된 파일 참조: 에이전트는 이전 턴의 경로를 보유하지만 리팩토링이나 파일 재구성 후에는 더 이상 존재하지 않습니다. 캐시된 경로를 읽기 전에 항상 파일 존재 여부를 확인하십시오. 확인에 실패하면 glob으로 재발견하십시오.
- Glob 패턴 잘못된 일치: 지나치게 광범위한 패턴(예:
**/*)은 관련 없는 파일을 컨텍스트로 가져와 토큰을 낭비하고 모델을 혼란스럽게 만듭니다. glob을 특정 디렉토리와 확장자로 범위를 제한하십시오. - 파일 크기 가정: 크기를 확인하지 않고 파일을 읽으면 단일 도구 호출로 100K+ 토큰이 컨텍스트에 덤프될 수 있습니다. 읽기 전에 파일 크기를 확인하고 대용량 파일에는 줄 범위 읽기를 사용하십시오.
- 파일 존재 여부 확인 누락: 에이전트는 이전 턴의 파일이 존재한다고 가정하지만 삭제되거나 이동되었을 수 있습니다. 항상 존재 여부 확인으로 읽기를 보호하고 누락된 파일 오류를 정상적으로 처리하십시오.
- 스크래치 패드 형식 표류: 구조화되지 않은 스크래치 패드는 연속적인 추가로 인해 형식 규칙이 침식되면서 구문 분석이 불가능해집니다. 첫 번째 쓰기부터 스키마(YAML, JSON 또는 구조화된 마크다운)를 정의하고 적용하십시오.
- 하드코딩된 절대 경로: 리포지토리가 다른 위치에 체크아웃되거나 컨테이너에서 실행될 때 중단됩니다. 프로젝트 루트에서 상대 경로를 사용하거나 경로를 동적으로 확인하십시오.
통합
이 스킬은 파일 기반 컨텍스트 저장소를 담당합니다.
…
[번역을 위해 잘림]