Skip to content

alirezarezvani/claude-code-skill-factory / generated-skills/claude-md-enhancer

claude-md-enhancer

Verified

Analyzes, generates, and enhances CLAUDE.md files for any project type using best practices, modular architecture support, and tech stack customization. Use when setting up new projects, improving existing CLAUDE.md files, or establishing AI-assisted development standards.

FileKindSize
HOW_TO_USE.mdmarkdown12.2 KB
README.mdmarkdown15.8 KB
SKILL.mdskill md16.1 KB
analyzer.pyscript12.9 KB
examples/README.mdmarkdown5.3 KB
examples/core-small-team-CLAUDE.mdmarkdown5.5 KB
examples/minimal-solo-CLAUDE.mdmarkdown1.8 KB
examples/modular-backend-CLAUDE.mdmarkdown9.1 KB
examples/modular-frontend-CLAUDE.mdmarkdown10.5 KB
examples/modular-root-CLAUDE.mdmarkdown6.4 KB
examples/python-api-CLAUDE.mdmarkdown13.0 KB
expected_output.jsonconfig9.8 KB
generator.pyscript19.1 KB
sample_input.jsonconfig4.4 KB
template_selector.pyscript16.7 KB
validator.pyscript14.9 KB
workflow.pyscript15.5 KB

examples/python-api-CLAUDE.md

View on GitHub
# CLAUDE.md

This file provides guidance for Claude Code when working with this Python API project.

## Overview

FastAPI-based RESTful API with PostgreSQL database, JWT authentication, and async SQLAlchemy. Small team (6 developers) following TDD practices with 90%+ test coverage requirement.

## Project Structure

```
project-root/
├── app/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── endpoints/       # API endpoints
│   │   │   │   ├── auth.py
│   │   │   │   ├── users.py
│   │   │   │   └── products.py
│   │   │   ├── dependencies.py  # Shared dependencies
│   │   │   └── router.py        # API router
│   │   └── __init__.py
│   ├── core/
│   │   ├── config.py            # App configuration
│   │   ├── security.py          # Auth utilities
│   │   └── database.py          # DB connection
│   ├── models/
│   │   ├── user.py              # SQLAlchemy models
│   │   └── product.py
│   ├── schemas/
│   │   ├── user.py              # Pydantic schemas
│   │   └── product.py
│   ├── services/
│   │   ├── auth_service.py      # Business logic
│   │   ├── user_service.py
│   │   └── product_service.py
│   ├── utils/
│   │   ├── logging.py           # Logging utilities
│   │   └── validators.py
│   ├── middleware/
│   │   ├── logging.py           # Logging middleware
│   │   └── rate_limit.py        # Rate limiting
│   └── main.py                  # App entry point
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   ├── conftest.py              # Pytest fixtures
│   └── test_main.py
├── alembic/
│   ├── versions/                # Migration files
│   └── env.py                   # Alembic config
├── .env.example
├── alembic.ini
├── pyproject.toml
├── requirements.txt
├── Dockerfile
└── docker-compose.yml
```

## File Structure

- **app/** - Main application package
  - **api/v1/** - API version 1 endpoints and routing
    - **endpoints/** - Path operation functions
    - **dependencies.py** - Dependency injection (DB sessions, auth)
  - **core/** - Core utilities (config, security, database)
  - **models/** - SQLAlchemy ORM models
  - **schemas/** - Pydantic models for request/response validation
  - **services/** - Business logic layer (separate from HTTP)
  - **utils/** - Helper functions (logging, validation)
  - **middleware/** - FastAPI middleware components
- **tests/** - Test suite with pytest
- **alembic/** - Database migrations

## Architecture

**Layer Pattern**: FastAPI → Services → Models → Database

**Flow**:
```
HTTP Request → Router → Dependency Injection → Endpoint → Service → Model → Database
                 ↓
            Response (Pydantic schema)
```

**Components**:
- **Endpoints**: HTTP layer, request/response handling with Pydantic
- **Services**: Business logic, reusable across endpoints
- **Models**: Data access layer with async SQLAlchemy 2.0
- **Schemas**: Request/response validation with Pydantic
- **Dependencies**: Shared dependencies (DB session, current user)

## Setup & Installation

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with:
# - DATABASE_URL (PostgreSQL connection string)
# - SECRET_KEY (for JWT token signing)
# - ENVIRONMENT (development/staging/production)

# Start PostgreSQL (using Docker)
docker-compose up -d postgres

# Run database migrations
alembic upgrade head

# Seed database (if needed)
python -m app.scripts.seed

# Start development server
uvicorn app.main:app --reload

# Server runs at http://localhost:8000
# API docs at http://localhost:8000/docs (Swagger UI)
# Alternative docs at http://localhost:8000/redoc (ReDoc)
```

## Core Principles

1. **Type Hints First**: Use type hints for all function signatures (Python 3.10+)
2. **Test-Driven Development**: Write tests before implementation
3. **API Design**: Follow RESTful conventions and OpenAPI standards
4. **Error Handling**: Comprehensive error handling with proper logging
5. **Code Quality**: Black formatting, Ruff linting, 90%+ test coverage

## Tech Stack

- **Framework**: FastAPI 0.104+
- **Database**: PostgreSQL 15 with async SQLAlchemy 2.0
- **Authentication**: JWT with python-jose
- **Validation**: Pydantic v2
- **Testing**: Pytest, Pytest-asyncio, HTTPX
- **Deployment**: Docker, Uvicorn, Gunicorn
- **Logging**: Structlog (JSON format)
- **Code Quality**: Black, Ruff, MyPy

## Development Workflow

### Development Process

1. Create feature branch from `main`: `git checkout -b feature/name`
2. Write tests first (TDD with pytest)
3. Implement feature with type hints
4. Run formatter, linter, and tests locally
5. Create pull request with description
6. Code review (minimum 1 approval required)
7. Merge to main (auto-deploy to staging)

### Code Style

- Use Black for formatting (line length: 100)
- Use Ruff for linting (replaces flake8, isort, etc.)
- Type hints on all functions and methods
- Docstrings for all public functions (Google style)
- Example:
  ```python
  def create_user(db: Session, user_in: UserCreate) -> User:
      """Create a new user in the database.

      Args:
          db: Database session
          user_in: User creation data

      Returns:
          Created user object

      Raises:
          ValueError: If email already exists
      """
      # Implementation...
  ```

## API Design Guidelines

### FastAPI Path Operations

- Use FastAPI path operations (`@app.get`, `@app.post`, etc.)
- Version APIs: `/api/v1/users`, `/api/v2/users`
- Use Pydantic models for request/response validation
- Implement proper HTTP status codes:
  - `200 OK` - Successful GET/PUT/PATCH
  - `201 Created` - Successful POST
  - `204 No Content` - Successful DELETE
  - `400 Bad Request` - Validation error
  - `401 Unauthorized` - Authentication required
  - `403 Forbidden` - Insufficient permissions
  - `404 Not Found` - Resource not found
  - `422 Unprocessable Entity` - Pydantic validation error
  - `500 Internal Server Error` - Server error

### Documentation

- Document with OpenAPI (auto-generated by FastAPI)
- Access Swagger UI at `/docs`
- Access ReDoc at `/redoc`
- Add descriptions to path operations:
  ```python
  @router.get("/users/{user_id}", response_model=UserResponse)
  async def get_user(user_id: int, db: Session = Depends(get_db)):
      """Retrieve a single user by ID."""
      # Implementation...
  ```

## Database Guidelines

### Migrations with Alembic

- Use Alembic for migrations
- **Never edit existing migrations** - create new ones
- Auto-generate migrations: `alembic revision --autogenerate -m "description"`
- Review generated migrations before applying
- Test migrations on copy of production data
- Name migrations descriptively: `add_user_email_index`

### SQLAlchemy 2.0 Async Style

- Use async SQLAlchemy 2.0 style
- Example:
  ```python
  from sqlalchemy import select
  from sqlalchemy.ext.asyncio import AsyncSession

  async def get_user(db: AsyncSession, user_id: int) -> User | None:
      result = await db.execute(select(User).where(User.id == user_id))
      return result.scalar_one_or_none()
  ```

### Query Optimization

- Implement proper indexes for frequently queried columns
- Avoid N+1 queries - use `selectinload` or `joinedload`
- Use database transactions for multi-step operations
- Paginate large result sets (max 100 items per page)

## Error Handling

### FastAPI Exception Handlers

- Use FastAPI exception handlers
- Create custom exceptions:
  ```python
  class UserNotFoundException(HTTPException):
      def __init__(self, user_id: int):
          super().__init__(
              status_code=404,
              detail=f"User {user_id} not found"
          )
  ```

### Error Response Format

Return consistent error format:

```python
{
  "detail": {
    "code": "VALIDATION_ERROR",
    "message": "User-friendly message",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}
```

### Logging

- Log errors with structlog (JSON format)
- Include context (request ID, user ID, timestamp)
- Log levels: ERROR, WARNING, INFO, DEBUG
- Never log sensitive data (passwords, tokens)
- Never expose stack traces in production

## Testing Requirements

### Pytest Best Practices

- Use pytest for all tests
- Use pytest fixtures for test setup
- Mock external dependencies (httpx, boto3, etc.)
- Aim for 90%+ code coverage
- Test both success and error paths

### Example Test

```python
import pytest
from httpx import AsyncClient
from app.main import app

@pytest.mark.asyncio
async def test_create_user(client: AsyncClient):
    """Test user creation endpoint."""
    response = await client.post(
        "/api/v1/users",
        json={"email": "test@example.com", "name": "Test User"}
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "test@example.com"
    assert "id" in data

@pytest.mark.asyncio
async def test_create_user_duplicate_email(client: AsyncClient):
    """Test user creation with duplicate email."""
    # First creation
    await client.post("/api/v1/users", json={"email": "test@example.com"})

    # Duplicate should fail
    response = await client.post("/api/v1/users", json={"email": "test@example.com"})
    assert response.status_code == 400
```

### Test Categories

```bash
# Run all tests
pytest

# Run specific test categories
pytest tests/unit/                # Unit tests only
pytest tests/integration/         # Integration tests only
pytest -m slow                    # Slow tests (marked with @pytest.mark.slow)

# Run with coverage
pytest --cov=app --cov-report=html
```

## Security Practices

### Input Validation

- Validate all input with Pydantic models
- Use Pydantic validators for complex validation
- Sanitize user input to prevent XSS

### Database Security

- Use parameterized queries (SQLAlchemy handles this)
- Prevents SQL injection
- Never concatenate user input into queries

### Authentication & Authorization

- Hash passwords with passlib + bcrypt
- Use JWT for stateless authentication
- Implement refresh token rotation
- Use environment variables for secrets
- Example:
  ```python
  from passlib.context import CryptContext

  pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
  hashed_password = pwd_context.hash(plain_password)
  ```

### Rate Limiting

- Implement rate limiting with slowapi
- Example: 100 requests per 15 minutes per IP
- Protect against brute force attacks

### CORS

- Enable CORS properly with CORSMiddleware
- Whitelist allowed origins in production
- Don't use wildcard (`*`) in production

## Performance Optimization

### Async/Await

- Use async/await for all I/O operations
- Use AsyncSession for database operations
- Use httpx.AsyncClient for external HTTP calls

### Caching

- Implement caching for frequently accessed data
- Use Redis for caching (with aioredis)
- Cache expensive computations
- Set appropriate TTL (time-to-live)

### Database Connection Pooling

- Configure SQLAlchemy connection pool
- Set appropriate pool size and overflow

## Common Commands

```bash
# Development
uvicorn app.main:app --reload     # Start dev server with hot reload
pytest                            # Run all tests
pytest --cov=app                  # Run tests with coverage
black .                           # Format code
ruff check .                      # Lint code
mypy app/                         # Type checking

# Database
alembic upgrade head              # Run all pending migrations
alembic downgrade -1              # Rollback last migration
alembic revision --autogenerate -m "description"  # Create migration
alembic current                   # Show current migration
alembic history                   # Show migration history

# Production
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

# Docker
docker-compose up -d              # Start all services
docker-compose logs -f app        # View application logs
docker-compose down               # Stop all services
```

## API Documentation

After starting the server, access API documentation at:

- **Swagger UI**: http://localhost:8000/docs (interactive)
- **ReDoc**: http://localhost:8000/redoc (readable)
- **OpenAPI JSON**: http://localhost:8000/openapi.json (raw schema)

## Environment Variables

Required environment variables (see `.env.example`):

```bash
# Application
ENVIRONMENT=development
SECRET_KEY=your-secret-key-here
DEBUG=True

# Database
DATABASE_URL=postgresql+asyncpg://user:password@localhost/dbname

# Authentication
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
```

---

**Project Type**: Python API (FastAPI)
**Team Size**: Small (6 developers)
**Lines**: ~225 (Python API template with native format)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall