
- Run
/initto 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.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.
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:
Typical CLI-style prompts for confirming filesystem changes:
__init__.py, exceptions.py, and reader.py. Below are representative, production-oriented excerpts that illustrate the refactor.
Example: init.py (excerpt)
Example: exceptions.py
Example: reader.py (header and dataclass excerpt)
Example: pyproject.toml fragment
Common file and CLI commands after scaffolding
To publish: initialize git, push to GitHub, configure PyPI credentials in CI, and create a release.
Common issues and troubleshooting
Note: On macOS, if your system Python maps to Python 2.x, use
pip3:
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.
Links and references
- Python Packaging User Guide
- pyproject.toml specification
- pytest documentation
- black code formatter
- mypy static type checker
- GitHub Actions