claude-reflect

Version

License: MIT

Tests

Platform

Claude Code를 위한 자체 학습 시스템으로, 수정 사항을 포착하고 워크플로우 패턴을 발견하여 이를 영구적인 메모리와 재사용 가능한 기술로 변환합니다.

실행하는 두 가지 방법:

	플러그인 (Plugin) (Python)	모드 (Mod) (reflect-mod, 3.3 버전에서 새로 추가됨)
Claude를 수정할 때	후크(hook)가 이를 대기열에 넣습니다	모델 체크(model check)가 어떤 언어에서든 즉시 확인합니다
...
reflect-mod: a correction becomes a rule you can save with one press

둘 중 하나를 선택하세요. 플러그인 설치 또는 모드로 claude-reflect 설치.

기능 (What it does)

1. 수정 사항으로부터 학습하기 (Learn from Corrections)

Claude를 수정할 때(

설치 후, Claude Code를 재시작하세요 (종료했다가 다시 엽니다). 그러면 hooks가 자동 구성되고 명령어가 준비됩니다.

처음 실행하는 경우? /reflect를 처음 실행하면, 학습을 위해 이전 세션을 스캔하라는 메시지가 표시됩니다.

필수 조건

• Claude Code CLI 설치
• Python 3.6 이상 (대부분의 시스템에 포함)

플랫폼 지원

• macOS: 완벽하게 지원됨
• Linux: 완벽하게 지원됨
• Windows: 완벽하게 지원됨 (네이티브 Python, WSL 불필요)

새로 추가: mod로서의 claude-reflect (얼리 액세스)

Claude Code mods는 세션 내부에서 실행되므로, 검토해야 할 큐가 필요 없는 동일한 아이디어가 작동합니다:

• 모든 짧은 프롬프트 (500자 이하,

Claude Code 2.1.286 이상 버전과 모드(mods) 활성화가 필요합니다. 체크된 프롬프트 각각은 사용자의 Claude 계정에서 발생하는 작은 모델 호출입니다. 위에 있는 모드 또는 Python 플러그인 중 하나만 설치하세요. 둘 다 설치할 경우, 모든 수정 사항이 두 번 기록됩니다. Python 플러그인은 /reflect --scan-history, --dedupe, --organize, /reflect-skills 및 Codex/Cursor 사용자를 위한 선택지로 유지됩니다. 상세 정보: mod/README.md.

명령어 (Commands)

작동 방식 (How It Works)

2단계 프로세스 (Two-Stage Process)

1단계: 캡처 (Capture) (자동)

훅(Hooks)이 자동으로 실행되어 수정 사항을 감지하고 대기열에 추가합니다:

/reflect를 실행하여 대기 중인 학습 내용을 검토하고 CLAUDE.md에 적용합니다.

감지 방법 (Detection Methods)

Claude-reflect는 **하이브리드 감지 접근 방식(hybrid detection approach)**을 사용합니다:

1. 정규 표현식 패턴 (Regex patterns) (실시간 캡처)

세션 중 빠른 패턴 매칭을 통해 다음을 감지합니다:

• 수정 사항 (Corrections): `

/reflect를 실행하면 Claude가 다음과 같은 옵션이 포함된 요약 표를 제시합니다:

• Apply - 학습 내용을 수락하고 CLAUDE.md에 추가합니다.
• Edit before applying - 먼저 학습 텍스트를 수정합니다.
• Skip - 이 학습을 적용하지 않습니다.

다중 타겟 동기화 (Multi-Target Sync)

승인된 학습 내용은 다음 위치에 동기화됩니다:

• ~/.claude/CLAUDE.md (전역 - 모든 프로젝트에 적용)
• ./CLAUDE.md (프로젝트별)
• ./**/CLAUDE.md (하위 디렉토리 - 자동 발견)
• ./.claude/commands/*.md (스킬 파일 - 수정 사항이 스킬과 관련될 때)
• AGENTS.md (존재하는 경우 - Codex, Cursor, Aider, Jules, Zed, Factory와 함께 작동)
• @filename 포함 또는 마크다운 링크를 통해 위에서 도달 가능한 문서(제한된 깊이, 순환 처리됨, 코드 블록/외부 URL 건너뜀) — CLAUDE.md가 standards.md, architecture.md 등에 지침을 위임할 때 유용합니다.

어떤 파일들이 업데이트될지 확인하려면 /reflect --targets를 실행하세요.

스킬 발견 (Skill Discovery)

/reflect-skills를 실행하여 세션에서 재사용 가능한 스킬이 될 수 있는 반복 패턴을 발견할 수 있습니다:

/reflect-skills                 # 현재 프로젝트 분석 (최근 14일)
/reflect-skills --days 30       # 최근 30일 분석
/reflect-skills --all-projects  # 모든 프로젝트 분석 (느림)
...

특징:

• AI 기반 감지(AI-powered detection) — 정규 표현식(regex)이 아닌 추론을 사용하여 패턴을 찾습니다.
• 의미적 유사성(Semantic similarity) — 다른 구문에서 동일한 의도를 감지합니다.
• 프로젝트 인식(Project-aware) — 프로젝트별로 패턴을 그룹화하고 올바른 위치를 제안합니다.
• 스마트 할당(Smart assignment) — 각 스킬이 어디에 속해야 하는지 (프로젝트 대 전역) 질문합니다.
• 스킬 파일 생성 — .claude/commands/에 초안 스킬을 만듭니다.

작동 방식:

이 스킬은 세션 기록을 의미적으로 분석하여 패턴을 발견합니다. 동일한 의도를 가진 다른 구문들이 인식됩니다:

Session 1:

Claude의 추론:
"이 4개의 요청은 동일한 의도를 가집니다. 생산성 데이터를 검토하는 것입니다. 워크플로우는 다음과 같습니다: 시간 추적 데이터 가져오기 → 활동 분류하기 → 집중 점수 계산하기. 이는 /daily-review에 대한 강력한 후보입니다." 

**예시 출력:**

════════════════════════════════════════════════════════════
SKILL CANDIDATES DISCOVERED
════════════════════════════════════════════════════════════
...

**생성된 스킬 파일 예시:**

```markdown
---
description: 사전 검사(pre-flight checks)를 거쳐 애플리케이션 배포
allowed-tools: Bash, Read, Write
...

스킬 개선 라우팅 (Skill Improvement Routing)

스킬을 사용하면서 Claude를 수정할 때(예: /deploy), 그 수정 사항은 스킬 파일 자체로 다시 전송될 수 있습니다:

User: /deploy
Claude: [테스트 실행 없이 배포]
User: "아니요, 배포하기 전에 항상 테스트를 실행하세요"
...

이러한 방식으로 스킬은 시간의 흐름에 따라 CLAUDE.md뿐만 아니라 더 똑똑해집니다.

업그레이드 (Upgrading)

v2.0.x 이전 버전에서

업데이트 후 "Duplicate hooks file detected" 또는 "No such file or directory"와 같은 오류가 보이면 플러그인 캐시를 지워야 합니다. 이는 알려진 Claude Code의 캐싱 문제 때문입니다:

• #14061 - /plugin update 명령어가 캐시를 무효화하지 않음
• #15369 - 제거(Uninstall)가 캐시된 파일을 지우지 않음

# 1. 플러그인 제거
claude plugin uninstall claude-reflect@claude-reflect-marketplace

...

표준 업데이트 (Standard Update)

일반적인 업데이트(캐시 문제가 없을 때):

# Claude Code에서 /plugin 메뉴 사용
/plugin
# claude-reflect에 대해 "Update now" 선택

제거 (Uninstall)

claude plugin uninstall claude-reflect@claude-reflect-marketplace

파일 구조 (File Structure)

claude-reflect/
├── .claude-plugin/
│   └── plugin.json         # 플러그인 매니페스트 (hooks 자동 등록)
...

기능 (Features)

히스토리 스캔 (Historical Scan)

claude-reflect를 처음 사용하는 경우 다음을 실행하세요:

/reflect --scan-history

이 기능은 사용자가 이전에 수행했던 모든 세션을 스캔하여, 설치 전까지 얻었던 학습 내용을 잃지 않도록 수정 사항을 기록합니다.

스마트 필터링 (Smart Filtering)

Claude가 걸러내는 항목:

• 질문 (수정 사항 아님)
• 일회성 작업 지침
• 컨텍스트 특정 요청
• 모호하거나 실행 불가능한 피드백

재사용 가능한 학습 내용만 보존됩니다.

중복 감지 (Duplicate Detection)

학습 내용을 추가하기 전에 기존의 CLAUDE.md 파일 내용을 확인합니다. 유사한 내용이 존재할 경우 다음 중 하나를 선택할 수 있습니다:

• 기존 항목과 병합(Merge)하기
• 이전 항목으로 대체(Replace)하기
• 중복 건 건너뛰기(Skip)

의미적 중복 제거 (Semantic Deduplication)

시간이 지남에 따라 CLAUDE.md에는 유사한 항목들이 쌓일 수 있습니다. /reflect --dedupe를 실행하여 다음을 수행할 수 있습니다:

• 의미적으로 유사한 항목 찾기 (다른 단어를 사용했더라도)
• 통합된 버전 제안하기
• 중복 학습 내용 정리하기

예시:

Before:
  - 복잡한 작업을 위해서는 gpt-5.1을 사용하세요
  - 추론에는 gpt-5.1을 선호하세요
...

팁 (Tips)

1. 중요 학습 내용에 명시적 마커 사용하기:
   복사

remember: Python 프로젝트의 경우 항상 venv를 사용하세요

2. **git 커밋 후 /reflect 실행하기** - 이 기능이 상기시켜 주지만, 습관으로 만드세요.

3. **새 기계에서 히스토리 스캔하기** - 새로운 개발 환경을 설정할 때:

/reflect --scan-history --days 90

4. **프로젝트 vs 전역 (Project vs Global)** - 모델 이름과 일반적인 패턴은 전역(global)으로, 프로젝트별 규칙은 해당 프로젝트의 CLAUDE.md에 유지합니다.

5. **월간 스킬 발견하기** - 놓쳤을 수 있는 자동화 기회를 찾기 위해 매달 `/reflect-skills --days 30`를 실행하세요.

6. **스킬 지능화되기 (Skills get smarter)** - 스킬 과정에서 Claude를 수정하면, 그 수정 내용이 `/reflect`를 통해 해당 스킬 파일 자체로 전달될 수 있습니다.

7. **세션 보존 기간 연장하기** - Claude Code는 기본적으로 30일 후 로컬 세션을 삭제합니다. claude-reflect가 `/reflect --scan-history` 및 `/reflect-skills`에 세션 기록을 의존하므로, `~/.claude/settings.json`에서 이를 연장하세요:
```json
{ "cleanupPeriodDays": 99999 }

기여 (Contributing)

풀 리퀘스트(Pull requests) 환영합니다! 먼저 기여 가이드라인을 읽어주세요.

라이선스 (License)

MIT