diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f974c3a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,35 @@
+# Claude Code Instructions — Schema Refinement
+
+## Project Context
+This is a fabric-orchestrator project managing Arista EVPN-VXLAN fabrics.
+Branch: `feature/41-infrahub-schema`
+Schema files are in `schemas/` directory (Infrahub YAML format).
+
+## Reference Topology (from overlaid.net)
+- 2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001-65004)
+- Loopback0: BGP router-id, Loopback1: shared VTEP IP per MLAG pair
+- VLANs 4090/4091: MLAG peering with trunk groups
+- EVPN overlay via eBGP multihop on loopbacks
+- L2VXLAN (Type-2) and L3VXLAN (Type-5) with VRFs
+
+## Infrahub Schema Rules
+1. `human_friendly_id` attributes MUST have `unique: true`
+2. If human_friendly_id needs to be scoped per-device, traverse Parent
+   relationships: `parent_rel__parent_attr__value`
+3. Parent relationships need `optional: false` explicitly
+4. Self-referencing relationships need `direction: outbound`
+5. Multiple relationships to same peer type need unique `identifier`
+6. Validate with: `infrahubctl schema check schemas/`
+
+## Commit Convention
+- Reference issue: `fix(schema): description — refs #41`
+- One logical change per commit
+- Run schema validation before committing
+
+## Files
+- `schemas/base.yml` — Device, Interfaces, IPAddress
+- `schemas/bgp.yml` — AS, BGPRouterConfig, PeerGroup, Session, AF
+- `schemas/vlan_vxlan.yml` — VLAN, VNI, VTEP, VlanVniMapping, EVPN
+- `schemas/vrf.yml` — VRF, RouteTarget, VRFDeviceAssignment
+- `schemas/mlag.yml` — MlagDomain, MlagPeerConfig, MlagInterface
+- `schemas/extensions.yml` — UnderlayLink, HostConnection, FabricSettings