Claude Code Power User Workshop

Velais Engineering Team — Internal Workshop

Format: 30-min briefing → Full hands-on build day Deliverable: A working MVP — automation, tool, or mini app — shipped via PR

Before You Arrive

Make sure you have the following ready:

Claude Code installed — native installer is recommended (no Node.js required, auto-updates):

# macOS (Homebrew — recommended)
brew install --cask claude-code

# macOS / Linux / WSL (shell script)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Run claude doctor after install to verify your setup.

Claude.ai desktop app installed
velais-skills repo cloned and symlinked: ls -la ~/.claude/skills/
At least one MCP server configured (GitHub, Filesystem, or Notion — see .mcp.json examples in the repo)
An idea — even a rough one — for something useful you want to build

Part 1 — Briefing (30 min)

“Before you touch a keyboard, understand the machine you’re working with.”

1.1 — Stop Thinking of It as Autocomplete

Claude Code is not a smarter Copilot. It is an agentic loop.

When you give it a task, it works through three phases — repeatedly:

Gather context → Take action → Verify results

These phases blend together. Claude chains dozens of tool calls, course-corrects based on what it finds, and keeps going until the task is done or you intervene. The agentic loop is powered by two components: models that reason and tools that act. Understanding that distinction changes how you prompt.

Key mental shift: You are not writing a prompt. You are setting the conditions for an agent to work autonomously. The quality of your setup determines the quality of the output — not the cleverness of your words mid-session.

1.2 — Context Is Your Scarcest Resource

This is the single most important concept in the briefing.

Anthropic’s engineering team describes it clearly:

“LLMs have an ‘attention budget’ that they draw on when parsing large volumes of context.”

Every token in the context window costs attention. As context grows, recall degrades. This happens to every model. Claude 4.x is better at managing it, but the constraint is architectural: self-attention results in n² pairwise relationships for n tokens. Bigger context = thinner attention.

This is why power users think about context engineering — not just prompting.

#—

The four levers you have:

Lever	What it does	When to use it
`CLAUDE.md`	Drops high-signal context upfront, every session	Always — set it up before you start
Plan Mode	Read-only exploration before any file is touched	Any task touching multiple files
`/compact`	Summarises the session, keeps the critical bits	When the context indicator fills up
Subagents	Isolate expensive research into a separate context window	When a subtask would flood your main thread

1.3 — Prompting Claude 4.x Is Different

Claude 4.x has extended thinking available — and it’s enabled by default in Claude Code. Claude reasons through problems step by step before responding. This means some old prompting habits work against you.

Remove these from your prompts:

Old habit	Why it’s now harmful
”Think carefully before answering”	Vague — thinking is already on. Use `Option+T` / `Alt+T` to toggle it if needed
”Be thorough, don’t be lazy”	Claude 4.6 is already proactive; this causes over-correction and write-then-rewrite cycles
”You MUST use [tool]“	Triggers over-use; use “use [tool] when it would help” instead

#—

What works instead:

Be specific, not motivational. Reference exact files with @. Name constraints explicitly.
Separate what you want from how you want it done.
Use Plan Mode instead of asking Claude to “think first” — Plan Mode is a read-only exploration mode, while thinking is internal reasoning. They serve complementary purposes.
Press Option+T (macOS) or Alt+T (Win/Linux) to toggle extended thinking on/off during a session.
On Opus 4.6, thinking uses adaptive reasoning — the model dynamically allocates thinking based on task complexity. Three effort levels are available: low, medium, and high (default).

Important: Thinking is enabled by default. Option+T / Alt+T toggles it on/off session-wide. Effort level can be adjusted via /model (use left/right arrow keys), the CLAUDE_CODE_EFFORT_LEVEL environment variable, or the effortLevel setting. Note: phrases like “think”, “think hard”, “ultrathink”, and “think more” are interpreted as regular prompt instructions and don’t allocate thinking tokens. The exception: including “ultrathink” in a skill’s SKILL.md file enables extended thinking for that skill.

1.4 — The Golden Rule: Separate Research from Implementation

This is Anthropic’s single most-repeated best practice across every official resource:

“Letting Claude jump straight to coding can produce code that solves the wrong problem.”

The recommended four-phase workflow:

Explore — enter Plan Mode, ask Claude to read relevant files. No code yet.
Plan — ask for a detailed implementation plan. Review it. Press Ctrl+G to open the plan in your text editor for direct editing. Redirect Claude with a follow-up prompt if anything is off before implementation starts.
Implement — switch back to normal mode. Let Claude build against the plan.
Commit — ask Claude to write the commit message, push, open the PR.

Steps 1 and 2 are where most people skip. They’re also where most time is saved.

Part 2 — The Build (Hands-On, Self-Directed)

“Build something real. Keep it MVP. Ship it.”

You choose what you build — an automation, a tool, a mini app. The only constraint: start with the smallest thing that works, then expand. This is a day for getting comfortable with the workflow, not for finishing a product.

You must go through every step below. That’s what makes this a mastery exercise.

Step 1 — Research on Claude Desktop (Before Any Code)

Open Claude.ai desktop — not Claude Code.

This is a deliberate context switch. Claude Code is for building. Claude desktop is for thinking. Use it to answer:

What does this thing actually need to do?
What are the edge cases I haven’t thought of?
What’s the right architecture for an MVP?
Which MCP server gives my agent the reach it needs?
Are there existing libraries or APIs I should know about?

Enable web search in Claude desktop and research freely. Paste links, upload docs, ask it to compare approaches. The goal is to arrive at Claude Code with clarity — not to discover the problem while the agent is already writing files.

Produce one output from this phase: a rough spec in plain text. Even a few bullet points. You’ll use it in the next step.

Pro tip: Ask Claude desktop to help you articulate what your CLAUDE.md should say. It’s good at this and it forces you to think through the project before you’re in the middle of it.

Step 2 — Write Your CLAUDE.md First

Before you open a terminal, write your CLAUDE.md. This is what separates deliberate from reactive development.

Create two files:

./CLAUDE.md — project-level, checked into git, shared with the team:

# Project Overview
[2-3 sentences on what this is and what it does]

# Architecture
[Key files, how they connect, anything non-obvious]

# Key Commands
- npm run dev: Start dev server
- npm run test: Run tests
- npm run build: Production build

# Coding Conventions
- [Language/framework preferences]
- [Import style]
- [Any patterns to follow]

# MCP Servers
- [Name]: Use for [specific purpose]. Configured in .mcp.json.

# Context Management
- When compacting, always preserve: list of modified files, failing tests, and any unresolved decisions

# Gotchas
- [Anything unexpected about this codebase or environment]

~/.claude/CLAUDE.md — user-level, applies to all your sessions:

# My Preferences
- Response style: [concise / detailed]
- Always use TypeScript where possible
- Prefer named exports over default exports
- Ask before making architectural decisions

What makes a good CLAUDE.md:

Concise and human-readable — it’s not documentation, it’s a briefing
Includes the key commands Claude will actually need to run
Names the MCPs explicitly and tells Claude when to use them
Has a compaction hint so critical context survives /compact
Can import additional files using @path/to/import syntax
Can be tuned using Anthropic’s Prompt Improver

Note: When you run /init at the start of a session, Claude will auto-generate a CLAUDE.md from your codebase. Use it as a starting point, not a finished product — always review and tighten it.

Step 3 — Configure Your MCP

Every build today must use at least one MCP. This isn’t a box-tick — MCPs give your agent real reach into the world outside the filesystem.

Check what’s configured:

cat .mcp.json                # project-level MCP config
cat ~/.claude/settings.json  # user-level settings (including MCPs)

#—

Add one if you don’t have what you need:

# GitHub — HTTP transport (recommended for remote servers)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Filesystem — local stdio server
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# List configured MCP servers
claude mcp list

# List connected MCP servers in a session
/mcp

# View details for a specific server
claude mcp get github

Tell Claude when to use it in your CLAUDE.md:

# MCP Servers
- github: Use when interacting with GitHub issues, PRs, or repo metadata. Never use gh CLI directly.

The MCP instruction in CLAUDE.md is what makes the agent use it reliably. Without it, Claude will sometimes reach for a bash workaround instead.

Step 4 — Enter Plan Mode and Write a Deliberate Prompt

Now open Claude Code in your project directory.

cd your-project
claude

Switch to Plan Mode:

Press Shift+Tab to cycle through permission modes. From Normal Mode, the first Shift+Tab switches to Auto-Accept Mode (⏵⏵ accept edits on at the bottom of the terminal). A second Shift+Tab switches into Plan Mode (⏸ plan mode on). In this mode, Claude reads files and explores — it cannot make changes.

You can also start a new session directly in Plan Mode:

claude --permission-mode plan

#—

Write your opening prompt. Be specific:

Read @src/auth/ and understand how session management works.
Also read @package.json to understand our dependencies.
Don't write any code yet.

Then create a detailed plan for building [your MVP].
The plan should:
- List every file that needs to change or be created
- Describe the implementation approach for each
- Call out any dependencies or risks

I'll review and approve the plan before you start coding.

After Claude produces the plan:

Read it carefully. If something’s off, stay in Plan Mode and prompt Claude to revise it.
Only when you’re satisfied, confirm and switch back to Normal Mode (Shift+Tab again to cycle through).

Referencing your skill in the prompt:

When creating [specific output], use the velais-brand-guidelines skill
to ensure the output follows our brand conventions.

Claude will read the skill’s SKILL.md when it encounters that task, loading only what it needs — this is progressive disclosure working as designed.

Hint: If you’re unsure whether your prompt is specific enough, ask yourself: could Claude misinterpret this and build something technically correct but wrong? If yes, add more constraints.

Step 5 — Follow the Agent and Manage Context

Switch back to normal mode (Shift+Tab once more from Plan Mode) and let Claude build.

Your job during execution is not to watch passively. You are an active collaborator.

Things to do while Claude works:

Press Ctrl+O to toggle verbose output — see detailed tool usage and execution as Claude works
Press Ctrl+C to interrupt at any point if it’s going in the wrong direction — then redirect with a new prompt
Press Esc+Esc or run /rewind to restore code and/or conversation to any previous checkpoint
Use @filename to pull in context Claude hasn’t read yet
Run /context to see what’s consuming your context window

Context management during the build:

Watch the context indicator in the status bar. When it starts filling up:

# Targeted compact — tell it what to preserve
/compact Focus on the API integration and keep the list of modified files

# Check what's consuming context before deciding whether to compact or clear
/context

# Use a subagent for expensive research tasks to keep main context clean
"Use a subagent to read the GitHub MCP documentation and summarise the available tools"

The subagent pattern is powerful: verbose work (reading docs, grepping large dirs, running tests) stays in the subagent’s isolated context. Only the summary returns to your main thread, keeping it clean for implementation.

For tasks with many steps, use a checklist:

Create a markdown checklist of everything that needs to be done
and check items off as you complete them. Update it after each
significant step so we have a working record.

This mirrors how Anthropic’s own teams use Claude Code on long-horizon tasks — a progress.md or todo.md file the agent maintains gives both you and Claude a shared anchor across the session. Claude also creates an automatic task list for complex multi-step work, visible via /todos or toggled with Ctrl+T.

Step 6 — Test-Driven Iteration

Before moving to reviews, write tests. This is the Anthropic-recommended workflow for anything verifiable:

The TDD loop with Claude Code:

1. Ask Claude to write tests based on expected inputs and outputs.
   Be explicit: "We are doing TDD. Do not write any implementation code yet.
   Do not use mocks for functionality that doesn't exist."

2. Tell Claude to run the tests and confirm they fail.

3. Once you're satisfied with the tests, ask Claude to commit them.

4. Ask Claude to write the implementation that makes the tests pass.
   "Do not modify the tests. Keep going until all tests pass."

5. Commit the implementation separately.

Claude performs best when it has a clear target to iterate against. Tests are that target — they let it make changes, check results, and adjust until it succeeds.

If your project uses the velais-skills repo (skill creation, Workshop B), the equivalent here is running the validator and fixing what it surfaces before moving to code review:
uv run scripts/validate_skill.py skills/your-skill-name
# Score must be ≥70 before proceeding

Step 7 — Security Review

Run a security review using a subagent or custom skill:

Use a subagent to review the code for security vulnerabilities.
Look for injection vulnerabilities, authentication flaws,
secrets in code, and insecure data handling.
Provide specific line references and suggested fixes.

Note: There is no built-in /security-review slash command. You can create a custom skill or subagent for this purpose. See the example security-reviewer subagent in the best practices docs.

Read what it surfaces critically and don’t auto-accept all fixes. The review looks for:

Secrets or credentials hardcoded or leaking through environment
Destructive operations without proper guards
Prompt injection vectors (especially relevant if your tool accepts external input)
Filesystem or network access that’s broader than needed

The guiding principle from Anthropic’s sandboxing work: Claude should take local, reversible actions freely. Anything destructive, hard-to-reverse, or visible to others should require explicit confirmation.

Think about blast radius: If this automation ran with a bug, what’s the worst it could do? The security review helps you surface that before it happens in production.

Step 8 — Code Review

Run a code review using a subagent, a custom skill, or by asking Claude directly:

Review the code changes on this branch for quality, patterns,
and maintainability. Check that the patterns are consistent
with the CLAUDE.md conventions.

Note: There is no built-in /review slash command. You can create a custom skill at .claude/skills/review/SKILL.md or .claude/commands/review.md to make /review available as a slash command.

This is a different lens from the security review. Where the security review is about blast radius and trust, the code review is about quality, patterns, and maintainability.

Pay attention to:

Are the patterns consistent with your CLAUDE.md conventions?
Is the code overly engineered? Claude can tend toward unnecessary abstractions — the review often surfaces these.
Are there obvious simplifications?

You can ask Claude to address specific comments from the review:

Fix the issues flagged in the code review output, but don't change
the test structure or the public API surface.

Step 9 — Commit and Open a PR

Let Claude handle the git workflow:

Commit all changes with a descriptive commit message.
Then push the branch and open a PR against main.
Use the gh CLI. The PR description should explain what was built
and how to test it.

Claude will look at the diff and context to write the commit message. It’s consistently better at this than writing them manually because it actually reads what changed. When you create a PR with gh pr create, the session is automatically linked to it — you can resume it later with claude --from-pr <number>.

If you’re working in the velais-skills repo, the CI quality gate (skill-quality-gate.yml) runs automatically on anything touching skills/**. It validates structure, checks for overlaps with existing skills, tracks scores, and posts a comment on your PR. Read it — address any flags before asking for a review.

Reference Card — Essential Commands

# ─── KEYBOARD SHORTCUTS ─────────────────────────────────────────────────────
Shift+Tab         → Cycle permission modes: Normal → Auto-Accept → Plan
Option+T / Alt+T  → Toggle extended thinking on/off
Ctrl+O            → Toggle verbose output (detailed tool usage and execution)
Ctrl+C            → Cancel current input or generation
Ctrl+B            → Move current bash command to background
                     (tmux users: press Ctrl+B twice)
Ctrl+D            → Exit Claude Code session
Ctrl+L            → Clear terminal screen (keeps conversation history)
Ctrl+R            → Reverse search command history
Ctrl+T            → Toggle task list
Ctrl+G            → Open prompt in default text editor
Ctrl+V / Cmd+V    → Paste image from clipboard
Ctrl+F            → Kill all background agents (press twice within 3s)
Option+P / Alt+P  → Switch model
Esc+Esc           → Rewind — restore code and/or conversation to a prior point
!                 → (at start of input) Run a bash command directly
@                 → File path autocomplete / reference a file

# ─── SESSION MANAGEMENT (CLI FLAGS) ─────────────────────────────────────────
claude --continue             → Resume most recent session in this directory
claude --resume               → Open interactive session picker
claude --resume <name>        → Resume session by name
claude --from-pr <number>     → Resume session linked to a specific PR
claude --permission-mode plan → Start new session directly in Plan Mode
claude --worktree <name>      → Create isolated git worktree and start Claude

# ─── SESSION MANAGEMENT (SLASH COMMANDS) ─────────────────────────────────────
/resume          → Open session picker from inside an active session
                   (navigate to any session and press R to rename it)
/clear           → Clear conversation history — use between tasks
/compact         → Compact conversation. Focus tip: /compact Focus on X
/rewind          → Rewind conversation and/or code to a previous state
/context         → Visualise context usage as a coloured grid
/config          → Open settings interface
/init            → Initialize project with CLAUDE.md guide
/model           → Select or change the AI model; adjust effort with arrow keys
/plan            → Enter Plan Mode
/permissions     → Configure permission allowlists
/todos           → List current TODO items
/tasks           → View task list
/stats           → Show session statistics
/cost            → Show cost information
/doctor          → Run diagnostic checks
/memory          → Edit CLAUDE.md files

# ─── CONTEXT & FILES ─────────────────────────────────────────────────────────
@filename        → Reference a specific file (adds full content to context)
@dir/            → Include a directory listing
cat file | claude → Pipe data directly into Claude

# ─── MCP ─────────────────────────────────────────────────────────────────────
claude mcp add --transport http <n> <url>      → Add a remote HTTP MCP server
claude mcp add --transport stdio <n> -- <cmd> → Add a local stdio MCP server
claude mcp list                                → List all configured MCP servers
claude mcp get <name>                          → Get details for a specific server
/mcp                                           → Manage MCP connections in session

# ─── AGENTS & TOOLS ─────────────────────────────────────────────────────────
/agents           → View and manage custom subagent configurations

# ─── GIT (VIA CLAUDE) ────────────────────────────────────────────────────────
"commit with a descriptive message and push"
"open a PR against main with a description of what was built"
"search git history to understand why X was implemented this way"

The MVP Constraint

Build the smallest thing that works. Then stop.

The point of today is workflow mastery, not product completion. A well-structured MVP that went through every step of this workshop — research, CLAUDE.md, Plan Mode, MCP, tests, security review, code review, PR — is worth more than a half-finished ambitious project that skipped the important parts.

Ask yourself after each phase: Does this work? Can I demonstrate it? If yes, that’s your MVP. Everything else is scope creep.

Demo & Debrief (20 min)

Each person gets 2 minutes:

Show what you built (live demo or screenshot)
One thing that surprised you
One thing you’d do differently

Then one group question: What’s the first thing you’d build for a client project using this workflow?

That question is how the Velais approach to agentic development grows.

Official Anthropic References

All resources used in this workshop are official Anthropic sources only.

Topic	Source
How Claude Code works (agentic loop, tools)	code.claude.com/docs/en/how-claude-code-works
Installation & setup	code.claude.com/docs/en/setup
Best practices — official docs	code.claude.com/docs/en/best-practices
Context engineering (attention budget, compaction, subagents)	anthropic.com/engineering/effective-context-engineering-for-ai-agents
Claude 4.x prompting guide	platform.claude.com — Claude 4 best practices
Interactive mode — full keyboard shortcut reference	code.claude.com/docs/en/interactive-mode
Keybindings reference	code.claude.com/docs/en/keybindings
Model configuration & effort levels	code.claude.com/docs/en/model-config
Plan Mode & common workflows	code.claude.com/docs/en/common-workflows
CLAUDE.md & memory	code.claude.com/docs/en/memory
Checkpointing — rewind & restore	code.claude.com/docs/en/checkpointing
MCP configuration	code.claude.com/docs/en/mcp
Custom subagents	code.claude.com/docs/en/sub-agents
Skills (unified with slash commands)	code.claude.com/docs/en/skills
Plugins reference	code.claude.com/docs/en/plugins-reference
Security & sandboxing	anthropic.com/engineering/claude-code-sandboxing
Agent Skills — engineering deep dive	anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
Agent Skills — product announcement	anthropic.com/news/skills
How Anthropic teams use Claude Code	anthropic.com/news/how-anthropic-teams-use-claude-code
Prompt improver (for tuning CLAUDE.md)	docs.anthropic.com — prompt improver

Appendix — Workshop B Preview (Skill Authoring)

This is a separate session, recommended a few weeks after Workshop A.

Skill authoring works best when you have a working example to extract from — which is exactly what you’ll have after today. In Workshop B, you’ll take something you built in Workshop A, work inside the velais-skills/ repo with Claude Code, and turn it into a reusable, validated skill that the whole team can use.

The workflow will cover:

Using bash scripts/new_skill.sh to scaffold correctly
Writing a description field that triggers reliably (the hardest part)
Using existing velais skills as reference corpus for Claude to pattern-match against
Running validate_skill.py and iterating to ≥70 score
Writing proper test-cases.yml with trigger diversity and specific assertions
Running LLM evals with eval_runner.py
Getting through the CI quality gate and merging to main

Note: In current Claude Code, custom slash commands and skills are unified — a file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work identically. Skills add optional features: frontmatter to control invocation (e.g., disable-model-invocation), subagent execution, and automatic loading by Claude when relevant. Files in .claude/commands/ still work and support the same frontmatter; if a skill and a command share the same name, the skill takes precedence.

Workshop designed by Velais Engineering. All technical references link to official Anthropic documentation, engineering blogs, and product announcements. Last verified: February 2026.