Two-Layer Architecture

• Two-Layer Architecture는 CLI tool 결과를 LLM에 전달하기 전 두 계층(Execution / Presentation)으로 분리하는 설계 패턴
• Layer 1은 순수 Unix 의미론, Layer 2는 LLM 인지 제약에 맞춘 변환을 담당하는 책임 분리 구조
• 바이너리 가드·오버플로우·메타 푸터·stderr 첨부 4가지 메커니즘으로 구성된 LLM-친화적 출력 변환 계층
• 파이프 의미 보존과 컨텍스트 보호를 동시에 달성하는 agent tool 설계의 핵심 원칙

해당 개념이 필요한 이유

• LLM은 텍스트만 처리 가능 → 바이너리 데이터를 직접 주입하면 토크나이저가 의미 없는 고엔트로피 토큰 생성
• Context window가 유한해 5000줄 로그 같은 대용량 출력은 이전 대화를 밀어내고 추론 품질을 저하
• Layer 1에서 메타데이터를 직접 부착하면 다음 파이프(grep)의 검색 대상에 섞여 Unix 의미론이 깨짐
• 명령어 실패 시 stderr를 누락하면 agent가 “왜 실패했는지” 모른 채 같은 시도를 반복

AS-IS — 단일 계층, raw 출력 직접 주입

LLM이 cat photo.png을 호출하면 raw PNG 바이트가 그대로 컨텍스트에 들어간다.

sequenceDiagram
    autonumber
    participant A as Agent
    participant T as run() Tool
    participant LLM
    A->>T: run("cat photo.png")
    T->>T: PNG 바이너리 그대로 stdout
    T-->>A: 182KB raw bytes
    A->>LLM: context에 raw bytes 주입
    Note over LLM: 토크나이저가 의미 없는<br/>토큰 수천 개 생성<br/>주의력 분산, 추론 품질 저하
    LLM-->>A: 혼란스러운 응답<br/>(20번 재시도 사례)

TO-BE — 2계층 분리, LLM에 안전한 출력만 전달

sequenceDiagram
    autonumber
    participant A as Agent
    participant L1 as Layer 1<br/>(Execution)
    participant L2 as Layer 2<br/>(Presentation)
    participant LLM
    A->>L1: run("cat photo.png")
    L1->>L1: cat 실행, raw bytes 생성
    L1->>L2: stdout/stderr/exit code 전달
    Note over L2: 바이너리 감지<br/>오버플로우 검사<br/>메타 푸터 부착<br/>stderr 첨부
    L2-->>A: "[error] binary image (182KB).<br/>Use: see photo.png<br/>[exit:1 | 8ms]"
    A->>LLM: 가공된 텍스트만 전달
    LLM-->>A: "see photo.png 호출"

두 계층의 책임 분리

각 계층의 책임 범위와 금지 사항이 명확히 갈린다.

계층	책임	금지
Layer 1 (Execution)	명령어 라우팅, 파이프/체인 처리, exit code 생성	메타데이터 부착, LLM 친화 가공, 출력 변형
Layer 2 (Presentation)	바이너리 가드, 오버플로우 처리, 메타 푸터, stderr 첨부	파이프 중간 단계 개입, 명령어 실행

왜 두 계층을 섞으면 안 되는가

cat bigfile.txt | grep error | head 10 실행을 예로 든다.

Layer 1에 메타데이터를 추가했을 때 발생하는 문제:

1. cat bigfile.txt → "내용...\n[exit:0 | 100ms]"  ← 메타 부착
2. grep error      → "[exit:0 | 100ms]" 도 검색 대상에 포함됨
3. 잘못된 매치 발생, 의미론 파괴

Layer 1에서 잘랐을 때 발생하는 문제:

1. cat bigfile.txt → 첫 200줄로 자름
2. grep error      → 자른 200줄에서만 검색
3. 사용자가 원한 "전체 파일에서 error 찾기"가 깨짐

따라서 Layer 1은 순수해야 하고, Layer 2는 최종 출력 직전에만 개입해야 한다.

Layer 2의 4가지 메커니즘

1. 바이너리 가드 (Binary Guard)

LLM 토크나이저는 바이너리를 처리하지 못하므로, 바이너리 감지 시 즉시 차단하고 대안 명령어를 안내한다.

감지 휴리스틱:

• Null byte 포함
• UTF-8 검증 실패
• 제어 문자 비율 10% 초과

출력 형태:

[error] cat: binary image file (182KB). Use: see photo.png
[error] cat: binary file (1.2MB). Use: cat -b file.bin

핵심: 에러 메시지가 다음 행동을 정확히 지시한다 (Agent Heuristic Design의 “Error as navigation” 원칙).

2. 오버플로우 모드 (Overflow Mode)

출력이 200줄 또는 50KB를 초과하면 잘라서 파일에 보관하고, 탐색 명령어를 함께 제공한다.

처리 흐름:

1. 첫 200줄만 LLM에 반환 (UTF-8 안전 절단)
2. 전체 출력을 /tmp/cmd-output/cmd-{n}.txt에 저장
3. 탐색 가능한 후속 명령어 안내

출력 예시:

[첫 200줄 내용]
--- output truncated (5000 lines, 245.3KB) ---
Full output: /tmp/cmd-output/cmd-3.txt
Explore: cat /tmp/cmd-output/cmd-3.txt | grep <pattern>
         cat /tmp/cmd-output/cmd-3.txt | tail 100
[exit:0 | 1.2s]

핵심 인사이트: LLM은 이미 grep/head/tail 사용법을 알므로, “대용량 데이터 탐색”이 agent의 기존 기술로 자동 변환된다.

3. 메타데이터 푸터 (Metadata Footer)

매 호출의 마지막 줄에 exit code와 실행 시간을 부착한다.

실제 출력 내용
[exit:0 | 1.2s]

부착 정보의 의미:

필드	의미	LLM 학습 효과
exit:0	성공	Unix 표준, LLM 사전지식 활용
exit:1	일반 실패	재시도 신호
exit:127	명령어 없음	다른 명령어 시도 신호
12ms	저렴	자유롭게 호출
3.2s	중간	신중히 사용
45s	비쌈	호출 최소화

반복 노출을 통해 agent가 시간과 비용 패턴을 내재화 → 시간이 갈수록 더 효율적인 호출.

4. stderr 첨부 (Stderr Attachment)

명령어 실패 시 stdout이 비어있지 않더라도 stderr를 항상 첨부한다.

[stdout 내용 (있으면)]

[stderr] bash: pip: command not found
[exit:127 | 8ms]

왜 중요한가: stderr 누락 시 agent는 “실패”만 알고 “왜 실패했는지” 모른 채 같은 시도를 반복 (실패 사례 2번 참고).

실패 사례에서 도출된 메커니즘

각 메커니즘은 실제 운영 중 발견된 안티패턴의 직접적 해결책이다.

사례 1 → 바이너리 가드 도입

사용자가 PNG 업로드 → agent가 cat으로 읽음 → 182KB raw 바이트가 LLM context로 → 토크나이저 의미 없는 토큰 생성 → agent 혼란 → cat -f, cat --format, cat --type image 등 20번 시행착오 후 강제 종료.

원인: 바이너리 감지 로직 부재 교훈: 도구 결과는 agent의 눈이다. 쓰레기를 반환하면 agent가 시맹(blind) 상태가 된다.

사례 2 → stderr 첨부 도입

pip install pymupdf 실행 → exit 127 → stderr “pip: command not found” 누락 → agent는 “실패”만 봄 → python3 -m pip, uv pip install, pip3 install, sudo apt install 등 10번 맹목적 재시도 후에야 uv run --with pymupdf 발견.

원인: stdout이 비어있지 않으면 stderr를 조용히 버리는 로직 교훈: stderr는 agent가 가장 필요로 하는 정보다. 정확히 명령어가 실패한 그 순간에.

사례 3 → 오버플로우 모드 도입

agent가 5,000줄 로그를 분석하려고 cat huge.log 호출 → 약 200KB 텍스트가 그대로 컨텍스트에 채워짐 → LLM 주의력 과부하, 응답 품질 급락, 이전 대화 컨텍스트 밀려남.

오버플로우 모드 적용 후: 첫 200줄로 구조 파악 → grep으로 문제 위치 특정 → 총 3호출, 2KB 컨텍스트로 동일 작업 완료.

교훈: agent에게 “전체 영토” 대신 “지도”를 줄 때 가장 효율적이다.

적용 시 체크리스트

• Layer 1 코드에 메타데이터 부착이 섞여 있지 않은가
• 바이너리 감지가 모든 stdout 경로를 커버하는가
• 출력 임계값(줄 수, 바이트 수)이 LLM 컨텍스트 크기에 맞춰져 있는가
• 임시 파일 경로(/tmp/cmd-output/...)가 agent에서 일관되게 노출되는가
• 명령어 실패 시 stderr가 누락되지 않는가
• exit code와 duration이 모든 응답에 일관되게 붙는가

관련 개념

• CLI-based Tool Calling — 이 패턴이 적용되는 상위 도구 모델(메인 개념)
• Agent Heuristic Design — Layer 2의 에러 메시지 설계가 따르는 원칙 집합
• delta — 스트리밍 메타데이터 일반 개념

참고 문서

• I was backend lead at Manus — 원문 Gist
• agent-clip 소스 — internal/loop.go (2계층 agent loop)
• agent-clip 소스 — internal/fs.go (바이너리 가드)
• agent-clip 소스 — internal/clip.go (stderr 처리)