learn

name	learn
description	업무 중 새로 알게 된 사실(코드/DB에서 발견한 암묵적 규칙, 고객사 패턴, 팀 관례)을 검증하고 구체화하여 공식 문서(biz-rules, 모듈 문서 등)에 반영할 때.
when_to_use	이거 알게 됐어, 새로 발견한 사실 문서에 반영, 암묵 규칙 기록. 10건 이상 일괄 흡수는 absorb 명시 호출, 시행착오는 pitfall.
allowed-tools	Read, Write, Glob, Grep, Bash

역할

사용자가 업무 중 알게 된 사실, 발견, 규칙을 전달하면:

1. 팩트체크: 코드베이스, 설정, 기존 문서와 대조하여 사실 여부 검증
2. 구체화: 추상적이거나 모호하면 재질문하여 정확한 지식으로 가공
3. 문서 반영: 관련 문서(CLAUDE.md, biz-rules.md, bot/*.md 또는 .local.claude/ONBOARDING.md 등)에 반영이 필요하면 제안 및 적용
4. 이력 저장: 검증된 지식을 파일로 남겨 축적

핵심 원칙: 검증되지 않은 지식은 문서에 반영하지 않는다. 코드에서 확인할 수 있는 것은 반드시 확인하고, 확인 불가능한 것은 [확인 필요] 태그를 붙인다.

톤: 호기심 많은 동료 개발자.

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 SW 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	Tier 1(도메인 무관) 점검만 수행
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
기존 지식 문서	CLAUDE.md, biz-rules.md, modules/, customers/	선택	중복 확인 생략, 이력만 기록
auto memory	MEMORY.md + 하위	선택	메모리 통합 판단 생략

입력 처리

$ARGUMENTS에 알게 된 사실을 자유롭게 입력:

/learn 배포는 무중단 롤링 아니라서 일정 잡을 때 점검 시간 따로 봐야 함
/learn 소프트 딜리트 컨벤션이 코드 컬럼 기반이라 WHERE 조건에서 필터링 필요
/learn {고객사} 환경은 본 SaaS 와 별도 인스턴스이지만 핵심 로직은 동기 유지
/learn 코드 리뷰는 정기적으로 진행되며, 정적 분석 워닝 0건이 머지 기준

프로세스

1단계: 지식 파싱

입력에서 핵심 주장을 추출:

항목	설명
주장	사용자가 말한 사실/규칙/발견
분류	아키텍처 / 인프라 / 코딩 규칙 / 비즈니스 규칙 / 프로세스 / 도구 / 고객사 / 기타
검증 가능 여부	코드/설정에서 확인 가능한지, 아니면 사람에게 들은 것인지

1-1단계: 기존 문서 중복 확인

팩트체크 전에 이미 기록된 지식인지 확인한다. 중복 기록 방지.

검색 대상:

• CLAUDE.md, ~/.claude/CLAUDE.md
• .local.claude/biz-rules.md, bot/*.md 또는 ONBOARDING.md, INFRASTRUCTURE.md
• .local.claude/modules/*.md, customers/*.md
• .local.claude/learn/*.md (이전 캡처 이력)

결과	행동
이미 동일한 내용이 기록됨	"이미 [문서명] N번 줄에 기록되어 있습니다" 안내 후, 보완할 내용만 있으면 추가 제안
유사하지만 불완전	기존 기록 + 새 정보를 합쳐서 보강 제안
기록 없음	다음 단계(팩트체크) 진행

[1M 활용] 서브 분할 없이 메인에서 직접 다중 파일 동시 로드 후 교차:

• 로드: CLAUDE.md, .local.claude/biz-rules.md, .local.claude/modules/*.md 관련 모듈, .local.claude/customers/*.md 관련 고객사, .local.claude/learn/*.md 이전 캡처 이력
• 교차: {이번 주장 vs 기존 문서 중복/충돌}, {여러 문서에 조각조각 있는 정보 통합(재기록 방지)}, {이전 learn 캡처의 결론이 번복되는지}

2단계: 팩트체크

코드 검증 가능한 주장:

• Grep, Read로 코드베이스에서 직접 확인
• 설정 파일(application.yml, pom.xml 등) 확인
• 기존 문서(CLAUDE.md, bot/.md 또는 ONBOARDING.md, biz-rules.md, modules/.md)와 대조
• 결과: [OK] 확인됨 / [FAIL] 틀림 / [WARN] 부분적 / [미정] 코드에서 확인 불가

코드 검증 불가능한 주장 (프로세스, 조직 관련 등):

• 기존 문서에 이미 기록된 내용과 충돌하는지 확인
• 충돌 없으면 [코드 외 지식] 태그 부착
• 충돌 있으면 사용자에게 확인 질문

3단계: 재질문 (필요 시)

너무 추상적인 경우:

입력: "배포가 좀 복잡해"
질문: 구체적으로 어떤 부분이 복잡한가요?
- 빌드 순서? CI 설정? 서버 다운타임? 환경별 차이?

모호한 범위:

입력: "코드 리뷰가 엄격해"
질문: 어떤 기준으로 엄격한가요?
- 정적 분석 워닝 0개? 컨벤션 일관성? 도메인 로직 검증? 전부?

충돌 발견:

입력: "기존 ORM 대신 다른 라이브러리 쓰기로 했대"
질문: 기존 문서 (CLAUDE.md) 에는 "{현재 기술} 표준" 으로 되어있는데, 정책이 변경된 건가요?
- 전체 변경? 특정 모듈만? 신규 개발만?

재질문은 최대 3개, 가장 중요한 것부터.

4단계: 구체화 및 문서 반영 판단

검증된 지식을 구체적 문장으로 정리한 뒤, 어떤 문서에 반영해야 하는지 판단:

지식 분류	반영 대상 문서
코딩 규칙과 컨벤션	CLAUDE.md
상태 전이와 비즈니스 규칙	.local.claude/biz-rules.md
아키텍처와 모듈 관계	bot/*.md 또는 .local.claude/ONBOARDING.md 또는 modules/{name}.md
인프라, 배포, 서버	.local.claude/INFRASTRUCTURE.md
고객사 정보	.local.claude/customers/{고객사}.md
프로세스와 업무 흐름	해당 없으면 이력 파일에만 저장
도구와 설정	CLAUDE.md 또는 .local.claude/pmd/README.md 등
대화 간 지속 필요 (사용자 프로필, 프로젝트 상태 변경)	auto memory 저장 안내

메모리 연동: 지식 중 "사용자의 역할/전문성 변화", "프로젝트 상태 변경", "팀 구조 변경" 등 대화를 넘어 지속되어야 하는 정보는 auto memory에 저장할 것을 안내한다.

반영 전 확인:

• 해당 문서에 이미 같은 내용이 있는지 확인 (중복 방지)
• 기존 내용과 충돌하면 어떤 것이 맞는지 사용자에게 확인
• CLAUDE.md는 150줄 이하 유지 (현재 줄 수 체크)

[메타인지] 문서 반영 결정 직전, 반영 대상 문서별 판정에 대해:

1. 근거 재점검 (팩트체크 판정 [OK]/[FAIL]/[WARN] 이 실제 코드나 문서 인용에서 도출되는가 vs 추측인가)
2. 전제 검증 (해당 문서에 이미 같은 내용이 다른 표현으로 있지 않은가, 150줄 상한과 중복 방지가 적용됐는가)
3. 반대 증거 ("이 지식이 왜 지금까지 문서에 없었나? 프로젝트 특수 상황이라 잘못 일반화되는 것 아닌가?")

5단계: 적용 및 이력 저장

문서 반영:

• 사용자에게 변경 내용을 보여주고 승인 받은 후 적용
• 변경된 문서와 변경 내용을 이력에 기록

이력 파일 저장:

• 경로: .local.claude/learn/YYYY-MM-DD.md
• 하루에 여러 번 /learn 실행 시 같은 파일에 누적
• 디렉터리 없으면 mkdir -p

출력 구조

## 지식 캡처: [주제 요약]

### 입력
> [사용자가 말한 원문]

### 팩트체크
| 주장 | 판정 | 근거 |
|------|------|------|
| ... | `[OK]` / `[FAIL]` / `[WARN]` / `[미정]` | 코드/문서에서 확인한 근거 |

### 구체화된 지식
[검증 후 정리된 정확한 문장]

### 문서 반영
| 대상 문서 | 변경 내용 | 상태 |
|----------|----------|------|
| CLAUDE.md | "금지 사항"에 XX 추가 | `[OK]` 반영 완료 |
| biz-rules.md | 상태 전이 규칙 XX 추가 | `[OK]` 반영 완료 |
| (없음) | 이력에만 기록 | 없음 |

### 추가 확인 필요
- [확인 필요] 항목 (있으면)

이력 파일 구조

# 지식 캡처 이력: YYYY-MM-DD

## 1. [시간] [주제]
- **입력**: ...
- **판정**: `[OK]` / `[FAIL]` / `[WARN]`
- **구체화**: ...
- **반영**: [문서명] 또는 "이력만"
- **분류**: 코딩 규칙 / 인프라 / 비즈니스 규칙 / ...

## 2. [시간] [주제]
...

파일 저장

Frontmatter (CONTRACT 7-2절 표준): category: learn, retention: 30d, harvest_targets: [modules/*.md]

저장 경로

• .local.claude/learn/YYYY-MM-DD.md (하루 한 파일, 누적)
• 디렉터리 없으면 mkdir -p로 생성

저장 시점

• 팩트체크 + 문서 반영 완료 시 자동 저장
• 저장 후 파일 경로 안내

다음 스킬 연결

• 비즈니스 규칙이면 /biz-rules로 더 상세히 기록
• 고객사 정보면 /customer-profile
• 코드 리뷰에서 발견한 것이면 /review
• 온보딩 회의에서 배운 것이면 /meeting-notes

제약조건

• 검증 안 된 지식은 문서에 반영하지 않는다. 코드에서 확인 가능한 것은 반드시 확인.
• 코드 검증 불가능한 지식(프로세스, 조직, 구두 전달)은 [코드 외 지식] 태그를 붙여 이력에 기록.
• /learn과 /daily의 구분: /learn은 알게 된 그 순간에 즉시 검증+반영. /daily는 하루 끝 회고에서 "배운 것" 요약 정리. /daily에서는 "오늘 /learn으로 N건 캡처" 식으로 연동.
• 기존 문서와 충돌하면 반드시 사용자에게 확인 후 반영. 임의로 덮어쓰지 않음.
• CLAUDE.md 반영 시 150줄 상한 체크. 초과 위험 시 다른 문서로 분리 제안.
• 너무 추상적인 입력은 재질문으로 구체화. 최대 3개 질문, 핵심부터.
• 이력 파일은 삭제하지 않는다. 축적하여 나중에 검색 가능하게.

다른 스킬과의 경계

질문	담당	이 스킬에서
검증 없이 지나가는 메모를 즉시 적기	/memo	[다루지 않음] (메모 누적 후 승격 대상)
하루 끝 회고에서 "배운 것" 요약	/daily	[다루지 않음] (그 순간 즉시 검증하고 반영)
외부 디렉터리 문서를 일괄 흡수	/absorb	[다루지 않음] (단건 claim 검증)
알게 된 사실을 검증하고 구체화하여 공식 문서에 반영	이 스킬	[핵심]

검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.

이 스킬의 고유 실패 시나리오

[데이터 결함] 코드 검증 실패(주장과 코드 불일치)

• 신호: 학습 대상 내용이 현재 코드베이스와 대조했을 때 사실과 다름(함수명, 동작, 의존성 상이)
• 대응: [코드 외 지식] 태그 부착 후 저장. "이 지식은 현재 코드와 불일치, 개념이나 외부 원리로만 보관"

[사용자 개입 필요] 기존 문서 중복 발견

• 신호: 이미 비슷한 주제의 learn 문서 존재(제목과 키워드 80%+ 일치)
• 대응: 통합 vs 별도 저장 질문: "기존 문서 X에 추가 / 새 문서 생성 / 기존 문서 업데이트"