◆ Introduction

Meet Marcus —
and recognize yourself.

Before we get into tools and workflows, let's set the stage. This module follows a real scenario based on engineers just like you.

5 min read

Scenario-based

No prior AI experience required

👨‍💻

Marcus Reid, Senior Software Engineer

8 years at Vortex Studios. Knows the engine inside out. Has opinions about tools. Skeptical that AI is anything more than autocomplete with better PR.

📋

Monday Morning, 9:02 AM

Vortex Studios — Global HQ, Game Engine Team

Marcus opens Slack to find a message from his tech lead:

"Hey — heads up, we're rolling out Claude Code to the whole engine team this week. Mandatory adoption. There's onboarding material dropping in the AI Hub. Leadership wants 80% of devs actively using it within 60 days. Lmk if you have questions."

— @tlead-jordan, 8:47 AM

Marcus stares at the message. Great. Another tool nobody asked for.

He's seen this before. New platform, big announcement, three months later everyone goes back to doing it the old way. He's not opposed to the idea of AI assistance — he's just not convinced it's actually going to change how he works.

But the message says mandatory. So here we are.

💡

Why Marcus's skepticism matters

Marcus represents the majority of engineers on your team — not resistant to change, but needing a reason to trust it. This module is designed around his questions, not a cheerleader's assumptions. By the end, Marcus has concrete evidence that Claude Code changes his workflow in ways that matter to him.

🎯

What you'll learn

How to set up Claude Code, write effective specs, manage context, recover from failures, and build a prompt library that actually gets used.

⏱️

Time investment

~45 minutes total, split into 5 focused lessons. Knowledge checks throughout. No busy work.

🔑

What you need

Claude Code installed (see setup guide), access to a project directory, and your Claude Pro or team account credentials.

◆ Lesson 1 of 5

Orientation &
First Launch

Marcus opens his terminal for the first time with Claude Code installed. Here's what he needs to understand before he types a single prompt.

8 min

1 knowledge check

🖥️

Marcus opens his terminal

First Claude Code session — engine-core project directory

Marcus navigates to the engine-core repository and types claude to launch his first session. Claude Code scans the directory.

bash — engine-core

marcus@vortex:~/projects/engine-core$ claude

✓ Claude Code v2.1 — authenticated as marcus.reid@vortex.com

✓ Scanning project structure...

✓ Indexed 847 files across 23 directories

⚠ No CLAUDE.md found — operating without project context

Claude Code ready. How can I help?

# Marcus types his first prompt...

> Give me an overview of this project

This appears to be a game engine core library. I can see:

• src/renderer/ — rendering pipeline (Vulkan-based)

• src/physics/ — collision and physics simulation

• src/audio/ — spatial audio system

• src/networking/ — multiplayer sync layer

• tests/ — partial coverage (est. 34%)

Note: Without CLAUDE.md, I'm inferring conventions from code patterns.

Some suggestions may not match your team's standards.

⚠️

That warning matters more than it looks

Without a CLAUDE.md file, Claude Code is guessing at your team's conventions, naming patterns, and coding standards. Every guess costs tokens and risks wrong output. Marcus needs to fix this first.

Marcus types /init to generate a starter CLAUDE.md. Claude Code analyzes the codebase and produces a draft.

CLAUDE.md — generated

> /init

Analyzing codebase conventions...

✓ Build system: CMake 3.26 + Ninja

✓ Language: C++20 with engine-specific extensions

✓ Test framework: GoogleTest

✓ Naming: PascalCase (classes), snake_case (functions)

CLAUDE.md created. Review and customize before committing.

Tip: Add engine-specific context your team knows but I can't infer.

✅

CLAUDE.md is a one-time investment that pays every session

Every project-specific convention you add to CLAUDE.md is context Claude Code gets for free on every future session — without burning tokens to re-discover it. Think of it as a briefing document your AI partner reads before every shift.

Marcus sees the warning: "No CLAUDE.md found — operating without project context." What is the most important reason to resolve this before doing any real work?

A

Without CLAUDE.md, Claude Code will refuse to run any commands.

B

Without CLAUDE.md, Claude Code guesses at conventions — wasting tokens on wrong assumptions and producing output that may not match team standards.

C

CLAUDE.md is only needed for large projects with more than 500 files.

D

Without CLAUDE.md, Claude Code cannot read the codebase at all.

◆ Lesson 2 of 5

Context &
Token Efficiency

The single biggest mistake new Claude Code users make — and how to avoid it. Marcus is about to learn the hard way.

10 min

Interactive comparison

💸

Tuesday afternoon — Marcus hits a wall

He's been in a Claude Code session for 90 minutes. Something feels off.

Marcus has been exploring — asking Claude Code to explain modules, suggest improvements, try different approaches. It's been interesting. But his tech lead pings him:

"Hey — saw you used ~85k tokens in your session today. That's about 4x what we budgeted per dev per day. Everything okay?"

— @tlead-jordan

Marcus hadn't thought about it. He was just… talking to it. Figuring things out.

Session Token Usage

84,231 / 100,000

⚠ Daily budget nearly exhausted — exploratory session with no defined spec

🔥

What happened — and why it matters

Marcus used Claude Code like a chat interface — open-ended, exploratory, iterative. This is the most expensive way to use it. Every back-and-forth, every "actually, can you try a different approach," every context load of files he didn't need — all of it costs tokens. The output quality also degrades as the context window fills with noise from earlier in the conversation.

The Mental Model: Sessions as Surgery, Not Conversation

Think of each Claude Code session as a surgical procedure — not an open-ended chat. You go in with a clear plan, execute the specific task, and close the session. The longer and more exploratory a session runs, the more tokens burn and the more noise accumulates in context.

❌ Exploratory (Expensive)

"Can you look at the physics module and see if there's anything to improve?"

→ Claude reads entire physics module (8 files)
→ Generates broad suggestions
→ You ask follow-ups
→ It tries 3 different approaches
→ Context fills with dead ends

~18,000 tokens • Low predictability

✓ Spec-Driven (Efficient)

"In physics/collision_resolver.cpp, the broadphase_check() function has O(n²) complexity. Rewrite it using a spatial hash grid. Do not modify any other files. Use our existing Vec3 math utilities."

→ Claude reads 1 file + Vec3 header
→ Executes exactly what's asked
→ Requests approval before saving
→ Session closes cleanly

~2,400 tokens • High predictability

⚡

The token efficiency formula

Tight scope + complete context upfront = fewer tokens, better output. When Claude Code knows exactly what to do and exactly what constraints apply, it doesn't explore, backtrack, or over-generate. Writing a good spec takes 5 minutes and saves 15,000 tokens. Every time.

The Three-Phase Discipline

📝

Before the session

Write the spec before opening Claude Code. Load only the files it actually needs. Verify CLAUDE.md is current. Never use Claude Code to figure out what you want to build.

🎯

During the session

Use Plan Mode for complex tasks. Set explicit file boundaries in every prompt. Recognize when a session goes off-track and reset — a clean session costs less than fixing a broken one.

✅

After the session

Review output before approving — check for scope creep, not just correctness. Update CLAUDE.md if you discovered new conventions. Capture prompts that worked for the prompt library.

Efficient Session — Same Task

2,847 / 100,000

✓ Spec written first • Scoped to 1 file • Boundaries explicit • Plan Mode used

◆ Lesson 3 of 5

The
Spec-Driven Workflow

Marcus writes his first real spec. This is the skill that separates developers who get results from developers who burn budget and give up.

10 min

Branching scenario

📋

Wednesday — Marcus has a real task

Tech lead assigned: add input validation to the player session initializer

Marcus has a concrete task: the PlayerSession::Initialize() function in the networking layer doesn't validate its inputs. He needs to add validation and unit tests.

He remembers Tuesday's lesson. Before he opens Claude Code, he writes a spec.

The Spec Template — What Every Prompt Needs

spec.md CLAUDE.md-compatible format

## Goal

Add input validation to PlayerSession::Initialize() in networking/player_session.cpp.

Write matching unit tests in tests/networking/player_session_test.cpp.

## Context

- Relevant files: networking/player_session.cpp, networking/player_session.h

- Validation should match patterns in networking/lobby_manager.cpp (see ValidateLobbyInput())

- Test framework: GoogleTest (see tests/README.md for conventions)

## Constraints

- C++20 only. No new dependencies.

- Do NOT modify player_session.h (interface is locked for this sprint)

- Error handling via our existing VortexResult pattern, not exceptions

- Max function length: 40 lines (team standard)

## Acceptance Criteria

- Null/empty player ID returns VortexResult::InvalidInput

- Session token length > 256 chars returns VortexResult::TokenTooLong

- Valid inputs pass through unchanged

- All new code has unit test coverage

## Out of Scope

// Explicit out-of-scope prevents Claude Code from over-generating

- Do not refactor existing validation logic elsewhere

- Do not add logging (separate PR)

- Do not modify any file not listed above

🎯

Why "Out of Scope" is the most important section

Undefined boundaries are where token waste lives. Without explicit out-of-scope statements, Claude Code will try to be helpful — refactoring adjacent code, adding logging, improving related functions. Each unsolicited action costs tokens and introduces risk. Tell it what not to do.

Marcus uses Plan Mode first

Claude Code — Plan Mode

> /plan [pastes spec above]

Plan — PlayerSession Input Validation

Files I will read:

1. networking/player_session.cpp (target file)

2. networking/player_session.h (reference only, will not modify)

3. networking/lobby_manager.cpp (ValidateLobbyInput pattern)

4. tests/networking/player_session_test.cpp (test target)

Files I will modify:

1. networking/player_session.cpp — add validation block

2. tests/networking/player_session_test.cpp — add 4 test cases

Steps:

1. Read lobby_manager ValidateLobbyInput() for pattern reference

2. Add validation to Initialize() using VortexResult pattern

3. Write 4 unit tests covering: null ID, empty ID, token too long, valid input

Estimated tokens: ~3,200. Proceed? [y/n]

✅

Plan Mode surfaces misunderstandings before they cost you

Marcus can see exactly what Claude Code is about to touch. If anything looks wrong — a file it shouldn't read, a step it's missing — he corrects it now, before a single token is spent on execution. This is the approval workflow at its most powerful.

Scenario: Marcus gets a decision to make

The plan looks good. Marcus types 'y' to proceed. Claude Code executes and produces the code. When reviewing the output, Marcus notices it also added a helper function called ValidateSessionToken() that wasn't in the spec — but it looks genuinely useful and well-written. What should Marcus do?

◆ Lesson 4 of 5

When Things
Go Wrong

Every developer hits a failure with Claude Code. The difference between those who adopt it and those who don't is knowing how to diagnose and recover — not avoiding failure entirely.

8 min

Failure scenario

1 knowledge check

🔥

Thursday — Marcus hits a real problem

The session spirals. Claude Code produces confidently wrong output.

Marcus has a more complex task today: refactor the audio spatial positioning system to support the new 3D listener API. He's in a hurry — standup is in 40 minutes — and skips writing a proper spec. He types directly into Claude Code:

Claude Code — Thursday session

> Refactor the audio spatial positioning to support the new 3D listener API

I'll refactor the spatial audio system. Let me read the relevant files...

Reading: audio/spatial_audio.cpp, audio/spatial_audio.h, audio/listener.cpp,

audio/audio_manager.cpp, audio/reverb_engine.cpp, audio/occlusion.cpp...

⚠ Reading 6 files to understand full audio subsystem context

I'll update the spatial positioning to use the new listener API. I'm also

taking this opportunity to modernize the reverb engine integration and

improve the occlusion calculation approach...

Proposed changes: 4 files modified, 847 lines changed

This is significantly larger than expected.

🚨

Three failure modes hit at once

1. Vague prompt → scope explosion. "Refactor the audio spatial positioning" gave no boundaries, so Claude Code interpreted "helpful" as "fix everything adjacent."

2. No Plan Mode → no checkpoint. Without /plan, Marcus had no opportunity to see the scope before it happened.

3. Token burn from over-reading. Loading 6 files when 2 were relevant cost ~12,000 tokens before a single line was written.

The Recovery Protocol

When a session goes off-track, the instinct is to keep correcting mid-stream. This is almost always wrong. Correction prompts add more noise to an already-cluttered context, burning more tokens and producing increasingly inconsistent output. The right move is to reset.

🛑

Step 1: Stop & Reject

Do not approve any of the output. Type 'n' or close the session. Reject all proposed changes. A clean slate costs less than trying to salvage a derailed session.

🔍

Step 2: Diagnose

Ask: Was the prompt too vague? Were boundaries missing? Did I skip Plan Mode? Was the CLAUDE.md missing relevant context? The diagnosis determines the fix.

📝

Step 3: Write the spec

The session that failed needed a spec. Write it now. Takes 5 minutes. Specify exactly which files, exactly what changes, exactly what to ignore.

🚀

Step 4: New session, /plan first

Start fresh. Open Claude Code in a clean session, paste the spec, and run /plan before executing. The new session will cost a fraction of the failed one.

💡

Failure is data, not defeat

Every failure mode Marcus hits is a prompt library entry waiting to happen. "Don't use Claude Code to refactor audio systems without these specific constraints" — that's a note that saves the next developer 12,000 tokens and 40 minutes of frustration. Capture it.

Marcus's session spiraled because he gave Claude Code a vague prompt and skipped Plan Mode. Now the session has produced 847 lines of unwanted changes. What is the correct next step?

A

Accept the output and manually review all 847 lines to identify what to keep.

B

Continue in the same session and ask Claude Code to undo the extra changes.

C

Reject all output, close the session, write a proper spec for just the listener API change, and start a fresh session with /plan first.

D

Ask Claude Code to explain every change it made before deciding.

◆ Lesson 5 of 5

Your
Prompt Library

The prompt library is the team's institutional memory for working with AI. By Friday, Marcus has something to contribute — and a system to benefit from.

6 min

Final lesson

📚

Friday — Marcus has learned something worth sharing

And the prompt library is where it lives permanently

By the end of his first week, Marcus has discovered something he didn't expect: when Claude Code works, it works remarkably well. The PlayerSession validation task on Wednesday took 22 minutes start-to-finish — including spec writing. Without Claude Code, he estimates it would have taken 90 minutes.

He also discovered what doesn't work — and that's equally valuable. The team's prompt library needs both.

What a Good Prompt Library Entry Looks Like

prompt-library/networking/add-input-validation.md ✓ Verified • Engine Team

## When to use this

Adding input validation to a function that currently has none.

Works best for: session init functions, API entry points, config loaders.

## When NOT to use this

Do not use for functions with existing validation — use the refactor template instead.

## Prompt template

"In [FILE], the [FUNCTION_NAME] function needs input validation.

Add validation using our VortexResult pattern (see networking/lobby_manager.cpp

for reference). Validate: [LIST_CONDITIONS]. Write matching GoogleTest unit tests

in tests/[MATCHING_TEST_FILE]. Do NOT modify [FILE].h or any other files."

## Token profile

~2,400–3,500 tokens depending on function complexity.

Always use /plan first. Estimated time: 15–25 min including spec writing.

## Known limitations

Does not handle async validation patterns — use async-validation template.

// Added by marcus.reid — verified on engine-core sprint 47

🏗️

Every entry has five components

When to use it — specific workflow moment, not a topic. When NOT to use it — prevents misapplication. The template — with bracketed placeholders for what to swap. Token profile — sets expectations. Known limitations — captures what the contributor learned the hard way.

Where the Library Lives — and Why It Matters

📁

GitHub Repository

Version-controlled, PR-based contributions, works with your existing workflow. Every change is tracked and attributed. The contribution model developers already know.

🤖

CLAUDE.md Integration

Your highest-frequency prompts live directly in CLAUDE.md — loaded automatically every session, zero friction. The best prompts should never require a lookup.

💬

Slack #ai-prompts Channel

Low-friction contribution path for things that worked. "This prompt saved me 2 hours" gets more organic sharing than a formal submission form ever will.

🎯

Marcus's week — what changed

Monday: skeptical. Tuesday: burned tokens exploring. Wednesday: nailed a scoped task with a proper spec — 22 minutes. Thursday: recovered from a failure without losing the day. Friday: contributed to the prompt library. That's the adoption curve in one week. Your job is to make it that smooth for 200 engineers.

🏆

Module Complete

You've completed Claude Code: Your First Week. Marcus went from skeptic to contributor in five lessons. Now it's your turn.

5

Lessons

2

Knowledge Checks

45min

Est. Duration

What you covered

⚙️

CLAUDE.md Setup

Why project context is a token investment that pays back every session.

⚡

Token Efficiency

The surgery mindset — scoped sessions, upfront context, clean resets.

📋

Spec-Driven Workflow

The five-part spec template and why Out of Scope is the most important field.

🔄

Failure Recovery

The four-step reset protocol — reject, diagnose, spec, restart.

📚

Prompt Library

How to contribute entries that actually get used — and how to benefit from others'.

🚀

Your next steps

This week: Run /init on your primary project and review the generated CLAUDE.md. Add two team-specific conventions it couldn't infer.

This sprint: Write a proper spec before your next Claude Code task. Use /plan. Track your token usage before and after.

This month: Contribute one prompt library entry based on something that worked for you.