PCB Agent 가이드

1. 한눈에 보기

KiCad 프로젝트 폴더를 지정하면 회로도에서 넷리스트를 뽑아 PCB 외곽 · 레이어 · 부품 배치를 만든 .kicad_pcb 를 같은 폴더에 저장하고, KiCad 3D 렌더링과 배치 정보 · DRC 결과를 보여 줍니다. 결과가 마음에 들지 않으면 아래 터미널에서 Claude Code CLI 에게 말로 고쳐 달라고 합니다.

입력 · KiCad 프로젝트(.kicad_pro / .kicad_sch) 입력 · 외곽(프리셋 / DXF) · 레이어 수 입력 · Datasheet 폴더(선택) 입력 · 외곽 고정 홀 · 추가 사항(선택) 출력 · 배치된 .kicad_pcb 출력 · Top / 3D / Bottom 렌더 출력 · 보고서 · DRC · BOM

왜 로컬 브리지가 필요한가요? 웹 페이지는 보안상 내 PC 의 프로그램(KiCad, Claude CLI)을 직접 실행할 수 없습니다. 그래서 PC 에서 작은 Node 서버(브리지)를 켜 두고, 웹 화면은 http://127.0.0.1:8765 의 브리지에게 일을 시킵니다.

2. 구조

세 층으로 나뉩니다. 웹 화면은 어디서 열든(irodmas.com · GitHub Pages · localhost) 같은 파일이고, 실제 작업은 모두 PC 의 브리지와 KiCad 에서 일어납니다.

웹 화면

상태를 갖지 않는 정적 페이지. 외곽(프리셋 · DXF)은 브라우저에서 {primitives, loops} 로 계산해 보냅니다. 마지막 폴더 · 외곽 설정은 브라우저와 프로젝트의 pcb-agent/settings.json 에 기억합니다.

로컬 브리지

KiCad 설치 위치와 claude 실행 파일을 찾고, 요청마다 KiCad 도구를 실행합니다. 진행 로그와 Claude 출력은 SSE(/api/events)로 실시간 전달합니다.

Footprint Agent

별도 저장소 webFootprintAgent(FastAPI, 포트 8766). 데이터시트로 KiCad 심볼 · 풋프린트를 만드는 에이전트로, PCB Agent 브리지가 API 로 호출해 없는 풋프린트를 채웁니다.

배치 엔진

KiCad 에 들어 있는 Python 으로 실행되어 pcbnew API 로 풋프린트를 불러오고 보드를 만듭니다. 결과는 JSON 보고서로 남깁니다.

3. 배치 파이프라인

⚡ 배치 실행을 누르면 아래 순서로 진행되고, 각 단계의 진행 상황이 로그 탭에 실시간으로 찍힙니다.

웹입력 정리
외곽 프리셋 치수 또는 DXF 를 해석해 Edge.Cuts 용 선 · 호 · 원과 닫힌 외곽 다각형(내부 컷아웃 포함)을 만듭니다.
브리지작업 파일 작성
pcb-agent/settings.json(다음에 복원)과 job.json(엔진 입력)을 쓰고, “고정 부품 유지”를 끄면 overrides.json 을 비웁니다.
kicad-cli넷리스트 추출
sch export netlist 로 계층 회로도 전체의 부품(ref · 값 · 풋프린트 · 데이터시트 · 시트)과 넷을 얻습니다.
엔진풋프린트 로드
pcb-agent/footprints.json 의 대체 풋프린트(Footprint Agent 가 만든 것)를 회로도 값보다 먼저 쓰고, 전역 · 프로젝트 fp-lib-table 과 ${KICAD9_FOOTPRINT_DIR} 등 경로 변수를 풀어 라이브러리에서 풋프린트를 불러오고, 패드마다 넷을 연결합니다. 없는 풋프린트는 보고서에 표시합니다.
엔진보드 · 외곽 · 레이어
Edge.Cuts 를 그리고 동박 레이어 수를 설정합니다(4층 이상은 내층 이름 GND / PWR …).
엔진외곽 고정 홀
직접 지정이면 크기 · 간격 · 배치대로, 자동이면 회로도의 홀 부품을 모서리에 놓거나(있을 때) 보드 크기에 맞는 홀을 새로 만들어 고정합니다. 다른 부품은 이 자리를 피해 배치됩니다. 자세히
엔진배치 참고 페이지 찾기
시트 이름 · 파일 · 제목에 placement · replacement · 배치 · layout · floorplan 이 있으면 그 페이지의 심볼 · 부품 이름 텍스트 위치를 보드 좌표로 옮겨 “목표 위치”로 씁니다.
엔진배치
고정 부품(overrides) → 마운팅 홀 → 커넥터(가장자리) → IC → 수동 소자 → 반복 개선. 자세한 방법은 4장.
엔진실크 정리 · 저장
부품 이름을 겹치지 않는 옆자리로 옮기고, 임시 폴더에 저장한 뒤 프로젝트 폴더로 복사합니다(기존 파일은 backups/, .kicad_pro 는 건드리지 않음).
엔진보드 분석
저장된 보드를 다시 읽어 크기 · 면적 · 부품 · 패드 · 넷 · 래츠네스트(MST) 길이 · 밀도 · 겹침 · 외곽 밖 부품을 report.json 에 씁니다.
kicad-cli렌더링 · DRC (동시에)
pcb render top / bottom / iso PNG, 앞면 레이어 SVG, pcb drc --schematic-parity 를 병렬로 실행합니다.
웹결과 표시
Top 렌더, 2D 배치도(래츠네스트), 요약 카드, 부품 · 넷 · DRC 표를 그립니다.
웹추가 사항 반영 (선택)
“추가 사항”이 있고 “배치가 끝나면 Claude 가 반영”이 켜져 있으면 그 내용을 Claude 에게 자동으로 보냅니다 → 5장의 수정 루프로 이어집니다.

“다시 분석” 버튼은 8~11 단계만 실행합니다 — KiCad 에서 직접 고친 보드를 확인할 때 씁니다.

4. 자동 배치 알고리즘

배치는 “연결된 부품끼리 가깝게, 커넥터는 가장자리에, 겹치지 않게”를 목표로 하는 그리디 배치 + 반복 개선입니다. 20개 부품 기준 1초 남짓 걸립니다.

부품 분류

hole — H, MH, MountingHole → 보드 모서리
connector — J, P, CN, USB, Connector 라이브러리 → 가장자리
ic — U, IC, Q, Y, Module, Package → 먼저, 크기 · 연결 순
passive — R, C, L, D, SW … → 연결된 부품 옆

크기

각 풋프린트의 코트야드(없으면 텍스트 제외 외곽) 상자를 0 · 90 · 180 · 270° 에서 미리 재 둡니다. 부품 사이에는 “부품 간격”, 외곽과는 “가장자리 여유”를 둡니다.

위치 비용

비용 = Σ_넷 w · 거리 + 0.08 · (보드 중심까지 거리) [+ 참고 위치까지 거리]

작은 넷: w = 1/(부품 수−1), 같은 넷 패드들의 무게중심까지 거리
큰 넷(GND · VCC · 3V3 …, 10핀 초과): w = 0.35, 가장 가까운 IC 핀까지 거리 → 디커플링 커패시터가 IC 전원 핀 옆으로
후보 위치는 연결된 부품들의 가중 중심에서 나선형으로 넓혀 가며, 들어갈 수 있는 첫 40곳 중 비용이 가장 낮은 곳

마운팅 홀을 모서리에.
주 IC를 보드 가운데에 임시로 놓습니다 — 커넥터가 IC 쪽 가장자리를 고르게 하기 위해.
커넥터: 외곽을 따라 2 × 격자 간격마다 후보를 만들고, 긴 변이 가장자리와 나란하고 결합면(패드 중심 → 몸체 중심 방향)이 바깥을 보는 회전만 허용, 가장자리에 붙여 놓습니다. 커넥터끼리는 서로 밀어냅니다.
주 IC 를 들어 올린 뒤 IC 를 크기 × 연결 수 순서로, 이어서 나머지를 “이미 놓인 부품과 연결이 많은 순서”로 놓습니다.
반복 개선(2회): 작은 부품부터 하나씩 빼서 다시 찾아보고, 비용이 줄면 옮깁니다.
못 넣은 부품은 (옵션) 뒷면, 그래도 안 되면 보드 오른쪽 밖에 나열하고 보고서의 “확인 필요”에 표시합니다.
실크: 부품 이름의 실제 글자 상자를 재서 위 · 아래 · 좌 · 우 · 세로 중 비어 있는 곳에 놓고, 자리가 없으면 Fab 레이어로 옮겨 실크 DRC 를 피합니다.

외곽 고정 홀

자동 (기본)	회로도에 마운팅 홀 부품(H · MH · MountingHole)이 있으면 그 부품을 모서리에 놓습니다. 없으면 에이전트가 추가합니다: 짧은 변 30 mm 미만 M2 (Ø2.2), 60 mm 미만 M2.5 (Ø2.7), 그 이상 M3 (Ø3.2) · 킵아웃 Ø4 / 5 / 6 mm · NPTH, 외곽 → 홀 중심 간격 = 킵아웃 반지름 + 1 mm(가장자리 여유가 더 크면 그 값), 25 mm 미만 보드는 대각선 2개 · 그 외 네 모서리 4개. 짧은 변이 간격의 4배보다 작으면 넣지 않고 경고합니다.
직접 지정	홀 크기(M2 ~ M5 또는 드릴 지름), 패드 · 킵아웃 지름, 외곽에서 홀 중심까지 간격, 배치(네 모서리 · 대각선 2개 · 모서리 + 긴 변 가운데 6개 · 좌표 직접 입력), 도금(PTH) 여부와 GND 연결. 빈 칸은 자동 값.
추가 안 함	새 홀을 만들지 않습니다 (회로도의 홀 부품은 모서리에 배치).

홀 위치는 보드 외곽 상자의 모서리(또는 변 가운데)에서 안쪽으로 걸어 들어가며 “보드 안이고 모든 외곽선 · 컷아웃에서 지정 간격 이상 떨어진” 첫 지점으로 정합니다 — 둥근 모서리 · 원형 · DXF 외곽에서도 같은 간격이 지켜집니다.
추가된 홀은 보드 전용 풋프린트(H1, H2 …, BOM · 위치 파일 제외)라서 회로도와 불일치 DRC 가 나지 않습니다. 도금 홀은 GND 넷에 연결할 수 있습니다.
홀은 배치 전에 고정되므로 다른 부품이 홀 킵아웃을 피해 놓입니다. Claude 가 overrides.json 에 H 위치를 적으면 그 자리를 우선합니다.

배치 참고 페이지가 있을 때 — 참고 위치가 있는 부품은 그 점에서 탐색을 시작하고 거리 비용(가중 1.0, 커넥터는 3.0)을 더하므로 디자이너가 그린 배치를 따르되, 겹침과 외곽은 엔진이 해결합니다. 페이지의 다른 글(예: “안테나는 오른쪽 가장자리”)은 Claude 에게 전달됩니다.

배선은 다음 단계 4-1. 자동 배선에서 Freerouting 으로 합니다.

4-1. 자동 배선 (Freerouting)

배치가 끝난 보드를 Freerouting 으로 자동 배선합니다. 설정 패널 ⑧ 배선의 🔀 배선 실행, 또는 배치가 끝나면 자동으로 배선을 켜 두면 배치 직후 이어서 실행됩니다.

엔진DSN 내보내기
기존 트랙 · 비아를 지우고(“기존 트랙 유지”를 켜면 남은 연결만), 동박을 비운 보드를 기준으로 저장한 뒤 Specctra route.dsn 을 만듭니다. KiCad 9 의 DSN 내보내기가 일부 풋프린트 그림(예: Choke_Schaffner_RN102)에서 멈추는 문제가 있어, 내보내기용 사본에서만 풋프린트 그림(선 · 호 · 문자)을 빼고 패드 · 외곽 · 존만 넘깁니다.
Freerouting1단계: 배선
Java 21+ 로 Freerouting 을 창 없이 실행합니다 (최대 배선 패스). 패스마다 미배선 · 위반 수가 작업 중 표시와 로그에 나옵니다.
Freerouting2단계: 최적화 (선택)
남은 시간 안에 최적화(길이 · 비아 줄이기)를 포함해 다시 실행하고, 끝나면 그 결과를 씁니다. 시간 제한에 걸리면 1단계 결과를 그대로 씁니다 — 큰 보드는 최적화 한 패스가 몇 분씩 걸리기 때문입니다.
엔진SES 가져오기
route.ses 를 기준 보드에 가져오고, 보드 최소 폭보다 좁은 트랙은 최소 폭으로 맞춥니다. GND 동박이 있으면 스티칭 비아(격자 + 끊어진 동박 섬마다 하나)를 넣고 동박을 채운 뒤 저장합니다 (이전 파일은 backups/).
kicad-cli렌더 · DRC
배선된 보드를 다시 렌더링하고 DRC 를 실행합니다. 요약에 트랙 수 · 길이 · 비아 · 미배선 연결 · Freerouting 시간과 패스가 표시됩니다.

필요한 것	Java 21 이상(예: Adoptium, 또는 `FREEROUTING_JAVA`), `freerouting-x.y.z.jar` (webCadAgent/tools/, 옆 PCB/tools/, ~/freerouting, 다운로드 폴더에서 찾음, 또는 `FREEROUTING_JAR`). 브리지 시작 시 확인해 ⑧ 배선에 표시합니다.
최대 배선 패스	기본 50. 미배선이 남으면 늘려 보세요.
시간 제한	기본 15분. 1단계가 이 안에 끝나지 않으면 결과가 없습니다 (Freerouting 은 끝날 때만 결과를 씁니다).
중지	1단계 중이면 배선 취소, 2단계(최적화) 중이면 1단계 결과로 마무리합니다.

예: ESP32-C3 보드(부품 24개) — 8패스 만에 미배선 0, 트랙 272개 · 비아 18개, Freerouting 57초. CoffeeMachine(부품 121개 · 미배선 165개) — 약 2분에 미배선 0, 최적화 1패스가 약 6분.

배치를 다시 실행하면 보드가 새로 만들어져 배선이 지워집니다. 배치를 확정한 뒤 배선하세요. 자동 배선 결과도 고속 · 전원 · 아날로그 경로는 KiCad 에서 확인 · 수정하는 것이 좋습니다.

4-2. 메탈 PCB (알루미늄 MCPCB)

설정 ④ 기판 종류에서 메탈 PCB를 고르면 단면 금속 기판 규칙으로 배치 · 배선합니다. LED · 전원 모듈처럼 열을 빼야 하는 보드에 씁니다.

옵션	베이스 금속(알루미늄 · 구리) · 두께(1.0 ~ 3.0 mm) · 동박(1 ~ 3 oz) · 절연층 열전도율(1.0 ~ 3.0 W/mK) · 외곽 → 동박 최소 거리(기본 1.0 mm)
배치	동박 레이어 1층(윗면)으로 고정, 부품은 윗면만(뒷면 배치 끔), 가장자리 여유는 최소 거리 이상, 고정 홀은 비도금(NPTH) — 도금 홀은 알루미늄 베이스와 닿기 때문. 스루홀 부품이 있으면 “절연 홀 가공 필요” 경고
배선	B.Cu 전체를 배선 · 비아 금지 영역으로 내보내 F.Cu 만, 비아 없이 배선. GND 동박은 F.Cu 만, 스티칭 비아 없음. 단면으로 연결하지 못한 곳은 요약에 표시 — 0Ω 점퍼나 배치 · 핀 배정 변경으로 해결
보드 · 제조	보드 두께 = 베이스 + 절연층(약 0.1 mm) + 동박. User.Comments 레이어에 제조 메모(베이스 · 두께 · 열전도율 · 비도금 · 가장자리 거리 · 마감), 보드 Plot 설정은 F.Cu · F.Mask · F.Paste · F.Silkscreen · Edge.Cuts 만 → 거버도 앞면 레이어만 나옵니다.

예: ESP32 보드를 메탈(알루미늄 1.5 mm · 2.0 W/mK)로 — 두께 1.635 mm, 고정 홀 비도금, 단면 배선 트랙 203개 · 비아 0, 미연결 6곳(점퍼 필요).

4-3. 제조 파일 (거버)

설정 ⑨ 📦 거버 생성은 만들어진 PCB 파일을 기준으로 브리지된 KiCad(kicad-cli)가 제조 파일을 만듭니다. PCB Agent 는 직접 파일을 만들지 않고, KiCad 가 만든 결과를 ZIP 으로 묶고 미리보기만 보여 줍니다.

거버	`pcb export gerbers --board-plot-params` — KiCad PCB 편집기의 Plot 설정(레이어 · 옵션)을 그대로 사용. 배치 엔진이 일반 기판은 앞 · 뒤 레이어 전체, 메탈 PCB 는 앞면 레이어만 Plot 설정에 넣어 둡니다. 바꾸려면 KiCad 에서 Plot 설정을 고치면 됩니다. Gerber 작업 파일(.gbrjob) 포함
드릴	`pcb export drill` Excellon(mm), PTH · NPTH 분리, (선택) 드릴 맵 Gerber X2
부품 위치	`pcb export pos` CSV(mm), 양면(메탈은 앞면), DNP 제외
BOM	`sch export bom` — 회로도 기준 KiCad BOM, 값 · 풋프린트로 묶음
결과	프로젝트의 `fabrication/<보드>-<시각>/` 와 같은 이름의 ZIP. ⬇ ZIP 받기, webGerber 에서 보기(samcho93.github.io/webGerber 가 브리지에서 ZIP 을 받아 실사 렌더링), 제조 미리보기 탭(앞면 · 뒷면 미러, 확대 · 이동). DRC 오류나 미배선이 있으면 경고

5. Claude 수정 루프

Claude 는 프로젝트 폴더를 작업 폴더로, Datasheet 폴더와 엔진 폴더를 추가 폴더로 받아 실행됩니다 (파일 수정 허용 · Bash/Read/Edit/Write 등).
시스템 프롬프트로 KiCad 경로, 보드 파일, 데이터시트 매칭, 현재 부품 위치표, 수정 방법이 전달됩니다:
1. 배치 변경: pcb-agent/overrides.json 에 {"U1": {"x":…, "y":…, "rot":90, "side":"F"}} 를 쓰고 엔진을 다시 실행 → 고정 부품 주변으로 나머지를 다시 배치
2. 그 밖의 수정(동박 · 킵아웃 · 넷 클래스 · 텍스트 …): pcbnew Python 스크립트로 직접
3. 외곽 · 레이어 변경: job.json 을 고쳐 다시 실행
추가 사항: 설정 패널 ⑥ 에 적은 요구 사항은 배치 직후 자동으로 Claude 에게 전달되고(옵션), 이후 모든 대화의 시스템 프롬프트에 “계속 지켜야 할 조건”으로 들어갑니다. Claude 는 반영한 것과 못 한 것(이유)을 정리해 답합니다.
Claude 가 끝났을 때 보드 파일 수정 시각이 바뀌었으면 브리지가 자동으로 다시 분석 · 렌더링합니다.
같은 프로젝트에서는 대화가 이어집니다. 새 세션으로 처음부터, ■ 중지로 작업을 멈춥니다. 비용 · 턴 수는 작업이 끝나면 표시됩니다.

5-1. Footprint Agent 연동

회로도의 Footprint 필드가 비어 있거나, 지정한 라이브러리에 풋프린트가 없으면 배치할 수 없습니다. 이런 부품은 풋프린트 탭에서 먼저 KiCad 라이브러리에서 찾고, 맞는 것이 없을 때만 webFootprintAgent 로 데이터시트에서 만듭니다.

라이브러리 우선 찾기

① 같은 이름	회로도가 이 PC 에 없는 라이브러리를 가리키면, 같은 이름의 풋프린트를 다른 라이브러리에서 찾습니다 (점수 100).
② 이미 만든 부품	Footprint Agent 라이브러리에 같은 부품 번호로 저장된 풋프린트가 있고 패드 수가 맞으면 프로젝트로 복사해 씁니다 (점수 95).
③ 심볼 필터	심볼의 풋프린트 필터(`R_`, `Connector:_1x??_`, `SOT?23`, `TSSOP3x3mm` …)에 맞고 패드 수가 핀 수와 같은* 풋프린트를 설치된 KiCad 라이브러리 전체(약 1만 4천 개)에서 고릅니다. 필터가 없으면 값 · 설명의 패키지 이름(SOIC-8, TO-220 …)으로 찾습니다.
기본값	수동 소자 기본 크기(0402 · 0603 · 0805 · 1206 · THT)와 커넥터 기본(핀 헤더 · 핀 소켓 2.54, JST XH 2.5, JST PH 2.0, 터미널 블록 5.08)으로 순위를 정합니다.
추천 / 확인 필요	앞의 규칙으로 분명히 정해지면 추천, 아니면 확인 필요. 정격이 큰 소자(2W 저항, 275VAC · 630V 콘덴서), 부품 번호가 있는 다이오드, “Fuse Holder” 같은 값, 후보가 비슷한 부품(전해 콘덴서 · 바리스터 · TO 패키지)은 기본 크기를 그대로 쓰지 않고 확인 필요로 둡니다.

자동 채우기

추천 후보가 있으면 바로 지정합니다 (footprints.json).
후보가 불확실한데 부품 번호가 있는 부품(SS14, MOC3052, K7805 …)과 후보가 전혀 없는 부품 → Footprint Agent 로 데이터시트를 찾아 생성합니다.
후보가 불확실하고 값만 있는 부품(470uF/16V, Fuse Holder …) → 확인 필요 목록. 행의 후보 목록에서 골라 적용.
값만으로 알 수 없고 후보도 없는 부품 → 직접 지정 (부품 번호 · 패키지 힌트를 넣고 생성).

예: CoffeeMachine 프로젝트(풋프린트 없는 부품 147개)에서 자동 채우기 한 번으로 97개가 라이브러리에서 지정되었고(2초), 17건은 확인 필요, 1건(MMBT2907)은 Footprint Agent 대상이었습니다.

Footprint Agent 로 만들기

3D 모델

Footprint Agent 는 풋프린트가 완성되면 데이터시트 패키지 도면(몸체 두께 · 띄움 · 리드 모양 · 각인)으로 3D 모델(STEP)을 만들어 함께 줍니다. PCB Agent 는 설치할 때 이 파일을 프로젝트의 AgentParts.3dshapes/ 로 복사하고 풋프린트를 ${KIPRJMOD}/AgentParts.3dshapes/<풋프린트>.step 으로 연결합니다. 보드에 이미 놓인 같은 부품에도 모델을 붙이고(엔진 models 모드) 3D 렌더 · 3D 보기(GLB)를 다시 그리므로, 배치를 다시 하지 않아도 3D 뷰에서 바로 보입니다. Footprint Agent 라이브러리에서 고른 풋프린트(점수 95)도 모델 파일을 같이 복사합니다.

Footprint Agent 브리지를 켭니다. webCadAgent 옆에 webFootprintAgent 를 clone 해 두면 풋프린트 탭의 시작 버튼으로 켤 수 있습니다 (또는 그 폴더에서 start.bat). 다른 위치는 FP_AGENT_DIR, 다른 주소는 FP_AGENT_URL.
프로젝트를 불러오면 풋프린트가 미지정이거나 라이브러리에 없음인 부품이 탭에 뜨고(탭 이름 옆 숫자), 같은 값 · 풋프린트의 부품은 한 줄로 묶입니다.
부품 번호(MPN 필드 → 값 순), 패키지 힌트(지정된 풋프린트 이름), 데이터시트(Datasheet 폴더에서 매칭된 PDF → 회로도의 링크 → 웹 검색)를 확인 · 수정하고 생성 (또는 자동 채우기).
진행 상황(데이터시트 확보 → 추출 → 생성 → 검증 → AI 검토)과 미리보기가 작업 카드에 표시됩니다. 통과하면 자동으로 프로젝트에 설치됩니다: <프로젝트>/AgentParts.pretty/ · AgentParts.kicad_sym, 프로젝트 fp-lib-table · sym-lib-table 에 ${KIPRJMOD} 경로로 등록, pcb-agent/footprints.json 에 {"U1": "AgentParts:…"}.
이 풋프린트로 다시 배치 를 누르면 고정 부품을 유지한 채 다시 배치합니다. 되돌리기 는 대체 풋프린트를 빼고 회로도 값으로 돌아갑니다.
결과가 확정되면 회로도에 반영 (부품 줄 · 작업 카드, 또는 매핑 모두 회로도에 반영) 을 누릅니다. 계층 회로도의 모든 시트에서 해당 레퍼런스의 심볼을 찾아 (property "Footprint" "…") 값만 AgentParts:… 로 바꾸고(나머지 서식은 그대로), 바꾼 .kicad_sch 는 먼저 pcb-agent/backups/sch-<시각>/ 에 백업한 뒤 footprints.json 에서 그 부품을 뺍니다. 이제 DRC 회로도 패리티의 footprint_symbol_mismatch 가 사라집니다. 여러 번 쓰인 시트에서 같은 심볼의 인스턴스들이 서로 다른 풋프린트로 매핑돼 있으면 바꾸지 않고 로그에 알려 줍니다. KiCad 회로도 편집기가 열려 있으면 먼저 닫으세요 (저장 시 덮어씁니다).

주의 — 회로도에 반영 전까지 대체 풋프린트는 회로도의 Footprint 필드를 바꾸지 않으므로 DRC 의 “회로도 불일치”에 표시됩니다. 자동 생성 결과는 1번 핀 위치 · 패드 번호 · 노출 패드를 데이터시트와 꼭 대조하세요.

6. 설치 · 실행

KiCad 9	`kicad-cli` 와 번들 Python(pcbnew)을 씁니다. KiCad 8 도 배치는 되지만 3D 렌더는 9 부터 (8 에서는 레이어 SVG 로 대체)
Node.js 18+	브리지 서버 (외부 패키지 없음)
Claude Code CLI	`npm i -g @anthropic-ai/claude-code` 설치 후 터미널에서 `claude` 로 한 번 로그인

git clone https://github.com/samcho93/webCadAgent
cd webCadAgent
node server/index.js          # Windows: start.bat 더블클릭

브라우저가 http://127.0.0.1:8765/ 로 열립니다. irodmas.com 화면에서 쓸 때는 오른쪽 위 연결 표시가 초록색이 되는지 확인하고, 브라우저가 “로컬 네트워크 접근”을 물으면 허용합니다.

`--port` / `PCB_AGENT_PORT`	포트 변경 (웹 화면 ⚙ 에서 브리지 주소도 변경)
`--no-open`	브라우저 자동 열기 끔
`KICAD_CLI` · `KICAD_PYTHON`	KiCad 를 기본 위치가 아닌 곳에 설치했을 때
`CLAUDE_CLI`	claude 실행 파일 경로
`PCB_AGENT_ORIGINS`	브리지를 쓸 수 있는 웹 주소 추가 (쉼표 구분)

7. 사용법 (메뉴별)

A. 설정 패널

PCB 외형

직사각형 · 정사각형 · 둥근 직사각형 · 원형 · 타원 · 육각형은 치수(mm)만 입력합니다. DXF 파일을 고르면 LINE · ARC · CIRCLE · LWPOLYLINE(bulge) · POLYLINE · ELLIPSE · SPLINE 을 읽어 닫힌 외곽과 내부 컷아웃을 만듭니다. 레이어가 여러 개면 쓸 레이어를 체크(이름에 outline · edge · board 가 있으면 자동 선택), 단위는 파일의 $INSUNITS 또는 직접 선택. 아래에 크기 · 면적이 표시되고 2D 배치도에 미리 보입니다.

레이어 · 배치 옵션

동박 레이어 — 기본 2층, 1 · 4 · 6 · 8층
배치 기준 — 자동(배치 페이지가 있으면 참고) / 배치 페이지 무시
가장자리 여유 · 부품 간격 — mm (기본 0.5 / 0.5)
뒷면 배치 — 공간이 모자랄 때 수동 소자를 B 면에
GND 동박 — GND 넷으로 F.Cu · B.Cu 존 추가
고정 부품 유지 — 켜면 overrides.json 의 부품 위치를 지키고, 끄면 비우고(이전 내용은 overrides.prev.json) 새로 배치
고품질 렌더링 — 느리지만 그림자 · 재질이 좋아짐

외곽 고정 홀

자동 · 직접 지정 · 추가 안 함 중에서 고릅니다. 직접 지정에서는

홀 크기 — M2 · M2.5 · M3 · M4 · M5 를 고르면 드릴 지름이 채워지고, 드릴 지름을 직접 입력할 수도 있습니다
패드 · 킵아웃 지름 — 도금 홀이면 동박 패드, 아니면 부품을 두지 않을 원 (빈 칸 = 나사 머리 기준 자동)
외곽 → 홀 중심 간격 — 보드 외곽선에서 홀 중심까지 (빈 칸 = 킵아웃 반지름 + 1 mm)
배치 — 네 모서리 / 대각선 2개 / 모서리 + 긴 변 가운데 6개 / 좌표 직접 입력(보드 왼쪽 위 기준 mm, 한 줄에 x, y)
도금 홀(PTH) · GND 연결

배치 후 아래에 실제로 넣은 홀 수 · 출처(에이전트 / 사용자 / 회로도) · 크기 · 좌표가 표시되고, 2D 배치도에는 원으로 그려집니다.

↺

기존 PCB 가 있을 때

프로젝트를 불러올 때 .kicad_pcb 가 있으면 먼저 그 보드를 표시하고(PCB Agent 로 만들지 않은 보드는 자동 분석 · 렌더링), 기존 PCB 수정 / 새로 배치 를 묻습니다. 수정 모드에서는 배치 · 배선을 유지한 채 2D 부품 이동 · 배선 · Claude · 거버 생성을 쓰고, “배치 실행”은 “새로 배치 (덮어쓰기)”로 바뀌어 확인 후에만 덮어씁니다. 위쪽 안내 막대에서 모드를 바꿀 수 있습니다.

B. 뷰

Top 렌더	KiCad 3D 레이트레이싱 Top 이미지 (기본 화면). 휠: 커서 위치 확대 · 드래그: 이동 · 더블클릭: 맞춤, 오른쪽 위 ＋／－／ ⤢ 버튼과 배율 표시
2D 배치도	외곽 · 코트야드 · 패드 · 래츠네스트. 휠 확대, 빈 곳 드래그로 화면 이동, 더블클릭 맞춤, ＋／－／ ⤢ 버튼, 부품 위에 올리면 정보, 클릭하면 부품 표에서 강조. 색: IC 진회색 · 수동 소자 갈색 · 커넥터 회청색 · 뒷면 파랑 ✥ 부품 이동: 부품을 드래그해 옮기기(격자 0.1 ~ 2.54 mm 맞춤, Shift 는 격자 없이), R 또는 ⟳ 로 90° 회전, 방향키로 미세 이동. 옮긴 부품은 점선, 다른 부품과 겹치거나 보드 밖이면 빨간색. 래츠네스트는 바로 다시 계산됩니다. 적용하면 보드 파일에 쓰고(다른 부품 · 배선은 그대로, 배선된 보드면 옮긴 부품의 트랙이 끊어지니 다시 배선) `overrides.json` 에 고정해 다시 배치해도 유지, 렌더 · DRC 다시 실행. 취소는 화면의 변경만 되돌립니다.
3D 보기	kicad-cli 로 내보낸 GLB(부품 3D 모델 · 트랙 · 패드 · 동박 · 실크 포함)를 브라우저에서 three.js 로 표시 — 드래그: 회전 · 오른쪽 드래그 / Shift+드래그: 이동 · 휠: 확대. 방향 버튼: 등각 · 윗면 · 아랫면 · 앞 · 뒤 · 왼쪽 · 오른쪽, 📷 현재 화면 PNG 저장, ↻ 다시 불러오기. 처음 열 때 GLB 를 만드느라 20초쯤 걸리고, 보드가 바뀌기 전까지는 다시 쓰입니다. (three.js 는 cdn.jsdelivr.net 에서 받습니다)
Bottom	뒷면 렌더 (Top 과 같은 확대 · 이동)
레이어 SVG	F.Cu · 실크 · Fab · 코트야드 · Edge.Cuts 2D 플롯 (KiCad 8 에서도 나옴, 확대 · 이동)
창 크기	설정 · 뷰 · 정보 · 터미널 사이의 경계선을 드래그해 크기를 바꿉니다 (더블클릭: 기본값). 크기는 브라우저에 기억됩니다. 좁은 화면(1280 px 이하)에서는 뷰와 정보 사이 경계선이 나타나고, 휴대폰 폭에서는 위아래로 쌓입니다.

C. 정보 탭

요약	보드 크기 · 면적 · 레이어 · 부품(윗면/뒷면, SMD/THT) · 패드 · 넷 · 래츠네스트 길이 · 미배선 · 겹침/외곽 밖 · DRC 위반, 부품 밀도 막대, 부품 종류, 배치 기준 · 설계 규칙 · 파일 경로 · 백업, “확인 필요” 목록, 보고서 JSON 저장
부품	ref · 값 · 풋프린트 · X · Y · 회전 · 면 · 크기 · 데이터시트(📄 로컬 / 🔗 웹). 검색 · 열 정렬, 행을 누르면 2D 배치도에서 강조, BOM CSV 저장(같은 값 · 풋프린트 묶음)
넷	넷별 패드 수 · 부품 수 · 래츠네스트 길이 (긴 순)
DRC	위반 · 오류 · 미연결(배선 전이라 정상) · 회로도 불일치, 종류별 묶음과 예시
풋프린트	Footprint Agent 연결 상태 · 시작, 수동 소자 · 커넥터 기본값, 자동 채우기(KiCad 라이브러리 → Footprint Agent), 풋프린트가 없는 부품 목록과 행마다 KiCad 라이브러리 후보 · 적용 · 생성, 생성 작업 진행 · 미리보기 · 설치 · 다시 배치 · 회로도에 반영 · 되돌리기 (5-1장)
회로도	시트 계층, 배치 참고 페이지 표시, 그 페이지에서 읽은 부품 수와 메모
데이터시트	부품 ↔ 파일 매칭 표, 폴더의 전체 파일 목록
로그	브리지 · 엔진 · 렌더 · DRC 진행 로그 (오류는 빨강)

D. Claude CLI 터미널

프로젝트를 불러오면 입력창이 열립니다. Enter 전송, Shift+Enter 줄바꿈. 위의 칩을 누르면 자주 쓰는 명령이 입력됩니다. 출력에는 Claude 의 답(실시간), 도구 사용(⏺ 노란색), 도구 결과(회색), 완료 시 턴 수 · 비용이 표시됩니다.

명령 예

USB 커넥터를 아래쪽 가장자리 가운데로 옮기고 나머지를 다시 배치해줘
ESP32 모듈 안테나가 보드 오른쪽 가장자리 밖을 향하도록 돌리고, 안테나 아래에는 부품을 두지 마
C1~C5 디커플링 커패시터를 각 IC 전원 핀에서 2 mm 안으로
데이터시트를 보고 레귤레이터 주변 레이아웃 권장 사항대로 배치해줘
보드를 50 × 40 mm 로 줄이고 4층으로 바꿔서 다시 배치
모서리에 M3 마운팅 홀 4개 추가
현재 배치를 검토하고 배선이 어려워 보이는 곳을 알려줘

배치 참고 페이지 만들기

회로도에 계층 시트를 하나 추가하고 이름을 placement (또는 배치)로 정합니다.
그 페이지에 보드 모양 비율대로 사각형을 그립니다 (보드 외곽 기준, 선택).
사각형 안의 원하는 자리에 부품 이름만 적은 텍스트(J1, U2, SW1 …)를 놓습니다. 심볼을 직접 배치해도 됩니다.
지켜야 할 조건은 문장으로 적어 둡니다 (예: “안테나는 오른쪽 가장자리”) — Claude 가 읽습니다.
프로젝트를 다시 불러오면 “배치 페이지: 있음”으로 표시되고, 배치 실행 시 그 위치를 따릅니다.

8. 파일 구조

저장소 (webCadAgent)

server/
  index.js     HTTP · SSE · API · 작업 잠금 · Claude 문맥
  kicad.js     KiCad 찾기 · 스캔 · 넷리스트 · 렌더 · DRC
  claude.js    claude -p stream-json 세션
python/
  pcb_agent.py 배치 엔진 · 보드 분석 (pcbnew)
web/
  index.html   작업 화면
  guide.html   이 가이드
  js/app.js    화면 동작 · 브리지 통신
  js/outline.js 외곽 프리셋 · DXF 파서
  js/board2d.js 2D 배치도 캔버스
start.bat · package.json · README.md

프로젝트 폴더에 생기는 것

<프로젝트>.kicad_pcb   배치된 보드
AgentParts.pretty/ · .kicad_sym  Footprint Agent 가 만든 부품
fp-lib-table · sym-lib-table  (AgentParts 등록)
pcb-agent/
  settings.json  마지막 외곽 · 레이어 · 옵션 · 홀 · 추가 사항
  footprints.json 대체 풋프린트 {ref: "AgentParts:…"}
  job.json       엔진 입력 (Claude 가 재실행)
  overrides.json 고정 부품 위치
  report.json    분석 보고서
  netlist.net    추출한 넷리스트
  route.dsn · route.ses · route_base.kicad_pcb  배선 중간 파일
  board.glb      3D 보기 모델
  render_top/bottom/iso.png
  top_layers.svg · drc.json
  backups/       덮어쓰기 전 PCB

엔진만 실행하기

"C:\Program Files\KiCad\9.0\bin\python.exe" python/pcb_agent.py <프로젝트>/pcb-agent/job.json

9. 브리지 API

GET /api/status	브리지 버전, KiCad · Claude 경로와 버전, 작업 중 여부
GET /api/events	SSE — `log` · `busy` · `claude`(start · delta · text · tool · tool_result · result · end) · `board`
GET /api/fs?path=	폴더 목록 (빈 값이면 드라이브 · 홈)
POST /api/project	`{dir}` → 프로젝트 · 시트 · 부품 · 배치 페이지 · 지난 결과
POST /api/datasheets	`{dir, projectDir}` → 파일 목록 · 부품 매칭
POST /api/place	`{projectDir, outline, outlineSpec, layers, placement, options, holes, requirements, pcbName, useOverrides, quality}` → `{report, images, drc}`
POST /api/analyze	`{projectDir}` → 현재 PCB 분석 · 렌더 · DRC
GET /api/image · /api/datasheet	렌더 이미지 · 데이터시트 파일 전달 (프로젝트의 pcb-agent / 매칭된 파일만)
GET /api/fp/status · POST /api/fp/start	Footprint Agent 상태 · 시작
POST /api/fp/candidates	`{projectDir}` → 부품별 풋프린트 상태(ok · agent · missing · none), 데이터시트 후보, 진행 중 작업
POST /api/fp/apply · autofill	라이브러리 풋프린트 지정 `{projectDir, refs, id, copyFrom?}` · 자동 채우기 `{projectDir, prefs: {passiveSize, connector}, aiReview, generate}` → applied · review · generating · manual
POST /api/fp/create · install · unmap	생성 요청 `{projectDir, refs, partNumber, packageHint, datasheetFile, datasheetUrl, aiReview}` · 설치(`{id, force}`) · 대체 해제
POST /api/fp/apply-schematic	`{projectDir, refs?}` → footprints.json 매핑을 회로도 Footprint 필드에 쓰고(백업 후) 매핑에서 제거. `{applied, skipped, backups, files}`
GET /api/route/status · POST /api/route · /api/route/stop	Java · Freerouting 확인, 자동 배선 `{projectDir, passes, timeoutMin, optimize, stitch, keepTracks}` → `{report, images, drc}`, 중지. 진행은 SSE `route` 이벤트
POST /api/fab · GET /api/fab-file	KiCad 로 제조 파일 생성 `{projectDir, options: {drillMap, pos, bom}}` → ZIP · 파일 목록 · 미리보기, fabrication 폴더의 파일 전달 (webGerber 가 이 주소로 ZIP 을 받음)
GET /api/glb · POST /api/move	3D 보기용 GLB (보드보다 오래되면 kicad-cli 로 다시 내보냄) · 2D 배치도에서 옮긴 부품 적용 `{projectDir, moves: {REF: {x, y, rot}}}` → 보드 저장 · overrides 고정 · 렌더 · DRC
POST /api/open-kicad	KiCad PCB 편집기로 열기
POST /api/claude · /stop · /reset	수정 명령 전송(백그라운드, 결과는 SSE) · 중지 · 새 세션

브리지는 127.0.0.1 에만 열리고, 허용된 Origin(irodmas.com · samcho93.github.io · localhost · PCB_AGENT_ORIGINS)이 아닌 요청은 403 으로 거절합니다.

10. 문제 해결

“로컬 브리지에 연결할 수 없습니다”

PC 에서 node server/index.js 가 실행 중인지, 포트가 8765 인지 확인하세요. irodmas.com 에서는 브라우저의 로컬 네트워크 접근 권한을 허용해야 합니다. Safari 는 https 페이지에서 localhost 접속을 막을 수 있으니 Chrome · Edge 를 쓰거나 http://127.0.0.1:8765/ 를 직접 여세요.

“풋프린트를 찾지 못한 부품”이 있어요

회로도의 Footprint 필드가 라이브러리:이름 형식인지, 그 라이브러리가 KiCad 전역 또는 프로젝트 fp-lib-table 에 등록돼 있는지 확인하세요. 풋프린트가 비어 있는 부품은 “미지정”으로 따로 표시됩니다.

부품이 보드 밖에 나열돼 있어요

외곽 안에 다 들어가지 않은 부품입니다. 외곽을 키우거나, 부품 간격 · 가장자리 여유를 줄이거나, “뒷면 배치”를 켜세요. 요약의 부품 밀도가 60~70% 를 넘으면 배선 공간도 부족해집니다.

DXF 를 읽었는데 “닫힌 외곽선을 만들 수 없습니다”

선 끝점이 서로 맞지 않거나(틈), 치수선 · 문자 레이어가 섞인 경우입니다. 외곽 레이어만 체크하고, CAD 에서 외곽을 하나의 폴리라인으로 합치면 가장 확실합니다. 블록(INSERT)은 읽지 않으니 분해해서 저장하세요.

3D 렌더가 안 나와요

pcb render 는 KiCad 9 부터 있습니다. KiCad 8 에서는 “레이어 SVG” 탭을 보세요. 로그 탭에 실패 원인이 찍힙니다.

Claude 가 실행되지 않아요

터미널에서 claude 를 한 번 실행해 로그인했는지 확인하세요. 설치 위치가 특이하면 CLAUDE_CLI 환경 변수로 실행 파일을 지정합니다. 한 번에 하나의 명령만 실행되며, ■ 중지로 멈출 수 있습니다.

고정 홀이 들어가지 않았어요

자동 모드에서 보드 짧은 변이 홀 간격의 4배보다 작으면 넣지 않습니다(요약의 “확인 필요”에 표시). 직접 지정으로 작은 홀(M2)과 짧은 간격을 주거나 대각선 2개를 고르세요. 회로도에 이미 홀 부품이 있으면 자동 모드는 새로 만들지 않고 그 부품을 씁니다.

Footprint Agent 가 “실행 중이 아님”이에요

webFootprintAgent 폴더에서 pip install -r requirements.txt 후 python run.py 를 실행하거나, webCadAgent 옆에 clone 해 두고 풋프린트 탭의 시작을 누르세요. Claude CLI 로그인(또는 .env 의 API 키)이 필요합니다.

배선이 “시간 안에 끝나지 않아 중단”돼요

1단계(배선)가 시간 제한 안에 끝나지 않은 경우입니다. 시간 제한을 늘리거나, 부품 간격 · 보드 크기를 늘리거나, 레이어를 4층으로 바꿔 보세요. 최적화가 오래 걸리는 것은 문제가 되지 않습니다 — 끝나지 않으면 1단계 결과를 씁니다.

배치를 되돌리고 싶어요

pcb-agent/backups/ 에 덮어쓰기 전 파일이 시각별로 남아 있습니다. 원하는 파일을 프로젝트 폴더의 .kicad_pcb 로 복사한 뒤 “다시 분석”을 누르세요.

11. 개발 이력

요청 · 변경 · 검증의 자세한 기록은 저장소의 CHANGELOG.md 에 있습니다. 최신 항목이 위입니다.

2026-10-19 · 3D	Footprint Agent 3D 모델(데이터시트 도면 · 각인)을 프로젝트 `AgentParts.3dshapes` 로 설치하고 보드의 같은 부품에 붙여 3D 뷰에 표시
2026-10-16 11:50 · `c78da88`	메탈 PCB(단면 · 비아 없음), KiCad 로 제조 파일(거버 · 드릴 · CPL · BOM) ZIP · webGerber, 기존 PCB 먼저 불러와 수정 / 새로 선택
2026-10-16 10:45 · `a717144`	뷰 확대 · 이동, 3D 보기(드래그 회전 · 방향 버튼), 2D 부품 이동 · 회전 → 적용, 창 크기 조정
2026-10-16 02:10 · `ffabf5a`	배치 후 Freerouting 자동 배선 (배선 버튼 · 배치 후 자동 실행 · 2단계 최적화 · 결과 렌더/DRC)
2026-10-15 15:01 · `5414358`	풋프린트: KiCad 라이브러리 우선 찾기(심볼 필터 · 패드 수 · 크기/커넥터 기본값) → 없으면 Footprint Agent, 자동 채우기
2026-10-15 14:43 · `7b60ff9`	Footprint Agent 가 실행 중인데 “실행 중이 아님”으로 나오던 문제 수정
2026-10-15 14:36 · `30e8b92`	한글 경로 프로젝트에서 브리지가 꺼지던 문제(Node 24 fs.rmSync) 수정, KiCad 탐지 위치 확대
2026-10-15 14:10 · `b8f2947`	풋프린트 탭: 대체 풋프린트를 회로도 Footprint 필드에 반영
2026-10-15 14:00 · `a8cb44e`	Footprint Agent(webFootprintAgent) 연동 — 없는 풋프린트를 데이터시트로 생성 · 설치
2026-10-15 13:32 · `7ca34a2`	?project=<폴더> 로 프로젝트 바로 열기, irodmas.com 대문 카드 스크린샷
2026-10-15 13:17 · `184f652`	외곽 고정 홀(자동 · 직접 지정), 추가 사항(배치 후 Claude 반영)
2026-10-15 13:02 · `78d197c`	구조 · 사용법 가이드 메뉴
2026-10-15 12:49 · `facbcb9`	초기 개발: 외곽(프리셋 · DXF) · 레이어 · 배치 참고 페이지 · 자동 배치 · 렌더 · DRC · Claude CLI 터미널, irodmas.com 배포

PCB Agent · github.com/samcho93/webCadAgent · MIT