> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Start Your First Session
> Guide to starting a first session with Claude Code, generating CLAUDE.md, and scaffolding a Python CSV utility into a package with tests, CLI, and tooling
In this lesson you'll learn how to start your first session with Claude Code and scaffold a small Python project. We'll cover the initial `/init` step that generates `CLAUDE.md`, how Claude inspects your repository, and an example of the kind of scaffolding it may propose for a CSV-based utility.
Getting started: run `/init` to create a `CLAUDE.md` file that contains project metadata, developer notes, and usage instructions for Claude. Claude will scan the repository (looking for files like `package.json`, `pyproject.toml`, `requirements.txt`, etc.), infer the project type, and propose edits or scaffolding — for example converting a single script into a small package with tests and a CLI. Treat Claude Code like another engineer: be explicit and concrete when describing expected behavior, file formats, command-line interfaces, and failure modes.
Be specific in prompts — describe file formats, expected command-line behavior, inputs, and error handling, just as you would when assigning a task to a teammate.
Example repository utility
* Below is the cleaned-up utility script this repository started with. Claude often finds single-purpose scripts like this and suggests packaging and tests. This snippet is robust and includes UTF-8 handling and header name flexibility.
```python theme={null}
# read_members.py
import csv
from pathlib import Path
def read_members(path: str = "members.csv") -> None:
"""
Read and print first and last names from a CSV file.
Accepts both snake_case and Title Case headers for name fields.
"""
try:
file_path = Path(path)
with file_path.open("r", newline="", encoding="utf-8") as file:
reader = csv.DictReader(file)
for row in reader:
first_name = (row.get("first_name") or row.get("First Name") or "").strip()
last_name = (row.get("last_name") or row.get("Last Name") or "").strip()
print(f"{first_name} {last_name}".strip())
except FileNotFoundError:
print(f"Error: {path} file not found")
except Exception as e:
print(f"Error reading file: {e}")
if __name__ == "__main__":
read_members()
```
What `/init` typically produces
* Claude inspects repository files and creates `CLAUDE.md` with project metadata, usage instructions, and developer notes.
* It may propose turning a single-purpose script into a package with packaging files, a test suite, a CLI entrypoint, and CI configuration.
* When Claude proposes changes, it displays interactive edit prompts so you can accept, decline, or modify suggested edits.
Example interactive prompt (cleaned for readability):
```text theme={null}
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)
```
Typical content added to `CLAUDE.md`
* Short project description, e.g. "Simple Python project that processes member data from a CSV file".
* Runtime & development instructions: Python version, virtual environment activation, and how to run the main script.
* Short architecture summary: single-purpose script vs package, suggested package layout.
* Suggested next steps: add `pyproject.toml`/`setup.py`, tests, CLI, and CI/CD setup.
Scaffolding a package
Claude often suggests a package layout. Below are representative, corrected snippets you might find in the suggestions. They show how small scripts can become a maintainable package with tests and tooling.
Files and purpose (summary)
| File / Resource | Purpose | Example / Notes |
| - | - | - |
| `__init__.py` | Package exports & version | Exposes `CSVMemberReader` and exceptions |
| `reader.py` | Core CSV reading functionality | Implements `CSVMemberReader` and `MemberData` |
| `exceptions.py` | Domain-specific exceptions | Custom exceptions for clear error handling |
| `pyproject.toml` | Build/tooling config | Build-system, formatters, mypy, pytest settings |
| `cli.py` | Command-line entrypoint | CLI example with logging and argparse |
| `tests/` | Unit tests with pytest | Examples validating header variations |
Example `__init__.py` for `csv_member_reader`:
```python theme={null}
"""
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`:
```python theme={null}
"""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` (core functionality with dataclass):
```python theme={null}
"""Core CSV member reading functionality."""
import csv
import logging
from dataclasses import dataclass
from pathlib import Path
from typing import Iterator, Optional
from .exceptions import FileNotFoundError, InvalidDataError
logger = logging.getLogger(__name__)
@dataclass
class MemberData:
id: Optional[str] = None
first_name: str = ""
last_name: str = ""
email: Optional[str] = None
class CSVMemberReader:
def __init__(self, path: str):
self.path = Path(path)
def __iter__(self) -> Iterator[MemberData]:
if not self.path.exists():
raise FileNotFoundError(f"{self.path} not found")
with self.path.open("r", encoding="utf-8", newline="") as f:
reader = csv.DictReader(f)
for row in reader:
try:
first = (row.get("first_name") or row.get("First Name") or "").strip()
last = (row.get("last_name") or row.get("Last Name") or "").strip()
yield MemberData(first_name=first, last_name=last)
except Exception as exc:
logger.exception("Invalid row encountered")
raise InvalidDataError("Malformed CSV row") from exc
```
Example `pyproject.toml` excerpt (tooling & testing hints):
```toml theme={null}
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
[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"
```
CLI helper example (`cli.py` start):
```python theme={null}
"""Command-line interface for CSV Member Reader."""
import argparse
import logging
from pathlib import Path
from .reader import CSVMemberReader
from .exceptions import CSVMemberReaderError
def setup_logging(verbose: bool = False) -> None:
"""Set up logging configuration."""
level = logging.DEBUG if verbose else logging.INFO
logging.basicConfig(
level=level,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
```
Example CLI usage script (`examples/basic_usage.sh`):
```bash theme={null}
#!/usr/bin/env bash
echo "=== CSV Member Reader CLI Examples ==="
# 1. Print all member names
echo "1. Print all member names:"
csv-member-reader ../members.csv
# 2. Show total member count
echo -e "\n2. Show total member count:"
csv-member-reader ../members.csv --count
# 3. Verbose output with logging
echo -e "\n3. Verbose output with logging:"
csv-member-reader ../members.csv --verbose --count
# 4. Using different encoding
echo -e "\n4. Using different encoding:"
csv-member-reader ../members.csv --encoding utf-8
# 5. Handling non-existent file (will show error)
echo -e "\n5. Handling non-existent file (expected error):"
csv-member-reader nonexistent.csv || echo "Expected error for missing file"
```
Testing
* Claude can scaffold `pytest` tests. Example test below verifies the package handles header variations like `first_name` or `First Name`.
```python theme={null}
# tests/test_reader.py
import io
import pytest
from csv_member_reader.reader import CSVMemberReader, MemberData
def test_column_name_variations(tmp_path):
content = "ID,First Name,Last Name,Email\n1,John,Doe,john@example.com\n"
file = tmp_path / "members.csv"
file.write_text(content, encoding="utf-8")
reader = CSVMemberReader(str(file))
members = list(reader)
assert members[0].first_name == "John"
assert members[0].last_name == "Doe"
```
Common development commands to add to `CLAUDE.md`
```bash theme={null}
# Setup the editable dev install and hooks
cd csv_member_reader
pip install -e ".[dev]"
pre-commit install
# Run tests
pytest
pytest --cov=csv_member_reader --cov-report=html
# Code quality
black .
flake8
mypy csv_member_reader
# Build package
python -m build
# Install and use CLI locally
pip install -e .
csv-member-reader ../members.csv
```
Common issues and verification steps
* Generated instructions may assume a particular environment or layout. Always open `CLAUDE.md` and confirm commands before running.
* If you get `ModuleNotFoundError: No module named 'csv_member_reader'`, ensure you installed the package in editable mode (`pip install -e .`) or that your PYTHONPATH includes the project root.
* Mypy errors such as "Source file found twice under different module names" usually indicate package layout or duplicate top-level folders; verify `pyproject.toml` and source layout.
Generated scaffolding is a strong starting point but not a guarantee of a fully working configuration. Validate tests, linter settings, and packaging instructions before publishing. If Claude suggests commands you don't understand (for example, `pip install -e ".[dev]"`), consult the relevant docs and adapt commands for your OS (on macOS you may need `pip3`).
Wrap-up
* Run `/init` to generate `CLAUDE.md` and let Claude analyze and propose repository changes.
* Be explicit in prompts; treat Claude as a developer who needs clear requirements.
* Review and validate any generated package layout, `pyproject.toml`, tests, and CI before publishing.
* Use Claude to accelerate repetitive scaffolding (package boilerplate, tests, CLI, docs), but always review and iterate.
Links and references
* [Python Packaging User Guide](https://packaging.python.org/)
* [pytest Documentation](https://docs.pytest.org/)
* [Black Formatter](https://black.readthedocs.io/)
* [mypy — Optional Static Typing for Python](https://mypy.readthedocs.io/)
* [pre-commit — A framework for managing and maintaining multi-language pre-commit hooks](https://pre-commit.com/)
This is how you start your first session: let Claude handle repetitive scaffolding while you validate, test, and refine the generated project structure.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.