feat: add comprehensive Makefile and update CLAUDE.md

- Add Makefile with common development commands:
  * Build targets (dev/optimized/cross-platform)
  * Code quality checks (lint, vet, fmt, test)
  * Release management (tag, push, version)
  * Development helpers (watch, demo, clean)
- Update CLAUDE.md with Makefile-based workflow
- Add development workflow guidance
- Include comprehensive help system with colored output

CLAUDE.md

@@ -4,29 +4,42 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Shush is a CLI tool written in Go that removes comments from source code files using sed under the hood. It supports multiple programming languages and can process individual files or directories (with optional recursive traversal).
+Shush is a CLI tool written in Go that removes comments from source code files using sed under the hood. It supports multiple programming languages and can process individual files or directories (with optional recursive traversal). The tool emphasizes preserving file structure while providing precise comment removal control.
 
 ## Build and Development Commands
 
 ```bash
-# Build the binary
+# Show all available commands
-go build -o shush ./cmd/shush
+make help
 
-# Run the tool
+# Build the binary (optimized)
+make build
+
+# Quick development build (faster, unoptimized)
+make build-dev
+
+# Run all checks (format, vet, lint, test)
+make check
+
+# Development cycle (build + quick test)
+make dev
+
+# Get comprehensive LLM-friendly usage guide
+./shush --llm
+
+# Example usage
 ./shush file.py
-./shush src/ --recursive --dry-run
+./shush src/ --recursive --dry-run --verbose
-
-# Test with dry-run to see preview
-./shush file.js --dry-run --verbose
 ```
 
 ## Architecture
 
 ### Project Structure
-- `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management
+- `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management, LLM guide
 - `internal/types/types.go` - Core type definitions (CLI struct, Language struct, BlockComment)
-- `internal/processor/processor.go` - Main processing logic, file/directory handling, sed command execution
+- `internal/processor/processor.go` - Main processing logic, file/directory handling, sed command execution, colored preview
 - `internal/processor/languages.go` - Language detection and mapping (file extension → comment syntax)
+- `ai_docs/` - Design documents for future features (GIT_FEATURE_PLAN.md)
 
 ### Core Flow
 1. **CLI Parsing**: Kong parses arguments into `types.CLI` struct
@@ -34,9 +47,10 @@ go build -o shush ./cmd/shush
 3. **Processing Strategy**: 
    - Single file: Direct processing
    - Directory: Scan for supported files (recursive if `-r` flag)
-   - Preview mode (`--dry-run`): Show colored diff without changes
+   - Preview mode (`--dry-run`): Show colored diff with line numbers and counts
+   - LLM mode (`--llm`): Display comprehensive usage guide
 4. **Sed Command Generation**: Build sed patterns based on language and flags (`--inline`, `--block`)
-5. **Execution**: Run sed commands or show preview with color-coded output
+5. **Execution**: Run sed commands or show preview with color-coded output using fatih/color
 
 ### Key Design Principles
 - **Comment Removal Logic**: 
@@ -66,3 +80,30 @@ To add new language support, update `languageMap` in `internal/processor/languag
 ```go
 "ext": {LineComment: "//", BlockComment: &types.BlockComment{Start: "/*", End: "*/"}},
 ```
+
+## Future Development
+
+### Planned Git Integration
+A major feature is planned for git-aware comment removal (see `ai_docs/GIT_FEATURE_PLAN.md`):
+- `--staged`: Remove comments only from staged changes
+- `--unstaged`: Remove comments only from unstaged changes  
+- `--changes-only`: Process all git changes (staged + unstaged + untracked)
+
+This would enable surgical comment removal from only the lines you've changed, preserving existing codebase comments.
+
+## Development Notes
+
+### Common Development Workflow
+1. `make dev` - Quick build and test cycle
+2. `make check` - Run all quality checks before committing
+3. `make release` - Prepare for release (runs full check suite)
+4. Update version in `cmd/shush/main.go`, then `make tag && make push`
+
+### Adding New Features
+- Version management: Update `var version` in `cmd/shush/main.go`
+- CLI flags: Add to `types.CLI` struct with appropriate kong tags
+- Language support: Extend `languageMap` in `languages.go`
+- For LLM integration patterns: Reference existing `--llm` implementation
+
+### Makefile Targets
+The Makefile provides comprehensive build, test, and release automation. Use `make help` to see all available commands including cross-platform builds, code quality checks, and release management.

Makefile

@@ -0,0 +1,126 @@
+# Shush - Comment Removal CLI Tool
+.PHONY: help build install clean test lint fmt vet run dev release tag push check deps update-deps
+
+# Default target
+help: ## Show this help message
+	@echo "Shush - Comment Removal CLI Tool"
+	@echo ""
+	@echo "Available commands:"
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+# Build commands
+build: ## Build the binary
+	go build -ldflags="-w -s" -o shush ./cmd/shush
+
+build-dev: ## Build without optimizations (faster, for development)
+	go build -o shush ./cmd/shush
+
+install: build ## Build and install to GOPATH/bin
+	go install ./cmd/shush
+
+# Cross-platform builds
+build-all: ## Build for all platforms
+	GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o dist/shush-linux-amd64 ./cmd/shush
+	GOOS=linux GOARCH=arm64 go build -ldflags="-w -s" -o dist/shush-linux-arm64 ./cmd/shush
+	GOOS=darwin GOARCH=amd64 go build -ldflags="-w -s" -o dist/shush-darwin-amd64 ./cmd/shush
+	GOOS=darwin GOARCH=arm64 go build -ldflags="-w -s" -o dist/shush-darwin-arm64 ./cmd/shush
+
+# Development commands
+run: build-dev ## Build and run with example file
+	./shush --help
+
+dev: build-dev ## Quick development cycle (build + show help)
+	./shush --llm | head -20
+
+test: ## Run tests
+	go test -v ./...
+
+test-race: ## Run tests with race detection
+	go test -race -v ./...
+
+test-cover: ## Run tests with coverage
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out -o coverage.html
+	@echo "Coverage report: coverage.html"
+
+# Code quality
+lint: ## Run golangci-lint
+	@if command -v golangci-lint >/dev/null 2>&1; then \
+		golangci-lint run; \
+	else \
+		echo "golangci-lint not installed. Install with: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest"; \
+	fi
+
+fmt: ## Format code
+	go fmt ./...
+
+vet: ## Run go vet
+	go vet ./...
+
+check: fmt vet lint test ## Run all checks (format, vet, lint, test)
+
+# Dependency management
+deps: ## Download dependencies
+	go mod download
+
+tidy: ## Tidy dependencies
+	go mod tidy
+
+update-deps: ## Update dependencies
+	go get -u ./...
+	go mod tidy
+
+# Release commands
+version: ## Show current version
+	@grep 'var version' cmd/shush/main.go | cut -d'"' -f2
+
+release: clean check build ## Prepare for release (clean, check, build)
+	@echo "Ready for release. Current version: $$(make version)"
+	@echo "To create release:"
+	@echo "  1. Update version in cmd/shush/main.go"
+	@echo "  2. Run: make tag"
+	@echo "  3. Run: make push"
+
+tag: ## Create and push git tag for current version
+	$(eval VERSION := $(shell make version))
+	git tag -a v$(VERSION) -m "Release v$(VERSION)"
+	@echo "Created tag v$(VERSION)"
+	@echo "Run 'make push' to push tag and trigger release"
+
+push: ## Push current branch and tags
+	git push upstream
+	git push upstream --tags
+
+# Utility commands
+clean: ## Clean build artifacts
+	rm -f shush
+	rm -rf dist/
+	rm -f coverage.out coverage.html
+
+demo: build-dev ## Run demo commands
+	@echo "=== Shush Demo ==="
+	@echo "1. Version info:"
+	./shush --version
+	@echo ""
+	@echo "2. Help output:"
+	./shush --help
+	@echo ""
+	@echo "3. LLM guide preview:"
+	./shush --llm | head -10
+
+# Development helpers
+watch: ## Watch for changes and rebuild (requires entr)
+	@if command -v entr >/dev/null 2>&1; then \
+		find . -name "*.go" | entr -r make dev; \
+	else \
+		echo "entr not installed. Install with your package manager"; \
+		echo "  macOS: brew install entr"; \
+		echo "  Ubuntu: apt install entr"; \
+	fi
+
+size: build ## Show binary size
+	@ls -lh shush | awk '{print "Binary size: " $$5}'
+
+# Create dist directory
+dist:
+	mkdir -p dist