Skip to content

first-session.md

Latest commit

 

History

History
388 lines (305 loc) · 10.7 KB

first-session.md

File metadata and controls

388 lines (305 loc) · 10.7 KB

Your First Claude Code Session

A step-by-step walkthrough to get productive immediately

🎯 Session Goals

By the end of this guide, you'll:

  • Successfully start and configure your first Claude Code session
  • Understand basic commands and workflows
  • Create a simple feature using TDD
  • Experience the core Claude Code development cycle

🚀 Pre-Session Checklist

Before starting, ensure:

  • Claude Code is installed and authenticated
  • You have a project with .claude/ directory
  • CLAUDE.md file exists (even if basic)
  • Your IDE is open and ready

📖 Step-by-Step First Session

Step 1: Start Claude Code Session

# Navigate to your project
cd your-project

# Start Claude Code
claude

# You should see:
# Claude Code v1.x.x
# Project: your-project
# Model: claude-sonnet-4 (default)
# Context loaded from CLAUDE.md

Step 2: Initialize Project Context

If this is your first time in the project:

# Initialize project structure
> /init

# This will:
# - Analyze your project structure
# - Create or update CLAUDE.md
# - Set up basic configuration
# - Load project context into Claude's memory

Expected Output:

✅ Project initialized
📁 Detected: React TypeScript project
📝 CLAUDE.md updated with project context
🔧 Configuration loaded from .claude/settings.json
🧠 Context ready - I understand your project structure and standards

Step 3: Explore Available Commands

# See all available commands
> /help

# Key commands you'll use:
> /init       - Initialize or refresh project context
> /compact     - Compress conversation history  
> /clear       - Clear conversation and start fresh
> /agents      - Create specialized sub-agents
> #            - Quick addition to CLAUDE.md (shortcut key)

Step 4: Quick Project Understanding

Ask Claude to analyze your project:

> "Analyze this project structure and tell me:
1. What type of application is this?
2. What are the main technologies used?
3. What's the current architecture pattern?
4. Are there any obvious areas for improvement?"

Claude will respond with:

  • Project type identification
  • Technology stack analysis
  • Architecture pattern recognition
  • Improvement suggestions

Step 5: Your First Feature Implementation

Let's implement a simple feature using TDD to experience the full workflow.

Choose a Simple Feature

> "I want to add a utility function to format currency values. 
It should:
- Accept a number and currency code
- Return formatted string (e.g., '$1,234.56')
- Handle edge cases like null/undefined
- Support multiple currencies (USD, EUR, GBP)

Let's implement this using TDD."

TDD Implementation Cycle

RED Phase - Write Failing Tests:

> "First, write comprehensive Jest tests for the currency formatter:
- Test valid numbers with different currencies
- Test edge cases (null, undefined, negative numbers)
- Test different locales and formatting
- Test invalid currency codes
Place tests in src/utils/__tests__/formatCurrency.test.ts"

Claude will create failing tests covering all scenarios.

GREEN Phase - Minimal Implementation:

> "Now implement the minimal code to make all tests pass.
Create src/utils/formatCurrency.ts following our project standards."

Claude will implement just enough code to pass tests.

BLUE Phase - Refactor and Improve:

> "All tests are passing. Now refactor for:
- Better performance with internationalization
- Improved error handling
- Cleaner code structure
- Add JSDoc documentation
Keep all tests passing."

Claude will improve the implementation while maintaining test coverage.

Step 6: Integration and Validation

Add the Feature to a Component

> "Create a simple React component that uses this currency formatter.
- Component name: PriceDisplay
- Props: amount (number), currency (string)
- Show formatted price with proper styling
- Handle loading and error states
- Include unit tests for the component"

Run Quality Checks

# If you have hooks configured, they'll run automatically
# Otherwise, manually run:
> "Run these quality checks and fix any issues:
1. TypeScript compilation
2. ESLint and Prettier  
3. Unit tests
4. Import/export validation"

Step 7: Context Management Practice

Add to CLAUDE.md

# Use the # shortcut to quickly add context
> # New utility: formatCurrency in src/utils/formatCurrency.ts
> # Pattern: All utility functions should have comprehensive tests
> # Rule: Currency formatting must support USD, EUR, GBP

Compact Session

# After significant work, compress conversation
> /compact

# This:
# - Summarizes the session
# - Preserves important context
# - Reduces token usage
# - Maintains conversation continuity

Step 8: Debugging Practice

Let's simulate a common issue:

> "Introduce a subtle bug in the formatCurrency function - 
maybe an edge case with zero values. Then help me debug it systematically:
1. Identify the failing test
2. Analyze the root cause  
3. Fix the issue
4. Verify all tests still pass
5. Add additional test coverage for this edge case"

This gives you practice with Claude's debugging workflow.

🎨 Understanding Claude's Responses

What Good Responses Look Like

✅ Comprehensive Implementation:

// Claude provides complete, working code
export const formatCurrency = (
  amount: number | null | undefined,
  currency: string = 'USD',
  locale: string = 'en-US'
): string => {
  // Full implementation with error handling
  // Proper TypeScript types
  // JSDoc documentation
  // Edge case handling
};

✅ Detailed Explanations:

I've implemented the currency formatter with the following features:
1. **Input Validation**: Handles null/undefined gracefully
2. **Internationalization**: Uses Intl.NumberFormat for proper formatting
3. **Error Handling**: Returns fallback for invalid currencies
4. **Performance**: Memoizes formatters to avoid recreation

The implementation follows your project's TypeScript standards and includes comprehensive test coverage.

What to Watch For

⚠️ Incomplete Responses:

  • Missing error handling
  • No TypeScript types
  • Incomplete test coverage
  • Not following project patterns

🔧 How to Improve:

> "This implementation is missing:
1. Error handling for invalid inputs
2. TypeScript strict types
3. JSDoc documentation
4. Tests for edge cases
Please complete these aspects following our project standards."

🛠️ Common First Session Issues

Issue: Claude Doesn't Understand Project Context

Symptoms:

  • Suggests wrong technologies
  • Uses inconsistent patterns
  • Missing project-specific requirements

Solution:

# Update CLAUDE.md with more context
> # Tech Stack: React 18, TypeScript 5.x, Tailwind CSS
> # Patterns: Use functional components with hooks
> # Testing: Jest + React Testing Library
> # Style: Prettier with 2-space indentation

# Then refresh context
> /init

Issue: Code Doesn't Match Project Standards

Symptoms:

  • Wrong file structure
  • Inconsistent naming
  • Missing required patterns

Solution:

> "This code doesn't match our project standards. Please revise to:
- Follow naming conventions in CLAUDE.md
- Use project file structure
- Include proper TypeScript types
- Follow error handling patterns from existing code

Reference: [point to specific existing files]"

Issue: Tests Are Too Simple

Symptoms:

  • Only happy path testing
  • Missing edge cases
  • No error scenario coverage

Solution:

> "These tests need to be more comprehensive. Add:
- Edge cases (null, undefined, empty values)
- Error scenarios (invalid inputs, network failures)
- Boundary conditions (min/max values)
- Integration scenarios (component interaction)

Follow the test patterns from [existing test file]"

🎯 Success Indicators

You're Getting Value When:

  • Claude follows your project patterns consistently
  • Code quality matches your existing codebase
  • Tests are comprehensive and meaningful
  • Implementations handle edge cases properly
  • Context is maintained throughout the session

You Need to Improve When:

  • Claude keeps asking for clarification
  • Generated code needs significant modification
  • Patterns are inconsistent across responses
  • Tests miss obvious edge cases
  • Context is lost between interactions

🔄 Session Management Tips

When to Use /compact

  • After completing a major feature
  • Before starting a new complex task
  • When conversation gets very long (>50 exchanges)
  • If Claude starts losing context

When to Use /clear

  • Starting completely different work
  • Context becomes confusing or contradictory
  • Need to switch focus areas entirely
  • Previous context is no longer relevant

When to Add to CLAUDE.md (#)

  • New patterns emerge during development
  • Important constraints are discovered
  • Team decisions are made
  • Architecture changes occur

📚 Next Steps After First Session

Immediate Actions

  1. Review CLAUDE.md - Update with learnings from session
  2. Save Session Notes - Document what worked well/poorly
  3. Commit Changes - Use git to save progress
  4. Plan Next Session - Identify next priority features

Skill Development

  1. Context Management - Master long-term context
  2. Prompt Engineering - Get better results
  3. TDD Workflows - Systematic development
  4. Advanced Techniques - Hooks, automation, scaling

Team Integration

  1. Share CLAUDE.md - Commit to version control
  2. Document Patterns - Update team guidelines
  3. Train Colleagues - Share successful techniques
  4. Iterate Process - Improve based on results

🎉 Congratulations!

You've completed your first productive Claude Code session. You should now have:

  • ✅ A working feature implemented with TDD
  • ✅ Comprehensive tests covering edge cases
  • ✅ Code that follows your project standards
  • ✅ Updated project context in CLAUDE.md
  • ✅ Understanding of basic Claude Code workflows

Key Takeaways:

  1. Context is crucial - Invest time in good CLAUDE.md
  2. Be specific - Detailed prompts get better results
  3. Follow patterns - Reference existing code for consistency
  4. Test everything - TDD ensures quality and edge case coverage
  5. Iterate quickly - Use Claude for rapid development cycles

Ready to level up? Continue with Context Management to master long-term project success.

Pro Tip: Your first session sets the foundation for all future work. Invest time in getting the context and patterns right - it pays dividends in every subsequent session.