작동 원리 심층 (Under the Hood): OpenWiki는 어떻게 움직이는가
OpenWiki는 겉보기에는 단순한 CLI 도구 같지만, 내부적으로는 코드 분석, LLM 요약, 파일 시스템 조작, Git 버전 관리 연동이 정교하게 맞물려 돌아가는 파이프라인을 가지고 있습니다.
1. 전체 아키텍처와 데이터 파이프라인
OpenWiki의 데이터 흐름은 원본 소스코드에서 시작하여 AI 최적화 마크다운 파일로 끝납니다. 이 과정을 시각화하면 다음과 같습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
flowchart LR
A["원본 소스코드
(TypeScript/Python 등)"] --> B["AST 파싱 및
파일 구조 추출"]
B --> C["LLM 요약 및
의미론적 연결 구성"]
C --> D["AI 에이전트용
마크다운 위키 저장"]
D --> E["AGENTS.md에
위키 참조 링크 갱신"]
이 파이프라인을 관장하는 핵심 컴포넌트들의 클래스 구조는 어떻게 되어 있을까요?
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
classDiagram
class CLI_Core {
+init_workspace()
+update_wiki()
}
class Git_Analyzer {
+get_latest_diffs()
+find_changed_files()
}
class LLM_Synthesizer {
+generate_markdown_summary()
+map_dependencies()
}
class File_System_Manager {
+write_wiki_pages()
+update_instruction_file()
}
CLI_Core --> Git_Analyzer : "변경 사항 추적"
CLI_Core --> LLM_Synthesizer : "요약 생성 요청"
CLI_Core --> File_System_Manager : "파일 입출력 처리"
OpenWiki 코어 모듈이 실행되면, 가장 먼저 Git_Analyzer가 저장소의 상태를 파악합니다. 이후 LLM_Synthesizer를 호출해 변경되거나 새로 생성된 코드의 맥락을 LLM(OpenAI, Anthropic 등)에게 물어보고 요약문을 받아냅니다. 최종적으로 File_System_Manager가 openwiki/ 디렉토리에 마크다운 파일을 기록합니다.
2. 생성되는 위키의 데이터 모델
OpenWiki가 생성하는 데이터 구조는 인간이 읽기 위한 것이 아니라 AI가 구조를 맵핑하기 좋도록 설계되어 있습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
erDiagram
REPOSITORY {
string repo_name
string root_path
}
WIKI_DOCUMENT {
string file_name
string target_module
string summary_content
}
INSTRUCTION_FILE {
string file_type
string entry_prompt
}
REPOSITORY ||--o{ WIKI_DOCUMENT : "위키 디렉토리 소유"
REPOSITORY ||--o| INSTRUCTION_FILE : "루트 지시문 포함"
INSTRUCTION_FILE ||--o{ WIKI_DOCUMENT : "참조 링크 제공"
위키 문서는 모듈별, 도메인별로 쪼개져 저장됩니다. 각 마크다운 파일 내부에는 명확한 헤딩(Heading)과 핵심 로직에 대한 요약, 그리고 연관된 다른 위키 파일로의 텍스트 링크가 포함되어 있어 AI가 꼬리를 물고 정보를 탐색할 수 있습니다.
3. AI 에이전트의 문서 조회 흐름 (Sequence)
실제로 에이전트(예: Cursor)가 개발자의 명령을 받았을 때 OpenWiki가 만들어둔 구조를 어떻게 활용하는지 상호작용 흐름을 살펴보겠습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
sequenceDiagram
participant DEV as "개발자"
participant AGENT as "AI 코딩 에이전트"
participant CMD as "루트 지시문(AGENTS.md)"
participant WIKI as "openwiki/ 디렉토리"
DEV->>AGENT: "인증 모듈에 OAuth2 로그인을 추가해줘"
AGENT->>CMD: "프로젝트 규칙 및 컨텍스트 읽기"
CMD-->>AGENT: "인증 관련 구조는 openwiki/auth.md를 참조하라"
AGENT->>WIKI: "auth.md 파일 내용 조회"
WIKI-->>AGENT: "현재 인증 아키텍처 요약 및 의존성 반환"
AGENT->>DEV: "정확한 컨텍스트를 기반으로 코드 작성 완료"
에이전트는 무거운 전체 코드를 읽는 대신, 루트 지시문이 안내하는 가벼운 마크다운 파일 하나만 읽고도 현재 인증 시스템이 어떤 라이브러리를 쓰고 어떤 폴더 구조를 가지는지 완벽히 파악합니다.
4. 지속적 동기화: Git Diff 기반 업데이트
가장 중요한 것은 이 위키가 어떻게 항상 최신 상태를 유지하느냐입니다. OpenWiki는 전체 코드를 매번 다시 요약하지 않습니다. 그것은 너무 느리고 비용이 많이 듭니다. 대신 git diff를 활용해 점진적(Incremental) 업데이트를 수행합니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
stateDiagram-v2
[*] --> 대기_상태
대기_상태 --> 커밋_발생 : "새로운 코드 푸시"
커밋_발생 --> Diff_분석 : "이전 위키 갱신 시점과 비교"
Diff_분석 --> LLM_해석 : "변경 내역의 의미론적 분석"
LLM_해석 --> 마크다운_수정 : "위키 파일 부분 업데이트"
마크다운_수정 --> PR_생성 : "GitHub Action을 통한 자동 PR"
PR_생성 --> [*]
스케줄러나 Git Hook에 의해 이벤트가 발생하면, OpenWiki는 이전 실행 이후 추가된 커밋들을 확인합니다. 변경된 파일 목록을 추출하고, 그 변경이 전체 구조에 어떤 의미를 가지는지 LLM에게 묻습니다. “A 파일에서 함수 이름이 바뀌었으니, 이 함수를 설명하던 위키 B 문서의 내용도 이렇게 수정하라”는 지시를 받아 위키를 패치(Patch)하는 것입니다.
