Skip to content

CLAUDE.md

Latest commit

 

History

History
132 lines (101 loc) · 5.41 KB

CLAUDE.md

File metadata and controls

132 lines (101 loc) · 5.41 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A single-page birthday joke web app: a "spot the 7 differences" puzzle between a colleague's photo and a cartoon lookalike — the punchline is there are 0 differences. Every tap on the images spawns a "Nope!" bubble; after 7 taps or pressing "I give up", a full-screen "Happy Birthday!" overlay with confetti is revealed.

Stack: vanilla HTML/CSS/JS in a single index.html (inline <style> and <script>). No build step, no dependencies, no tests. Designed mobile-first.

Files that matter:

  • index.html — entire app. Personalize the recipient by editing the NAME const near the top of the <script> block.
  • assets/colleague.jpg and assets/cartoon.jpg — the two puzzle images (user-supplied).
  • notes/todo.md, notes/lessons.md — required by the workflow rules below.

Run & Deploy

  • Run locally: python3 -m http.server 8000 from the repo root, then open http://localhost:8000. Opening index.html directly via file:// also works but breaks if you later add features that need a real origin.
  • Test on a phone over LAN: same server; visit http://<your-laptop-ip>:8000 from the phone (laptop and phone on the same Wi-Fi).
  • Deploy: GitHub Pages serving from main / root. No build step — pushing to main is the deploy.

Workflow & Standards

Workflow Orchestration

0. Session Bootstrap — MANDATORY, NO EXCEPTIONS

Before doing ANY work:

  1. Read notes/lessons.md — if it doesn't exist, you are blocked until you create it
  2. Write notes/todo.md with your plan — if this file has no plan for the current task, you are blocked until it does
  3. You may NOT write code, create branches, or spawn subagents until both files exist and are populated

These are not optional. Skipping them is a bug in your workflow.

1. Plan Mode Default

  • Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
  • If something goes sideways, STOP and re-plan immediately - don't keep pushing
  • Use plan mode for verification steps, not just building
  • Write detailed specs upfront to reduce ambiguity

2. Subagent Strategy

  • Use subagents liberally to keep the main context window clean
  • Offload research, exploration, and parallel analysis to subagents
  • For complex problems, throw more compute at it via subagents
  • One task per subagent for focused execution

3. Self-Improvement Loop

  • After ANY correction from the user: update notes/lessons.md with the pattern
  • Write rules for yourself that prevent the same mistake
  • Ruthlessly iterate on these lessons until mistake rate drops
  • Review lessons at session start for relevant project

4. Verification Before Done

  • Never mark a task complete without proving it works
  • Diff behavior between main and your changes when relevant 
    git diff main...HEAD
  • Ask yourself: "Would a staff engineer approve this?"
  • Run tests, check logs, demonstrate correctness
  • Verification can be delegated to a subagent
  • Update notes/lessons.md with relevant verification results

5. Demand Elegance (Balanced)

  • For non-trivial changes: pause and ask "is there a more elegant way?"
  • If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
  • Skip this for simple, obvious fixes - don't over-engineer
  • Challenge your own work before presenting it

6. Autonomous Bug Fixing

  • When given a bug report: just fix it. Don't ask for hand-holding
  • Point at logs, errors, failing tests — then resolve them
  • Zero context switching required from the user
  • Go fix failing CI tests without being told how

Task Management

  1. Plan First: Write plan to notes/todo.md with checkable items
  2. Verify Plan: Check in before starting implementation
  3. Track Progress: Present plan to user before starting implementation
  4. Explain Changes: High-level summary at each step
  5. Document Results: Add review section to notes/todo.md
  6. Capture Lessons: Update notes/lessons.md after corrections

File Formats

notes/todo.md

# Task: <name>
Branch: `task/<short-task-name>`
Date: YYYY-MM-DD

## Plan
- [ ] Step 1
- [ ] Step 2
- [ ] Step 3

## Subtasks (if parallel subagents used)
- [ ] Part A — branch: `task/<name>-part-a`
- [ ] Part B — branch: `task/<name>-part-b`

## Review
- Summary of changes
- Files touched
- Verification results

notes/lessons.md

# Lessons Learned

## YYYY-MM-DD — Short description
**Mistake**: What went wrong
**Root cause**: Why it happened
**Rule**: What to do differently going forward

Core Principles

Principle Meaning
Simplicity First Make every change as simple as possible. Minimal code impact.
No Laziness Find root causes. No temporary fixes. Senior developer standards.
Minimal Impact Changes touch only what's necessary. Avoid introducing bugs.
Parallel by Default If subtasks are independent, use parallel subagents.
Prove It Works Nothing is done until it's verified.
Use The Files todo.md and lessons.md are not decoration. Write to them or you're doing it wrong.