Claude Code Tutorial
with Raindrop MCP

Learn to build production-grade applications with Claude Code and Raindrop MCP

Claude Code + Git Efficiency Tutorial

Build a Token-Optimized To-Do App

Master the Disposable Intern Model with Professional Git Workflow

Philosophy: The Disposable Intern Model + Git Safety Net

Why this matters: Think of Claude like hiring a temporary worker, and Git as your security camera system. If you hired someone to paint one room, you'd take a photo before they start (git commit), let them work on that one room, then take another photo when done. If they mess up, you can always repaint (git reset).

Each Claude session should be:

  • Isolated: One task, minimal context
  • Tracked: Git commit before and after
  • Reversible: Can always roll back
  • Documented: Clear commit messages

This prevents:

  • Lost work: Everything is committed
  • Cascading failures: Can revert bad changes
  • Context confusion: Git branches isolate work
  • Token waste: Can show Claude just the diff

What We're Building

A decomposed to-do application with:

Backend Service: Standalone API (git branch: backend-core)
Frontend Interface: Static HTML/JS (git branch: frontend-core)
Test Infrastructure: Gaming-resistant tests (git branch: test-suite)
Guardian Tools: Protection system (git branch: tooling)
Main Branch: Integrated, working application

Why Git + decomposition? Each component lives in its own branch during development, merges to main only when complete and tested. Like building rooms separately then assembling the house.

Prerequisites

Before starting this tutorial, please ensure you have the following tools installed and configured.

  • Claude Code and Git: This tutorial assumes you have access to and are comfortable running Claude Code and Git.
  • VS Code with Claude Code Extension: While you can use any code editor, Visual Studio Code is highly recommended for its powerful features and extension ecosystem.
  • VS Code Makefile Tools Extension: This extension, provided by Microsoft, is essential for Visual Studio Code to correctly recognize and run Makefile commands. You can find it in the VS Code Extensions Marketplace.

PHASE 0: Git Setup and Strategy (3 minutes)

Step 0.1: Initialize Git Repository

mkdir todo-app
cd todo-app
git init

Why Git from the start?

  • Track everything: Even your initial planning
  • Time machine: Can always go back to any point
  • Parallel development: Branches allow multiple Claude sessions
  • Clear history: See exactly how the app evolved

Step 0.2: Create .gitignore

cat > .gitignore << 'EOF'
# Dependencies
node_modules/
package-lock.json

# Test artifacts
coverage/
.test_baselines/

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Temporary
*.tmp
*.log
tmp/
temp/

# Build outputs
dist/
build/
EOF

git add .gitignore
git commit -m "Initial commit: Add .gitignore"

Why commit .gitignore first?

  • Clean history: Prevents accidentally committing unwanted files
  • Sets standards: Everyone working on project follows same rules
  • Protects secrets: Ensures .env files never get committed
  • Reduces noise: Keeps git status clean and readable

PHASE 1: Decomposition & Architecture (5 minutes)

Step 1: Create Project Structure with Git Tracking

# Create all directories
mkdir -p backend frontend tests/api tests/backend tests/frontend tests/integration tools docs

# Create README for documentation
cat > README.md << 'EOF'
# Todo App

## Structure
- `/backend` - API service
- `/frontend` - Web interface
- `/tests` - Test suites
- `/tools` - Automation scripts
- `/docs` - API documentation

## Branches
- `main` - Stable, integrated code
- `backend-*` - Backend features
- `frontend-*` - Frontend features
- `test-*` - Test development
- `fix-*` - Bug fixes
EOF

git add README.md
git commit -m "docs: Add project structure and README"

Why commit structure first?

  • Establishes foundation: Clear project organization from start
  • Documents intent: README explains the plan
  • Creates baseline: Can always return to clean structure
  • Branch strategy clear: Everyone knows where features go

Step 2: Create Root claude.md with Git Awareness

Copy and paste this entire command block into your terminal to create the claude.md file with all content:

cat > claude.md << 'EOF'
# TODO APP - GROUND RULES

## GIT WORKFLOW RULES
- **ALWAYS** read current git status before making changes
- **NEVER** modify files without checking git diff first
- **COMMIT** after each successful change
- **BRANCH** for new features (feature/name pattern)
- **TEST** before committing
- **MSG FORMAT**: type: description (feat:, fix:, test:, docs:, refactor:)

## ARCHITECTURE OVERVIEW
- Backend: Standalone todo service (Node.js/Express)
- Frontend: Static HTML/JS client
- Communication: HTTP/JSON only
- Storage: JSON file (no database setup)
- **NO CROSS-CONTAMINATION** between components

## TECHNOLOGY STACK
- Backend: Node.js 18+, Express only
- Frontend: Vanilla HTML/CSS/JavaScript
- Testing: Jest for backend, simple assertions for frontend
- Version Control: Git with feature branches

## CRITICAL CONSTRAINTS
- **NO** external dependencies beyond specified
- **NO** frameworks or libraries not listed
- **NO** modification of test files during implementation
- **NO** abstraction layers or future-proofing
- **SINGLE FILE** implementations preferred
- **GIT COMMIT** after each working change

## STATE MACHINE
Work proceeds in phases:
1. Structure → Documentation → Tests → Implementation
2. Each phase tracked in Git
3. Each phase must be complete before next
4. Tools verify phase completion

## GIT BRANCH STRATEGY
- main: Always working, all tests pass
- backend-{feature}: Backend development
- frontend-{feature}: Frontend development
- test-{component}: Test development
- fix-{issue}: Bug fixes
- Each branch merges to main only when tests pass

## COMMIT MESSAGE CONVENTION
- feat: New feature
- fix: Bug fix
- test: Test addition/modification
- docs: Documentation
- refactor: Code restructuring
- chore: Maintenance tasks

## FILE NAMING CONVENTIONS
- Tests: test_*.js
- Tools: tool_*.js
- Single entry points: server.js, index.html
EOF

After pasting and pressing Enter, the file will be created. Now verify and commit it:

git add claude.md
git commit -m "docs: Add Claude ground rules with Git workflow"

Why Git rules in claude.md?

  • Claude understands version control: Will check git status before changes
  • Commit messages consistent: Claude follows the convention
  • Branch awareness: Claude knows to work in branches
  • Prevents accidents: Claude won't commit broken code

Step 3: Create a Dynamic CODE_MAP.md 🗺️

To make future feature development more efficient, we'll create a single, human-readable file that acts as a dynamic map of the codebase. It will link features to specific files and line numbers. This document will be kept up-to-date and provided to the LLM to significantly reduce context and token usage.

claude "TASK: Create a dynamic code map for the project
CONTEXT: The purpose of this document is to track the location of features, files, and code lines to make future LLM-powered development more efficient.

DELIVERABLE: CODE_MAP.md

CONTENT REQUIRED:
# CODE MAP

## Project Structure
- `/backend`: API service
- `/frontend`: Web interface
- `/tests`: All test suites
- `/tools`: Helper scripts and automation
- `docs/api-spec.md`: API contract

## Backend Code Map
### server.js
- `[TBD]`: Express server setup
- `[TBD]`: GET /api/todos - List all todos
- `[TBD]`: POST /api/todos - Create todo
- `[TBD]`: PUT /api/todos/:id - Update todo
- `[TBD]`: DELETE /api/todos/:id - Delete todo

## Frontend Code Map
### index.html
- `[TBD]`: HTML structure
- `[TBD]`: CSS styles
- `[TBD]`: JavaScript functions
- `[TBD]`: API calls
- `[TBD]`: Event handlers

## How to use this document
- When a feature is added or modified, update this document with the relevant file path and line number.
- Always include this document in the CONTEXT of future Claude Code sessions.

AFTER CREATING:
- git add CODE_MAP.md
- git commit -m 'docs: Add dynamic code map document'"

Why create this document now?

  • Token Efficiency: You can show this small document to the LLM instead of the entire codebase, drastically reducing token usage.
  • Streamlined Development: The LLM knows exactly where to make changes, eliminating the need to "scan" the project.
  • Collaboration: It serves as a clear, high-level overview for any developer working on the project.

PHASE 2: API Contract Definition with Branching (5 minutes)

"Control + C" twice to exit Claude Code session

Step 4: Create Documentation Branch

git checkout -b docs-api-spec

Why a separate branch?

  • Isolation: API design doesn't affect main branch
  • Review possible: Can review API before implementation
  • Parallel work: Others can work while you design API
  • Clean history: API evolution tracked separately

Step 5: Define API Contract

claude "TASK: Define todo API specification
CONTEXT: We're in branch 'docs-api-spec'

DELIVERABLE: /docs/api-spec.md

ENDPOINTS TO DEFINE:
- GET /api/todos - List all todos
- POST /api/todos - Create todo
- PUT /api/todos/:id - Update todo (mark complete)
- DELETE /api/todos/:id - Delete todo

REQUEST/RESPONSE FORMATS:
- Create: {text: string} → {id, text, completed, createdAt}
- Update: {completed: boolean} → {id, text, completed, createdAt}
- List: → [{id, text, completed, createdAt}]
- Delete: → {success: true}

ERROR RESPONSES:
- 400: {error: 'Invalid input'}
- 404: {error: 'Todo not found'}
- 500: {error: 'Server error'}

VALIDATION RULES:
- Text: required, 1-500 characters
- ID: UUID format
- Completed: boolean only

AFTER CREATING:
- Run: git add docs/api-spec.md
- Run: git commit -m 'docs: Add API specification'
- Do NOT merge to main yet"

Step 6: Create Backend Component Documentation

First, "Control + C" twice to exit previous Claude Code session, then

claude "TASK: Create backend component documentation
WORKING BRANCH: docs-api-spec

DELIVERABLE: /backend/claude.md

CONTENT REQUIRED:
# BACKEND SERVICE RULES

## PURPOSE
Todo CRUD operations service following /docs/api-spec.md

## TECHNOLOGY CONSTRAINTS
- Node.js 18+, Express only
- No external dependencies beyond Express
- Single file implementation (server.js)

## API CONTRACT
See /docs/api-spec.md for complete specification

## FILE STRUCTURE
- /backend/server.js - Main service file
- /backend/package.json - Dependencies
- Port: 3000

## TESTING REQUIREMENTS
- All endpoints must pass /tests/backend/test_todo_service.js
- Run tests with: npm test or node test_todo_service.js

## CODE MAP (Update as implementation progresses)
### /backend/server.js
- Server setup: lines [TBD]
- Routes: lines [TBD]
- Todo storage: lines [TBD]
- Validation: lines [TBD]

### To add new endpoint:
1. Add route definition
2. Add validation
3. Update CODE MAP

## CRITICAL RULES
- **NEVER** import frontend code
- **NEVER** modify test files
- **ALWAYS** validate input per API spec
- **ALWAYS** return exact format from API spec

AFTER CREATING:
- git add backend/claude.md
- git commit -m 'docs: Add backend component rules'"

Step 7: Create Frontend Component Documentation

First, "Control + C" twice to exit previous Claude Code session, then

claude "TASK: Create frontend component documentation
WORKING BRANCH: docs-api-spec

DELIVERABLE: /frontend/claude.md

CONTENT:
# FRONTEND SERVICE RULES

## PURPOSE
Todo user interface that communicates with backend API

## TECHNOLOGY CONSTRAINTS
- Vanilla HTML/CSS/JavaScript only
- No frameworks or libraries
- Single file (index.html with embedded CSS/JS)

## API INTEGRATION
- Backend URL: http://localhost:3000
- All API calls to /api/todos endpoints
- See /docs/api-spec.md for formats

## UI REQUIREMENTS
- Input field for new todos
- List display of all todos
- Checkbox for completion
- Delete button per todo
- Error message display area
- Loading states during API calls

## CODE MAP (Update as implementation progresses)
### /frontend/index.html
- HTML structure: lines [TBD]
- CSS styles: lines [TBD]
- JavaScript functions: lines [TBD]
- API calls: lines [TBD]
- Event handlers: lines [TBD]

## CRITICAL RULES
- NO external dependencies
- NO server-side code
- Must handle API errors gracefully
- Must show connection errors clearly
- All API responses must be validated

AFTER CREATING:
- git add frontend/claude.md
- git commit -m 'docs: Add frontend component rules'"

Step 8: Create Test Component Documentation

First, "Control + C" twice to exit previous Claude Code session, then

claude "TASK: Create test suite documentation
WORKING BRANCH: docs-api-spec

DELIVERABLE: /tests/claude.md

CONTENT:
# TEST SUITE RULES

## PURPOSE
Gaming-resistant test suite that validates all components

## TEST CATEGORIES
1. API Contract Tests - Verify API matches specification
2. Backend Implementation Tests - Verify business logic
3. Frontend UI Tests - Verify user interface behavior
4. Integration Tests - Verify end-to-end workflows

## TESTING APPROACH
- External test data files (JSON)
- No inline assertions that can be gamed
- Test files are read-only during implementation
- All tests must fail before implementation

## TEST EXECUTION
- Individual: node tests/[category]/test_*.js
- All: node tools/run_tests.js
- With coverage: npm test

## PROTECTION RULES
- Test files cannot be modified during implementation
- Test guardian monitors file integrity
- Git tracks any test modifications
- Tests define success criteria before coding

## CRITICAL RULES
- NEVER modify test files to make them pass
- ALWAYS use external data files
- EVERY feature needs a test first
- ALL tests must pass before merge to main

AFTER CREATING:
- git add tests/claude.md
- git commit -m 'docs: Add test suite documentation'"

Step 9: Review and Merge All Documentation

# Review all documentation created
ls -la docs/
ls -la backend/claude.md
ls -la frontend/claude.md
ls -la tests/claude.md
ls -la CODE_MAP.md
# If everything looks good, merge
git checkout main
git merge docs-api-spec --no-ff -m "merge: Complete project documentation"
git branch -d docs-api-spec

# Tag documentation complete
git tag -a v0.1-docs -m "Documentation phase complete"

Why complete ALL documentation first?

  • No ambiguity: Every component knows its role
  • Parallel work: Multiple developers can start simultaneously
  • Test-driven: Documentation defines what tests should verify
  • Token efficient: Claude has clear, focused context for each task

PHASE 3: Complete Test Infrastructure BEFORE Implementation (15 minutes)

This phase creates a comprehensive test infrastructure before any implementation begins.

Starting Phase 3 - Important: Start with a clean context for the testing phase

First, "Control + C" twice to exit previous Claude Code session, then:

# Create and switch to the test infrastructure branch
git checkout -b test-infrastructure

Why a separate branch for tests?

  • Isolation: Test development doesn't affect main
  • Review possible: Can review test suite before implementation
  • Defines success: Implementation can't start until tests are ready

Step 10: Test Guardian - Protects Test Files 🛡️

The first step is to create the guardian that will protect all the tests we're about to write. This ensures the tests cannot be modified later to make them pass, thereby guaranteeing the integrity of our test suite.

claude "TASK: Create test file integrity guardian with Git awareness
WORKING BRANCH: test-infrastructure

DELIVERABLE: /tools/test_guardian.js

FUNCTIONALITY:
- Store MD5 hashes of all test files in a baseline file.
- Detect modifications to test files by comparing current hashes to the baseline.
- Integrate with `git status` to warn if uncommitted changes exist in test files.
- Prevent gaming by modification.

COMMANDS:
- `node tools/test_guardian.js baseline` - Store hashes of all test files.
- `node tools/test_guardian.js check` - Detect changes and report if files have been modified.
- `node tools/test_guardian.js git-check` - Compare with `git` and report uncommitted changes.

MONITORING:
- All files matching `/tests/**/*.js` and `/tests/**/*.json`
- Store hashes in `/tools/.test_hashes.json`

OUTPUT:
- Clean: '✓ All test files unchanged'
- Modified: '✗ TEST FILES MODIFIED: [list]'
- Git status: '⚠ Uncommitted test changes detected'

AFTER CREATING:
- `git add tools/test_guardian.js`
- `git commit -m 'feat: Add test guardian with git integration'`"

Step 11: API Contract Tests - Verify API Spec Compliance 📝

These tests are a "black box" check that verifies the backend API matches the specification we wrote. They are crucial because the frontend and any other clients will depend on this contract.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create API contract tests
WORKING BRANCH: test-infrastructure

DELIVERABLES:
1. /tests/api/test_api_contract.js
2. /tests/api/api_data.json

CONTEXT:
- The tests must strictly follow the API specification in `/docs/api-spec.md`.
- These tests do not use any internal backend logic; they simply make HTTP requests to `http://localhost:3000`.

TEST DATA STRUCTURE (api_data.json):
{
  "testCases": [
    {
      "endpoint": "/api/todos",
      "method": "POST",
      "payload": { "text": "Walk the dog" },
      "expectedStatus": 200,
      "expectedKeys": ["id", "text", "completed", "createdAt"]
    },
    {
      "endpoint": "/api/todos",
      "method": "POST",
      "payload": { "text": "" },
      "expectedStatus": 400,
      "expectedError": "Invalid input"
    },
    {
      "endpoint": "/api/todos/123",
      "method": "PUT",
      "payload": { "completed": true },
      "expectedStatus": 404,
      "expectedError": "Todo not found"
    }
  ]
}

REQUIREMENTS:
- Use an external JSON file (`api_data.json`) for test cases.
- Test all API endpoints: `GET`, `POST`, `PUT`, `DELETE`.
- Verify correct status codes and error messages for both success and failure cases.
- All tests must fail initially because no backend implementation exists yet.

AFTER CREATING:
- `mkdir tests/api`
- `git add tests/api/`
- `git commit -m 'test: Add API contract tests'`"

Step 12: Backend Implementation Tests - Tests Business Logic ⚙️

These tests are specifically for the backend service's internal logic. They will be more granular, verifying that the CRUD operations correctly manipulate the internal data store (the in-memory array).

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create backend implementation tests
WORKING BRANCH: test-infrastructure

DELIVERABLES:
1. /tests/backend/test_todo_service.js
2. /tests/backend/backend_data.json

CONTEXT:
- These tests will verify the internal business logic of the backend.
- They will be written with a testing framework like Jest, but without a real server running.

TEST DATA STRUCTURE (backend_data.json):
{
  'createTests': [
    {input: {text: 'Buy milk'}, expected: {text: 'Buy milk', completed: false}},
    {input: {text: ''}, expectedError: 'Invalid input'},
    {input: {}, expectedError: 'Invalid input'}
  ],
  'updateTests': [
    {id: 'test-id-1', update: {completed: true}, expected: {completed: true}},
    {id: 'invalid-id', expectedError: 'Todo not found'}
  ],
  'deleteTests': [
    {id: 'test-id-1', expectedSuccess: true},
    {id: 'invalid-id', expectedError: 'Todo not found'}
  ]
}

REQUIREMENTS:
- Load test cases from external JSON (`backend_data.json`).
- Test each CRUD operation (create, read, update, delete) thoroughly.
- Test error conditions and edge cases, such as invalid input or non-existent IDs.
- The tests should report results clearly and must fail initially.

AFTER CREATING:
- `mkdir tests/backend`
- `git add tests/backend/`
- `git commit -m 'test: Add backend implementation tests'`"

Step 13: Frontend UI Tests - Tests User Interface 🖼️

These tests ensure the frontend interface behaves correctly. They check for the presence of UI elements, simulate user interactions (like clicking a button or typing into a field), and verify that the UI updates as expected in response.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create frontend UI tests
WORKING BRANCH: test-infrastructure

DELIVERABLES:
1. /tests/frontend/test_ui.js
2. /tests/frontend/frontend_data.json

CONTEXT:
- These tests will be written in plain JavaScript to be run in a browser environment.
- They will verify that the HTML elements are rendered correctly and respond to user actions.

TEST DATA STRUCTURE (frontend_data.json):
{
  "testCases": [
    {"type": "elementExists", "selector": "#todo-input", "message": "Input field exists"},
    {"type": "elementExists", "selector": "#add-button", "message": "Add button exists"},
    {"type": "clickAndVerify", "input": "New todo", "expectedText": "New todo", "message": "Add button creates todo item"},
    {"type": "stateChange", "selector": ".todo-item .checkbox", "action": "click", "expectedClass": "completed", "message": "Checkbox toggles completion state"},
    {"type": "removal", "selector": ".todo-item .delete-button", "action": "click", "expectedRemoval": true, "message": "Delete button removes item"}
  ]
}

REQUIREMENTS:
- Load test cases from external JSON (`frontend_data.json`).
- Use simple assertions to verify UI state.
- Test the presence of key elements, adding new todos, marking them as complete, and deleting them.
- All tests must fail initially.

AFTER CREATING:
- `mkdir tests/frontend`
- `git add tests/frontend/`
- `git commit -m 'test: Add frontend UI tests'`"

Step 14: Integration Tests - Test End-to-End Workflows 🚀

These are the most comprehensive tests. They verify that the entire system works together, from the frontend UI all the way to the backend and back again. They simulate a real user journey.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create end-to-end integration tests
WORKING BRANCH: test-infrastructure

DELIVERABLES:
1. /tests/integration/test_e2e.js
2. /tests/integration/integration_data.json

CONTEXT:
- These tests simulate a full user workflow, from UI interaction to backend validation.
- They will assume the backend server is running and the frontend page is loaded.

TEST DATA STRUCTURE (integration_data.json):
{
  "testCases": [
    {"description": "Create a new todo", "actions": ["type 'Test todo' into #todo-input", "click #add-button"], "expected": {"element": ".todo-item", "text": "Test todo"}},
    {"description": "Mark a todo as complete", "actions": ["create 'Another todo'", "click .todo-item .checkbox"], "expected": {"element": ".todo-item.completed"}},
    {"description": "Delete a todo", "actions": ["create 'Todo to delete'", "click .todo-item .delete-button"], "expected": {"elementRemoved": ".todo-item"}}
  ]
}

REQUIREMENTS:
- Load test cases from external JSON (`integration_data.json`).
- Simulate user actions like typing, clicking, and waiting for UI updates.
- Verify that the final state of the UI is correct and reflects the backend's state.
- All tests must fail initially because no implementation exists yet.

AFTER CREATING:
- `mkdir tests/integration`
- `git add tests/integration/`
- `git commit -m 'test: Add end-to-end integration tests'`"

Step 15: Test Runner - Runs All Test Suites 🏁

With all the individual test files now in place, we can create the comprehensive test runner script. This script will sequentially execute all the test suites we just created and provide a clear, consolidated report of the results.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create comprehensive test runner
        WORKING BRANCH: test-infrastructure

        DELIVERABLE: /tools/run_tests.js

        FUNCTIONALITY:
        1. Check `git status` for uncommitted changes.
        2. Verify test file integrity by running the guardian (`node tools/test_guardian.js check`).
        3. Run all four test suites in a specific order:
           - API Contract tests
           - Backend Implementation tests
           - Frontend UI tests
           - Integration tests
        4. Report the results for each suite individually.
        5. Provide a clear summary of the overall status (e.g., 'FAILED', 'PASSED').

        TEST SUITES:
        - API Contract: /tests/api/test_api_contract.js
        - Backend: /tests/backend/test_todo_service.js
        - Frontend: /tests/frontend/test_ui.js
        - Integration: /tests/integration/test_e2e.js

        OUTPUT FORMAT:
        =====================================
        GIT STATUS: ✓ Working directory clean
        TEST INTEGRITY: ✓ All test files unchanged
        =====================================
        TEST RESULTS
        =====================================
        ✗ API Contract: 0/12 tests passed (no backend)
        ✗ Backend: 0/8 tests passed (not implemented)
        ✗ Frontend: 0/10 tests passed (not implemented)
        ✗ Integration: 0/5 tests passed (nothing to integrate)
        -------------------------------------
        OVERALL: FAILED (0/35 tests passed)
        =====================================
        Note: This is the expected output, as no implementation exists yet.

        AFTER CREATING:
        - `git add tools/run_tests.js`
        - `git commit -m 'feat: Add comprehensive test runner'`"

Step 16: Development Tools - Helper Tools for Development 🔧

To improve the developer experience and speed up the feedback loop, we'll create a few helper scripts that will be used during the implementation phase. These are essential for a professional workflow.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create development helper tools
WORKING BRANCH: test-infrastructure

DELIVERABLES:
1. /tools/watch_tests.js - Continuously run tests during development.
2. /tools/test_single.js - Run a specific test suite.
3. /tools/quick_check.js - Fast validation before commits.

TOOL 1 - `watch_tests.js`:
- Watch for file changes in `/backend` or `/frontend`.
- Automatically run the relevant test suite when files are modified.
- Clear the console and show results.
- Exit with Ctrl+C.

TOOL 2 - `test_single.js`:
- Usage: `node tools/test_single.js backend`
- Usage: `node tools/test_single.js frontend`
- Usage: `node tools/test_single.js api`
- Usage: `node tools/test_single.js integration`
- Run just one specific test suite for faster feedback.

TOOL 3 - `quick_check.js`:
- Run a quick validation check.
- This includes the guardian check and only the unit tests (API and Backend).
- It should skip the slower integration and frontend tests.
- Report results in under 5 seconds for rapid feedback.

AFTER CREATING:
- `git add tools/`
- `git commit -m 'feat: Add development helper tools'`"

Step 17: Create Makefile with Git Commands ⚙️

This step creates a final layer of automation, providing short, memorable commands that wrap the complex commands we've already created. This standardizes the project's workflow and improves the developer experience from the very start of implementation.

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Create Makefile with git-aware commands
WORKING BRANCH: test-infrastructure

DELIVERABLE: Makefile

COMMANDS NEEDED:
# Development
install: npm install in backend
start: node tools/start_app.js
test: node tools/run_tests.js
test-backend: node tools/test_single.js backend
test-frontend: node tools/test_single.js frontend

# Git workflow
status: git status with pretty formatting
branch: show current branch and recent commits
commit: test then commit with message prompt
push: test, commit, then push to origin

# Protection
guardian-baseline: node tools/test_guardian.js baseline
guardian-check: node tools/test_guardian.js check
check-all: guardian-check + git status + test

# Cleanup
clean: remove node_modules and temp files
reset-hard: git reset --hard HEAD (with confirmation)

Add help text explaining each command

AFTER CREATING:
- `git add Makefile`
- `git commit -m 'feat: Add Makefile with git integration'`"

Step 18: Set Test Baseline and Merge ✅

This is the final step of the test infrastructure phase. You will run the guardian for the first time to create the baseline of your test files, which are now all in place. Then, you'll merge everything into the main branch.

# Create the baseline for test protection
node tools/test_guardian.js baseline

# Commit the new baseline file
git add tools/.test_hashes.json
git commit -m "chore: Set test baseline for guardian"

# Run all tests to see they fail (expected!)
make test

# Review all the work in this branch
git log --oneline main..HEAD
git diff main...test-infrastructure --stat

# Merge to main
git checkout main
git merge test-infrastructure --no-ff -m "merge: Complete test infrastructure"

# Clean up and tag this milestone
git branch -d test-infrastructure
git tag -a v0.2-tests -m "All tests defined before implementation"

Why merge failing tests to main?

  • Tests define the goal: Failing tests show what needs to be built
  • Protection enabled: Test guardian is now active
  • Ready for implementation: Success criteria are clear
  • TDD principle: Red (fail) → Green (pass) → Refactor

PHASE 4: Backend Implementation with Git Flow (10 minutes)

NOW we can finally start implementing, with all documentation and tests in place!

Step 20: End the Previous Claude Session 🚪

Before you start a new task in a new Git branch, it's a best practice to close the current Claude session. This ensures the "disposable intern" model is followed and prevents any context overlap.

Step 21: Create Backend Feature Branch 🌿

This step creates a new, isolated workspace for our backend-specific development.

First, Press "Control + C" twice to exit previous Claude Code session, then:

In your terminal, run:

git checkout -b backend-core

Why a new branch?

  • Isolation: Backend bugs don't affect main.
  • Testing ground: Can experiment without fear.
  • Parallel friendly: Frontend can be built simultaneously.
  • Clear scope: This branch only touches the backend/ directory.

Step 22: Start New Claude Session 🤖

Now you can "summon" a new Claude agent, specialized for this backend task.

claude "TASK: Create simplest todo backend - echo only
WORKING BRANCH: backend-core (confirm with git branch)

CONTEXT TO READ:
- /docs/api-spec.md
- /tests/backend/test_todo_service.js
- /CODE_MAP.md

DELIVERABLE: /backend/server.js

REQUIREMENTS:
- Express server on port 3000
- GET /api/todos returns empty array []
- POST /api/todos echoes back input with generated ID
- No actual storage yet

GIT WORKFLOW:
1. Create server.js
2. Test with: `make test-backend`
3. If tests pass (partially): git add backend/server.js CODE_MAP.md
4. git commit -m 'feat: Add echo backend service'
5. Do NOT merge to main yet

CONSTRAINTS:
- DO NOT modify test files
- Check git status before committing"

Step 23: Incremental Backend Development

For each operation, create a small commit:

Add Create Operation:

First, Press "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Add CREATE operation to backend
WORKING BRANCH: backend-core

CONTEXT:
- Current git diff shows echo service working
- Read /backend/server.js
- Read /docs/api-spec.md create spec
- Read /CODE_MAP.md

MODIFY:
- /backend/server.js
- /CODE_MAP.md

ADD ONLY:
- In-memory todos array
- POST /api/todos saves to array
- GET /api/todos returns array

GIT WORKFLOW:
1. Make changes
2. Run: `make test-backend`
3. Check: git diff backend/server.js CODE_MAP.md
4. If good: git add backend/server.js CODE_MAP.md
5. git commit -m 'feat: Add create operation to backend'"

Add Update Operation:

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Add UPDATE operation to backend
WORKING BRANCH: backend-core

SHOW RECENT HISTORY: git log --oneline -3
READ CURRENT STATE: git diff HEAD backend/server.js
READ CONTEXT: /CODE_MAP.md

MODIFY:
- /backend/server.js
- /CODE_MAP.md

ADD ONLY:
- PUT /api/todos/:id endpoint
- Find todo by ID and update completed status
- Return updated todo

GIT WORKFLOW:
1. Run tests after changes
2. Review with: git diff
3. Commit: git commit -am 'feat: Add update operation to backend'"

Add Delete Operation:

First, "Control + C" twice to exit previous Claude Code session, then:

claude "TASK: Add DELETE operation to backend
WORKING BRANCH: backend-core

CHECK STATUS: git status
CHECK BRANCH: git branch
READ CONTEXT: /CODE_MAP.md

MODIFY:
- /backend/server.js
- /CODE_MAP.md

ADD ONLY:
- DELETE /api/todos/:id endpoint
- Remove todo from array
- Return success response

COMPLETE BACKEND WITH:
1. Run full test suite with: `make test`
2. If all backend tests pass:
   - git add -A
   - git commit -m 'feat: Complete backend CRUD operations'
3. Show: git log --oneline -5"

Step 24: Test and Merge Backend

First, "Control + C" twice to exit previous Claude Code session, then:

claude "Ensure all tests pass
make test-backend

# Review the complete backend implementation
git diff main...backend-core

# Check commit history
git log --oneline main..backend-core"

If everything looks all right:

# Merge to main
git checkout main
git merge backend-core --no-ff -m "merge: Complete backend implementation"
git branch -d backend-core

# Tag this milestone
git tag -a v0.1-backend -m "Backend API complete"

Why tag milestones?

  • Checkpoints: Can always return to working backend
  • Deployment ready: Tags mark stable versions
  • Documentation: Shows project progression
  • Rollback points: Easy to revert to known-good state

PHASE 5: Frontend Implementation with Parallel Branch (10 minutes)

📝 Note: This can be done in parallel with backend if you have multiple developers/Claude sessions!

Step 25: End the Previous Claude Session 🚪

Before you start a new task in a new Git branch, it's a best practice to close the current Claude session. This ensures the "disposable intern" model is followed and prevents any context overlap.

Press Ctrl+C twice to exit the running Claude Code session. You should see your normal terminal prompt return.

Step 26: Create Frontend Branch 🌿

This step creates a new, isolated workspace for our frontend-specific development.

In your terminal, run:

git checkout -b frontend-core

Step 27: Frontend Display Only

claude "TASK: Create todo display interface
WORKING BRANCH: frontend-core

DELIVERABLE: /frontend/index.html
CONTEXT: /CODE_MAP.md

CREATE:
- Single HTML file with embedded CSS/JS
- Input field and Add button
- Todo list display area
- Complete/Delete buttons per todo

FUNCTIONALITY:
- Local state only (no API yet)
- Add updates display
- Complete toggles strikethrough
- Delete removes from display

GIT WORKFLOW:
1. Create index.html
2. Test in browser
3. git add frontend/index.html CODE_MAP.md
4. git commit -m 'feat: Add frontend UI with local state'

NO API INTEGRATION YET"

Step 28: Add API Integration

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "TASK: Connect frontend to backend API
WORKING BRANCH: frontend-core

CHECK CURRENT STATE: git diff HEAD frontend/index.html
READ CONTEXT: /CODE_MAP.md

MODIFY:
- /frontend/index.html JavaScript section
- /CODE_MAP.md

ADD:
- Fetch calls to http://localhost:3000/api/todos
- Load todos on page load
- Create/Update/Delete via API
- Error handling for connection issues

TEST PROCESS:
1. Manually start the backend server in one terminal window by running: cd backend && node server.js
2. Open frontend/index.html in browser
3. Test all operations
4. Check browser console for errors

GIT WORKFLOW:
1. After testing works:
2. git diff frontend/index.html CODE_MAP.md (review changes)
3. git add frontend/index.html CODE_MAP.md
4. git commit -m 'feat: Add API integration to frontend'"

Why is this a normal step?

This step is a crucial part of a two-step frontend development approach, which is a widely-used best practice.

  • Local-State First: You build the UI and its functionality using local data. This isolates the frontend, allowing you to focus on the user experience and design without worrying about a running backend.
  • API Integration: Once the UI is stable, you replace the local-state logic with fetch calls to your live backend endpoints. This connects the two components, making the application dynamic and persistent.

This approach breaks a complex task into two manageable, independent parts, which is a core element of the decomposition philosophy we're following.

Your UI will pop up in the web browser window, likely with "Failed to load todos. Make sure the backend server is running." error at first.

You will have to restart the backend service for it to work. But first:

Step 29: Frontend Polish and Merge

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "Add loading states and better error messages to frontend
Show 'Loading...' during API calls
Show user-friendly error messages
git commit -am 'feat: Add loading states and error handling'"

Test everything together:

# Test everything together
make start

# If all works, merge
git checkout main
git merge frontend-core --no-ff -m "merge: Complete frontend implementation"
git branch -d frontend-core

# Tag the complete basic version
git tag -a v1.0-basic -m "Basic todo app complete"

PHASE 6: Integration and Tooling (5 minutes)

First, Press Ctrl+C twice to exit the running Claude Code session, then:

Step 30: Create Integration Branch

git checkout -b tooling-integration

Step 31: Create Start Script with Git Checks

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "TASK: Create a robust app startup script with git awareness
WORKING BRANCH: tooling-integration

DELIVERABLE: /tools/start_app.js
CONTEXT: /CODE_MAP.md

FUNCTIONALITY:
1. Check git status - warn if uncommitted changes
2. Show current branch and last commit
3. Start backend server on port 3000
4. Implement a **robust check for server readiness**. Instead of a fixed delay, the script must **poll the server's health check endpoint** (GET /) every 500ms for a maximum of 30 seconds.
5. If the server becomes available, open the frontend in a new browser tab.
6. If the server does not become available within 30 seconds, print an error message and exit.
7. Handle Ctrl+C gracefully, shutting down the server process cleanly.

AFTER CREATING:
- git add tools/start_app.js CODE_MAP.md
- git commit -m 'feat: Add robust startup script with git awareness'"

Step 32: Merge and Tag Complete Version

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude Test all the tools
make check-all
make start

# Merge tooling
git checkout main
git merge tooling-integration --no-ff -m "merge: Complete tooling and automation"
git branch -d tooling-integration

# Tag the complete version
git tag -a v1.0-complete -m "Complete todo app with tooling"

# Push everything to remote (if you have one)
git push origin main --tags

PHASE 7: Feature Addition Workflow with Git

Step 33: Create Feature Branch

First, Press Ctrl+C twice to exit the running Claude Code session, then:

# Always branch from main
git checkout main
git pull origin main  # If working with remote
git checkout -b feat-priority

Step 35: Update API Specification

claude "TASK: Add priority field to API spec
BRANCH: feat-priority (verify with git branch)

MODIFY: /docs/api-spec.md

ADD:
- priority field: high, medium, low
- Default: medium
- Add to all request/response examples

GIT WORKFLOW:
- git diff docs/api-spec.md
- git add docs/api-spec.md
- git commit -m 'docs: Add priority field to API spec'"

Step 36: Update Tests First

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "TASK: Add priority test cases
BRANCH: feat-priority

CHECK: git log --oneline -1 (verify API spec committed)

MODIFY: /tests/backend/test_data.json

ADD:
- Test cases for all three priority levels
- Test default priority
- Test invalid priority rejection

IMPORTANT: Run guardian baseline BEFORE modifying tests
- node tools/test_guardian.js baseline

AFTER CHANGES:
- git diff tests/backend/test_data.json
- git add tests/backend/test_data.json
- git commit -m 'test: Add priority field test cases'
- node tools/test_guardian.js baseline (update baseline)"

Step 37: Implement Backend Changes

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "TASK: Add priority to backend
BRANCH: feat-priority

SHOW CHANGES SO FAR: git log --oneline main..HEAD
READ CONTEXT: /CODE_MAP.md

MODIFY:
- /backend/server.js
- /CODE_MAP.md

ADD:
- priority field to todo object
- Validation for priority values
- Default to 'medium' if not provided

TEST AND COMMIT:
- `make test-backend`
- git diff backend/server.js CODE_MAP.md
- git commit -am 'feat: Add priority field to backend'"

Step 38: Update Frontend

First, Press Ctrl+C twice to exit the running Claude Code session, then:

claude "TASK: Add priority UI
BRANCH: feat-priority

CURRENT PROGRESS: git log --oneline -3
READ CONTEXT: /CODE_MAP.md

MODIFY:
- /frontend/index.html
- /CODE_MAP.md

ADD:
- Priority dropdown in add form
- Priority badge display (colored)
- high=red, medium=yellow, low=green

TEST AND COMMIT:
- Manual testing in browser
- git diff frontend/index.html CODE_MAP.md
- git commit -am 'feat: Add priority UI to frontend'"

Step 39: Test Integration and Merge

First, Press Ctrl+C twice to exit the running Claude Code session, then:

Claude Run all tests
make check-all

# Review all changes
git log --oneline main..HEAD
git diff main...HEAD

# Merge to main
git checkout main
git merge feat-priority --no-ff -m "merge: Add priority feature"

# Tag new version
git tag -a v1.1-priority -m "Add priority feature"

# Clean up
git branch -d feat-priority

Git Best Practices with Claude Code

The Golden Rules

Always Work in Branches

git checkout -b feat-{name}

Why? Keeps main stable, allows parallel work, easy to abandon failed experiments.

Commit Early and Often

git add -p  # Review changes piece by piece
git commit -m "type: specific description"

Why? Creates restore points, documents thinking process, easier debugging.

Use Semantic Commit Messages

  • feat: New feature
  • fix: Bug bug
  • test: Test addition/modification
  • docs: Documentation
  • refactor: Code restructuring
  • chore: Maintenance tasks

Review Before Merging

git diff main...feature-branch
git merge --no-ff -m "merge: Description"

Why? Catches issues before they hit main, preserves branch history.

Tag Stable Versions

git tag -a v1.0.0 -m "Release version 1.0.0"

Why? Mark deployable versions, easy rollback points, clear project progression.

Troubleshooting with Git

Common Issues and Solutions

Uncommitted Changes Blocking Branch Switch

git stash
git checkout other-branch
git stash pop

Merge Conflicts

claude-code "TASK: Resolve merge conflict"

Accidentally Committed to Main

git checkout -b feature-branch
git checkout main
git reset --hard origin/main

Need to Undo Last Commit

git reset --hard HEAD~1

The Professional Mindset

Think of your project as a living document:

  • Main branch: The published book
  • Feature branches: Draft chapters
  • Commits: Individual edits
  • Tags: Published editions
  • Tests: Fact-checkers

With this workflow, you can build complex applications with confidence, knowing that every change is tracked, tested, and reversible.

Happy building with Claude Code + Git!