KiCad Footprint Agent

작업 기록

라이브러리

시작하기

부품 번호를 입력하거나 데이터시트 PDF/링크를 지정합니다.
에이전트가 데이터시트에서 핀 표와 패키지 도면을 읽어 사양을 추출합니다.
회로 기호(.kicad_sym)와 풋프린트(.kicad_mod)를 생성합니다.
규칙 검증 · KiCad CLI 파싱 · AI 교차 검토를 거쳐, 통과하면 라이브러리에 저장합니다.

사용법

1. 준비

Claude 연결 (둘 중 하나)
- Claude Code CLI — API 키 없이 사용합니다. npm i -g @anthropic-ai/claude-code 설치 후 터미널에서 claude 를 한 번 실행해 로그인하면, 서버가 claude -p 를 헤드리스로 실행해 데이터시트 읽기(Read)·웹 검색(WebSearch/WebFetch)을 합니다. 상단 칩이 Claude CLI 연결 로 표시됩니다.
- Anthropic API 키 — 프로젝트 폴더의 .env 에 ANTHROPIC_API_KEY=… 를 넣으면 API 로 직접 호출합니다 (키가 있으면 API 우선). FP_AGENT_BACKEND=cli 로 CLI 를 강제할 수 있습니다.
KiCad 9 — 설치되어 있으면 kicad-cli 를 자동으로 찾아 생성 파일이 실제로 KiCad 에서 열리는지 검증합니다. 경로가 다르면 KICAD_CLI 환경변수로 지정합니다.

2. 부품 만들기 — 세 가지 입력 방법

① PDF 업로드

데이터시트 PDF 를 끌어놓습니다. 가장 확실한 방법입니다.

② 데이터시트 링크

PDF 주소(또는 PDF 링크가 있는 페이지)를 붙여넣으면 서버가 내려받습니다.

③ 부품 번호만

링크·파일이 없으면 에이전트가 웹 검색으로 제조사 공식 데이터시트를 찾아 내려받습니다.

패키지 지정 — 한 데이터시트에 여러 패키지(SOIC/TSSOP/QFN 등)가 있으면 원하는 것을 적어 주세요. 비우면 부품 번호의 주문 코드로 판단합니다.
AI 검토 — 끄면 추출 결과로 바로 생성·규칙 검증만 합니다 (빠르지만 교차 검토 없음).
통과 시 자동 저장 — 규칙 검증 · KiCad 파싱 · AI 검토를 모두 통과하면 라이브러리에 바로 저장합니다.

2-1. 폴더 일괄 생성

데이터시트 PDF 가 모여 있는 폴더를 지정해 한 번에 만듭니다. 왼쪽 위 폴더 일괄 을 누르세요.

폴더 지정 — 경로를 붙여넣거나 찾아보기 로 내 PC 의 폴더를 고릅니다 (브리지가 이 PC 의 폴더 목록을 보여 줍니다). 필요하면 하위 폴더 포함.
PDF 찾기 — 폴더의 PDF 목록이 나옵니다. 이미 라이브러리에 저장된 데이터시트(파일 내용 SHA-1 이 같은 것)는 초록 표시와 함께 선택이 풀려 있습니다. 만들 파일만 체크합니다.
옵션 — 라이브러리 이름, AI 검토, 통과 시 자동 저장, 이미 저장된 데이터시트 건너뛰기, 동시 처리(1~3개, Claude 사용량과 PC 성능에 맞춰 조절).
일괄 생성 시작 — 오른쪽 진행 표에서 파일별 단계 · 결과(저장됨 / 검토 필요 / 실패 / 건너뜀)를 봅니다. 행을 누르면 그 부품의 미리보기 · 검증 · AI 검토가 아래에 열리고, 검토 필요 항목은 거기서 고쳐 저장합니다.
중지 — 진행 중인 파일은 끝까지 처리하고 남은 파일은 건너뜁니다.

파일 이름은 부품 번호 단서로만 쓰고, 실제 부품 · 패키지는 데이터시트 내용으로 판단합니다. 한 데이터시트에 여러 부품 · 패키지가 있으면 대표 하나만 만들므로, 다른 변형은 단일 부품 모드에서 패키지 지정 으로 추가하세요.

2-2. 3D 모델

3D 모델 을 켜 두면(기본) 풋프린트가 완성된 뒤 데이터시트의 패키지 도면으로 3D 모델(STEP)을 만들어 풋프린트에 연결합니다.

AI 가 도면의 측면도 · 윗면도에서 몸체 두께(A − A1), 띄움(A1), 리드 두께(c) · 모양(걸윙 / J 리드 / 노리드 / 양 끝 전극 / 스루홀 / 볼), 윗모서리 경사, 1번 핀 표시, 색을 읽습니다. 평면 치수는 풋프린트 사양을 그대로 씁니다.
각인: 데이터시트 마킹 도면(Package Marking · Marking Diagram 그림)에 그려진 문구를 줄 그대로 새깁니다. 날짜 · 로트 코드 자리(YYWW 등)도 표기대로. 마킹 도면이 없으면 마킹 표(Device Marking)의 코드, 둘 다 없을 때만 품명을 씁니다. 근거는 3D 탭의 「각인」 옆에 (마킹 도면 / 마킹 표 / 품명) 으로 표시됩니다.
KiCad 로 렌더링한 그림(기울여 보기 · 위에서 보기)을 AI 가 도면과 다시 대조하고, 틀리면 고쳐서 한 번 더 만듭니다.
3D 탭에서 그림 · 판독값 · 검토 결과를 보고, 3D 사양(JSON)을 고쳐 이 사양으로 3D 다시 만들기 할 수 있습니다. .step 버튼으로 내려받기.
이미 저장된 부품: 왼쪽 라이브러리 카드에서 3D 가 있는 부품은 3D 로 표시됩니다. 3D 일괄 추가 는 3D 가 없는 부품 전부, 부품 옆 3D 만들기 는 그 부품 하나 — 저장된 사양과 데이터시트로 3D 단계만 실행하고 원래 라이브러리(AutoParts · AgentParts …)에 다시 저장합니다. 진행은 오른쪽 일괄 작업 표에 나옵니다.
저장 위치: library/<라이브러리>.3dshapes/<풋프린트>.step (풋프린트와 따로). PCB Agent 는 부품을 설치할 때 이 파일을 프로젝트의 AgentParts.3dshapes 로 복사해 3D 뷰에 붙입니다.

3. 결과 확인

탭	내용
미리보기	회로 기호와 풋프린트(패드 번호·1번 핀 표시·코트야드 포함). 체크박스로 KiCad CLI 렌더링과 비교할 수 있습니다.
핀	핀 번호 · 이름 · 전기적 타입 · 그룹
패드	패키지 치수 요약과 패드 좌표표 (원점 = 패키지 중심, Y 아래쪽 +, mm)
검증	규칙 검증 항목별 결과와 kicad-cli 로그
AI 검토	회차별 검토 판정, 지적 사항, 데이터시트 근거 페이지
3D	3D 렌더 그림, 도면에서 읽은 높이 · 리드 · 각인, AI 대조 검토, 3D 사양 편집 · 다시 만들기
사양 편집	추출된 사양 JSON 을 고쳐 즉시 재생성(AI 없이) 하거나 재생성 + AI 검토 를 다시 돌립니다.

4. 저장과 KiCad 에서 사용

상태가 검증 통과 이면 저장 버튼으로, 검토 필요 이면 내용을 확인한 뒤 강제 저장합니다.
저장 위치: library/<라이브러리>.kicad_sym, library/<라이브러리>.pretty/*.kicad_mod, 근거 기록 library/specs/*.json, 데이터시트 사본 library/datasheets/.
KiCad → 환경설정 → 심볼/풋프린트 라이브러리 관리 에서 위 파일을 추가하거나, 함께 생성되는 sym-lib-table / fp-lib-table 항목을 복사해 사용합니다. 심볼의 Footprint 필드는 <라이브러리>:<풋프린트> 로 미리 연결되어 있습니다.

5. Claude 없이 쓰기

examples/ 폴더의 JSON 처럼 사양을 직접 작성해 사양 편집 탭에 붙여넣고 즉시 재생성 하면 생성 · 규칙 검증 · KiCad 검증까지 동작합니다.

주의

자동 생성 결과는 반드시 데이터시트와 대조해 확인한 뒤 실제 보드에 사용하세요. 특히 1번 핀 위치, 패드 번호 방향, 노출 패드(EP) 번호, 다이오드 극성은 검증 통과 후에도 눈으로 확인하는 것을 권장합니다.

개발 · 수정 이력

KiCad Footprint Agent — 데이터시트에서 KiCad 회로 기호 · 풋프린트를 자동으로 만드는 웹 에이전트. 날짜는 KST. 커밋 해시는 GitHub samcho93/webFootprintAgent 기준이며, 첫 커밋(c72b6de) 전의 개발 과정은 단계별로 정리했다.

버전	날짜	요약	커밋
0.5.1	2026-10-19	라이브러리에 있는 부품에 3D 모델 일괄 추가	—
0.5.0	2026-10-19	데이터시트 도면 기반 3D 모델 (각인 포함) · PCB Agent 3D 뷰 연동	c4028c9
0.4.2	2026-10-15	다른 PC 에서 실행할 때의 환경 점검	d58645c
0.4.1	2026-10-15	사용법 메뉴에 개발 · 수정 이력 표시	d0375a3
0.4.0	2026-10-15	폴더 일괄 생성	96bb45d
0.3.1	2026-10-15	`?job=<id>` 로 결과 바로 열기	2be6411
0.3.0	2026-10-15	irodmas.com 배포 (정적 화면 + 로컬 브리지)	c72b6de
0.2.0	2026-10-15	API 키 없이 Claude Code CLI 로 동작	c72b6de
0.1.0	2026-10-15	초기 개발	c72b6de

0.5.1 — 라이브러리 부품에 3D 모델 일괄 추가

요청: 이미 라이브러리에 저장된 부품(0.5.0 이전)에도 3D 모델을 한 번에 추가.

추가

라이브러리 카드: 3D 가 있는 부품에 3D 표시, 3D 일괄 추가 (N) 버튼, 부품별 3D 만들기.
일괄 큐에 「라이브러리 3D」 종류: 저장된 사양(specs/*.json)과 데이터시트(기록된 경로, 없으면 datasheets/<부품>.pdf)로 3D 단계만 실행 → 풋프린트가 있는 라이브러리(AutoParts · AgentParts …)에 모델과 함께 다시 저장. 원래 상태 표기(passed · 수동 승인 등) 유지, 이미 3D 가 있으면 건너뜀(force 로 다시).
POST /api/library/model3d, 부품 목록에 lib · model 항목.

수정

작은 몸체에 긴 각인(예: SOT-23-5 에 "SN74LVC1G14")이 들어가지 않으면 조용히 빠지던 문제 → 2 · 3 줄로 나눠 다시 배치.
각인은 데이터시트 마킹 도면의 문구를 참조 (요청): ① 마킹 도면(Package Marking · Marking Diagram · Top Marking 그림)에 그려진 줄을 그대로 — 날짜 · 로트 자리(YYWW, LLLL …)도 표기대로 ② 도면이 없으면 마킹 표 / Package Option Addendum 의 Device Marking 코드(작은 패키지는 "C14F" 같은 짧은 코드) ③ 둘 다 없을 때만 품명. 근거를 marking_source(도면 · 표 · 품명)로 기록해 3D 탭과 로그에 표시하고, 검토 단계도 마킹 도면과 줄 단위로 대조. CLI 백엔드가 그림으로 넘기는 페이지에 마킹 도면 페이지를 우선.
KiCad 탐지: 설치 폴더 이름(KiCad\9.0\bin)에서 버전을 읽어 kicad-cli version(첫 실행 14초)을 생략 → 0.25초. 바쁠 때 탐지가 한 번 실패하면 5분 동안 3D 렌더 · 검토가 모두 생략되던 문제 → 못 찾은 결과는 30초만 캐시.
스루홀 원통(부저 등)에 SMD 용 사각 받침대가 붙던 문제, 원통 몸체에는 각인이 안 되던 문제 (원 안 정사각형에 새김).

0.5.0 — 3D 모델 (데이터시트 도면 기반, 각인 포함)

요청: 풋프린트가 완성되면 AI 가 데이터시트를 참조 · 판단해 3D 모델을 만들고 따로 저장해, PCB Agent 의 3D 뷰에서 PCB 에 붙여 사용. 데이터시트가 있는 부품은 도면을 바탕으로 렌더링하고, 품명 등 텍스트 각인도 넣을 것.

추가

파이프라인에 3D 모델 단계(풋프린트 검토 뒤): 도면 판독(Claude) → STEP 생성 → KiCad 렌더 → 렌더 그림 ↔ 도면 대조 검토(Claude) → 틀리면 수정해 다시 (최대 2회, FP_AGENT_3D_ROUNDS). 3D 단계가 실패해도 풋프린트 결과는 유지.
Model3DSpec: 몸체 두께(A − A1) · 띄움(A1) · 리드 두께(c) · 리드 모양(걸윙 / J / 노리드 / 양 끝 전극 / 스루홀 / 볼 / 평판 탭) · 윗모서리 경사 · 색 · 1번 핀 표시(점 / 캐소드 띠) · 각인 줄(Device/Package Marking 표).
app/kicad/model3d.py: CAD 커널 없이 볼록 다면체(상자 · 기울어진 각기둥 · 원기둥 · 구 · 경사 몸체)를 조합해 색 있는 STEP(AP214, FACETED_BREP)으로 출력. 패키지 유형별 리드 형상.
app/kicad/marking.py: 획 글꼴(영문 대문자 · 숫자 · 기호)로 윗면 각인. 데이터시트 윗면도 방향(세로로 긴 몸체는 1번 핀 기준 90° 회전), 1번 핀 점과 겹치지 않게 배치.
app/kicad/render3d.py: KiCad Python(pcbnew)으로 작은 보드를 만들어 kicad-cli pcb render (기울여 보기 · 위에서 보기).
저장: library/<라이브러리>.3dshapes/<풋프린트>.step, 풋프린트에 (model ...) 연결.
화면: 「3D 모델」 옵션(단일 · 폴더 일괄), 단계 표시에 3D, 3D 탭(렌더 그림 · 판독값 · 검토 · 3D 사양 편집 · 다시 만들기), .step 내려받기.
Claude CLI 백엔드에서 그림 입력 지원 (임시 파일 → Read 도구).
API: GET /api/jobs/{id}/download/model, GET /api/jobs/{id}/render3d/{iso|top}, POST /api/jobs/{id}/model3d.
PCB Agent 연동 (webCadAgent): 부품 설치 때 STEP 을 프로젝트 AgentParts.3dshapes/ 로 복사하고 ${KIPRJMOD} 경로로 연결, 이미 보드에 놓인 같은 풋프린트에 3D 모델을 붙인 뒤 3D 뷰(렌더 · GLB)를 다시 그림. Footprint Agent 라이브러리에서 고른 풋프린트도 모델을 함께 복사.

수정

Claude CLI 백엔드에서 PDF 페이지를 그림으로 못 여는 환경(pdftoppm 없음) 때문에 도면을 보지 못하던 문제 → 도면 · 랜드 패턴 · 각인 표 페이지를 PyMuPDF 로 PNG 로 렌더해 함께 넘김. 앞 단계 근거 페이지(p.54 …)와 패키지 코드(D0008A …)를 우선 골라, 풋프린트 추출 · 검토에도 같은 방식 적용.

검증

LM358DR (TI, SOIC-8 D0008A): 도면 판독 몸체 1.575 mm + 띄움 0.175 mm(A1 0.10~0.25), 걸윙, 각인 "LM358" → 렌더 → 3D 검토 pass → 저장.
TPS62130RGT (TI, VQFN-16 RGT0016C): 원본 p.40 측면도 A 0.8~1.0 → 0.9 mm, 노리드 단자, NiPdAu 마감 → 금색 단자, Part marking "PTSI"(p.32) → 3D 검토 pass → 저장.
예제 9종(QFN · BGA · DIP · 0603 · SOT-23 · SOT-23-5 · SIP 등) STEP 생성 · KiCad 렌더 확인, tests/test_model3d.py (STEP 참조 무결성 · 면 방향 · 각인 배치).

0.4.2 — 다른 PC 에서 실행할 때의 환경 점검

요청: PCB Agent 와 Footprint Agent 를 다른 PC 에서 실행할 때 문제되는 점을 점검하고 보완.

추가

KiCad 탐색 · 버전 확인: C:~H:\Program Files\KiCad\<버전>, 사용자별 설치(%LOCALAPPDATA%\Programs\KiCad), PATH 까지 찾고 버전을 숫자로 비교해 가장 높은 것을 쓴다 (PCB Agent 와 같은 위치). kicad-cli version 으로 버전을 읽어 KiCad 9 미만이면 쓰지 않음.
KiCad 가 없거나 오래되었으면 KiCad 검증을 생략하고 검증 탭에 kicad.skip 경고로 표시 (이전에는 kicad-cli 를 못 찾아도 아무 표시 없이 통과).
Claude CLI 점검: 설치 · --json-schema 지원(--help 로 확인) · 로그인(claude auth status). 문제가 있으면 작업 시작 전에 한국어 안내.
브리지 버전: /api/status 에 version, 화면의 PAGE_VERSION 과 비교해 브리지가 오래되면 git pull 안내 배너.
화면 위 환경 경고 배너(KiCad · Claude · 브리지 버전)와 「다시 확인」, 상단 칩에 KiCad 버전 · 브리지 버전 표시.
점검은 시작할 때 백그라운드로 미리 하고 5분 캐시 — /api/status 가 막히지 않는다 (kicad-cli version 첫 실행 약 14초).
run.py: Python 3.10 미만 · 패키지 누락이면 고치는 방법(설치할 Python 경로 포함)을 출력. start.bat: python 이 3.10 미만이면 py -3 사용.
README 「다른 PC 에서 실행」 절, 테스트 tests/test_env_checks.py (버전 일치, KiCad 8 이면 검증 생략).

수정

start.bat 을 ASCII 로만 작성 — cmd 가 UTF-8 한글 줄 뒤의 줄을 잘못 읽어 Python 을 찾지 못하던 문제.
0.2.0 때의 설명 정정: ~/.local/bin 의 2.1.63 도 --json-schema 를 지원한다. 그래서 버전 번호 대신 --help 로 지원 여부를 확인한다.

0.4.1 — 사용법 메뉴에 개발 · 수정 이력 표시

요청: 개발 · 수정 이력을 사용법 메뉴에 추가.

「사용법」 페이지 아래에 개발 · 수정 이력 카드 추가 — 버전별 접기(최신 버전만 펼침), 머리의 「개발 · 수정 이력 ↓」 · 「맨 위로 ↑」 이동 버튼.
원본은 CHANGELOG.md 하나. irodmas.com 은 static/ 만 복사하므로 tools/sync_changelog.py 가 Markdown 을 HTML 로 바꿔 static/index.html 의 표시 사이에 넣는다.
tests/test_changelog.py: CHANGELOG.md 를 고치고 반영을 잊으면 실패.

0.4.0 — 폴더 일괄 생성 (96bb45d)

요청: 폴더를 지정해 저장되어 있는 데이터시트들의 풋프린트를 한 번에 만들기.

추가

화면 왼쪽 위 단일 부품 / 폴더 일괄 전환. 폴더 경로 입력 또는 찾아보기(브리지가 이 PC 의 드라이브 · 폴더 목록 제공), 하위 폴더 포함.
PDF 찾기: PDF 목록과 크기, 이미 라이브러리에 있는 데이터시트 표시(파일 SHA-1 비교) — 기본으로 선택 해제.
일괄 큐: 동시 처리 1~3개, 이미 저장된 데이터시트 건너뛰기, 중지(진행 중인 파일은 끝까지 처리).
진행 표: 파일별 단계 · 결과(저장됨 / 검토 필요 / 실패 / 건너뜀), 행을 누르면 해당 부품 결과가 아래에 열림. 작업 기록에 일괄 작업 표시. ?batch=<id> 로 진행 표 바로 열기.
추출 프롬프트에 파일 이름을 부품 번호 단서로 전달 (문헌 번호 등 임의 이름일 수 있으므로 데이터시트로 확인될 때만 사용).
저장 기록(library/specs/*.json)에 datasheet_sha1 추가. 이전 저장분은 library/datasheets/*.pdf 의 해시로 인식.
API: GET /api/fs/dirs, POST /api/batch/scan, POST /api/batch, GET /api/batch/{id}, POST /api/batch/{id}/stop, GET /api/batches.

수정

여러 작업이 같은 심볼 라이브러리를 동시에 병합하지 않도록 저장을 잠금으로 직렬화.
드라이브 목록이 7초 걸리던 문제(네트워크 드라이브 접근) → GetLogicalDrives 비트마스크로 즉시 표시.
패드 피치 검사 오경고: SOT-23-5(3+2 배치)처럼 빈 자리가 있는 패키지에서 경고 → 가장 가까운 패드 간격이 피치와 같은지로 판단.
라이브러리 목록의 긴 이름이 가로 스크롤을 만들던 문제.

검증

실제 TI 데이터시트 3개 폴더, 동시 2: LM358DR 건너뜀(이미 저장), SN74LVC1G14DBVR(SOT-23-5, 1 NC · 2 A · 3 GND · 4 Y · 5 VCC) · TPS62130RGT(VQFN-16 3×3 + EP 17) 모두 AI 검토 통과 · 저장. 핀 대응은 데이터시트 핀 표와 일치.
예제 6종 회귀 테스트 통과.

0.3.1 — 결과 바로 열기 (2be6411)

?job=<id> 로 특정 작업 결과를 바로 연다 (대문 캡처 · 공유용).
메뉴 전환 때 주소의 쿼리 문자열이 지워지던 문제 수정.

0.3.0 — irodmas.com 배포 (c72b6de)

요청: irodmas.com 에 배포.

irodmas.com 은 정적 파일만 서비스하므로 webCadAgent 와 같은 구조로 바꿨다 — 웹 화면은 irodmas.com, KiCad · Claude 는 사용자 PC 의 로컬 브리지에서 실행.

로컬 브리지 run.py / start.bat (기본 127.0.0.1:8766, --port, --no-open).
보안: 허용된 Origin(irodmas.com · www · samcho93.github.io · localhost)만 응답, 로컬 Host 만 처리(DNS 리바인딩 방지), Chrome 사설망 접근(Access-Control-Allow-Private-Network) 헤더.
웹 화면: 브리지 주소 자동 선택(로컬은 같은 주소, 외부는 저장된 브리지 주소) · ⚙ 로 변경, 연결 안 됨 안내 배너, 정적 경로를 상대 경로로.
GitHub 저장소 생성(공개, MIT) · GitHub Pages 켬, 루트 index.html → static/ 이동.
SamStudy 허브 등록 samcho93/SamStudy#89: Tools 카드(webfootprintagent, root: static) · 소개 글 · 960×600 대문 캡처. 허브 빌드(build.mjs)와 빌드 결과에서 브리지 연결 확인 후 머지.
남은 일(관리자): 「강좌 다시 가져오기」, 강좌 탭에서 공개 · 무료/유료 · 속성 지정.

0.2.0 — Claude Code CLI 연동 (c72b6de)

요청: API 키 없이 Claude CLI 로 webCadAgent 처럼 사용.

app/agents/claude_cli.py: 로그인된 claude CLI 를 헤드리스로 실행 (claude -p --output-format stream-json --json-schema …). PDF 는 임시 폴더에 두고 Read 도구로 읽기, 검색은 WebSearch · WebFetch, 결과는 structured_output.
백엔드 자동 선택: ANTHROPIC_API_KEY 가 있으면 API, 없으면 CLI. FP_AGENT_BACKEND=api|cli 로 강제.
서버가 시작할 때 프로젝트 .env 를 직접 읽음. 상단 칩에 「Claude CLI 연결」 표시.
CLI 탐색은 셸과 같은 PATH 순서 (~/.local/bin 의 오래된 2.1.63 대신 npm 의 2.1.287 사용).

수정

구조화 출력 스키마 버그: 스키마 변환이 title 키를 모두 지워 title 이라는 실제 필드까지 사라짐 → 데이터시트 검색이 실패. 속성 이름 맵은 건드리지 않도록 고침 (API 경로에도 같은 영향이 있었음).
패드 사이에 짧은 실크 조각이 남던 문제 → 외곽 모서리에 이어진 실크만 남김.

검증

LM358DR 전체 파이프라인(API 키 없음, 약 2.3분): TI 공식 데이터시트 검색 → 68쪽 중 24쪽 선택 → SOIC-8(D0008A) 추출, 핀 1~8 TI 핀 표와 일치, 패드는 TI 권장 랜드 패턴(1.55×0.6 mm, 열 간격 5.4 mm) 그대로 → 규칙 검증 0 오류 · kicad-cli 통과 · AI 검토 pass → 자동 저장.

0.1.0 — 초기 개발 (c72b6de)

요청: 데이터시트를 열거나 링크로 연결해 핀 · 풋프린트 정보를 인식하여 KiCad 회로 기호 · 풋프린트를 자동 제작. 데이터시트가 없으면 에이전트가 찾아서 제작 → 검토 → 검증 → 저장.

구성

데이터 모델 (app/models.py): 모든 단계가 주고받는 PartSpec(핀, 패키지 치수, 랜드 패턴, 근거 페이지), 검토 결과, 검색 결과.
KiCad 9 생성기

회로 기호(symbol.py): 전원 위 · GND 아래 · 입력 왼쪽 · 출력 오른쪽 자동 배치, 100 mil 격자, 기능 그룹 정렬, Footprint · Datasheet 필드 연결.
풋프린트(footprint.py): 패키지 유형 9종(걸윙 2열/4면, 노리드 2열/4면, 칩 2단자, DIP, 핀 헤더, BGA, 좌표 직접 지정). 데이터시트 권장 랜드 패턴 우선, 없으면 IPC-7351B Nominal 근사식. EP 페이스트 분할, 실크(패드 회피) · 팹(1번 핀 모따기) · 코트야드.
라이브러리 저장(library.py): 심볼 라이브러리 병합(같은 이름 교체), .pretty, 사양 · 검증 · 검토 기록 JSON, 데이터시트 사본, sym-lib-table · fp-lib-table.

검증 (verify.py): 핀 번호 중복, 격자, 심볼 ↔ 패드 1:1 대응, 패드 겹침 · 간격, 피치, 코트야드 포함, 애뉼러 링, 치수 상식 검사 + kicad-cli 로 실제 파싱 · 렌더링.
Claude 에이전트: 데이터시트 웹 검색(finder.py), 추출 · 독립 검토(extractor.py), 호출 래퍼(llm.py — 스트리밍, JSON 스키마 출력, 거절 시 대체 모델). 검토에서 오류가 나오면 수정 사양으로 재생성(최대 2회), 끝까지 통과하지 못하면 「검토 필요」.
데이터시트 처리 (datasheet.py): 다운로드(HTML 이면 PDF 링크 추적), 키워드 점수로 관련 페이지 최대 24쪽 선택.
웹 화면 (FastAPI + 바닐라 JS, 한국어): 입력 폼(부품 번호 · 링크 · PDF 끌어놓기 · 패키지 지정), 단계 표시 · 진행 로그, 결과 탭(미리보기 · 핀 · 패드 · 검증 · AI 검토 · 사양 편집), 저장 · 강제 저장 · 다운로드, 작업 기록 · 라이브러리 목록.
메뉴: 「사용법」, 「파이프라인 구조」 페이지 (개발 중 요청으로 추가).

개발 중 수정

QFN 코너 패드 1–16 이 맞닿음(간격 0 mm) → 측면 패드 안쪽 끝을 잘라 코너 간섭 방지, 노리드 heel 0 으로 조정 (KiCad 기본 QFN-16 3×3 과 거의 같은 패드).
EP 축소 판정의 부동소수점 오차로 「1.7→1.7 축소」 메모가 나오던 문제.
kicad-cli 출력의 cp949 디코딩 오류(한글 Windows) → UTF-8 로 읽기.
kicad-cli sym export svg 가 필드 위치를 잘못 그려 미리보기를 자체 SVG 렌더러(preview.py, 핀 · 패드 번호 · 1번 핀 표시)로 교체하고, KiCad 렌더링은 체크박스로 비교.
hidden 속성이 grid 레이아웃에 덮여 메뉴 페이지가 겹치던 문제, 파이프라인 흐름도 줄바꿈.
API 키가 없을 때 원시 예외 대신 한국어 안내 메시지.

취소된 요청

「추가 사항」 입력 창과 「외곽 고정 홀」(홀 크기 · 외곽 간격 지정, 없으면 자동 추가) — 요청 후 취소되어 구현하지 않음.

검증

예제 6종(SOIC-8, QFN-16+EP, SOT-23-3, 0603, DIP-8, BGA) 생성 → 규칙 검증 오류 0 → kicad-cli 파싱 · 렌더링 통과 (tests/test_generators.py).
같은 라이브러리에 7번 저장 → 심볼 6개로 병합(중복 교체), 병합된 라이브러리 KiCad 에서 열림.

알려진 제한

한 데이터시트에서 대표 부품 · 패키지 하나만 만든다 (다른 변형은 단일 부품 모드의 「패키지 지정」으로 추가).
심볼은 단일 유닛 (듀얼 옵앰프 등 다중 유닛 분리는 하지 않음).
kicad-cli 검증이 호출당 10~40초 걸려 부품 하나에 AI 단계 외 약 1분이 더 든다.
3D 모델은 연결하지 않는다.
자동 생성 결과는 실제 보드에 쓰기 전에 1번 핀 위치 · 패드 번호 방향 · EP 번호 · 극성을 데이터시트와 대조해야 한다.

에이전트 파이프라인 구조

AI 단계(보라)는 Claude 가, 결정론적 단계(초록)는 코드가 수행합니다. 모든 단계는 하나의 PartSpec(부품 사양 JSON)을 주고받습니다.

입력PDF · 링크 · 부품 번호

→

① 자료 확보업로드/다운로드
없으면 웹 검색 에이전트

→

② 페이지 선별핀 표·패키지 도면·
권장 랜드 패턴 페이지

→

③ 추출핀 · 패키지 치수 →
PartSpec

→

④ 생성.kicad_sym
.kicad_mod (IPC-7351)

→

⑤ 검증규칙 검사 +
kicad-cli 파싱

→

⑥ AI 검토데이터시트와
교차 대조

→

⑥-2 3D 모델도면 판독 → STEP
렌더 대조 검토

→

⑦ 저장라이브러리 +
근거 기록

↺ ⑥ 에서 오류가 발견되면 검토 에이전트의 수정 사양으로 ④ → ⑤ → ⑥ 을 다시 수행합니다 (기본 최대 2회). 끝까지 통과하지 못하면 검토 필요 상태로 사람에게 넘깁니다.

단계	수행	하는 일	산출물
① 자료 확보	코드 / Claude (web_search·web_fetch)	업로드 PDF 사용, 링크 다운로드(HTML 이면 PDF 링크 추적). 둘 다 없으면 제조사 공식 사이트 우선으로 후보 URL 을 찾고 차례로 내려받기 시도	datasheet.pdf
② 페이지 선별	코드 (PyMuPDF)	키워드 점수(pin description, package outline, land pattern…)로 최대 24쪽 선택, 표지·마지막 도면 페이지 보강	부분 PDF + 원본 페이지 번호
③ 추출	Claude (구조화 출력)	주문 코드에 맞는 패키지 선택, 핀 번호·이름·전기적 타입, 치수 min/max, 권장 랜드 패턴(있으면 패드 좌표), 근거 페이지 기록	PartSpec JSON
④ 생성	코드	심볼: 전원 위/GND 아래/입력 왼쪽/출력 오른쪽 자동 배치, 100 mil 격자. 풋프린트: 패키지 유형별 IPC-7351B Nominal 계산, 코너 간섭·EP 간격 자동 보정, EP 페이스트 분할, 실크/팹/코트야드	.kicad_sym, .kicad_mod
⑤ 검증	코드 + kicad-cli	핀 번호 중복, 심볼↔패드 1:1 대응, 패드 겹침/간격, 피치 일치, 코트야드 포함, 애뉼러 링, 치수 상식 검사, KiCad 파싱·렌더링	검증 리포트
⑥ AI 검토	Claude (독립 검토자)	“틀렸다고 가정하고” 데이터시트와 항목별 대조. 오류가 있으면 수정된 전체 사양 제시	판정 · 지적 사항 · 수정 사양
⑥-2 3D 모델	Claude + 코드 + kicad-cli	패키지 도면에서 몸체 두께 · 띄움 · 리드 두께/모양 · 윗모서리 경사 · 색 · 각인(Device Marking) 판독 → 다면체 조합으로 STEP(색 포함) 생성 · 획 글꼴로 각인 → 작은 보드에 놓고 `kicad-cli pcb render` → 그림을 도면과 대조 검토, 틀리면 수정해 다시	.step (풋프린트에 연결)
⑦ 저장	코드	심볼 라이브러리에 병합(같은 이름 교체), 풋프린트 파일, 사양·검증·검토 기록 JSON(데이터시트 SHA-1 포함), 데이터시트 사본, lib-table 생성	library/
폴더 일괄	코드	폴더의 PDF 를 큐에 넣고 동시 처리 수만큼 ①~⑦ 을 반복. 데이터시트 SHA-1 로 이미 저장된 파일은 건너뛰고, 라이브러리 병합은 잠금으로 한 번에 하나씩 기록	파일별 결과 표

구성 파일

`app/pipeline.py`	작업 관리와 단계 오케스트레이션 (검토 반복 루프, 폴더 일괄 큐 포함)
`app/agents/finder.py`	데이터시트 웹 검색 에이전트
`app/agents/extractor.py`	추출 · 검토 에이전트 프롬프트
`app/agents/llm.py`	Claude 호출 — API(스트리밍, JSON 스키마 출력, 거절 시 대체 모델) 또는 CLI 백엔드 선택
`app/agents/claude_cli.py`	Claude Code CLI 헤드리스 실행 (`claude -p --json-schema`, API 키 불필요)
`app/datasheet.py`	다운로드, 관련 페이지 선별
`app/kicad/symbol.py` · `footprint.py`	KiCad 9 형식 생성기
`app/kicad/model3d.py` · `marking.py` · `render3d.py`	3D 형상 · STEP 출력 · 각인 글꼴 · KiCad 렌더
`app/agents/model3d_agent.py`	도면 판독 · 3D 렌더 대조 검토 프롬프트
`app/kicad/verify.py` · `preview.py` · `library.py`	검증 · 미리보기 · 저장