--- id: daily-reference-design name: "reference-design" url: https://skills.yangsir.net/skill/daily-reference-design author: diodeinc domain: hardware tags: ["hardware-design", "circuit-design", "reference-design", "engineering", "documentation"] install_count: 799 rating: 4.20 (20 reviews) github: https://github.com/diodeinc/pcb --- # reference-design > 构建可复用的应用电路，捕获支持电路、默认模式、关键方程和布局注意事项 **Stats**: 799 installs · 4.2/5 (20 reviews) ## Before / After 对比 ### 电路设计效率对比 **Before**: 每次都从零开始设计电路，重复查阅数据手册并手动计算参数，一个设计需要2-3天，容易出错 **After**: 复用成熟的参考设计，直接获取验证过的电路和参数，半天内完成设计，可靠性大幅提升 | Metric | Before | After | Change | |---|---|---|---| | 设计时间 | 72小时 | 4小时 | -94% | ## Readme # reference-design # Reference Design Build reusable application circuits, not generated IC wrappers. A good reference design captures the support circuitry, default mode, key equations, layout-sensitive notes, and evidence needed to use the part confidently. ## Hard Rules - Reuse before create. Search existing registry/workspace modules and reference designs first. - Do not create a pin breakout or generated wrapper and call it a reference design. - The `.zen` docstring is the canonical design document. The README is for usage examples only. - `pcb build` warnings matter. Review them, especially BOM/sourceability warnings such as `bom.match_generic`. - Do not guess ambiguous passives, straps, sequencing, or oscillator details. Get evidence or stop and ask. - Imitate only strong exemplars. Weak/generated packages are useful for pin lookup, not authoring style. - Preserve `# pcb:sch ...` comments. They carry tool-managed schematic layout metadata. Do not delete them. If you rename a referenced component, module instance, or net, update the corresponding `# pcb:sch` names too. ## Reuse Before Create - Search registry modules/reference designs with `component-search`. - Search registry components or import the IC if it is missing, then inspect close matches with `pcb doc --package ...` and by reading their source. - If an existing design is close, prefer using it or patching it. - Create a new reference design only when it adds real reusable design judgment. Do not create a new reference design yet if: - the datasheet does not clearly specify the required support circuitry - the topology still depends on unresolved system-level choices - the result would mostly duplicate an existing package with only minor edits - the IC symbol/component quality is too poor to wire confidently ## Strong Vs Weak Exemplars Strong exemplars usually have most of these traits: - minimal, integrator-facing IO instead of exposing every raw IC pin - typed configs for real design choices - passive values traceable to datasheet tables, equations, or app-note guidance - optional features modeled cleanly, with evidence notes for non-obvious choices - sourceable generic choices or documented house-part compromises - useful usage examples, and layout/testbench artifacts when complexity warrants them Weak/generated exemplars usually show warning signs such as: - mostly raw IC pins exposed directly - little or no design rationale, or magic values with no evidence - no attempt to capture the intended application circuit - no sourceability thinking - README content that is generic, marketing-like, or duplicated from the code Use weak examples for package API lookup only. ## Quality Bar A high-quality reference design is electrically faithful, narrowly scoped, reasonably sourceable, and evidence-backed. Treat the `.zen` file as the design artifact, not just executable code. ## Evidence Extraction Extract at least: - the exact typical application circuit or recommended topology - supply rails, limits, sequencing, and required external passives - strap, mode-select, reset, enable, bias, compensation, and timing networks - equations for programmable values and any datasheet-recommended example points - oscillator or crystal requirements, sensitive analog/high-speed connections, and thermal/layout guidance - any package-specific caveats that change how the design should be exposed When the datasheet is ambiguous, look for app notes, eval schematics, or nearby validated registry designs before guessing. ## Define The Public API First Reference-design API rules: - Expose the application-level interface, not the raw pinout. - Keep layout-sensitive or implementation-detail nodes internal unless external access is genuinely required. - Expose configs only for choices an integrator should reasonably tune; do not expose every passive. - Prefer one narrow, coherent operating mode over a sprawling universal module. - If two operating modes materially change topology, consider separate designs instead of config explosion. ## Scaffold And Implement ### Directory layout and naming Name the reference design from the functional MPN, not the full orderable SKU. Use these rules: - Start from the manufacturer part number. - Keep functional variation in the name: electrical options and package/pinout differences stay. - Replace non-functional variation with lowercase `x`: temperature grade, reel/tray packaging, RoHS/Pb-free, and other ordering-only suffixes. - If the only wildcarded characters would be trailing non-functional suffixes, omit the trailing `x`. - If there is only one functional variant, do not add an unnecessary `x`. - If the part exists in multiple footprint or pinout options, make a separate reference design for each one. - If multiple manufacturers make footprint-compatible parts with different package suffixes, use the common base name plus a clear package suffix. Examples: - `DP83867ISRGZR` -> `DP83867` - `TPS3430WDRCR` -> `TPS3430WDRC` - compatible cross-vendor variants with different package suffixes -> `L78L05_TO92` Use `` for the resolved reference-design name from the rules above, for example: ``` reference// ├── .zen ├── pcb.toml └── README.md ``` Scaffold with `pcb new package reference/`. ### File structure Organize the `.zen` file in this order: - Top-of-file docstring - `load()`s and helper definitions - `io()` and `config()` definitions - internal nets and imports - main IC instantiation and supporting circuitry grouped by function - layout / tool-managed metadata Group support circuitry by electrical function: power, decoupling, feedback, straps, clocks, reset, interface conditioning, protection. Keep the `# pcb:sch ...` block intact and in sync with renames. ### Docstring policy Include: - what circuit/application mode this module implements - the exact IC/package or family it targets - the intended operating envelope, interfaces, configs, and assumptions - evidence notes for important choices and non-obvious layout guidance - sourceability compromises such as house-part rounding when relevant Keep this in the `.zen` file so the code and rationale stay together. ### Comment policy Good comment targets: - datasheet section/table/equation references - justification for rounded/clamped values - optional-feature stuffing strategy or layout-sensitive placement guidance Avoid comments that merely restate the code. ## Sourceability And BOM Quality Read `registry/.pcb/stdlib/bom/match_generics.zen` when sourceability choices matter. The stdlib matcher only covers a constrained house catalog, so generic values, packages, dielectric choices, and voltage ratings affect whether parts match. Use these rules: - Treat `pcb build` warnings as review items, especially `bom.match_generic`. - Prefer generic values/package/voltage combinations that match house parts when that does not compromise the design. - If the datasheet value does not match house parts, a nearby house value is acceptable only when the change is technically defensible. - Whenever you round, clamp, or substitute to land on a house-matchable value, document the reason in the docstring or a nearby comment. - If a generic cannot reasonably match, do not silently force a workaround. Ask the user whether they want to specify an explicit part or suppress the warning with justification. Typical fixes are choosing the nearest valid house value above a datasheet minimum, clamping computed values to supported parts, or adjusting package/voltage choices without violating the design. Use `pcb bom -f json` when you need sourcing detail beyond the matcher. ## Build Iteratively Build after every major block, not just at the end. ``` pcb build reference/ ``` Typical problems: - wrong interface field names or package wiring - missing `load()`s, bad stdlib assumptions, or ambiguous optional-feature modeling - unmatched generics or values that are plausible electrically but not sourceable Format when done: ``` pcb fmt reference/ ``` ## README Policy Use it for: - realistic instantiation examples - different application contexts when they materially change integration - concise consume-the-module notes only Do not put general feature lists, design notes, or long rationale sections in the README. That belongs in the `.zen` docstring. Minimal README shape: ``` # Reference Design ## Usage ```python MyRef = Module("github.com/diodeinc/registry/reference//.zen") MyRef( name="U1", VIN=vin, VOUT=vout, GND=gnd, ) ``` ## Other Usage Examples Add additional examples only when they show materially different integration patterns. ``` ## Stop Conditions Stop and ask or gather more evidence when: - the datasheet is unclear about a required passive, strap, or topology choice - the design depends on unresolved system-level requirements - the imported component/symbol quality is too poor to wire safely - `pcb build` warnings suggest unresolved correctness or sourceability issues - the design is drifting into a generic breakout instead of a reference module ## Final Checklist - Existing registry/workspace packages were checked first. - The module implements one coherent application circuit. - The docstring explains the design, evidence, and any sourceability compromises. - `pcb build` was run and warnings were reviewed. - `pcb fmt` was run, and the README contains usage examples only. Weekly Installs452Repository[diodeinc/pcb](https://github.com/diodeinc/pcb)GitHub Stars206First SeenMar 17, 2026Security Audits[Gen Agent Trust HubPass](/diodeinc/pcb/reference-design/security/agent-trust-hub)[SocketPass](/diodeinc/pcb/reference-design/security/socket)[SnykWarn](/diodeinc/pcb/reference-design/security/snyk)Installed onclaude-code446amp53cline53github-copilot53codex53kimi-cli53 --- *Source: https://skills.yangsir.net/skill/daily-reference-design* *Markdown mirror: https://skills.yangsir.net/api/skill/daily-reference-design/markdown*