스킬 점검 루프: Claude Code·Codex 스킬을 세션 로그로 매주 리팩토링하는 프롬프트

여러분, Claude Code나 Codex에 스킬을 몇 개나 넣어두셨나요? 그중 몇 개가 지금도 제대로 동작하는지 알고 계신가요? 결론부터 말하면, 스킬을 만든 뒤에는 세션 로그와 스킬 문서를 매주 대조하는 점검 루프를 같이 붙여야 합니다.

저는 추가해둔 스킬 중에서 몇 개나 제대로 동작하는지 일주일에 한 번씩 검증 루프를 돌리고 있습니다. 이 루프가 찾아준 문제는 이런 것들이었습니다. 에러도 없이 조용히 실패하고 있던 캘린더 조회, 문서가 낡아서 AI가 매번 실제 파일을 다시 열어보던 비효율, 세션마다 판단이 흔들리던 애매한 규칙. 전부 세션 로그를 안 봤으면 계속 몰랐을 문제들입니다.

이 글에서는 그 점검을 매주 돌려주는 프롬프트 전문과 설계 의도, 그리고 2026년 10월 3일 기준 공식 문서로 확인한 도구별 등록 방법을 정리했습니다.

스킬 점검 루프 핵심 요약

• 에러 없이 조용히 실패하거나 낡는 스킬이 있고, 이런 문제는 세션 로그에서 드러납니다.
• Claude 데스크톱 앱이나 ChatGPT 데스크톱 앱의 Codex에 프롬프트를 붙여넣으면, 매주 월요일 오전 9시에 도는 예약 작업 skill-refactoring-loop가 등록됩니다.
• 루프는 최근 1~2주 세션 기록과 스킬 문서를 대조해 반복됐거나 사용자가 명시적으로 교정한 것만 변경안으로 만듭니다.
• 스킬 파일은 바로 고치지 않습니다. 변경안과 근거를 보고서로 남기고, 사람이 승인 표시를 한 것만 반영합니다.
• 보고서는 한 폴더에 쌓이고, 직전 보고서를 이어받아 같은 제안을 반복하지 않습니다.
• 이 자동화 자체가 AI가 일하고, 로그로 검증하고, 사람이 승인하고, 결과가 스킬에 남는 작은 개선 루프입니다.

세션 로그에서만 보이던 스킬 문제 세 가지

세 문제는 성격이 다릅니다. 조용히 실패하는 절차도 있고, 시간이 지나며 낡은 문서도 있고, 해석이 갈리는 규칙도 있습니다.

에러 없이 실패하던 캘린더 조회

제 경우에는 캘린더 조회가 에러도 없이 조용히 실패하고 있었습니다. 에러가 나면 누군가 들여다보지만, 에러가 없으면 사람도 AI도 이상하다고 느끼기 어렵습니다. 이런 실패는 에러 로그 대신, AI가 절차를 벗어나 다른 방법으로 처리했거나 사용자가 결과를 바로잡은 흔적으로 드러날 수 있습니다. 프롬프트가 찾게 하는 신호 중 ‘스킬을 벗어난 즉흥 처리’와 ‘사용자의 교정 지시’가 이런 흔적을 잡습니다.

낡은 문서가 만드는 반복 비용

스킬 문서는 작성한 시점의 파일 구조와 절차를 기준으로 쓰입니다. 그런데 실제 파일은 계속 바뀝니다. 문서와 실제가 어긋나면 AI는 문서를 믿지 못하고 매번 실제 파일을 다시 열어봅니다. 실행할 때마다 같은 확인 비용을 내는 셈입니다. 로그에서는 이 동작이 ‘문서에 없는데 매번 반복된 수동 단계’로 남을 수 있습니다. 매번 어떤 파일을 다시 여는지 보이면, 문서의 어느 부분을 고쳐야 하는지도 함께 보입니다.

세션마다 흔들리는 애매한 규칙

해석의 여지가 있는 규칙은 세션마다 다르게 적용됩니다. 한 세션만 보면 어느 쪽 판단이든 그럴듯해서, 여러 세션을 나란히 놓고 봐야 같은 규칙이 다르게 해석되고 있다는 게 드러납니다. 해석이 어긋난 세션에는 사용자가 바로잡는 지시가 남을 수 있고, 이게 ‘사용자의 교정 지시’ 신호로 잡힙니다.

에러 로그만 봐서는 세 문제 모두 놓치기 쉽습니다. 교정 지시, 즉흥 처리, 반복된 수동 단계 같은 작업의 흔적까지 봐야 드러납니다.

하네스 리팩토링에서는 한 달에 한 번 정도 규칙과 스킬을 열어보고 “이거 아직도 필요한가?”를 물어보자고 했습니다. 스킬 점검 루프는 그 질문을 매주 실제 사용 기록으로 던지는 장치입니다.

스킬 점검 루프 프롬프트 전문

한 번 붙여넣어 등록해두면, AI가 매주 세션 로그와 스킬 문서를 대조해 변경안 보고서를 올려줍니다. 붙여넣을 곳은 Claude 데스크톱 앱의 Code 세션이나 ChatGPT 데스크톱 앱의 Codex 대화입니다.

매주 월요일 오전 9시에 실행되는 예약 작업을 "skill-refactoring-loop"라는 이름으로 등록해줘.
등록하기 전에 이 환경의 세션 기록과 스킬 파일 위치를 직접 확인해서 작업 본문에 반영해.

매주 할 일: 최근 1~2주 세션 기록을 근거로, 스킬 문서를 실제 사용 패턴에 맞게 업데이트해.

- 실제 실행된 스킬 중 실행이 잦았던 것부터, 한 번에 감당할 만한 개수를 네가 판단해서 골라. 스킬 문서와 실제 세션 기록을 대조해서 사용자의 교정 지시, 스킬을 벗어난 즉흥 처리, 반복된 에러, 문서에 없는데 매번 반복된 수동 단계를 찾아.
- 우연한 1회가 아니라 반복됐거나 사용자가 명시적으로 교정한 것만 변경안으로 만들어.
- 오랫동안 실행 기록이 없는 스킬은 아직 필요한지 내가 판단할 수 있게 제거 후보로 함께 보고해.
- 잘 작동하는 기존 지시는 건드리지 말고, 전면 재작성은 하지 마.
- 스킬 파일을 바로 수정하지 말고 변경안과 근거를 보고서로 남겨. 반영은 내가 보고서에 승인 표시를 한 뒤에만 해.
- 보고서는 매주 같은 폴더에 쌓고 직전 보고서를 이어받아서, 이미 제안했거나 기각된 내용을 반복하지 말고, 몇 주에 걸쳐 사용 중인 스킬 전체에 골고루 순서가 가게 해.
- 의미 있는 변경이 없으면 "변경 없음"이라고만 보고해.

프롬프트 설계 해설: 무엇을 고치고 무엇을 남기나

짧아 보여도 줄마다 막으려는 실패가 하나씩 있고, 대부분은 AI의 과잉 수정을 막는 장치입니다.

앞 세 줄: 위치를 고정하고 목표를 정한다

첫 줄은 이름과 일정을 정하고, 둘째 줄은 세션 기록과 스킬 파일 위치를 등록 시점에 직접 확인해 작업 본문에 적게 합니다. 위치와 형식이 도구, 설정, 버전마다 다르기 때문입니다. Claude Code만 해도 기록 형식은 버전마다 바뀔 수 있고, 저장 위치는 CLAUDE_CONFIG_DIR로 옮길 수 있습니다.

셋째 줄의 ‘업데이트해’는 목표입니다. 바로 고치라는 뜻이 아니라, 아래 지시대로 변경안과 승인을 거쳐 반영하라는 뜻으로 읽으면 됩니다. ‘업데이트해’와 ‘스킬 파일을 바로 수정하지 말고’가 함께 있어도 충돌하지 않는 이유입니다.

실행이 잦은 스킬부터, 감당할 만큼만

모든 스킬을 매주 다 보게 하면 보고서가 길어지고, 긴 보고서는 결국 안 읽게 됩니다. 자주 쓰는 스킬일수록 근거가 되는 기록도 많고, 고쳤을 때 효과도 큽니다. 범위를 ‘실제 실행된 스킬’로 좁힌 점도 중요합니다. 오랫동안 실행 기록이 없는 스킬은 이 단계에서 빠지고, 제거 후보로 따로 보고됩니다.

우연한 1회가 아니라 반복과 교정만

세션 로그에서 찾는 신호는 네 가지입니다.

찾는 신호	로그가 알려주는 지점
사용자의 교정 지시	스킬이 사용자의 기대와 어긋난 곳
스킬을 벗어난 즉흥 처리	문서대로는 안 돼서 AI가 우회한 곳
반복된 에러	같은 단계에서 계속 막히는 곳
문서에 없는데 매번 반복된 수동 단계	절차에 들어가야 할 단계가 빠진 곳

여기서 핵심은 “우연한 1회는 제외”라는 조건입니다. 한 번 일어난 일까지 규칙으로 만들면 스킬은 예외 처리만 잔뜩 붙은 긴 문서가 된다고 봅니다.

잘 작동하는 지시는 건드리지 않는다

개선하라는 지시만 주면 문서를 통째로 다시 쓰는 일이 생깁니다. 전면 재작성은 이미 검증된 지시까지 같이 흔듭니다. 변경안이 작아야 사람이 근거를 보고 승인할 수 있고, 문제가 생겨도 되돌리기 쉽습니다.

제거 후보는 지우지 않고 보고만

안 쓰는 스킬도 비용이 있습니다. Claude Code는 스킬 이름과 설명 목록에 모델 컨텍스트의 1%를 기본 예산으로 쓰고, 넘치면 덜 쓰는 스킬의 설명부터 뺍니다. Codex도 초기 스킬 목록에 컨텍스트의 최대 2%를 쓰고, 스킬이 많으면 설명부터 줄입니다.

그래도 가끔만 쓰는 중요한 스킬일 수 있으니 지울지는 사람이 판단합니다. 지우기 전에는 Codex의 [[skills.config]]로 끄거나, Claude Code의 skillOverrides로 설명 없이 이름만 노출하는 중간 단계도 있습니다.

보고서가 루프의 기억이 된다

예약 작업은 대개 실행마다 새 세션으로 시작하니, AI는 이전 실행에서 무엇을 제안했는지 기억하지 못합니다. 보고서를 같은 폴더에 쌓고 직전 보고서를 이어받게 한 건 이 때문입니다. “변경 없음”만 쓰게 한 건 억지 제안을 막기 위해서입니다. 매주 뭔가 고쳐야 한다는 압박이 없어야 보고서를 믿을 수 있습니다.

승인 없이 반영하면 나쁜 습관이 규칙으로 굳는다

한 가지만 주의하세요. 승인 없이 바로 반영하게 두면 일주일치 나쁜 습관까지 그대로 규칙으로 굳어버립니다.

세션 로그에는 잘한 일만 남지 않습니다. 급해서 대충 넘어간 처리, 그때만 필요했던 임시 예외, 귀찮아서 받아들인 우회도 똑같이 기록되죠. AI 입장에서는 “실제로 일어난 일”과 “앞으로 그래야 하는 일”을 구분하기 어렵습니다. 승인 단계는 그 둘을 사람이 걸러내는 필터입니다.

승인 표시와 반영 시점

이 프롬프트대로라면 반영은 이런 순서로 돌아갑니다.

1. 루프가 변경안과 근거를 보고서로 남깁니다.
2. 사람이 항목마다 승인이나 기각을 표시합니다.
3. 다음 실행이 직전 보고서를 읽고 승인된 항목만 스킬에 반영합니다. 기각된 항목은 다시 제안하지 않습니다.

승인한 변경은 최대 일주일 늦게 들어가는 셈입니다. 표시 형식은 프롬프트에 정해져 있지 않으니, 아래 예시 골격처럼 정해두면 됩니다.

변경안: <스킬 이름>
- 근거: <반복된 세션 장면>
- 제안: <추가하거나 바꿀 문장>
- 판정: 승인 / 기각 (사유: )

기각 사유를 한 줄 남겨두면 다음 실행이 같은 제안을 거르기 쉬워집니다. 또 Claude 데스크톱 앱이라면 처음 승인한 주에도 Run now로 직접 돌려 스킬 파일 수정을 always allow로 허용해두는 편이 낫다고 봅니다. 그래야 이후 무인 실행이 권한 확인에서 멈추지 않습니다.

OpenAI 문서 예시와 비교

OpenAI 문서에도 ~/.codex/sessions를 훑어 스킬 사용에 문제가 있었으면 스킬을 업데이트하라는 예약 작업 예시가 있습니다. 나란히 놓으면 차이가 분명합니다.

구분	OpenAI 문서 예시	스킬 점검 루프
보는 기간	지난 하루	최근 1~2주
변경 기준	좋은 이유가 있을 때만	반복됐거나 명시적으로 교정된 것만
반영 방식	스킬을 바로 업데이트하고 알려줌	보고서로 남기고 승인 후에만 반영
대상 범위	개인 스킬만	사용 중인 스킬 전체(개인·프로젝트 구분 없음)
우선순위	따로 없음	실행이 잦은 스킬부터 몇 주에 걸쳐 순환

어느 쪽이 정답이라기보다 단계의 차이죠. OpenAI 문서의 ‘처음 몇 번의 결과를 검토하며 프롬프트나 주기를 조정하라’는 예약 작업 전반에 대한 일반 권고입니다. 다만 저는 스킬을 바로 반영하는 방식도 신뢰가 쌓인 다음에 고르는 편이 맞다고 봅니다.

Claude Code와 Codex에서 예약 작업 등록하기

이 루프는 내 컴퓨터에 있는 세션 기록을 읽어야 하니, 예약 작업도 내 컴퓨터에서 돌아야 합니다. 세션 기록은 기본적으로 Claude Code가 ~/.claude/projects/<project>/<session-id>.jsonl에, Codex가 ~/.codex/sessions에 남깁니다.

Claude Code 세션 기록은 기본 30일 보관이고 cleanupPeriodDays로 바꿀 수 있습니다. 이 값을 2주보다 짧게 줄여뒀다면 1~2주치 기록 중 일부를 루프가 보지 못합니다.

두 앱 모두 실행마다 별도 Git worktree를 쓰는 옵션이 있습니다. 보고서를 한 폴더에 쌓아 이어받는 구조라, 저는 이 루프를 worktree 없이 돌리는 편이 맞다고 봅니다.

이 프롬프트는 보고서 위치를 정하지 않습니다. 고정하려면 프롬프트 블록은 그대로 두고, 맨 끝에 아래 한 줄을 덧붙이세요(경로는 각자 환경 값).

보고서는 <작업 폴더 안의 보고서 폴더 경로>에 쌓아.

Claude Code: 데스크톱 앱의 로컬 예약 작업

Claude Code의 예약 방식은 세 가지입니다. 데스크톱 앱의 Routines 페이지에서는 로컬 예약 작업과 원격 routine(클라우드)을 모두 만들 수 있는데, 이 루프는 Local로 만듭니다.

방식	실행 위치	로컬 파일 접근	이 루프에 맞나
원격 routine(클라우드, /schedule)	Anthropic 클라우드	불가 (새로 clone)	세션 기록을 못 봄
로컬 예약 작업(데스크톱)	내 컴퓨터	가능	적합
/loop	내 컴퓨터의 열린 세션	가능	세션 유지 필요, 7일 뒤 만료

Claude 데스크톱 앱의 Code 탭 세션에 프롬프트를 붙여넣으면 됩니다. 첫 줄이 등록 요청이라, 제 판단으로는 New routine 폼의 Instructions 칸에 통째로 넣기보다 세션에서 AI가 작업 본문을 쓰게 하는 편이 맞다고 봅니다. 만들어진 작업은 Routines 목록에서 열어, 상세 페이지의 Edit에서 일정이 매주 월요일 오전 9시인지 확인하세요.

운영할 때 알아둘 점은 두 가지입니다.

1. 앱이 켜져 있고 컴퓨터가 깨어 있어야 실행됩니다. 놓친 실행은 최근 7일 안에서 가장 최근 것 하나만 따라잡지만, 기간을 1~2주로 잡아뒀으니 늦게 돌아도 괜찮습니다.
2. 등록 직후 Run now로 한 번 돌려보세요. 권한이 필요한 도구에서 실행이 멈출 수 있는데, 첫 실행에서 always allow를 골라두면 다음 실행부터는 같은 도구를 묻지 않습니다.

Codex: ChatGPT 데스크톱 앱에서 등록

Codex 앱은 2026년 7월 9일 새 ChatGPT 데스크톱 앱으로 합쳐졌습니다.

등록은 데스크톱 앱의 Codex 대화에 프롬프트를 붙여넣되, 실행마다 새 대화로 시작하는 독립 예약 작업으로 만들어 달라고 덧붙이면 됩니다. 독립 예약 작업은 매번 저장된 프롬프트로 시작해 결과를 Scheduled 화면에 올리고, 채팅 안 예약 작업은 등록한 채팅의 맥락으로 돌아옵니다. 주의할 점은 이렇습니다.

• Codex CLI와 IDE 확장에는 예약 작업 관리 화면이 없습니다. CLI는 프롬프트 시험용으로 쓰고, 등록은 데스크톱 앱에서 하세요.
• 웹에서 만든 예약 작업은 내 컴퓨터 폴더를 직접 다루지 못합니다. 데스크톱 앱에서 로컬 프로젝트를 고르고, 실행 시점에 컴퓨터와 앱을 켜두세요.
• 기본 샌드박스 설정으로 무인 실행됩니다. workspace-write 모드에서는 작업 공간 밖 파일 수정이 실패합니다. 개인 스킬(~/.agents/skills)처럼 작업 공간 밖의 스킬은 그 폴더를 writable roots에 넣어야 승인 항목을 반영할 수 있고, 보고서 폴더도 작업 공간 안이나 writable roots에 있어야 기록됩니다.
• writable roots를 늘리고 싶지 않다면 루프에는 보고서까지만 맡기고, 승인한 변경은 평소 Codex 대화에서 직접 반영하는 방법도 있습니다.

스킬 점검 자동화는 작은 개선 루프다

제가 더 중요하게 보는 건 이 프롬프트의 구조입니다. 이 자동화는 그 자체로 하나의 작은 개선 루프입니다.

1. AI가 스킬을 써서 일합니다.
2. 그 과정이 세션 로그로 남습니다.
3. 매주 루프가 로그와 스킬 문서를 대조해 변경안을 올립니다.
4. 사람이 승인할 것만 고릅니다.
5. 승인된 변경이 스킬에 남고, 다음 작업이 더 좋아집니다.

Loop Engineering에서 이야기한 Worker와 Verifier 분리가 여기에도 들어 있습니다. 평소 세션의 AI가 Worker라면 매주 로그를 읽는 루프가 Verifier입니다. 일하는 세션과 검증하는 세션이 달라서 자기 결과를 좋게 보는 편향도 줄어든다고 봅니다. 실패 비용이 큰 작업일수록 사람 승인까지 넣는다는 기준도 같습니다.

사람이 하는 일도 달라집니다. 스킬을 직접 열어 고치는 게 아니라, 근거가 붙은 변경안 중에서 고르기만 하면 되죠.

스킬 점검 루프 적용 기준과 다음 단계

정리하면, 스킬은 만드는 순간보다 쓰이는 동안이 더 중요하고, 그 동안의 기록은 세션 로그에 남습니다. 스킬이 몇 개 안 되고 거의 매일 직접 손보고 있다면 아직은 수동 점검으로도 충분할 것 같아요. 스킬이 쌓여서 어떤 게 실제로 쓰이는지 감이 안 오기 시작했다면, 그때가 루프를 붙일 시점입니다.

적용 순서는 간단합니다. 프롬프트를 Claude 데스크톱 앱이나 ChatGPT 데스크톱 앱의 Codex에 붙여넣고, Claude 데스크톱 앱이라면 등록 직후 Run now로, Codex라면 첫 예약 실행 뒤 Scheduled 화면에서 첫 보고서를 확인하세요. 처음 몇 주는 변경안을 직접 읽고 승인하면서 제안의 질을 확인하고, 신뢰가 쌓이면 그때 승인 범위를 풀어주면 됩니다.

여러분이 만든 스킬 중에 지금 제 역할을 못 하고 있는 건 몇 개일까요? 스킬을 만들지만 말고, 스킬을 점검하는 루프를 붙여보면 좋겠습니다.