- Add CLAUDE.md with consolidated project guidelines - Remove .cursor/rules/*.mdc files - CLAUDE.md works with both Cursor and Claude Code
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:
- Summary - Brief overview of the changes
- Changes Made - List of specific modifications
- Testing - How changes were tested (unit tests, manual testing)
- 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
gcloudCLI is fine for investigation and debugging - Temporary changes via
gcloudCLI 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
gcloudor Console changes as the final state
Workflow
- Make changes in
infrastructure/ - Run
pulumi previewand verify the output - Run
pulumi upto 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:
- Unit tests (karaoke_gen package) with coverage check
- Backend unit tests
- E2E integration tests with emulators (auto-starts/stops emulators)
Pre-commit Checklist
make testpasses- Version in
pyproject.tomlhas been bumped
Do not commit or push code that fails tests. Fix any test failures before proceeding.