From 48d941bf05dd1035d3d19f045410ce31f6c0e4fe Mon Sep 17 00:00:00 2001 From: Alexis Date: Fri, 5 Dec 2025 10:49:00 +0100 Subject: [PATCH 1/4] feat: Add a CLAUDE.md file --- {{cookiecutter.project_slug}}/CLAUDE.md | 51 +++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 {{cookiecutter.project_slug}}/CLAUDE.md diff --git a/{{cookiecutter.project_slug}}/CLAUDE.md b/{{cookiecutter.project_slug}}/CLAUDE.md new file mode 100644 index 0000000..3e37f9d --- /dev/null +++ b/{{cookiecutter.project_slug}}/CLAUDE.md @@ -0,0 +1,51 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +{{ cookiecutter.project_description }} + +{%- if cookiecutter.repo_type == 'CLI' %} +This is a command-line application with entry point `{{ cookiecutter.entry_point }}`. +{%- else %} +This is a Python library package. +{%- endif %} + +## Stack + +- Package manager: uv +- Build backend: hatchling +- Linting/formatting: ruff +- Type checking: pyright +- Testing: pytest +- CI: GitHub Actions (lint, test, release{%- if cookiecutter.documentation != 'none' %}, docs{%- endif %}) + +## Commands + +Use Makefile targets, not tool commands directly: + +- `make format` - Fix formatting issues +- `make lint` - Run all static checks (ruff, pyright) +- `make test` - Run tests with coverage +- `make doc` - Generate documentation +- `make build` - Build the package +{%- if cookiecutter.entry_point %} +- `make run` - Run the CLI (use `ARGS="..."` for arguments) +{%- endif %} + +## Verification + +Run `make lint && make test` before committing. + +## Commit Messages + +- Summary line: max 50 chars (hard limit 72) +- Body lines: max 72 chars +- Use Markdown formatting in description +- Reference issues where relevant (e.g., `See #123`) + +## Project Layout + +- `src/{{ cookiecutter.__project_import.replace('.', '/') }}/` - Source code +- `test/` - Test files From f036a43beee0e25787863739672ccbed8b28bffa Mon Sep 17 00:00:00 2001 From: Alexis Date: Fri, 5 Dec 2025 11:01:08 +0100 Subject: [PATCH 2/4] Add repository CLAUDE.md file --- CLAUDE.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0783b26 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +A Cookiecutter template for Python packages, supporting both CLI and library project types. Generates projects with uv, ruff, pyright, and pytest pre-configured. It also comes with GitHub Actions workflows configured for the project. + +This template is opinionated and enforces recommended practices when creating new Python projects. + +## Repository Structure + +- `{{cookiecutter.project_slug}}/` - Template directory (rendered by Cookiecutter) +- `cookiecutter.json` - Template variables and prompts +- `hooks/` - Pre/post generation scripts + - `pre_gen_project.py` - Validates inputs (namespace, slug, entry point) + - `post_gen_project.py` - Cleans up unused files based on options + +## Key Template Variables + +| Variable | Purpose | +|----------|---------| +| `project_name` | Human-readable name | +| `project_slug` | Pip/repo name (auto-derived) | +| `project_namespace_import` | Optional namespace (e.g., `company.tools`) | +| `repo_type` | `CLI` or `library` | +| `entry_point` | CLI command name (CLI only) | + +## Testing Changes + +Generate a test project to verify template changes: + +```bash +# Generate in temp directory +uvx cookiecutter -o /tmp . + +# Or with specific options (no prompts) +uvx cookiecutter --no-input -o /tmp . project_name="Test Project" repo_type="CLI" +``` + +Then verify the generated project: + +```bash +cd /tmp/test-project +make lint && make test +``` + +## Verification + +When modifying the template: + +1. Ensure Jinja2 syntax is valid in template files +2. Test both `CLI` and `library` repo types +3. Test with and without `project_namespace_import` +4. Verify generated project passes `make lint && make test` + +## Commit Messages + +- Summary line: max 50 chars (hard limit 72) +- Body lines: max 72 chars +- Use Markdown formatting in description From e2a84170db3ac84336b44757a5389d71edb43c08 Mon Sep 17 00:00:00 2001 From: Alexis Date: Fri, 5 Dec 2025 11:03:46 +0100 Subject: [PATCH 3/4] =?UTF-8?q?Fix=20build=20backend:=20hatchling=20?= =?UTF-8?q?=E2=86=92=20uv=5Fbuild?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- {{cookiecutter.project_slug}}/CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_slug}}/CLAUDE.md b/{{cookiecutter.project_slug}}/CLAUDE.md index 3e37f9d..35b2972 100644 --- a/{{cookiecutter.project_slug}}/CLAUDE.md +++ b/{{cookiecutter.project_slug}}/CLAUDE.md @@ -15,7 +15,7 @@ This is a Python library package. ## Stack - Package manager: uv -- Build backend: hatchling +- Build backend: uv_build - Linting/formatting: ruff - Type checking: pyright - Testing: pytest From 7e13be589a2424e1f4f6375c83b59dc29e652722 Mon Sep 17 00:00:00 2001 From: Alexis Date: Fri, 5 Dec 2025 17:01:02 +0100 Subject: [PATCH 4/4] Refactor: Move content to AGENTS.md, source from CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md now contains only `@AGENTS.md` reference, keeping AGENTS.md as the single source of truth for agent instructions. Applied to both the repository root and the cookiecutter template. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- AGENTS.md | 59 +++++++++++++++++++++++ CLAUDE.md | 62 +------------------------ {{cookiecutter.project_slug}}/AGENTS.md | 49 +++++++++++++++++++ {{cookiecutter.project_slug}}/CLAUDE.md | 52 +-------------------- 4 files changed, 110 insertions(+), 112 deletions(-) create mode 100644 AGENTS.md create mode 100644 {{cookiecutter.project_slug}}/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c99eea1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# AGENTS.md + +## Project Overview + +A Cookiecutter template for Python packages, supporting both CLI and library project types. Generates projects with uv, ruff, pyright, and pytest pre-configured. It also comes with GitHub Actions workflows configured for the project. + +This template is opinionated and enforces recommended practices when creating new Python projects. + +## Repository Structure + +- `{{cookiecutter.project_slug}}/` - Template directory (rendered by Cookiecutter) +- `cookiecutter.json` - Template variables and prompts +- `hooks/` - Pre/post generation scripts + - `pre_gen_project.py` - Validates inputs (namespace, slug, entry point) + - `post_gen_project.py` - Cleans up unused files based on options + +## Key Template Variables + +| Variable | Purpose | +|----------|---------| +| `project_name` | Human-readable name | +| `project_slug` | Pip/repo name (auto-derived) | +| `project_namespace_import` | Optional namespace (e.g., `company.tools`) | +| `repo_type` | `CLI` or `library` | +| `entry_point` | CLI command name (CLI only) | + +## Testing Changes + +Generate a test project to verify template changes: + +```bash +# Generate in temp directory +uvx cookiecutter -o /tmp . + +# Or with specific options (no prompts) +uvx cookiecutter --no-input -o /tmp . project_name="Test Project" repo_type="CLI" +``` + +Then verify the generated project: + +```bash +cd /tmp/test-project +make lint && make test +``` + +## Verification + +When modifying the template: + +1. Ensure Jinja2 syntax is valid in template files +2. Test both `CLI` and `library` repo types +3. Test with and without `project_namespace_import` +4. Verify generated project passes `make lint && make test` + +## Commit Messages + +- Summary line: max 50 chars (hard limit 72) +- Body lines: max 72 chars +- Use Markdown formatting in description diff --git a/CLAUDE.md b/CLAUDE.md index 0783b26..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,61 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -A Cookiecutter template for Python packages, supporting both CLI and library project types. Generates projects with uv, ruff, pyright, and pytest pre-configured. It also comes with GitHub Actions workflows configured for the project. - -This template is opinionated and enforces recommended practices when creating new Python projects. - -## Repository Structure - -- `{{cookiecutter.project_slug}}/` - Template directory (rendered by Cookiecutter) -- `cookiecutter.json` - Template variables and prompts -- `hooks/` - Pre/post generation scripts - - `pre_gen_project.py` - Validates inputs (namespace, slug, entry point) - - `post_gen_project.py` - Cleans up unused files based on options - -## Key Template Variables - -| Variable | Purpose | -|----------|---------| -| `project_name` | Human-readable name | -| `project_slug` | Pip/repo name (auto-derived) | -| `project_namespace_import` | Optional namespace (e.g., `company.tools`) | -| `repo_type` | `CLI` or `library` | -| `entry_point` | CLI command name (CLI only) | - -## Testing Changes - -Generate a test project to verify template changes: - -```bash -# Generate in temp directory -uvx cookiecutter -o /tmp . - -# Or with specific options (no prompts) -uvx cookiecutter --no-input -o /tmp . project_name="Test Project" repo_type="CLI" -``` - -Then verify the generated project: - -```bash -cd /tmp/test-project -make lint && make test -``` - -## Verification - -When modifying the template: - -1. Ensure Jinja2 syntax is valid in template files -2. Test both `CLI` and `library` repo types -3. Test with and without `project_namespace_import` -4. Verify generated project passes `make lint && make test` - -## Commit Messages - -- Summary line: max 50 chars (hard limit 72) -- Body lines: max 72 chars -- Use Markdown formatting in description +@AGENTS.md diff --git a/{{cookiecutter.project_slug}}/AGENTS.md b/{{cookiecutter.project_slug}}/AGENTS.md new file mode 100644 index 0000000..b5bfbb7 --- /dev/null +++ b/{{cookiecutter.project_slug}}/AGENTS.md @@ -0,0 +1,49 @@ +# AGENTS.md + +## Project Overview + +{{ cookiecutter.project_description }} + +{%- if cookiecutter.repo_type == 'CLI' %} +This is a command-line application with entry point `{{ cookiecutter.entry_point }}`. +{%- else %} +This is a Python library package. +{%- endif %} + +## Stack + +- Package manager: uv +- Build backend: uv_build +- Linting/formatting: ruff +- Type checking: pyright +- Testing: pytest +- CI: GitHub Actions (lint, test, release{%- if cookiecutter.documentation != 'none' %}, docs{%- endif %}) + +## Commands + +Use Makefile targets, not tool commands directly: + +- `make format` - Fix formatting issues +- `make lint` - Run all static checks (ruff, pyright) +- `make test` - Run tests with coverage +- `make doc` - Generate documentation +- `make build` - Build the package +{%- if cookiecutter.entry_point %} +- `make run` - Run the CLI (use `ARGS="..."` for arguments) +{%- endif %} + +## Verification + +Run `make lint && make test` before committing. + +## Commit Messages + +- Summary line: max 50 chars (hard limit 72) +- Body lines: max 72 chars +- Use Markdown formatting in description +- Reference issues where relevant (e.g., `See #123`) + +## Project Layout + +- `src/{{ cookiecutter.__project_import.replace('.', '/') }}/` - Source code +- `test/` - Test files diff --git a/{{cookiecutter.project_slug}}/CLAUDE.md b/{{cookiecutter.project_slug}}/CLAUDE.md index 35b2972..43c994c 100644 --- a/{{cookiecutter.project_slug}}/CLAUDE.md +++ b/{{cookiecutter.project_slug}}/CLAUDE.md @@ -1,51 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -{{ cookiecutter.project_description }} - -{%- if cookiecutter.repo_type == 'CLI' %} -This is a command-line application with entry point `{{ cookiecutter.entry_point }}`. -{%- else %} -This is a Python library package. -{%- endif %} - -## Stack - -- Package manager: uv -- Build backend: uv_build -- Linting/formatting: ruff -- Type checking: pyright -- Testing: pytest -- CI: GitHub Actions (lint, test, release{%- if cookiecutter.documentation != 'none' %}, docs{%- endif %}) - -## Commands - -Use Makefile targets, not tool commands directly: - -- `make format` - Fix formatting issues -- `make lint` - Run all static checks (ruff, pyright) -- `make test` - Run tests with coverage -- `make doc` - Generate documentation -- `make build` - Build the package -{%- if cookiecutter.entry_point %} -- `make run` - Run the CLI (use `ARGS="..."` for arguments) -{%- endif %} - -## Verification - -Run `make lint && make test` before committing. - -## Commit Messages - -- Summary line: max 50 chars (hard limit 72) -- Body lines: max 72 chars -- Use Markdown formatting in description -- Reference issues where relevant (e.g., `See #123`) - -## Project Layout - -- `src/{{ cookiecutter.__project_import.replace('.', '/') }}/` - Source code -- `test/` - Test files +@AGENTS.md