claude-code-starter-kit: Instructions file for Claude Code

Project: [YOUR PROJECT NAME]

⚠️ Customize this file for your specific project. This is the most important file for Claude Code to understand your codebase.

Overview

[Brief description of what your project does]

Tech Stack

• Language: [Python 3.11+ / TypeScript / Go / etc.]
• Framework: [FastAPI / Express / Gin / etc.]
• Database: [PostgreSQL / MongoDB / etc.]
• Cache: [Redis / Memcached / etc.]
• Testing: [pytest / jest / go test / etc.]

Project Structure

src/                    # Source code
├── api/               # API endpoints/routes
├── services/          # Business logic
├── models/            # Data models
├── utils/             # Utilities
tests/                  # Test files (mirrors src/ structure)
├── conftest.py        # Shared fixtures (Python)
├── unit/              # Unit tests
└── integration/       # Integration tests
docs/                   # Documentation

Development Commands

# Install dependencies
[pip install -r requirements.txt / npm install / go mod download]

# Run tests
[pytest tests/ -v / npm test / go test ./...]

# Run with coverage
[pytest --cov=src / npm test -- --coverage / go test -cover ./...]

# Lint
[ruff check . / npm run lint / golangci-lint run]

# Format
[black . && isort . / npm run format / gofmt -w .]

# Start dev server
[uvicorn main:app --reload / npm run dev / go run main.go]

Testing Conventions

File Naming

• Test files: test_<module>.py or <module>.test.ts or <module>_test.go
• Located in tests/ directory, mirroring src/ structure

Test Structure

# Python example
def test_<function>_<scenario>_<expected_result>():
    # Arrange
    ...
    # Act
    ...
    # Assert
    ...

Mocking Guidelines

• Mock external services (APIs, databases, cache)
• Use fixtures for common setup
• Never mock the code under test

What to Test

• ✅ Public functions and methods
• ✅ Edge cases and error handling
• ✅ Business logic in services
• ⚠️ Integration points (with mocks)
• ❌ Private implementation details
• ❌ Third-party library internals