Skip to content

CLAUDE.md

Latest commit

 

History

History
93 lines (63 loc) · 3.86 KB

CLAUDE.md

File metadata and controls

93 lines (63 loc) · 3.86 KB
Raw

AGENTS.md

First-time setup

If a placeholder/ directory still exists in this repo, the template has not been initialized yet. Before doing any other work:

  1. Run bin/customize.sh <package-name> with appropriate --author, --email, --description, and --repository-url flags (see ### Setup Your Plugin in README.md for details). This handles the directory rename, pyproject.toml/.releaserc.yaml edits, and from placeholder. import rewrites in one shot.
  2. Verify with uv venv && source .venv/bin/activate && uv sync --all-extras && tox.
  3. Remove the template-only files: rm CONTRIBUTING.md bin/customize.sh.
  4. Delete this ## First-time setup section from both CLAUDE.md and AGENTS.md. It only applies to fresh-template repos and would be misleading once the placeholder is gone.

Must read README.md first.

This project uses the mloda framework. Assume any given task is related to mloda.

Environment

source .venv/bin/activate

Dependencies

Use uv to install dependencies:

uv sync --all-extras

Running checks

Use tox to run all checks:

tox

Run checks from the project virtualenv:

source .venv/bin/activate && tox

tox is the required final verification step after code or dependency changes. Running only pytest is not sufficient for completion.

Run individual checks

pytest
ruff format --check --line-length 120 .
ruff check .
mypy --strict --ignore-missing-imports .
bandit -c pyproject.toml -r -q .

Commit messages

Use Conventional Commit format for all commits so semantic versioning/release tooling can parse intent. Do not include Co-Authored-By lines or any other mention of AI agents in commit messages.

Examples:

  • fix: handle empty feature set
  • chore(deps): bump mloda to 0.4.6

Claude Code Skills

The mloda-registry provides Claude Code skills that assist with plugin development:

When helping with FeatureGroups, ComputeFrameworks, or Extenders, leverage these skills for pattern guidance and best practices.

Consider generating project-specific skills for your own plugin repository to provide tailored AI assistance for your implementation patterns and conventions.

Project Practices

tox is the gate. It runs pytest, then ruff format --check, ruff check, mypy --strict --ignore-missing-imports, and bandit. All of these must pass before a PR is mergeable. A separate tox -e security environment runs pip-audit for CVE scanning.

  • Python: supported range is >=3.10. The default tox env is python310.
  • Type hints: use modern forms (list[str], dict[str, int], X | None).
  • Formatting: ruff format with line length 120.
  • Tests: every new feature or bug fix must come with tests; follow the patterns in the existing tests/ and placeholder/.../tests/ trees.
  • Supply chain: [tool.uv] exclude-newer = "7 days" in pyproject.toml defers new dependency releases by 7 days; exclude-newer-package pins mloda, mloda-testing, and mloda-registry to a longer window. Do not edit these without a reason.
  • Commits: use Conventional Commits (feat:, fix:, chore:, docs:, test:, refactor:, style:, ci:, build:, perf:). semantic-release computes the next version: feat: triggers a minor bump, all other types trigger a patch bump (see .releaserc.yaml).

Issue Creation

When filing a GitHub issue (via gh issue create or otherwise), follow the structure in .github/ISSUE_TEMPLATE/issue.yml:

  • Summary in one sentence
  • Reproduction (for bugs) or motivation (for features)
  • Code pointers if relevant (file:line)
  • Definition of done if scoped (what counts as complete)

Issues that meet this bar are eligible for the good first issue label without further sharpening.