Go Project Template with Claude Code Integration

A production-ready Go project template featuring comprehensive linting, testing, commit enforcement, and seamless Claude Code integration for AI-assisted development.

🚀 Quick Start

Using This Template

1. Create a new repository from this template:

   # Option 1: Use GitHub's "Use this template" button (recommended)
   # Click the green "Use this template" button at the top of this repo
   
   # Option 2: Clone and modify manually
   git clone https://github.com/your-username/go-project-template.git my-new-project
   cd my-new-project
   rm -rf .git
   git init

2. Customize for your project:

   # Update go.mod with your module name
   go mod edit -module github.com/your-org/your-project
   
   # Update README.md, remove template-specific content
   # Update any placeholder names in code files

3. Set up development environment:

   # Ensure Go tools are in your PATH
   export PATH=$PATH:$(go env GOPATH)/bin
   
   # Install development tools and git hooks
   make dev
   
   # Verify everything works
   make commit-ready

4. Start coding with confidence:

   # Your code will automatically follow Go best practices
   # Git hooks ensure quality before each commit
   git add .
   git commit -m "Initial commit"  # This runs all quality checks automatically

🎯 What You Get

📋 World-Class Go Standards

• Complete style guide following Effective Go, Google Go Style Guide, and Uber Go Style Guide
• Idiomatic patterns for error handling, interfaces, and concurrency
• Advanced conciseness patterns from industry leaders

🔍 Comprehensive Quality Enforcement

• golangci-lint with production-ready configuration
• gitleaks for secret scanning
• govulncheck for vulnerability detection
• Race condition detection with every test run
• 85% code coverage requirement (configurable)

✅ Automatic Commit Quality Gates

• Pre-commit hooks that enforce all quality standards
• make commit-ready target that must pass before any commit
• Zero tolerance for broken builds or failing tests

🤖 Claude Code Ready

• Organized context files in .claude/ directory
• Complete project documentation for AI assistance
• Clear project organization rules

🏗️ Professional Project Structure

• Clean root directory with only essential files
• Organized tooling in .claude/ directory
• Sample code demonstrating best practices

🔧 Development Workflow

Prerequisites

Ensure Go tools are in your PATH:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH=$PATH:$(go env GOPATH)/bin

# Or run before each development session
export PATH=$PATH:$(go env GOPATH)/bin

Daily Development

# Format code (automatic with most editors)
make fmt

# Run quality checks before committing
make commit-ready

# Build and test
make build
make test

# See all available targets
make help

Working with Git

# The pre-commit hook automatically runs quality checks
git add .
git commit -m "Add new feature"  # Automatically runs make commit-ready

# If checks fail, fix issues and try again
make fmt              # Fix formatting
make lint             # See linting issues  
make test             # Run tests
make commit-ready     # Verify everything passes

# Bypass hooks only in emergencies (not recommended)
git commit --no-verify -m "Emergency fix"

Environment Variables

Control the linting behavior with environment variables:

# Skip specific checks (not recommended for commits)
SKIP_GOLANGCI=1 make lint      # Skip golangci-lint
SKIP_TESTS=1 make test         # Skip tests
COVER_THRESHOLD=90.0 make test # Set coverage threshold

# Enable experimental linters
EXPERIMENTAL="gitleaks,nilaway,shuffle" make lint

Troubleshooting

Common Issues:

1. goimports not found: Add Go tools to PATH:

   export PATH=$PATH:$(go env GOPATH)/bin

2. golangci-lint: command not found: Run make install-tools or the linter will auto-download

3. Permission denied on scripts: Make scripts executable:

   chmod +x .claude/scripts/*.sh

4. Coverage threshold errors: Set appropriate threshold:

   COVER_THRESHOLD=0 make commit-ready  # For initial setup

🤖 Working with Claude Code

This template is designed to work seamlessly with Claude Code. Here's how to get the most out of AI-assisted Go development:

Getting Started with Claude Code

1. Install Claude Code (if you haven't already):

   # Follow installation instructions from Anthropic

2. The template is ready to use - Claude Code will automatically read claude.md and understand your project's standards.

Effective Claude Code Usage

✅ What Claude Code Excels At

Code Generation:

# Claude Code will automatically follow your style guide
claude "Create a HTTP handler for user registration with validation"
claude "Add a database layer with connection pooling"
claude "Write comprehensive tests for the auth package"

Code Review & Improvement:

# Claude Code understands your quality standards
claude "Review this function for Go best practices"
claude "Refactor this code to be more idiomatic"
claude "Add proper error handling to this function"

Architecture & Design:

# Claude Code knows your project organization rules
claude "Design a config package following our standards"
claude "Create an interface for this service layer"
claude "Add logging middleware that follows our patterns"

📝 Best Practices for Claude Code Prompts

Be Specific About Context:

# Good: Specific and contextual
claude "Add a Rate Limiter middleware to cmd/server/main.go that follows our error handling patterns"

# Better: Include requirements
claude "Create a Redis-backed cache service in pkg/cache/ with proper error handling, testing, and our functional options pattern"

Reference Project Standards:

# Claude Code knows about your style guide
claude "Refactor this to follow our early return pattern"
claude "Add functional options to this constructor"
claude "Make this function more concise following our style guide"

Ask for Complete Solutions:

# Claude Code will include tests, documentation, and proper structure
claude "Create a complete user authentication system with JWT tokens, including handlers, middleware, tests, and documentation"

🎯 Effective Prompt Patterns

For New Features:

claude "Create a [feature] that follows our project standards including:
- Proper error handling with custom types
- Comprehensive tests with table-driven patterns  
- Documentation following our style
- Integration with existing [related component]"

For Refactoring:

claude "Refactor [file/function] to be more idiomatic:
- Use early returns
- Improve error handling
- Add missing tests
- Follow our naming conventions"

For Code Review:

claude "Review this code for:
- Compliance with our Go style guide
- Performance improvements
- Security issues
- Missing test cases"

📁 Understanding the Project Structure

Claude Code understands this organization:

your-project/
├── claude.md                     # Main Claude context - Claude reads this first
├── .claude/                      # All Claude-related files (AI tooling)
│   ├── docs/                     # Detailed style guides and standards
│   ├── scripts/                  # Quality automation scripts
│   ├── config/                   # Tool configurations
│   └── hooks/                    # Git hook templates
├── cmd/                          # Application entry points
├── pkg/                          # Exportable library code
├── internal/                     # Private application code
└── [standard Go project files]

Key principle: Keep the root clean - Claude Code knows to put tooling files in .claude/

🚀 Advanced Claude Code Techniques

Project-Wide Changes:

claude "Update all error handling across the project to use our latest error patterns"
claude "Add structured logging to all HTTP handlers"
claude "Implement graceful shutdown for all services"

Documentation Generation:

claude "Generate API documentation for all HTTP endpoints"
claude "Create README sections for each package"
claude "Add inline documentation following our standards"

Testing Strategy:

claude "Add integration tests for the entire auth flow"
claude "Create benchmarks for performance-critical functions"
claude "Add property-based tests for data validation functions"

📚 Documentation Structure

• Go Style Guidelines - Complete idiomatic Go standards
• Commit Standards - Quality enforcement and commit requirements
• Project Organization - Directory structure and file organization

🛠️ Customization

Adjusting Quality Standards

Coverage Threshold:

# In Makefile or environment
export COVER_THRESHOLD=90.0  # Require 90% coverage

Linter Configuration:

# Edit .claude/config/.golangci.yml
# Add/remove linters as needed for your project

Git Hooks:

# Customize .claude/hooks/pre-commit
# Add project-specific checks

Adding New Standards

1. Document in .claude/docs/ - Add new style guidelines
2. Update claude.md - Reference new documentation
3. Configure linters - Enforce with automated tools
4. Update scripts - Add to quality check pipeline

🤝 Contributing

When contributing to projects using this template:

1. Follow the established patterns - Claude Code will help you maintain consistency
2. Run quality checks - make commit-ready before every commit
3. Update documentation - Keep .claude/docs/ current
4. Use Claude Code - Leverage AI assistance for maintaining standards

📄 License

Apache 2.0

---

🎉 Happy Coding!

You now have a production-ready Go project with AI-assisted development capabilities. Claude Code will help you maintain high standards while moving fast.

Remember: The goal is to write clear, maintainable, idiomatic Go code that your future self (and your team) will thank you for.

Start coding with claude "Let's build something amazing!" 🚀