Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt

Use this file to discover all available pages before exploring further.

.tracerules is currently in beta while we evaluate quality benchmarks with and without custom rules enabled. Available to beta program members.

​
What It Does

A .tracerules file in your project gives the AI persistent context about how you want to design. Instead of repeating preferences every conversation, you write them once and the AI follows them automatically. Think of it like .cursorrules for hardware: custom instructions that augment the AI’s default behavior without replacing it. The AI still knows electronics — your rules add your specific style, conventions, and constraints on top.

​
File Location

TraceRules live in a .trace/ directory at the root of your project: 
my-project/
├── my-board.kicad_sch
├── my-board.kicad_pcb
├── .tracerules            ← Legacy location (still supported)
└── .trace/
    ├── rules.md           ← Your preferences (you edit this)
    └── context.md         ← AI-maintained notebook (AI edits this)
The AI looks for rules in the following locations, in priority order:
  1. .trace/rules.md in the project directory
  2. .tracerules in the same directory as the active .kicad_pro file
  3. .tracerules in the project root directory
Only one file is loaded per session. If multiple exist, the highest-priority one wins.
We recommend using .trace/rules.md for new projects. The .tracerules file at the project root is still fully supported for backward compatibility.

​
Rules File Format

.trace/rules.md (or .tracerules) is a plain Markdown file. The AI reads it at the start of every conversation. Write your preferences in natural language: 
# Project Rules

## Manufacturer
- Preferred manufacturer: Pikkolo Assembly (Denver, CO)
- Board thickness: 1.6mm
- Minimum trace width: 6mil
- Minimum via: 0.3mm drill, 0.6mm pad

## Component Preferences
- Passives: 0402 imperial (0201 where space-constrained)
- Resistor tolerance: 1% default
- Capacitor voltage: minimum 2x operating voltage
- Prefer parts with JLCPCB stock

## Placement Strategy
- Place decoupling caps within 2mm of IC power pins
- Group by functional block
- Keep crystal oscillator within 5mm of MCU

## Routing Conventions
- USB differential pairs: 90 ohm impedance
- Power traces: minimum 20mil for 1A
- No acute angles on high-speed signals

## Design Conventions
- Use hierarchical sheets for repeated blocks
- Net naming: UPPERCASE for power, CamelCase for signals

​
Workspace Context

.trace/context.md is maintained by the AI automatically. It learns about your project across conversations and records:
  • Component decisions and why they were chosen
  • Layout constraints discovered during routing
  • DFM feedback from previous manufacturing attempts
  • Design history and tradeoffs
You can read this file to see what the AI has learned, but generally should not edit it — the AI keeps it current.
The context file is project-scoped. Each project accumulates its own context independently, so rules and learning from one board don’t bleed into another.

​
How the AI Uses Your Rules

When you start a conversation, the AI:
  1. Reads .trace/rules.md for your explicit preferences
  2. Reads .trace/context.md for project history and learned constraints
  3. Applies manufacturer DFM constraints if you’ve specified a preferred manufacturer
  4. Follows your placement, routing, and component conventions throughout the session
If your rules specify a manufacturer, the AI automatically validates designs against that manufacturer’s capabilities in real-time — flagging violations like trace widths below their minimum or vias smaller than their drill capabilities.
Rules are additive — they augment the AI’s knowledge, they don’t override electrical correctness. If a rule conflicts with safety or best practices (e.g., “never use decoupling capacitors”), the AI will follow engineering best practices and explain why.

​
What to Put in .tracerules

Good rules are things the AI can’t infer from your schematic alone:
CategoryExamples
Component preferencesPreferred manufacturers, package sizes, distributor priorities
Schematic conventionsPin placement style, sheet organization, naming conventions
Layout constraintsRouting priorities, placement zones, stackup preferences
Manufacturing targetsPreferred fab house, DRC limits, assembly constraints
Project context”This is a battery-powered wearable” or “This is a high-reliability aerospace board”

​
What Not to Put

  • Electrical fundamentals the AI already knows (it knows to add bypass caps)
  • Overly broad instructions (“make it good”)
  • Contradictory rules that fight each other
  • Sensitive information (API keys, credentials)
Be specific. “Use 10K pull-ups on I2C lines” is better than “use appropriate pull-ups.” The more concrete your rules, the more consistently the AI follows them.

​
TraceRules Editor

Access the editor from the chat panel menu (⋮ → TraceRules). You can:
  • View and edit your rules directly in-app with Markdown syntax highlighting
  • Open the file in Finder (macOS) or Explorer (Windows) for editing in your preferred text editor
  • Create a new .trace/rules.md file if one doesn’t exist yet
Changes are picked up by the AI on the next conversation — no restart required.

​
Example: Full Project Setup

Here’s a complete .trace/rules.md for a typical IoT product: 
# Smart Sensor Hub — Design Rules

## Target
- Battery-powered environmental sensor hub
- Target: 2+ year battery life on 2x AA
- Operating temp: -20°C to +60°C

## Manufacturer
- Fab: JLCPCB 4-layer, 1.0mm thickness (space-constrained)
- Assembly: JLCPCB SMT (extended parts OK)
- Surface finish: LeadFree HASL (cost-sensitive)
- Min trace/space: 0.127mm/0.127mm

## Components
- MCU: Nordic nRF52840 (BLE + Thread)
- Passives: 0402 imperial, 1% resistors
- All parts must have JLCPCB Extended stock
- Prefer AEC-Q200 rated passives for temperature range

## Layout
- Antenna keep-out: no copper/components within 5mm of antenna trace
- Battery connector on board edge, accessible without disassembly
- Programming header on bottom layer, accessible through enclosure slot
- Thermal relief on all ground pads

## Power
- Use TPS62840 for main 3.3V rail (quiescent < 100nA)
- Separate analog/digital ground planes, connect at single point
- All power traces: minimum 0.3mm width

## Routing
- BLE antenna: 50 ohm microstrip, length-matched to reference design
- I2C bus: 4.7K pull-ups to 3.3V, max trace length 100mm
- SPI clock: keep under 50mm, route on inner layer if possible

​
Evaluating Quality

We’re actively benchmarking the AI’s output quality with and without .tracerules enabled. If you’re in the beta, your feedback on whether rules improve or degrade output quality helps us tune the system. Submit feedback from the beta dashboard.