참고: 이 도구의 아주 초기 버전입니다. 토론 형식이나 GitHub에 이슈를 생성하여 피드백을 주신다면 매우 감사하겠습니다. 감사합니다!

🚀 MCP Server 사용 가능: NPM에서 AI Distiller를 위한 Model Context Protocol (MCP) 서버를 설치하세요: @janreges/ai-distiller-mcp

• Claude, Cursor 및 기타 MCP 호환 AI 도구와 원활하게 통합됩니다!

🤔 왜 AI Distiller인가요?

수천 개의 파일과 함수가 포함된 대규모 프로젝트에서 작업하시나요? Claude Code, Gemini, Copilot 또는 Cursor와 같은 AI 도구들이 빈번하게 "환각 (hallucinating)" 현상을 일으켜, 언뜻 보기에는 올바르지만 실제로는 프로젝트와 호환되지 않는 코드를 생성하여 어려움을 겪고 계신가요?

문제는 컨텍스트 (context)입니다. AI 모델은 제한된 컨텍스트 윈도우 (context window)를 가지고 있어 전체 코드베이스를 이해할 수 없습니다. 대신, AI 에이전트(AI agents)는 파일을 검색하고, 키워드를 "grep"하며, 찾은 용어의 앞뒤 몇 줄을 살펴보고, 클래스와 함수의 인터페이스를 (항상 그렇지는 않지만) 추측하려고 시도합니다. 그 결과는 무엇일까요? 매개변수를 추측하고, 잘못된 데이터 타입을 반환하며, 기존 아키텍처를 무시하는 오류투성이의 코드입니다. 만약 당신이 AI 에이전트의 숙련된 사용자 (vibe coder)라면, AI 에이전트에게 지속적으로 테스트를 작성하고 실행하도록 지시하거나, 정적 코드 분석 (static code analysis), 프리 커밋 훅 (pre-commit hooks) 등을 사용하도록 명령함으로써 스스로를 도울 수 있다는 것을 알고 있을 것입니다. 그러면 AI 에이전트가 대개 코드를 스스로 수정하겠지만, 그 과정에서 20단계의 과정과 5분의 시간이 소요될 것입니다. 반면에, 각 AI 요청에 대해 비용을 지불하고 있고 (대규모 컨텍스트는 비용이 많이 드는 요소입니다)

AI Distiller (또는 짧게 aid)는 이 문제를 해결하는 데 도움을 줍니다. 주요 기능은 코드 "증류 (distillation)"입니다. 이는 AI가 첫 시도에 코드를 정확하게 작성하는 데 필요한 가장 필수적인 정보만을 전체 프로젝트(이상적으로는 메인 소스 폴더, 또는 매우 큰 프로젝트의 경우 특정 모듈 하위 디렉토리)에서 추출하는 과정입니다. 이 증류 과정은 보통 원본 소스 코드 볼륨의 5~20%에 불과한 컨텍스트 (context)를 생성하여, AI 도구들이 이를 컨텍스트에 포함할 수 있게 합니다. 결과적으로 AI는 시행착오를 거치는 대신, 기존 코드를 설계된 그대로 사용하게 됩니다.

매우 간단히 말하자면, aid는

증류 과정 내에서 인터페이스의 공개 (public) 부분, 입력 및 출력 데이터 타입만을 남기고, 기본 상태에서는 메서드 구현 (method implementations) 및 비공개 (non-public) 구조를 폐기합니다. 하지만 모든 것은 CLI 옵션 (CLI Options)을 통해 설정 가능합니다.

• 🤔 왜 AI Distiller인가?
• ✨ 주요 기능 (Key Features)
• 🎯 작동 원리 (How It Works)
• 🔗 의존성 인식 증류 (Dependency-Aware Distillation)
• 🚀 빠른 시작 (Quick Start)
• 📖 출력 예시 (Example Output)
• 📖 가이드 및 예제 (Guides & Examples)
• 📖 전체 CLI 레퍼런스 (Complete CLI Reference)
• 🛠️ 고급 사용법 (Advanced Usage)
  ⚠️ 한계점 (Limitations)
• 🔒 보안 고려 사항 (Security Considerations)
• ❓ 자주 묻는 질문 (FAQ)
• 🤝 기여하기 (Contributing)
• 📄 라이선스 (License)
• 🙏 감사 인사 (Acknowledgments)

새로운 세밀한 플래그 (flag) 시스템을 통해 포함할 내용을 정확하게 제어하세요:

가시성 제어 (Visibility Control):

--public=1

(기본값) - 공개 멤버 (public members) 포함
--protected=0

(기본값) - 보호된 멤버 (protected members) 제외
--internal=0

(기본값) - 내부/패키지 프라이빗 (internal/package-private) 제외
--private=0

(기본값) - 비공개 멤버 (private members) 제외

콘텐츠 제어 (Content Control):

--comments=0

(기본값) - 주석 (comments) 제외
--docstrings=1

(기본값) - 문서화 (documentation) 포함
--implementation=0

(기본값) - 함수/메서드 본문 (function/methods bodies) 제외
--imports=1

(기본값) - 임포트/사용 문 (import/use statements) 포함

기본 동작: 기본적인 문서화와 함께 공개 API 시그니처(public API signatures)만 표시합니다. 이는 최대 압축률을 유지하면서도 AI가 이해하기에 완벽한 방식입니다.

AI Distiller는 AI 기반 분석을 위해 정제된 코드와 결합된 특화된 프롬프트(prompts)를 생성합니다:

• 체계적인 파일별 분석을 위한 작업 목록 및 프롬프트 생성: --ai-action=flow-for-deep-file-to-file-analysis

• 코드 구조를 포함한 문서화 워크플로우 프롬프트 생성: --ai-action=flow-for-multi-file-docs

파일로 출력

• 프롬프트는 .aid/ 디렉토리에 저장됩니다 (작은 코드베이스의 경우 --stdout 사용 가능)

AI 실행 준비 완료

• 생성된 파일에는 분석 프롬프트와 정제된 코드가 모두 포함됩니다

AI 에이전트 지침

• 출력물에는 AI 에이전트가 생성된 파일을 읽고 처리할 수 있도록 하는 가이드가 포함됩니다

Gemini의 이점

• 1M 토큰 컨텍스트 윈도우(context window)를 통해 대규모 코드베이스 분석에 최적화되어 있습니다

참고: AI Distiller는 직접 분석을 수행하지 않습니다. 대신 AI 에이전트(Claude, Gemini, ChatGPT)가 실행할 수 있도록 최적화된 프롬프트를 준비합니다. 사용자는 AI 에이전트에게 생성된 파일을 처리하도록 명시적으로 요청하거나, 그 내용을 웹 기반 AI 도구로 복사해야 할 수도 있습니다.

Text (--format text) - AI 소비를 위한 초압축 형식 (기본값)
Markdown (--format md) - 깔끔하고 구조화된 마크다운
JSON Structured (--format json-structured) - 도구 활용을 위한 풍부한 의미론적 데이터 (semantic data)
JSONL (--format jsonl) - 스트리밍 형식
XML (--format xml) - 레거시 시스템 호환용

각 정제 작업이 끝나면, AI Distiller는 압축 효율과 처리 속도를 보여주는 요약을 표시합니다:

# Default: 대화형 터미널을 위한 시각적 진행 바 (초록색 점 = 절약됨, 빨간색 점 = 남음)
✨ Distilled 970 files [░░░░░░░░░░░░░░░] 98% (10M → 256K) in 231ms 💰 ~2.4M tokens saved (~64k remaining)
# --summary-type 옵션으로 원하는 형식을 선택하세요
...

사용 가능한 형식:

visual-progress-bar (기본값) - 압축 과정을 진행 바(progress bar)로 표시
stock-ticker - 컴팩트한 주식 시장 스타일 디스플레이
speedometer-dashboard

• 지표가 포함된 다중 행 대시보드 minimalist-sparkline

• 모든 필수 정보가 포함된 단일 행 ci-friendly

• CI/CD 파이프라인을 위한 깔끔한 형식 json

• 기계 판독이 가능한 JSON 출력 off

• 요약 출력 비활성화

모든 형식에서 이모지를 제거하려면 --no-emoji를 사용하세요.

AI Distiller는 프로젝트 루트(project root)를 자동으로 감지하고 모든 출력을 .aid/ 디렉토리에 중앙 집중화합니다:

자동 감지 (Automatic detection): .aidrc, go.mod, package.json, .git 등을 상위 디렉토리로 검색합니다.
일관된 위치 (Consistent location): aid를 어디에서 실행하든 모든 출력은 <project-root>/.aid/로 이동합니다.
캐시 관리 (Cache management): 더 나은 조직화를 위해 MCP 캐시는 .aid/cache/에 저장됩니다.
간편한 정리 (Easy cleanup): 출력이 버전 관리(version control)에 포함되지 않도록 .gitignore에 .aid/를 추가하세요.

감지 우선순위 (Detection priority):

• .aidrc 파일: 프로젝트 루트를 명시적으로 표시하기 위해 이 빈 파일을 생성하세요.
• 언어 마커 (Language markers): go.mod, package.json, pyproject.toml 등
• 버전 관리 (Version control): .git 디렉토리
• 환경 변수 (Environment variable): AID_PROJECT_ROOT (마커를 찾을 수 없는 경우의 대체 수단)
• 현재 디렉토리 (Current directory): 경고와 함께 제공되는 최종 대체 수단

# 특정 디렉토리를 프로젝트 루트로 표시 (권장)
touch /my/project/.aidrc
# 프로젝트 내 어디에서든 실행 - 출력은 항상 프로젝트 루트로 이동합니다
...

현재 tree-sitter를 통해 12개의 언어를 지원합니다:

전체 지원 (Full Support): Python, Go, JavaScript, PHP, Ruby
베타 (Beta): TypeScript, Java, C#, Rust, Kotlin, Swift, C++
출시 예정 (Coming Soon): Zig, Scala, Clojure

• C++ - 템플릿 (templates), 네임스페이스 (namespaces), 최신 기능 (modern features)을 포함한 C++11/14/17/20 지원
• C# - 레코드 (records), Nullable 참조 형식 (nullable reference types), 패턴 매칭 (pattern matching)을 포함한 완전한 C# 12 지원
• Go - 인터페이스 (interfaces), 고루틴 (goroutines), 제네릭 (generics, 1.18+)을 포함한 완전한 Go 지원
• Java - 레코드 (records), 봉인된 클래스 (sealed classes), 패턴 매칭 (pattern matching)을 포함한 Java 8-21 지원
• JavaScript - 클래스 (classes), 모듈 (modules), async/await를 포함한 ES6+ 지원
• Kotlin - 코루틴 (coroutines), 데이터 클래스 (data classes), 봉인된 클래스 (sealed classes)를 포함한 Kotlin 1.x 지원
• PHP - PHP 8.x 기능 (attributes, union types, enums)을 포함한 PHP 7.4+ 지원
• Python - 타입 힌트 (type hints), async/await, 데코레이터 (decorators)를 포함한 완전한 Python 3.x 지원
• Ruby - 블록 (blocks), 모듈 (modules), 메타프로그래밍 (metaprogramming)을 포함한 Ruby 2.x/3.x 지원
• Rust - 트레이트 (traits), 수명 (lifetimes), async를 포함한 Rust 2018/2021 에디션 지원
• Swift - 프로토콜 (protocols), 확장 (extensions), 프로퍼티 래퍼 (property wrappers)를 포함한 Swift 5.x 지원
• TypeScript - 제네릭 (generics), 데코레이터 (decorators), 타입 시스템 (type system)을 포함한 TypeScript 4.x/5.x 지원

스캔 (Scans): 지원되는 파일 유형에 대해 코드베이스를 재귀적으로 스캔합니다 (10개 이상의 언어)
파싱 (Parses): 언어별 tree-sitter 파서(모두 포함되어 있으며 의존성 없음)를 사용하여 각 파일을 파싱합니다
추출 (Extracts): 필요한 정보만 추출합니다: 공개 API (public APIs), 타입 시그니처 (type signatures), 클래스 계층 구조 (class hierarchies)
출력 (Outputs): 선호하는 형식으로 출력합니다: 압축된 텍스트, 마크다운 (markdown), 또는 구조화된 JSON

모든 tree-sitter 문법은 aid 바이너리에 컴파일되어 있습니다 - 외부 의존성이 전혀 없습니다!

고급 기능 (Advanced Feature): AI Distiller에는 파일 간의 호출 그래프 (call graphs)를 분석하여 코드베이스에서 실제로 사용되는 코드만 포함하는 의존성 인식 증류 (dependency-aware distillation) 기능이 포함되어 있습니다. 이를 통해 여러 파일에 걸친 함수/메서드 호출을 추적하여 심층적인 코드 분석을 위한 집중된 증류 결과물을 생성합니다.

💡

의존성 분석 (dependency analysis)이 처음이신가요? 이 기능은 코드 내에서 어떤 함수가 실제로 서로를 호출하는지 추적하여, 관련 부분만 포함하는 최소한의 컨텍스트 (context)를 생성합니다. 전체 파일을 처리하지 않고도 코드 관계를 이해해야 하는 AI 도구에 완벽합니다.

전체 파일을 포함하는 대신, 의존성 인식 증류는 다음과 같이 작동합니다:

진입점 식별 (Identifies entry points) (메인 함수, 내보낸 API)
함수 호출 추적 (Traces function calls) (파일 경계를 가로질러 수행)
호출 그래프 구축 (Builds call graphs) (의존성을 이해하기 위해 수행)
사용된 코드만 포함 (Includes only used code)

• 실제로 호출되는 함수들
  사용되지 않는 코드 필터링 (Filters out unused code)
• AI 컨텍스트를 위한 데드 코드 제거 (dead code elimination)

# 기본 의존성 분석 (Basic dependency analysis)
aid main.py --dependency-aware
# 분석 깊이 제어 (Control analysis depth)
...

우리는 의존성 인식 증류 (dependency-aware distillation)가 다양한 프로그래밍 언어에서 가능한 한 신뢰할 수 있도록 광범위하게 작업해 왔습니다. 하지만 언어마다 복잡성이 크게 다르며, 현재 상태에 대해 투명하게 공개하고자 합니다:

범례 (Legend):

• 🟢
  Very Good (매우 좋음): 프로덕션 환경에 적합하며, 복잡한 시나리오를 안정적으로 처리함 - 🟠
  Good (좋음): 사소한 제한 사항이 있으나 견고한 기능 제공 - 🟡
  Limited (제한적): 기본적인 기능만 제공하며, 파싱 (Parsing) 능력이 제한적일 수 있음 - ✅
  Full (전체): 파일 간 의존성 추적 (Cross-file dependency tracing) 완벽 지원 ⚠️ Basic (기본): 단순한 시나리오에서는 잘 작동하나, 복잡한 패턴에서는 제한적일 수 있음 - ❌
  Issues (문제 있음): 기능이 현저히 제한됨

Very Good Performance (매우 우수한 성능) (8개 언어):

Processing Time (처리 시간): 36-41ms로 일관됨
Compression (압축): 65-72% 크기 감소
Scalability (확장성): 최대 10개의 파일까지 효율적으로 처리
Memory Usage (메모리 사용량): 최소 수준이며, 멈춤(Hanging)이나 타임아웃 (Timeout) 문제 없음

Areas for Enhancement (개선 필요 영역):

Large Projects (대규모 프로젝트): 50개 이상의 파일에서는 성능이 제한될 수 있음
Language Processors (언어 프로세서): C#, C++, TypeScript는 근본적인 제한 사항이 있음
Complex Call Patterns (복잡한 호출 패턴): 고급 메타프로그래밍 (Metaprogramming) 패턴은 제한적일 수 있음

Perfect for (다음 용도에 최적):

• 🎯
  Impact Analysis (영향 분석)- 변경 사항에 의해 어떤 코드가 영향을 받는지 이해 - 🔍
  Code Navigation (코드 탐색)- 여러 파일에 걸친 실행 흐름 (Execution flows) 추적 - 🎪
  Focused Context (집중된 컨텍스트)- AI 어시스턴트 (AI assistants)를 위해 관련 코드만 추출 - 📚
  Legacy Understanding (레거시 코드 이해)- 복잡한 코드베이스를 체계적으로 추적 - 🔧
  API Analysis (API 분석)- 어떤 메서드 (Methods)가 단순히 정의되었는지와 실제로 호출되는지를 구분

Best Practices (권장 사항):

# 빠른 개요 파악을 위해 작은 깊이(depth)로 시작
aid main.py --dependency-aware --max-depth=1
# 종합적인 분석을 위해 깊이 증가
...

문제점: 현대의 코드베이스 (Codebases)는 수백만 줄의 코드가 포함된 수천 개의 파일을 포함하고 있습니다. 하지만 AI가 코드 아키텍처 (Architecture)를 이해하고, 개선 사항을 제안하거나 개발을 돕기 위해서는 모든 구현 세부 사항을 볼 필요가 없습니다. AI에게 필요한 것은 구조와 공개 인터페이스 (Public interfaces)입니다.