Claude CodeでKiCadの基板設計をkicad-cliで検証する手順
kicad-cliのERCとDRCをJSONで出力し、Claude Codeに読ませて違反を直す検証ループを組みます。権限の絞り方と、違反が残る間は終わらせないStop hookも示します。
KiCadの基板設計をClaude Codeで検証するなら、鍵になるのはkicad-cliです。回路図の電気的ルールチェック(ERC)と基板の設計ルールチェック(DRC)をコマンド1本で実行でき、結果をJSONファイルに書き出せます。そのファイルをClaude Codeに読ませれば、違反の一覧を見ながら修正案を出し、直したら再実行する、という検証ループが成立します。本記事はKiCad 9.0のCLIマニュアルに沿って、そのループの組み方を説明します。
回路設計の中身までClaudeに任せる記事ではありません。扱うのは「機械が判定できる違反を、Claudeが読んで潰し込む」部分です。マイコン側のファームウェア開発はESP32の開発とシリアルデバッグの手順にあります。
kicad-cliで何ができるか
kicad-cliはKiCadに同梱されるコマンドラインの入口です。サブコマンドはfp、jobset、pcb、sch、sym、versionの6つ。回路図の検査はsch、基板の検査はpcbの下にあります。
macOSでは実行ファイルが/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cliにあります。PATHに通っていなければ、フルパスで呼ぶか、シェルのエイリアスやシンボリックリンクでkicad-cliの名前に揃えてください。
どのサブコマンドも--help(-h)で使い方を表示します。たとえば次の2つです。
kicad-cli version
kicad-cli pcb drc --helpversionの既定出力はバージョン番号だけです。--format aboutを付けるとライブラリのバージョンや環境情報まで出るので、不具合報告に添える用途になります。検証ループを組む前に、手元のKiCadがCLI付きの9.0系かどうかをここで確かめておきます。
ERCとDRCのコマンドを押さえる
検査コマンドは2つです。入力が違い、基板側にだけ付くオプションがあります。
| 項目 | ERC | DRC |
|---|---|---|
| コマンド | ERCkicad-cli sch erc | DRCkicad-cli pcb drc |
| 入力 | ERC回路図(.kicad_sch) | DRC基板(.kicad_pcb) |
| 出力形式 | ERC--format report(既定)またはjson | DRC同左 |
| 違反の重大度 | ERC--severity-allほか3種 | DRC同左 |
| 終了コード | ERC--exit-code-violationsで違反ありが5 | DRC同左 |
| 共通のオプション | ERC--units、-D(--define-var) | DRC同左 |
| 固有のオプション | ERCなし | DRC--schematic-parity、--all-track-errors |
Claudeに読ませるなら、出力は--format jsonが向きます。既定のreportは人間向けのテキストで、.rptの拡張子で出力されます。JSONなら項目ごとに機械的に拾えます。
重大度のオプションは--severity-errorと--severity-warning、除外済みの違反を含める--severity-exclusions、すべてを含む--severity-allの4種です。組み合わせて指定できます。マニュアルに既定の重大度は書かれていないので、--severity-allを明示すると取りこぼしがありません。
DRCにだけある--schematic-parityは、基板と回路図の整合を調べます。回路図に部品を足したのに基板へ反映していない、といった食い違いが対象です。AIに回路図を書き換えさせる運用では、これを付けておくと片側だけ直した状態に気づけます。
--exit-code-violationsを付けると、違反が1件もなければ終了コード0、1件でもあれば5を返します。マニュアルに書かれている終了コードはこの2つだけです。0でも5でもない値が返ったときは、検査が走り切っていない可能性があります。入力ファイルのパスを疑ってください。
出力先を決める-o(--output)も要点です。省略すると、入力ファイルと同じ場所に、同じ名前で.rptか.jsonの拡張子を付けて書き出します。設計ファイルのフォルダに結果が散らばるので、reports/に集める指定が向きます。
数値の単位を決める--unitsも両方にあります。選べるのはmm(既定)、in、milsの3つです。レポートに出る寸法の単位がJSONごとにぶれると、Claudeが違反の大きさを読み違えます。設計ルールをmmで書いているなら、--units mmを明示して固定しておく手があります。
-D KEY=VALUE(--define-var)は、プロジェクト変数を上書きして検査するオプションです。複数回指定できます。変数でバリアントを切り替えている基板なら、ファイルを書き換えずに別の組み合わせを検査できます。
検査を1本のスクリプトにまとめる
ERCとDRCを毎回別々に打たせると、Claudeがオプションを変えたり、片方を忘れたりします。そこで検査を1本のシェルスクリプトにまとめ、Claudeにはそれだけを呼ばせます。プロジェクトがboardという名前だとして、scripts/check-kicad.shは次のようになります。
#!/usr/bin/env bash
# 使い方: scripts/check-kicad.sh board
set -u
proj=${1:?プロジェクト名を渡してください}
mkdir -p reports
kicad-cli sch erc --format json --severity-all \
--exit-code-violations \
-o reports/erc.json "$proj.kicad_sch"
erc=$?
kicad-cli pcb drc --format json --severity-all \
--schematic-parity --exit-code-violations \
-o reports/drc.json "$proj.kicad_pcb"
drc=$?
echo "ERC exit=$erc / DRC exit=$drc (0=違反なし, 5=違反あり)"
[ "$erc" -eq 0 ] && [ "$drc" -eq 0 ]スクリプトの最後の行で、両方が0のときだけ全体が成功になります。どちらかが5なら失敗を返すので、後述のStop hookがそのまま完了条件に使えます。同じ発想のMakefile版はMakefileの検証ループにあります。make checkの中でこのスクリプトを呼ぶ形にしても構いません。
検証の1周は、次の流れになります。
検証ループの1周
- 1
設計を編集する
Claudeが回路図か基板を変更します。
- 2
スクリプトを実行する
scripts/check-kicad.sh boardを呼び、ERCとDRCを続けて走らせます。 - 3
JSONを読む
reports/erc.jsonとreports/drc.jsonから、違反の種類と件数を拾います。 - 4
違反を直す
直せるものを直し、人の判断が要るものは案として示します。
- 5
再検査する
終了コードが両方0になるまで、手順2に戻ります。
複数の出力をまとめて走らせたい場合、KiCad 9.0にはjobset runもあります。.kicad_jobsetファイルに書いた一連のジョブを順に実行するコマンドで、--stop-on-errorを付けると失敗した時点で止まります。GUIでジョブセットを組んでいるプロジェクトでは、スクリプトの代わりにこちらを呼ぶ選択肢です。呼び出しは次の形になります。
kicad-cli jobset run --file board.kicad_jobset --stop-on-error board.kicad_pro--fileにジョブセットのファイル、末尾の引数にプロジェクトファイルを渡します。--outputを省くと、ジョブセット内のすべての出力先が生成されます。
権限を絞り、読む範囲を決める
検査コマンドは結果ファイルを書き出すだけなので、許可してよい部類です。一方、kicad-cliにはfp upgradeやsym upgradeのようにライブラリを新しい形式へ変換するコマンドもあります。Bash(kicad-cli *)で丸ごと許可すると、これらも確認なしで通ります。
Claude Codeの許可ルールは、*の前にある語が範囲を決めます。Bash(git log *)がgit log系だけを通すのと同じ仕組みで、サブコマンドまで書いておけば範囲を絞れます。末尾の*の前には空白を置きます。.claude/settings.jsonの例です。
{
"permissions": {
"allow": [
"Bash(kicad-cli version *)",
"Bash(kicad-cli sch erc *)",
"Bash(kicad-cli pcb drc *)",
"Bash(scripts/check-kicad.sh *)"
],
"ask": [
"Bash(kicad-cli fp upgrade *)",
"Bash(kicad-cli sym upgrade *)"
]
}
}注意点が2つあります。1つ目は、ルールは書いた文字列で照合されることです。macOSでフルパスのまま呼ぶ運用なら、ルールもフルパスで書いてください。PATHに通した名前を許可しても、フルパスの呼び出しは別のコマンドとして扱われます。
2つ目は、&&や;でつないだ複合コマンドです。許可ルールは各サブコマンドごとに判定されるため、scripts/check-kicad.sh board && 別のコマンドの後半が許可外なら、そこで確認が出ます。検査の呼び出しは1本ずつ単独で行わせると、確認で止まりにくくなります。権限設計の考え方は、変換の上書きを拒否するffmpegの権限設計でも同じ型を使っています。
CLAUDE.mdに検証の手順を書く
スクリプトと権限が整ったら、手順をCLAUDE.mdに書いておきます。Claudeが毎回同じ流れで動くようにするためです。KiCadの基板では、次のくらいの短さで足ります。
# KiCad基板の検証
- 回路図か基板を変更したら、完了を報告する前に
`scripts/check-kicad.sh board` を実行する
- 結果は `reports/erc.json` と `reports/drc.json` を読む。
違反の種類ごとに件数を数えてから直す
- 部品の値、フットプリント、ネット名は勝手に変えない。
ルール違反の解消に必要な場合は、変更案を先に示す
- ルール側(ネットクラスやDRCの制約)を緩めて通さない
- `reports/` は生成物なので編集しない3行目と4行目が肝です。DRCを通す最短の道は、ルールを緩めることです。クリアランスの制約値を下げれば違反は消えますが、基板としては製造できなくなるかもしれません。ルールを動かさない制約を、文章で明示しておきます。
違反が残る間は終わらせない
最後の仕上げがStop hookです。Claudeが「終わりました」と応答しようとした瞬間にスクリプトを走らせ、違反があれば終了コード2で止めます。Stopイベントの終了コード2は「Claudeが止まるのを防ぎ、会話を続ける」動作で、stderrの内容が理由として渡されます。
.claude/settings.jsonにhookを登録します。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/kicad-gate.sh"
}
]
}
]
}
}kicad-gate.shの中身です。
#!/usr/bin/env bash
input=$(cat)
# hookによる継続中なら、無限ループを避けて通す
echo "$input" | grep -q '"stop_hook_active": *true' && exit 0
cd "$CLAUDE_PROJECT_DIR" || exit 0
if ! out=$(scripts/check-kicad.sh board 2>&1); then
echo "$out" >&2
echo "reports/erc.json と reports/drc.json の違反を直してください" >&2
exit 2
fistop_hook_activeは、すでにStop hookの結果で続行している最中にtrueになる項目です。公式はこの値を見るか、トランスクリプトを処理して、永久に解消しない条件で止め続けないよう勧めています。DRCがどうしても通らない基板では、これがないと同じ指示を繰り返すだけになります。
止め続ける上限の挙動はStop hookのブロック回数上限に詳しくまとまっています。KiCadのようにチェックが重いコマンドでは、実行時間も気になります。検査が数十秒かかる基板なら、hookを毎回の応答終了で走らせず、CLAUDE.mdの指示だけで運用する手もあります。
Claudeに直させるときの線引き
ここまでで「検査を回して違反を読む」仕組みはできました。残る問いは、直す作業を誰がやるかです。
kicad-cliのpcbコマンド一覧にあるのは、DRCと各種エクスポートです。DRCの違反を自動修正する操作は含まれていません。つまり修正は、設計ファイルを編集するか、KiCadのGUIで人が直すかのどちらかになります。
どちらが向くかは、違反の種類で分けると進めやすくなります。
| 違反の種類 | Claudeに任せやすさ | 理由 |
|---|---|---|
| 回路図のERC(未接続ピン、電源フラグ不足) | Claudeに任せやすさ条件次第 | 理由回路図の意図を知らないと誤った結線を足す |
基板と回路図の不一致(--schematic-parity) | Claudeに任せやすさ向く | 理由差分の列挙と原因の切り分けが中心 |
| クリアランスなど配線の違反 | Claudeに任せやすさ人が直す | 理由座標の編集になり、見た目で確かめたい |
これはマニュアルの記述ではなく、運用上の見立てです。.kicad_pcbはテキスト形式のファイルですが、座標を直接書き換える修正は目視確認なしだと危険です。配線の修正はKiCadで人が行い、Claudeには違反の分類、原因の仮説、直した後の再検査の確認をさせる。この分担から始めると事故が少なくなります。
ERCの違反は、Claudeが誤った修正をしやすい領域です。たとえば未接続ピンの警告は、意図して開放にしたピンでも出ます。回路図上で「未接続マーカー」を付けるのが正解の場合もあります。CLAUDE.mdに「部品とネットは勝手に変えない」と書いた理由がこれです。
つまずいたときの切り分け
結果が空のとき、違反が多すぎて読み切れないとき、終了コードが想定外のときの順で見ます。
- 結果のJSONが作られない: 入力ファイルのパスが誤っている可能性があります。
-oを付けない場合は入力の隣に出るので、reports/の外も探してください - 件数が多すぎる:
--severity-errorだけに絞って、エラーから潰します。警告は別の周回で扱います - ERCは通るのにDRCで部品が足りないと言われる:
--schematic-parityが回路図との食い違いを拾っています。基板側にフットプリントを反映する更新が要ります - hookが止まらない:
stop_hook_activeの判定を入れているか確認します
検証ループの設計は、ハードウェアでもソフトウェアと変わりません。コマンド1本で白黒が付く検査を用意し、その結果を読ませ、通るまで終わらせない。KiCadはkicad-cliがその1本目を提供してくれる、扱いやすい題材です。
まとめ
kicad-cli sch ercとkicad-cli pcb drcをJSON出力と--exit-code-violationsで呼び、1本のスクリプトにまとめれば、Claude Codeの検証ループの土台ができます。許可ルールは検査系だけに絞り、ライブラリ変換は確認に回します。違反の解消はルールを緩めない約束とセットにして、配線の座標修正は人の目で確かめる運用が、最初の一歩として無難です。