Claude Code Starter Kit

claude-code-setup.md

Setting Up Claude Code

Prerequisites

• Claude Code installed
• GitHub CLI authenticated (gh auth login)
• Copy settings.json to ~/.claude/settings.json

Quick Start

1. Create CLAUDE.md at repo root with project rules
2. Add custom commands in .claude/commands/

File Structure

your-repo/
├── CLAUDE.md              # Project rules (loaded automatically)
└── .claude/
    └── commands/          # Custom slash commands
        ├── pr.md
        └── review.md

~/.claude/projects/<project>/       # Auto-created by Claude
├── memory/MEMORY.md                # Persistent memory
└── plans/                          # Implementation plans

CLAUDE.md

Project rules loaded automatically every session. See claude.md.

Key Features

Memory

Claude maintains a MEMORY.md file per project in ~/.claude/projects/<project>/memory/. Use it to store preferences, context, and notes that persist across sessions. Just tell Claude what to remember.

Plans

When using plan mode, Claude saves implementation plans to ~/.claude/projects/<project>/plans/. Useful for complex tasks that need user approval before execution.

Hooks

Claude Code supports hooks for automation. Useful hooks include notifications when Claude needs attention, or running linters before commits.

Custom Commands

Place .md files in .claude/commands/ to register slash commands.

• /pr — PR preparation workflow. See pr.md.
• /review — Code review checklist. See review.md.

Git Worktrees

Work on multiple branches simultaneously:

git worktree add ../your-repo-2 feature/other-task

Run separate Claude sessions in each directory.

claude.md

Project Rules

Tooling

• Prefer make for task automation - run make help to see available commands

Commits & PRs

• Commit only when explicitly requested; do not auto-commit.
• Use the same Conventional Commit type for both branch name and commit format: branches as <type>/* and commits as type(scope): description (allowed types: feat, fix, refactor, docs, test, chore).
• Keep commit subject lines under 72 characters.
• Use the repository PR template when available.

Code

• Minimal changes - only change what's requested, don't over-engineer
• No duct tape - implement properly or defer entirely
• Prefer editing over creating - don't create new files unless necessary

Validation

• Always read files before editing - never guess at code structure
• Run lint and tests (e.g., make lint, make test)
• Document any validations that could not run

Testing

• Justify new tests - only add tests that provide value
• Keep feedback cycle fast - avoid redundant or trivial tests

Documentation

• Update docs when behavior changes - keep README/docs in sync
• Match existing style - follow patterns in docs/

Safety

• Stop on unexpected diffs - ask before proceeding
• Remove debug code before committing
• Justify new dependencies - avoid adding without rationale

Communication

• Ask when requirements are unclear - don't assume, clarify first
• Capture decisions, trade-offs, and open questions
• Use TODO(username): for intentional deferrals

pr.md

PR Workflow

Follow these steps in order. Do not skip or reorder.

Respect repository policies in CLAUDE.md and AGENTS.md when present.

1. Confirm with the user that all code changes are complete.

2. Run validation commands required by the project (lint, type-check, tests).

   • Record pass/fail for each command.
   • Record any validation that could not run, with reason.

3. Stage and commit changes following the project's commit conventions.

   • Use Conventional Commit format: type(scope): description
   • Only commit when explicitly requested.

4. Push to the remote branch.

5. Review main...HEAD (or the appropriate base branch) to understand the full changeset.

6. Draft the PR.

   • Read .github/pull_request_template.md when available.
   • PR title: type(scope): description
   • Keep the body concise and factual — no filler.
   • Include:
     • What changed and why
     • Validation results (pass/fail per command)
     • Any validations that could not run, with reason
     • Linked issues/tickets
   • If required template fields, issue links, or UI screenshots are missing, stop and ask before proceeding.

7. Wait for user confirmation before creating or updating the PR.

8. Create or update the PR using GitHub CLI.

   • Check for an existing PR: gh pr list --head <branch> --json number,url
   • If exists: gh pr edit <number> --title "<title>" --body "<body>"
   • If not: gh pr create --title "<title>" --body "<body>" --base main
   • Confirm final state: gh pr view --json number,url,title

9. Report the result: PR number, URL, and any open items.

review.md

Review - PR Review & Validation

Step 1: Create or Update the PR

• If on main: Create a feature branch, commit changes to it.
• If on a feature branch: Continue with existing branch.

Then:

• If no PR exists, create one.
• If a PR exists, push any uncommitted changes.

Step 2: Launch Review Agents in Parallel

Use the Task tool to launch these agents simultaneously.

Scope constraint:

• Only recommend changes to files modified in this PR.
• Reference other files for context, but don't change them.
• If a fix requires touching files outside PR scope, stop and ask first.

Agent 1: Codebase Consistency

• Duplicated logic that exists elsewhere?
• Inconsistencies within changed files?
• Opportunities to use existing utilities?

Agent 2: Clean Code

• Single Responsibility — doing one thing?
• Opportunities to extract reusable code?
• Deeply nested conditionals to flatten?
• Long functions to decompose?

Agent 3: Defensive Code & Security

• Try-catch swallowing errors silently?
• Fallback values masking errors?
• Optional chaining hiding broken assumptions?
• Secrets or credentials in code?
• Security vulnerabilities?
• Debug code left behind?

Agent 4: Documentation & i18n

• Do changes affect documented APIs or workflows?
• Are there new patterns that should be documented?
• Do existing docs need updates?
• Are user-facing strings properly localized?

Agent 5: UX & Accessibility

• Do changed interactions remain consistent with the rest of the app?
• Are accessibility attributes preserved or added where needed?

Step 3: Apply Fixes

1. Apply most recommendations — if on the fence, do it.
2. Handle conflicts — prefer existing code over new abstractions.
3. Track what you skip — note for summary.

Step 4: Validate

Run lint, type-check, and tests relevant to changes. If any required validation cannot run, record why.

Step 5: Commit and Push (Only If Requested)

Do not auto-commit. If asked, follow project commit conventions.

Step 6: Summary

• Findings: Ordered by severity, with file references
  • high: bug, regression, security issue, or data-loss risk
  • medium: maintainability, performance, or accessibility risk
  • low: style, minor cleanup, or documentation polish
• Changes Applied: What was fixed
• Skipped: What was skipped and why
• Validation: What passed/failed
• Unable to Validate: What couldn't run and why
• Merge Readiness: Ready vs another pass needed

settings.json

{
  "permissions": {
    "allow": [
      "Bash(cat *)",
      "Bash(env)",
      "Bash(find *)",
      "Bash(gh api*)",
      "Bash(gh issue list*)",
      "Bash(gh issue status*)",
      "Bash(gh issue view*)",
      "Bash(gh pr checks*)",
      "Bash(gh pr list*)",
      "Bash(gh pr status*)",
      "Bash(gh pr view*)",
      "Bash(gh run list*)",
      "Bash(gh run view*)",
      "Bash(gh repo view*)",
      "Bash(git blame*)",
      "Bash(git branch*)",
      "Bash(git cherry*)",
      "Bash(git config --get*)",
      "Bash(git config --list*)",
      "Bash(git describe*)",
      "Bash(git diff*)",
      "Bash(git fetch*)",
      "Bash(git grep*)",
      "Bash(git log*)",
      "Bash(git ls-files*)",
      "Bash(git merge-base*)",
      "Bash(git reflog*)",
      "Bash(git remote*)",
      "Bash(git rev-parse*)",
      "Bash(git shortlog*)",
      "Bash(git show*)",
      "Bash(git stash list*)",
      "Bash(git stash show*)",
      "Bash(git status*)",
      "Bash(git tag*)",
      "Bash(grep *)",
      "Bash(head *)",
      "Bash(ls *)",
      "Bash(make *)",
      "Bash(node -v*)",
      "Bash(open *)",
      "Bash(pbcopy*)",
      "Bash(pnpm *)",
      "Bash(printenv*)",
      "Bash(pwd)",
      "Bash(tail *)",
      "Bash(wc *)",
      "Bash(which *)",
      "Glob",
      "Grep",
      "Read",
      "WebFetch",
      "WebSearch"
    ],
    "ask": [
      "Bash(gh issue close*)",
      "Bash(gh issue comment*)",
      "Bash(gh issue create*)",
      "Bash(gh issue edit*)",
      "Bash(gh pr close*)",
      "Bash(gh pr comment*)",
      "Bash(gh pr create*)",
      "Bash(gh pr edit*)",
      "Bash(gh pr merge*)",
      "Bash(git add*)",
      "Bash(git checkout*)",
      "Bash(git cherry-pick*)",
      "Bash(git clean*)",
      "Bash(git commit*)",
      "Bash(git merge*)",
      "Bash(git pull*)",
      "Bash(git push*)",
      "Bash(git rebase*)",
      "Bash(git reset*)",
      "Bash(git restore*)",
      "Bash(git revert*)",
      "Bash(git rm*)",
      "Bash(git stash drop*)",
      "Bash(git stash pop*)",
      "Bash(git stash push*)",
      "Bash(git switch*)"
    ],
    "deny": []
  }
}