# 🤖 Claude Code Starter Kit

> A production-ready boilerplate for integrating Claude Code into your development workflow. Automate testing, security scanning, code review, and routine maintenance tasks.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-blue)](https://claude.ai/code)
[![PyPI](https://img.shields.io/pypi/v/claude-code-starter-kit-mcp)](https://pypi.org/project/claude-code-starter-kit-mcp/)

## 📦 MCP Server

All commands and agents in this kit are also available as an **MCP (Model Context Protocol) server**, making them usable from Claude Desktop, Claude Code, or any MCP-compatible client.

### Install

```bash
pip install claude-code-starter-kit-mcp
```

### Setup in Claude Code

Add to your project's `.claude/settings.json` (or `~/.claude/settings.json` for global use):

```json
{
  "mcpServers": {
    "claude-code-starter-kit": {
      "command": "claude-code-starter-kit-mcp"
    }
  }
}
```

### Setup in Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "claude-code-starter-kit": {
      "command": "claude-code-starter-kit-mcp"
    }
  }
}
```

### Available MCP Tools

| Tool | Maps to |
|------|---------|
| `command_test` | `/test` |
| `command_test_coverage` | `/test-coverage` |
| `command_security_check` | `/security-check` |
| `command_detailed_review` | `/detailed-review` |
| `command_fix_bugs` | `/fix-bugs` |
| `command_refactor` | `/refactor` |
| `command_docs` | `/docs` |
| `command_monitor` | `/monitor` |
| `agent_test_engineer` | test-engineer agent |
| `agent_security_auditor` | security-auditor agent |
| `agent_code_reviewer` | code-reviewer agent |
| `agent_bug_hunter` | bug-hunter agent |

All tools accept an optional `arguments` string (e.g. a file path or flags like `--changed`).

### PyPI Auto-publish

Releases to PyPI are automated via GitHub Actions. Push a version tag to trigger a publish:

```bash
git tag v0.2.0
git push origin v0.2.0
```

Requires a [PyPI Trusted Publisher](https://docs.pypi.org/trusted-publishers/) configured for the `pypi` environment in your repository settings.

---

## 🎯 What This Kit Provides

| Feature | Description |
|---------|-------------|
| **Automated Testing** | Generate unit tests for new code automatically |
| **Security Scanning** | Track vulnerabilities and get fix suggestions |
| **Code Review** | AI-powered review on every PR |
| **Bug Detection** | Monitor repo for common issues and anti-patterns |
| **Documentation** | Auto-generate and update docs |

## 🚀 Quick Start

### 1. Copy to Your Project

```bash
# Clone this repo
git clone https://github.com/dachivadachkoria/claude-code-starter-kit.git

# Copy the .claude directory to your project
cp -r claude-code-starter-kit/.claude your-project/
cp claude-code-starter-kit/CLAUDE.md your-project/

```

### 2. Customize CLAUDE.md

Edit `CLAUDE.md` in your project root to match your:
- Tech stack
- Testing conventions
- Code style
- Project structure

### 3. Start Using

```bash
cd your-project
claude

# Now use the commands:
/test src/myfile.py           # Generate tests
/security-check                 # Check vulnerabilities
/detailed-review                        # Code review
/fix-bugs                      # Auto-fix common issues
```

## 📁 Repository Structure

```
.claude/
├── settings.json              # Claude Code configuration
├── commands/                  # Slash commands
│   ├── test.md               # /test - Generate unit tests
│   ├── test-coverage.md      # /test-coverage - Coverage analysis
│   ├── security-check.md      # /security-check - Vulnerability check
│   ├── detailed-review.md             # /detailed-review - Code review
│   ├── fix-bugs.md           # /fix-bugs - Auto-fix issues
│   ├── docs.md               # /docs - Generate documentation
│   └── refactor.md           # /refactor - Safe refactoring
├── agents/                    # Specialized AI agents
│   ├── test-engineer.md      # Testing specialist
│   ├── security-auditor.md   # Security expert
│   ├── code-reviewer.md      # Review specialist
│   └── bug-hunter.md         # Bug detection expert
└── knowledge-base/            # Project-specific guidelines
    ├── testing-guide.md
    └── security-checklist.md

CLAUDE.md                      # Project context (customize this!)
.github/
└── workflows/
    └── claude-review.yml      # Optional: CI integration
```

## 🔧 Available Commands

### Testing Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/test <file>` | Generate tests for a file | `/test src/auth.py` |
| `/test --changed` | Test all changed files | `/test --changed` |
| `/test-coverage` | Analyze and improve coverage | `/test-coverage` |

### Security Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/security-check` | Full security audit | `/security-check` |
| `/security-check --deps` | Check dependencies only | `/security-check --deps` |
| `/security-fix` | Auto-fix vulnerabilities | `/security-fix` |

### Code Quality Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/detailed-review` | Review staged changes | `/detailed-review` |
| `/detailed-review <file>` | Review specific file | `/detailed-review src/api.py` |
| `/fix-bugs` | Detect and fix issues | `/fix-bugs` |
| `/refactor <file>` | Safe refactoring | `/refactor src/legacy.py` |

### Documentation Commands

| Command | Description | Example |
|---------|-------------|---------|
| `/docs` | Generate/update docs | `/docs` |
| `/docs <file>` | Document specific file | `/docs src/utils.py` |

## 💡 Built-in Commands

Claude Code has excellent built-in commands you should know:

- `/security-review` - AI-powered security scanning
- `/review` - Code review
- `/init` - Initialize project with CLAUDE.md
- `/compact` - Compress context when running low

## 🛡️ Safety Guidelines

### What Claude Code CAN Do Safely

✅ Generate and run tests  
✅ Analyze code for vulnerabilities  
✅ Suggest fixes with explanations  
✅ Create documentation  
✅ Refactor with your approval  

### What Requires Your Review

⚠️ Any changes to authentication/authorization  
⚠️ Database migrations  
⚠️ Environment/config changes  
⚠️ Dependency updates  
⚠️ Production deployment scripts  

### Best Practices

1. **Review before commit** - Always review generated code
2. **Use branches** - Let Claude work on feature branches
3. **Incremental changes** - Small, focused tasks work best
4. **Test first** - Run tests before accepting changes
5. **Version control** - Commit frequently, revert if needed

## 🔌 Language-Specific Setup

<details>
<summary><b>Python</b></summary>

```markdown
# Add to your CLAUDE.md

## Testing
- Framework: pytest
- Run: `pytest tests/ -v`
- Coverage: `pytest --cov=src --cov-report=html`

## Style
- Formatter: black, isort
- Linter: ruff or flake8
- Types: mypy
```

</details>

<details>
<summary><b>JavaScript/TypeScript</b></summary>

```markdown
# Add to your CLAUDE.md

## Testing
- Framework: jest or vitest
- Run: `npm test`
- Coverage: `npm test -- --coverage`

## Style
- Formatter: prettier
- Linter: eslint
- Types: TypeScript strict mode
```

</details>

<details>
<summary><b>Go</b></summary>

```markdown
# Add to your CLAUDE.md

## Testing
- Framework: testing + testify
- Run: `go test ./...`
- Coverage: `go test -coverprofile=coverage.out ./...`

## Style
- Formatter: gofmt, goimports
- Linter: golangci-lint
```

</details>

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Ideas for Contributions

- [ ] More language-specific templates
- [ ] Framework-specific commands (Django, React, etc.)
- [ ] CI/CD integration examples
- [ ] IDE extension recommendations
- [ ] Video tutorials

## 📚 Resources

- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Anthropic API Docs](https://docs.anthropic.com)

## 📄 License

MIT License - feel free to use in personal and commercial projects.

---

**Made with 🤖 by the community, for the community**

*Star ⭐ this repo if you find it useful!*