프로그래밍 책을 AI 에이전트 전문 기술로 바꾸는 법

언스트럭처드 공식 문서에는 PDF 처리 방식이 auto, fast, hi_res, ocr_only 네 가지로 정리되어 있습니다. 이 구분만 봐도 결론은 분명합니다. 프로그래밍 책을 AI 에이전트 전문 기술로 바꿀 때는 PDF를 바로 작업 기술에 넣지 말고, PDF 추출 → Knowledge Base 구축 → Agent Skill 실행 절차 작성으로 분리해야 합니다. 이번 주에는 책 일부를 골라 세 층을 각각 검증하는 방식으로 시작하는 것이 안전합니다. (PDF 처리 방식 공식 문서)

이 글은 코드와 표가 포함된 PDF를 처리해야 하는 개발자를 위한 내용입니다. 전체 책을 작업 기술에 넣을지 지식 검색 방식으로 운영할지 비교하는 에이전트 개발자에게도 적합합니다. 여러 권의 기술 자료를 계속 갱신해야 하는 지식 공학팀이라면 마지막의 유지 관리 기준까지 확인해야 합니다.

먼저 구조를 세 층으로 나누기

책을 변환할 때 가장 흔한 실수는 원문 전체를 하나의 긴 지시문으로 만드는 것입니다. 그러면 다음 문제가 생깁니다.

오래된 코드와 최신 코드가 함께 검색됩니다.
답변이 어느 장과 페이지에서 나왔는지 확인하기 어렵습니다.
코드 실행에 필요한 라이브러리와 운영체제 조건이 빠집니다.
작업 기술이 길어져 다른 작업의 문맥을 차지합니다.
책을 교체할 때 전체 기술을 다시 작성해야 합니다.
PDF에 포함된 비밀 정보나 실행 명령이 그대로 실행될 위험이 있습니다.

권장 구조는 다음과 같습니다.

추출 층: PDF 페이지에서 글, 코드, 표, 이미지 정보를 복원합니다.
Knowledge Base 층: 장, 절, 페이지, 버전, 코드 조건을 검색 가능한 지식 단위로 저장합니다.
Agent Skill 층: 어떤 요청에서 지식을 찾고, 어떤 순서로 실행하며, 결과를 어떻게 검사할지 정의합니다.

앤스로픽 공식 문서도 작업 기술을 지시문, 실행 코드, 참고 자료가 들어 있는 파일 기반 묶음으로 설명합니다. 필요한 자료만 단계적으로 읽게 하는 방식이므로, 책 전체를 항상 문맥에 올리는 설계와는 다릅니다. (작업 기술 구조 공식 문서)

첫 단계: 텍스트형 PDF는 페이지와 배치를 보존해 추출하기

텍스트형 PDF라면 처음부터 OCR을 적용하지 않는 것이 좋습니다. 먼저 실제 문자 정보가 있는지 확인합니다. 피뮤피디에프는 일반 텍스트뿐 아니라 블록, 단어, 위치 정보를 추출할 수 있습니다. 블록 추출 결과에는 경계 좌표와 블록 번호가 포함되므로 코드와 설명의 위치를 다시 확인하기 쉽습니다. (텍스트와 블록 추출 공식 문서)

권장 처리 순서는 다음과 같습니다.

문서 목차를 읽고 장과 절의 시작 페이지를 기록합니다.
페이지별 텍스트를 추출합니다.
블록 좌표를 사용해 위에서 아래, 왼쪽에서 오른쪽 순서가 맞는지 검사합니다.
페이지 머리말, 꼬리말, 반복되는 책 제목을 제거합니다.
코드 블록은 일반 문장과 별도 유형으로 저장합니다.
원문 페이지 번호와 추출 결과를 함께 보관합니다.

피뮤피디에프의 기본 추출 순서는 PDF 제작 방식에 따라 자연스러운 읽기 순서와 다를 수 있습니다. 위치 기반 정렬을 요청할 수 있지만, 두 칼럼 문서나 떠 있는 코드 예제는 별도 검수가 필요합니다. (텍스트 추출 조리법 공식 문서)

이 단계에서 확인할 핵심 항목은 세 가지입니다.

글자가 깨져 다른 문자로 바뀌지 않았는가
코드의 들여쓰기와 기호가 보존되었는가
페이지 번호와 장 제목이 원문과 일치하는가

단순히 추출된 문자의 양만 세면 안 됩니다. 검색 가능한 텍스트가 많아도 코드의 들여쓰기 하나가 사라지면 실행 지식으로는 사용할 수 없습니다.

두 번째 단계: 스캔 PDF는 필요한 페이지만 OCR하기

스캔된 책은 글자가 아니라 이미지로 저장되어 있습니다. 이때 모든 페이지를 같은 방식으로 OCR하면 처리 시간이 늘고, 이미 추출 가능한 텍스트까지 다시 인식하면서 오탈자가 생길 수 있습니다.

먼저 페이지별로 다음 상태를 판별합니다.

문자 선택이 가능한 페이지
이미지 한 장으로만 구성된 페이지
표나 그림이 많은 페이지
두 칼럼과 코드 이미지가 섞인 페이지

언스트럭처드는 PDF에서 빠른 추출, 고해상도 배치 분석, OCR 전용 처리를 구분합니다. auto는 문서 상태에 따라 방식을 선택하며, 표 구조가 중요한 경우에는 고해상도 방식이 필요할 수 있습니다. 공식 문서에는 OCR 언어 설정과 표 구조 추론 옵션도 명시되어 있습니다.

스캔판 프로그래밍 책에서 코드를 추출할 때는 OCR 결과를 그대로 신뢰하면 안 됩니다. 다음 문자는 자주 혼동됩니다.

숫자 0과 알파벳 O
숫자 1과 소문자 l
백틱과 작은따옴표
괄호와 중괄호
들여쓰기와 탭
마침표와 쉼표

표와 두 칼럼은 더 위험합니다. OCR 결과만 저장하지 말고 원본 페이지 그림과 추출 텍스트를 함께 보관해야 합니다. 코드가 이미지 안에 있다면 코드 영역을 잘라 별도 검사를 거칩니다.

주의: 사용 권한이 있는 PDF만 처리해야 합니다. 암호를 우회하거나 저작권 보호를 무력화하는 방법은 이 변환 흐름에 포함하지 않습니다. 접근 제한이 있는 문서는 권리자에게 제공받은 정상 파일로 다시 시작해야 합니다.

세 번째 단계: 코드와 설명을 하나의 지식 단위로 묶기

프로그래밍 책의 코드는 단독 지식이 아닙니다. 실행 환경, 패키지 버전, 앞에서 정의한 함수, 예상 출력이 함께 있어야 합니다.

따라서 다음과 같은 단위로 구조화하는 편이 좋습니다.

지식 단위
- 책 제목
- 판본 또는 개정 정보
- 장과 절
- 원문 페이지
- 주제
- 설명
- 코드
- 실행 환경
- 의존 패키지
- 예상 결과
- 알려진 제한

코드만 따로 저장하면 검색 결과는 그럴듯하지만 실행 단계에서 실패합니다. 예를 들어 코드가 특정 언어 버전이나 운영체제 기능에 의존한다면, 해당 조건이 지식 단위의 필수 필드가 되어야 합니다.

라마인덱스의 문서와 노드 구조도 이 방식과 잘 맞습니다. 문서는 원자료를 담고, 노드는 문서에서 분리된 검색 단위가 됩니다. 문서의 메타데이터는 파생 노드에 전달할 수 있으므로 책 제목과 파일 정보를 검색 결과에 남기기 쉽습니다. (문서와 노드 공식 문서)

네 번째 단계: 고정 길이보다 의미 경계로 Knowledge Base 나누기

모든 문서를 같은 글자 수로 자르는 방식은 프로그래밍 책에 적합하지 않습니다. 함수 설명 중간에서 코드가 끊기거나, 오류 해결 조건과 해결 방법이 서로 다른 검색 단위로 분리될 수 있기 때문입니다.

우선 장과 절을 큰 경계로 사용합니다. 그다음 다음 기준으로 더 작게 나눕니다.

개념 설명과 예제 코드
코드 실행 조건과 결과
오류 원인과 해결 절차
표의 제목과 표 내용
장의 요약과 다음 절의 전제

라마인덱스에는 의미적으로 가까운 문장을 묶는 분할 방식이 있으며, 메타데이터 포함과 앞뒤 노드 관계를 설정할 수 있습니다. 언스트럭처드는 먼저 문서 요소를 만든 뒤 필요한 경우에만 추가로 잘게 나누는 흐름을 설명합니다. (의미 기반 분할 공식 문서)

각 단위에는 최소한 다음 출처 정보를 붙이십시오.

책 제목과 판본
원본 파일 식별자
장과 절
인쇄 페이지와 PDF 페이지
추출 방식
처리 날짜
검수 상태

이 정보가 있어야 에이전트가 답변 뒤에 “어디에서 찾았는가”를 제시할 수 있습니다. 라마인덱스의 인용 질의 방식도 검색된 출처 단위를 답변에 연결하는 구조를 제공합니다. (인용 질의 공식 문서)

다섯 번째 단계: Agent Skill은 지식이 아니라 실행 절차로 작성하기

Agent Skill에는 책의 모든 내용을 복사하지 않습니다. 작업 기술은 다음 질문에 답해야 합니다.

어떤 요청에서 이 기술을 호출하는가
Knowledge Base에서 어떤 조건으로 검색하는가
검색 결과의 판본과 실행 환경을 어떻게 확인하는가
코드를 어디에서 실행하는가
결과가 예상 출력과 맞는지 어떻게 검사하는가
실패하면 어떤 정보와 함께 사용자에게 되묻는가

작업 기술의 파일에는 짧은 호출 설명과 단계별 절차를 넣고, 긴 원문과 참고 자료는 별도 파일이나 Knowledge Base에 둡니다. 공식 문서 기준으로 작업 기술은 메타데이터, 지시문, 필요할 때 읽는 참고 자료와 실행 파일을 나누어 사용할 수 있습니다. 메타데이터의 이름과 설명에도 호출 조건과 기능을 분명히 넣어야 합니다.

코드 실행이 필요한 작업이라면 추가 제한이 필수입니다.

임시 실행 디렉터리 사용
네트워크 기본 차단
패키지 설치 허용 목록 지정
파일 읽기와 쓰기 경로 제한
실행 시간과 메모리 제한
결과 파일의 확장자와 크기 검사
명령어와 환경 변수 기록

특히 책의 예제 코드를 자동 실행할 때는 셸 명령과 외부 접속 기능을 분리해야 합니다. 설명용 예제가 실제 운영 서버를 변경하지 않도록 격리 환경에서 먼저 검증해야 합니다.

여러 권을 합칠 때는 새 색인이 아니라 변경 영향부터 추적하기

여러 프로그래밍 책을 한 Knowledge Base에 넣을 때는 주제별로 검색할 수 있게 통합하되, 출처와 충돌을 없애면 안 됩니다. 같은 개념을 서로 다른 판본이 다르게 설명할 수 있기 때문입니다.

권장 방식은 다음과 같습니다.

주제 색인은 통합합니다.
책과 판본 정보는 원래대로 보존합니다.
서로 다른 코드와 설명은 별도 출처로 남깁니다.
최신 판본을 기본값으로 표시합니다.
오래된 판본은 호환성 참고 자료로 표시합니다.
새 판본이 들어오면 영향을 받은 장만 다시 추출합니다.
관련 Agent Skill의 검색과 실행 시험을 다시 수행합니다.

작업 기술 자체도 버전으로 관리해야 합니다. 설명 파일만 바뀐 경우와 실행 스크립트가 바뀐 경우를 구분하면 장애 원인을 찾기 쉽습니다. 새 책을 추가할 때마다 전체 색인을 무조건 재생성하기보다, 변경된 문서와 연결된 지식 단위부터 갱신하는 편이 운영 부담이 작습니다.

PDF를 바로 Skill에 넣어도 되는 조건은 따로 있습니다

PDF를 바로 Agent Skill에 넣는 방식은 다음 조건을 모두 만족할 때만 고려할 수 있습니다.

자료가 짧습니다.
내용이 장기간 변하지 않습니다.
실행 절차가 단순합니다.
출처 페이지를 별도로 추적할 필요가 없습니다.
여러 판본을 비교하지 않습니다.
코드 실행이나 권한 검사가 없습니다.

그 외에는 Knowledge Base와 Skill을 분리해야 합니다. 아래 표는 선택 기준을 빠르게 정리한 것입니다.

선택 방식	적합한 자료	검색과 인용	유지 관리	실행 안전성	편집 기준 점수
PDF 전체를 Skill에 포함	짧고 안정적인 안내서	낮음	낮음	중간	2점
텍스트만 추출해 Knowledge Base 저장	일반 설명 중심 책	중간	중간	높음	3점
PDF와 OCR을 구분한 Knowledge Base	스캔, 표, 두 칼럼 문서	높음	중간	높음	4점
추출·지식·Skill을 세 층으로 분리	코드가 많고 여러 판본을 관리하는 팀	매우 높음	높음	매우 높음	5점

따라서 이번 주의 실행 순서는 간단합니다. 합법적인 텍스트형 PDF 한 권에서 1개 장을 고릅니다. 페이지와 코드 추출을 확인합니다. 같은 내용을 지식 단위로 저장합니다. 마지막으로 검색, 실행, 결과 검사를 포함한 짧은 Agent Skill을 만들어 봅니다. 세 단계 중 하나라도 출처를 잃으면 전체 책 변환을 중단하고 구조부터 수정해야 합니다.

현재 로컬 PC나 일반 클라우드에서 이 작업을 진행하면 OCR 의존 패키지 설치가 꼬이고, 코드 실행과 원문 보관이 한 환경에 섞이며, 팀원이 같은 조건을 재현하기 어려운 문제가 생깁니다. 특히 여러 PDF를 일괄 처리하거나 책 속 코드를 반복 검증할 때는 저장 공간, 권한, 격리 실행을 따로 관리해야 합니다. 이런 경우에는 VPSSpark의 문서 처리 환경 상담을 통해 필요한 작업 조건을 먼저 정리하고, 단기간의 맥 원격 환경 사용 옵션을 비교하는 편이 현실적입니다. 장기 고정 부하나 물리 장치 연결이 필요한 팀이라면 직접 장비를 운영하는 편이 낫지만, 합법적인 PDF를 일괄 처리하고 코드를 검증하는 임시 환경이라면 환경을 분리해 쓰는 쪽이 장애와 정리 비용을 줄이기 쉽습니다. VPSSpark의 운영 범위가 궁금하다면 서비스 운영 방식 안내도 함께 확인할 수 있습니다.