ELI5 · 쉬운 설명

agent-trace — 지난번 실수를
작업 시작 전에 손에 쥐여 주는 고리

마지막 업데이트 2026-09-22

예전에는 일이 끝난 뒤 리포트를 냈습니다. 지금은 일을 시작하기 전에 에이전트의 대화창에 필요한 만큼만 밀어 넣습니다. 무엇이 들어오고 무엇이 나가는지, 코드 어디가 그 일을 하는지 그림 7장으로 설명합니다.

2026-09-22저장소 ~/git-projects/agent-tracev0.5.0앞선 설명은 구성과 동작 흐름

한 장 요약. 예전 agent-trace는 블랙박스 영상을 모아 사고 구간을 표시하는 안전관리자였습니다. 지금은 운전대를 잡기 직전에 "지난번 여기서 사고 났었다"고 한 줄 말해 주는 조수석 사람이 됐습니다. 말은 짧게만 하고, 할 말이 없으면 아무 말도 하지 않으며, 운전에는 손대지 않습니다.

그림 1닫힌 고리 — 기록이 다시 기록으로

예전에는 화살표가 오른쪽 끝에서 멈췄습니다. 지금은 한 바퀴 돕니다.

agent-trace 전체 고리 에이전트가 남긴 기록을 agent-trace가 읽어 SQLite에 저장하고, 규칙과 판정이 문제 턴을 고르고, 그 결과가 교훈이 되어 사람 승인을 거친 뒤, 다음 작업 시작 시점에 에이전트 대화창으로 되돌아간다. 에이전트 4종 Claude Code Codex Hermes OpenCode OpenCode는 수집 아직 남김 기록 파일 ~/.claude ~/.codex ~/.hermes 읽음 agent-trace ① 하나의 모양으로 저장 ② 규칙이 문제 턴 표시 ③ LLM이 판정 ④ 교훈으로 압축 사람이 승인 lessons approve 교훈 창고 lessons 훅·플러그인이 대화창에 밀어 넣음 세션 시작 / 프롬프트 제출 시점 이 되돌아오는 화살표가 이번에 새로 생긴 부분입니다

에이전트는 여전히 agent-trace를 모릅니다. 다만 대화 첫머리에 짧은 메모가 한 장 붙어 있을 뿐입니다.

그림 2입출력 — 무엇이 들어오고 무엇이 나가나

들어오는 것은 많고 나가는 것은 아주 적습니다. 그게 핵심입니다.

입력과 출력의 크기 차이 왼쪽에서 수만 건의 툴 호출과 수천 개의 턴이 들어오고, 가운데 저장소를 거쳐, 오른쪽으로는 한 번에 몇 백 자짜리 메모만 나간다. 들어오는 것 사용자 프롬프트 · 최종 답변 툴 호출 34,831건 지연 시간 · 토큰 · 오류 건드린 파일 경로 SQLite 한 파일 agent-trace.db 턴 5,796 · 세션 854 표시 260 · 판정 6 파일 색인 781 전부 내 컴퓨터 안 골라서 나가는 것 대화창에 붙는 메모 한 장 이 폴더에서 지난번에 한 일 반복해서 실패한 명령 승인된 교훈 몇 줄 최대 1,200자 맞는 게 없으면 0자 — 아무 말도 하지 않음

수만 건이 들어와도 나가는 건 A4 반 장이 안 됩니다. 대화창 자리는 비싸니까요.

왜 이렇게까지 줄이나. 대화창에 넣은 글자는 전부 비용이고, 관련 없는 정보를 매번 붙이면 에이전트가 진짜 중요한 것을 놓칩니다. 그래서 개수로 먼저 자르고, 넘치면 문장을 자르지 않고 항목을 통째로 버립니다.

그림 3네 에이전트에 붙는 방법 — 둘은 설정, 둘은 코드

도구마다 문을 여는 방식이 다릅니다. 문은 달라도 들어가는 짐은 같습니다.

네 에이전트의 연결 방식 Claude Code와 Codex는 설정 파일에 명령 한 줄을 등록하고, Hermes와 OpenCode는 플러그인 코드 파일을 둔다. 네 경로 모두 같은 하나의 명령을 호출한다. 설정 한 줄이면 되는 쪽 Claude Code Codex settings.json / hooks.json 코드를 둬야 하는 쪽 Hermes (파이썬) OpenCode (자바스크립트) plugins/agent-trace 설치할 때 자동 생성 똑같은 명령 하나 agent-trace hook run 판단은 여기 한 곳에만 DB 읽기 읽기 전용으로만 0.1초 이내 메모 또는 침묵

플러그인은 스스로 판단하지 않고 심부름만 합니다. 그래서 파이썬과 자바스크립트로 갈라져도 동작이 어긋나지 않습니다.

도구붙는 곳부르는 시점넣는 방법
Claude Code~/.claude/settings.json세션 시작 · 프롬프트 제출추가 컨텍스트
Codex~/.codex/hooks.json세션 시작 · 프롬프트 제출추가 컨텍스트
Hermes~/.hermes/plugins/agent-trace/턴 시작 직전사용자 메시지 뒤에 덧붙임
OpenCode~/.config/opencode/plugins/메시지 도착사용자 메시지 뒤에 덧붙임
Codex만 한 단계 더. Codex는 등록된 훅이라도 사람이 신뢰를 승인하기 전에는 조용히 건너뜁니다. 오류도 경고도 없이 그냥 안 부릅니다. 대화형으로 codex를 한 번 띄워 승인해야 동작하고, agent-trace hook status가 미승인 여부를 알려줍니다.

그림 4언제 말을 거나 — 두 시점, 서로 다른 크기

처음 한 번은 길게, 매 질문마다는 아주 짧게.

주입 두 시점 세션이 시작될 때 최대 1200자짜리 배경 메모가 한 번 들어가고, 이후 사용자가 프롬프트를 낼 때마다 최대 600자짜리 짧은 신호가 들어간다. 세션 시작 세션 끝 배경 메모 · 최대 1,200자 지난 작업 · 최근 파일 · 반복 실패 짧은 신호 · 최대 600자 직전 턴 경고 · 지목한 파일 이력 질문 1 질문 2 질문 3

같은 교훈은 한 세션에 한 번만 들어갑니다. 이미 대화에 남아 있으니 다시 넣을 이유가 없습니다.

그림 5교훈의 일생 — 판정에서 주입까지

문제 턴 하나가 어떻게 "다음에 조심할 한 줄"이 되는지.

교훈의 일생 규칙이 턴을 표시하고, LLM이 판정하고, 같은 제안을 묶어 교훈을 만들고, 사람이 승인하면 주입 대상이 되며, 주입 기록이 남는다. ① 표시 규칙 7종이 고름 260건 ② 판정 LLM이 근거를 인용 아직 6건 ③ 교훈으로 같은 제안끼리 묶고 건드린 파일로 범위 정함 LLM 안 씀 · 공짜 ④ 사람 승인 approve / reject 거부하면 영영 안 나감 ⑤ 주입 · 기록 점수 높은 순 최대 3개 언제 넣었는지 남김 승인 안 된 교훈은 "심각도 2 이상"일 때만 저절로 나갑니다 사람이 보지 않은 판정이 곧바로 에이전트 행동을 바꾸지 않도록

②에서 ③으로 갈 때 LLM을 다시 부르지 않습니다. 판정이 이미 짧은 제안 문장을 남겨 뒀으니까요.

고를 때 매기는 점수

신호점수왜
프롬프트가 그 파일을 콕 집음+3.0가장 확실한 관련성
같은 작업 폴더+1.5같은 프로젝트의 일
사람이 승인함+1.0검증된 교훈을 앞세움
심각도+0.5 × 등급심한 문제를 먼저
근거 턴 수+0.3 × log반복될수록 신뢰
오래됨−0.5 × 개월옛날 교훈은 서서히 밀려남

그림 6자기 꼬리 물기 막기

우리가 넣은 글이 다시 "사용자가 한 말"로 수집되면 곤란합니다.

주입한 글에 표식을 달고 수집 때 떼어내기 주입한 메모는 표식으로 감싸고, 다시 수집할 때 파서가 그 표식 구간을 통째로 떼어내 원래 프롬프트만 저장한다. 에이전트가 보는 것 파일 리팩터링 진행해 <agent-trace-context> 지난번 교훈 … 기록에 남음 수집할 때 가위질 strip_injected() 파서 3종 모두에서 저장되는 것 파일 리팩터링 진행해 원문 그대로 이걸 안 하면 다음 판정이 우리가 쓴 글을 사용자 발화로 착각합니다

넣을 때 표식을 달고, 읽을 때 떼어냅니다. 왕복해도 원문이 정확히 돌아오는지 테스트로 고정해 뒀습니다.

그림 7코드 지도 — 어느 파일이 무슨 일을 하나

파이썬 파일 19개, 약 5,300줄. 역할별로 묶으면 다섯 덩어리입니다.

읽어 들이기
도구별 기록 파일을 읽어 턴이라는 하나의 모양으로 바꿉니다. 도구가 늘면 여기만 늘어납니다.
parsers/ingest.pywatcher.py
담아 두기
SQLite 한 파일. 표·색인·마이그레이션이 전부 여기 있습니다. 가장 큰 파일입니다.
store.pymodel.py
문제 찾기
규칙이 먼저 고르고, 그중에서만 LLM이 판정합니다. 순서가 반대면 비용이 터집니다.
rules.pyjudge.py
교훈 만들고 고르기
판정을 묶어 교훈으로, 주입할 때 점수로 고릅니다. 무엇을 건드렸는지는 별도 추출기가 뽑습니다.
lessons.pytoolinfo.pycontext.py
에이전트에 붙이기
설정 파일을 고치거나 플러그인 코드를 만듭니다. 남의 설정을 망가뜨리지 않는 게 제일 중요합니다.
hooks.pyplugins.pyservice.py
사람이 쓰는 문
명령 19개가 모두 여기로 들어옵니다. 설치·수집·조회·판정·교훈·훅이 한 자리에.
cli.py

입력에서 출력까지, 함수로 따라가기

단계들어가는 것하는 일나오는 것
수집기록 파일parse_* → upsert_session턴 · 툴 호출 · 파일 색인
표시끝난 턴evaluate_turn규칙 표시(flags)
판정표시된 턴judge_turn분류 · 심각도 · 제안
교훈판정lessons.build교훈 레코드 + 적용 범위
선별폴더 · 프롬프트lessons.select상위 몇 개
주입훅 페이로드session_context · prompt_context메모 한 장 또는 빈 값

지금숫자로 보는 현재 상태

5,796모인 턴
854세션
34,831툴 호출
260규칙이 표시
6LLM 판정
2교훈
354통과 테스트
4연결된 도구
지금 가장 얇은 곳은 판정입니다. 규칙은 260건을 표시해 뒀는데 LLM 판정은 6건뿐이고, 그래서 교훈도 2건입니다. 교훈은 판정에서 나오므로 판정을 더 쌓기 전에는 이 고리가 헛돕니다. 판정은 턴당 30초쯤 걸리고 Claude Code 사용량을 씁니다. 
uv run agent-trace judge --limit 20
uv run agent-trace lessons build

안전망가뜨리지 않기 위한 장치들

남의 도구 설정을 고치고 남의 대화창에 글을 넣는 일이라, 조심할 곳이 많습니다.

걱정장치
훅이 죽어서 세션이 멈춤무슨 일이 있어도 종료 코드 0과 빈 출력으로 끝냄
수집 프로세스와 충돌훅은 DB를 읽기 전용으로 염. 기록만 짧은 쓰기로 따로
남의 훅 설정을 지움기존 항목 보존 + 최초 1회 .agent-trace.bak 백업
남이 쓴 플러그인을 덮어씀우리가 만든 파일에만 표식. 표식 없으면 건드리지 않음
두 번 설치같은 내용이면 다시 쓰지 않음(멱등)
검증 안 된 교훈이 행동을 바꿈승인 전에는 심각도 높은 것만. 거부하면 영구 제외
같은 말 반복세션당 한 번. 주입 기록을 남겨 확인
데이터가 밖으로 나감전부 로컬 SQLite. 외부 전송은 판정 때만, 명시적으로
실제로 여기서 사고가 났었습니다. 훅의 마지막 방어선인 "조용히 실패" 코드 자체가 로거를 참조하지 못해 오류로 죽었습니다. 조용해야 할 자리가 시끄러웠던 셈이고, 테스트가 잡았습니다.

해보기설치부터 확인까지

# 설치 (uv 필요, 파이썬은 알아서 받아 옴)
uv tool install "git+ssh://git@github.com/Dobraindev/agent-trace.git@v0.5.0"

# 수집 시작 + 상시 실행 등록
agent-trace setup

# 에이전트 네 종류에 훅·플러그인 붙이기
agent-trace hook install
hermes plugins enable agent-trace     # Hermes만 한 줄 더
codex                                  # Codex는 대화형으로 한 번 띄워 승인

# 무엇이 들어갈지 미리 보기 (훅 없이도 확인 가능)
agent-trace hook preview SessionStart --cwd .
agent-trace hook status
관련 문서