code-recall — 코드 이해도 퀴즈로 인지부채 회수

인지부채는 시스템에 존재하는 코드량과 사람이 실제로 이해한 양의 격차다. 이 스킬은 능동 회상(retrieval practice)으로 그 격차를 측정하고 좁힌다.

핵심 규칙: 출제 근거는 항상 실제로 읽은 코드다. diff 조각이나 추측으로 문항을 만들면 잘못된 이해를 강화해 부채를 오히려 늘린다. 근거 없는 문항은 만들지 않는다.

0단계 — 레포 식별 및 로그 로드

대상 레포는 이 순서로 정한다:

1. 사용자가 경로나 레포명을 지정하면(code-recall ~/work/billing, 빌링 퀴즈) 그것
2. 없으면 현재 작업 디렉터리
3. 현재 위치가 git 레포가 아니면(예: 홈 디렉터리) 묻는다. 추측해서 아무 레포나 고르지 않는다. 기존 로그가 있으면 그 목록을 보여주고 고르게 한다:

   ls ~/.claude/code-recall/*.md 2>/dev/null

레포가 정해지면 보조 스크립트로 컨텍스트를 한 번에 얻는다 — 결정적 단계(레포 식별, 로그 파싱, SHA 소실 폴백, 변경분·강등 후보 검출)는 모델 재량이 아니라 스크립트가 수행한다:

bash ~/.claude/skills/code-recall/scripts/code-recall.sh context <레포>
# repo_root / slug / branch / head / 로그 존재 여부 / last_session_* /
# changed_files (SHA 소실 시 날짜 폴백 자동) / demote_candidates (앵커 파일이 변경된 개념)

스크립트가 없으면(부분 설치) git rev-parse --show-toplevel / --abbrev-ref HEAD / --short HEAD 로 같은 정보를 직접 수집한다.

레포 슬러그 = 레포 디렉터리명. 로그 파일은 한 곳에만 둔다:

~/.claude/code-recall/<슬러그>.md

• 없으면 mkdir -p ~/.claude/code-recall 로 만든다.
• 대상 프로젝트 레포에는 아무 파일도 만들지 않는다. 로그는 개인 학습 이력이므로 레포·PR에 섞이면 안 된다.
• 외부 도구(노트 앱·동기화 폴더 등)를 전제하지 않는다. 이 스킬은 ~/.claude 와 git 만 있으면 어느 환경에서든 동작해야 한다.
• 같은 슬러그의 다른 레포일 수 있으니, 로그를 열면 frontmatter의 repo_path 가 지금 대상과 일치하는지 확인한다. 다르면 사용자에게 알리고 <슬러그>-2.md 처럼 분리한다.

로그가 없으면 아래 스키마로 새로 만든다. 있으면 읽고 시작한다.

---
repo: <슬러그>
repo_path: <절대경로>
last_session_sha: <SHA>
last_session_date: <YYYY-MM-DD>
sessions: 0
bootstrap: none | partial | full
---

## 도메인 지도 (L0)
<부트스트랩에서 파악한 계층 구조, 엔트리포인트, 요청이 흐르는 경로.
 다음 회차에 재탐색을 생략하기 위한 캐시이자 L0 문항의 출처.>

## 개념 상태 (L1)
| 개념 | 앵커 | 상태 | 마지막 회차 | 확신오답 |
|---|---|---|---|---|
| 주문 상태 전이 규칙 | src/domain/order.ts:142 | 검증됨 | 2026-08-03 | 0 |
| 레이어 아키텍처 | 📄 docs/arch.md:12 | 미학습 | - | 0 |

<상태: 미학습 / 학습중 / 검증됨>

## 불변식 (L2)
| 불변식 | 앵커 | 깨지면 | 상태 |
|---|---|---|---|
| 회원 등급 변경 시 사용자 캐시를 무효화해야 한다 | src/repo/user-repo.ts:266 | 최대 7일 stale | 미학습 |

## 오답 재료
<스캐너가 보고한 "실수하기 쉬운 지점". 그럴듯한 오답(distractor)의 원천.>
- <혼동 유발 지점> | <앵커> | <어떻게 오해하기 쉬운지>

## 재출제 큐
- [ ] <개념> — 사유(확신 오답 / 애매한 정답)

## 열린 질문
- <코드만으로는 "왜"가 확인되지 않은 것. 추측으로 메우지 말고 여기 적립.>

## 문항 이슈
- <이의가 인정돼 폐기한 문항과 원인. 같은 유형의 나쁜 문항을 피하기 위한 기록.>

## 미탐색 영역
- <부트스트랩에서 읽지 못한 모듈. 다음 회차가 이어받는다. 비면 bootstrap: full 로 승격.>

## 회차 기록
- <N회차 (날짜)>: <무엇을 읽고 무엇을 냈는지 한 줄>

앵커 규칙: 앵커는 원칙적으로 코드(파일:라인)다. 문서에서 얻어 아직 코드로 확인하지 못한 항목은 앵커 앞에 📄 를 붙인다 — 📄 앵커는 "코드 확인 전"이라는 뜻이고, 그 개념을 출제하기 전에(늦어도 출제하는 회차에) 코드 실물을 확인해 코드 앵커로 교체한다. 📄 인 채로 L2 확신 문항을 만들지 않는다.

도메인 지도 (L0)가 있으면 그것을 신뢰하고 전체 탐색을 생략한다 — 부트스트랩은 레포당 1회다. 캐시된 경로가 실제로 존재하지 않을 때만 그 부분을 다시 확인하고 갱신한다.

1단계 — 출제 대상 선정

먼저 강등을 반영한다. context 리포트의 demote_candidates(앵커 파일이 변경된 개념·불변식)는 상태를 검증됨 → 학습중 으로 내리고 출제 후보에 올린다. 코드가 바뀌면 검증은 낡은 것이다 — 2단계에서 해당 코드를 다시 읽고 출제해, 통과하면 다시 검증됨 으로 올린다.

우선순위대로 5문제 분량만 고른다. 넓게 훑지 말고 한 회차는 1~2개 주제에 집중한다.

1. 재출제 큐 — 지난 회차의 확신 오답 (가장 위험한 부채)
2. 변경분 — context 리포트의 changed_files (SHA 소실 시 날짜 폴백은 스크립트가 처리). 작성자를 구분하지 않는다. 남이 올린 코드도 이해 대상이다.
3. 미학습 개념 — 개념 상태에 없는 영역
4. 오래된 검증 — 검증됨이지만 마지막 회차가 오래된 것

사용자가 범위를 지정하면(code-recall 캐시 쪽, 이번 주 변경분) 그것을 우선한다.

낼 것이 없으면 없다고 말한다. 재출제 큐가 비고, 변경분이 없고, 전 개념이 최근 검증됨이면 "오늘은 회수할 부채가 없다"고 보고하고 끝낸다 — 이것도 유효한 결과다. 억지로 5문제를 채우려고 지엽적인 문항을 만들지 않는다.

첫 회차 = 부트스트랩 (로그가 없을 때)

여기서만 비용을 크게 쓴다. 도메인 개념을 정확히 잡지 못하면 이후 모든 문항이 부정확해지고, 잘못된 이해를 강화해 부채를 오히려 늘린다. 커밋 빈도 같은 메타데이터는 어디가 중요한지는 알려주지만 그 개념이 무엇인지는 알려주지 않으므로, 도메인 코드는 실제로 읽어야 한다.

대신 결과를 로그에 영속화해 두 번 하지 않는다. 부트스트랩 1회는 크게 허용하고(수백k), 2회차 이후는 15k 이하로 돌아온다.

시작 전에 반드시 동의를 받는다. 사용자는 "3~5분짜리 퀴즈"를 기대하고 불렀을 수 있다. B1(값싼 신호)까지만 돌린 뒤 규모를 보여주고 선택하게 한다:

• 전체 부트스트랩 — 도메인 모듈 N개를 스캐너로 병렬 독해 (1회, 비용 큼)
• 빠른 시작 — 문서(CLAUDE.md·README·프로젝트 스킬)만 읽고 바로 첫 퀴즈. 로그에 bootstrap: partial 로 남기고, 코드 계층은 이후 회차가 나눠서 채운다

B1. 값싼 신호로 읽을 순서 정하기 (파일 내용 안 읽음)

# 규모
git -C <레포> ls-files | wc -l

# 디렉터리별 파일 수 → 어디에 무게가 실려 있나
git -C <레포> ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

# 최근 6개월 변경 핫스팟
git -C <레포> log --since=6.months --name-only --pretty=format: \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -20

핫스팟 상위에 CI 설정·.claude/·문서가 올라오는 경우가 흔하다. 이 신호는 도메인 코드 안에서의 순위로만 쓰고, 비코드 경로는 걸러서 본다.

과거 Claude Code 세션 신호 — 있으면 쓰고 없으면 건너뛴다. 트랜스크립트는 ~/.claude/projects/<절대경로의 / 를 - 로 치환>/*.jsonl 에 있고, worktree마다 디렉터리가 갈리므로 슬러그로 와일드카드 매칭해 합산한다. 파일이 수십 MB라도 경로만 뽑으면 0.1초 안에 끝난다:

grep -oh '"file_path":"[^"]*"' ~/.claude/projects/*<슬러그>*/*.jsonl 2>/dev/null \
  | sed 's/^"file_path":"//;s/"$//' \
  | grep -v '/\.claude/\|/\.github/\|CLAUDE\.md\|/memory/' \
  | sort | uniq -c | sort -rn | head -20

이 목록은 최근 실제로 작업한 영역을 보여주므로 부채 후보로 정확도가 높다. 단, 경로 빈도만 쓴다 — 트랜스크립트 내용은 파싱하지 않는다(아래 경고).

B2. 선별적 심층 독해 — 순서가 중요하다

0순위: 팀이 이미 정리해 둔 문서를 코드보다 먼저 읽는다. 코드보다 싸고, 코드 독해로는 절대 얻을 수 없는 정책이 여기 있다.

• CLAUDE.md, README, docs/, ADR, .github/*.md
• 프로젝트 자체 스킬 .claude/skills/*/SKILL.md — 아키텍처·컨벤션 스킬이 있으면 최우선
• 단, 문서는 낡을 수 있다. 문서에서 얻은 불변식도 앵커를 코드에 걸어 한 번 확인한다.

실측 예: 어떤 레포는 아키텍처 스킬에 레이어·인증·에러·캐싱 정책이 정리돼 있었고, CLAUDE.md가 "코드만 봐서는 오해하는 정책" 을 명시적으로 경고하고 있었다 — 이를테면 모든 에러를 단일 상태 코드로 내보내는 규약이나, ORM이 관리 화면에만 쓰이고 일반 쿼리는 raw SQL이라는 사실 같은 것. 이런 항목은 코드를 몇 시간 읽어도 나오지 않는 L2 불변식이면서, 모르면 잘못된 문항을 만들게 되는 지점이다.

1순위 이후: 코드

테스트는 본문을 읽지 않고 파일명·describe 목록만 훑는다 — 불변식 힌트로 값이 싸다.

건너뛰는 쪽이 보통 파일 수의 절반 이상이다. 걸러내면 비용은 줄고 정확도는 오른다.

B3. 컨텍스트 격리

도메인 모듈 단위로 쪼개 code-recall-scanner 에이전트를 모듈당 1개 스폰한다(병렬). 각 스캐너는 자기 컨텍스트에서 읽고 개념 · 앵커 · 불변식 · 실수하기 쉬운 지점만 반환한다.

• 정의: ~/.claude/agents/code-recall-scanner.md — 툴이 Read, Grep, Glob 뿐이라 구조적으로 읽기 전용이고, 출력 프로토콜이 코드 전문 반환을 금지한다.
• 스킬과 함께 배포해야 한다. 에이전트가 없으면 아래 폴백으로 내려간다.

메인 대화에 코드 전문을 쌓지 않는다 — 컨텍스트가 코드로 가득 차면 정작 퀴즈 품질이 떨어진다.

폴백: 에이전트를 쓸 수 없으면(미배포, 또는 세션 정책상 서브에이전트 호출 금지) 모듈을 여러 회차로 나눠 직접 읽는다. 이때 로그 frontmatter에 bootstrap: partial 을 남기고 미탐색 영역 에 남은 모듈을 적어, 다음 회차가 이어받게 한다.

B4. 산출물을 로그에 영속화

• 도메인 지도 (L0) — 계층과 요청 흐름
• 개념 상태 (L1) — 개념명 + 앵커. 상태는 전부 미학습으로 시작
• 불변식 (L2) — 깨지면 버그가 되는 전제. 문항 가치가 가장 높다
• 오답 재료 — 스캐너의 "실수하기 쉬운 지점". 버리지 않는다 — 이후 모든 회차의 distractor 원천이다
• 열린 질문 — 코드로 확인되지 않은 "왜"
• 미탐색 영역 — 못 읽은 모듈. frontmatter bootstrap: 을 full/partial 로 기록

B5. 첫 퀴즈

부트스트랩 직후엔 L0~L1 위주로 5문제. 방금 읽었다는 이유로 L2 불변식부터 묻지 않는다. 부트스트랩 회차는 이미 코드를 읽었으므로 2단계(앵커 확장)를 건너뛰고 바로 3단계로 간다.

부채 우선순위 = (커밋 빈도 + 세션 접촉 빈도) × 이해도 낮음. 자주 바뀌는데 미학습인 영역이 가장 위험하다. 6개월간 아무도 건드리지 않은 파일은 후순위다.

⚠️ 트랜스크립트를 지식의 출처로 쓰지 않는다. 과거 세션에는 폐기된 접근, 틀린 추측, 중간 상태가 섞여 있다. 그것을 근거로 출제하면 오염된 이해를 학습시킨다. 트랜스크립트는 "어디를 봐야 하나" 만 알려주는 신호이고, 개념의 내용은 항상 현재 코드에서 검증한다.

2단계 — 앵커 확장 (이 스킬의 핵심)

diff만 보고 출제하지 않는다. 고른 대상마다 실제 코드를 읽어 맥락을 확보한다.

1. 변경/대상 영역에서 심볼(함수·클래스·상수·필드)을 뽑는다.

   git diff -U0 <sha>..HEAD -- <path>   # hunk 헤더에 함수명이 실림

2. 각 심볼의 정의부를 읽는다.
3. 각 심볼의 주요 호출부를 찾아 읽는다 — 이 단계가 도메인 의미를 만든다.

   grep -rn "<심볼>" --include="<확장자>" .

4. 코드만으로 "왜"가 안 나오면 근거를 더 찾는다. 사용 가능한 것만 쓰고 없으면 건너뛴다 (특정 도구가 설치돼 있다고 전제하지 않는다):
   • 커밋 메시지 — git log --format='%B' -n 5 -- <path> (어디서나 가능)
   • 레포 내 문서 — docs/, ADR, README, CLAUDE.md (어디서나 가능)
   • PR 설명·리뷰 코멘트 — gh pr list --search <심볼> (또는 그 조직의 GitHub 스킬)
   • 이슈 트래커·위키 — 해당 스킬이 설치돼 있을 때만
   • 그래도 확인 불가면 문항으로 만들지 말고 열린 질문에 적립한다

예산: 읽는 파일 5개 이하, 회차당 총 15k 토큰 이하. 초과할 것 같으면 주제를 좁힌다.

3단계 — 브리핑 (모르는 개념만)

개념 상태가 미학습인 개념은 문제부터 내지 않는다. 백지 상태에서 인출 실패만 반복하면 학습 효과가 없다. 5~10줄 브리핑을 먼저 제시하고 그다음 출제한다.

난이도 램프:

학습중(한 번 이상 접한 개념)과 검증됨은 브리핑 없이 바로 묻는다 — 검증됨은 L2로.

4단계 — 객관식 5문제 + 확신도

한 번에 한 문제씩 제시한다. 5문제를 한꺼번에 나열하지 않는다.

Q1. [앵커: src/repo/user-repo.ts:227]
<질문>

(a) ...
(b) ...
(c) ...
(d) ...

답과 확신도를 함께 알려주세요 — 예: "b, 확실" / "b, 애매"

출제 규칙

• 예측형으로 만든다. "이 함수에 null이 들어오면 무엇이 반환되나" 처럼 실행 모델을 인출하게 한다. 용어 암기를 묻지 않는다.
• 그럴듯한 오답(plausible distractors)을 쓴다. 실제로 있을 법한 잘못된 이해를 오답으로 삼는다. 사소한 오답은 소거법으로 뚫려 학습 효과가 0이 된다.
• 모든 문항에 앵커(file:line)를 붙인다. 앵커를 댈 수 없는 문항은 폐기한다.
• 출제 앵글: 설계 근거와 검토된 대안 · 엣지 케이스 실패 모드(null·빈 값·예상 밖 입력) · 시스템 전반 파급 효과 · 제약 위반의 결과 · 컴포넌트 간 통신 · 가장 위험한 가정과 외부 의존성
• 한 문항이 한 가지만 묻게 한다. 복합 문항은 어디서 틀렸는지 알 수 없다.

5단계 — 채점과 오답 처리

즉시 피드백한다. 회차 끝까지 미루면 오답 선택지를 잘못 학습할 수 있다.

확신도에 따라 처리 강도를 나눈다:

• 설명은 짧게, 근거는 반드시 코드 인용으로. 레포 내 관련 문서(docs/, ADR, README)나 개인 노트가 있으면 그 위치까지 함께 짚는다.
• 오답 선택지를 더 파고들 때도 서술형으로 바꾸지 않는다. "왜 (b)가 아닌가?"를 다시 4지선다로 물어 변별을 훈련한다.
• 서술형은 기본 경로에서 쓰지 않는다. 같은 개념에서 확신 오답이 3회 이상 누적됐거나 사용자가 직접 요청할 때만 예외로 1문제 낸다.
• 문항에 이의가 제기되면 사용자가 아니라 문항을 먼저 의심한다. "문제가 이상하다 / 코드랑 다르다"는 반응이 오면 방어하지 말고 앵커 코드를 다시 읽어 검증한다. 문항이 틀렸으면 그 문제는 채점에서 제외하고(오답 카운트 없음) 로그의 문항 이슈 에 무엇이 왜 틀렸는지 기록한다 — 같은 유형의 나쁜 문항을 반복 생성하지 않기 위한 데이터다.

회차 끝에 이렇게 마무리한다:

5문제 중 N정답 · 확신 오답 M개
가장 위험한 지점: <확신 오답 1개를 짚는다>
다음 회차 예고: <재출제 큐에서 무엇이 나올지>

시스템 워크 모드 (월 1회 권장)

객관식은 국소 사실의 회상을 재는 데 강하지만, 인지부채의 본질인 시스템 모델의 부재는 못 잰다. "시스템 워크", "플로우 설명", "추적 퀴즈" 요청 시, 또는 회차 기록에 (워크) 가 30일 이상 없으면 이 모드로의 대체를 먼저 제안한다.

1. 도메인 지도(L0)에서 실제 요청/플로우 하나를 고른다 (예: "일정 생성 요청이 저장되기까지").
2. 사용자가 코드를 보지 않고 각 계층에서 무슨 일이 일어나는지 설명한다.
3. Claude 는 계층 하나씩 설명을 앵커 코드와 대조해 맞음·누락·오해를 짚는다.
4. 설명이 막히거나 틀린 지점이 부채 핫스팟이다 — 해당 개념을 미학습/학습중 으로 로그에 반영하고 다음 객관식 회차의 최우선 대상으로 올린다.
5. 회차 기록에 (워크) 표시로 남긴다.

객관식이 넓이를 유지하고 워크가 깊이를 검증한다 — 대체재가 아니라 보완재다.

6단계 — 로그 갱신

Edit으로 로그 파일을 갱신한다. 매번 통째로 다시 쓰지 않는다.

• frontmatter: last_session_sha(현재 HEAD), last_session_date, sessions +1
• 개념 상태 (L1)·불변식 (L2): 출제된 항목의 상태·마지막 회차·확신오답 갱신 (L2도 L1과 같은 상태 전이를 따른다: 미학습 → 학습중 → 검증됨)
• 📄 앵커: 이번에 코드로 확인한 것은 코드 앵커로 교체
• 재출제 큐: 확신 오답 추가, 이번에 해소된 항목 체크
• 열린 질문: 이번에 확인 못 한 "왜" 적립 / 답을 얻은 항목은 해소 표시 후 관련 L1·L2에 반영
• 도메인 지도 (L0)·오답 재료: 새로 파악한 것이 있으면 반영
• 문항 이슈: 이의가 인정돼 폐기한 문항이 있으면 기록
• 회차 기록: 이번 회차 한 줄 추가 (시스템 워크 회차는 (워크) 표시)
• 갱신 후 스키마 검증: bash ~/.claude/skills/code-recall/scripts/code-recall.sh validate-log <로그>

하지 않을 것

• 프로젝트 레포에 파일 생성 — 로그는 ~/.claude/code-recall/ 에만
• 특정 노트 앱·동기화 폴더·개인 경로 전제 — 팀에 배포되는 스킬이다. ~/.claude 와 git 외의 환경을 요구하지 않는다
• 부트스트랩 반복 — 레포당 1회다. 2회차 이후는 로그의 L0·L1·L2를 재사용하고 회차마다 1~2개 주제로 좁힌다. 로그가 있는데 다시 전체를 훑고 있으면 잘못 가고 있는 것이다
• 부트스트랩에서 테스트 본문·생성 코드·벤더·설정까지 균등하게 읽기 — 도메인 계층만 읽는다
• 추측 출제 — 확인 안 된 "왜"는 열린 질문으로
• AI 생성 코드만 대상으로 삼기 — 프로젝트 전체가 이해 대상이다
• 서술형 기본 사용 — 진입 장벽만 높이고 채점 신호가 흔들린다
• 회차 끝까지 피드백 미루기

톤

시니어 동료처럼. 엄격하되 함정을 파지 않는다. 목표는 점수가 아니라 어디를 모르는지 정확히 드러내는 것이다. 잘한 부분은 명시적으로 인정한다.