> ## 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

> Define custom rules that shape how the AI designs your circuits. Like .cursorrules for hardware — persistent context that augments the AI's default behavior.

<Info>
  `.tracerules` is currently in beta while we evaluate quality benchmarks with and without custom rules enabled. Available to [beta program](/resources/beta) members.
</Info>

## 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.

<Tip>
  We recommend using `.trace/rules.md` for new projects. The `.tracerules` file at the project root is still fully supported for backward compatibility.
</Tip>

## 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:

```markdown theme={null}
# 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
* Custom-generated symbols and footprints (parts created from a datasheet or by request, rather than pulled from a library)
* 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.

<Note>
  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.
</Note>

## 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.

<Warning>
  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.
</Warning>

## What to Put in .tracerules

Good rules are things the AI can't infer from your schematic alone:

| Category                  | Examples                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **Component preferences** | Preferred manufacturers, package sizes, distributor priorities                       |
| **Schematic conventions** | Pin placement style, sheet organization, naming conventions                          |
| **Layout constraints**    | Routing priorities, placement zones, stackup preferences                             |
| **Manufacturing targets** | Preferred 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)

<Tip>
  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.
</Tip>

## 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:

```markdown theme={null}
# 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](https://buildwithtrace.com/dashboard/beta/feedback).