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
===
```mermaid +render +width:100%
graph TD
S["🏢 System Level
Who is the AI? What org is this?
Guardrails, conventions, culture"]
P["📁 Project Level
What are we building?
Constraints, decisions, patterns"]
U["👤 User Level
Who am I?
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.
🎯