davlug3/pcb-design-skill

PCB設計 (KiCad 8/9)

製造可能で構文的に有効なKiCad PCBファイルを作成し、.kicad_pcb S式ファイルとして出力します。KiCadが主要フレームワークです。 ファイル形式については記憶に頼らず、KiCad開発者ドキュメントと、提供されているバリデータでクリーンなアセットを信頼できる情報源として使用してください。

対象ダイアレクト: KiCad 9 ((version 20241229))。 KiCad 8 (20240108) もサポートされていますが、違いは references/pcb-file-format.md#version-dialect-matrix に記載されています（特にレイヤー序数はKiCad 9で再度変更されました）。ダイアレクトを混在させないでください。v6/v7時代の (tstamp ...) やv6の (width ...) グラフィックがv8/v9ヘッダー内にあると、ファイルが読み込めなくなる最も一般的な原因です。

必須条件

1. ファイルごとに1つのダイアレクト。 ヘッダーの version、generator_version、トラックUUID、ストローク構文、フットプリントフィールドはすべて、宣言されたバージョンと一致している必要があります。
2. 基板はスニペットではなく完全なファイルであること。 KiCadで開き、以下の構造チェッカーに合格する必要があります。
3. 接続性は幾何学的です。 正しいネット番号を持つトラックがパッドや他のトラックに接触していなければ、未配線のままです。
4. 暗黙の電気的推測は禁止。 ピンからネットへのマッピング、極性、フットプリントの選択、安全な間隔は、前提条件として明記するか、質問する必要があります。
5. 検証された製造制限なしに、製造準拠を主張しないでください。 製造数値はスタックアップおよびベンダーに固有です。
6. 合格レポートなしにリリースを主張しないでください。 ボードがリリース可能となるのは、report/design-report.json が professional_claim: true を示した場合のみです。それ以外の場合は、失敗したゲートと不足している承認をリストアップしてください。

自動設計パイプライン（新しい基板に推奨）

このパイプラインが実行可能な場合は、リリース基板を手動で作成しないでください。パイプラインは設計仕様を実際のKiCadライブラリフットプリントを持つ基板に変換し、Freeroutingで配線し、KiCad DRC + DFM + ネットリストパリティを実行し、ガーバー/ドリル/位置/STEP/IPC-D-356をエクスポートし、ゲートレポートを書き込みます。profile.fab_outputs にリストされているすべての出力はハードゲートです。手動での作成は、生成された基板の確認または修正にのみ使用してください。

# 1. 意図の検証（KiCadは不要）
python3 scripts/design_spec.py validate specs/led-blinky.json

# 2. 完全自動設計。ローカルでKiCad 9 pcbnew、Java 25、Freerouting 2.5.0が
#    利用可能な場合は自動的に選択し、それ以外の場合はGitHub Actionsに委譲します。
python3 scripts/design_pipeline.py all specs/led-blinky.json

# 電気的な信頼ソースは回路図またはネットリストです。仕様は機械的要素/ルールを提供します。
python3 scripts/design_pipeline.py all specs/led-blinky.json --schematic design.kicad_sch
python3 scripts/design_pipeline.py all specs/led-blinky.json --netlist design.net

# 既存の基板: 再構築せずに配線/チェック/エクスポート。
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build

# ステージのみ
python3 scripts/design_pipeline.py build specs/led-blinky.json -o build/led-blinky
python3 scripts/design_pipeline.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json
python3 scripts/design_pipeline.py check build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check
python3 scripts/design_pipeline.py fab   build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab

標準入力。 specs/<name>.json は自動パスの信頼できる情報源です。schemas/design-spec.schema.json と specs/led-blinky.json をモデルとして使用してください。自然言語リクエストの場合は、最初に仕様を作成し、assumptions[] に前提条件を記載してから、パイプラインを実行します。KiCad回路図/ネットリストの場合、ネットリストがコンポーネント/パッドネットの信頼できる情報源となり、仕様オーバーレイは基板サイズ、スタックアップ、ルール、配置、配線を提供します。

基板クラスプロファイル。 プロファイルはルールエンベロープとリリースゲートを選択します:

プロファイル	自動化	必要な人間による承認
2layer-low-speed	完全: 構築、配置、配線、DRC、DFM、製造	なし
4layer-impedance / 6layer-impedance	ゲート付き: スタックアップ + インピーダンス + 長さ整合チェック	stackup、impedance
rf-mixed-signal	アシスト; RFネットは手動で再配線する必要があります	rf、emc、thermal
flex-rigid	アシスト	mechanical、flex_bend、assembly
high-voltage	ゲート付き; クリアランス/沿面距離チェック	safety、creepage

professional_claim は、すべてのハードゲートに合格し、すべての必須承認が signoff.completed にリストされている場合にのみ true になります。RF、EMC、熱、安全性、フレックス疲労はパイプラインで認定できません。過剰に主張する代わりに、そのように明記してください。レビュー担当者を signoff.reviewer に記録します。

バックエンド選択: ローカルまたはCI（自動）。 完全自動化には pcbnew（KiCad 9 Python）、kicad-cli、Java 25、freerouting-2.5.0.jar（Freerouting 2.5.0はJava 25用にビルドされています）が必要です。--backend auto がデフォルトです。現在の環境をプローブし、要求されたすべてのステージにツールが揃っている場合はローカルで実行し、そうでない場合は .github/workflows/design.yml に委譲します。このワークフローは公式の kicad/kicad:9.0 コンテナで実行され、JRE 25をインストールし、Freeroutingをダウンロードし、パイプライン全体を実行し、design-output と design-report をアップロードします。

環境	プローブ結果	選択されたバックエンド
KiCad 9 + Java 25 + jar がインストールされた実際のPC	すべてのステージ準備完了	ローカル
KiCadなしのTermux/コンテナ; gh 認証済み; クリーンなプッシュ済みリポジトリ	pcbnew/kicad-cli なし	CI
ローカルツールも使用可能なCIもなし	欠落	ローカル、欠落ツールリストで失敗

python3 scripts/env_probe.py                        # このマシンで何が実行できるか？
python3 scripts/env_probe.py --json                 # 機械可読なプローブ
python3 scripts/design_pipeline.py all specs/led-blinky.json                     # 自動
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend local
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend ci --ci-download build/ci

CIディスパッチは慎重です。ダーティツリーまたは上流より先行しているブランチを拒否します。これは、Actionsがプッシュされたリビジョンをチェックアウトし、そうでなければ間違った基板を設計するためです。最初に仕様、プロファイル、スキーマ、スクリプト、ワークフローをコミットしてプッシュします。gh がインストールされ認証されている必要があります（pkg install gh、次に gh auth login）。現在のリポジトリ以外にディスパッチする場合にのみ --ci-repo owner/name を使用します。CI実行はデフォルトで監視され、終了コードは professional_claim を反映します。ディスパッチ後に即座に戻るには --no-ci-watch を追加します。

ステージコマンド（build、route、check、fab）はローカルで実行されます。これはCIがコミットされていないステージファイルを参照できないためです。エンドツーエンドのCI実行には all --backend ci を使用します。GitHub Actions内ではパイプラインは常にローカルに留まるため、CI実行が再度ディスパッチされることはありません。

反復ルール。 ゲートが失敗した場合は、仕様（配置、幅、クリアランス、スタックアップ、クラス割り当て）を変更して再生成します。生成された基板を編集してからレポートが適用されると主張しないでください。レポートは解決された正確な仕様（<name>.spec.json）を記録します。

検索ソース（推測する前に使用）

リソース	URL	用途
S式入門 (共通構文)	https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html	構文、引用、座標、レイヤー、フットプリント、パッド、グラフィック、ゾーン、グループ
ボードファイル形式	https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html	.kicad_pcb トップレベルセクション、ヘッダー、レイヤー、セットアップ、ネット、トラック、ゾーン
フットプリントライブラリ形式	https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html	.kicad_mod コンテキストとフットプリントフィールド
KiCadファイル形式インデックス	https://dev-docs.kicad.org/en/file-formats/index.html	一致する回路図が必要な場合の回路図/シンボル形式
KiCad DRCドキュメント	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking	実際のDRCがチェックする内容と設定可能なルール
KiCadカスタム設計ルール	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules	.kicad_dru 構文とルール式
JLCPCB製造能力	https://jlcpcb.com/capabilities/pcb-capabilities	現在の製造制限（使用前に確認）
IPC-2221 / IPC-2152	https://www.ipc.org/	トレース幅/電流、クリアランス、沿面距離の基礎

開発者ドキュメントは、アプリケーションに追いついていない箇所があります（まだv7以前の (width ...) グラフィックや (tstamp ...) トラックを説明しています）。ドキュメントと対象のKiCadバージョンの実際のファイルが矛盾する場合は、実際のファイルに従い、矛盾点をメモしてください。

ローカルリファレンスとアセット

パス	内容
references/pcb-file-format.md	バージョンマトリックス、セクション、レイヤー序数、セットアップ/スタックアップ、フットプリント、パッド、トラック、ゾーン、チェックリスト
references/sexpr-primitives.md	トークン構文、引用、ストローク、エフェクト、UUID、パッド/グラフィック/ゾーンプリミティブ、バージョン依存トークン
references/practical-rules.md	スタックアップ、配置、配線、電流/幅、SI/PI/EMI、インピーダンス、熱、機械、DFM/DFA、デフォルト
assets/minimal-2layer.kicad_pcb	バリデータでクリーンなブランク2層基板（開始点としてこれをコピー）
assets/example-led.kicad_pcb	バリデータでクリーンな配線済みサンプル: THTヘッダー、SMD抵抗/LED、ビア、カーヤード、実装穴
assets/example.kicad_dru	カスタムルールの例（ネットクラス幅、高電圧クリアランス）
schemas/design-spec.schema.json	標準自動設計仕様（基板、ルール、ネット、配置、スタックアップ、ゲート）
profiles/*.json	基板クラスルールエンベロープとリリースゲート
specs/led-blinky.json	自動パイプラインのリファレンス仕様
scripts/design_spec.py	依存関係のない仕様バリデータ、ネットリストインポーター、インピーダンス/電流計算、ゲートレポート
scripts/pcb_build.py	実際のKiCadフットプリントを使用した仕様→KiCad基板（pcbnew）
scripts/pcb_route.py	DSNエクスポート→Freerouting→SESインポート→ゾーンフィル
scripts/pcb_check.py	構造、DRC、DFM、ネットリストパリティ、長さ整合ゲート
scripts/pcb_fab.py	ガーバー、ドリル、位置、STEP、IPC-D-356、製造README
scripts/design_pipeline.py	自動設計全体を調整し、リリースレポートを書き込みます。--backend auto はローカルまたはCIを選択
scripts/env_probe.py	pcbnew、kicad-cli、Java 25、Freerouting、gh/gitを検出し、ローカルまたはCIを推奨
scripts/ci_dispatch.py	.github/workflows/design.yml をディスパッチし、オプションで監視してアーティファクトをダウンロード
scripts/check_pcb.py	依存関係のない構造/ジオメトリ事前チェッカー
.github/workflows/design.yml	CI: KiCad 9コンテナでの構築、配線、DRC/DFM、製造エクスポート、レポート

ドキュメントページ全体を取得する前に、これらのリファレンスで検索語句を使用してください: version、generator_version、layers、stackup、setup、net、footprint、property、attr、pad、stroke、segment、via、zone、keepout、filled_polygon、Edge.Cuts、embedded_fonts、remove_unused_layers、courtyard、impedance、differential、3W、return path、DFM、trace width。

手動/確認ワークフロー

最初に自動パイプラインを使用してください。このワークフローは、生成された基板を確認するため、仕様が制約を表現できない設計にパッチを適用するため、またはパイプラインツールが利用できない環境で作業するためのものです。

1. 設計意図を明確にする（重要な制約について黙って推測しない）。

   • 基板の機能、コンポーネント、コネクタ、電源/グラウンドネット、ターゲットサイズ、機械的制約。
   • 製造の前提: 層数（デフォルト2）、単位（mm）、銅箔厚、スタックアップ、表面仕上げ、組み立てプロセス。
   • ターゲットKiCadリリース。ユーザーが別途指定しない限り、デフォルトはKiCad 9。
   • 要件が不十分な場合は、応答で前提条件を明示的に述べ、ファイルに妥当なデフォルト値をエンコードします。

2. 最初に電気ネットリストをモデル化します。

   • アイテムが参照する前に、(net 0 "") とすべての名前付きネットを定義します。序数を安定かつ一意に保ちます。
   • すべてのパッド、トラック、ビア、ゾーン net 序数が存在することを確認します。パッド (net N "NAME") 名がネットテーブルと完全に一致することを確認します。
   • 対応する回路図が存在する場合、フットプリントには path/参照リンクが必要です。基板のみの設計は、適切な場所に board_only とマークする必要があります。

3. メカニクス、レイヤー、スタックアップを定義します。

   • assets/minimal-2layer.kicad_pcb から開始し、そのヘッダー/レイヤー/セットアップを有効に保ちます。
   • layers セクションを標準名と正しい序数で設定します（references/pcb-file-format.md の表を参照; B.CrtYd/F.CrtYd は連続していません）。
   • (general (thickness 1.6) (legacy_teardrops no))、(paper "A4")、およびスタックアップが重要な場合は現実的な stackup を設定します。
   • 閉じた Edge.Cuts 境界（ライン/アークまたは1つの矩形/円/ポリゴン）を提供します。銅箔を端から離します。

4. フットプリントを配置します。

   • 完全な埋め込みフットプリント定義を使用します: layer、uuid、at、property フィールド（Reference/Value）、attr smd|through_hole、パッド、シルクスクリーン、F.CrtYd/B.CrtYd カーヤード、オプションで F.Fab と3Dモデル。
   • 機能ごとに配置: コネクタ、電源入力、MCUを最初に。関連回路をグループ化。アナログ/デジタル/ノイズの多いドメインを分離。
   • 各ICの電源/グラウンドピンに、ループ面積を最小にしてデカップリングコンデンサを配置。値/パッケージはデータシートまたは記載された前提条件に従う。
   • カーヤードとアセンブリの間隔を尊重。リファレンスを読みやすくし、極性部品をマーク。

5. 接続を配線します。

   • トラックには segment、層変更には via、曲線トラックには arc を使用。KiCad 8/9のトラックは (uuid ...) を使用し、(tstamp ...) は使用しません（v6/7は tstamp を使用）。
   • 電流/スタックアップの意図から各アイテムの width を設定。信号よりも電源を広く。ネットクラスはプロジェクト/設計ルールファイルに存在し、.kicad_pcb にはありません。
   • トラックを短く/直接的に保ち、45°の曲がりを優先し、高速パス上のビアを最小化。
   • リターンパスを維持: プレーンスプリットを横切る高速/敏感なトレースを配線しない。クロストークが発生しやすい並行ランには約3Wの間隔を適用。
   • インピーダンス/差動ペアは setup とルールを介して処理。これは将来的なスタックアップリファレンスに含める必要があります。

6. ゾーンとプレーンを追加します（必要な場合）。

   • パワーまたはグラウンドの接続とシールドのためのゾーンを接続して定義します。(zone (net N) ...)。接続性（net + ゾーン接続パッド）に (priority ...) は不要。
   • (fill ...) と (polygon ...) でゾーンを塗りつぶし、(filled_polygon ...) が正しく生成されるようにアウトラインを提供。
   • ゾーンはデフォルトで (hatch ...) を使用しないでください（熱を求めている場合を除く）。代わりに solid または塗りつぶしポリゴンを使用。

7. 構造的にチェックします（スクリプトが利用可能な場合）。

   python3 scripts/check_pcb.py miniblink.kicad_pcb
   

   fail はチェックリストの違反を意味します。pass は、ファイルがKiCadにロードされ、座標範囲が適切であり、レイヤー/ネット/フットプリントが正しいことを意味します。

8. 構造チェックが通ったら、DRCに送信します（スクリプトが利用可能な場合）。

   python3 scripts/pcb_check.py drc myboard.kicad_pcb --dru assets/example.kicad_dru
   

9. 製造データをエクスポートします（必要な場合）。

   python3 scripts/pcb_fab.py gerbers myboard.kicad_pcb -o fab/
   

完全なワークフローの例:

# 前提: 既存の仕様
python3 scripts/design_spec.py validate specs/led-blinky.json

# 構築
python3 scripts/pcb_build.py build specs/led-blinky.json -o build/led-blinky

# 配線（DSN/SES）
python3 scripts/pcb_route.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json

# チェック（構造、DRC、DFM、ネットリストパリティ）
python3 scripts/pcb_check.py all build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check

# 製造エクスポート（ガーバー、ドリル、位置、STEP、IPC-D-356、README）
python3 scripts/pcb_fab.py all build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab

# リリースレポートレポートを生成（design_pipeline.pyの一部として自動的に行われます）
# python3 scripts/design_pipeline.py all specs/led-blinky.json -o build/led-blinky/release

トラブルシューティング

「空白の基板」問題

自動パイプラインによって生成された基板がKiCadで空白に見える場合（コンポーネントや銅箔がない）:

• 通常、生成された pos ファイルは正しいですが、KiCadのリフレッシュバグです。KiCadでファイル→リフレッシュ（F5）していることを確認してください。
• ファイルを閉じて再度開いてみてください。
• build/ ディレクトリ内の *.kicad_pcb ファイルを直接開いてみてください。
• それでも解決しない場合は、レイアウトを確認するために scripts/pcb_check.py を実行してください。scripts/check_pcb.py も軽量なクロスプラットフォームチェックに利用できます。

「これはリリース準備ができた基板ですか？」

自動パイプラインが design-report.json を生成すると、次のものが含まれます:

• professional_claim: true/false — 「プロフェッショナル」は、すべてのハードゲート（DFM、DRC、ネットリストパリティ、製造出力）に合格し、必須の人間による承認が記録されたことを意味します。
• 各ゲートのステータス（pass/fail/untested/n/a）。
• 人間による承認が必要なゲート（RF、EMC、熱、安全、フレックス疲労）なので、パイプラインは professional_claim を直接検証しないことに注意してください。
• 出力ディレクトリ内のデフォルトの製造出力一式。

ファイルが自動パイプラインによって生成されたものでも、手動で編集されたものでも、製品品質かどうかを尋ねられた場合、常にレポートを確認する必要があります。リリースレポートなしに professional_claim: true を主張しないでください。

互換性"

このスキルはKiCad 9を対象としており、KiCad 8との後方互換性があります。常に (version ヘッダーを正しいダイアレクトで設定し、出力 .kicad_pcb ファイルにわたってレイヤー序数が一貫していることを確認してください。references/pcb-file-format.md は、ダイアレクト間の変更点の詳細なマトリックスを提供します。

例

specs/led-blinky.json リファレンスと assets/example-led.kicad_pcb アセットは、機能する例として提供されています。

トラブルシューティング

• スクリプトの問題については、scripts/ ディレクトリのREADMEを参照してください。
• ファイルの検証には scripts/check_pcb.py を使用してください。
• エラーログを報告するために詳細フラグ（-v）を渡してください。