Session 3: Briefing Your AI Colleague

Duration: 2 hours
Prerequisites: Sessions 1-2 completed, environment working
You'll need: Leigher project open in Claude Code

Part 1: What CLAUDE.md Does (20 min)

The Problem

You've connected Claude to your project. It can read files, write code, and make changes. But it doesn't know:

What this project is
How things work here
What you always want
What you never want

Without this context, Claude guesses. It uses generic patterns. It makes choices that don't match your conventions.

The Solution

CLAUDE.md is a file in your project root that tells Claude how to work with your codebase. Claude reads it at the start of every session—before looking at any code.

Think of it as onboarding a new team member. You wouldn't just give them Figma access and say "go." You'd explain the project, the conventions, where to find things.

CLAUDE.md is that explanation, written once, applied to every Claude session.

What Changes

Without CLAUDE.md:

Claude uses generic React patterns
Claude picks arbitrary colors
Claude creates new components instead of using existing ones
Claude doesn't know your naming conventions

With CLAUDE.md:

Claude follows your specific patterns
Claude uses your design tokens
Claude checks existing components first
Claude matches your conventions

Part 2: What Goes in CLAUDE.md (40 min)

The Essential Sections

A good CLAUDE.md has these sections:

What is this project? — Brief context
Project structure — Where things live
Tech stack — What technologies are in play
Where to find details — Pointers to other docs
Critical rules — Things that apply to every task
Quick start — How to run the project

Let's build each section.

Section 1: What is this project?

Two or three sentences. Just enough for Claude to understand the domain.

## What is Leigher?

AI-powered personalization platform. Marketing teams create personalized 
content experiences based on visitor segments without writing code.

Section 2: Project Structure

A simple tree showing where things live. Main folders only—not every file.

## Project Structure

leigher-v2/ ├── cloudflare-worker/ # Backend API ├── dashboard/ # React frontend ├── studio/ # Standalone demos ├── docs/ # Documentation ├── design-tokens.md # Colors, spacing, typography └── component-patterns.md # UI patterns

Section 3: Tech Stack

Quick reference. No explanations—just the facts.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Frontend | React 19 + Vite |
| Backend | Cloudflare Workers (Hono) |
| Database | Cloudflare KV |
| Auth | Google OAuth 2.0 |

Section 4: Where to Find Details

Point Claude to your other documentation. This is important—it tells Claude where your tokens, patterns, and detailed rules live.

## Before You Start

Read these files as needed for your task:

| File | When to Read |
|------|--------------| 
| `design-tokens.md` | Any visual work |
| `component-patterns.md` | Creating/modifying components |
| `agent_docs/code-conventions.md` | Understanding DO/DON'T rules |
| `agent_docs/figma-integration.md` | Working with Figma designs |

Section 5: Critical Rules

The rules that apply to every task. Keep this focused—put detailed rules in separate files.

## Critical Rules (Always Apply)

1. **Use CSS variables** — Never hardcode colors
2. **Check existing components** — Browse before creating new
3. **One CSS file per component** — Import at top of component
4. **Test locally** — Run before committing

Section 6: Quick Start

How to run the project. Keep it simple.

## Quick Start

```bash
cd dashboard &#x26;&#x26; npm run dev      # → localhost:5173
cd cloudflare-worker &#x26;&#x26; npm run dev  # → localhost:8787


---

## Part 3: Organizing Detailed Rules (30 min)

### The Problem with Long Files

You probably have more than 4 rules. You might have 10 things Claude should never do, 10 things it should always do, plus patterns, plus Figma workflow details.

If you put all of this in CLAUDE.md, it becomes hundreds of lines. That's fine—Claude can read it. But it becomes hard to maintain and easy to let grow out of control.

### The Solution: agent_docs/

Create a folder called `agent_docs/` for detailed instructions. CLAUDE.md stays focused; details live in separate files.

your-project/ ├── CLAUDE.md # Overview and pointers ├── design-tokens.md # Visual tokens ├── component-patterns.md # UI patterns └── agent_docs/ ├── code-conventions.md # Detailed DO/DON'T rules ├── figma-integration.md # Figma workflow └── building-and-testing.md # Commands, deployment


### agent_docs/code-conventions.md

This is where your detailed rules live:

```markdown
# Code Conventions

## What Claude Should NEVER Do

1. Never hardcode color values — use CSS variables
2. Never use inline styles — use CSS classes
3. Never create components that already exist
4. Never use flat gray backgrounds — use warm off-whites
5. Never use single-layer shadows — always compound
6. Never skip hover states on interactive elements
...

## What Claude Should ALWAYS Do

1. Check existing components before creating new ones
2. Use CSS variables for all colors
3. Create separate CSS file for each component
4. Match existing visual patterns
5. Add hover and focus states
...

agent_docs/figma-integration.md

Details about the Figma → Claude workflow:

# Figma Integration

## Two Paths, One Design System

| Path | Best For |
|------|----------|
| Figma → Claude | Visual exploration, complex layouts |
| Prompt → Browser | Quick fixes, interactions, content |

## Token Alignment

| Figma Style | CSS Variable |
|-------------|--------------|
| bg-primary | `var(--bg-primary)` |
| text-primary | `var(--text-primary)` |
...

Part 4: Testing Your Setup (20 min)

The Real Test

Generate a component and see if Claude follows your rules.

Create a notification banner component with an icon, message, and dismiss button.

Check:

Did Claude use CSS variables (not hardcoded colors)?
Did Claude create a separate CSS file?
Did Claude check for existing components?
Did Claude add hover states?

If Claude Missed Something

Is the rule documented? (CLAUDE.md or agent_docs/)
If not, add it
If yes, make it more specific

Iterate

CLAUDE.md and agent_docs/ are living documentation. Update them when:

Claude repeatedly makes the same mistake
You discover a new convention
A rule is too vague

Session 3 Checklist

[ ] Created CLAUDE.md with project context
[ ] Added project structure diagram
[ ] Added tech stack table
[ ] Added pointers to detailed docs
[ ] Added critical rules (4-6 rules)
[ ] Added quick start commands
[ ] Created agent_docs/ folder
[ ] Created agent_docs/code-conventions.md with DO/DON'T rules
[ ] Tested by generating a component
[ ] Verified Claude follows rules without reminding

What's Next

Session 4: Your Design System Files

CLAUDE.md tells Claude where to find information. Now let's create the design system files—design-tokens.md for your visual tokens and component-patterns.md for your UI patterns.

Session 3 of 10 • The Shipping AI Designer Course
Next: Session 4 — Your Design System Files

Briefing Your AI Colleague