Claude Code Workflows

Maximum AI power — use Claude Code for complex development tasks, autonomous coding, and advanced workflows.

INFO

• Time: ~5-7 hours
• Difficulty: Advanced
• Prerequisites: Core Modules + Flagship Project + Terminal comfort

---

This Page Covers

• What Claude Code Is - Why you might use it and how it differs from chat-based AI
• Installation & Setup - Node.js, API key, and first-time configuration
• Basic Usage - Your first conversation and effective instructions
• Project Context - CLAUDE.md files and memory hierarchy
• Plan Mode - Handling complex multi-step tasks
• MCP Servers - External integrations
• Custom Commands - Skills and headless mode
• Workflows - Effective patterns and best practices

---

Who This Is For

Target Audience

This specialization is ideal if you:

• Are comfortable working in the terminal
• Want maximum AI assistance for coding
• Have existing projects you want to improve
• Prefer working locally rather than in a browser

Prerequisites

Before starting, make sure you:

• Completed Core Modules (especially Module 2: Development Environment)
• Can navigate folders using terminal commands (cd, ls, pwd)
• Have Node.js installed (check with node --version)
• Have a code project to work on (your flagship project works great!)

If terminal commands feel unfamiliar, review Module 2 first.

---

What is Claude Code?

A Terminal-Based AI Assistant

Claude Code is Anthropic's official command-line tool for AI-assisted development. Instead of using a web browser or a chat window, you run Claude Code directly in your terminal.

Think of it this way:

• Claude.ai (web) = chatting with Claude in a browser window
• Claude Code (terminal) = Claude working directly with your files on your computer

Why Use Claude Code Instead of Other Tools?

Direct file access: Claude Code can read, write, and edit files on your computer. No copy-pasting code back and forth.

Runs in your environment: It works directly in your project folder, so it understands your project structure.

Powerful for coding: Claude Code can:

• Explore your codebase and explain what it does
• Make changes across multiple files
• Run commands like tests or builds
• Create new files when needed

Works offline-ish: Once installed, you only need internet for the AI responses, not for file operations.

When Claude Code shines:

• Making changes to existing projects
• Understanding unfamiliar code
• Refactoring across multiple files
• Automating repetitive coding tasks

When other tools might be better:

• Quick questions (use Claude.ai in browser)
• Building a new app from scratch with AI (use Lovable or similar)
• Sensitive data handling (keep AI away from private info)

---

Installation

Step 1: Install Claude Code

Open your terminal and run:

npm install -g @anthropic-ai/claude-code

What this does:

• npm install downloads and installs a package
• -g means "global" — install it so you can use it anywhere, not just in one project
• @anthropic-ai/claude-code is the package name

The installation takes a minute or two. You'll see progress messages.

If you get a permission error: The best fix is to use nvm to manage Node.js, which avoids permission issues entirely. As a quick workaround, you can use sudo, but this isn't recommended for long-term use:

sudo npm install -g @anthropic-ai/claude-code

Step 2: Verify Installation

Check that it installed correctly:

claude --version

You should see a version number. If you see "command not found," try closing and reopening your terminal.

Step 3: Authentication

The first time you run Claude Code, you'll need to connect it to your Anthropic account.

Run:

claude

Claude Code will guide you through authentication:

1. It opens your browser to Anthropic's website
2. You log in (or create an account if you don't have one)
3. You authorize Claude Code to use your account
4. The terminal confirms you're connected

Note: Claude Code requires either a Claude Pro/Max subscription or an Anthropic API key. Your usage counts toward your plan limits.

Step 4: First Run

Navigate to any project folder and start Claude Code:

cd ~/Projects/my-project
claude

You'll see Claude Code's interface — a prompt waiting for your input. Type /help to see available commands.

---

Basic Usage

Starting Claude Code

Always start Claude Code from inside a project folder:

cd ~/Projects/your-project
claude

This is important! Claude Code uses your current folder as context. If you start it from your home folder, it won't know which project you're working on.

Asking Claude to Explain Code

One of the best ways to start is by asking Claude to explain what your project does.

Try these prompts:

What does this project do?

Explain the main files in this project

How does the login functionality work?

Claude will read your files and give you an explanation. This is incredibly useful when:

• You're returning to a project after time away
• You inherited code from someone else
• You want to understand how something works

Asking Claude to Make Changes

Once you understand the codebase, you can ask Claude to make changes.

Be specific about what you want:

Add a logout button to the navigation bar

Change the primary color from blue to green in the CSS

Add form validation to the email field

Vague requests get vague results. Instead of make the form better, say:

Add validation that checks if the email contains an @ symbol

Reviewing Proposed Changes

This is the most important part: always review changes before accepting them.

When Claude proposes changes, you'll see a "diff" view — this shows what will be added (in green) and what will be removed (in red).

Before accepting:

1. Read through the changes
2. Make sure you understand what's being modified
3. Check that it matches what you asked for
4. Look for any unintended changes

Accepting or Rejecting Changes

After reviewing:

• Accept: If the changes look good, confirm to apply them
• Reject: If something's wrong, decline and ask Claude to try again with different instructions

Tip: If you accept changes and then realize there's a problem, you can use git to undo them (more on this in the workflows section).

---

CLAUDE.md Files

What They Are

A CLAUDE.md file is a special file you create to give Claude Code context about your project. Think of it as an instruction manual for Claude.

When Claude Code starts in a folder, it automatically reads any CLAUDE.md file and uses that information to understand your project better.

Where to Put Them

Place CLAUDE.md in the root of your project (the main folder, where package.json usually lives):

my-project/
├── CLAUDE.md         <- Put it here
├── package.json
├── src/
│   └── ...
└── ...

Example CLAUDE.md

Here's a template you can adapt:

# CLAUDE.md

## Project Overview

This is a personal portfolio website built with Next.js. It shows my work
and has a contact form.

## Commands

    npm run dev      # Start development server at localhost:3000
    npm run build    # Build for production
    npm test         # Run tests

## Architecture

**Key files:**
- `pages/index.js` - Homepage
- `pages/contact.js` - Contact form page
- `components/Header.js` - Navigation header (used on all pages)
- `styles/globals.css` - Main stylesheet

**Important notes:**
- The contact form sends emails via an API route in `pages/api/contact.js`
- Images are stored in `public/images/`
- This site is deployed to Netlify

## Things to Know

- Don't modify files in `node_modules/` or `.next/`
- The `.env.local` file has API keys (don't commit this)

Why This Helps

Without a CLAUDE.md, Claude has to figure out your project by reading all the files. With one, Claude:

• Gets up to speed instantly
• Knows your preferred commands
• Understands your project structure
• Avoids touching files it shouldn't

Time investment: 10 minutes to write a CLAUDE.md saves hours of explaining your project repeatedly.

Memory Hierarchy

Claude Code reads configuration from multiple sources, creating a hierarchy of instructions:

1. Project memory (CLAUDE.md in project root) — Project-specific rules and context
2. User memory (~/.claude/CLAUDE.md) — Your personal preferences across all projects
3. Modular rules (.claude/rules/*.md) — Organized rules for specific topics

Modular rules let you split complex projects into manageable pieces:

my-project/
├── CLAUDE.md                    # Main project context
├── .claude/
│   └── rules/
│       ├── code-style.md        # Coding conventions
│       ├── testing.md           # How to write tests
│       └── api-patterns.md      # API design rules
└── src/

Path-Specific Rules

You can apply rules only to certain files using paths: frontmatter:

---
paths:
  - src/components/**
  - src/ui/**
---

# Component Guidelines

- Use functional components with hooks
- Include PropTypes or TypeScript interfaces
- Export components as default

This rule only applies when Claude works on files in src/components/ or src/ui/.

Using /memory Command

Edit your memory files quickly with:

/memory

This opens your user memory file for editing. Use it to store:

• Preferred coding styles
• Common project patterns
• Frequently used commands

What to Include (and What to Avoid)

Good for CLAUDE.md:

• Project overview and purpose
• How to run/build/test the project
• Key file locations and architecture
• Naming conventions and coding standards
• Things that would surprise someone new

Avoid putting in CLAUDE.md:

• Obvious things Claude can figure out from code
• Long documentation (link to docs instead)
• Frequently changing information
• Secrets or sensitive data

---

Effective Workflows

Start with Exploration

When working with any project, start by understanding it:

What does this project do?

Show me the main entry points

What technologies does this project use?

This helps both you AND Claude understand what you're working with.

Be Specific About Changes

Good prompts are specific:

Vague (harder for Claude)	Specific (better results)
Fix the bug	The form doesn't validate email addresses. Add validation.
Make it look better	Increase the font size of headings to 24px
Add a feature	Add a dark mode toggle button in the header

Review Diffs Before Accepting

Every time Claude proposes changes:

1. Read the diff carefully
2. Check that only intended files are modified
3. Look for anything unexpected
4. Ask questions if something's unclear

Use Git for Safety

Here's a powerful workflow combining Claude Code with git:

Before making changes:

git status                    # See current state
git add -A && git commit -m "Before Claude changes"   # Save current state

After Claude makes changes:

git diff                      # Review all changes
git add -A && git commit -m "Added feature X via Claude Code"  # Save if good

If something went wrong:

git checkout .                # Undo all uncommitted changes
# or
git reset --hard HEAD~1       # Undo the last commit entirely

This gives you a safety net. You can always go back.

---

Slash Commands

Getting Help

Type /help at any time to see available commands:

/help

Common Commands

Command	What it does
/help	Show all available commands
/clear	Clear the conversation history
/compact	Summarize conversation to save context
/config	Open Claude Code settings
/init	Create a CLAUDE.md file for current project
/memory	Edit your memory files
/doctor	Run health checks on your installation
/mcp	Manage MCP server connections
/plan	Enter plan mode for complex tasks
/cost	Show token usage and costs
/context	Visualize current context usage
/model	Change which Claude model to use

Tips for Commands

• Commands start with /
• Type just the command (like /help) and press Enter
• Commands are not the same as prompts — they control Claude Code itself
• Use /init when starting with a new project to quickly create a CLAUDE.md template

---

Plan Mode

What is Plan Mode?

Plan mode is a special workflow where Claude Code explores and plans before making any changes. Think of it as "read-only reconnaissance" — Claude investigates your codebase, understands the problem, and creates a plan for you to approve.

When to Use Plan Mode

Plan mode is valuable for:

• Complex multi-file changes — Refactoring that touches many files
• Unfamiliar codebases — When you (or Claude) need to understand before acting
• Architectural decisions — Designing features that require careful planning
• High-risk changes — Situations where you want extra review

How to Enter Plan Mode

Option 1: Toggle during a session

Press Shift+Tab to switch between plan mode and normal mode. This is the most common way.

Option 2: Use the slash command

/plan

Option 3: Start Claude Code in plan mode

claude --plan

The Plan Mode Workflow

A typical plan mode session looks like this:

1. Explore — Ask Claude to understand the codebase

   How does the authentication system work in this project?

2. Plan — Request a plan for your changes

   I want to add password reset functionality. Create a plan.

3. Review — Claude presents a step-by-step plan with files it will modify

4. Approve — Exit plan mode and let Claude implement the approved plan

5. Implement — Claude makes the changes you approved

Plan Mode vs Normal Mode

Aspect	Plan Mode	Normal Mode
File changes	Not allowed	Allowed (with approval)
File reading	✅ Yes	✅ Yes
Command execution	Limited	Full access
Best for	Exploration, planning	Implementation

---

MCP Servers

What are MCP Servers?

MCP (Model Context Protocol) servers extend Claude Code with additional tools. They let Claude interact with external services like databases, GitHub, issue trackers, and more.

Think of MCP servers as plugins that give Claude new capabilities.

Common Use Cases

• Database queries — Let Claude read from your development database
• GitHub integration — Create PRs, review code, manage issues
• Issue trackers — Connect to Jira, Linear, or other project management tools
• Custom APIs — Give Claude access to internal tools

Installing an MCP Server

Add a server using the CLI:

claude mcp add <server-name>

For example, to add a GitHub server:

claude mcp add github

Follow the prompts to configure authentication if required.

Managing MCP Servers

List installed servers:

claude mcp list

View server status in Claude Code:

/mcp

Remove a server:

claude mcp remove <server-name>

Security Considerations

• Only install MCP servers from trusted sources
• Review what permissions a server requests
• Be careful with servers that access production data
• Use read-only connections when possible

For advanced MCP configuration and creating custom servers, see the MCP Integration specialization.

---

Custom Commands (Skills)

Creating Your Own Slash Commands

You can create custom commands (called "skills") that automate common workflows. These live in your project's .claude/commands/ folder.

Basic Structure

Create a markdown file in .claude/commands/:

my-project/
├── .claude/
│   └── commands/
│       └── fix-issue.md      # Creates /fix-issue command
└── ...

Simple Example

Create .claude/commands/fix-issue.md:

---
description: Fix a GitHub issue
---

Look up GitHub issue #$ARGUMENTS and:
1. Understand what the issue is asking for
2. Find the relevant files
3. Implement a fix
4. Create a commit with a message referencing the issue

Now you can run:

/fix-issue 123

Claude will look up issue #123 and attempt to fix it.

Using Arguments

The special variable $ARGUMENTS captures everything after your command name:

You type	$ARGUMENTS becomes
/fix-issue 123	123
/summarize src/utils	src/utils
/deploy staging	staging

More Examples

Code review command (.claude/commands/review.md):

---
description: Review code changes
---

Review the current git diff and provide feedback on:
- Code quality and best practices
- Potential bugs or edge cases
- Naming and clarity
- Test coverage suggestions

Documentation generator (.claude/commands/doc.md):

---
description: Generate documentation for a file
---

Generate documentation for $ARGUMENTS:
- Add JSDoc comments to all exported functions
- Create a summary at the top of the file
- Include usage examples where helpful

Sharing Commands

Commands in .claude/commands/ are part of your project. Commit them to share with your team, or add .claude/ to your .gitignore if you want to keep them private.

---

Headless Mode

Running Claude Code in Scripts

You can run Claude Code non-interactively using the -p flag. This is useful for automation, CI/CD pipelines, or quick one-off tasks.

claude -p "Explain what this project does"

Claude will process the prompt and output the response directly to your terminal.

Practical Examples

Generate a summary:

claude -p "Summarize the changes in the last 5 commits" > changelog.txt

Quick code review:

claude -p "Review the staged changes for potential issues"

Combine with other tools:

git diff | claude -p "Explain these changes"

When to Use Headless Mode

• Automating repetitive analysis tasks
• Integrating Claude into shell scripts
• Quick questions without entering interactive mode
• CI/CD pipelines for code review or documentation

---

Using Claude Code with VS Code

The Integrated Terminal

The easiest way to use Claude Code with VS Code is through the integrated terminal.

Opening the terminal:

1. In VS Code, press Ctrl+` (backtick) or go to View → Terminal
2. The terminal opens at the bottom of your editor
3. It automatically starts in your project folder

Running Claude Code:

claude

Now you can:

• Ask Claude about code that's open in your editor
• Make changes that appear immediately in your tabs
• Switch between the terminal and editor easily

Side-by-Side Workflow

A productive setup is having Claude Code on one side and your files on the other:

1. Open the terminal panel (Ctrl+`)
2. Drag the terminal to the right side of the screen (or use View → Editor Layout → Two Columns)
3. Run Claude Code in the terminal
4. Open relevant files in the left panel

This way, you can see Claude's responses while looking at the code it's referencing.

Viewing Changes in Real-Time

When Claude modifies files:

1. VS Code detects the changes automatically
2. Modified files show a dot next to their name in tabs
3. You can use VS Code's built-in diff view (click the "M" badge in the Source Control panel)

Quick tip

If Claude makes changes and you want to see exactly what changed, use VS Code's Source Control panel (the branch icon in the sidebar). It shows all modified files and lets you view diffs visually.

VS Code Extensions That Help

These extensions work well alongside Claude Code:

• GitLens — Enhanced git history and blame annotations
• Error Lens — Shows errors inline, helping you spot issues Claude might have introduced

Also enable VS Code's built-in Auto Save (File → Auto Save) so your files save automatically when Claude makes changes.

---

Best Practices

Keep CLAUDE.md Updated

When your project changes significantly, update the CLAUDE.md file. Outdated instructions confuse Claude.

Review Changes Before Accepting

This is so important it bears repeating. Never blindly accept changes. Always:

1. Read the diff
2. Understand what's changing
3. Verify it matches your request

Use for Appropriate Tasks

Good uses for Claude Code:

• Code changes and refactoring
• Understanding codebases
• Adding features to existing projects
• Fixing bugs
• Writing tests

Keep away from Claude Code:

• Files with passwords or API keys
• Sensitive personal data
• Production systems (test locally first)

Combine with Git

Always use git alongside Claude Code:

• Commit before major changes (so you can undo)
• Commit after successful changes (so you can track)
• Use branches for experimental features

Start Small

When first using Claude Code on a project:

1. Start with small, contained changes
2. Build confidence in how it works
3. Gradually tackle larger tasks

---

Mini Project: Make a Change with Claude Code

Let's practice! You'll use Claude Code to make a small change to an existing project.

What You'll Do

1. Navigate to an existing project
2. Start Claude Code
3. Ask it to explain the project
4. Make a small change
5. Review and accept the change
6. Verify the change works

Step-by-Step

Step 1: Choose a project

Use your flagship project or any other project you've worked on.

cd ~/Projects/your-project

Step 2: Start Claude Code

claude

Step 3: Explore first

Ask Claude to explain the project:

What does this project do? Give me a quick overview.

Step 4: Make a small change

Choose something simple. Examples:

• Change a button label
• Update the page title
• Modify a color
• Add a comment to explain some code

Example prompt:

Change the main heading on the homepage from "Welcome" to "Hello there"

Step 5: Review the diff

Look at what Claude proposes:

• Is it the right file?
• Is the change what you expected?
• Are there any unintended modifications?

Step 6: Accept or adjust

If it looks good, accept the change. If not, ask Claude to try again with more specific instructions.

Step 7: Verify

Run your project and check that the change works:

npm run dev

Open your browser and verify the change appears correctly.

What You Learned

• How to start Claude Code in a project
• How to ask for explanations
• How to request specific changes
• How to review proposed changes
• The importance of verification

---

Key Takeaways

• Claude Code is a terminal-based AI assistant that works directly with your files
• Always start from a project folder so Claude has context
• CLAUDE.md files give Claude important information about your project
• Use plan mode for complex changes — explore and plan before implementing
• MCP servers extend Claude with external tools (databases, GitHub, issue trackers)
• Custom commands automate repetitive workflows with simple markdown files
• Headless mode (claude -p) enables scripting and automation
• Review every change before accepting — look at the diff carefully
• Combine with git for a safety net — you can always undo changes
• Be specific in your requests for better results

---

What's Next?

You now have Claude Code set up and know how to use it effectively. Here's how to continue building your skills:

Practice suggestions:

• Try plan mode on your next complex feature
• Create a custom command for a workflow you repeat often
• Set up an MCP server for a service you use daily
• Build a comprehensive CLAUDE.md for your main project

Explore related specializations:

• MCP Integration — Deep dive into Model Context Protocol

Go deeper:

• The official Claude Code documentation covers advanced features
• Experiment with different Claude models using /model for different tasks
• Join the Claude community to share custom commands and workflows