ELI5 · 쉬운 설명 · 전체 지도

agent-trace — 지금까지 만든 것,
한 장으로 보기

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

처음엔 기록을 모으기만 했습니다. 지금은 모은 기록에서 교훈을 뽑아 다음 작업 전에 건넵니다. 8단계에 걸쳐 무엇이 생겼는지, 지금 무엇이 되고 무엇이 아직 안 되는지 그림 6장으로 정리합니다.

2026-09-23저장소 ~/git-projects/agent-tracev0.6.0 (61024fe) + 심각도 기준테스트 373개 통과

한 장 요약. agent-trace는 코딩 에이전트의 일기장을 읽는 선생님입니다. ① 일기장 네 종류를 한 가지 모양으로 옮겨 적고 ② 이상한 날에 빨간 펜으로 표시하고 ③ 왜 이상했는지 따져 보고 ④ "다음엔 이렇게"라는 한 줄로 줄여 ⑤ 다음 날 아침 가방에 넣어 줍니다. ①~⑤가 모두 이어졌고, v0.6.0부터는 ③도 사람 없이 하루 20건까지 돕니다. 선생님이 "이건 외워 둬"라고 직접 말하면 판정 없이 바로 가방에 들어갑니다.
887세션
6,125턴
258룰이 표시한 턴
10LLM 판정 (자동 4)
4교훈 (자동 생성 2)
26대화창 주입

2026-09-23 18시 로컬 DB 기준 · 세션은 Codex 518 · Claude Code 354 · Hermes 15

그림 18단계로 자란 과정

왼쪽은 "모으기", 가운데는 "고르기", 오른쪽은 "되돌려 주기"입니다.

agent-trace 단계별 성장 Plan 1 Claude Code 수집, Plan 2 Codex와 Hermes와 서브에이전트, Plan 3 룰 표시와 LLM 판정과 개선 루프, v0.2.0 설치형 패키지, v0.3 맥락 주입 훅과 실시간 룰, v0.4.0 네 도구 모두 주입, v0.5.0 교훈 루프, v0.6.0 자동 판정과 대화 중 교훈 추가 순서로 이어진다. 모으기 고르기 · 배포 되돌려 주기 1 Plan 1 Claude Code기록 읽기SQLite 저장Phoenix 전송 2 Plan 2 + Codex+ Hermes서브에이전트부모 턴에 중첩 3 Plan 3 룰 7개로 표시LLM 판정제안 → 승인CLAUDE.md 한 줄 4 v0.2.0 uv tool installsetup 한 번상시 서비스Phoenix 선택 5 v0.3 훅으로 대화창에직전 작업 주입실시간 룰 표시Codex 승인 감지 6 v0.4.0 Hermes 플러그인OpenCode 플러그인네 도구 모두주입 가능 7 v0.5.0 판정 → 교훈승인·거부점수로 골라작업 전 주입 8 v0.6.0 watch가 자동 판정하루 20건대화 중lessons add 3단계의 "CLAUDE.md 한 줄"은 사람이 안 눌러 0건 → 5~7단계는 대화창에만 7단계도 판정을 사람이 돌려야 해서 가늘었다 → 8단계가 판정을 자동으로 Plan 1~3: PR #1~#3 · v0.2~0.5: 09-21 · v0.6.0: 09-23

그림 2지금 도는 고리 — 저절로 도는 것과 사람이 하는 것

위 줄은 watch를 켜 두기만 하면 돕니다. 아래 줄은 사람이 말하거나 명령을 칠 때만 돕니다.

자동 경로와 사람 경로 자동 경로는 에이전트 기록을 watch가 수집하고 룰이 표시하고, 표시된 턴을 하루 20건까지 자동 판정해 심각도 2 이상이면 교훈으로 만들고, 훅이 다음 작업에 주입한다. 사람 경로는 대화 중 교훈으로 저장해라고 말하면 lessons add로 승인 상태의 교훈이 바로 들어가고, approve와 reject로 자동 교훈을 고른다. 저절로 (watch 상시) 에이전트가 일함기록 파일이 늘어남 룰이 표시느림·반복·에러·정정 자동 판정하루 20건 · 최신순반응 보고 10분 뒤 심각도 2 이상만교훈으로 저장status=auto 훅이 주입시작·프롬프트 직전 다음 작업알고 시작 ↺ 다시 기록으로 (주입한 글은 표식으로 떼어 냄) 사람이 할 때 "교훈으로 저장해"대화 중에 말하면 에이전트가 실행lessons add · approved 좋다 / 아니다approve · reject 판정 없이 바로 주입 자동 교훈은 사람이 보기 전에 주입됩니다 — 아니다 싶으면 reject. 거부한 교훈은 절대 다시 안 들어갑니다

그림 3에이전트별로 되는 것

"읽기"와 "건네기"가 둘 다 돼야 고리가 닫힙니다.

에이전트별 지원 매트릭스 Claude Code와 Codex는 기록 읽기, 서브에이전트, 맥락 주입, 교훈 주입이 모두 된다. Codex는 대화형 승인 한 번이 필요하다. Hermes는 읽기와 주입이 되고 서브에이전트는 해당 없다. OpenCode는 주입만 되고 읽기가 안 된다. OpenClaw는 아직 둘 다 없다. 기록 읽기서브에이전트대화창 주입교훈 주입 Claude CodeCodexHermesOpenCodeOpenClaw settings.json 훅hooks.json + 승인 1회파이썬 플러그인JS 플러그인— ✓✓✓✓ ✓✓✓✓ ✓✓✓ ✓✓ 해당 없음 ✕✕ ✕✕✕✕
OpenCode는 말은 건네지만 듣지는 못합니다 — 파서가 없어 그 세션은 DB에 쌓이지 않고, 그래서 OpenCode에서 한 실수는 교훈이 되지 못합니다.

그림 4깔때기 — 어디가 가는가

6천 턴이 들어와 교훈 4개가 나옵니다. 막대 길이는 로그 눈금입니다.

수집에서 주입까지 깔때기 수집된 턴 6125개, 룰이 표시한 턴 258개, LLM 판정 10건(자동 4), 교훈 4개(자동 생성 2), 주입 26회. 판정 단계에서 가장 크게 줄어들지만 v0.6.0부터 하루 20건씩 자동으로 늘어난다. 수집한 턴 6,125 룰이 표시 258 LLM 판정 10 ← 가장 좁은 곳. 이제 하루 20건까지 자동으로 늘어남 (자동 4) 교훈 4 자동 판정이 만든 것 2 · 09-21 개발 중 시험으로 만든 것 2 대화창 주입 26 한 세션에 같은 교훈은 한 번만
v0.5.0까지는 고리는 이어졌지만 물이 거의 안 흘렀습니다(판정 6건, 사람이 돌려야 함). v0.6.0에서 watch가 표시된 최근 턴을 하루 20건까지 스스로 판정하고, 켜자마자 판정 4건 중 2건이 교훈이 됐습니다. 판정 1건은 실측 약 14초입니다.

그림 5심각도 — 2가 문턱이다

판정은 0~3으로 매깁니다. 2 이상이면 교훈으로 저장되고, 승인 없이 주입됩니다.

심각도 0~3 기준과 문턱 0은 문제 없음, 1은 비효율이지만 결과는 맞음, 2는 사용자가 다시 지시하거나 정정해야 했음 또는 결과 일부가 틀림, 3은 명시적 지시 위반 또는 되돌리기 어려운 작업. 2와 3은 교훈으로 저장되고 승인 없이 주입된다. 0 문제 없음 분류가 ok면코드가 0으로 고정 1 돌아갔지만 결과는 맞음 재시도 · 느림 · 헛탐색다시 지시할 필요는 없었음 2 사용자가 다시 말해야 했음 다음 프롬프트가 정정·재요청또는 결과 일부가 틀림 3 지시 위반 · 되돌리기 어려움 삭제 · 강제 push범위 밖 대량 수정 판정만 남음 교훈 저장 + 승인 없이 주입

원래 판정 프롬프트에는 0(문제없음) ~ 3(심각) 한 줄뿐이라 1과 2를 LLM이 감으로 갈랐습니다. 지금은 위 기준을 프롬프트에 넣었고, 2의 기준을 "사용자가 정정했는가"로 두어 다음 턴 프롬프트로 확인할 수 있게 했습니다. 이 기준은 그 뒤의 판정부터 적용되고, 기존 판정은 옛 기준 그대로입니다.

그림 6아직 비어 있는 칸

OpenCode · OpenClaw 읽기
파서가 없습니다. OpenCode는 주입만 되고, OpenClaw는 아무것도 없습니다.
수집 범위
자동 교훈이 먼저 퍼짐
심각도 2 이상 자동 교훈은 사람이 보기 전에 주입됩니다. 판정이 틀리면 reject로 막아야 합니다.
안전
교훈 본문 180자 잘림
판정 문장을 180자에서 잘라 저장해 뒷부분이 주입되지 않습니다. lessons show도 잘린 글을 보여 줍니다.
정확도
룰 오탐
slow_turn은 툴 실행·사용자 대기도 "느림"으로 셉니다. aborted는 Claude Code에서 사실상 항상 거짓.
정확도
멈춤 감지 · 효과 측정
stall 룰은 계획만 있습니다. 주입 뒤 같은 실수가 줄었는지 재는 명령도 없습니다.
계획
팀 공유 · 홈 경로
교훈은 내 DB에만 있습니다. 훅은 CODEX_HOME 같은 경로 변수를 읽지 않습니다. Windows는 서비스 없음.
배포

부록누가 무슨 일을 하나 (코드 지도)

일파일생긴 단계
일기장 네 종류를 한 모양으로parsers/claude_code.py · codex.py · hermes.py · model.py1·2
옮겨 적기 · 창고ingest.py · store.py (SQLite 12개 표, 스키마 8)1
실시간 감시 · 상시 실행watcher.py · service.py1·4
Phoenix로 보내기 · 사람 주석 받기exporter.py · phoenix_sync.py1·3
빨간 펜(룰)rules.py3·5
왜 이상했나(LLM)judge.py3
CLAUDE.md에 한 줄(사람 승인)proposals.py3
대화창에 넣을 글 만들기context.py · toolinfo.py5
훅·플러그인 설치/실행hooks.py · plugins.py5·6
교훈 만들기·고르기 · 직접 추가lessons.py7·8
표시된 턴 자동 판정(하루 상한)autojudge.py8

해보기처음부터 지금 상태까지

uv tool install "git+ssh://git@github.com/Dobraindev/agent-trace.git@v0.6.0"
agent-trace setup                 # 모으기 시작 + 상시 실행(자동 판정 하루 20건 포함)
agent-trace hook install          # 네 도구에 건네기 연결
hermes plugins enable agent-trace # Hermes만 한 줄 더 · Codex는 codex 한 번 띄워 승인

agent-trace lessons list          # 쌓인 교훈 보기 (source: judge / manual)
agent-trace lessons reject <id>   # 아니다 싶은 자동 교훈 막기
agent-trace lessons add "배포 전에 tsc 돌릴 것"   # 직접 넣기(대화 중 "교훈으로 저장해"와 같음)

AGENT_TRACE_AUTO_JUDGE_DAILY=0    # 자동 판정 끄기(~/.config/agent-trace/.env)
관련 문서