Copyright 2026 Colin Ezra Wilder. Licensed under the Apache License, Version 2.0 (해당 스킬과 함께 제공되는 LICENSE 및 NOTICE 파일 참조).
CadQuery 서브프로세스를 통한 CAD 부품
로컬, 스크립트 가능한 CAD: Python 스크립트가 솔리드를 작성하고, 와치독된 서브프로세스가 이를 실행하며, cq_helpers가 내보내기를 검증하고, 6뷰 PNG가 형상을 증명합니다. 사용자는 결과물을 FDM 프린터로 출력하므로, 여기서 나가는 모든 STL은 깔끔하게 슬라이싱되어야 합니다.
불가침 규칙
- 오직 원샷 서브프로세스만. 2026년 7월 14일에 장기 실행 CAD 서버 프로세스가 호출 간 가져온 모델이 누적되어 전체 머신을 OOM 크래시시켰습니다 (2026년 11월 14일 재생에서 먼저 비균일 스케일을 의심했으나 해소됨; 주의사항 참조). 서브프로세스가 죽으면 한 번의 실행만 손실되지만, 프로세스 내 작업이 죽으면 시스템 전체가 다운됩니다. 모든 빌드는
scripts/run_watchdogged.ps1을 통해 실행하고, 다른 venv 스크립트(드로잉 프로브, 메쉬 검사 등)도 마찬가지로 실행하세요. CadQuery 유무와 관계없이 적용됩니다.hooks/require_runner.py가 Claude Code 훅으로 등록되면(README 참조), venv의 Python을 직접 호출할 경우 대신 사용할 러너 명령어와 함께 거부됩니다: 이 거부는 규칙이 작동한다는 증거이며, 우회해야 할 오류가 아닙니다. - 검증된 부품 파일은 절대 편집하지 않음. 출력이 테스트되어 작동하는 스크립트는 동결됩니다. 변형은 새 파일(예:
adapter_hex.py옆에adapter_hex_trim.py)로 만들고, docstring에 무엇이 왜 변경되었는지 정확히 기재합니다. 모든 스크립트에는STATUS:줄(스크립트 규칙 참조)이 있어 "검증됨"을 기억에 의존하지 않고 기록합니다. - 모든 내보내기는
cq_helpers.export_checked를 통해. BRepisValid()만으로는 깨끗한 메쉬가 보장되지 않습니다. 슬라이서는 유효성 검사를 통과하는 비-워터타이트 STL을 거부합니다. 이 게이트는 이미 출시된 불량 부품을 잡아낸 바 있습니다. - 출력될 모든 부품은 PRINT 방향에서 섬 검사를 받음.
h.islands(solid, up="+z")(또는 계획된 up 축)는 베드 위에서 시작하여 나중에야 부품 레이어와 결합되는 재질을 찾아내므로, 전체 높이 동안 지지대 위에 서 있습니다. HIGH 섬은 "서포터가 처리할 것"이 아니라, 프린트 계획 전에 수정하거나 사용자에게 알려야 할 설계 문제입니다. 2026년 10월 9일에 로봇 쉘의 휠 간격 기둥이 하나였습니다(트리 서포트 위 36.8mm 높이, 6.52 얇음). 모든 적합 게이트를 통과했음에도 22시간 3색 프린트 중간에 부러졌습니다. 적합 게이트는 "맞는가"를 묻지만, 이것은 "바닥부터 쌓을 수 있는가"를 묻습니다.
워크플로우
- 프롬프트가 열어둔 사항을 확인. 완전한 사양("12mm 높이, 9 외경, 4.3 구멍")은 게이트가 필요 없습니다. 하중 지지 선택이 열려 있는 경우(어떤 구멍, "15mm 돌출"이 어디서 측정되었는지, 무엇이 장착되는지, 어떤 하드웨어, 어떤 폴더), 짧은 제안으로 읽은 내용을 기술하고 빌드 전에 사용자에게 물어보십시오. 참조 이미지는 항상 이 게이트를 거칩니다(아래 참조).
- 스크립트 작성. 제공할 부품: 스크립트는 해당 부품 폴더에 출력물과 함께 위치합니다(스크립트 자체가 부품의 기록입니다. "부품 위치" 참조). 프로브 및 실험: 스크래치 폴더 사용.
- 실행:
기본값: 300초 제한시간, 4GB 한도, 500ms 폴링, 인터프리터& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(-Python <path>또는CADPARTS_PYTHON환경 변수로 재정의). 한도는 전체 프로세스 트리의 커밋된 메모리에 적용되며, Windows 작업 개체를 통해 커널에서 시행됩니다: 초과 할당은 거부되고(스크립트는MemoryError또는 OCCT 할당 실패를 봄) 러너가 트리를 종료하며, 종료 코드 137을 반환합니다. cadquery를 가져오는 것만으로 약 0.7GB를 커밋하므로, 한도를 1GB 아래로 설정하지 마십시오. 알려진 무거운 작업에 대해서만 의도적으로 한도를 높이고, 종료에 대한 첫 번째 대응으로 하지 마십시오. 와치독 종료는 일반적으로 형상 오류(주의사항 참조)를 의미하며, 작은 한도 때문이 아닙니다.-Tail N은 stdout의 마지막 N줄만 출력합니다. 전체 로그는 항상 스크립트 옆에<script>.out.txt로 저장됩니다. 긴 로깅 스크립트에 사용하여 전체 로그가 컨텍스트에 들어가지 않도록 합니다. 요약 줄은 벽시계 시간을 보고합니다.-TimeoutSec을 추측이 아닌 그 값으로 선택하십시오. PowerShell 도구를 통해 실행하는 경우, 도구 자체의 제한시간을-TimeoutSec보다 높게 설정하십시오. 도구가 러너를 먼저 죽이면 작업 개체도 빌드를 함께 중단시킵니다: 실행은 손실되며, 절대 고아가 되지 않습니다. - 출력 읽기. 러너는 스크립트의 stdout, stderr(있는 경우), 벽시계 시간, 트리의 최대 커밋 메모리를 출력합니다.
DONE센티널이 필요합니다. 이것 없이 끝난 실행은 완료되지 않은 것입니다. 종료 코드 137 = 와치독 종료(마지막 줄에 제한시간 또는 한도 초과 표시); 3 = 와치독이 무장할 수 없음(또는 인터프리터 누락), 스크립트가 실행되지 않음.<script>.out.txt는 빌드의 실행 로그입니다(README에서 참조).<script>.err.txt는 stderr에 내용이 있을 때만 존재합니다. 한도 초과 종료 시, 한계를 건드리기 전에 문제를 진단하십시오(주의사항: "한도 초과 종료 진단"). - 보고 전에 검증.
render6PNG를 읽고 실루엣을 의도와 비교하십시오. 스크립트가 출력한 bbox/볼륨에서 치수를 보고하고, 기억에 의존하지 마십시오. 각 기능을 빌드된 솔리드 MEASURING으로 확인하십시오(describe, 면 bbox, 벽을 관통하는 슬래브 교차). 입력 상수를 자기 자신과 비교하는 assert는 아무것도 증명하지 않습니다. 그런 다음 부품이 출력될 방향으로h.islands를 실행하고(불가침 규칙 4), 이를 부품과 함께 보고하십시오. - 기록. 폴더 README 업데이트(출력할 파일), STATUS 줄 설정, 다음 세션에 필요한 학습 내용 기록("기록" 참조).
부품 위치 및 부품 폴더 구성
부품 루트: 질문 (여전히 ASK라고 적혀 있으면, 사용자에게 부품이 위치할 곳을 물어보십시오, 예: C:\Users\<name>\Documents\cad-parts, 여기에 기록하겠다고 제안). 각 부품은 해당 루트 아래에 자체 폴더를 가집니다. 관련 부품은 하위 폴더로 그룹화하십시오(로봇 섀시 부품은 함께, 일회성 출력은 함께). 부품의 홈이 명확하지 않으면 질문하십시오. 추측하지 마십시오.
부품 폴더에는 다음이 포함됩니다:
- 스크립트, STEP 및 렌더는 최상위 레벨에; 모든 STL은
stl/하위 폴더에 (stl_dir="stl"로 내보내기). 체인 폴더("체인 편집" 참조)에서 최상위 레벨에는 부품의 하나의 라이브 버전이 있습니다. 최상위 부품에 대한 STL이stl/에 있으면, 그것이 출력할 것입니다. 누군가가 제공한 깨진 STL은 최상위 레벨에 유지되며,stl/에는 절대 넣지 않습니다.stl/는 출력 가능을 의미하기 때문입니다. README.md: 부품의 설명, 계보("사용 중: v12, 최신: v16 시험"), 및 명시적인 "출력할 것" 줄. 사용자의 승인 없이archived/로 이동하지 마십시오. README가 아직 없으면 작성하십시오. 버전 대신 형제 크기(11mm 및 14mm 스탠드오프)는 각각 하나의 출력 줄을 갖습니다.archived/: 대체된 버전, 버전 또는 체인 단계당 하나의 폴더, 각각 스크립트, STEP, STL, 렌더 및 실행 로그, 그리고 아카이브 루트에WHY-ARCHIVED.md가 함께 있습니다. 아카이브된 체인 단계는 제자리에서 다시 실행되지 않습니다(소스 경로가 이전 레이아웃을 가정함). 먼저 최상위 레벨로 복사하십시오.- 다시는 돌아오지 말아야 할 기능에 대한
DEAD-*.md마커(예:CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md: 두 개의 모터를 파괴한 크러쉬 리브). 부품을 만지기 전에 폴더의 모든 DEAD 파일을 읽으십시오. - 인쇄 계획(작성된 경우), 하나의 STL 이름에 연결됨. 부품이 변경되면 오래된 것으로 표시하십시오.
<script>.out.txt, 빌드의 실행 로그.- 체인 폴더의
current.json(다음 섹션).
스크립트 규칙
- 모듈 docstring: 부품이 무엇인지, 왜 존재하는지, 실행 방법, 및
STATUS:줄 (Windows 경로를 포함할 때는 raw docstringr"""사용: CPython 3.14는\c,\s이스케이프에 대해 경고합니다):STATUS: printed 2026-09-08, fitted, FROZEN또는STATUS: trial, unprinted. FROZEN은 불가침 규칙 2가 검증됨으로 의미하는 바입니다. 인쇄 결과가 돌아오면 줄을 업데이트하십시오. - docstring은 이 버전의 델타와 그 이유를 포함합니다. 계보와 출력할 파일은 README에 속합니다. 이전 버전의 메모를 앞으로 붙여넣지 마십시오(그렇게 한 스크립트는 50KB에 달했습니다).
- 버전 번호는 0.1 단위로 증가: 버전이 있는 부품 라인의 각 새 빌드는 +0.1, v22 -> v22.1 ... v22.9 -> v23, 사용자가 명시하지 않는 한 앞서 건너뛰지 않습니다. 파일은 점을 밑줄로 씁니다(
chassis_v22_1.py,.step,stl/..._v22_1.stl) 이후 스크립트가 이전 버전을 모듈로 가져오기 때문입니다(import chassis_v12 as V12). 점이 있는 모듈 이름은 가져올 수 없습니다. docstring과 README는 "v22.1"이라고 말합니다. 기존 파일은 번호를 유지합니다. 체인 단계(step8,step11e)는 자체 체계를 유지하며, 부품에 각인된 버전 스탬프는 사용자 자신의 카운트로 유지됩니다. - 모든 치수는 맨 위에 명명된 상수로, mm 단위, 한 곳에서 편집 가능.
import cq_helpers as h(venv의 site-packages에 설치됨).- 왼쪽 또는 오른쪽을 쓸 때마다 HAND를 명시: 로봇 또는 부품 자체의 왼쪽(당신이 그 부품이라고 가정하고 앞을 바라볼 때) 또는 앞을 바라볼 때 보는 사람의 왼쪽. 이들은 반대입니다. docstring, README 또는 메시지에 "왼쪽"이라고만 쓰면 결함입니다. 다중 부품 프로젝트의 맨 위에 축 규칙(어느 쪽이 앞, +x, 위)을 쓰고 유지하십시오.
solid.isValid()를 어설트하고 경계 상자가 의도한 치수와 일치하는지 어설트하십시오. 공식도 어설트로 보호하십시오(예: 보어 깊이가 샤프트 돌출부를 초과해야 함). 잘못된 매개변수 편집이 조용히 스크랩을 출력하는 대신 크게 실패하도록 합니다.- 결합 하드웨어는 솔리드로 모델링되고
h.interference로 검사됩니다. 치수는 데이터시트 또는 캘리퍼에서 가져오고 각 상수의 주석에 측정 또는 가정된 값과 출처를 표시하십시오. 더 나은 정보가 없을 때의 기본 체결구 값: M3 소켓 헤드 5.5 x 3.0, M3 클리어런스 D3.30, M2 셀프 탭 파일럿(PLA) D1.7 ~ 1.8. 기타 표준 체결구: ISO 261 나사 및 ISO 273 클리어런스, 가정으로 표시. print(..., flush=True)로 진행 상황 표시;print("DONE", flush=True)로 종료.- 내보내기:
h.export_checked(solid, str(OUT / "part_name"), stl_dir="stl")그런 다음h.render6(solid, str(OUT / "part_name.png")). - 내보낸 파일당 하나의 부품; 부품은 개별적으로 인쇄됩니다.
가져온 STEP의 체인 편집
많은 부품은 가져온 상위 STEP의 델타입니다(하나의 베이스 플레이트는 9개의 델타를 통해 step 10c에 도달했습니다). 규칙:
- 단계 이름을
step<N>으로 지정하고, 분기에는 접미사 문자(step7c) 또는 리베이스에는step5r)를 사용합니다. docstring의 SRC 줄은 상위 파일을 지정합니다. 리베이스에는 폴더에 WHY 노트가 필요합니다. - 체인 폴더는 라이브 상위를 지정하는
current.json을 가지고 있습니다. 사용자가 출력할 부품을 지정할 때, 또는 단계 스크립트에서export_checked직후에h.set_current(folder, "part.step", note="2026-09-22: ...")로 작성하십시오. README의 "출력할 것" 줄과current.json이 일치해야 합니다. - 종속 항목은 상위를
plate = h.import_current(PLATE_DIR, pin="base_plate_step10c")로 가져오고, 하드 코딩된 파일 이름을 사용하지 마십시오. 체인이 이동하면 고정된 빌드가 두 부품을 모두 명명하며 실패합니다. 새 상위에 대해 모든 적합 검사를 다시 실행한 다음 핀을 이동하십시오. STEP이set_current없이 교체된 경우 지문 검사도 실패합니다. (이유: 종속 항목은 한때 상위 STEP이 사라지면 실행을 중단했고, 하나는 새 상위가 출력할 부품인 동안 오래된 상위에 고정된 모든 검사를 통과했습니다.) - 델타 증명: 전후에
h.diff를 실행하고 편집 상자 외부의 모든 것이 변경되지 않았음을 어설트하십시오. - 새 종속 부품(플레이트에 볼트로 고정된 브래킷)은 최소한 다음을 어설트합니다: 착석(결합 면과의 간격 0, 중첩 없음), 구멍 축이 상위의 축과 일치, 두 구멍 모두에서 생크 클리어런스, 헤드 및 도구 접근이 명확함(각 헤드 위에 육각 키 기둥), 차단해서는 안 되는 상위 기능이 여전히 자유로워야 함. 상위의 구멍은 B-rep에서 읽고, 축 방향으로 실린더 면을 필터링합니다(필렛도 실린더 면이기 때문).
- 스크립트의 매개변수 전용 변형(11mm 스탠드오프의 14mm 복사본): 두 스크립트의 텍스트 diff로 "다른 것은 변경되지 않음"을 증명하고(docstring, NAME 및 매개변수만 다름) 분석 볼륨에 대한
describe()를 추가합니다. 형상 diff 프로브는 필요하지 않습니다. - 비균일 스케일은 가져온 B-rep의 모든 면을 B-스플라인으로 바꿉니다(주의사항): 오프셋이 실패할 수 있습니다. 재구축하거나 메쉬를 스케일링하십시오.
cq_helpers API (venv site-packages)
export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015): Workplane 또는 Shape를 허용합니다.isValid()를 요구합니다..step/.stl을 씁니다(STL은stl_dir이 설정되면<basepath의 dir>/<stl_dir>/으로, 여기서는 항상"stl"). trimesh 워터타이트 + STL의 와인딩 게이트(자동 복구 포함: merge_vertices 자릿수 5 다음 4, fill_holes, fix_normals, 볼륨 드리프트 < 0.5%인 경우에만 허용). 그런 다음 STL은 디스크에서 다시 읽은 STEP과 일치해야 합니다(또는step=False일 때 shape와): 각 면당 경계 상자가 max(0.05 mm, 부품 최대 크기의 0.5 %) 이내, 볼륨이agree_tol이내여야 합니다. trimesh 메쉬를 반환합니다. 실패한 각 검사는h.GateError(AssertionError의 하위 클래스, 명시적으로 발생하므로python -O가 건너뛸 수 없음)를 발생시켜 실행을 중단합니다. 작성된 각 파일에 대해export ok:줄(전체 경로 및 확장자 포함)과 동의 숫자가 있는export check:줄 하나를 출력합니다. 자동 복구는 유효한 B-rep의 미세한 테셀레이션 균열을 닫습니다. 누락된 면은 닫지 않습니다("사용자가 제공한 메쉬 복구" 참조). STL은 새 복사본에서 메쉬됩니다(형상은 메쉬되지 않은 상태로 유지됨). 따라서 먼저 형상에 고정된 메쉬는 삭제됩니다.mesh=(deflection, angular)(mm 절대, rad)로 고정하십시오. 은박 면이 있는 공급업체 부품은(0.05, 0.2)가 필요했습니다(주의사항).render6(shape, png_path, color="#b25563", tol=0.3): 하나의 PNG에 6개의 표준 음영 뷰(앞/뒤/왼쪽/오른쪽/위/앞-3/4). 깊이 버퍼링된 VTK 오프스크린 렌더링(matplotlib의 페인터 정렬은 어셈블리에서 가짜 반투명을 생성함, 주의사항), 평행 투영, 각 뷰는 부품에 프레임이 지정됨. Workplane은 스택의 모든 Shape를 렌더링합니다.tol은 테셀레이션의 선형 처짐(mm)입니다(큰 어셈블리의 경우 0.6).- `render_compare(shape, ref_image_path, p