You will work with a coding agent during your entire trainee program. The agent explains concepts, helps you when you are stuck, reviews your code and — later in the program — writes code under your direction. This card shows you the tool, our rules for using it, and gets your laptop set up.
Important
Work on this lesson in
teachermode.
Learning goals
- You can start Claude Code, work in a session, and resume it later.
- You can explain the usage quota and which model to work on.
- You can explain our session modes (
teacher,advisor,builder) and the rules that go with each. - You can use the three commands you need every day:
/trainee-start-lesson,/trainee-finish-lesson,/trainee-mode. - You can explain why we insist that you understand every line you ship.
Claude Code basics
Claude Code is a coding agent that runs in your terminal. Start it with claude inside a project folder.
You can use it like a chat ("what does this error mean?"), but it can also read your files, run commands and edit code — depending on the permissions you give it and the mode of your session.
Things worth knowing from day one:
-
Model: Always work on Opus, for everything. Check with
/model, switch with/model opus. Don't move to a smaller model to save quota. - Quota: Your usage is limited per 5-hour window. If you hit that limit, tell your mentor — we'll put you on a bigger plan. Running out is a plan problem, not something for you to work around.
-
Permissions: By default Claude Code asks you before it edits a file or runs a command. We work in auto mode, where another model reviews those actions instead of you, so you're not clicking "yes" all day. It is not the default — switch to it yourself at the start of each session with
Shift+Tab, which cycles through the permission modes. We come back to the others later in the program. -
Sessions: One lesson, one session. As you keep working with an agent, its context window fills up and it will eventually get confused. Start each lesson in a fresh session, and resume it with
claude --resumeif you need a break.
Learning with the trainee skills
We provide a set of agent skills Show archive.org snapshot that help you work through the trainee curriculum.
Installing the skills
You need an SSH key registered with your GitLab account at code.makandra.de. If you haven't done that yet, follow GitLab's guide Show archive.org snapshot first — you will need it for pushing your code anyway.
Then install the trainee skills:
git clone git@code.makandra.de:makandra/trainee-skills.git ~/.claude/trainee-skills
~/.claude/trainee-skills/update.sh
Start Claude Code and type /trainee- — the trainee skills should show up. Run /trainee-setup. It will pick a folder for your code, create a folder for stand-alone exercises and prepare your global agent configuration. The MovieDB app comes later, in the card "Sample apps".
Starting a lesson
When you're ready for a new lesson, start a fresh claude session and type:
/trainee-start-lesson <card url>
The agent will automatically familiarize itself with the card and set the right teaching mode (see below).
Some cards are private and the agent can't fetch them by URL. It will tell you so and ask you to paste the card: open the URL in your browser, copy the whole card, paste it into the chat.
While working on a lesson, please use the agent to help with the learning goals and exercises.
Finishing a lesson
A lesson is finished when you have a good understanding of the learning goals and have implemented all the exercises.
When you're ready to move on to the next lesson, type:
/trainee-finish-lesson
This checks that you did the exercises, asks you a few questions about what you learned, asks how the session went for you, and writes a short summary for your mentor.
The questions at the end are not a test. If you can't answer one, that is exactly what your mentor wants to know — and it is much less awkward to find out here than in the review. If a learning goal clearly isn't there yet, the agent will stop and send you back to the material, and you run /trainee-finish-lesson again afterwards.
Our teaching modes
Every card declares a teaching mode near the top, like this one:
Important
Work on this lesson in
teachermode.
The teaching mode defines what the agent will and won't do:
-
teacher(your first months): The agent explains, answers questions and discusses your code — but you type all code yourself. When you get stuck it helps in steps: first a question back, then the concept, then the shape of your solution with the interesting part left blank. Only if that doesn't work does it take over the change, and it will say so. -
advisor: You plan a change together with the agent, implement it yourself, then the agent reviews your work. It will explain anything you ask, in as much depth as you want — it just won't write the code. You implement the review feedback yourself, in separate commits. -
builder: You direct, the agent implements, and you review the agent's code. You must understand everything before it ships.
Starting a lesson with /trainee-start-lesson automatically detects the card's mode and switches to it. Switch modes manually only when your mentor suggests it: /trainee-mode <mode>.
The honor system
The teaching modes work on trust — nothing technically stops you from breaking them. So here is the deal:
- Taking the shortcut is allowed, hiding it is not. Asking the agent to take over when you're stuck is fine and visible in the transcript. Doing it secretly in a side-session defeats the purpose of your own training.
- Explain it or don't ship it. In reviews, your mentor will pick pieces of your code and ask you to explain them. "The agent wrote that" is not an explanation. If you can't explain it, the card is not done.
- Your transcripts are part of the review. You and your mentor will look at your agent conversations together, just like your code.
The reason for all this: after graduating the trainee program you will review and direct agents daily. A developer who only forwards agent output without understanding it adds no value. We are training you to be the person who can judge and improve that output.
Resources
Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.
Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.
- 📄 Claude Code: Quickstart Show archive.org snapshot — install, first session, basic commands. Skim it; the rest of the docs can wait.
- 📄 Claude Code: Overview Show archive.org snapshot — what the tool is and where it runs.
- 📄 No Meat Proxy Show archive.org snapshot — why forwarding agent output without understanding it adds no value, and what to do instead.
- 📄 Nutzung von KI-Systemen — our policy for using AI systems (internal card, sign in to read).
- ▶️ Agentic Coding bei makandra: Was sich für uns ändert Show archive.org snapshot — internal talk (in our library).
Exercises
1. Your first lesson session
If you haven't done the steps from Installing the skills above, do them now.
Start a new session in your exercises folder and run /trainee-start-lesson with this card's URL. The agent should recognize teacher mode and tell you what it will and won't do. Ask it at least three questions about anything on this card that isn't fully clear to you yet.
2. Your first guided task
In the same session, tell the agent you want to write your first Ruby script with its help: a greet.rb that asks for your name and prints a greeting. Because this lesson uses teacher mode, the agent won't type it for you — it guides, you write. That's the dynamic you'll work in for the next months, so feel how it plays out:
- Let it guide you step by step; type and run everything yourself.
- Ask it to explain one part in more depth, then ask for the same explanation from a different angle (an analogy, a comparison to a language you know).
- When the script runs, ask the agent to quiz you with two or three questions about what you wrote.
3. Finish the lesson
Run /trainee-finish-lesson and work through it.
When you're done, the agent will write a file to the mentor-handoff/ folder. It contains a summary of your session. Give that file to your mentor before your next review.
