Claude Code Workshop - Technical Reference

Duration: 90 minutes | Format: Instructor-led, live coding
Repo: opentelemetry-demo

Pre-Workshop Setup
Phase 1: Documentation & Analysis
Phase 2: Test Generation
Phase 3: Debugging & QA
Phase 4: Development & MCP
Phase 5: Skills, Packaging & Marketplace
Phase 6: Reusability Demo

Pre-Workshop Setup

Participant Requirements

# Check Claude Code is installed
claude --version

# Clone the repository
git clone https://github.com/rishikeshradhakrishnan/opentelemetry-demo
cd opentelemetry-demo

# Verify Node.js (needed for MCP in Phase 4)
node --version

# Start Claude Code
claude

Instructor Pre-Check

# Verify all services are present
ls src/

# Expected output:
# accountingservice  cartservice       currencyservice  frontend      paymentservice         recommendationservice
# adservice          checkoutservice   emailservice     loadgenerator productcatalogservice  shippingservice

Phase 1: Documentation & Analysis

1A: Basic Documentation Demo

Prompt:

Analyze the architecture of this application.
Create a README.md that includes:
- High-level architecture diagram (mermaid)
- List of all services with their primary language
- How services communicate with each other
- Quick start instructions for local development

Expected Output:

Mermaid diagram showing service relationships
Table of services with languages (Go, Python, TypeScript, etc.)
Communication patterns (gRPC, HTTP)
Docker compose instructions

1B: Plugin Directory Setup

Commands:

# Create the plugin directory structure
mkdir -p .claude/plugins/codebase-toolkit/agents
mkdir -p .claude/plugins/codebase-toolkit/skills

# Also create local agents directory for immediate use
mkdir -p .claude/agents

Resulting Structure:

.claude/
├── agents/                              # Local active agents
└── plugins/
    └── codebase-toolkit/               # Our plugin project
        ├── agents/                      # Plugin agents
        └── skills/                      # Plugin skills

1C: Service-Documenter Subagent

File: .claude/plugins/codebase-toolkit/agents/service-documenter.md

---
name: service-documenter
description: Documents a single microservice. Use when analyzing individual services for documentation purposes.
tools: Read, Grep, Glob
model: sonnet
---

You are a technical documentation specialist. When given a service directory:

1. Identify the primary language and framework
2. Find the main entry point
3. List key functions/endpoints
4. Identify dependencies on other services
5. Note any configuration files

Output a concise markdown summary with:
- **Service name** and language
- **Purpose** (1-2 sentences)
- **Key endpoints/functions** (bullet list)
- **Dependencies** (other services it calls)
- **Configuration** options

Installation Command:

cp .claude/plugins/codebase-toolkit/agents/service-documenter.md .claude/agents/

1D: Parallel Subagents Demo

Check Context Usage

/context

Prompt:

Document this codebase using 4 parallel subagents.
Assign each subagent to a different group:

Subagent 1: Go services (checkoutservice, productcatalogservice)
Subagent 2: Python services (recommendationservice, loadgenerator)  
Subagent 3: Frontend services (frontend in TypeScript, paymentservice in JS)
Subagent 4: .NET services (cartservice, accountingservice)

Each subagent should use the service-documenter approach.
Then combine all findings into a comprehensive ARCHITECTURE.md

Expected Behavior:

4 parallel Task(...) indicators appear
Each completes independently
Results synthesized into single document

Check Context Usage Again

/context

1E: Participant Parallel Exercise

Prompt:

Explore this codebase using 3 parallel tasks:

Task 1: Analyze the frontend layer (src/frontend)
Task 2: Analyze the backend services (src/checkoutservice, src/cartservice)
Task 3: Analyze the data/infrastructure layer (docker-compose.yml, kubernetes/)

Each task should report:
- What components exist
- Key technologies used
- How they connect to other parts

Synthesize findings into a summary.

Success Criteria:

Participant sees parallel Task(...) execution
Receives combined summary
Has service-documenter.md in plugin folder

Phase 2: Test Generation

2A: Go Test Demo

Prompt:

Look at src/checkoutservice (Go) and generate a test suite:
- Unit tests for the main order placement logic
- Mock any external service calls
- Use table-driven tests following Go conventions
- Cover both success and error scenarios

Expected Output:

File named *_test.go
Table-driven test structure
Mocked external services
Error case coverage

2B: Python Test Alternative

Prompt:

Generate pytest tests for src/recommendationservice/recommendation_server.py
Include fixtures for the product catalog dependency

Expected Output:

pytest file with fixtures
Mocked gRPC calls
Multiple test cases

2C: Participant Test Exercises

Python (pytest):

Generate pytest tests for src/recommendationservice/recommendation_server.py
Include:
- Test for the ListRecommendations function
- Mock the product catalog dependency
- Test empty input handling
- Use pytest fixtures appropriately

Go (testing):

Generate tests for src/productcatalogservice/main.go
Include:
- Table-driven tests for GetProduct
- Tests for ListProducts with various filters
- Mock any database or external calls
- Test error conditions

TypeScript (Jest):

Generate Jest tests for the frontend cart functionality
Include:
- Test adding items to cart
- Test removing items
- Test quantity updates
- Mock API calls to the cart service

C# (xUnit):

Generate xUnit tests for src/cartservice
Include:
- Test AddItem functionality
- Test GetCart returns correct items
- Mock the Redis dependency
- Test concurrent access scenarios

Phase 3: Debugging & QA

3A: Single-Service Debug Demo

Option A - Hypothetical:

Users are reporting random payment failures.
Analyze src/paymentservice to find potential issues.
Check for error handling gaps, race conditions, and edge cases.

Option B - Prompt for injected bug:

Users are reporting random payment failures in production.
Analyze src/paymentservice to find the root cause.
Show me the problematic code and propose a fix.

3B: Bug-Hunter Subagent

File: .claude/plugins/codebase-toolkit/agents/bug-hunter.md

---
name: bug-hunter
description: Investigates a service for bugs, error handling gaps, and potential issues. Use when debugging or auditing code quality.
tools: Read, Grep, Glob
model: sonnet
---

You are a debugging specialist. When investigating a service:

1. Check all error handling paths
2. Look for unhandled exceptions
3. Identify potential race conditions
4. Find timeout/retry issues
5. Check for null/undefined handling

Report findings as:
- 🔴 **Critical:** [issue + file:line] - must fix immediately
- 🟡 **Warning:** [issue + file:line] - should address
- 🟢 **Info:** [observation] - minor improvement

Always include specific file paths and line numbers.
Suggest a fix for each critical and warning issue.

Installation Command:

cp .claude/plugins/codebase-toolkit/agents/bug-hunter.md .claude/agents/

3C: Parallel Debugging Demo

Prompt:

Debug the checkout flow using 4 parallel subagents:

Subagent 1: Investigate src/frontend for client-side error handling
Subagent 2: Investigate src/checkoutservice for orchestration issues
Subagent 3: Investigate src/paymentservice for payment processing bugs
Subagent 4: Investigate src/cartservice for data consistency issues

Use the bug-hunter approach for each.
Compile all findings into a prioritized bug report.

Expected Output:

4 parallel investigations
Findings categorized by severity
Cross-service issue identification

3D: Participant Debug Exercise

Prompt:

Analyze 3 services in parallel for potential issues:

Task 1: Check src/productcatalogservice for performance issues
Task 2: Check src/recommendationservice for error handling gaps
Task 3: Check src/cartservice for data validation issues

For each, report:
- Specific code locations with issues
- Severity (critical/warning/info)
- Suggested fix

Combine into a single report ordered by severity.

Success Criteria:

Parallel debugging executed
Issues identified with file:line references
Has bug-hunter.md in plugin folder

Phase 4: Development & MCP

4A: Feature Development Demo

Prompt:

Add a promotional discount code feature to the checkout flow:

1. Create a discount code input field on the cart/checkout page
2. Support these discount codes:
   - SAVE10 - 10% off entire order
   - FREESHIP - Free shipping (set shipping to $0)
   - ASTRO20 - 20% off orders over $100
3. Validate discount codes against a simple in-memory store
4. Display the discount amount and updated total
5. Ensure the discount is applied in the order confirmation
6. Add appropriate OpenTelemetry spans for discount validation

First show me your implementation plan, then build it.

Expected Output:

Implementation plan first
Multi-file changes
Consistent with existing patterns

4B: MCP Configuration

MCP (Model Context Protocol) servers extend Claude Code's capabilities by connecting to external tools. Claude Code uses the claude mcp add CLI command to configure servers.

Adding MCP Servers:

MCP servers can be added using the CLI with different transport types:

Transport	Use Case	Example
`http`	Remote cloud services (recommended)	GitHub, Sentry
`sse`	Server-Sent Events (deprecated)	Legacy services
`stdio`	Local processes	Playwright, Filesystem

Scope Options:

Scope	Storage Location	Use Case
`local`	`~/.claude.json` (per project)	Personal, single project
`project`	`.mcp.json` in project root	Team sharing, plugin bundling
`user`	`~/.claude.json` (global)	Personal, all projects

For this workshop, we use --scope project so the configuration is stored in .mcp.json and can later be bundled with a plugin.

Workshop MCP Servers:

# 1. Add Playwright MCP (browser automation)
claude mcp add --transport stdio --scope project playwright -- npx -y @anthropic/mcp-server-playwright

# 2. Add GitHub MCP (repository operations)
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/

# 3. Add Filesystem MCP (file operations outside repo)
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Resulting .mcp.json file (created automatically):

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}

Managing MCP Servers:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get playwright

# Remove a server
claude mcp remove playwright

# Check server status (within Claude Code)
/mcp

MCP Server Reference:

Server	Transport	Purpose	Requirements
Playwright	stdio	Browser automation, screenshots, UI testing	Node.js
GitHub	http	Repo operations, PRs, issues	OAuth (via `/mcp`)
Filesystem	stdio	File operations outside repo	Node.js

Authentication:

Some MCP servers (like GitHub) require OAuth authentication:

Add the server using claude mcp add
Start Claude Code: claude
Run /mcp command
Select the server and click "Authenticate"
Complete OAuth flow in browser

Windows Users Note:

On native Windows (not WSL), use the cmd /c wrapper:

claude mcp add --transport stdio --scope project playwright -- cmd /c npx -y @anthropic/mcp-server-playwright

4C: MCP Demo Prompts

Playwright MCP (Browser Automation):

Use Playwright to:
1. Open the demo application at http://localhost:8080
2. Take a screenshot of the homepage
3. Click on a product and capture that page too
4. Report what UI elements are visible

GitHub MCP (Repository Operations):

Note: GitHub MCP requires OAuth authentication. Run /mcp first, select "github", and click "Authenticate" to complete the OAuth flow in your browser.

Use the GitHub MCP to:
1. List the open issues in this repository
2. Summarize what bugs or features are requested
3. Suggest which our bug-hunter subagent could help investigate

Filesystem MCP (External File Access):

Use the Filesystem MCP to:
1. List files in the allowed directory
2. Read the contents of a specific file
3. Create a summary of what files are available

4D: Participant MCP Setup

Step 1: Verify Node.js is installed

node --version
# Should output v18.x or higher

Step 2: Add MCP servers using CLI

# Navigate to the project directory
cd opentelemetry-demo

# Add Playwright MCP (simplest to test)
claude mcp add --transport stdio --scope project playwright -- npx -y @anthropic/mcp-server-playwright

Step 3: Verify the configuration was created

# Check that .mcp.json was created
cat .mcp.json

Expected output:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"]
    }
  }
}

Step 4: Start Claude Code and verify

claude

Then run:

/mcp

You should see playwright listed as an available server.

Step 5: Test the MCP server

Use Playwright to take a screenshot of http://localhost:8080

Optional: Add GitHub MCP with authentication

# Exit Claude Code first
exit

# Add GitHub MCP
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/

# Start Claude Code
claude

# Authenticate with GitHub
/mcp
# Select "github" → "Authenticate" → Complete OAuth in browser

Optional: Add Filesystem MCP

# Exit Claude Code first
exit

# Add Filesystem MCP (replace with your actual path)
claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Start Claude Code
claude

Troubleshooting:

Issue	Solution
"Command not found: claude"	Ensure Claude Code is installed and in PATH
"npx: command not found"	Install Node.js (v18+)
Server not appearing in `/mcp`	Restart Claude Code after adding servers
"Connection closed" on Windows	Use `cmd /c` wrapper (see 4B)
GitHub authentication fails	Ensure you have a GitHub account and try `/mcp` again
`.mcp.json` not created	Check you're in the correct directory

4E: Participant Development Exercises

Task A — New Feature:

Add a "wishlist" feature to this application:
1. Users can save products for later
2. Store wishlist data using the existing cart service patterns
3. Add API endpoints to the frontend service
4. Follow the existing code patterns in this repo

First show me your implementation plan, then build it.

Task B — Refactoring:

Refactor src/cartservice to improve code quality:
- Extract repeated logic into helper functions
- Improve error messages to be more descriptive
- Add input validation where missing

Keep all existing functionality working.

Task C — New API Endpoint:

Add a "search products" endpoint to productcatalogservice:
- Accept a search query string
- Filter products by name or description
- Return matching products sorted by relevance
- Include proper error handling

Show me your plan first, then implement it.

Phase 5: Skills, Packaging & Marketplace

5A: Code-Reviewer Skill

Directory Setup:

mkdir -p .claude/plugins/codebase-toolkit/skills/code-reviewer

File: .claude/plugins/codebase-toolkit/skills/code-reviewer/SKILL.md

---
name: code-reviewer
description: Review code for quality, patterns, and potential issues. Use when reviewing PRs, auditing code quality, or preparing for code review.
---

# Code Review Skill

When reviewing code, analyze for:

## Code Quality
- Clear naming conventions
- Appropriate function/method length
- Single responsibility principle
- DRY (Don't Repeat Yourself) violations

## Error Handling
- All error paths handled
- Meaningful error messages
- No swallowed exceptions
- Proper cleanup in error cases

## Performance
- Unnecessary allocations
- N+1 query patterns
- Missing caching opportunities
- Inefficient algorithms

## Security Basics
- Input validation present
- No hardcoded secrets
- Proper authentication checks

## Output Format
Provide findings as:
- 🔴 **Critical** - Must fix before merge
- 🟡 **Warning** - Should address
- 🟢 **Suggestion** - Nice to have

Include file paths and line numbers for each finding.

Installation Commands:

mkdir -p ~/.claude/skills/code-reviewer
cp .claude/plugins/codebase-toolkit/skills/code-reviewer/SKILL.md ~/.claude/skills/code-reviewer/

Test Prompt:

/code-reviewer

Review src/paymentservice for code quality issues.

5B: Plugin Manifest (plugin.json)

File: .claude/plugins/codebase-toolkit/.claude-plugin/plugin.json

First, create the .claude-plugin directory inside your plugin folder:

mkdir -p .claude/plugins/codebase-toolkit/.claude-plugin

Then create the manifest:

{
  "name": "codebase-toolkit",
  "description": "A toolkit for onboarding to new codebases. Includes parallel documentation generation, automated bug hunting, and code review capabilities.",
  "version": "1.0.0",
  "author": {
    "name": "Workshop Participant"
  },
  "keywords": ["documentation", "debugging", "code-review", "onboarding"]
}

5C: Complete Plugin Structure

Verify your plugin has this structure:

.claude/plugins/codebase-toolkit/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest (required)
├── agents/
│   ├── service-documenter.md    # Documentation subagent
│   └── bug-hunter.md            # Debugging subagent
└── skills/
    └── code-reviewer/
        └── SKILL.md             # Code review skill

Verify all files exist:

ls -la .claude/plugins/codebase-toolkit/.claude-plugin/
ls -la .claude/plugins/codebase-toolkit/agents/
ls -la .claude/plugins/codebase-toolkit/skills/code-reviewer/

5D: Create Local Test Marketplace

A marketplace is a directory containing a manifest that lists available plugins. We'll create a local one to test before publishing to GitHub.

Step 1: Create marketplace directory (sibling to the repo)

# From inside opentelemetry-demo, go up one level
cd ..

# Create the marketplace structure
mkdir -p test-marketplace/.claude-plugin
cp -r opentelemery-demo/.claude/plugins/codebase-toolkit test-marketplace

Step 2: Create marketplace manifest

File: test-marketplace/.claude-plugin/marketplace.json

{
  "name": "test-marketplace",
  "owner": {
    "name": "Workshop Participant"
  },
  "plugins": [
    {
      "name": "codebase-toolkit",
      "source": "./codebase-toolkit",
      "description": "A toolkit for onboarding to new codebases"
    }
  ]
}

Directory structure after this step:

~/workshop/
├── opentelemetry-demo/              # Cloned demo repo (work happens here)
└── test-marketplace/                # This becomes your GitHub marketplace
    ├── .claude-plugin/
    │   └── marketplace.json         # source: "./codebase-toolkit"
    └── codebase-toolkit/            # Plugin lives inside marketplace
        ├── .claude-plugin/
        │   └── plugin.json
        ├── agents/
        ├── skills/
        └── hooks/

5E: Install and Test Plugin Locally

Step 1: Remove manually installed components (clean slate)

rm -f ~/.claude/agents/service-documenter.md
rm -f ~/.claude/agents/bug-hunter.md
rm -rf ~/.claude/skills/code-reviewer

# Clean from Opentelemetry Demo as well if installed.
cd opentelemetry-demo
rm -f .claude/agents/service-documenter.md
rm -f .claude/agents/bug-hunter.md
rm -rf .claude/skills/code-reviewer

Step 2: Go back to the demo repo and add the marketplace

cd opentelemetry-demo
claude

/plugin marketplace add ../test-marketplace

Step 3: Install the plugin

/plugin install codebase-toolkit@test-marketplace

Select "Install now" when prompted.

Step 4: Restart Claude Code

# Exit and restart
exit
claude

Step 5: Test the plugin

/code-reviewer

Briefly review src/cartservice for code quality.

5F: Publish to GitHub Marketplace

GitHub Marketplace Repository: rishikeshradhakrishnan/marketplace

The marketplace repository structure:

marketplace/                              # GitHub repo
├── .claude-plugin/
│   └── marketplace.json                  # Marketplace manifest
└── plugins/
    └── codebase-toolkit/                 # Plugin copied here
        ├── .claude-plugin/
        │   └── plugin.json
        ├── agents/
        │   ├── service-documenter.md
        │   └── bug-hunter.md
        └── skills/
            └── code-reviewer/
                └── SKILL.md

Step 1: Clone the marketplace repo

cd ~
git clone https://github.com/rishikeshradhakrishnan/marketplace.git
cd marketplace

Step 2: Create the directory structure

mkdir -p .claude-plugin
mkdir -p plugins

Step 3: Copy your plugin

cp -r ~/workshop/opentelemetry-demo/.claude/plugins/codebase-toolkit plugins/

Step 4: Create the marketplace manifest

File: .claude-plugin/marketplace.json

{
  "name": "rishikesh-marketplace",
  "owner": {
    "name": "Rishikesh Radhakrishnan"
  },
  "metadata": {
    "description": "Claude Code plugins for developer productivity",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "codebase-toolkit",
      "source": "./plugins/codebase-toolkit",
      "description": "A toolkit for onboarding to new codebases. Includes parallel documentation, debugging, and code review.",
      "version": "1.0.0",
      "author": {
        "name": "Workshop Participant"
      },
      "keywords": ["documentation", "debugging", "code-review", "onboarding"]
    }
  ]
}

Step 5: Commit and push

git add .
git commit -m "Add codebase-toolkit plugin v1.0.0"
git push origin main

Step 6: Add the GitHub marketplace to Claude Code

cd ~/workshop/opentelemetry-demo
claude

/plugin marketplace add rishikeshradhakrishnan/marketplace

5G: Browse Existing Marketplaces

Add Anthropic's official demo marketplace:

/plugin marketplace add anthropics/claude-code

Browse available plugins:

/plugin

Select "Browse Plugins" to see available options.

List all known marketplaces:

/plugin marketplace list

Available Marketplaces:

Marketplace	Source	Description
anthropics/claude-code	GitHub	Official Anthropic demo plugins
rishikeshradhakrishnan/marketplace	GitHub	Workshop plugins
test-marketplace	Local	Local testing

Phase 6: Reusability Demo

6A: Clone Fresh Repository

Step 1: Navigate to a new directory

cd ~
mkdir plugin-demo
cd plugin-demo

Step 2: Clone the OpenTelemetry demo fresh (main branch, no modifications)

git clone https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo

6B: Install Plugin from Marketplace

Step 1: Start Claude Code

claude

Step 2: Add the GitHub marketplace

/plugin marketplace add rishikeshradhakrishnan/marketplace

Step 3: Install the plugin

/plugin install codebase-toolkit@rishikesh-marketplace

Step 4: Restart Claude Code

exit
claude

6C: Use Plugin on New Codebase

Option 1: Use the code-reviewer skill

/code-reviewer

Review the src/frontend directory for code quality issues.
Focus on error handling and TypeScript best practices.

Option 2: Use the service-documenter subagent

Use the service-documenter subagent to document 
src/checkoutservice and src/paymentservice in parallel.
Create a combined services documentation file.

Option 3: Use bug-hunter for parallel debugging

Use 3 bug-hunter subagents in parallel to investigate:
- src/cartservice
- src/productcatalogservice  
- src/recommendationservice

Compile findings into a prioritized report.

Notes: Before workshop, add to src/paymentservice/charge.js: for bug simulation.

// Add inside the charge function
if (Math.random() < 0.3) throw new Error("Connection timeout");

FilesExpand file tree

Workshop-Technical-Reference.md

Latest commit

History

Workshop-Technical-Reference.md

File metadata and controls

Claude Code Workshop - Technical Reference

Table of Contents

Pre-Workshop Setup

Participant Requirements

Instructor Pre-Check

Phase 1: Documentation & Analysis

1A: Basic Documentation Demo

1B: Plugin Directory Setup

1C: Service-Documenter Subagent

1D: Parallel Subagents Demo

1E: Participant Parallel Exercise

Phase 2: Test Generation

2A: Go Test Demo

2B: Python Test Alternative

2C: Participant Test Exercises

Phase 3: Debugging & QA

3A: Single-Service Debug Demo

3B: Bug-Hunter Subagent

3C: Parallel Debugging Demo

3D: Participant Debug Exercise

Phase 4: Development & MCP

4A: Feature Development Demo

4B: MCP Configuration

4C: MCP Demo Prompts

4D: Participant MCP Setup

4E: Participant Development Exercises

Phase 5: Skills, Packaging & Marketplace

5A: Code-Reviewer Skill

5B: Plugin Manifest (plugin.json)

5C: Complete Plugin Structure

5D: Create Local Test Marketplace

5E: Install and Test Plugin Locally

5F: Publish to GitHub Marketplace

5G: Browse Existing Marketplaces

Phase 6: Reusability Demo

6A: Clone Fresh Repository

6B: Install Plugin from Marketplace

6C: Use Plugin on New Codebase