Files
karaoke-gen/CLAUDE.md
T
Andrew Beveridge cceb4ec1d2 Migrate Cursor rules to CLAUDE.md for cross-tool compatibility
- Add CLAUDE.md with consolidated project guidelines
- Remove .cursor/rules/*.mdc files
- CLAUDE.md works with both Cursor and Claude Code
2025-12-25 14:41:37 -05:00

2.8 KiB

Project Guidelines for AI Assistants

This document contains guidelines and rules for AI assistants working on this codebase.

Branching Workflow

Never commit directly to main. Always work on a feature branch.

Create descriptive branch names like feature/add-discord-notifications, fix/audio-sync-issue, or refactor/cleanup-api-routes.

Creating a Pull Request

Once all changes are complete, tests pass, and commits are pushed, create a PR with:

  1. Summary - Brief overview of the changes
  2. Changes Made - List of specific modifications
  3. Testing - How changes were tested (unit tests, manual testing)
  4. Related Issues - Reference any GitHub issues (e.g., "Fixes #123")

Only merge after review and CI checks pass.

Infrastructure Changes

All Google Cloud infrastructure (IAM, Cloud Storage, Cloud Run, Secret Manager, Artifact Registry, etc.) must be managed via Pulumi IaC in the infrastructure/ folder.

Rules

  • Reading/querying with gcloud CLI is fine for investigation and debugging
  • Temporary changes via gcloud CLI or Console are acceptable for urgent fixes or experimentation, but must be cleaned up and properly codified in the IaC afterward
  • Permanent changes must go through Pulumi — never leave gcloud or Console changes as the final state

Workflow

  1. Make changes in infrastructure/
  2. Run pulumi preview and verify the output
  3. Run pulumi up to apply

Authentication Issues

If you encounter any authentication issues with gcloud or pulumi (e.g., expired tokens, permission errors), stop and notify the user so they can run the appropriate auth commands in their external terminal:

gcloud auth login
gcloud auth application-default login

Do not attempt to work around auth issues or make assumptions about credentials.

Version Management

When committing and pushing changes, always bump the patch version in pyproject.toml.

The version is located at tool.poetry.version in pyproject.toml. For example, if the current version is 0.70.3, bump it to 0.70.4.

This ensures every commit pushed to the repository has a unique version number for tracking and deployment purposes.

Testing Requirements

Before committing and pushing ANY changes, you MUST run the full test suite.

Test Command

make test

This is the only command you need. It runs all tests in order and fails fast if any test fails:

  1. Unit tests (karaoke_gen package) with coverage check
  2. Backend unit tests
  3. E2E integration tests with emulators (auto-starts/stops emulators)

Pre-commit Checklist

  • make test passes
  • Version in pyproject.toml has been bumped

Do not commit or push code that fails tests. Fix any test failures before proceeding.