Claude Code Development Context

This file provides comprehensive context for AI assistants working on this project, enabling seamless collaboration and consistent development practices.

🎯 Project Overview

Project Name: Sample AI Collaboration Project Purpose: Comprehensive template demonstrating AI-assisted development workflows Type: Python-based template project with full AI collaboration system Status: Template/Example project ready for customization

Key Features:

Complete AI development tracking and session management
Professional project structure suitable for any Python project
Comprehensive documentation and handoff systems
GitHub-ready with proper security and organization

🏗️ Project Architecture

Directory Structure

SampleAIProject/
├── src/                          # Source code
│   ├── core/                     # Core business logic
│   │   ├── __init__.py
│   │   └── main_module.py        # Primary functionality
│   ├── utils/                    # Utility functions
│   │   ├── __init__.py
│   │   └── helpers.py            # Common utilities
│   └── legacy/                   # Legacy code (if migrating)
│       └── __init__.py
├── tests/                        # Test suite
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
├── AI/                           # 🤖 AI Development System
│   ├── README.md                 # AI collaboration guide
│   ├── dev_log/                  # Session logs with timestamps
│   ├── context/                  # Project context preservation
│   │   ├── technical_decisions.md    # Why decisions were made
│   │   ├── project_status.md         # Current state and capabilities
│   │   └── coding_standards.md       # How code should be written
│   └── prompts/                  # Reusable prompt templates
│       ├── session_handoff_template.md
│       ├── session_ending_template.md
│       └── feature_development_template.md
├── docs/                         # Project documentation
├── requirements.txt              # Python dependencies
├── CLAUDE.md                     # This file - AI development context
├── .gitignore                    # Comprehensive gitignore
├── LICENSE                       # MIT License
└── README.md                     # Main project documentation

Core Components

src/core/

Purpose: Contains the main business logic and core functionality Pattern: Each module should have a single responsibility Testing: Each core module should have corresponding tests

src/utils/

Purpose: Reusable utility functions and helper modules Pattern: Pure functions that can be used across the project Testing: High test coverage required due to reuse

AI/ System

Purpose: Complete AI development tracking and collaboration system Components:

dev_log/: Timestamped session summaries for continuity
context/: Technical decisions and current project state
prompts/: Templates for consistent AI interactions

🛠️ Development Environment

Python Environment

Python Version: 3.8+ Virtual Environment: Recommended (venv or conda) Package Manager: pip with requirements.txt

Required Tools

# Core dependencies (customize for your project)
pip install -r requirements.txt

# Development tools (recommended)
pip install pytest black flake8 mypy isort

# Optional but helpful
pip install pre-commit

Environment Variables

# Template - customize for your project needs
export PROJECT_ENV=development
export LOG_LEVEL=DEBUG

# Add your project-specific environment variables here
# Example:
# export API_KEY=your_api_key_here
# export DATABASE_URL=your_database_url

🔧 Development Workflows

Starting Development

Clone/Copy Template: Copy this template to start new projects
Environment Setup: Create virtual environment and install dependencies
AI Session: Use session handoff template for AI collaboration
Development: Follow established patterns and document decisions

Testing Approach

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_core.py

# Run tests with detailed output
pytest -v

Code Quality

# Format code
black src/ tests/

# Check style
flake8 src/ tests/

# Sort imports
isort src/ tests/

# Type checking
mypy src/

📋 Development Standards

Code Organization

Modules: Single responsibility, clear purpose
Functions: Well-documented with type hints
Classes: Follow SOLID principles
Imports: Organized (standard, third-party, local)

Documentation Requirements

Docstrings: All public functions and classes
Comments: Explain complex logic and business rules
README: Keep updated with current capabilities
AI Context: Update AI/context/ files with decisions

Testing Standards

Coverage: Aim for >80% test coverage
Types: Unit, integration, and end-to-end tests
Naming: Clear test names describing what's tested
Organization: Mirror source code structure

🤖 AI Collaboration Guidelines

Session Management

Starting Sessions: Use AI/prompts/session_handoff_template.md During Development: Update context files as decisions are made Ending Sessions: Use AI/prompts/session_ending_template.md

Context Preservation

Technical Decisions: Document why choices were made in technical_decisions.md Current State: Track what works in project_status.md Standards: Document patterns in coding_standards.md

Development Workflow

Read Context: Start by understanding current project state
Plan Work: Create clear objectives for the session
Implement: Follow established patterns and document changes
Test: Verify functionality and maintain quality
Document: Update relevant context files
Handoff: Create comprehensive session summary

🔍 Common Development Patterns

Error Handling

import logging

logger = logging.getLogger(__name__)

def example_function(param: str) -> bool:
    """Example function with proper error handling."""
    try:
        # Main logic here
        result = process_parameter(param)
        logger.info(f"Successfully processed: {param}")
        return result
    except ValueError as e:
        logger.error(f"Invalid parameter value: {e}")
        raise
    except Exception as e:
        logger.error(f"Unexpected error processing {param}: {e}")
        raise

Configuration Management

import os
from dataclasses import dataclass
from typing import Optional

@dataclass
class Config:
    """Application configuration."""
    debug: bool = False
    log_level: str = "INFO"
    api_key: Optional[str] = None
    
    @classmethod
    def from_env(cls) -> 'Config':
        """Load configuration from environment variables."""
        return cls(
            debug=os.getenv('DEBUG', 'false').lower() == 'true',
            log_level=os.getenv('LOG_LEVEL', 'INFO'),
            api_key=os.getenv('API_KEY'),
        )

Testing Patterns

import pytest
from unittest.mock import Mock, patch

class TestExampleModule:
    """Test suite for example module."""
    
    def setup_method(self):
        """Set up test fixtures."""
        self.config = Config(debug=True)
    
    def test_function_success(self):
        """Test successful function execution."""
        # Given
        input_data = "valid_input"
        
        # When
        result = example_function(input_data)
        
        # Then
        assert result is True
    
    @patch('example_module.external_service')
    def test_function_with_mock(self, mock_service):
        """Test function with external dependency mocked."""
        # Given
        mock_service.return_value = "mocked_response"
        
        # When
        result = function_using_service()
        
        # Then
        assert result == "expected_result"
        mock_service.assert_called_once()

🚀 Deployment Considerations

Environment Setup

Dependencies: All requirements documented in requirements.txt
Configuration: Environment-specific settings via environment variables
Secrets: Never commit secrets, use environment variables or secret management

Production Readiness

Logging: Structured logging with appropriate levels
Error Handling: Graceful error handling and recovery
Monitoring: Health checks and performance metrics
Security: Input validation and secure coding practices

🔒 Security Guidelines

Data Protection

Input Validation: Validate all external input
Output Encoding: Properly encode output to prevent injection
Secrets Management: Use environment variables or secret managers
Access Control: Implement proper authentication and authorization

Code Security

# Input validation example
def validate_user_input(user_input: str) -> str:
    """Validate and sanitize user input."""
    if not user_input or len(user_input) > 1000:
        raise ValueError("Invalid input length")
    
    # Remove potentially dangerous characters
    import re
    sanitized = re.sub(r'[<>&"]', '', user_input)
    return sanitized.strip()

📊 Performance Considerations

Optimization Guidelines

Profiling: Profile before optimizing
Caching: Cache expensive operations when appropriate
Database: Use efficient queries and proper indexing
Memory: Be mindful of memory usage with large datasets

Monitoring

Metrics: Track key performance indicators
Logging: Log performance-critical operations
Alerting: Set up alerts for performance degradation

🔄 Maintenance and Updates

Regular Tasks

Dependencies: Keep dependencies updated and secure
Documentation: Maintain accurate documentation
Tests: Update tests as code evolves
Security: Regular security reviews and updates

Technical Debt Management

Refactoring: Regular code refactoring sessions
Standards: Evolve coding standards as needed
Tools: Evaluate and adopt new development tools

📈 Project Evolution

Adding Features

Planning: Use feature development templates
Implementation: Follow established patterns
Testing: Comprehensive test coverage
Documentation: Update all relevant documentation
AI Context: Update context files with new decisions

Scaling Considerations

Architecture: Design for future growth
Performance: Consider performance implications
Team: Plan for team growth and knowledge sharing
Process: Evolve development processes as needed

🤝 Team Collaboration

Code Review

Standards: Follow code review checklist
Feedback: Constructive and specific feedback
Learning: Use reviews as learning opportunities
Quality: Maintain high code quality standards

Knowledge Sharing

Documentation: Keep technical decisions documented
Sessions: Regular knowledge sharing sessions
AI Logs: Use AI development logs for team learning
Patterns: Share successful patterns and practices

💡 AI Assistant Guidelines

When working on this project:

Start by Reading: Always read latest dev_log and context files
Follow Patterns: Use established code patterns and conventions
Document Decisions: Update context files with new technical decisions
Test Thoroughly: Maintain high test coverage and quality
Communicate Clearly: Provide clear explanations and reasoning
End Properly: Use session ending templates for proper handoff

🔧 Customization Notes

This template is designed to be customized for any Python project:

Update project name and description throughout documentation
Modify directory structure to match your project needs
Customize dependencies in requirements.txt
Adapt coding standards for your team preferences
Update environment variables for your specific needs
Modify AI context files to reflect your project decisions

This file ensures AI assistants have complete context for effective collaboration on your project. Keep it updated as the project evolves! 🤖✨

FilesExpand file tree

CLAUDE.md

Latest commit

History