AI 코딩 에이전트가 같은 실수를 반복하지 않게 하려면, 실수할 때마다 사람이 CLAUDE.md 를 고치는 대신 「사용자가 바로잡은 말」을 세션 기록에서 자동으로 모아 두 갈래로 쓰면 됩니다. 하나는 그 저장소의 다음 세션 첫 입력에 최근 정정을 그대로 보여 주는 것이고(첫 번째 정정부터 바로 배움), 다른 하나는 같은 저장소에서 같은 유형이 다른 날 두 번 이상 나오면 규칙 후보로 제안 대장에 올리는 것입니다(문장으로 굳힘). Claude Code 는 세션을 JSON Lines(.jsonl) 로 남기므로, 사용자 메시지 중 「놓쳤잖아」「하지 말라고 했잖아」 같은 꼴만 정규식으로 걸러 유형을 붙이면 됩니다.
이 글은 혼자 쓰는 개발 환경을 AI 에이전트 중심으로 바꾸면서(AX, AI 전환) 만든 장치를 하루에 하나씩 정리하는 연재의 다섯 번째 편입니다. 지난 편은 검토 기록 없는 커밋을 훅이 멈추는 이야기였습니다.
왜 「실수하면 CLAUDE.md 를 고쳐라」로는 부족했을까?
에이전트가 실수하면 「이 실수를 반복하지 않게 규칙 파일을 고쳐」라고 시키는 방법이 널리 알려져 있고, 저도 그렇게 시작했습니다. 두 가지가 걸렸습니다.
첫째, 고치는 주체가 사람입니다. 바로잡는 말은 작업 중에 짧게 튀어나옵니다. 「그게 아니고」「빠졌잖아」 한마디를 하고 나면 다시 작업으로 돌아가지, 규칙 파일을 열어 문장을 다듬는 일은 미루게 됩니다. 저장소가 여럿이면 어느 파일에 적을지부터 고민이 됩니다.
둘째, 한 번 바로잡은 말은 그 세션이 끝나면 사라집니다. 모델은 대화가 끝나면 아무것도 기억하지 않습니다. 다음 날 같은 저장소에서 새 세션을 열면 같은 가정으로 같은 실수를 했고, 저는 같은 말을 다시 했습니다. 규칙이 되기 전까지의 공백이 문제였습니다.
바로잡은 말은 어디에 남아 있을까?
Claude Code 는 세션마다 모든 메시지와 도구 호출을 ~/.claude/projects/<작업 폴더>/<세션 id>.jsonl 에 남깁니다. 사용자 메시지도 그 안에 그대로 있습니다. 그러니 이 파일들을 날짜 범위로 훑어 사용자 메시지만 꺼내고, 그중 「바로잡는 말」 꼴만 고르면 정정 사례가 됩니다. 정정 바로 앞의 에이전트 작업(어떤 도구로 무엇을 했는지)도 같은 파일에 있어 「무엇을 틀렸는지」 요지를 함께 남길 수 있습니다.
처음에는 「정정 비율」만 재는 지표가 있었습니다. 비율은 나빠졌는지 알려 주지만 무엇을 틀렸는지는 알려 주지 않았고, 지침을 고칠 근거가 되지 못했습니다. 그래서 2026-10-10 에 문장 자체를 사례로 모으는 스크립트를 따로 만들었습니다.
어떤 말을 「정정」으로 칠까?
여기서 가장 오래 걸린 것이 거르는 기준입니다. 「다시 확인해 봐」「~아닌가?」 같은 말은 실수가 아닐 때가 많습니다. 30일 표본을 손으로 보니 절반이 이런 재확인·의심이었습니다. 이런 말까지 규칙으로 올리면 틀린 규칙이 쌓여 에이전트를 더 망칩니다. 그래서 정밀도를 우선해 규칙 기반으로 인정하는 유형을 네 가지로 좁혔습니다.
TYPES = ( # 앞에서부터 처음 맞는 것. 물음표로 끝나면 「지시 위반」만 인정
("누락", re.compile(r"놓쳤|빠졌|빠뜨|빼먹|누락"), False),
("지시 위반", re.compile(r"말라(?:고|니까|니깐|했)|말랬|하지\s?말(?:라|랬|래|자)|하라고\s*[.!]*$"), True),
("전제 착오", re.compile(r"(?:그게|그거|이게)\s?아니|[가-힣A-Za-z0-9_.]+(?:이|가|게)\s?아니(?:고|라)(?=\s)"), False),
("결과 오류", re.compile(r"잘못(?:됐|되었|했|만들|계산|나왔)|틀렸|틀린|이상해|엉뚱|엉망"), False),
)규칙에 걸리지 않는 말은 「기타」로 모아 두기만 합니다. 거기에 예외가 더 붙었습니다. 「내가 말을 잘못했어」는 사람 쪽 실수라 빼고, 「잘못되면」은 가정이라 빼고, 「응, 그게 아니고 …」처럼 맞장구 뒤에 설명하는 말도 뺍니다. 다른 세션이 보낸 메시지(「[」로 시작)와 200자가 넘는 긴 지시문도 정정이 아닙니다. 「기타」는 나중에 작은 모델에 한 번 더 물어 네 유형 중 하나로 다시 가르되, 기본값은 「아님」으로 두었습니다. 틀린 정정 하나가 맞는 정정 열 개보다 해롭기 때문입니다.
모은 사례를 어디에 쓸까?
두 갈래입니다.
첫째, 다음 세션 첫 입력에 보여 줍니다. 세션의 첫 프롬프트가 들어올 때 도는 훅(UserPromptSubmit)이 그 저장소의 최근 30일 정정 중 유형이 정해진 것만 골라 최대 4건, 거기에 검토 에이전트나 가드 훅이 스스로 잡아낸 실수 2건을 덧붙여 한 번만 넣습니다. 세션 id 로 표지 파일을 남겨 같은 세션에 두 번 넣지 않습니다. 이렇게 하면 규칙이 되기 전이라도 첫 번째 정정부터 다음 세션이 알고 시작합니다.
[최근 정정] 이 저장소에서 사용자가 최근 30일 안에 바로잡은 말과,
검토·스스로 찾아낸 실수다. 같은 가정·같은 실수를 하기 전에
이 목록과 맞는지 먼저 본다 — 근거로 인용할 때는 원문을 다시 확인한다:
- 2026-10-20 누락: …
- 2026-10-18 지시 위반: …둘째, 반복되면 규칙 후보로 올립니다. 저장소와 유형이 같은 사례가 「세션과 날짜가 다른 단위」로 두 번 이상이면 제안 대장에 번호를 달아 올립니다. 같은 세션 같은 날의 반복은 한 번으로 셉니다. 같은 문제를 여러 번 말한 것일 수 있어서입니다. 사람 정정이 한 건도 없이 에이전트가 스스로 찾은 것만 쌓인 묶음은 올리지 않고 보류합니다. 검토를 자주 부르는 세션일수록 보류 없이는 제안이 쏟아졌습니다. 대장에는 저장소·유형·세션 수·날짜만 쓰고 원문은 로컬에만 둡니다.
# 매일 저녁 자동화가 돌리는 한 줄 — 최근 4일 사례를 모으고, 「기타」를 모델로 다시 가른 뒤, 반복 유형을 대장에 올린다
python3 scripts/corrections-collect.py --days 4 --llm --propose
# 올라온 묶음의 사례 보기(로컬 화면 전용)
python3 scripts/corrections-collect.py --show <저장소>/<유형>지금은 하루가 어떻게 달라졌나?
2026-10-23 기준으로 잰 값입니다. 2026-09-11 부터 2026-10-21 까지 모인 사례는 363건이고, 그중 사람이 바로잡은 말이 135건, 검토 에이전트·가드 훅·에이전트 자신이 먼저 알아챈 실수가 228건입니다. 유형별로는 지시 위반 80·결과 오류 63·누락 48·전제 착오 46 이고, 「기타」로 남은 것이 126건입니다. 첫 입력 주입은 2026-10-11 부터 세션 141개에 297번 들어갔습니다. 제안 대장에는 「정정 반복」 항목이 32개 올라왔고 그중 27개가 규칙 문장이나 훅으로 반영됐습니다.
달라진 것은 두 가지입니다. 바로잡은 말을 어디에 적을지 제가 고민하지 않습니다. 작업 중에 한마디 하고 넘어가면 그날 저녁 자동화가 모으고, 다음 날 그 저장소 세션이 그 말을 보고 시작합니다. 그리고 규칙 파일에 들어가는 문장은 「두 번 이상 반복된 것」으로 제한돼, 한 번 짜증 났던 일 때문에 규칙이 늘어나는 일이 줄었습니다. 대가도 있습니다. 정규식 기준이라 「기타」가 가장 큰 묶음이고, 거기에 숨은 진짜 정정은 모델 재분류가 잡아 줄 때까지 기다려야 합니다.
자주 묻는 질문
세션 기록 파일은 어디에 있고 무엇이 들어 있나요?
Claude Code 는 작업 폴더별로 ~/.claude/projects/<폴더 이름을 인코딩한 값>/ 아래에 세션마다 .jsonl 파일을 둡니다. 한 줄이 메시지 하나이고, 사용자 메시지·에이전트 메시지·도구 호출과 결과가 순서대로 들어 있습니다. 이 글의 스크립트는 그중 사용자 메시지와 직전 도구 호출만 읽습니다.
정정 원문을 git 에 올려도 되나요?
올리지 않습니다. 바로잡는 말에는 작업 중인 데이터·파일 이름·때로는 비밀값이 섞입니다. 사례 파일은 로컬 폴더에만 두고, 비밀값이나 SQL 이 든 문장은 원문 대신 가린 표시만 남깁니다. git 으로 가는 제안 대장에는 저장소·유형·세션 수·날짜만 적습니다.
왜 모델에게 처음부터 다 가르게 하지 않나요?
정밀도 때문입니다. 틀린 정정이 규칙이 되면 에이전트가 엉뚱한 규칙을 지키려 듭니다. 그래서 규칙 기반 네 유형만 우선 인정하고, 모델은 「기타」를 다시 가르는 데만 씁니다. 그마저도 한 모델의 판정은 다른 모델이 같은 질문으로 다시 가른 뒤 둘이 일치할 때만 규칙 판정과 같은 무게로 셉니다. 어긋나면 「기타」로 되돌립니다.