ELI5 · 쉬운 설명 · 전체 지도

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

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

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

2026-09-23저장소 ~/git-projects/agent-tracev0.5.0 (ea778f8)테스트 354개 통과

한 장 요약. agent-trace는 코딩 에이전트의 일기장을 읽는 선생님입니다. ① 일기장 네 종류를 한 가지 모양으로 옮겨 적고 ② 이상한 날에 빨간 펜으로 표시하고 ③ 왜 이상했는지 따져 보고 ④ "다음엔 이렇게"라는 한 줄로 줄여 ⑤ 다음 날 아침 가방에 넣어 줍니다. ①~⑤가 모두 이어졌고, 지금 가장 가는 곳은 ③(판정 6건뿐)입니다.
887세션
6,092턴
258룰이 표시한 턴
6LLM 판정
2교훈 (승인 1)
26대화창 주입

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

그림 17단계로 자란 과정

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

agent-trace 단계별 성장 Plan 1 Claude Code 수집, Plan 2 Codex와 Hermes와 서브에이전트, Plan 3 룰 표시와 LLM 판정과 개선 루프, v0.2.0 설치형 패키지, v0.3.0 맥락 주입 훅과 실시간 룰, v0.4.0 네 도구 모두 주입, v0.5.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 판정 → 교훈승인·거부점수로 골라작업 전 주입 3단계의 "CLAUDE.md 한 줄"은 사람이 안 눌러 0건 → 5~7단계는 파일을 안 고치고 대화창에만 넣는 길 Plan 1~3: PR #1~#3 · v0.2~0.5: 2026-09-21 하루에 태그

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

위 줄은 켜 두기만 하면 매 턴 돌고, 아래 줄은 사람이 명령을 칠 때만 돕니다.

자동 경로와 수동 경로 자동 경로는 에이전트 기록을 watch가 수집하고 룰이 표시하고 훅이 다음 턴에 주입한다. 수동 경로는 judge로 판정하고 lessons build로 교훈을 만들고 lessons approve로 승인하며, 만들어진 교훈은 자동 경로의 주입으로 합류한다. 저절로 (매 턴) 에이전트가 일함기록 파일이 늘어남 watch가 읽음launchd 상시 룰이 바로 표시느림·반복·에러·정정 훅이 주입세션 시작·프롬프트 직전 다음 턴알고 시작 다시 기록으로 (주입한 글은 마커로 떼어 내고 저장) 사람이 누를 때 왜 이상했나 판정judge 한 줄 교훈으로lessons build 좋다/아니다approve · reject 표시된 턴만 판정 대상 교훈이 주입에 합류 승인 안 한 교훈은 심각도 2 이상일 때만 들어가고, 거부한 교훈은 절대 안 들어갑니다

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

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

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

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

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

수집에서 주입까지 깔때기 수집된 턴 6092개, 룰이 표시한 턴 258개, LLM 판정 6건, 교훈 2개(승인 1), 주입 26회. 판정 단계에서 가장 크게 줄어든다. 수집한 턴 6,092 룰이 표시 258 LLM 판정 6 ← 여기가 병목 (사람이 judge를 돌려야 늘어남) 교훈 2 승인 1 · 자동 1 대화창 주입 26 한 세션에 같은 교훈은 한 번만
고리는 다 이어졌지만 물이 적게 흐릅니다. judge는 턴당 약 33초가 걸리고 사용량을 쓰므로 자동으로 돌지 않습니다. 교훈을 늘리는 가장 빠른 길은 agent-trace judge --limit 20을 몇 번 돌리는 것입니다.

그림 5아직 비어 있는 칸

OpenCode · OpenClaw 읽기
파서가 없습니다. OpenCode는 주입만 되고, OpenClaw는 아무것도 없습니다.
수집 범위
판정이 적다
258개 표시 중 6개만 판정. judge를 자동으로 돌리는 장치가 없습니다.
병목
룰 오탐
slow_turn은 툴 실행·사용자 대기도 "느림"으로 셉니다. aborted는 Claude Code에서 사실상 항상 거짓.
정확도
멈춤 감지
같은 에러 반복·장시간 무응답(stall) 룰은 계획만 있고 아직 없습니다.
계획
주입이 효과 있었나
injections에 기록은 남지만, 주입 뒤 같은 실수가 줄었는지 재는 명령은 없습니다.
측정
팀 공유 · Windows
교훈은 내 DB에만 있습니다. Windows는 상시 서비스를 직접 띄워야 합니다.
배포

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

일파일생긴 단계
일기장 네 종류를 한 모양으로parsers/claude_code.py · codex.py · hermes.py · model.py1·2
옮겨 적기 · 창고ingest.py · store.py (SQLite 12개 표)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

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

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 judge --limit 10      # 판정 쌓기 (사용량 소모)
agent-trace lessons build         # 판정 → 교훈
agent-trace lessons list          # 승인할 것 고르기
agent-trace lessons approve <id>
관련 문서