> ## 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.
# Demo Start Your First Session
> A demo showing how Claude Code initializes a repository, generates CLAUDE.md, and scaffolds a production-ready Python package from a simple CSV reader script with tests, tooling, and CI
All right — let's walk through starting your first Claude Code session, analyzing a repository, and scaffolding a production-ready Python package from a simple script.
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.
```python theme={null}
# 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:
```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)
```
## 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:
| Resource | Purpose |
| ------------------ | ------------------------------------------------------------ |
| Package directory | `csv_member_reader/{csv_member_reader,tests,examples,docs}` |
| Packaging metadata | Add `pyproject.toml` or `setup.py` for builds and publishing |
| Project docs | README, CONTRIBUTING, docs for usage and developer guide |
| Testing & linting | `pytest`, `mypy`, `black`, `pre-commit` |
| CLI & workflows | CLI entry point and GitHub Actions for CI/CD |
Typical CLI-style prompts for confirming filesystem changes:
```Bash theme={null}
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)
```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 (header and dataclass excerpt)
```python theme={null}
"""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
```toml theme={null}
[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
```bash theme={null}
# 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:
| Step | Command / Action |
| -------------------------------- | ------------------------------------------------------------ |
| Enter project directory | cd csv\_member\_reader |
| Install editable dev environment | pip install -e ".\[dev]" |
| Install pre-commit hooks | pre-commit install |
| Run tests | pytest |
| Run tests with coverage | pytest --cov=csv\_member\_reader --cov-report=html |
| Build the package | python -m build |
| Install and run CLI | pip 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
| Symptom | Likely cause | Fix |
| ---------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| ModuleNotFoundError: No module named 'csv\_member\_reader' | Package not installed in editable mode or PYTHONPATH misconfigured | Run `pip install -e .` from the package root or adjust PYTHONPATH |
| mypy reports duplicate module paths | Ambiguous package layout or **init**.py placement | Ensure consistent package layout and use explicit mypy options like `--explicit-package-bases` |
| pre-commit install fails | Not inside a git repository | Initialize git (`git init`) before installing pre-commit hooks |
Note: On macOS, if your system Python maps to Python 2.x, use `pip3`:
```bash theme={null}
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.
## Links and references
* [Python Packaging User Guide](https://packaging.python.org/)
* [pyproject.toml specification](https://peps.python.org/pep-0621/)
* [pytest documentation](https://docs.pytest.org/)
* [black code formatter](https://black.readthedocs.io/)
* [mypy static type checker](https://mypy.readthedocs.io/)
* [GitHub Actions](https://docs.github.com/actions)