Claude Code Starter Kit

Production-tested configuration for Claude Code — the AI coding agent by Anthropic.

These patterns are extracted from real production projects and battle-tested over months of daily use. They solve the most common problems when working with Claude Code on serious projects.

What's Inside

.claude/
├── settings.json          # Hooks configuration
├── hooks/
│   ├── session-start      # Injects project context at every session start
│   └── check-deploy-branch.sh  # Blocks deploys from wrong branch
├── rules/
│   └── code-style.md      # Code style enforcement
├── skills/
│   ├── verification-before-completion/  # "Prove it works before saying done"
│   └── systematic-debugging/            # "Find root cause before fixing"
└── agents/
    └── README.md           # Guide for creating project agents
CLAUDE.md                   # Project knowledge base template

Quick Start

1. Copy to your project

# Clone the starter kit
git clone https://github.com/gmen1057/claude-code-starter-kit.git

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

2. Customize

Must do:

1. Edit CLAUDE.md — fill in your project's details
2. Edit .claude/hooks/session-start — replace placeholders with your critical rules
3. Edit .claude/skills/verification-before-completion/SKILL.md — fill in the verification commands table at the bottom

Optional: 4. Edit .claude/rules/code-style.md — adjust for your stack 5. Create agents in .claude/agents/ — see README.md there

3. Make hooks executable

chmod +x .claude/hooks/session-start
chmod +x .claude/hooks/check-deploy-branch.sh

4. Done

Start a Claude Code session in your project. The session-start hook will fire automatically.

What Each Piece Does

Hooks

session-start — The most impactful file. Injects your project's critical invariants into every Claude session. Without this, Claude starts each session from scratch and may violate rules it doesn't know about.

check-deploy-branch.sh — Prevents deploying from feature branches. Simple but saves you from "oops, deployed develop to production" moments.

settings.json also configures:

• Protected files — blocks edits to .env, secrets, credentials without confirmation
• Push reminder — after pushing 5+ files, reminds to update CLAUDE.md
• Stop reminder — at session end, flags if many files changed without doc update

Skills

verification-before-completion — Forces Claude to actually run verification commands before claiming work is done. Eliminates the #1 problem: "I fixed it" without testing.

systematic-debugging — Forces Claude to investigate root causes before attempting fixes. Stops the pattern of "try random changes until something works". Includes:

• root-cause-tracing.md — How to trace bugs backward
• defense-in-depth.md — Validate at every layer
• condition-based-waiting.md — Replace sleep() with condition polling

Rules

code-style.md — Enforces naming conventions, forbidden patterns, import order. Customize for your stack.

Agents

Project-specific agents live in .claude/agents/. The included README explains when and how to create them. Agents are most useful for:

• Complex subsystems with many rules (payments, auth, deploy)
• Workflows with multiple steps (adding a new page, integrating an API)
• Areas where Claude keeps making the same mistakes

CLAUDE.md

The project knowledge base. This is the single most important file for Claude Code. Fill it with:

• Tech stack and architecture
• Key patterns and invariants
• Development and deployment commands
• Known issues and technical debt

Philosophy

Three principles behind this kit:

1. Verify, don't trust — Claude is confident but not infallible. The verification skill makes it prove claims with actual command output.

2. Prevent, don't fix — Hooks catch mistakes before they happen. Blocking a deploy from the wrong branch is better than rolling it back.

3. Context is everything — Claude without project context writes generic code. The session-start hook and CLAUDE.md give it the knowledge to write code that fits YOUR project.

License

MIT — use it however you want.