ai-presentations/week2-claude-md/presentation.md

Making AI Actually Work

CLAUDE.md and the Art of Instruction

Why AI Disappoints People

What people say:

"AI doesn't work."

"It hallucinates too much."

"Copilot is useless."

What's actually happening:

"I gave it no context."

"I asked it to guess."

"I gave it the wrong tool."

Imagine hiring a brilliant consultant and telling them nothing about your company.

Then being surprised when their advice is generic.

The Three Levels

graph TD
    S["🏢 System Level<br/>Who is the AI? What org is this?<br/>Guardrails, conventions, culture"] 
    P["📁 Project Level<br/>What are we building?<br/>Constraints, decisions, patterns"]
    U["👤 User Level<br/>Who am I?<br/>Preferences, style, context"]
    
    S --> P --> U
    
    style S fill:#ff6b6b,stroke:#333,color:#fff
    style P fill:#4a9eff,stroke:#333,color:#fff
    style U fill:#51cf66,stroke:#333,color:#fff

Each level compounds. The AI gets better at every layer.

System Level

The organisation-wide context. Who is this AI? What does it know?

"Be helpful" → generic, useless

"You are an Axway services consultant. You know our deployment patterns use GitOps via ArgoCD. Customer naming follows the CUST-REGION-ENV pattern. Escalation path is engineer → team lead → director. Never modify production without explicit approval."

→ Now the AI has context that would take a new hire weeks to absorb.

Project Level

The "new colleague joins the project" test:

What would you put in their first-day doc?

• What are we building and why?

• What's been decided (and what hasn't)?

• What are the constraints?

• Where is everything? (repos, docs, environments)

• What are the gotchas?

Write that document. Put it in CLAUDE.md or AGENTS.md.

Your AI reads it every single session.

User Level

Personal working style. The compound effect.

Without:

• Generic tone
• Over-explains basics
• Wrong assumptions
• Feels like talking to a stranger

With:

• Matches your communication style
• Knows your role and expertise level
• Remembers your preferences
• Feels like working with someone who knows you

System + Project + User = AI that feels like a team member, not a chatbot.

Intent vs. Instruction

Vague 😬

"Check if my server is secure"

Better 👍

"Audit SSH config against CIS benchmarks, prioritise by severity"

Best 🎯

Write a skill for it. AI follows the same checklist every time.

Ambiguity is the enemy of automation.

If you don't define "safe"… the AI will.

DEMO

Same prompt. Two contexts. Watch what changes.

Your Homework

• This week: Write a CLAUDE.md for one project you're working on

• This week: Add 3 sentences about your preferences to your AI tool

• Next time you're frustrated: Ask "what context was I not giving it?"

These are 10-minute tasks that permanently improve every AI interaction.

Next Week

Real stories from real people in this room.

What Dhruv built for $2.50. What Gill discovered in her first hour.

What's actually changing in how we work.

🎯