Crystals

A crystal is a fact established once, never re-derived. It lives in a CLAUDE.md file and loads at session start. Crystals prevent your AI from rediscovering what you already know.

When to create a crystal

Create a crystal when you have established a fact through hard work and do not want to re-establish it.

Signs that something should become a crystal:

• You have explained it to your AI more than twice
• It took significant effort to figure out
• It constrains decisions in multiple sessions
• Getting it wrong wastes substantial time

Do not crystallise everything. Crystals add cognitive load to your AI's context window. Only crystallise facts that genuinely need to persist.

The three tiers

Crystals have confidence levels. Use the tier markers to signal stability.

Tier	Symbol	Meaning
Confirmed	◆	Stable fact. Tested. Will not change without explicit revision.
Working	◈	Useful assumption. Currently accurate. May evolve with new information.
Provisional	◇	Hypothesis. Testing it. Might be wrong.

Tier progression is one-directional. Provisional → Working → Confirmed. If a confirmed crystal turns out to be wrong, delete it and create a new provisional one. Do not demote.

Writing good crystals

Good crystals are:

• Specific: Not "use good naming conventions" but "function names are verbNoun, e.g. getUserProfile"
• Actionable: Your AI can apply the crystal immediately
• Bounded: One fact per crystal, not a paragraph of context
• Dated: Include when the crystal was established

Bad crystals are vague, compound, or redundant with information your AI already has.

Examples

Good crystals:

| ◆ | Repo uses pnpm, not npm | 2024-03-15 |
| ◆ | All API routes return `{ data, error }` shape | 2024-03-12 |
| ◈ | User auth state lives in Zustand, not context | 2024-03-18 |
| ◇ | Edge functions may be faster than serverless for auth | 2024-03-20 |

Bad crystals:

| ◆ | Write clean code | ← too vague |
| ◆ | Use TypeScript and make sure types are good | ← compound, vague |
| ◆ | Don't use var | ← redundant (AI knows this) |

Crystal placement in CLAUDE.md

Crystals live in a table in your room's CLAUDE.md file. Place them near the top, after identity context but before detailed instructions.

# Dev Room

## Identity
This is the development workspace for project-x.

## Crystals
| Tier | Crystal | Established |
|------|---------|-------------|
| ◆ | Monorepo: apps/web, apps/api, packages/shared | 2024-03-01 |
| ◆ | Deploy target: Vercel (web), Railway (api) | 2024-03-01 |
| ◆ | Auth: Clerk, not custom | 2024-03-05 |
| ◈ | State: Zustand for client, tRPC for server | 2024-03-10 |
| ◇ | Consider Drizzle over Prisma for edge compat | 2024-03-18 |

## Workflow
...

Crystal hygiene

Review crystals monthly. Ask:

• Is this still true?
• Did this ever get used?
• Should this be promoted or deleted?

Delete crystals that are no longer relevant. A cluttered crystal table slows your AI's comprehension. Ten sharp crystals beat fifty vague ones.

TIP

When a crystal becomes part of your muscle memory and you no longer need your AI to know it, delete it. Crystals are for bridging the gap between your knowledge and your AI's starting state.

Crystals vs loci

Crystals are facts for your AI. Loci are insights for navigation.

A crystal says "this is true, act on it." A locus says "this is significant, remember it exists."

Crystals go in CLAUDE.md. Loci go in .locus files. Crystals are consumed at session start. Loci are referenced when needed.

When something is both a fact to act on and an insight to navigate by, put it in both places.