에이전트 stdout을 파일로 남기려면?

긴 에이전트 실행은 터미널 스크롤만으로는 재현·감사가 어렵습니다. 채팅 UI에 남은 요약은 세션이 바뀌면 잘리고, “아까 뭐라고 했지?”를 다시 묻기엔 비용이 큽니다. 에이전트 로그 파일을 셸 리다이렉트와 tee로 남기면, 다음 세션에서도 같은 경로로 실패 원인을 추적할 수 있습니다.

이 글의 축은 셋입니다. 어디로 리다이렉트하나? · 실패만 모으려면? · 다음 세션에서 어떻게 읽히나? 요금·플랜·토큰 한도·제휴·창작 후기는 없습니다.

근거는 POSIX/Bash의 표준 리다이렉트(>, 2>, 2>&1, &>)와 GNU tee의 파일·stdout 동시 기록입니다. 특정 에이전트 제품의 유료 로그 한도·가격은 다루지 않습니다.

어디로 리다이렉트하나?

한 줄 답: 고정 디렉터리 + 타임스탬프 파일명에 stdout·stderr를 남깁니다. 화면에도 보려면 tee, 파일만 남기려면 >/2>입니다. 대상은 워크스페이스 밖 임시 폴더가 아니라 **레포/작업 트리 옆 logs/**처럼 다음 세션이 찾을 경로입니다.

권장 대상:

대상예시용도
통합 로그logs/agent-20260925-2100.logstdout+stderr 한 파일 (디버그·티켓 첨부)
stderr만logs/agent-20260925-2100.err실패·경고만 빠르게 훑기
세션 메타logs/agent-20260925-2100.cmd실행한 명령·cwd·시각 한 줄

기본 패턴(화면 + 파일):

mkdir -p logs
LOG="logs/agent-$(date +%Y%m%d-%H%M).log"

# stdout·stderr를 파일과 터미널에 동시 기록
your-agent-cli run --task brief.md 2>&1 | tee "$LOG"

파일만(조용한 CI·헤드리스):

your-agent-cli run --task brief.md >"$LOG" 2>&1
echo "exit=$?" >>"$LOG"

스트림을 나누고 싶을 때:

your-agent-cli run --task brief.md \
  >"logs/agent-out.log" \
  2>"logs/agent-err.log"

Bash에서 &>file은 stdout+stderr를 한 파일로 보냅니다. 2>&1은 stderr를 현재 stdout으로 합칩니다—파이프 앞에서는 2>&1 | tee 순서가 중요합니다.

하지 말 것:

  • /tmp/agent.log만 쓰고 경로를 티켓에 안 남기기(다음 세션·다른 머신에서 실종).
  • 매 실행마다 같은 파일에 >로 덮어쓰기만 하고 이전 실패본 삭제(비교 불가).
  • 바이너리·대용량 도구 덤프를 로그에 무제한 섞기(필요 시 head/rg로 추출).

실패만 모으려면?

한 줄 답: 항상 임시 로그에 기록한 뒤, exit code가 0이 아니면만 보관합니다. stderr만 모을 때는 2>로 분리하거나, 통합 로그에서 rg로 error/fail 줄만 잘라 실패 요약 파일을 만듭니다.

패턴 A — 실패 시에만 보관:

mkdir -p logs/fail
TMP="$(mktemp -t agent.XXXXXX.log)"
LOG="logs/fail/agent-$(date +%Y%m%d-%H%M).log"

set +e
your-agent-cli run --task brief.md >"$TMP" 2>&1
rc=$?
set -e

if [ "$rc" -ne 0 ]; then
  {
    echo "# cmd: your-agent-cli run --task brief.md"
    echo "# cwd: $(pwd)"
    echo "# exit: $rc"
    echo "# when: $(date -Iseconds)"
    cat "$TMP"
  } >"$LOG"
  echo "saved failure log: $LOG" >&2
else
  rm -f "$TMP"
fi
exit "$rc"

패턴 B — stderr만 상시 보관, stdout은 성공 시 폐기:

ERR="logs/agent-$(date +%Y%m%d-%H%M).err"
your-agent-cli run --task brief.md 2>"$ERR"
# stdout은 터미널/파이프에만; 실패 분석은 .err부터

패턴 C — 통합 로그에서 실패 신호만 요약:

rg -n -i 'error|fail|traceback|denied|EPERM|ENOENT' "$LOG" \
  >"logs/$(basename "$LOG" .log).fail.txt" || true

실무 규칙:

  1. exit code를 로그 헤더에 고정 — “에이전트가 뭔가 이상했다”만으로는 다음 세션이 재현하지 못합니다.
  2. 성공 로그는 짧게 또는 순환 — 디스크를 아끼려면 성공은 logs/ok/에 N개만 남기거나 생략합니다. 실패는 logs/fail/에 더 오래 둡니다.
  3. 시크릿 주의 — 환경 변수·토큰이 stdout에 찍히면 로그 파일이 유출면이 됩니다. 티켓에 붙이기 전 rg로 마스킹하거나, 도구에 quiet/redact 옵션이 있으면 켭니다(제품별 문서 따름).

tee로 화면과 파일을 같이 보면서도 실패만 남기려면, 위 패턴 A처럼 임시 파일 → 조건부 이동이 가장 단순합니다. tee만으로는 exit code를 자동 필터하지 않습니다(pipefail을 켜면 파이프 실패는 잡을 수 있음).

set -o pipefail
your-agent-cli run --task brief.md 2>&1 | tee "$TMP"
rc=$?
# 이후 패턴 A와 동일하게 rc로 보관 여부 결정

다음 세션에서 어떻게 읽히나?

한 줄 답: 경로 규칙 + 헤더(명령·cwd·exit·시각) 를 약속하고, 다음 세션 첫 명령은 ls logs/fail → less/rg입니다. 에이전트에게는 채팅 요약 대신 로그 경로를 프롬프트에 넣고 “이 파일만 근거로 재시도”라고 범위를 고정합니다.

읽기 순서:

  1. 목록 — ls -lt logs/fail | head 로 최근 실패본.
  2. 헤더 — 파일 앞 5~10줄에서 명령·exit·시각 확인.
  3. 신호 — rg -n -i 'error|fail|traceback' LOG.
  4. 꼬리 — tail -n 80 LOG (에이전트는 보통 마지막에 요약·스택을 남김).
  5. 재시도 프롬프트 — 아래 템플릿에 경로만 넣기.
## Prior run (read-only evidence)
Log: logs/fail/agent-20260925-2100.log
Exit: 1 (see header)

## Task
Fix the failure shown in that log. Do not re-run unrelated steps.

## Constraints
- Quote path:line from the log when explaining the root cause.
- Do not paste secrets from the log into new files.
- After fix, re-run the same CLI and save a new log under logs/.

## Done when
- New run exit 0, or a new fail log with a different root cause noted in the header.

세션 간 계약 체크리스트:

[ ] logs/ (또는 logs/fail/) 경로가 README·AGENTS.md에 한 줄로 있는가?
[ ] 파일명에 날짜·시간이 들어가 덮어쓰기를 피하는가?
[ ] 로그 헤더에 cmd·cwd·exit·when이 있는가?
[ ] 다음 에이전트 호출에 채팅 전문 대신 로그 경로를 넣는가?
[ ] 성공/실패 보관 정책이 팀과 같은가?

팁: 장기 실행은 tmux/script로 세션 자체를 녹화할 수도 있지만, 이 글의 축은 재현 가능한 텍스트 로그 파일입니다. UI 전용 히스토리에만 의존하지 마십시오.

한 줄 정리: 고정 logs/에 2>&1 | tee로 남기고 → 실패만 logs/fail/에 보관하며 → 다음 세션은 그 경로를 근거로 읽습니다.

FAQ

Q. >와 tee 중 무엇을 쓰나요?
A. 화면에서도 진행을 보려면 2>&1 | tee FILE, 헤드리스·CI면 >FILE 2>&1입니다. 둘 다 에이전트 로그 파일을 남기는 목적에는 충분합니다.

Q. stderr만 보면 충분한가요?
A. 도구가 오류를 stdout에 섞어 찍으면 부족합니다. 불확실하면 통합 로그(2>&1)를 기본으로 두고, 실패 요약만 rg로 잘라 쓰십시오.

Q. 로그가 너무 커지면?
A. 성공본은 삭제·순환하고, 실패본은 헤더+rg 히트+tail만 티켓에 붙입니다. 전체 덤프는 아티팩트 저장소에 두고 링크만 남기는 편이 낫습니다.

Q. 윈도우/비 Bash는?
A. 개념은 같습니다(stdout/stderr 분리·파일 기록). 이 글 예시는 Bash/tee 기준입니다. PowerShell은 *> 등으로 대응합니다—플랜·요금과 무관한 OS 차이입니다.

출처