python version of a claude.md

CLAUDE.md

Claude General Preferences

This file contains general preferences and guidelines for Claude that apply across all projects. Include this file in any project where you want consistent Claude behavior.

Code Style & Quality

Python

• Follow PEP 8 style guide
• Use type hints for all function signatures
• Prefer dataclasses or Pydantic models for structured data
• Maintain >80% test coverage with pytest
• Use docstrings for all public functions and classes

Import Organization

• Group imports in this order with blank lines between:
  1. Standard library imports
  2. Third-party imports
  3. Local/project imports
• Sort alphabetically within each group

Formatting Tools

• Use Black for Python code formatting
• Use Ruff for linting and import sorting
• Apply formatters via pre-commit hooks when available

Attribution Guidelines

CRITICAL: Claude must NEVER add attribution to itself in any form.

Prohibited Attribution

• ❌ Do NOT add "Generated with Claude" to commit messages
• ❌ Do NOT add "Co-Authored-By: Claude" to commits
• ❌ Do NOT add Claude attribution in JIRA, Confluence, or any other systems
• ❌ Do NOT include AI/Claude references in code comments
• ❌ Do NOT add emoji indicators like 🤖 to denote AI involvement

Correct Attribution

• ✅ All changes should be solely attributed to the human user
• ✅ The person running Claude is the author of all work

Communication Style

Professional Systems (JIRA, Confluence, etc.)

• Use professional, text-only communication
• No emojis in comments or documentation
• Use bullet points or dashes for lists (not emoji checkmarks)
• Keep language clear, concise, and technical

Code Comments

• Write comments as if a human developer wrote them
• Focus on WHY, not WHAT the code does
• No self-referential AI/Claude mentions

Development Best Practices

Error Handling

• Log errors with full context (IDs, timestamps, operation details)
• Use structured logging with appropriate levels (DEBUG, INFO, WARN, ERROR)
• Implement graceful degradation for external service failures
• Add retry logic with exponential backoff for transient failures
• Never silently swallow exceptions

Security & Safety

• Never commit secrets (API keys, tokens, passwords, credentials)
• Validate all inputs (URLs, file paths, user data)
• Sanitize outputs before using in production systems
• Use safe file operations - no arbitrary writes outside project directories
• Check file contents for malicious patterns before processing

Performance

• Use async/await for I/O operations (network, file system)
• Batch API/LLM requests when possible
• Implement caching for expensive operations
• Stream large files instead of loading into memory
• Profile before optimizing - don't guess at bottlenecks

Git Workflow

Commit Practices

• Write descriptive commit messages explaining the WHY
• Use conventional commit format when project specifies it
• One logical change per commit
• Reference issue numbers when applicable

Branch Strategy

• Never commit directly to main/master branch
• Use descriptive branch names (feature/, fix/, chore/)
• Keep branches focused on single features/fixes
• Rebase or merge cleanly - avoid messy histories

Platform-Specific Guidelines

macOS

• Always use COPYFILE_DISABLE=1 when creating tar archives
• This prevents AppleDouble (._*) metadata files
• Example: COPYFILE_DISABLE=1 tar -czf archive.tar.gz directory/

Cross-Platform Paths

• Use os.path.join() or pathlib for file paths
• Never hardcode path separators
• Be aware of case sensitivity differences

Testing Guidelines

• Write tests alongside code, not after
• Use descriptive test names that explain the scenario
• Follow Arrange-Act-Assert pattern
• Mock external dependencies
• Aim for >80% coverage but prioritize critical paths
• Include edge cases and error scenarios

Documentation

Code Documentation

• Document all public APIs
• Include examples in docstrings
• Keep documentation in sync with code
• Explain complex algorithms or business logic

Project Documentation

• Update README files when adding features
• Document setup and deployment procedures
• Create runbooks for operational tasks
• Use clear headings and formatting

General "Never" Rules

1. Don't bypass type checking without excellent reason and documentation
2. Don't hardcode file paths, URLs, or environment-specific values
3. Don't ignore test failures - fix or remove flaky tests
4. Don't expose sensitive data in logs, errors, or responses
5. Don't over-optimize - avoid micro-optimizations without profiling
6. Don't break existing APIs without versioning/deprecation
7. Don't mix concerns - keep business logic separate from infrastructure
8. Don't use global state - prefer dependency injection
9. Don't suppress linter warnings without documenting why
10. Don't commit commented-out code - use version control instead

Performance Optimization

When to Optimize

• Only optimize after profiling shows actual bottlenecks
• Don't sacrifice readability for marginal gains
• Document why optimization was necessary
• Include benchmarks to prove improvements

What Not to Optimize

• Working commands that complete in reasonable time
• API calls that are already batched appropriately
• Code that runs infrequently
• Anything without measurement data

Dependency Management

• Pin direct dependencies to specific versions
• Use lockfiles (poetry.lock, package-lock.json, etc.)
• Regularly update dependencies for security patches
• Document why specific versions are required
• Avoid unnecessary dependencies

Code Review Mindset

When reviewing or writing code, consider:

• Is this the simplest solution that works?
• Will another developer understand this in 6 months?
• Are edge cases handled appropriately?
• Is this testable and maintainable?
• Does this follow established patterns in the codebase?

---

Remember: These are general preferences. Always defer to project-specific guidelines in the project's own CLAUDE.md file when there are conflicts.