Skip to content

Instantly share code, notes, and snippets.

@enachb

enachb/CLAUDE_QUICKSTART.md

Last active January 10, 2026 01:15
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save enachb/b27c336067d5f2478ed6558e040d96e6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save enachb/b27c336067d5f2478ed6558e040d96e6 to your computer and use it in GitHub Desktop.
Download ZIP
Claude Code Quick Start Guide - One-page guide for junior developers with actionable steps
Raw
CLAUDE_QUICKSTART.md

Claude Code Quick Start Guide

Team Quick Reference - Everything you need to know in one page

What is Claude Code?

Claude Code is an AI assistant that writes, tests, and validates code automatically. This project has automation where Claude:

  • ✅ Auto-compiles code after every edit via hooks
  • ✅ Runs tests automatically to verify functionality
  • ✅ Checks code coverage (enforces 70% minimum)
  • ✅ Validates with go vet and staticcheck before completing work
  • ✅ Guides TDD workflow with /tdd command

💡 Pro Tip: All the automation (hooks, skills, quality checks) were created by Claude itself! You can ask Claude to create custom automation for your workflow:

  • "Create a hook that runs tests after I edit files"
  • "Make a skill for code review workflow"
  • "Add a quality gate for import organization"

Just describe what you want - Claude will generate the scripts and configuration for you!

🚀 How to Use Claude Code

Starting a Conversation

# Just start talking to Claude
"Help me implement user authentication in the alerts service"

Claude will:

  1. Ask clarifying questions
  2. Read relevant code
  3. Make changes
  4. Automatically compile via hooks (no manual build needed)
  5. Automatically run tests to verify functionality
  6. Automatically check coverage to ensure 70%+ requirement
  7. Report results and any issues found

Using TDD Workflow

# Invoke the TDD skill
/tdd

# Describe what you want: "Implement a function to validate email addresses"

# Claude automatically orchestrates:
# 1. RED: Writes a failing test
# 2. GREEN: Implements minimal code to pass
# 3. REFACTOR: Improves the code while keeping tests green
# 4. After each phase, hooks automatically compile and verify

🛠️ What Claude Does Automatically

Auto-Compilation Hook

Every time Claude edits a .go or .proto file, hooks automatically trigger:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔨 Auto-compiling codebase after editing: validator.go
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Build output...]
✅ Build succeeded
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude sees this feedback immediately and fixes any compilation errors before continuing.

What Claude Can't Do

For security, Claude cannot:

  • ❌ Access .env files or secrets
  • ❌ Delete system files (rm -rf)
  • ❌ Download files with curl/wget
  • ❌ Modify private keys

✅ Code Quality Requirements (MANDATORY)

Claude automatically runs these checks via hooks and during development:

The 4 Quality Gates

Claude ensures all code meets these standards:

  1. All tests pass - go test ./...
  2. Coverage meets 70% minimum - go test -cover ./...
  3. No vet warnings - go vet ./...
  4. No staticcheck issues - staticcheck ./...

These checks run automatically when Claude edits files (via hooks) and before completing any feature.

Quality Check Commands (Claude Runs These)

Claude automatically runs these via hooks and before completing work:

# Alerts service
make test-alerting                    # Unit tests (Claude runs automatically)
make test-alerting-integration        # Integration tests
cd alerts && go test -cover ./...     # Coverage check (enforces 70%)

# Mission service
make mission-test                     # All tests
cd mission_service && go test -cover ./...

# Video service
make video-test                       # Unit tests
make video-e2e                        # E2E tests
cd video-service && go test -cover ./...

You don't need to run these manually - Claude's hooks and workflows execute them automatically.

Before Completing Work

Claude automatically verifies (you can also run manually to confirm):

# Navigate to modified service
cd alerts  # or mission_service, video-service, etc.

# Run all checks
echo "🧪 Running tests..."
go test ./...

echo "📊 Checking coverage (must be 70%+)..."
go test -cover ./...

echo "🔬 Running go vet..."
go vet ./...

echo "🔍 Running staticcheck..."
staticcheck ./...

echo "🔨 Building..."
cd .. && make build-fast

echo "✅ All quality gates passed! Ready to commit."

Claude's hooks enforce these checks - if any fail, Claude will fix them before completing the work.

🎯 Common Tasks

Adding a New Feature

  1. Describe what you want: "Implement email validation in user registration"
  2. Optionally use /tdd for guided TDD workflow
  3. Claude automatically:
    • Writes tests
    • Implements code
    • Compiles via hooks after each edit
    • Runs tests to verify
    • Checks coverage (enforces 70%)
    • Runs vet and staticcheck
  4. Reviews results with you
  5. Ready to commit when all checks pass

Fixing a Bug

  1. Describe the bug: "There's a bug in X where Y happens"
  2. Claude automatically:
    • Investigates the code
    • Proposes and implements fix
    • Compiles via hooks
    • Runs relevant tests
    • Verifies coverage maintained
  3. Reports fix and test results

Understanding Existing Code

# Just ask Claude
"What does the ValidateNATSSubject function do?"
"How does the alerts service work?"
"Where is error handling implemented?"

Claude can read and explain code using the Go language server (Gopls).

Creating Custom Automation

You don't need to manually create hooks, skills, or configs! Just ask Claude:

# Create a hook
"Create a hook that runs linters after editing Go files"
"Make a hook that checks for TODO comments before committing"

# Create a skill
"Create a skill for API development that guides me through creating endpoints"
"Make a skill for database migrations with rollback testing"

# Add quality checks
"Add a hook that enforces 80% test coverage"
"Create a pre-commit hook that validates commit messages"

What Claude will do:

  1. Create the script files (.claude/hooks/my-hook.sh)
  2. Configure settings (settings.local.json)
  3. Make scripts executable (chmod +x)
  4. Test that it works
  5. Explain how to use it

Example conversation:

You: "Create a hook that checks code formatting before I commit"

Claude: "I'll create a pre-commit hook that runs go fmt. Let me create:
1. .claude/hooks/format-check.sh
2. Configure it in settings.local.json

[Creates files...]

Done! Now whenever you commit, the hook will check if code is formatted.
Try it: edit a Go file with bad formatting and commit."

📁 Project Structure

cloud/
├── alerts/              # Alerting service
├── mission_service/     # Mission CRUD
├── video-service/       # Video segmentation
├── server/              # Main server
├── .claude/             # Automation config (don't edit unless you know what you're doing)
│   ├── hooks/           # Auto-compilation scripts
│   └── skills/          # TDD workflow
├── CLAUDE.md            # Project commands and architecture
└── CLAUDE_AUTOMATION.md # Full automation guide (2,383 lines)

🆘 Getting Help

During Development

Ask Claude directly:

"What quality checks are you running automatically?"
"Explain the TDD workflow"
"What does the auto-compilation hook do?"

Documentation

  • This file: Quick reference (you are here)
  • CLAUDE.md: Project commands and architecture
  • CLAUDE_AUTOMATION.md: Complete automation guide
  • Team: Ask senior developers if stuck

Common Issues

Problem Solution
Tests failing Read error message, fix code, re-run
Coverage < 70% Add tests for uncovered code paths
Vet warnings Fix suspicious constructs
Staticcheck errors Follow staticcheck suggestions
Build failing Check compilation errors, fix syntax

🎓 Best Practices

✅ DO

  • Trust Claude's automation - hooks and quality checks run automatically
  • Use /tdd for new features (structured red-green-refactor workflow)
  • Describe clearly what you want - Claude handles implementation details
  • Ask Claude to explain any code or automation you don't understand
  • Review Claude's test output when it reports failures
  • Let Claude create custom automation - just describe what you need

❌ DON'T

  • Manually run builds - hooks do this automatically after every edit
  • Skip Claude's quality gates - 70% coverage and tests are mandatory
  • Manually edit .claude/ files - ask Claude to create/modify automation
  • Commit secrets - Claude's permissions block access to .env files
  • Override hook failures - if Claude's checks fail, let Claude fix them

📋 Daily Workflow Example

Morning: Start work on new feature

# 1. Start Claude Code
claude code

# 2. Describe what you want
"I need to implement email validation for user registration"

# 3. Optionally use TDD workflow
/tdd

# 4. Claude automatically:
#    - Writes failing test
#    - Implements minimal code
#    - Refactors for quality
#    - Compiles after each edit (via hooks)
#    - Runs tests to verify
#    - Checks coverage (enforces 70%)

Throughout the day: Claude auto-compiles, tests, and validates after each change ✅

Work completion: Claude automatically verifies quality gates

Claude: "✅ All quality gates passed:
  - Tests: 43/43 passing
  - Coverage: 74.3% (exceeds 70% requirement)
  - go vet: No warnings
  - staticcheck: No issues
  - Build: Success

Ready to commit!"

Create PR: Review Claude's changes and commit

# Make sure you're on a feature branch
git checkout -b feature/email-validation

# Claude has verified quality gates - commit
git add .
git commit -m "Add email validation with 74% test coverage"
git push origin feature/email-validation

# Create PR
gh pr create --title "Add email validation" --body "Implements email validation with tests. All quality gates passed."

🔑 Key Takeaways

  1. Claude does everything automatically - Writes code, tests, compiles, validates
  2. Hooks run on every edit - Compilation, tests, coverage checks all automatic
  3. You describe, Claude implements - Focus on what you want, not how to do it
  4. 70% coverage enforced automatically - Claude won't complete work below this threshold
  5. Quality gates are automatic - Tests, coverage, vet, staticcheck run via hooks
  6. Custom automation on demand - Ask Claude to create new hooks, skills, checks

🚦 Quick Reference Commands

# Development
make dev-up                          # Start services
make dev-down                        # Stop services

# Testing (pick your service)
make test-alerting                   # Alerts tests
make mission-test                    # Mission tests
make video-test                      # Video tests

# Quality checks (run in service directory)
go test ./...                        # Run tests
go test -cover ./...                 # Check coverage
go vet ./...                         # Run vet
staticcheck ./...                    # Run staticcheck

# Building
make build-fast                      # Fast build (hooks do this automatically)

# TDD Workflow
/tdd                                 # Invoke TDD skill

# Help
# Just ask Claude: "How do I X?"

⚡ TL;DR (Too Long; Didn't Read)

  1. Claude writes, tests, and validates automatically - You describe what you want
  2. Hooks run on every edit - Compilation, tests, coverage checks automatic
  3. Use /tdd for structured test-driven development workflow
  4. 4 Quality Gates enforced automatically: tests pass + 70% coverage + no vet + no staticcheck
  5. Claude creates custom automation - Just ask: "Create a hook that runs X"
  6. Trust the automation - Claude won't complete work that fails quality gates

Start here: Tell Claude what you want to build - Claude handles the rest!

Questions? Ask Claude or consult CLAUDE_AUTOMATION.md for full details.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment