Lesson 2.5: Build Your Project CLAUDE.md

🎯 What You'll Learn: How to create a comprehensive CLAUDE.md that gives Claude persistent project knowledge
⏱️ Time Required: 50 minutes
📦 What You'll Build: A complete CLAUDE.md file deployed in your project

Riley's Journey Continues

In Lesson 2.4, Riley mapped out her memory strategy. She knows what belongs in CLAUDE.md. Now it's time to build it.

💬 "I was nervous about writing CLAUDE.md - it felt like a big deal. But once I started, I realized it's just answering the question: 'What would I tell a new team member on day one?' All the context they'd need to do great work."
— Riley Harper

Where Riley is now:

By the end of this lesson:

What We're Building in This Lesson

CLAUDE.md is like writing an onboarding document for a new team member. Include everything they'd need to know to do great work on Day 1.

In this lesson:

Key Concept: CLAUDE.md Structure

The 6 Essential Sections

┌─────────────────────────────────────────────────────────────┐
│                    CLAUDE.md STRUCTURE                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. PROJECT OVERVIEW                                        │
│     What is this project? Who is it for?                    │
│                                                             │
│  2. KEY TERMINOLOGY                                         │
│     Words/terms specific to this project                    │
│                                                             │
│  3. STANDARDS & CONVENTIONS                                 │
│     How things should be done                               │
│                                                             │
│  4. KEY FILES & STRUCTURE                                   │
│     Where important things live                             │
│                                                             │
│  5. COMMON TASKS                                            │
│     What Claude will typically help with                    │
│                                                             │
│  6. IMPORTANT CONTEXT                                       │
│     Things Claude should always know                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why These Sections?

Exercise: Build Your CLAUDE.md

⏱️ Total Time: 40 minutes

What You'll Build

📄 A comprehensive CLAUDE.md file for your automation project.

Step 1: Create the File

⏱️ Time: 2 minutes

What you're doing:

Creating the CLAUDE.md file in the right location.

Options:

# Option A: Project root
touch CLAUDE.md

# Option B: In .claude folder
touch .claude/CLAUDE.md

Riley chose: Project root (/margin-automation/CLAUDE.md)

💬 "I put mine in the project root because I want it visible. It reminds me to keep it updated, and my team can see it when they open the folder."

✅ Success Check:

Step 2: Write the Project Overview

⏱️ Time: 5 minutes

What you're doing:

Giving Claude essential context about what this project is.

Template:

# [Project Name]

## Project Overview

**What this is:** [One sentence description]

**Who it's for:** [Target users/audience]

**Business context:** [Why this project exists]

**Key goal:** [What success looks like]

Riley's Project Overview:

# Margin Operations Automation

## Project Overview

**What this is:** Automation toolkit for the derivatives clearing risk operations desk, starting with the weekly margin report and position risk analysis workflow.

**Who it's for:** Riley Harper (Operations Director) and the derivatives clearing risk team.

**Business context:** Mid-sized financial services firm. Operations team of 12, supporting ~200 portfolio managers across equity and fixed income derivatives. Reporting to Head of Risk Operations (Marcus Webb).

**Key goal:** Automate the Monday margin report (was 4 hours, now 18 minutes) and position risk analysis. Target: free 5+ hours per week for strategic risk review and counterparty analysis.

Your Project Overview:

# [Your Project Name]

## Project Overview

**What this is:**

**Who it's for:**

**Business context:**

**Key goal:**

✅ Success Check:

Step 3: Define Key Terminology

⏱️ Time: 10 minutes

What you're doing:

Preventing the "Breach vs. flag" problem by defining important terms precisely.

Template:

## Key Terminology

### Product/Service Terms
| Term | Definition |
|------|------------|
| [Term] | [What it means in THIS context] |

### Process Terms
| Term | Definition |
|------|------------|
| [Term] | [What it means in THIS context] |

### Common Mistakes
- DON'T use "[wrong term]" - we call it "[right term]"

Riley's Key Terminology:

## Key Terminology

### Margin Call Status (USE THESE EXACT TERMS)
| Status | Definition |
|--------|------------|
| **Open** | Margin call issued, awaiting counterparty payment |
| **Disputed** | Counterparty contests the call amount |
| **Settled** | Payment received and confirmed |
| **Failed** | Settlement deadline missed — escalation required |

⚠️ **Do NOT use** "outstanding", "pending", "completed", or "overdue". These have specific regulatory meanings in clearing confirmations that differ from our internal status labels.

### Position Risk Status (USE THESE EXACT TERMS)
| Status | Definition |
|--------|------------|
| **Watch** | Approaching exposure limits — monitoring required |
| **Restricted** | New positions blocked pending risk review |
| **Breached** | Exposure limits exceeded — same-day escalation to Marcus Webb |

⚠️ **Do NOT use** "flagged", "at-risk", or "warning" as substitutes. Each status triggers different compliance actions and reporting obligations.

### Key Metric Abbreviations
| Term | Full Name | Common Mistakes to Avoid |
|------|-----------|--------------------------|
| **IM** | Initial Margin | NOT "collateral deposit" or "margin deposit" |
| **VM** | Variation Margin | NOT "daily settlement" or "MTM payment" |
| **Net Exposure** | Counterparty exposure after netting agreements | NOT "total position" |

### Internal Roles
| Term | Definition |
|------|------------|
| **PM** | Portfolio Manager (manages investment positions) |
| **Ops** | Operations team (Riley's team — margin and settlement) |
| **Clearing** | Derivatives Clearing Risk desk (our department) |
| **Compliance** | Regulatory compliance team (Clara Singh) |

Your Key Terminology:

List 10-15 terms specific to your domain:

## Key Terminology

### [Category 1]
| Term | Definition |
|------|------------|
| | |
| | |

### [Category 2]
| Term | Definition |
|------|------------|
| | |
| | |

### Common Mistakes
- DON'T use "___" - we call it "___"

✅ Success Check:

Step 4: Document Standards & Conventions

⏱️ Time: 8 minutes

What you're doing:

Telling Claude how things should be done in this project.

Template:

## Standards & Conventions

### Output Formatting
[How reports, analyses, etc. should be formatted]

### Communication Standards
[Tone, style, recipients for different outputs]

### Thresholds & Rules
[Business rules that apply to decisions]

Riley's Standards:

## Standards & Conventions

### Report Formatting
- Use markdown tables for data comparison
- Always include week-over-week change (%)
- Flag variances >10% with ⚠️ emoji
- Executive summaries: 3 bullet points maximum
- Include date range in all report headers

### Communication Style
- Head of Risk Operations (Marcus Webb): Brief, numbers-focused, flag anything requiring escalation
- Portfolio Managers: Detail on specific positions, clear next steps
- Compliance team (Clara Singh): Precise terminology, audit-ready format

### Business Thresholds
| Metric | Threshold | Action |
|--------|-----------|--------|
| Net Exposure per counterparty | >£10M | Escalate to Marcus Webb |
| IM variance | >10% WoW | Requires explanation in report |
| Margin call age | >2 business days unsettled | Flag as "Failed" |
| Counterparty concentration | >25% of portfolio | Move to Restricted status |

### Data Standards
- Currency: Always GBP (£) unless specified otherwise
- Dates: DD/MM/YYYY format (UK standard)
- Percentages: One decimal place (e.g., 45.2%)
- Large numbers: Use K/M notation (£1.2M not £1,200,000)

Your Standards:

## Standards & Conventions

### Output Formatting
-
-
-

### Communication Style
-
-

### Business Thresholds
| Metric | Threshold | Action |
|--------|-----------|--------|
| | | |
| | | |

✅ Success Check:

Step 5: Map Key Files & Structure

⏱️ Time: 5 minutes

What you're doing:

Telling Claude where important things live.

Template:

## Key Files & Structure

### Project Structure

[folder tree]

### Important Files
| File | Purpose |
|------|---------|
| [path] | [what it contains] |

Riley's Structure:

## Key Files & Structure

### Project Structure

/margin-automation/

├── CLAUDE.md ← You are here

├── .claude/

│ ├── skills/

│ │ ├── weekly-margin-report/

│ │ │ └── SKILL.md

│ │ └── calculate-variance/

│ │ └── SKILL.md

│ ├── agents/

│ │ ├── position-risk-analyzer.md

│ │ └── counterparty-researcher.md

│ └── settings.json

├── templates/

│ ├── margin-report-template.md

│ └── email-templates/

├── data/

│ └── [Prime Broker portal exports go here]

└── outputs/

└── [Generated reports saved here]

### Important Files
| File | Purpose |
|------|---------|
| `skills/weekly-margin-report/SKILL.md` | Monday margin report generator |
| `agents/position-risk-analyzer.md` | Analyses why positions are at risk |
| `templates/margin-report-template.md` | Standard report format |
| `data/` | Drop Prime Broker portal exports here |

Your Structure:

## Key Files & Structure

### Project Structure

[Your folder tree]

### Important Files
| File | Purpose |
|------|---------|
| | |
| | |

✅ Success Check:

Step 6: Document Common Tasks

⏱️ Time: 5 minutes

What you're doing:

Helping Claude anticipate what you'll typically ask for.

Riley's Common Tasks:

## Common Tasks

### What I Typically Ask Claude to Help With

1. **Monday Margin Report**
   - Trigger: "run Monday margin report" or "weekly report"
   - Uses: weekly-margin-report skill
   - Needs: Prime Broker portal export (positions.csv, margins.csv)

2. **Position Risk Analysis**
   - Trigger: "analyze [counterparty]" or "why is [position] on Watch"
   - Uses: position-risk-analyzer agent
   - Needs: Position details, counterparty name, exposure amount, IM/VM values

3. **Margin Call Drafting**
   - Trigger: "draft margin call notice to [counterparty]"
   - Needs: Call amount, status, settlement deadline
   - Tone: Formal, precise — see Communication Standards

4. **Data Formatting**
   - Trigger: "format this data" or "create exposure table from"
   - Follow: Report Formatting standards above

### What I DON'T Need Claude For
- Actual Prime Broker portal queries (I do that manually)
- Sending emails or notices (I review and send)
- Making risk decisions (I decide, Claude advises)

Your Common Tasks:

## Common Tasks

### What I Typically Ask Claude to Help With

1. **[Task Name]**
   - Trigger: "[how you'd ask]"
   - Needs: [what info required]

2. **[Task Name]**
   - Trigger: "[how you'd ask]"
   - Needs: [what info required]

### What I DON'T Need Claude For
-
-

✅ Success Check:

Step 7: Add Important Context

⏱️ Time: 5 minutes

What you're doing:

Including anything else Claude should always know.

Riley's Important Context:

## Important Context

### Key People
| Person | Role | What They Care About |
|--------|------|---------------------|
| Marcus Webb | Head of Risk Operations (Riley's manager) | Escalations, Breached positions, report accuracy |
| James Okafor | Senior Risk Analyst | Position-level detail, counterparty analysis |
| Clara Singh | Compliance Officer | Precise terminology, audit trails, regulatory filings |
| Head of Derivatives Clearing | Senior stakeholder | Monday report recipient, portfolio-level summary |

### Current Priorities (this quarter)
- Reduce margin call settlement failures (currently 3% of calls)
- Improve Watch → Breach escalation speed
- Build audit trail for all automated report outputs

### Things Claude Should Always Remember
- Riley reports to Head of Risk Operations (Marcus Webb)
- The Monday report goes to Marcus + Head of Derivatives Clearing
- Breached positions (>£10M net exposure) require same-day escalation
- Source data comes from Prime Broker portal exports
- Fiscal year ends March 31; regulatory reporting cycle is quarterly

### Things That Change (Check with Riley)
- Current quarter exposure limits
- Active counterparty disputes
- Team composition
- Any regulatory guidance updates

Your Important Context:

## Important Context

### Key People
| Person | Role | What They Care About |
|--------|------|---------------------|
| | | |

### Current Priorities
-
-

### Things Claude Should Always Remember
-
-
-

### Things That Change (Check First)
-
-

✅ Success Check:

Riley's Complete CLAUDE.md

Here's Riley's complete file for reference:

# Margin Operations Automation

## Project Overview

**What this is:** Automation toolkit for the derivatives clearing risk operations desk, starting with the weekly margin report and position risk analysis workflow.

**Who it's for:** Riley Harper (Operations Director) and the derivatives clearing risk team.

**Business context:** Mid-sized financial services firm. Operations team of 12, supporting ~200 portfolio managers across equity and fixed income derivatives. Reporting to Head of Risk Operations (Marcus Webb).

**Key goal:** Automate the Monday margin report (was 4 hours, now 18 minutes) and position risk analysis. Target: free 5+ hours per week for strategic risk review.

---

## Key Terminology

### Margin Call Status (USE THESE EXACT TERMS)
| Status | Definition |
|--------|------------|
| **Open** | Margin call issued, awaiting counterparty payment |
| **Disputed** | Counterparty contests the call amount |
| **Settled** | Payment received and confirmed |
| **Failed** | Settlement deadline missed — escalation required |

⚠️ Do NOT use "outstanding", "pending", "completed", or "overdue".

### Position Risk Status (USE THESE EXACT TERMS)
| Status | Definition |
|--------|------------|
| **Watch** | Approaching exposure limits — monitoring required |
| **Restricted** | New positions blocked pending risk review |
| **Breached** | Exposure limits exceeded — same-day escalation |

⚠️ Do NOT use "flagged", "at-risk", or "warning" as substitutes.

### Key Metrics
- **IM** = Initial Margin (NOT "collateral deposit" or "margin deposit")
- **VM** = Variation Margin (NOT "daily settlement" or "MTM payment")
- **Net Exposure** = counterparty exposure after netting agreements

---

## Standards & Conventions

### Report Formatting
- Markdown tables for data
- Include week-over-week change (%)
- Flag variances >10% with ⚠️
- Executive summaries: 3 bullets max

### Business Thresholds
| Metric | Threshold | Action |
|--------|-----------|--------|
| Net Exposure per counterparty | >£10M | Escalate to Marcus Webb |
| IM variance | >10% WoW | Requires explanation in report |
| Margin call age | >2 business days | Flag as "Failed" |

### Data Standards
- Currency: GBP (£)
- Dates: DD/MM/YYYY
- Percentages: One decimal (45.2%)
- Large numbers: K/M notation (£1.2M)

---

## Key Files & Structure

/margin-automation/

├── CLAUDE.md

├── .claude/

│ ├── skills/

│ │ ├── weekly-margin-report/

│ │ └── calculate-variance/

│ └── agents/

│ ├── position-risk-analyzer/

│ └── counterparty-researcher/

├── templates/

├── data/ ← Prime Broker portal exports

└── outputs/ ← Generated reports

---

## Common Tasks

1. **Monday Margin Report**: "Run Monday margin report"
2. **Position Risk Analysis**: "Analyze why [counterparty] is on Watch"
3. **Margin Call Drafting**: "Draft margin call notice to [counterparty]"

---

## Important Context

### Key People
| Person | Role |
|--------|------|
| Marcus Webb | Head of Risk Operations (Riley's manager) |
| James Okafor | Senior Risk Analyst |
| Clara Singh | Compliance Officer (receives breach reports) |

### Always Remember
- Monday report → Marcus Webb + Head of Derivatives Clearing
- Breached positions (>£10M net exposure) require same-day escalation
- Source data comes from Prime Broker portal exports
- Fiscal year ends March 31; regulatory reporting is quarterly

---

*Last updated: [current date]*

Overall Success Criteria

By the end of this lesson, you should have:

Test Your CLAUDE.md:

Troubleshooting

---
*Last updated: [Date]*
*Next review: [Date + 1 month]*

You Did It - Week 2 Complete!

You've built a comprehensive CLAUDE.md file!

What Riley accomplished this week:

💬 "Week 2 transformed how I work with Claude. I went from repeating myself every session to having Claude know my context automatically. My position-risk-analyzer agent works perfectly because it understands our terminology. The multi-agent coordination means my Monday workflow is completely automated. This is what AI should feel like."

Week 2 Accomplishments:

What's Different Now:

💡 Keep it under 200 lines. Focus on terminology and thresholds, the things that cause the most errors when Claude gets them wrong. One CLAUDE.md per project folder means context switches automatically when you change directory.