Code Walkthrough

Create executable, verifiable documentation that explains how code works.

Overview

This skill helps you create linear code walkthroughs — structured documents that explain a codebase from start to finish. Inspired by Simon Willison’s “Agentic Engineering Patterns”, this approach combines:

• Automated code extraction (using cat, grep, sed)
• Executed commands with captured output
• Human-readable explanations of architecture and design decisions

The result is a document that both humans can read and machines can verify.

When to Use This Skill

Use code-walkthrough when:

1. Onboarding to a new codebase — understand unfamiliar projects quickly
2. Documenting your own code — create maintainable documentation
3. Understanding AI-generated code — turn “vibe coding” into actual knowledge
4. Code reviews — provide detailed architectural explanations
5. Knowledge sharing — help teammates understand complex systems

Prerequisites

Required Tools

• Showboat (pip install showboat or uvx showboat) — for creating executable walkthrough documents
• Standard Unix tools (cat, grep, sed, find, wc, head, tail)

Optional Tools

• tree — for directory visualization
• cloc — for code statistics

Workflow

Step 1: Initialize the Walkthrough

Create a new walkthrough document in the target repository:

cd /path/to/repository
showboat init walkthrough.md "Project Name - Code Walkthrough"

Step 2: Document Structure

Add a structured overview using showboat note:

showboat note walkthrough.md "
## Project Overview

[High-level description of what the project does]

### Technology Stack
- Language: [e.g., Go, Python, TypeScript]
- Framework: [e.g., Django, React, Gin]
- Database: [e.g., PostgreSQL, SQLite]

### Architecture Pattern
[e.g., MVC, Clean Architecture, Microservices]
"

Step 3: Capture Project Structure

Use automated commands to capture directory structure:

showboat exec walkthrough.md bash "ls -la"
showboat exec walkthrough.md bash "find . -type f -name '*.go' | head -20"
showboat exec walkthrough.md bash "wc -l **/*.go 2>/dev/null | tail -20"

Tip: If tree is available, use it for better visualization:

showboat exec walkthrough.md bash "tree -L 2 -d"

Step 4: Deep Dive into Key Files

Extract and explain important files using cat:

showboat note walkthrough.md "
## Entry Point Analysis

The application starts here:
"

showboat exec walkthrough.md bash "cat cmd/server/main.go"

Step 5: Add Analysis and Insights

After each code extraction, add explanatory notes:

showboat note walkthrough.md "
### Key Observations

1. **Dependency Injection**: Uses Wire for DI
2. **Graceful Shutdown**: Handles SIGINT/SIGTERM
3. **Configuration**: Supports both CLI flags and env vars
"

Step 6: Verify the Walkthrough

Ensure all commands still work and outputs match:

showboat verify walkthrough.md

If outputs have changed (e.g., after code updates), generate an updated version:

showboat verify walkthrough.md --output walkthrough-updated.md

Best Practices

Do’s

• Use automated extraction: Always use cat, grep, sed instead of copy-pasting code. This prevents errors and ensures the walkthrough stays up-to-date.
• Include output blocks: Every exec command should be followed by its output in the document.
• Progressive disclosure: Start with high-level structure, then drill into details.
• Explain the “why”: Don’t just show code — explain design decisions and architecture patterns.
• Keep it linear: Structure the document as a journey through the codebase.

Don’ts

• Don’t manually copy-paste code: This defeats the purpose of verifiable documentation.
• Don’t include secrets: Use grep -v or environment variables to filter sensitive data.
• Don’t make it too long: Focus on the most important 20% of the codebase that explains 80% of the architecture.
• Don’t skip verification: Always run showboat verify before sharing.

Example Walkthrough Structure

# Project Name - Code Walkthrough

## 1. Project Overview
[High-level description]

## 2. Directory Structure
[Automated listing]

## 3. Entry Point
[Main file analysis]

## 4. Core Modules
### 4.1 Module A
### 4.2 Module B

## 5. Data Flow
[How data moves through the system]

## 6. Key Design Patterns
[Architecture insights]

## 7. Summary
[Key takeaways]

Advanced Techniques

Filtering Sensitive Information

When documenting code that might contain secrets:

showboat exec walkthrough.md bash "cat config.yaml | grep -v 'password\|secret\|key'"

Partial File Extraction

For large files, extract only relevant sections:

# Show first 50 lines
showboat exec walkthrough.md bash "head -50 large_file.py"

# Show specific function
showboat exec walkthrough.md bash "grep -A 20 'def important_function' file.py"

# Show specific section by line numbers
showboat exec walkthrough.md bash "sed -n '100,150p' file.go"

Code Statistics

Include metrics to give readers a sense of scale:

showboat exec walkthrough.md bash "find . -name '*.py' -exec wc -l {} + | tail -1"
showboat exec walkthrough.md bash "cloc . --exclude-dir=node_modules,venv"

Resources

scripts/

• generate_walkthrough.py — Helper script to automate common patterns
• extract_module.sh — Extract and document a specific module

Tips for Different Project Types

Web Applications

Focus on:

• Request/response flow
• Routing and middleware
• Database models and relationships
• API endpoints

CLI Tools

Focus on:

• Command structure and subcommands
• Configuration handling
• Exit codes and error handling
• I/O patterns

Libraries/Frameworks

Focus on:

• Public API surface
• Core abstractions and interfaces
• Extension points
• Usage examples

AI-Generated Code

Focus on:

• “How does this actually work?” questions
• Dependencies and external calls
• Data transformations
• Potential edge cases or bugs

Troubleshooting

“Command not found” errors

Ensure tools are installed:

pip install showboat
# or
uvx showboat --help

Large output truncation

For very large outputs, consider:

• Using head/tail to show portions
• Using grep to extract specific parts
• Splitting into multiple code blocks

Binary files or images

Use showboat image for screenshots:

showboat image walkthrough.md screenshot.png

Related Patterns

• Simon Willison’s Linear Walkthroughs: https://simonwillison.net/guides/agentic-engineering-patterns/linear-walkthroughs/
• Showboat Documentation: https://github.com/simonw/showboat
• Agentic Engineering Patterns: https://simonwillison.net/guides/agentic-engineering-patterns/