KiCad PCB Design skill for Codex

Done well means: ERC and DRC run clean (or every exclusion is justified in writing) with the fab’s actual rules loaded, every footprint and pin mapping was checked against its datasheet, and the fabrication package is generated by a repeatable command, not by hand clicks that differ each release.

What Codex can and cannot do here

• Can: run kicad-cli checks and exports, parse JSON reports, read .kicad_sch and .kicad_pcb (text S-expressions) to review nets, values, footprints and properties, diff revisions, and write review findings.
• Should not: hand-edit placement, routing or symbol graphics in the S-expression files. Coordinates and UUIDs are easy to corrupt. Recommend the change and let the user make it in the editor, or use KiCad’s scripting API for bulk property edits.
• Cannot judge from files alone: physical fit, thermal behaviour, signal integrity on fast buses. Flag these for human review or simulation.

Inspect first

1. Read AGENTS.md, then the project: *.kicad_pro, *.kicad_sch (and sub-sheets), *.kicad_pcb, sym-lib-table, fp-lib-table, project libraries.
2. Check the KiCad version that saved the files ((version ...) and (generator_version ...) at the top). Files saved by KiCad 9 do not open in 8; never re-save in a newer version without telling the user.
3. Ask for the target fab and service (standard 2-layer, 4-layer, assembly) and download or request its capabilities: minimum track/space, drill, annular ring, solder mask bridge.

kicad-cli version
kicad-cli sch erc --format json --severity-all -o erc.json board.kicad_sch
kicad-cli pcb drc --format json --schematic-parity --severity-all -o drc.json board.kicad_pcb

kicad-cli must be installed on the host (it ships with KiCad). Add --exit-code-violations in CI so violations fail the job.

Reading reports

python3 - <<'EOF'
import json, collections
for name in ("erc.json", "drc.json"):
    data = json.load(open(name))
    items = [v for sheet in data.get("sheets", [data]) for v in sheet.get("violations", [])]
    items += data.get("unconnected_items", []) + data.get("schematic_parity", [])
    c = collections.Counter((v.get("severity"), v.get("type")) for v in items)
    print(name, sum(c.values()))
    for (sev, typ), n in c.most_common():
        print(f"  {sev:<8} {typ:<40} {n}")
EOF

Group by type, fix the highest-count real problems first, and only exclude a violation with a comment explaining why (exclusions are stored in the project and show in review).

Schematic review checklist

• Every IC pin checked against the datasheet pinout for the exact package (QFN vs TSSOP pin numbers differ); symbol pin numbers match the footprint pads
• Power: each supply has a source, rating and decoupling; PWR_FLAG only where a net really is driven from outside (connector, regulator output not modelled)
• Decoupling: 100 nF per power pin plus bulk capacitance per rail; values from the datasheet’s recommended circuit, voltage rating at least 2 times rail for MLCCs (DC bias derating)
• Pull-ups on I2C (once per bus), open-drain lines, reset and boot/strap pins
• Reverse polarity, ESD and over-current protection on external connectors
• Unused inputs tied, not floating; unused outputs left open
• Test points on power rails, reset, programming/debug signals (SWD, UART)
• Every symbol has a footprint, value, and manufacturer part number (MPN) field for BOM

Footprints

• Prefer KiCad standard library footprints; for custom ones, check pad size, pitch and pin 1 against the manufacturer’s recommended land pattern, not just the package drawing.
• Check with the 3D viewer that connectors face the board edge and polarised parts are oriented as the silkscreen shows.
• Assembly services rotate parts by their own conventions; verify the first board’s placement preview from the fab rather than trusting the export.

Layout rules of thumb

Topic	Rule
Ground	Solid ground plane on a layer next to signals (layer 2 on 4-layer); avoid splitting it
Decoupling	Capacitor between the pin and the via to ground, shortest loop; one via per pad
Return paths	Do not route fast signals across plane gaps or splits
Trace width	Size from current and allowed rise per IPC-2152 (KiCad calculator); 0.25 mm signal is a common default, power wider
Crystals	Close to the MCU, guard with ground, no traces underneath
USB 2.0	90 ohm differential pair, matched length, ESD diodes at the connector
Switching regulators	Follow the datasheet layout; keep the hot loop (input cap, switch, diode) tiny
Mechanical	Mounting holes, keep-outs and connector positions from the enclosure drawing first

Put these into the board setup as netclasses and custom rules so DRC enforces them rather than relying on memory:

(rule "USB diff pair"
  (condition "A.inDiffPair('/USB_D')")
  (constraint diff_pair_gap (opt 0.15mm))
  (constraint diff_pair_uncoupled (max 3mm)))

Get the gap and width for 90 ohm from the fab’s stackup impedance calculator.

Fabrication outputs

mkdir -p fab
kicad-cli pcb export gerbers --board-plot-params -o fab/gerbers/ board.kicad_pcb
kicad-cli pcb export drill --format excellon --excellon-separate-th -o fab/gerbers/ board.kicad_pcb
kicad-cli pcb export pos --format csv --units mm --side both -o fab/positions.csv board.kicad_pcb
kicad-cli sch export bom -o fab/bom.csv board.kicad_sch
kicad-cli sch export pdf -o fab/schematic.pdf board.kicad_sch

• --board-plot-params uses the layer selection saved in the board’s plot settings; check that every copper, mask, paste, silkscreen and Edge.Cuts layer is included.
• Many fabs want specific BOM and position column names; map them with a script or the BOM export field options and keep that mapping in the repo.
• KiCad 9 jobsets can store the whole output set in the project; prefer them when the team is on KiCad 9.
• Open the Gerbers in KiCad’s GerbView or the fab’s online viewer before ordering.
• Ordering boards costs money: prepare the package, but let the user place the order.

Repository hygiene

*-backups/
*.kicad_prl
fp-info-cache
\#auto_saved_files\#
_autosave-*
fab/

Commit project-specific symbol and footprint libraries (with 3D models) inside the repo and reference them through ${KIPRJMOD} in the library tables, so the project opens on another machine. Tag each fabricated revision and keep its exact output package.

Verification

• ERC: zero errors; warnings either fixed or excluded with a written reason
• DRC with the fab’s rules and --schematic-parity: zero errors and no unconnected items
• Footprint and pinout check against datasheets recorded for every IC and connector
• Gerbers and drill files reviewed in a viewer; board outline closed; layer count right
• BOM has an MPN for every placed part; position file rotation checked on the fab preview

Report

**Project:** sensor-node rev C, KiCad 9.0, 4-layer, JLCPCB standard rules
**ERC:** 0 errors, 2 warnings excluded (PWR_FLAG on USB VBUS, unused op-amp channel tied)
**DRC:** 0 errors after raising USB pair gap to 0.15 mm; 0 unconnected; parity clean
**Review findings:** U3 footprint is TSSOP but MPN is QFN (blocker); missing pull-up on SCL (major)
**Outputs:** fab/ (gerbers, drill, positions.csv, bom.csv, schematic.pdf); not ordered