Skip to content

CLAUDE.md

Latest commit

 

History

History
799 lines (567 loc) · 24.6 KB

CLAUDE.md

File metadata and controls

799 lines (567 loc) · 24.6 KB
Raw

Claude Code Project Guidelines

User Settings: Global Claude configuration at ~/.claude/CLAUDE.md (user-level)

This file contains all project guidelines: baseline standards and project-specific configurations.

Template Feedback Requirement (CRITICAL)

This project was generated from the cookiecutter-python-template using cruft.

MANDATORY: When working on this project, if you identify any issue that should have been addressed in the template (missing files, incorrect configurations, documentation gaps, tooling issues, etc.), you MUST:

  1. Add the feedback to docs/template_feedback.md
  2. Include:
    • Issue: Clear description of what's wrong or missing
    • Context: How you discovered it
    • Suggested Fix: What the template should do differently
    • Priority: Critical / High / Medium / Low

This feedback will be shared with the template team to improve the cookiecutter template for future projects.

Project Overview

Name: Audio Processor Description: Audio file conversion and processing for RAG content pipelines Author: Byron Williams byron@williamshome.family Repository: https://github.com/ByronWilliamsCPA/audio-processor Created: 2025-12-04

Technology Stack

  • Python: 3.12
  • Package Manager: UV
  • Code Quality: Ruff (linter/formatter), BasedPyright (type checker)
  • Testing: pytest, coverage
  • Security: Bandit, pip-audit
  • CLI Framework: Click
  • Documentation: MkDocs Material
  • Containerization: Docker

Core Development Standards

Essential Requirements

  • Code Quality: Ruff formatting (88 chars), Ruff linting (PyStrict-aligned), BasedPyright type checking (strict mode)
  • Security: GPG/SSH key validation, dependency scanning, encrypted secrets
  • Testing: Minimum 80% coverage, tiered testing approach
  • Git: Conventional commits, signed commits, feature branch workflow
  • Response-Aware Development: Assumption tagging and verification

Response-Aware Development (RAD)

Assumption Tagging Standards

When writing code, ALWAYS tag assumptions that could cause production failures:

# #CRITICAL: [category]: [assumption that could cause outages/data loss]
# #VERIFY: [defensive code required]
# Example: Payment processing, auth flows, concurrent writes

# #ASSUME: [category]: [assumption that could cause bugs]
# #VERIFY: [validation needed]
# Example: UI state, form validation, API responses

# #EDGE: [category]: [assumption about uncommon scenarios]
# #VERIFY: [optional improvement]
# Example: Browser compatibility, slow networks

Critical Assumption Categories (MANDATORY tagging)

  • Timing Dependencies: State updates, async operations, race conditions
  • External Resources: API availability, file existence, network connectivity
  • Data Integrity: Type safety at boundaries, null/undefined handling
  • Concurrency: Shared state, transaction isolation, deadlock potential
  • Security: Authentication, authorization, input validation
  • Payment/Financial: Transaction integrity, retry logic, rollback handling

Branch Workflow Requirement (CRITICAL)

NEVER work directly on the main branch. Always create a feature branch before making any code changes.

Before ANY Code Changes

# 1. Check current branch
git branch --show-current

# 2. If on main/master, create a feature branch FIRST
git checkout -b feat/{descriptive-slug}

# 3. Or for bug fixes
git checkout -b fix/{issue-or-description}

Branch Naming Convention

Task Type Branch Prefix Commit Type Version Impact
New feature feat/ feat: Minor (0.X.0)
Bug fix fix/ fix: Patch (0.0.X)
Breaking change feat/ or fix/ feat!: or fix!: Major (X.0.0)
Documentation docs/ docs: No release
Refactoring refactor/ refactor: No release
Performance perf/ perf: Patch (0.0.X)
Testing test/ test: No release
Chore/maintenance chore/ chore: No release

Branch Creation (MANDATORY)

ALWAYS create a new branch when:

  1. Starting ANY implementation task - Never commit directly to main or develop
  2. TODO item involves code changes - Each feature/fix should have its own branch
  3. Multiple independent features - Create separate branches for parallel work
  4. User explicitly requests a feature/fix - Branch immediately before coding

Note: The primary branch is main (not master).

Security-First Development (CRITICAL)

Claude MUST adopt a security-first approach in all development:

1. Proactive Security Suggestions

When working on this project, always suggest appropriate security measures:

  • Dependencies: Suggest vulnerability scanning (pip-audit)
  • APIs: Suggest authentication, rate limiting, input validation
  • Data: Suggest encryption at rest and in transit, access controls
  • Containers: Suggest image vulnerability scanning (Trivy)

2. Never Bypass Security Issues

  • ALL security findings from scanners (Semgrep, SonarQube, Bandit, Checkov) should be addressed, not dismissed
  • If a finding is a false positive, document WHY with inline comments
  • Use baseline files only for truly unavoidable exceptions with justification

3. Code Quality Standards

  • Treat linting warnings as errors to fix, not ignore
  • Address ALL type checker warnings, not just errors
  • Don't accumulate technical debt by deferring quality issues

4. Default to Strictest Settings

  • Security scanners: fail on HIGH/CRITICAL by default
  • Type checking: strict mode (already configured)
  • Linting: no ignored rules without documented reason

5. FIPS 140-2/140-3 Compliance

For deployment on FIPS-enabled systems (Ubuntu LTS with fips-updates, government systems, healthcare, finance):

Prohibited algorithms (will fail in FIPS mode):

  • MD5, MD4, SHA-1 (for security purposes)
  • DES, 3DES, RC2, RC4, Blowfish
  • Non-approved key exchange methods

Required patterns:

# ✗ WRONG - Will fail on FIPS systems
import hashlib
h = hashlib.md5(data)

# ✓ CORRECT - Non-security use is allowed
h = hashlib.md5(data, usedforsecurity=False)

# ✓ CORRECT - Use FIPS-approved algorithms for security
h = hashlib.sha256(data)

Check FIPS compatibility:

uv run python scripts/check_fips_compatibility.py --fix-hints

Problematic packages (need verification or replacement):

  • bcrypt → Use passlib with PBKDF2 or argon2-cffi
  • pycrypto → Use pycryptodome with FIPS mode
  • Verify cryptography version >= 3.4.6 with OpenSSL FIPS provider

Code Quality Standards

Type Checking with BasedPyright

BasedPyright replaces MyPy as the standard type checker (3-5x faster, stricter analysis):

  • Mode: strict (recommended)
  • Strict Inference: strictListInference, strictDictionaryInference, strictSetInference enabled
  • Configuration: In pyproject.toml under [tool.basedpyright]

PyStrict-Aligned Ruff Rules

Ruff configuration includes PyStrict-aligned rules for ultra-strict code quality:

  • BLE: Blind except detection (no bare except: or except Exception:)
  • EM: Error message best practices
  • SLF: Private member access violations
  • INP: Require __init__.py in packages
  • ISC: Implicit string concatenation
  • PGH: Deprecated type comments, blanket ignores
  • RSE: Raise statement best practices
  • TID: Banned imports, relative import rules
  • YTT: Python version checks
  • FA: Future annotations
  • T10: Debugger statements (no breakpoint(), pdb)
  • G: Logging format strings

File-Type Standards

  • Python: 88-char line length, comprehensive rule compliance
  • Markdown: 120-char line length, consistent formatting
  • YAML: 2-space indentation, 120-char line length
  • Validation: Pre-commit hooks enforce all standards

Claude Code Supervisor Role

Claude Code acts as the SUPERVISOR for all development tasks and MUST:

  1. Always Use TodoWrite Tool: Create and maintain TODO lists for ALL tasks
  2. Assign Tasks to Agents: Each TODO item should be assigned to a specialized agent
  3. Review Agent Work: Validate all agent outputs before proceeding
  4. Use Temporary Reference Files: Create .tmp- prefixed files in tmp_cleanup/ for complex tasks
  5. Maintain Continuity: Use reference files to preserve context across conversation compactions

Agent Assignment Patterns

- Security tasks       -> Security Agent (mcp__zen__secaudit)
- Code reviews         -> Code Review Agent (mcp__zen__codereview)
- Testing              -> Test Engineer Agent (mcp__zen__testgen)
- Documentation        -> Documentation Agent (mcp__zen__docgen)
- Debugging            -> Debug Agent (mcp__zen__debug)
- Analysis             -> Analysis Agent (mcp__zen__analyze)
- Refactoring          -> Refactor Agent (mcp__zen__refactor)

OpenSSF Best Practices Compliance

Required Project Files

All projects must have:

  • LICENSE - Open source license
  • SECURITY.md - Security policy and vulnerability reporting
  • CONTRIBUTING.md - Contribution guidelines
  • CHANGELOG.md - Release history
  • README.md - Project documentation

Quality Gates

  • All tests pass (80%+ coverage)
  • Ruff linting (no errors)
  • BasedPyright type checking
  • Security scans (no high/critical)
  • Pre-commit hooks pass

CVE Citation Policy

Any CHANGELOG entry that fixes a security vulnerability MUST include the CVE ID if one has been assigned. Format: - fix(security): resolve CVE-YYYY-NNNNN: <brief description>

If no CVE has been assigned at release time, record the GitHub Security Advisory ID and update the entry when a CVE is allocated.

Development Philosophy

Security First -> Quality Standards -> Documentation -> Testing -> Collaboration

Core Principles

  1. Security First: Always validate keys, encrypt secrets, scan dependencies
  2. Reuse First: Check existing repositories for solutions before building new code
  3. Configure, Don't Build: Prefer configuration and orchestration over custom implementation
  4. Quality Standards: Maintain consistent code quality across all projects
  5. Documentation: Keep documentation current and well-formatted
  6. Testing: Maintain high test coverage and run tests before commits
  7. Collaboration: Use consistent Git workflows and clear commit messages

Pre-Commit Checklist

Before committing ANY changes, ensure:

  • Working on appropriate feature branch (not main/develop)
  • Branch follows {type}/{descriptive-slug} convention
  • TodoWrite used for task tracking
  • File-specific linter has been run and passes
  • Pre-commit hooks execute successfully
  • No linting warnings or errors remain
  • Code formatting is consistent with project standards
  • Security scanning shows no vulnerabilities

Project-Specific Configuration

Project Requirements

Coverage & Quality:

  • Test coverage: Minimum 80%
  • All linters must pass: uv run ruff check ., uv run basedpyright src/
  • Security scans: uv run bandit -r src, uv run pip-audit

Project Planning Documents

First-Time Setup: If planning documents show "Awaiting Generation", see the Project Setup Guide.

Planning Documents (in docs/planning/):

References:

Quick Start

# 1. Generate planning documents
/plan <your project description>

# 2. Synthesize into project plan
"Synthesize my planning documents into a project plan"

# 3. Review docs/planning/PROJECT-PLAN.md

# 4. Start development
/git/milestone start feat/phase-0-foundation

Using Planning Documents

# Load context for a task
Load from project-vision.md sections 2-3 and adr/adr-001-*.md,
then implement [feature] per tech-spec.md section [X].

# Validate code against specs
Review this code against tech-spec.md section 6 (security).

# Check phase progress
Review PROJECT-PLAN.md Phase 1 deliverables and update status.

Quick Start Commands

# Initial setup
uv sync --all-extras
uv run pre-commit install

# Development cycle
uv run pytest -v                           # Run tests
uv run pytest --cov=src --cov-report=html # With coverage
uv run ruff format .                       # Format code
uv run ruff check . --fix                  # Lint and fix
uv run basedpyright src/                   # Type check

# Before commit (all must pass)
uv run pytest --cov=src --cov-fail-under=80
uv run ruff check .
uv run basedpyright src/
uv run bandit -r src
pre-commit run --all-files

# Documentation
uv run mkdocs serve                        # Local preview
uv run mkdocs build                        # Build static site
# Docker
docker-compose up -d                       # Start dev environment
docker build -t audio_processor .  # Build production image

Project Structure

src/audio_processor/
├── __init__.py              # Package initialization
├── cli.py                   # CLI entry point
├── core/                    # Core business logic
│   ├── __init__.py
│   ├── config.py           # Configuration (Pydantic Settings)
│   └── exceptions.py       # Centralized exception hierarchy
├── middleware/              # Middleware components
│   └── __init__.py
└── utils/                   # Utilities
    ├── __init__.py
    └── logging.py          # Structured logging with correlation

tests/
├── unit/                   # Unit tests
├── integration/            # Integration tests
├── conftest.py            # Pytest fixtures
└── test_example.py        # Example tests

docs/                       # MkDocs documentation
├── index.md               # Home page
└── ...                    # Additional docs

Code Conventions

Project-Specific Patterns:

  • Configuration: Use Pydantic Settings with .env files
  • Logging: Structured logging via src/audio_processor/utils/logging.py
  • Error Handling: Custom exceptions in src/audio_processor/core/exceptions.py

Exception Hierarchy

Use the centralized exception hierarchy for consistent error handling:

from audio_processor.core.exceptions import (
    ValidationError,
    ResourceNotFoundError,
    ConfigurationError,
    AuthenticationError,
    AuthorizationError,
    ExternalServiceError,
    APIError,
    DatabaseError,
    BusinessLogicError,
)

# Raise with context
raise ValidationError(
    "Invalid email format",
    field="email",
    value=user_input,
)

# Handle in API endpoints
try:
    process_data(input_data)
except ValidationError as e:
    return {"error": str(e), "details": e.to_dict()}

Exception Types:

Exception Use Case
ConfigurationError Missing/invalid config
ValidationError Input validation failures
ResourceNotFoundError Missing resources (404)
AuthenticationError Auth failures (401)
AuthorizationError Permission denied (403)
ExternalServiceError Third-party service failures
APIError External API errors
DatabaseError Database operation errors
BusinessLogicError Domain rule violations

Docstrings (Google Style):

def process_data(input_path: str, max_rows: int = 1000) -> dict[str, Any]:
    """Process data from input file.

    Args:
        input_path: Path to input file
        max_rows: Maximum rows to process (default: 1000)

    Returns:
        Dictionary with processing results

    Raises:
        FileNotFoundError: If input file doesn't exist
        ValueError: If file format is invalid
    """

Configuration Management

Use Pydantic Settings for environment-based configuration:

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    project_name: str = "Audio Processor"
    log_level: str = Field(default="INFO", env="LOG_LEVEL")
    debug: bool = Field(default=False, env="DEBUG")

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

Git Worktree Workflow

Full Documentation: See ~/.claude/CLAUDE.md for complete worktree concepts, commands, and best practices.

Project-Specific Paths:

# Worktree directory for this project
../audio_processor-worktrees/

# Quick reference commands
git worktree add ../audio_processor-worktrees/feature-name -b feature/feature-name
git worktree add ../audio_processor-worktrees/pr-42 origin/feature/pr-branch
git worktree list
git worktree remove ../audio_processor-worktrees/feature-name

Remember: Each worktree needs uv sync --all-extras after creation (worktrees share git but not virtualenvs).

Common Tasks

Add Dependency

uv add package-name              # Production
uv add --dev package-name        # Development

Update Dependencies

uv sync --upgrade                        # All packages
uv sync --upgrade-package package-name   # Specific package

Run Specific Test

uv run pytest tests/unit/test_example.py::test_function_name -v

CI/CD Pipeline

GitHub Actions Workflows:

  1. CI (.github/workflows/ci.yml): Tests, linting, type checking
  2. Security (.github/workflows/security-analysis.yml): CodeQL, Bandit, pip-audit, OSV
  3. Docs (.github/workflows/docs.yml): Build and deploy documentation
  4. Publish (.github/workflows/publish-pypi.yml): PyPI release automation

Quality Gates (must pass):

  • All tests pass (80% coverage)
  • Ruff linting (no errors)
  • BasedPyright type checking
  • Security scans (no high/critical)
  • Pre-commit hooks

Third-Party Integrations

CodeRabbit (AI Code Reviews)

CodeRabbit provides automated AI-powered code reviews on every pull request.

Configuration: .coderabbit.yaml

Features:

  • Automatic review on PR creation
  • Security vulnerability detection
  • Code quality suggestions
  • Path-specific review instructions

Commands:

# In PR comments:
@coderabbitai summary      # Get high-level summary
@coderabbitai review       # Request re-review
@coderabbitai help         # Show available commands

Setup: Install the CodeRabbit GitHub App

Troubleshooting

Pre-commit Hooks Failing

pre-commit run --all-files           # Run manually
pre-commit clean                     # Clean cache
pre-commit install --install-hooks   # Reinstall

UV Lock Issues

uv lock                          # Regenerate lock
uv sync --all-extras             # Reinstall dependencies (includes dev tools)

BasedPyright Type Errors

uv run basedpyright src/  # Show type errors
# Add `# pyright: ignore[error-code]` for specific issues

Performance Targets

Metric Target Notes
Test Suite <30s Full suite with coverage
CI Pipeline <5min All checks
Code Coverage 80% Enforced in CI

Cruft Template Updates

This project uses a two-part standards system for safe template updates.

How It Works

┌─────────────────┐     cruft update     ┌──────────────────┐
│   Template      │ ──────────────────► │  .standards/     │
│   Repository    │                      │  (baselines)     │
└─────────────────┘                      └────────┬─────────┘
                                                  │
                                                  │ /merge-standards
                                                  ▼
                                         ┌──────────────────┐
                                         │  Root files      │
                                         │  (customized)    │
                                         └──────────────────┘
  1. Baseline files in .standards/ are updated automatically by cruft
  2. Root files (CLAUDE.md, REUSE.toml) contain your customizations
  3. Merge agent helps integrate baseline changes into your files

Update Workflow

# 1. Check for template updates
cruft check

# 2. View what would change
cruft diff

# 3. Update (baselines in .standards/ will be updated automatically)
cruft update --skip CLAUDE.md --skip REUSE.toml --skip docs/template_feedback.md

# 4. Check if baselines changed
git diff .standards/

# 5. If baselines changed, merge them into your root files
/merge-standards
# Or ask Claude: "Merge the updated baseline standards"

Files to ALWAYS Skip

These contain project-specific customizations:

  • CLAUDE.md - Your project guidelines (merge from .standards/CLAUDE.baseline.md)
  • REUSE.toml - Your licensing annotations (merge from .standards/REUSE.baseline.toml)
  • docs/template_feedback.md - Project-specific template feedback
  • docs/planning/* - Project planning documents
  • .env - Environment configuration

Files Auto-Updated by Cruft

  • .standards/* - Baseline files (merge into root files after update)
  • .github/workflows/* - CI/CD workflows
  • pyproject.toml - Review changes, may need manual merge
  • Tool configs - Usually safe to update

Baseline Files Reference

Baseline Merges Into Purpose
.standards/CLAUDE.baseline.md CLAUDE.md Development standards
.standards/REUSE.baseline.toml REUSE.toml SPDX licensing

See .standards/README.md for detailed merge instructions.

Additional Resources

Model Selection

Use the right model for each task to balance quality and cost:

Task type Model When
Architecture, planning, ADRs Opus 4.7 Multi-step decisions, deep code review
Standard development Sonnet 4.6 Most coding and editing
Read-only exploration Haiku 4.5 File scanning, quick lookups

Per-agent model defaults and orchestration patterns: see ~/.claude/.claude/rules/supervisor.md

Global Rules Cross-References

The following global rule files govern behavior in this project. Consult them when the relevant situation arises; the brief notes below describe the scope of each.

Rule file Scope
~/.claude/.claude/rules/writing.md AI pattern blacklist, grammar authority, full writing rules
~/.claude/.claude/rules/git-workflow.md Branch naming, worktree patterns, commit conventions
~/.claude/.claude/rules/python.md Python linting gates, function quality, BasedPyright config
~/.claude/.claude/rules/testing.md Testing scope, root-cause order, golden file protection
~/.claude/.claude/rules/supervisor.md Agent assignment patterns, model selection per agent

Last Updated: 2025-12-05 Template Version: 0.1.0