Claude Code Tutorial — Complete Beginner's Guide

I just cloned this repo and need to get oriented. Do the following:

1. Read the README, package.json, and any config files to understand the project
2. Identify the tech stack, framework version, and key dependencies
3. Check for a CLAUDE.md — if none exists, create one with:
   - Project overview (1-2 sentences)
   - Tech stack table
   - Commands section (dev, build, test, lint)
   - Directory structure overview
   - Key conventions you observe in the existing code
4. Try running the dev server and report any issues
5. Summarize what this project does and the 3 most important files to understand first

Do not modify any source code — only create the CLAUDE.md and report findings.

Analyze this codebase and write a comprehensive CLAUDE.md file. Read the existing code, configs, and documentation first.

Include these sections:
## Project Overview — what this project does, one paragraph

## Tech Stack — table with Layer | Technology format

## Commands — every npm script / make target with descriptions

## Directory Structure — tree view of important directories with descriptions

## Architecture — how the app is structured, key patterns, data flow

## Database — schema overview, ORM, migration workflow

## Key Components — table of the most important files and what they do

## Conventions — naming, file structure, import order, styling

## Important Rules — things Claude Code must never do (e.g., don't push to main, don't modify migrations directly)

Base everything on what you actually find in the code. Do not make assumptions. If something is unclear, note it with a TODO.

Implement the following feature: {{featureDescription}}

**Affected files (likely):** {{expectedFiles}}

**Requirements:**
{{requirements}}

**Constraints:**
- Follow the existing code patterns in this project (check CLAUDE.md)
- Do not modify files outside the scope of this feature
- Maintain all existing tests — if you break one, fix it
- Add TypeScript types for any new interfaces or function signatures
- If you need to install a new dependency, ask me first before proceeding

**Implementation approach:**
1. Read the relevant files first and explain your plan
2. Wait for my approval before making changes
3. Implement changes file by file
4. After all changes, run {{testCommand}} and {{lintCommand}} to verify

Show me a brief plan before you start coding.

I'm hitting this error:

```
{{errorOutput}}
```

**Steps to reproduce:** {{reproSteps}}
**When it started:** {{whenItStarted}}

Debug this systematically:
1. Read the error and identify the failing file/line
2. Read that file and trace the execution path
3. Check recent git changes if relevant: run `git diff {{branch}}` or `git log --oneline -10`
4. Identify the root cause — not just the symptom
5. Propose a fix and explain why it solves the root cause
6. Apply the fix
7. Run {{verifyCommand}} to confirm it works

If the error has multiple possible causes, investigate each one. Do not guess — verify by reading the actual code.

I want to implement {{featureDescription}} using TDD.

**Tech:** {{testFramework}} for testing, {{language}} codebase

**Step 1 — Write tests first:**
- Create test file at {{testFilePath}}
- Write tests for these behaviors:
  {{expectedBehaviors}}
- Include edge cases: {{edgeCases}}
- Use descriptive test names: "should {{behavior}} when {{condition}}"
- All tests should FAIL initially (red phase)

**Step 2 — Run the tests:**
- Execute {{testCommand}} and confirm they all fail for the right reasons
- Show me the output

**Step 3 — Implement the minimum code to pass:**
- Write the implementation at {{implFilePath}}
- Write only enough code to make the tests pass — no extra features
- Run tests again to confirm they all pass (green phase)

**Step 4 — Refactor if needed:**
- Clean up the implementation while keeping all tests green
- Run the full test suite to check for regressions

Do each step sequentially. Show me the test output after each phase.

Prepare this project for deployment. Here is what I need:

**Target:** {{deploymentTarget}}
**Current state:** {{currentState}}

**Tasks:**
1. **Pre-deploy checks:**
   - Run the full test suite: {{testCommand}}
   - Run lint: {{lintCommand}}
   - Run type check: {{typeCheckCommand}}
   - Check for any TODO/FIXME comments in the code that should be resolved
   - Verify environment variables are documented

2. **Build verification:**
   - Run {{buildCommand}} and ensure it succeeds
   - Check the build output size and flag anything unusually large

3. **Deployment config:**
   - Verify {{configFile}} has the correct settings for {{environment}}
   - Check that sensitive values are using environment variables, not hardcoded

4. **Create a deploy checklist** as a comment summarizing:
   - What tests passed/failed
   - Any warnings from the build
   - Environment variables needed
   - Any manual steps required after deploy

Do not actually deploy — just prepare everything and give me the checklist.

Review {{filePath}} and suggest improvements. Do NOT make changes yet — just analyze and report.

**Review criteria:**
1. **Readability:** Are variable/function names clear? Is the logic easy to follow?
2. **Performance:** Any unnecessary re-renders, O(n^2) operations, or missing memoization?
3. **Error handling:** Are failure modes covered? Any silent failures?
4. **Types:** Are TypeScript types precise or using `any` / overly broad types?
5. **Duplication:** Is there logic that could be extracted into a shared utility?
6. **Testing:** Is this code easily testable? What would be hard to test and why?

For each issue:
- Quote the specific code
- Explain the problem
- Rate severity: critical / should-fix / nice-to-have
- Provide the improved version

After review, ask me which improvements I want to apply before making any changes.

I need to understand how {{featureOrSystem}} works in this codebase. I am not familiar with this part of the code.

**Starting point:** {{entryPoint}}

Trace the code flow and explain:
1. **Entry point:** What triggers this feature? (route, event, user action)
2. **Data flow:** Follow the data from input to output — which files and functions does it pass through?
3. **Dependencies:** What services, APIs, or database tables does it interact with?
4. **State management:** Where is state stored and how does it change?
5. **Edge cases:** What error handling exists? What happens when things fail?

Create a concise map:
```
{{entryPoint}} -> [file1:function] -> [file2:function] -> [output]
```

Then explain the 3 most important things I need to know before modifying this code.

Read as many files as needed to give a complete picture. Do not guess — trace the actual imports and function calls.