Skip to main content
All right — let’s walk through starting your first Claude Code session, analyzing a repository, and scaffold­ing a production-ready Python package from a simple script.
A minimalist presentation slide that says "Start your First Session" on the left and a large "Demo" on a dark curved shape at right. A small "© Copyright KodeKloud" appears in the bottom-left corner.
Quick practical tips for a productive first session:
  • Run /init to generate a CLAUDE.md file that guides Claude Code for repository-specific actions.
  • Use Claude Code to analyze files, suggest edits, run bash commands, and help with git workflows.
  • Be explicit in prompts — include expected behavior, sample inputs/outputs, and any constraints to get precise results.
Be explicit as you would be with another developer — include expected behavior, example inputs/outputs, constraints, and any style or tooling preferences (e.g., black, mypy).

Example repository: simple CSV reader

The demo repository starts as a single-file Python script that reads member names from a CSV. It demonstrates basic error handling and flexible header parsing.
# members_reader.py
import csv

def read_members():
    try:
        with open('members.csv', 'r', newline='', encoding='utf-8') as file:
            reader = csv.DictReader(file)
            for row in reader:
                first_name = row.get('first_name', row.get('First Name', ''))
                last_name = row.get('last_name', row.get('Last Name', ''))
                print(f"{first_name} {last_name}")
    except FileNotFoundError:
        print("Error: members.csv file not found")
    except Exception as e:
        print(f"Error reading file: {e}")

if __name__ == "__main__":
    read_members()

What happens when you run /init

When you run the /init command, Claude Code:
  • Scans the repository for files (e.g., package.json, pyproject.toml, requirements, Python sources).
  • Generates a CLAUDE.md file describing the project, usage, and recommended next steps.
  • Proposes interactive edits and scaffolding; each change requires your confirmation.
Example interactive prompts you may see while accepting edits:
Read README.md for important project information
Create CLAUDE.md file with essential information

• Write(CLAUDE.md)

Opened changes in Visual Studio Code
Save file to continue...

Do you want to make this edit to CLAUDE.md?
> 1. Yes
  2. Yes, and don't ask again this session (shift+tab)
  3. No, and tell Claude what to do differently (esc)

What belongs in CLAUDE.md

CLAUDE.md provides repository-specific guidance for subsequent Claude Code actions. Typical contents for this demo include:
  • Project description: a small Python utility to parse member CSVs.
  • How to activate a virtual environment and run the script.
  • Notes on code architecture: single-purpose script, basic error handling, flexible parsing of snake_case and Title Case headers.
  • Recommended next steps for packaging, testing, and CI.

Typical scaffolding Claude Code may propose

Claude Code often suggests turning a script into a package with a standardized layout, tests, and tooling. Example suggestions:
ResourcePurpose
Package directorycsv_member_reader/{csv_member_reader,tests,examples,docs}
Packaging metadataAdd pyproject.toml or setup.py for builds and publishing
Project docsREADME, CONTRIBUTING, docs for usage and developer guide
Testing & lintingpytest, mypy, black, pre-commit
CLI & workflowsCLI entry point and GitHub Actions for CI/CD
Typical CLI-style prompts for confirming filesystem changes:
Bash(mkdir -p csv_member_reader/{csv_member_reader,tests,examples,docs})
 Running...

Bash command:
mkdir -p csv_member_reader/{csv_member_reader,tests,examples,docs}
Create proper Python package directory structure

Do you want to proceed?
> 1. Yes
  2. Yes, and don't ask again for mkdir commands in /Users/jeremy/demos/my-awesome-project
  3. No, and tell Claude what to do differently (esc)
If you accept, Claude Code will write new files such as __init__.py, exceptions.py, and reader.py. Below are representative, production-oriented excerpts that illustrate the refactor.

Example: init.py (excerpt)

"""
CSV Member Reader - A Python package for reading and
processing member data from CSV files.
"""

from .reader import CSVMemberReader, MemberData
from .exceptions import CSVMemberReaderError, FileNotFoundError, InvalidDataError

__version__ = "0.1.0"

__all__ = [
    "CSVMemberReader",
    "MemberData",
    "CSVMemberReaderError",
    "FileNotFoundError",
    "InvalidDataError",
]

Example: exceptions.py

"""Custom exceptions for CSV Member Reader."""

class CSVMemberReaderError(Exception):
    """Base exception for CSV Member Reader."""
    pass

class FileNotFoundError(CSVMemberReaderError):
    """Raised when the CSV file is not found."""
    pass

class InvalidDataError(CSVMemberReaderError):
    """Raised when the CSV data is invalid or malformed."""
    pass

Example: reader.py (header and dataclass excerpt)

"""Core CSV member reading functionality."""

import csv
import logging
from typing import Iterator, Optional, Dict, Any, List
from dataclasses import dataclass
from pathlib import Path

from .exceptions import FileNotFoundError, InvalidDataError

logger = logging.getLogger(__name__)

@dataclass
class MemberData:
    """Data class representing a member record."""
    id: Optional[str] = None
    first_name: str = ""
    last_name: str = ""
    # additional fields...

Example: pyproject.toml fragment

[tool.black]
line-length = 88
target-version = ['py38']

[tool.mypy]
python_version = "3.8"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
addopts = "--cov=csv_member_reader --cov-report=html --cov-report=term-missing"

Common file and CLI commands after scaffolding

# Create project structure
mkdir -p csv_member_reader/{csv_member_reader,tests,examples,docs}

# Make CLI script executable (if created)
chmod +x scripts/csv-member-reader
A canonical development checklist you can follow:
StepCommand / Action
Enter project directorycd csv_member_reader
Install editable dev environmentpip install -e ”.[dev]“
Install pre-commit hookspre-commit install
Run testspytest
Run tests with coveragepytest —cov=csv_member_reader —cov-report=html
Build the packagepython -m build
Install and run CLIpip install -e . && csv-member-reader ../members.csv —count
To publish: initialize git, push to GitHub, configure PyPI credentials in CI, and create a release.

Common issues and troubleshooting

SymptomLikely causeFix
ModuleNotFoundError: No module named ‘csv_member_reader’Package not installed in editable mode or PYTHONPATH misconfiguredRun pip install -e . from the package root or adjust PYTHONPATH
mypy reports duplicate module pathsAmbiguous package layout or init.py placementEnsure consistent package layout and use explicit mypy options like --explicit-package-bases
pre-commit install failsNot inside a git repositoryInitialize git (git init) before installing pre-commit hooks
Note: On macOS, if your system Python maps to Python 2.x, use pip3:
pip3 install -e ".[dev]"
Claude Code can generate many useful files and CI scaffolding, but always review generated code, dependency versions, and CI settings. Validate and test changes before committing or publishing.

Why refactor into a package?

  • Organization: Modules and classes are easier to maintain than a growing script.
  • Reusability: An installable package can be consumed as a library or CLI.
  • Testability: Unit tests and CI workflows make it safer to evolve code.
  • Distribution: pyproject-based packaging and GitHub workflows enable publishing to PyPI.

Wrap-up

  • The typical first session: run /init, review and refine CLAUDE.md, and confirm proposed edits.
  • Claude Code can scaffold package layout, tests, CLI, docs, and CI — but you must review and iterate on suggestions.
  • Treat Claude Code as an assistant: provide explicit requirements and verify all generated artifacts before publishing.
The demo illustrated how a simple CSV-reading script can be analyzed and progressively refactored into a production-ready package using Claude Code. Use the patterns above to guide your own repository bootstrap and development workflow.

Watch Video