Study Notes — 레포지토리 분석 누적 기록 스킬

작업 디렉토리(레포 루트)의 STUDY_NOTES.md에 분석 결과를 시간순으로 누적 기록한다.

핵심 원칙

• 누적 only, 덮어쓰기 금지: 새 발견은 항상 새 섹션으로 추가. 기존 섹션은 보존.
• 재사용 가능한 이해만 기록: 구조·패턴·관례·결정 근거. 일회성 명령 결과나 디버깅 로그는 기록하지 않음.
• 명시적 분석 요청에만 발동: 짧은 작업·단일 질문·피처 추가·버그 수정에는 발동하지 않음.

발동 조건

다음과 같은 사용자 요청이 있을 때 발동:

• "이 레포 분석해줘"
• "이 코드베이스 이해해보자"
• "이 프로젝트 어떻게 만들어졌는지"
• "전반적으로 어떻게 동작하는지"
• "구조 파악"
• 영어: "analyze this repo", "walk me through the codebase", "understand this project"

다음에는 발동하지 않음:

• "이 함수 뭐 하는지" (단일 질문)
• "버그 고쳐줘" (수정 작업)
• "테스트 짜줘" (생성 작업)
• "파일 어디 있어?" (탐색)

동작

1. 파일 위치 확인

작업 디렉토리(pwd) 루트에 STUDY_NOTES.md 존재 확인.

2. 파일 없으면 생성

다음 헤더로 시작:

# STUDY_NOTES — {레포명 또는 디렉토리명}

이 레포지토리를 분석하며 알게 된 내용을 시간순으로 누적합니다.
섹션 형식: `## YYYY-MM-DD - 주제`

---

3. 새 섹션 추가

파일 끝에 다음 형식으로 append:

---

## YYYY-MM-DD - 주제

[알게 된 내용]

• 날짜는 현재 날짜(절대 날짜)로 기록. "오늘", "어제" 같은 상대 표현 금지.
• 같은 날짜에 새 주제가 생기면 별도 섹션으로 분리. 한 섹션에 몰아넣지 않음.
• 주제는 한 줄로 명확하게. (예: "레포 빌드 히스토리", "마켓플레이스의 정체", "스킬별 활용도 평가")

4. 정정·보완 시

기존에 기록한 내용이 틀렸거나 갱신이 필요하면, 기존 섹션은 그대로 두고 새 섹션에 "정정/보완" 표시로 추가.

## 2026-04-27 - 마켓플레이스 정체 (정정)

이전 섹션의 X 부분이 틀렸음. 실제로는 Y가 맞음.
근거: ...

시간순 누적이 원칙이므로 과거 기록을 수정하지 않는다.

무엇을 기록하나

✅ 기록 대상:

• 레포 구조와 디렉토리 의도
• 핵심 메커니즘과 동작 원리
• 관례·컨벤션·스키마
• 결정 근거 (왜 이렇게 만들어졌나)
• 빌드/CI/릴리즈 파이프라인
• 외부 의존성과 통합 포인트
• 사용자가 명시적으로 기록 요청한 내용

❌ 기록 안 함:

• 단순 명령 실행 결과
• 일회성 디버깅 추적
• 임시 작업 상태 (TASKS, plan)
• 재현 불가능한 환경 의존 정보
• 이미 README/CLAUDE.md/CHANGELOG에 잘 적힌 내용 (포인터만 남김)

사용자 통제

다음 발화가 있으면 즉시 동작 변경:

• "기록하지 마" / "노트 안 남겨도 돼" → 이번 분석은 기록 스킵
• "이건 기록해" → 명시적 기록 (필터 무시)
• "STUDY_NOTES 정리해줘" → 중복 제거·재구성 모드 (단, 시간순 보존)

출력

기록 완료 시 한 줄로 보고:

STUDY_NOTES.md에 "{주제}" 섹션 추가했습니다. 이제 N개 섹션.

여러 섹션을 한 번에 추가했으면 추가된 섹션 제목들을 나열.

예시 흐름

사용자: "이 레포 분석해줘" → 분석 진행 (Read, Bash로 git log, ls 등) → 알게 된 내용을 종합 → STUDY_NOTES.md 없으면 생성, 있으면 append → "STUDY_NOTES.md 생성. '레포지토리 정체와 전체 구조' 섹션 추가. 1개 섹션."

사용자: "이 레포 어떻게 만들어졌는지 궁금해" → git log 분석 → "STUDY_NOTES.md에 '레포 빌드 히스토리' 섹션 추가. 7개 섹션."

Anti-patterns

• 짧은 질문 하나에도 STUDY_NOTES 갱신 (과발동)
• 한 섹션에 여러 주제 몰아넣기 (검색·재사용 어려워짐)
• 명령 출력을 그대로 붙여넣기 (요약·정제 필요)
• 동일 사실 중복 기록 (먼저 기존 섹션 확인)
• 기존 섹션 수정·삭제 (시간순 누적 원칙 위반)
• "오늘", "방금" 같은 상대 시간 표현 (절대 날짜로)