Module 3: Claude Code and Agentic Workflows

Overview

Welcome to the future of software development. Claude Code isn't just another AI coding assistant—it's a paradigm shift that implements context engineering principles directly in your terminal. This module will transform how you think about coding, moving from writing every line to orchestrating intelligent agents.

What You'll Learn

Installing and configuring Claude Code for maximum productivity
The CLAUDE.md system for persistent context
Multi-agent development with git worktrees
The "vibe coding" workflow that's revolutionizing development
Plan-first development that actually works

Prerequisites

Completed Modules 1 & 2
Basic familiarity with terminal/command line
A project to practice on (or we'll create one)
60 minutes of hands-on time

Understanding Claude Code

What Makes Claude Code Different

Traditional AI Assistants:

Live in a separate window
Copy-paste driven workflow
Lose context between sessions
Suggest what you should type

Claude Code:

Lives in your terminal
Direct file system access
Persistent project memory
Actually writes the code

The Mental Model Shift

Think of Claude Code as a brilliant junior developer who:

Has read your entire codebase
Never forgets project decisions
Can work on multiple features in parallel
Asks clarifying questions when needed
Gets better the more you work together

Installation and Setup

Step 1: Install Claude Code

# First, request access (if needed)
# Visit: anthropic.com/claude-code

# Once approved, install via npm
npm install -g @anthropic-ai/claude-code

# Or use the installer
curl -fsSL https://anthropic.com/install-claude-code | bash

# Verify installation
claude --version

Step 2: Authentication

# Login with your Anthropic account
claude login

# This opens your browser for auth
# After auth, you'll see:
✓ Successfully authenticated as your@email.com

Step 3: Initialize Your Project

# Navigate to your project
cd /path/to/your/project

# Initialize Claude Code
claude init

# This creates:
# - .claude/ directory for commands
# - CLAUDE.md for project context
# - .claudeconfig for settings

The CLAUDE.md File: Your Project's Memory

Understanding CLAUDE.md

This file is context engineering in action. It's automatically loaded into every Claude conversation, providing persistent memory across sessions.

Anatomy of an Effective CLAUDE.md

# Project Context for Claude

## Project Overview
This is a task management API built with Node.js and PostgreSQL.
We prioritize clean code, comprehensive tests, and developer experience.

## Architecture Decisions
- **Framework**: Express.js with TypeScript
- **Database**: PostgreSQL with Prisma ORM
- **Authentication**: JWT with refresh tokens
- **Testing**: Jest for unit tests, Supertest for integration

## Coding Standards
- Use functional programming where possible
- Prefer composition over inheritance
- All endpoints must have OpenAPI documentation
- Minimum 80% test coverage for new code
- Use conventional commits for git messages

## Current State
- Core CRUD operations: ✅ Complete
- Authentication system: ✅ Complete
- Email notifications: 🚧 In Progress
- Real-time updates: 📄 Planned

## Key Files and Their Purpose
- `src/server.ts` - Main application entry
- `src/routes/` - API endpoint definitions
- `src/services/` - Business logic layer
- `src/models/` - Database models
- `src/utils/` - Shared utilities

## Development Workflow
1. Create feature branch from `develop`
2. Write tests first (TDD)
3. Implement feature
4. Ensure all tests pass
5. Submit PR with conventional commit

## Known Issues / Tech Debt
- TODO: Refactor user service for better separation
- FIXME: Rate limiting needs Redis implementation
- HACK: Temporary email queue in memory

## External Documentation
- API Docs: http://localhost:3000/api-docs
- Architecture Diagrams: /docs/architecture/
- Deployment Guide: /docs/deployment.md

CLAUDE.md Best Practices

Keep it Updated: Treat it like critical documentation
Be Specific: Vague context leads to vague code
Include Anti-patterns: Tell Claude what NOT to do
Link to Resources: Reference other docs and examples
Version Control: Track changes to context over time

Multi-Agent Development Workflows

The Power of Parallel Development

Claude Code shines when you work on multiple features simultaneously:

# Traditional workflow (serial)
Feature A → Feature B → Bug Fix → Feature C

# Claude Code workflow (parallel)
Feature A ↔ Feature B
    ↓           ↓
Bug Fix    Feature C

Setting Up Git Worktrees

Git worktrees allow multiple working directories from the same repo:

# From your main project directory
git worktree add ../project-feature-auth feature/authentication
git worktree add ../project-feature-api feature/api-redesign
git worktree add ../project-bugfix bug/memory-leak

# Now you have:
/project (main branch)
/project-feature-auth (feature branch)
/project-feature-api (feature branch)
/project-bugfix (bug fix branch)

Orchestrating Multiple Agents

Each worktree can have its own Claude Code instance:

# Terminal 1: Authentication Feature
cd ../project-feature-auth
claude
> Implement JWT authentication with refresh tokens

# Terminal 2: API Redesign
cd ../project-feature-api
claude
> Redesign the REST API to follow OpenAPI 3.0 spec

# Terminal 3: Bug Fix
cd ../project-bugfix
claude
> Find and fix the memory leak in the WebSocket handler

Agent Coordination

When agents need to share context:

# In CLAUDE.md or a shared file
## Active Development Threads

### Authentication (Terminal 1)
- Implementing JWT with refresh tokens
- Modified: auth.service.ts, user.model.ts
- Status: Testing refresh token rotation

### API Redesign (Terminal 2)
- Converting to OpenAPI 3.0
- Modified: All route files
- Status: 60% complete, working on user routes

### Memory Leak Fix (Terminal 3)
- Identified: WebSocket connections not closing
- Modified: websocket.handler.ts
- Status: Fix implemented, running tests

The "Vibe Coding" Revolution

What is Vibe Coding?

Vibe coding is the art of describing what you want and letting Claude Code handle the implementation details. It's not about being lazy—it's about operating at a higher level of abstraction.

The Two-Step Flow

Step 1: Planning Phase

claude> Create a detailed plan for implementing a real-time 
notification system. Consider WebSockets vs SSE, scalability 
concerns, and how to handle offline users. Save the plan 
to docs/notification-system-plan.md

Claude creates a comprehensive plan with:

Architecture decisions
Implementation steps
Potential challenges
Testing strategy

Step 2: Implementation Phase

# Clear context for fresh start
/clear

claude> Implement the notification system following the plan 
in docs/notification-system-plan.md. Start with the WebSocket 
server setup.

Vibe Coding Best Practices

Think in Features, Not Functions

❌ "Write a function to validate email" ✅ "Add email validation to our user registration flow"
Provide Business Context

❌ "Add caching" ✅ "Add caching to reduce database load during peak hours (500+ requests/second)"

Iterate Naturally

claude> That looks good, but can you add retry logic 
for failed notifications?

Test-Driven Development with Claude

The TDD Workflow

Claude Code excels at TDD because it can see test failures and iterate:

# Step 1: Write the tests
claude> Write comprehensive tests for a password reset feature. 
Include edge cases like expired tokens, already-used tokens, 
and invalid email addresses. Use our existing test patterns.

# Step 2: Run tests (they should fail)
claude> Run the tests and confirm they fail

# Step 3: Implement the feature
claude> Now implement the password reset feature to make 
all tests pass. Follow our authentication patterns.

# Step 4: Iterate until green
claude> The test for expired tokens is still failing. 
Fix the implementation.

Benefits of AI-Driven TDD

Comprehensive test coverage: AI thinks of edge cases you might miss
Faster iteration: No context switching between test and implementation
Better tests: AI writes tests that actually catch bugs
Learning opportunity: See testing patterns you hadn't considered

Practical Workflows

Workflow 1: Feature Development

# 1. Start with research
claude> Research best practices for implementing OAuth2 
with our stack. What are the security considerations?

# 2. Create a plan
claude> Based on the research, create an implementation 
plan for adding Google OAuth to our authentication system

# 3. Set up the structure
claude> Create the necessary files and folder structure 
for the OAuth implementation

# 4. Implement incrementally
claude> Implement the OAuth configuration and provider setup

# 5. Add tests
claude> Write integration tests for the OAuth flow

# 6. Document
claude> Update our API documentation with the new OAuth endpoints

Workflow 2: Debugging Complex Issues

# 1. Gather context
claude> We're experiencing intermittent 500 errors in production. 
Analyze our error logs (in logs/error.log) and identify patterns

# 2. Form hypothesis
claude> Based on the log analysis, what are the most likely causes?

# 3. Investigate
claude> Check our database connection pooling configuration 
and recent changes to the user service

# 4. Test hypothesis
claude> Write a script to reproduce the connection pool exhaustion

# 5. Implement fix
claude> Implement a fix for the connection pool issue with 
proper error handling

# 6. Verify
claude> Add monitoring to ensure this issue doesn't recur

Workflow 3: Code Refactoring

# 1. Analyze current state
claude> Analyze our user service for code smells and 
technical debt. Focus on SOLID principles.

# 2. Plan refactoring
claude> Create a step-by-step refactoring plan that 
maintains backward compatibility

# 3. Set up safety nets
claude> Write characterization tests for the current behavior 
before we refactor

# 4. Refactor incrementally
claude> Start refactoring the user service, beginning 
with extracting the email functionality

# 5. Verify behavior
claude> Run all tests to ensure behavior hasn't changed

Advanced Techniques

Custom Commands

Create reusable commands in .claude/commands/:

<!-- .claude/commands/create-endpoint.md -->
Create a new REST endpoint with the following:
- Route definition in the appropriate router
- Controller with proper error handling
- Service layer for business logic
- Input validation using our schemas
- Unit and integration tests
- OpenAPI documentation
- Update the API changelog

The endpoint should follow our existing patterns.

Use it:

claude> /create-endpoint POST /api/tasks/:taskId/assign

Context Switching

Working on multiple related features:

# Save current context
claude> Summarize what we've implemented so far for 
the notification system and save to .claude/contexts/notifications.md

# Switch to another feature
/clear
claude> Load the context from .claude/contexts/search.md 
and continue implementing the full-text search feature

Collaborative Claude Sessions

When pair programming with Claude:

# Developer 1 starts
claude> Let's pair on the caching implementation. 
I'll handle the Redis setup if you write the cache 
invalidation logic.

# Claude implements Redis setup

# Developer implements invalidation

# Back to Claude
claude> Review my invalidation logic and suggest 
improvements for edge cases I might have missed

Common Patterns and Anti-patterns

Patterns (Do's) ✅

Plan Before Building
- Always start with a plan
- Save plans for future reference
- Iterate on plans before coding
Incremental Development
- Small, focused requests
- Build incrementally
- Test each increment
Context Preservation
- Update CLAUDE.md regularly
- Document decisions
- Save important contexts

Anti-patterns (Don'ts) ❌

Kitchen Sink Requests

❌ "Build a complete user management system with authentication, authorization, profile management, and admin panel"
Ignoring Test Failures

❌ "The tests are failing but the code looks right, just skip them"
Context Pollution

❌ Working on authentication, API redesign, and bug fixes in the same Claude session

Hands-on Exercise

Build a Feature with Claude Code

Let's build a complete feature using proper context engineering:

Setup (5 minutes)

# Create a new project or use existing
mkdir task-api && cd task-api
claude init

Configure Context (10 minutes)
- Edit CLAUDE.md with project details
- Add coding standards
- Define architecture

Plan the Feature (10 minutes)

claude> We need a task commenting system. Create a 
detailed plan including data model, API endpoints, 
real-time updates, and mention notifications.

Implement with TDD (20 minutes)

# Write tests first
claude> Write tests for the commenting system 
based on our plan

# Implement to pass tests
claude> Implement the commenting system to make 
all tests pass

Add Polish (10 minutes)

claude> Add error handling, logging, and API 
documentation for the commenting endpoints

Review and Refine (5 minutes)

claude> Review the implementation for security 
issues and performance bottlenecks

Checkpoint Task

Your Mission

Use Claude Code to build a complete feature using the plan-first approach:

Choose a feature for your project:
- User notifications
- Search functionality
- File upload system
- Analytics dashboard
- Or your own idea
Execute the workflow:
- Create detailed plan (save to file)
- Set up tests first
- Implement incrementally
- Use at least 2 parallel agents
- Document everything
Demonstrate mastery:
- Clean git history
- All tests passing
- Proper documentation
- No manual code writing (pure vibe coding)
Measure success:
- Time to complete vs traditional coding
- Code quality metrics
- Test coverage
- Feature completeness

Deliverable

A GitHub repo showing:

Your CLAUDE.md file
The planning document
Clean commit history
Working feature with tests
Brief reflection on the experience

Tips for Success

Getting Started

Start with small features to build confidence
Use Claude for code reviews of your manual code
Gradually increase complexity

When Stuck

Ask Claude to explain its approach
Break requests into smaller pieces
Review the plan before implementation

Maximizing Productivity

Keep multiple terminals open
Use tmux or screen for session management
Create command shortcuts for common tasks

Next Steps

You've mastered Claude Code and agentic workflows. Module 4 will show you how to build persistent memory systems that make your AI agents truly intelligent.

Preview of Module 4

Vector databases for semantic memory
Conversation history management
The LCMP protocol in action
Building agents that get smarter over time

Ready to give your agents perfect memory? Module 4 awaits!

Claude Code Agentic Workflows

Prerequisites

Next Steps

Your Progress