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

> Quick reference for .trace/rules.md — project-specific AI preferences that shape how Trace designs your circuits.

`.trace/rules.md` is a plain Markdown file that tells the AI **how you want to design**. Write your preferences once; the AI follows them every session — no repeating yourself.

<Info>
  For a full conceptual overview, examples, and best practices, see [Core Concepts → TraceRules](/concepts/tracerules).
</Info>

## File Location

```
my-project/
├── my-board.kicad_sch
├── my-board.kicad_pcb
└── .trace/
    ├── rules.md       ← Your preferences (you edit this)
    └── context.md     ← AI-maintained notebook (AI edits this)
```

The AI loads rules from the first file it finds, in priority order:

1. `.trace/rules.md` (recommended)
2. `.tracerules` in the `.kicad_pro` directory
3. `.tracerules` in the project root

## What You Can Configure

| Category                    | Example Rules                                                                    |
| --------------------------- | -------------------------------------------------------------------------------- |
| **Placement strategy**      | "Place decoupling caps within 2mm of IC power pins", "Group by functional block" |
| **Manufacturer target**     | "Preferred fab: JLCPCB 4-layer", "Min trace width: 6mil", "Surface finish: ENIG" |
| **Passive sizes**           | "0402 imperial default", "0201 where space-constrained"                          |
| **Clearance & trace width** | "Power traces: minimum 20mil for 1A", "USB diff pair: 90Ω impedance"             |
| **Thermal relief**          | "Thermal relief on all ground pads", "Direct connect for high-current pads"      |
| **DRC ignore categories**   | "Ignore silkscreen overlap warnings", "Skip courtyard checks on test points"     |
| **Routing conventions**     | "No acute angles on high-speed signals", "Route clocks on inner layers"          |
| **Component preferences**   | "Prefer parts with JLCPCB stock", "AEC-Q200 rated passives"                      |

## Quick Setup

### From the Desktop App

Open the TraceRules editor from the chat panel menu: **⋮ → TraceRules**

### From the CLI

```bash theme={null}
buildwithtrace rules init                    # create starter .trace/rules.md
buildwithtrace rules set "Use 0402 passives" # append a rule
buildwithtrace rules show                    # print current rules
buildwithtrace rules edit                    # open in $EDITOR
```

### By Hand

Create `.trace/rules.md` in your project and write in plain Markdown:

```markdown theme={null}
# Design Rules

## Manufacturer
- Fab: PCBWay 4-layer, 1.6mm, 1oz copper
- Min trace/space: 0.127mm/0.127mm
- Min via: 0.3mm drill, 0.6mm pad

## Components
- Passives: 0402 imperial
- All parts must be in-stock at LCSC

## Layout
- Decoupling caps within 2mm of power pins
- USB connector on top edge
- Programming header accessible without disassembly

## Routing
- USB: 90Ω differential impedance
- Power: 0.5mm minimum width
- SPI clock: inner layer preferred
```

## How the AI Uses Rules

Every time you start a conversation, the AI:

1. **Reads** `.trace/rules.md` for your explicit preferences
2. **Reads** `.trace/context.md` for accumulated project knowledge
3. **Applies** manufacturer DFM constraints if you've specified a fab
4. **Follows** your conventions throughout the session

If a rule conflicts with electrical safety or engineering best practices, the AI prioritizes correctness and explains why.

## Workspace Context (.trace/context.md)

This companion file is **maintained by the AI automatically**. It acts as a design notebook that persists learnings across conversations:

* Component decisions and rationale
* 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 it to see what the AI has learned, but generally should not edit it — the AI keeps it current. Each project has its own independent context file.

## Tips

<Tip>
  **Be specific.** "Use 10K pull-ups on I2C" is better than "use appropriate pull-ups." Concrete rules produce consistent results.
</Tip>

<Tip>
  **Layer preferences by priority.** Put your most important constraints first — the AI weighs earlier rules more heavily when resolving conflicts.
</Tip>

<Tip>
  **Combine with DRC Import.** Import your manufacturer's `.kicad_dru` file to get machine-checked constraints in addition to your natural-language preferences. See [DRC Import](/concepts/drc-import).
</Tip>

## Related

* [TraceRules — Full Guide](/concepts/tracerules) — Detailed concepts, workspace context, and complete examples
* [DRC Import](/concepts/drc-import) — Import manufacturer constraint files
* [CLI `rules` Command](/resources/cli-commands#buildwithtrace-rules) — Manage rules from the terminal