tom/claude-code-commands
1
0
Fork 0
Code Issues Pull requests Activity

Initial commit

Browse source
This commit is contained in:
Tom Foster 2025-08-04 00:18:37 +01:00
commit 6ae1390324
5 changed files with 700 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

71
LICENSE Normal file
View file

@ -0,0 +1,71 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
**1. Definitions.**
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
**2. Grant of Copyright License.**
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
**3. Grant of Patent License.**
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
**4. Redistribution.**
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
**5. Submission of Contributions.**
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
**6. Trademarks.**
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
**7. Disclaimer of Warranty.**
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
**8. Limitation of Liability.**
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
**9. Accepting Warranty or Additional Liability.**
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS

80
README.md Normal file
View file

@ -0,0 +1,80 @@
# 💻 Claude Code Commands
**Slash commands for Claude Code and similar CLI coding assistants.**
A collection of shortcuts and custom workflows accessible via `/` commands.
1. [⚡ What are Slash Commands?](#-what-are-slash-commands)
2. [🔧 Compatibility](#-compatibility)
3. [📦 Setup](#-setup)
4. [🚀 Usage](#-usage)
1. [Creating Custom Commands](#creating-custom-commands)
2. [Best Practices for Command Design](#best-practices-for-command-design)
5. [📄 License](#-license)
## ⚡ What are Slash Commands?
Slash commands are shortcuts that trigger specific behaviours in your CLI coding assistant. Type `/`
followed by a command name to execute pre-configured instructions.
When you invoke a command, it:
- Loads custom instructions from the corresponding `.md` file
- Configures the assistant's behaviour for that specific task
- Applies any specialised prompts or constraints
- Executes the workflow you've defined
## 🔧 Compatibility
Designed for Claude Code and CLI coding assistants that support Markdown-based slash commands.
**Note:** As of the time of writing, the Gemini CLI does not have a similar slash command feature.
## 📦 Setup
1. **Fork this repository** to your own Git account
2. **Clone to `~/.claude/commands`**:
```bash
git clone ssh://git@git.tomfos.tr/tom/claude-code-commands.git ~/.claude/commands
```
This gives you:
- Your own command collection to customise
- Version control for your modifications
- Easy syncing across machines
## 🚀 Usage
Each `.md` file defines an available command. The filename determines the command name.
**Example**: `write-docs.md` → `/write-docs`
Usage in Claude Code:
1. Type `/` followed by the command name
2. Press enter to load those instructions
3. The assistant adopts the command's behaviour
### Creating Custom Commands
Add a Markdown file with your instructions:
```markdown
# my-command.md
You are an expert at [specific task]. When invoked:
1. [First action]
2. [Second action]
3. [Report results]
```
### Best Practices for Command Design
1. **Single Purpose**: Each command should do one thing well
2. **Clear Instructions**: Be specific about what the command does
3. **Include Examples**: Show typical usage scenarios
4. **Handle Edge Cases**: Anticipate what might go wrong
## 📄 License
This project is licensed under the [Apache License 2.0](LICENSE).

379
framework.md Normal file
View file

@ -0,0 +1,379 @@
# Python Framework & Configuration Audit
Your primary task is to audit this project's configuration and ensure it aligns with modern Python
development best practices. You should either **create new configuration files** for a new project
or **intelligently modify existing ones** to meet these standards.
Do not blindly replace files. Your goal is to enforce a consistent, modern, and efficient
development environment. Always explain the changes you are making and why they align with the
framework principles outlined below.
## Initial Project Analysis
**Before making any changes, gather project information:**
1. **Check if this is a Git repository and get remote URL:**
```bash
git remote -v
```
Use this information to populate the `[project.urls]` section in `pyproject.toml`.
2. **Examine existing project structure:**
- Look for existing `pyproject.toml`, `setup.py`, `requirements.txt`, or `poetry.lock`
- Check for existing source code to understand the project name and structure
- Look for existing tests to understand testing framework (pytest, unittest, etc.)
- **Read `README.md`** if it exists - this often contains the best description of what the
project does and can inform the `name`, `description`, and `classifiers` in `pyproject.toml`
3. **Identify the project type:**
- Is it a library (should be installable)?
- Is it an application (needs entry points)?
- Does it need containerisation?
## Guiding Principles
Before looking at the specific files, understand the philosophy behind this framework:
- **Speed & Efficiency:** We prioritise fast dependency management, builds, and CI/CD pipelines.
Tools like `uv` and multi-stage Docker builds are central to this.
- **Consolidation:** We use `pyproject.toml` as the single source of truth for project metadata,
dependencies, and tool configuration (linting, formatting, etc.).
- **Clarity & Consistency:** Code and configuration should be easy to read and maintain. Comments
in configuration files should explain non-obvious choices.
- **Automation:** The CI/CD workflow automates quality assurance and should be reliable whilst
providing fast feedback.
## 1. Project & Tooling Configuration (`pyproject.toml`)
The `pyproject.toml` file is the backbone of the project's structure.
**Your Task:**
- If no `pyproject.toml` exists, create one based on the template below.
- If one exists, audit it. Ensure it uses `ruff` for both linting and formatting, configures project
metadata under the `[project]` table, and uses the `[tool.uv]` section for dependency management.
- Pay close attention to the `ruff` linting codes. The template contains comments explaining the
currently selected ruleset. If the project's file has outdated or conflicting codes, update them
and explain the change.
- **IMPORTANT:** Replace placeholder values with actual project information gathered from your
initial analysis.
```toml
[project]
# Replace with actual project name (use directory name if unclear)
name = "your-project-name"
version = "0.1.0"
# Replace with appropriate description based on project contents
description = "A brief description of what this project does."
readme = "README.md"
# Choose appropriate licence (MIT, Apache-2.0, GPL-3.0, etc.)
license = { text = "MIT" }
# Replace with actual author information
authors = [{ name = "Your Name", email = "your.email@example.com" }]
maintainers = [{ name = "Your Name", email = "your.email@example.com" }]
# Adjust Python version based on project requirements
requires-python = ">=3.11"
classifiers = [
"Development Status :: 3 - Alpha", # Or 4 - Beta, 5 - Production/Stable
"License :: OSI Approved :: MIT License", # Match your chosen licence
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
]
# Adjust dependencies based on actual project requirements
dependencies = [
# Example common dependencies - replace with actual needs:
# "fastapi>=0",
# "requests>=2",
# "pydantic>=2",
# "pytz>=2025",
"uvicorn[standard]>=0",
]
[project.urls]
# Replace with actual repository URL from `git remote -v`
Homepage = "https://github.com/username/repository-name"
# Add additional URLs as appropriate:
# "Bug Reports" = "https://github.com/username/repository-name/issues"
# "Source" = "https://github.com/username/repository-name"
# "Documentation" = "https://your-project-docs.readthedocs.io/"
[dependency-groups]
dev = ["ruff>=0", "uv>=0"]
[tool.uv]
package = true
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
# Only include if this is an application with CLI entry points
[project.scripts]
# Replace with actual script name and module path
your-cli-command = "your_package.__main__:main"
[tool.setuptools]
packages = { find = {} }
[tool.ruff]
cache-dir = "/tmp/.ruff_cache"
fix = true
line-length = 100
preview = true
show-fixes = false
# Adjust target version to match requires-python
target-version = "py311"
unsafe-fixes = true
[tool.ruff.format]
line-ending = "auto"
skip-magic-trailing-comma = false
[tool.ruff.lint]
fixable = ["ALL"]
ignore = [
"ANN401", # use of Any type
"BLE001", # blind Exception usage
"COM812", # missing trailing comma
"CPY", # flake8-copyright
"FBT", # boolean arguments
"PLR0912", # too many branches
"PLR0913", # too many arguments
"PLR0915", # too many statements
"PLR0917", # too many positional arguments
"PLR6301", # method could be static
"RUF029", # async methods that don't await
"S104", # binding to all interfaces
"S110", # passed exceptions
"TRY301", # raise inside try block
]
select = ["ALL"]
unfixable = [
"F841", # local variable assigned but never used
"RUF100", # unused noqa comments
"T201", # don't strip print statement
]
[tool.ruff.lint.isort]
combine-as-imports = true
required-imports = ["from __future__ import annotations"]
[tool.ruff.lint.pydocstyle]
convention = "google"
```
## 2. Development Environment Setup
**Essential Commands for Project Setup:**
1. **Install `uv` (if not already installed):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Initialise virtual environment and install dependencies:**
```bash
uv sync --all-groups
```
## 3. Containerisation (`Dockerfile`)
**Create this file only if the project needs containerisation** (web services, deployable applications).
Our containerisation strategy focuses on creating minimal, secure, and efficient runtime images.
**Your Task:**
- Audit or create a `Dockerfile` that follows a multi-stage build process.
- The fundamental pattern is:
1. A `build` stage, based on a full Python image, where dependencies are compiled using `uv`.
2. A final, minimal `runtime` stage (e.g., `python-slim`) where the virtual environment from the
`build` stage is copied over.
- Ensure the `PATH` environment variable in the final stage is correctly prepended with the virtual
environment's `bin` directory. This ensures that `python` commands execute from within the virtual
environment by default.
- **Replace project-specific details** with actual project information.
```dockerfile
# Build stage using uv with a frozen lockfile and dependency caching
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS uv
WORKDIR /app
# Enable bytecode compilation and copy mode
ENV UV_COMPILE_BYTECODE=1 \
UV_LINK_MODE=copy
# Install dependencies using the lockfile
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --frozen --no-dev --no-editable --no-install-project
# Install the project in a second layer
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --frozen --no-dev --no-editable
# Prepare runtime image
FROM python:3.13-slim-bookworm AS runtime
WORKDIR /app
# Install minimal system dependencies and create runtime user
# Adjust system packages based on your project's needs
RUN apt-get update && apt-get install -y curl \
&& rm -rf /var/lib/apt/lists/* \
&& groupadd -g 1000 appuser \
&& useradd -u 1000 -g 1000 -m appuser
# Copy only the virtual environment from the build stage
COPY --from=uv /app/.venv /app/.venv
# Switch to non-root user
USER appuser
# Set environment variables for runtime
ENV PATH="/app/.venv/bin:$PATH" \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1
# Replace with appropriate startup command for your application
ENTRYPOINT ["uvicorn", "your_package", "--host", "0.0.0.0", "--port", "80"]
# Add health check for web services
# HEALTHCHECK --interval=30s --timeout=10s --retries=3 CMD curl -f http://localhost:80/health || exit 1
```
## 4. Continuous Integration
The CI workflow automates our quality checks. The goal is fast, parallel execution.
### For Forgejo (`.forgejo/workflows/docker-build.yml`)
- Audit or create a CI file that defines jobs for linting, testing, and building.
- Ensure the jobs are configured to run in parallel where possible.
- The workflow should leverage caching mechanisms for dependencies to speed up subsequent runs.
- The "lint" stage should simply run `ruff check .` and `ruff format --check .`.
- The "test" stage should run the project's test suite, likely using `pytest`.
```yaml
name: Docker Build
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
env:
REGISTRY: git.tomfos.tr # Replace with your registry URL
jobs:
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Add uv to PATH
run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Set up Python
run: uv python install
- name: Install dependencies
run: uv sync
- name: Run ruff check
run: uv run ruff check .
- name: Run ruff format
run: uv run ruff format --check .
test:
name: Test
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Add uv to PATH
run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Set up Python
run: uv python install
- name: Install dependencies
run: uv sync
- name: Run tests
run: uv run pytest --cov
build-and-push:
name: Build and Push
runs-on: ubuntu-latest
needs: [lint, test]
if: github.event_name == 'push'
permissions:
contents: read
packages: write
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: https://github.com/docker/setup-buildx-action@v3
- name: Log in to Container Registry
uses: https://github.com/docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ gitea.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Determine image metadata
id: meta
uses: https://github.com/docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ gitea.repository }}
tags: |
type=ref,event=branch
type=ref,event=branch,suffix=-{{sha}}
type=raw,value=latest,enable={{is_default_branch}}
- name: Build and push Docker image
uses: https://github.com/docker/build-push-action@v6
with:
context: .
file: ./Dockerfile
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ gitea.repository }}:build-cache
cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ gitea.repository }}:build-cache,mode=max
```
## How to Apply These Instructions
### For a New Project
1. **Gather Information:** Run `git remote -v` to get repository URL, examine directory structure
2. **Create Configuration:** Use the templates above, replacing placeholders with actual project details
3. **Setup Environment:** Run `uv sync` to create virtual environment and install dependencies
4. **Announce:** "Setting up the project with modern Python development framework"
### For an Existing Project
1. **Audit Current Setup:** Compare existing files against framework guidelines
2. **Preserve Valid Configuration:** Don't discard project-specific settings that don't conflict
3. **Migrate Dependencies:** If `requirements.txt` exists, migrate to `pyproject.toml` dependency groups
4. **Update Tools:** Ensure `ruff` is used for both linting and formatting
5. **Explain Changes:** Clearly list proposed changes and justification for each
### Migration from Legacy Tools
- **From `setup.py`:** Move metadata to `[project]` table in `pyproject.toml`
- **From `requirements.txt`:** Move to `dependencies` and `[dependency-groups]` in `pyproject.toml`
- **From `black` + `flake8`/`pylint`:** Replace with `ruff` for unified linting and formatting
- **From `pip`:** Migrate to `uv` for faster dependency management

68
review-docstrings.md Normal file
View file

@ -0,0 +1,68 @@
# Review and Update Docstrings
You are an expert programmer tasked with reviewing and improving docstrings in a Python codebase.
Your goal is to ensure every docstring is accurate, clear, and adheres to the specified standards.
**Primary Directive:** All docstrings MUST be written in UK English (e.g. use initialise, colour,
behaviour).
## Docstring Standards
All docstrings must be "Google-style," characterised by clear, indented sections for arguments,
return values, and exceptions. If a function or method has no arguments, does not return a value,
or does not explicitly raise exceptions, the corresponding "Args," "Returns," or "Raises" sections
can be omitted.
Review and enhance docstrings following the structure in this example:
```python
"""Handles user authentication and session management.
This module provides the main API for the web frontend to authenticate
users, create sessions, and validate session tokens. It interacts
directly with the user database and the caching layer.
It uses a token-based (JWT) authentication strategy. Password hashing is
handled by a separate security utility, and rate limiting is managed by
an upstream gateway.
See Also:
/path/to/project/security/hashing.py
/path/to/project/docs/auth_flow.md
"""
class AuthenticationError(Exception):
"""Raised for authentication failures."""
pass
class Authenticator:
"""Handles user authentication and token generation.
Provides methods to verify credentials and manage JWTs for sessions.
"""
def __init__(self, secret_key: str):
"""Initialises the authenticator.
Args:
secret_key: The secret key for signing JWTs.
"""
self.secret_key = secret_key
def login(self, username: str, password: str) -> str:
"""Authenticates a user and returns their JWT.
Args:
username: The user's username.
password: The user's password.
Returns:
The JWT for the authenticated session.
Raises:
AuthenticationError: If the username or password is incorrect.
"""
if not self._verify_credentials(username, password):
raise AuthenticationError("Invalid username or password.")
return self._generate_token(username)
```

102
uv-linting.md Normal file
View file

@ -0,0 +1,102 @@
# UV and Ruff Development Loop
A framework for iterative development using `uv` for dependency management and `ruff`
for formatting and linting. This combination provides a fast and efficient development
workflow.
## Development Guidelines
### Project Configuration
- Use centralised project configuration in `pyproject.toml` whenever possible
- Store all tool configurations (ruff, pytest, mypy, etc.) in `pyproject.toml`
- Keep dependency specifications and project metadata in `pyproject.toml`
### Dependency Management
- Manage all dependencies exclusively with `uv`
- Use `uv add <package>` to add new dependencies (e.g. `uv add fastapi`)
- Use `uv add --dev <package>` for development dependencies (e.g. `uv add --dev pytest`)
- Use `uv remove <package>` to remove dependencies
- Never manually edit `uv.lock` - let `uv` manage it
### Python Development Principles
Follow KISS, DRY, YAGNI, SOLID, and Zen Of Python software engineering principles when
writing and refactoring code.
### Common UV Commands
```bash
# Add a new dependency
uv add fastapi
# Add a development dependency
uv add --dev pytest
# Remove a dependency
uv remove requests
# Install all dependencies
uv sync
# Run a command in the virtual environment
uv run python script.py
```
## Session Start
These commands should be run once at the beginning of each development session to ensure
your tools and dependencies are up to date.
### 1. Update `uv`
Ensure you have the latest version of the `uv` tool.
```bash
uv self update
```
### 2. Update Dependencies
Update all dependencies in your `pyproject.toml` to the latest versions and update the
`uv.lock` file.
```bash
uv lock -U
```
## Iterative Development Process
These commands are run repeatedly as you write and modify your code.
### 1. Format Code
Automatically format your code using `ruff`.
```bash
uv run ruff format
```
### 2. Check for Linting Issues
Check for any linting errors or style issues.
```bash
uv run ruff check
```
### 3. Resolve Linting Issues
Review the output from `ruff check` and address any reported issues by refactoring
your code to follow best practices.
**Guidelines for resolving lints:**
- Prefer refactoring code over suppressing warnings
- Use `#noqa` comments sparingly (valid use case: avoiding circular imports)
- Update `pyproject.toml` configuration if specific rules need to be disabled project-wide
- Clean up after yourself - remove unused imports, variables, and functions
- Follow the development principles outlined above when making changes
After fixing issues, repeat the format and check commands until no issues remain.