How to ride a horse
A workshop on using Claude Code — without hurting yourself or anyone else.
You are all informáticos
You may not call yourself one. But think about it.
What do you work with, day after day? What is the single tool you use more than any other?
A computer.
If a carpenter is someone who works with wood and a baker is someone who works with dough, then you — whatever your title says — are someone who works with a computer. You are an informático.
So the real question is…
Now that it is clear what you are, the question is: how good of an informático are you?
Let's do a quick self-test. For each of these, ask yourself honestly: have you ever typed this?
mkdir my-folder
cd ..
ls
No judgement. Just notice your answer.
What is actually happening
Most people who use a computer all day have never typed any of those.
They click. They drag. They double-click. They hit Print Screen. The computer is a box of icons.
The people who did learn these commands learned something deeper: that the computer is a machine you can instruct, not just a surface you can touch.
That was always a good idea. Now it is an even better one.
Premise #2 — documentation compounds
Three independent observations:
- People who write down their goals achieve them more. The famous study here is Gail Matthews at Dominican University — writing goals down, sharing them, and sending weekly updates produced significantly higher achievement rates than just thinking about them.
- People who keep journals remember more. Expressive-writing and journaling research consistently shows stronger recall and stronger integration of experiences over time.
- Products with good documentation are better products. Ask any engineer. The codebase with a
READMEis the codebase that can be changed without fear. - Countries with written laws have fewer beheadings. Documentation scales judgement beyond the judge.
Slide-deck citations to firm up before delivery — Matthews (2015) goal-setting, expressive-writing / journaling memory literature. Taig to confirm exact references.
Premise #3 — structured thinking wins
Think about a task as simple as building a spreadsheet.
If you think in rows, columns, headers, data types — you are done in ten minutes. If you think in "I'll just start typing things", you spend an hour and produce something nobody can read.
That is not true of every task. But it is true of most white-collar tasks.
It is also why engineers, mathematicians and physicists get hired for jobs that have nothing to do with engineering, mathematics or physics. The hiring manager is not buying the subject knowledge. They are buying the habit of structured thinking.
A brilliant concrete example of this at work: naming tasks by their objective, not by their activity. "Reduce page-load time under 200 ms" is a task you can finish — the name tells you when you are done. "Performance work" is a chore that never ends.
There is a whole talk on this principle — watch it here.
All three were true a year ago
- Being comfortable with a computer was an advantage.
- Documenting things was an advantage.
- Structured thinking was an advantage.
You could get through life without any of them. Plenty of successful people did.
Now Claude Code is in the picture. And each of these three advantages just got larger.
Much larger.
Why this workshop is called "How to ride a horse"
Here is a simple question.
Who is faster — a person running, or a person riding a horse?
It depends on whether they know how to ride.
If they do, it is not even a question. The horse-rider wins every time, by a margin that is embarrassing for the runner.
If they don't, the rider is slower than the runner. Sometimes they fall off. Sometimes the horse kicks them. Sometimes they die.
Using Claude Code is exactly like this.
What this workshop is
I am going to show you how to ride a horse, while most of your friends and relatives are still running.
But I want you to take this seriously. If you don't do it right, you will hurt yourself. You will hurt other people. You will hurt the company.
Two examples of hurting you can picture today:
- Uncaught hallucinations committed into a repo. The AI confidently invents a function that does not exist. You don't check. You ship it. Now production is broken and the bug hunt begins.
npm installof a malicious package. The AI suggests a library. You accept. The library is typosquatting a real one and exfiltrates your environment variables on install. Your API keys are now on someone else's server.
These are not hypotheticals. They happen every week, somewhere.
The gear — meet your equipment
You have three things to understand. They map directly onto horse-riding.
- The terminal is the reins. It is what you grip. It is how you steer. Without this, you have no control.
- The coding assistant is the horse. Claude Code, Gemini CLI, Codex — the thing that actually does the work and carries you forward. This is the most important part.
- The LLM is the saddle. Sonnet, Opus, Gemini 2.5. You can swap it. Some are more comfortable, some are faster. But the horse matters more than the saddle.
Let's grab the reins
Open your terminal. On a Mac, press ⌘ + Space and type "Terminal".
Now type these, one at a time, pressing Enter after each:
cd Desktop
ls
mkdir "Patata"
cd Patata
You just navigated your Desktop, listed its contents, created a folder called Patata, and walked into it.
That is riding the reins.
Everybody do this now
Using the terminal — not Finder, not the mouse — complete each of these:
- Create a folder
- Ping a website (try
ping google.com, thenCtrl + Cto stop) - Delete a folder (try
rmdir Patataafter youcd ..back out)
Once you have done all three, find someone in the room who has not, and help them.
We do not move on until every hand in the room has held the reins.
Next: mounting the horse
You have the reins. You know how to steer.
Now we get to the horse itself — the coding assistant — which is where the real power lives and also where most of the danger is.
Take a breath. Stretch. Then we continue.
Anatomy of the horse
When you give a coding assistant a task — a stack trace, a feature request, anything — it does not answer in one shot. It runs a loop.
The model drives three stages: gather context (read code, logs, docs), formulate a plan (decide what to change), take an action (edit files, run commands). Then it looks at what happened and does it all again until the task is done — or until it's stuck.
Every coding assistant on the market works roughly this way.
The brain lives in the cloud
The language model in that diagram is not on your machine. It lives in a data centre.
- Most coding assistants use remotely hosted language models.
- Claude Code uses the Claude series — Opus, Sonnet, Haiku — hosted at Anthropic, AWS or Google Cloud (configurable per deployment).
Every thought your horse has makes a round trip to that data centre. That is why latency matters, rate limits exist, and an outage on the hosting provider is an outage for you.
Tool use — how the brain moves muscles
The model itself cannot touch your filesystem, run your terminal, or hit the internet. It can only produce text.
So the coding assistant hands the model a contract in plain text: "if you want to read a file, reply in this exact format. I'll read it for you and hand back the contents."
The model replies ReadFile: main.go in ordinary text. The coding assistant recognises the pattern, reads the file on its behalf, and sends the contents back in the next prompt. The model never touched your disk.
Every tool — Read, Write, Bash, WebFetch, Edit — is the same pattern: a text contract negotiated between two computers.
Why we're teaching you Claude specifically
Not every model is good at this. Understanding a tool contract and staying inside it is a skill, and models vary wildly.
The Claude series — Opus, Sonnet, Haiku — are particularly strong at understanding what tools do and using them to complete tasks.
That is the single most important reason the horse we are teaching you to ride is Claude Code, and not one of the other animals in the stable.
Give the horse a map of your stable — /init
Before you ride anywhere, the horse needs to know the terrain: what's in this repo, how it's organised, what conventions you follow, which commands matter.
The /init command is Claude Code's onboarding ritual for a new repo.
CLAUDE.md is a plain text file at the root of your project (and optionally at subfolder level, for scoped guidance). It holds what the horse needs to know about your stable — patterns, commands, gotchas, do-nots. Claude Code reads it at the start of every conversation.
Run /init once per repo. Edit the file by hand as the project evolves.
Point the horse at a landmark — @ file mentions
Instead of copy-pasting a file path, mention it with @.
- Type @ — an autocomplete list of files and folders appears.
- Use ↑ and ↓ to scroll.
- Press Enter to insert the path.
Once inserted, that file's contents are bundled into the context for the next turn. No paste-gymnastics, no missing files, no broken paths.
It is one of those small quality-of-life features you don't realise you needed until you've used it for an afternoon.
Show the horse what you mean — paste screenshots
You can paste an image directly into a Claude Code prompt. The model sees it as an actual image, not as OCR'd text.
- Take a screenshot on macOS: ⌘ + Shift + 4 (drag a region).
- Take a screenshot on Windows: Win + Shift + S.
- Paste into the terminal: Ctrl + V.
Claude Code renders the pasted image as [Image #1] in your prompt and forwards it to the model.
Useful for: design mock-ups, UI bugs, chart data you don't want to retype, error messages from tools that won't let you copy text.
If the screenshot shortcut on macOS isn't behaving, press ⌘ + Shift + 5, click Options, and pick Clipboard as the destination.
Keep the horse's head clear — conversation hygiene
Every message you send, and every message the horse replies with, stays in the context for the rest of the conversation.
That is usually a good thing — the horse remembers what you just asked, and what it just did.
But when you switch tasks, all the old messages come along for the ride. Imagine this sequence:
- You ask: "What's in the
auth.tsfile?" → Claude reads it and explains. - You ask: "Write tests for
createSession." → Claude starts. - Claude hits an error about a missing package → investigates → fixes it → runs the tests. Done.
- You move on and ask: "Now write tests for
createUser."
At step 4, the missing-package chatter from step 3 is still in the context. It is irrelevant to the new task, but it is pulling the horse's attention in a direction you no longer care about.
Rule of thumb: new task = new conversation. Use /clear to wipe the chat, or just open a fresh session. The shorter the context, the sharper the horse.
Conversation controls — when to rein the horse in
Four tools you'll use every day.
- Esc — interrupts Claude mid-reply. Redirect or correct it without losing the
conversation. Also useful to fix
#memory entries you've just added. - Double-tap Esc — rewinds the conversation to an earlier point. Good when a recent detour polluted the context but the work before it is still valuable.
/compact— summarises the conversation and continues. Keeps Claude focused but preserves what it has learned in this session./clear— dumps the history. Clean slate, for when you switch to an unrelated task.
Between them, these four are a dial: from adjust course, keep everything (Esc), through keep the useful part, drop the rest (double-Esc, /compact), to start fresh (/clear).
If you're using Claude Code without Git, you're doing it wrong
Not "could be better if". Wrong. Full stop.
Every time the horse edits a file, you need three things — and Git is the only tool that gives you all three.
- A way to supervise.
git diffshows every change, line by line. Read every diff. Hallucinated functions, wrong paths, bogus imports — they all live in the diff, and they are obvious the moment you look. - A way to undo. The horse makes mistakes.
git stash,git restoreandgit resetlet you throw a bad run away without losing your nerve. Without Git, every mistake is a panic. - A way to turn work into knowledge. Each commit is a small record of what was tried and what worked.
git logbecomes your project's reasoning trail — and Claude Code can read it back on the next session to remember how you think.
Claude Code without Git is riding blindfolded. You cannot supervise what you cannot see, you cannot undo what you cannot roll back, and you cannot learn from work you never recorded. This is non-negotiable.
Initialise every repo with git init before you let the horse near it. Commit often. Read every diff.
Quiz time
You have sat through the deck. Now let's see what stuck.
Eight multiple-choice questions, four options each. For each one:
- Read the question.
- Discuss with a neighbour for 30–60 seconds.
- We reveal the answer on the next slide and talk through it.
No prizes. No shame. Just a calibration check on your own understanding.
Q1 — why does tool-use exist?
What is the fundamental limitation of language models that necessitates the use of a tool system in coding assistants?
- A. They can only generate code in specific programming languages.
- B. They have limited memory capacity for large codebases.
- C. They cannot understand complex programming concepts.
- D. They can only process text input/output and cannot directly interact with external systems.
Q1 — answer
D. They can only process text input/output and cannot directly interact with external systems.
Why. The model sits in a data centre and speaks only in text. It cannot touch your filesystem, your terminal, or the internet. Tools are the text contract that lets the model ask the coding assistant to do those things on its behalf — exactly the ReadFile example we walked through earlier.
Q2 — MCP servers in GitHub Actions
What permission configuration is required when integrating MCP servers with Claude Code in GitHub Actions?
- A. Each MCP server tool must be individually listed in the permissions.
- B. No special permissions are needed if running in GitHub Actions.
- C. Permissions are automatically inherited from the GitHub repository settings.
- D. A single blanket permission for all MCP operations.
Q2 — answer
A. Each MCP server tool must be individually listed in the permissions.
Why. GitHub Actions runs Claude Code non-interactively — there is no human at the keyboard to approve a permission prompt. Every tool call has to be pre-authorised, one line per tool. MCP server tools do not inherit from GitHub repo permissions, and there is no blanket-allow. Add a new tool, add a new line.
Q3 — Plan Mode vs Thinking Mode
What is the primary difference between Plan Mode and Thinking Mode in Claude Code?
- A. Plan Mode is for writing code while Thinking Mode is for debugging.
- B. Plan Mode is faster while Thinking Mode is more accurate.
- C. Plan Mode uses fewer tokens while Thinking Mode uses more tokens.
- D. Plan Mode handles breadth (multi-step tasks) while Thinking Mode handles depth (complex logic).
Q3 — answer
D. Plan Mode handles breadth, Thinking Mode handles depth.
Why. Plan Mode is for breaking a big job into steps before touching the code — it outputs a plan file you can review and course-correct. Thinking Mode (extended thinking) is for going deeper on a single hard problem — the model reasons for longer before answering. Use Plan Mode for "refactor this whole module"; use Thinking Mode for "why is this regex matching too much?".
Q4 — the three CLAUDE.md files
Which of the following correctly describes the three types of CLAUDE.md files and their usage?
- A. Project level (debugging), Local level (testing), Machine level (production).
- B. Project level (personal use), Local level (team sharing), Machine level (repository specific).
- C. Project level (shared with team, committed), Local level (personal, not committed), Machine level (global for all projects).
- D. Project level (configuration), Local level (documentation), Machine level (automation).
Q4 — answer
C. Project (shared with team, committed), Local (personal, not committed), Machine (global).
Why. CLAUDE.md at the project root is committed to the repo and read by every teammate's Claude. CLAUDE.local.md is gitignored — that is where your personal shortcuts and machine-specific notes go. ~/.claude/CLAUDE.md lives in your home folder and applies to every project on your machine. Three stacked layers, from shared down to private.
Q5 — custom slash commands
How do you create a custom command in Claude Code that accepts runtime parameters?
- A. Use the
@parametersdecorator in the command file. - B. Define parameters in
settings.jsonconfiguration. - C. Add command-line flags when executing the command.
- D. Include
$ARGUMENTSplaceholder in the markdown command file.
Q5 — answer
D. Include $ARGUMENTS in the markdown command file.
Why. Slash commands are plain markdown files in .claude/commands/<name>.md. Anywhere you write $ARGUMENTS in the file, Claude Code substitutes whatever the user typed after the command name. No decorators, no JSON config, no flags — it is text substitution.
Q6 — which hook can block a tool?
Which type of hook can prevent a tool call from happening if certain conditions are met?
- A. PostToolUse hook.
- B. Project hook.
- C. Global hook.
- D. PreToolUse hook.
Q6 — answer
D. PreToolUse hook.
Why. PreToolUse runs before a tool is executed and can return a decision that blocks the call. PostToolUse runs after — too late to prevent anything. "Project" and "Global" describe where a hook is configured (per-repo vs per-user), not when it fires.
Q7 — protect the .env file
A developer wants to prevent Claude from reading sensitive .env files. Which type of hook should they set up, and what tool names would they likely match?
- A. PostToolUse hook, matching
WriteandEdit. - B. PreToolUse hook, matching
WriteandCreate. - C. PreToolUse hook, matching
ReadandGrep. - D. PostToolUse hook, matching
ReadandDelete.
Q7 — answer
C. PreToolUse hook, matching Read and Grep.
Why. You want to block before the read happens → PreToolUse. The tools Claude would use to get the contents of a .env are Read and Grep (and sometimes Bash cat). Write/Edit/Create are not relevant — those modify files, they do not read them. PostToolUse fires after the read, which means the secret has already been loaded into the context window. Too late.
Q8 — what are hooks for?
What is the primary purpose of hooks in Claude Code?
- A. To manage project dependencies.
- B. To automatically generate new code snippets.
- C. To run commands before or after Claude executes a tool.
- D. To provide a user interface for Claude.
Q8 — answer
C. To run commands before or after Claude executes a tool.
Why. Hooks are event-triggered scripts that fire on tool-lifecycle events — most commonly PreToolUse (before a tool runs) and PostToolUse (after). They are the escape hatch for "do my custom thing whenever Claude does X": block a tool, log an audit trail, run a formatter, send a notification.
Attribution
This deck's theory section (agent-loop, tool-use, hosting) and practical-techniques slides on /init, @ mentions, paste-screenshots, conversation hygiene and conversation controls are adapted from Anthropic's official Claude Code training. The framing (horse-riding metaphor, terminal as reins, Git non-negotiability) is ours.