circuit

검증 (ERC)

한 줄 요약 — 회로를 만들기 전에 에러를 자동으로 찾습니다. 각 경고는 해당 학습 문서로 연결됩니다.

사용법

circuit check my-circuit.yaml           # 정적 검사 (ngspice 불필요)
circuit check my-circuit.yaml --deep    # + 시뮬레이션 기반 정량 검사
circuit check my-circuit.yaml --json    # 기계 판독용
circuit check examples/**/*.yaml        # 전체 검사

종료 코드:

코드의미
0정상
1ERC 에러
2사용법 오류
3시뮬레이션 실패
4expect 불일치

출력 예

examples/05-diode/led-no-resistor.yaml

  ✖ W301  LED1에 직렬 저항이 없습니다              (12번째 줄)
      LED는 전압이 조금만 올라가도 전류가 급격히 증가해
      파괴됩니다. 반드시 전류를 제한해야 합니다.
      
      수정: LED와 직렬로 저항을 넣으세요.
            R = (V_supply - V_F) / I_desired
            
      참고: docs/05-diode/04-led-current-limiting.md

  ⚠ I309  벌크 커패시터가 없습니다
      참고: docs/08-power/04-decoupling.md

  에러 1개, 경고 0개, 정보 1개

💡 모든 진단이 학습 문서로 연결됩니다. 검증기가 곧 교재입니다.

규칙 분류

E1xx — 구조 (정적)

코드심각도규칙
E101errorref 중복
E102error존재하지 않는 핀 (R1.3)
E103error부품 핀이 어떤 넷에도 없음
E104error같은 핀이 두 넷에
E105error부유 넷 (핀 1개만)
E106error알 수 없는 type
E107error값 파싱 실패
E108error반도체에 model 없음
E109error넷 이름/ref 정규식 위반
W110warningref 접두어와 타입 불일치
W111warningexpect가 없는 노드 참조
I112info사용되지 않은 부품

E2xx — 전기 (정적)

코드심각도규칙참고
E201errorGND 넷 없음2-02
E202errorGND에서 도달 불가한 회로 섬
E203error전원 단락 (전압원 양단이 같은 넷)
E204error전압원만의 루프
E205error전류원이 개방(open) 노드에
E206error출력 충돌 (한 넷에 출력 2개 이상)
E207error부품 양단이 같은 넷 (소자 단락(short))
W208warning커패시터(capacitor)만으로 GND 연결 (DC 경로 없음)
W209warning전해 커패시터 역극성0-04
W210warningVCC 넷에 전원이 없음

W3xx — 부품 (정적)

코드규칙참고
W301LED에 직렬 저항 없음5-04
W302BJT 베이스 저항 없음6-02
W303레귤레이터(regulator) 디커플링 없음8-02
W304MOSFET 게이트 플로팅6-05
W305opamp 피드백 경로 없음7-01
W306opamp 전원핀(v+/v-) 미결선7-01
W307스위치에 풀업(pull-up)풀업 pull-up아무도 신호선을 잡고 있지 않을 때 전압을 높은 쪽으로 끌어 두어, 떠 있는 입력을 없애는 저항입니다.자세히 보기 →·풀다운 없음9-05
W308유도성 부하에 플라이백 없음5-05
I309벌크 커패시터(bulk capacitor)벌크 커패시터 bulk capacitor보드 입구에 두는 큰 커패시터로, 디커플링이 못 따라가는 느린 전류 변화를 받아 냅니다.자세히 보기 → 없음8-04

★ W5xx — 측정 회로 특화 (정적)

이 저장소의 목적에 맞춘 규칙들입니다.

코드규칙참고
W501고임피던스 노드에 버퍼 없음 (> 100 kΩ가 긴 배선(trace)/부하로)13-03
W502ADC 입력에 안티에일리어싱 필터(anti-aliasing filter)에일리어싱 aliasing샘플링 주파수의 절반보다 높은 성분이 낮은 주파수인 척 되접혀 들어오는 현상으로, 한 번 섞이면 되돌릴 수 없습니다.자세히 보기 → 없음10-04
W503OP앰프 출력에 직접 큰 용량성 부하7-07
W504소스 임피던스(impedance)임피던스 impedance교류에서의 저항으로, 크기뿐 아니라 전압과 전류의 시간 차이(위상)까지 담은 복소수입니다.ZC=1jωC,ZL=jωLZ_C = \frac{1}{j\omega C},\quad Z_L = j\omega L자세히 보기 → × 부하 용량이 목표 대역폭(bandwidth) 초과11-05
W505IC 전원핀에 디커플링 없음8-04
W506고임피던스 노드에 누설 큰 보호 소자5-05
W507차동 입력의 임피던스 불균형12-07

E4xx — 정량 (--deep, 시뮬레이션 필요)

코드규칙
E401저항 소비전력 > 정격
E402LED 전류 > 최대
W403LED 전류 < 1 mA (너무 어두움)
E404커패시터 전압 > 정격
W405opamp 출력 클리핑
W406BJT가 의도치 않게 포화(saturation)/차단
E407다이오드(diode) 역전압 초과
W408레귤레이터 드롭아웃(dropout) 미달
E409ngspice 비수렴 (한국어 원인 추정)

★ 왜 정적 검사와 --deep을 나누는가

정적 (check)정량 (--deep)
ngspice 필요❌✅
속도즉시시뮬레이션 시간
CI에서항상ngspice 있을 때
검출구조·연결 오류정격 초과, 동작점(operating point)동작점 operating point신호가 없을 때 트랜지스터가 앉아 있는 전압·전류 자리로, 여기가 어긋나면 증폭이 잘려 나갑니다.자세히 보기 →

ngspice가 없는 환경에서도 기본 검증은 되어야 하므로 분리했습니다.

규칙 조회

circuit rules                    # 전체 목록
circuit rules --code W301        # 특정 규칙 상세
circuit rules --json             # 스킬·도구용

출력 예:

W301 — LED에 직렬 저항이 없습니다

심각도: warning

왜 문제인가:
  LED는 다이오드이므로 전압-전류 관계가 지수함수입니다.
  전압이 0.1 V만 올라도 전류가 4배가 되어, 전원 전압의
  오차나 온도 변화만으로 파괴될 수 있습니다.

어떻게 고치나:
  LED와 직렬로 전류제한 저항을 넣으세요.
    R = (V_supply − V_F) / I_desired
  예: 5 V, 적색 LED(2.0 V), 10 mA → R = 300 Ω

관련 문서:
  docs/05-diode/04-led-current-limiting.md

★ 검증기가 학습 도구인 이유

회로를 그린다검증한다 (circuit check)경고가 나온다문서를 읽는다경고마다 해당 학습 문서 링크가 붙어 있다이해한다고친다고친 회로를 다시 검증 — 여기서 루프가 닫힌다다시 검증한다

실수를 통해 배우되, 부품을 태우지 않고 배웁니다.

⚖️ 트레이드오프

선택✅⚠️
엄격한 규칙실수 방지오탐(false positive) 이 많으면 무시하게 됨
느슨한 규칙방해 안 됨놓치는 실수
경고에 문서 링크학습 효과문서 유지보수
정적 + 정량 분리환경 무관 기본 검증두 번 실행

💡 오탐을 줄이는 것이 중요합니다. 경고가 너무 많으면 사용자가 전부 무시하게 되어, 진짜 문제도 놓칩니다. 심각도를 신중하게 정하고, 의도적인 설계는 예외 처리할 수 있게 합니다.

예외 처리

의도적인 설계라면 규칙을 끌 수 있습니다.

components:
  - {ref: D1, type: led, model: LED_RED, 
     ignore: [W301]}   # 정전류 드라이버로 구동하므로 저항 불필요

⚠️ 이유를 주석으로 남기세요.

🔌 CI에서 사용

# .github/workflows/ci.yml
- name: 회로 검증
  run: |
    circuit check examples/**/*.yaml
    circuit test examples/**/*.yaml     # ngspice 필요

모든 예제가 항상 검증됩니다. 문서와 코드가 같이 썩지 않습니다.

연습문제

문제 1. 다음 회로에서 검증기가 잡을 문제는?

exercises/17-02-led-fixed.yaml
이름 없는 회로 회로도V15VD1LED_REDAB
이름 없는 회로
components:
  - {ref: V1, type: vdc, value: 5}
  - {ref: D1, type: led, model: LED_RED}
nets:
  A: [V1.p, D1.a]
  B: [V1.n, D1.k]
풀이
코드문제
E201GND 넷이 없음 → SPICE 시뮬레이션 불가
W301LED에 직렬 저항 없음 → 파괴 위험

수정:

components:
  - {ref: V1, type: vdc, value: 5}
  - {ref: R1, type: r, value: 330}
  - {ref: D1, type: led, model: LED_RED}
nets:
  VIN: [V1.p, R1.1]
  A:   [R1.2, D1.a]
  GND: [V1.n, D1.k]
```text
</details>

**문제 2.** W501(고임피던스 노드에 버퍼 없음)은 어떻게 검출합니까?

```schematic
exercises/17-02-w501-buffer.yaml
풀이

검출 논리:

  1. 각 노드의 테브난 등가(Thévenin equivalent) 저항을 계산 (2-05)
  2. 100 kΩ 이상인 노드를 찾음
  3. 그 노드가 다음 중 하나에 연결되었는지 확인:
    • 커넥터 (외부로 나감)
    • 큰 용량성 부하
    • 여러 부품 (배선이 길어질 가능성)
  4. 그리고 버퍼(팔로워 구성 OP앰프, 소스 팔로워(source follower)소스 팔로워 source follower전압 이득이 1인데도 쓰는 이유는 높은 임피던스를 낮은 임피던스로 바꿔 주기 때문입니다.자세히 보기 →)가 없으면 경고

메시지 예:

W501  노드 'ELECTRODE'의 임피던스가 1.0 MΩ입니다
      이 노드가 커넥터 J1로 나갑니다. 케이블 용량(약 100 pF/m)과
      만나면 대역폭이 1.6 kHz로 제한됩니다.
      
      수정: 이 노드 바로 옆에 버퍼(볼티지 팔로워)를 넣으세요.
      참고: docs/13-signal-chain/03-input-impedance.md

이 규칙이 이 저장소의 목적(신호 측정)에 특화된 부분입니다. 일반 EDA 도구는 이런 검사를 하지 않습니다.

이전 ← 01 circuit.yaml 포맷 | 다음 → 03 시뮬레이션으로 측정 확인