Claude Code 기반 지식 관리 에이전트 개발 가이드
개요
Claude Code를 활용하여 문서와 웹 콘텐츠를 자동으로 수집, 분석, 저장하고 재가공하는 지식 관리 에이전트를 구축하는 방법을 소개합니다. 이 시스템은 다양한 형식의 입력 소스를 처리하여 Obsidian, Notion 등의 지식 관리 도구에 자동으로 저장하고, 이를 다시 새로운 콘텐츠로 변환하는 완전 자동화된 워크플로우를 제공합니다.
시스템 아키텍처
전체 시스템은 크게 세 가지 계층으로 구성됩니다. 첫 번째는 입력 계층으로, 여기서는 DOCX 문서, PDF 논문, 웹사이트 등 다양한 형식의 데이터 소스를 받아들입니다. 두 번째는 처리 계층으로, Claude Code와 커스텀 스킬들이 협력하여 콘텐츠를 분석하고 구조화합니다. 세 번째는 출력 계층으로, 처리된 데이터를 Obsidian이나 Notion 같은 플랫폼에 저장하고 필요에 따라 새로운 형식의 콘텐츠로 재생성합니다.
핵심 구성 요소
1. 입력 소스 처리 시스템
시스템이 다루는 입력 소스는 크게 두 가지 유형으로 나뉩니다. 첫 번째는 로컬 파일로, DOCX 문서와 PDF 논문 파일이 여기에 해당합니다. 이러한 파일들은 직접 경로를 지정하여 Claude Code에 전달할 수 있습니다. Claude의 네이티브 문서 처리 능력을 활용하면 DOCX 파일은 바로 읽을 수 있고, PDF의 경우 텍스트 추출 기능을 통해 내용을 파싱할 수 있습니다.
두 번째는 웹 기반 소스입니다. 일반적인 웹사이트의 경우 Claude의 기본 web_fetch 도구를 사용하여 내용을 가져올 수 있습니다. 하지만 JavaScript로 동적으로 렌더링되는 페이지나 특수한 인증이 필요한 사이트의 경우, Playwright MCP 서버를 활용합니다. Playwright는 실제 브라우저를 자동화하여 페이지를 완전히 렌더링한 후 콘텐츠를 추출할 수 있기 때문에, Claude가 기본적으로 접근하기 어려운 사이트도 처리할 수 있습니다.
2. MCP 서버 설정
Playwright MCP 서버를 설정하려면 먼저 Node.js 환경에서 필요한 패키지를 설치해야 합니다. @modelcontextprotocol/server-playwright 패키지와 playwright 자체를 설치한 후, MCP 설정 파일에 서버를 등록합니다. 이 서버는 웹페이지 탐색, 스크린샷 캡처, 폼 작성, 버튼 클릭 등 브라우저에서 할 수 있는 거의 모든 작업을 자동화할 수 있습니다.
설정 파일에는 서버의 실행 명령과 환경 변수를 지정합니다. Headless 모드로 실행할지, 어떤 브라우저를 사용할지 등의 옵션을 설정할 수 있습니다. 중요한 점은 Claude Code의 CLAUDE.md 파일에서 이 MCP 도구를 언제 사용해야 하는지 명확히 지시해야 한다는 것입니다.
3. 커스텀 스킬 개발
지식 관리 에이전트의 핵심은 콘텐츠를 “꼼꼼하게” 읽고 분석하는 커스텀 스킬들입니다. 이러한 스킬들은 각각 특정한 역할을 수행하도록 설계됩니다.
문서 분석 스킬은 입력된 콘텐츠의 구조를 파악하고 주요 개념을 추출합니다. 예를 들어, 학술 논문의 경우 초록, 서론, 방법론, 결과, 결론을 구분하고, 각 섹션에서 핵심 주장과 데이터를 식별합니다. 기술 문서라면 API 명세, 코드 예제, 설정 방법 등을 구조화합니다.
메타데이터 추출 스킬은 저자, 날짜, 태그, 카테고리 등 문서의 메타 정보를 자동으로 생성합니다. 이는 나중에 검색과 분류를 용이하게 만듭니다. 특히 Obsidian의 YAML 프론트매터나 Notion의 데이터베이스 속성으로 변환하기에 적합한 형식으로 메타데이터를 구성합니다.
요약 및 하이라이트 스킬은 긴 문서에서 핵심 내용만을 추출합니다. 단순한 텍스트 요약이 아니라, 사용자가 나중에 참조할 때 가장 중요한 인사이트를 빠르게 파악할 수 있도록 구조화된 요약을 생성합니다.
4. 저장소 통합
처리된 데이터를 실제 지식 관리 도구에 저장하는 부분이 매우 중요합니다. Obsidian과 Notion은 서로 다른 접근 방식을 필요로 합니다.
Obsidian의 경우, 마크다운 파일 시스템을 기반으로 하므로 비교적 직관적입니다. Claude Code는 지정된 Vault 경로에 직접 마크다운 파일을 생성할 수 있습니다. 파일명은 문서 제목이나 고유 ID를 기반으로 생성하고, YAML 프론트매터에 메타데이터를 포함시킵니다. 내부 링크는 [[파일명]] 형식을 사용하고, 태그는 #태그명 형식으로 추가합니다. 이미지나 첨부 파일이 있다면 별도의 attachments 폴더에 저장하고 적절히 링크를 연결합니다.
Notion의 경우 API를 통한 접근이 필요합니다. Notion MCP 서버를 설정하거나, 직접 Notion API를 호출하는 스크립트를 작성할 수 있습니다. 먼저 저장할 데이터베이스의 ID를 확인하고, 해당 데이터베이스의 스키마(속성 구조)를 파악해야 합니다. 그런 다음 API 요청을 통해 새로운 페이지를 생성하고 블록 콘텐츠를 추가합니다. Notion의 블록 구조는 마크다운보다 복잡하므로, 파싱한 콘텐츠를 적절한 블록 타입(heading, paragraph, code, image 등)으로 변환하는 로직이 필요합니다.
워크플로우 자동화
기본 프로세스
전체 워크플로우는 다음과 같은 단계로 진행됩니다. 사용자가 파일 경로나 URL을 제공하면, Claude Code는 먼저 입력 타입을 판별합니다. DOCX나 PDF라면 해당 파일을 읽어들이고, URL이라면 web_fetch나 Playwright를 사용하여 콘텐츠를 가져옵니다.
다음 단계에서는 사전에 정의된 스킬들이 순차적으로 또는 병렬적으로 실행됩니다. 문서 분석 스킬이 먼저 콘텐츠를 파싱하고 구조화하면, 메타데이터 추출 스킬이 필요한 속성들을 생성합니다. 요약 스킬이 핵심 내용을 추출하고, 필요하다면 번역 스킬이 다국어 콘텐츠를 처리합니다.
모든 처리가 완료되면, 사용자가 선택한 옵션에 따라 적절한 저장소에 데이터를 저장합니다. Obsidian이라면 마크다운 파일을 생성하고, Notion이라면 API를 통해 페이지를 만듭니다. 두 곳 모두에 저장하는 옵션도 가능합니다.
옵션 설정 시스템
사용자는 처리 방식을 세밀하게 제어할 수 있어야 합니다. 이를 위해 설정 파일이나 대화형 인터페이스를 통해 다양한 옵션을 제공할 수 있습니다.
저장 위치 옵션으로는 Obsidian only, Notion only, 또는 Both를 선택할 수 있습니다. 처리 깊이는 Quick(빠른 요약만), Standard(일반적인 분석), Deep(상세한 분석과 추가 리서치) 중에서 선택합니다. 출력 형식도 원본 유지, 요약본, 구조화된 노트, 마인드맵 형식 등 다양하게 지정할 수 있습니다.
컨텐츠 재가공 기능
저장된 데이터를 새로운 형태의 콘텐츠로 변환하는 것이 이 시스템의 강력한 기능입니다. 예를 들어, 여러 논문을 분석하여 저장한 노트들을 모아 종합적인 문헌 리뷰를 작성할 수 있습니다. 기술 문서들을 바탕으로 튜토리얼이나 가이드를 생성할 수도 있습니다.
이 과정은 별도의 스킬로 구현됩니다. Content Generation 스킬은 저장된 노트들을 검색하고, 관련된 내용들을 연결하여 새로운 문서를 생성합니다. 이때 원본 소스를 적절히 인용하고, 필요한 경우 추가적인 컨텍스트나 설명을 덧붙입니다.
실전 구현 예시
CLAUDE.md 설정
Claude Code의 동작을 정의하는 CLAUDE.md 파일에는 다음과 같은 내용이 포함되어야 합니다. 먼저 에이전트의 역할을 명확히 정의합니다. “당신은 지식 관리 에이전트입니다. 문서와 웹 콘텐츠를 분석하고, 구조화하여, 지정된 저장소에 저장하는 것이 주요 임무입니다.”
그다음 입력 처리 규칙을 명시합니다. “파일 경로가 제공되면 해당 파일의 확장자를 확인하고 적절한 방법으로 읽습니다. URL이 제공되면 먼저 web_fetch를 시도하고, 실패하거나 콘텐츠가 불완전하면 Playwright MCP를 사용합니다.”
스킬 실행 순서도 정의합니다. “항상 document_analyzer 스킬을 먼저 실행하여 콘텐츠 구조를 파악하고, 그 결과를 바탕으로 metadata_extractor와 summarizer를 실행합니다. 필요한 경우 translator 스킬도 활용합니다.”
저장 로직도 명확히 합니다. “사용자가 저장 위치를 지정하지 않으면 기본값은 Obsidian입니다. Obsidian에 저장할 때는 /path/to/vault/Imported/ 디렉토리를 사용하고, 파일명은 ‘날짜-제목.md’ 형식을 따릅니다.”
스킬 파일 구조
각 스킬은 독립적인 마크다운 파일로 작성됩니다. 예를 들어 document_analyzer.md 스킬은 다음과 같은 구조를 가집니다.
스킬의 목적을 먼저 설명합니다. “이 스킬은 입력된 문서를 분석하여 제목, 섹션 구조, 주요 개념, 핵심 논점을 추출합니다.” 그런 다음 입력 형식을 정의합니다. “전체 문서 텍스트를 입력으로 받습니다.”
분석 절차를 단계별로 기술합니다. “1단계: 문서의 전체 구조를 파악합니다. 제목, 부제목, 섹션을 식별합니다. 2단계: 각 섹션의 핵심 내용을 요약합니다. 3단계: 문서 전체에서 반복되는 주요 개념과 키워드를 추출합니다. 4단계: 문서의 주요 주장이나 결론을 식별합니다.”
출력 형식은 JSON이나 구조화된 마크다운으로 정의합니다. “결과는 다음 형식의 JSON으로 반환합니다: {title, sections: [{heading, summary, key_points}], main_concepts, conclusions}”
Playwright 활용 예시
복잡한 웹사이트를 처리할 때 Playwright MCP를 어떻게 사용하는지 구체적인 예를 들어보겠습니다. 예를 들어, 로그인이 필요한 Medium 글을 가져오려면 다음과 같은 프로세스를 거칩니다.
먼저 Playwright를 통해 브라우저를 시작하고 Medium 사이트로 이동합니다. 로그인 버튼을 찾아 클릭하고, 이메일과 비밀번호 필드를 채운 후 로그인을 완료합니다. 로그인이 성공하면 목표 URL로 이동하고, 페이지가 완전히 로드될 때까지 기다립니다. JavaScript로 렌더링된 콘텐츠가 모두 표시되면, 본문 내용을 추출하고 이미지 URL도 함께 수집합니다.
추출된 HTML을 마크다운으로 변환하고, 이미지는 로컬에 다운로드하거나 URL을 그대로 유지합니다. 최종적으로 정리된 콘텐츠를 Claude의 다른 스킬들이 처리할 수 있는 형식으로 반환합니다.
배치 처리 구현
여러 문서를 한 번에 처리하는 배치 기능도 유용합니다. 폴더 경로를 제공하면 그 안의 모든 문서를 순차적으로 처리하거나, URL 리스트 파일을 제공하면 각 URL을 방문하여 콘텐츠를 수집합니다.
이 과정에서 진행 상황을 추적하고, 실패한 항목은 별도로 로깅하며, 처리가 완료된 후 전체 결과를 요약 보고서로 생성합니다. 각 문서의 처리 시간, 성공/실패 여부, 생성된 파일 경로 등을 포함한 상세 로그를 제공합니다.
고급 기능
자동 태깅 시스템
처리된 문서에 자동으로 관련 태그를 부여하는 기능을 구현할 수 있습니다. 이는 머신러닝 기반 키워드 추출이나, 사전 정의된 태그 체계와의 매칭을 통해 이루어집니다. Claude의 강력한 자연어 이해 능력을 활용하면, 문서의 맥락을 파악하여 적절한 태그를 제안할 수 있습니다.
관계 그래프 생성
저장된 문서들 간의 관계를 자동으로 파악하고 링크를 생성하는 기능도 가능합니다. 비슷한 주제를 다루는 문서들을 찾아 연결하거나, 한 문서에서 언급된 개념이 다른 문서에서 상세히 다뤄졌다면 자동으로 링크를 추가합니다. 이는 Obsidian의 그래프 뷰에서 지식의 네트워크를 시각화하는 데 매우 유용합니다.
주기적인 업데이트 체크
웹 소스의 경우, 정기적으로 재방문하여 내용이 업데이트되었는지 확인하는 기능을 추가할 수 있습니다. 변경사항이 감지되면 기존 노트에 업데이트 이력을 추가하거나, 새로운 버전을 별도로 저장할 수 있습니다.
템플릿 시스템
다양한 문서 유형에 맞는 템플릿을 미리 정의해두면 더욱 일관된 노트를 생성할 수 있습니다. 학술 논문용 템플릿, 기술 문서용 템플릿, 뉴스 기사용 템플릿 등을 준비하고, 문서 유형을 자동 감지하여 적절한 템플릿을 적용합니다.
성능 최적화
대량의 문서를 처리할 때는 성능 최적화가 중요합니다. Claude Code의 체크포인트 시스템을 활용하여 긴 작업을 중단했다가 재개할 수 있도록 구현합니다. 각 문서 처리가 완료될 때마다 진행 상황을 저장하여, 오류가 발생해도 처음부터 다시 시작하지 않도록 합니다.
캐싱 전략도 중요합니다. 이미 처리한 URL이나 파일의 해시값을 저장하여, 중복 처리를 방지합니다. 웹 콘텐츠의 경우 일정 기간 동안은 캐시된 버전을 사용하고, 주기적으로만 재확인합니다.
보안 및 프라이버시
문서 처리 과정에서 민감한 정보를 다룰 수 있으므로 보안에 주의해야 합니다. API 키나 인증 정보는 환경 변수나 별도의 설정 파일에 안전하게 저장하고, 코드에 하드코딩하지 않습니다. Playwright로 로그인이 필요한 사이트에 접근할 때는 세션 정보를 안전하게 관리하고, 사용 후 적절히 정리합니다.
처리된 문서에 개인정보나 민감한 데이터가 포함되어 있을 수 있으므로, 저장 전에 선택적으로 필터링하는 옵션을 제공할 수 있습니다. 특정 패턴(이메일 주소, 전화번호, 신용카드 번호 등)을 감지하여 마스킹하거나 제거하는 기능을 구현합니다.
결론
Claude Code를 활용한 지식 관리 에이전트는 문서 수집부터 분석, 저장, 재가공까지 전체 지식 관리 워크플로우를 자동화할 수 있는 강력한 도구입니다. MCP를 통해 다양한 외부 시스템과 통합하고, 커스텀 스킬을 통해 콘텐츠 처리를 세밀하게 제어할 수 있습니다.
핵심은 각 단계를 명확히 정의하고, 스킬들이 체계적으로 협력하도록 설계하는 것입니다. Progressive Context Loading 아키텍처를 활용하면 수십 개의 스킬을 컨텍스트 한계 없이 사용할 수 있으며, 체크포인트 시스템으로 안정적인 장시간 작업이 가능합니다.
이러한 시스템을 구축하면 단순히 정보를 저장하는 것을 넘어, 지식을 구조화하고 연결하며, 새로운 인사이트를 생성하는 진정한 의미의 지식 관리를 실현할 수 있습니다.
작성 일자: 2025-12-24