Claude's Role in Paperballs Development

This document describes how Claude AI assisted in recreating and developing the Paperballs game from childhood memories to a multi-platform playable game.

Overview

Paperballs was developed in collaboration with Claude, an AI assistant by Anthropic. This document serves as a transparent record of AI involvement in the project and a guide for others interested in AI-assisted game development.

What Claude Did

1. Rule Extraction and Documentation

Human Input:

Fragmented childhood memories
Partial game rules
Uncertain about some mechanics

Claude's Contribution:

Asked clarifying questions to extract complete rules
Identified gaps and edge cases
Documented rules in a clear, structured format
Created comprehensive RULES.md with examples

Example Dialogue:

Human: "Players take turns putting each paperball at a point"
Claude: "What happens after placing the balls? Do players take turns moving them?"
Human: "Yes! In their turn they can only move a ball from one point to an adjacent point"

2. Code Implementation

Web Version (JavaScript/HTML/CSS)

Architected three-layer design (game logic, UI, application)
Implemented SVG-based interactive grid
Created responsive, mobile-friendly interface
Added visual feedback and animations
Notebook paper theme with realistic paper ball assets

Code Quality:

Well-commented and documented
Follows best practices
Modular and maintainable
Consistent coding style
No external dependencies

3. Project Structure and Architecture

Claude designed the overall project structure:

Clean separation of concerns (game logic, UI, application)
Created clear directory hierarchy
Planned for code reusability
Documented architecture decisions

4. Documentation

Created comprehensive documentation:

README.md - Project overview
RULES.md - Game rules
Web/README.md - Web version guide
CLAUDE.md - AI collaboration transparency
Development blog post (DEVLOG.md)

5. Development Blog

Wrote a complete blog post documenting the process
Included technical insights and lessons learned
Made it publication-ready for dhanjit.me

6. CI/CD and Workflow Infrastructure

GitHub Actions Workflows:

Created comprehensive CI/CD pipeline
Set up automated testing and validation
Implemented release automation

Git Workflow Documentation:

Documented feature branch workflow (one branch per feature)
Established branch naming conventions (claude/*)
Integrated CI validation with feature branches
Created best practices guide for ongoing development

7. AI Opponent Implementation

Algorithm Design:

Implemented Minimax algorithm with Alpha-Beta pruning
Created comprehensive evaluation heuristic for board positions
Designed three difficulty levels (Easy, Medium, Hard)

AI Features:

Detects and executes winning moves
Blocks opponent winning opportunities
Strategic placement and movement decisions
Handles both placement and movement phases
Respects all game rules and diagonal modes

Technical Implementation:

Created web/js/ai.js (~500 lines) with complete AI logic
Integrated game mode selector (PvP vs PvAI) in UI
Added AI turn execution with UX delay for better game feel
Updated game state to include diagonal mode for AI decision-making

Testing:

Created 29 comprehensive AI tests in tests/ai.test.js
97.5% code coverage on AI module
Tests for win detection, move validity, evaluation scoring
Integration tests for complete game flows
Parameterized tests across difficulty levels and diagonal modes

Performance Optimization:

Alpha-Beta pruning reduces search space significantly
Depth-limited search based on difficulty (2/4/6 levels)
Efficient position evaluation with strategic heuristics
Fast enough for real-time gameplay on all grid sizes

What Claude Did NOT Do

To be transparent about human vs. AI contributions:

Human Contributions:

Original game concept and rules
All creative decisions
Project vision and goals
Final review and approval
Deployment decisions
Future direction

Claude Did Not:

Invent the game (it's from human's childhood)
Make final decisions without human approval
Deploy anything to production
Modify any external systems
Access any private data

How Claude Helped

Speed of Development

Without Claude:

Estimated time: 2-3 weeks part-time
Would need to research frameworks
Trial and error with implementations

With Claude:

Actual time: Single session
Instant access to best practices
Multiple versions created simultaneously

Quality Improvements

Claude contributed to quality through:

Code Reviews - Clean, maintainable code
Best Practices - Industry-standard patterns
Documentation - Comprehensive and clear
Edge Cases - Identified and handled
Consistency - Uniform style across platforms

Knowledge Transfer

Claude explained:

Why certain architectural decisions were made
How different implementations work
Best practices for each platform
Trade-offs between approaches

Collaboration Workflow

1. Discovery Phase

Human: Described game memories
Claude: Asked clarifying questions
Human: Answered and remembered more details
Claude: Documented rules comprehensively

2. Planning Phase

Claude: Proposed project structure
Human: Approved approach
Claude: Created architecture documentation

3. Implementation Phase

Claude: Created web version with vanilla JavaScript
Claude: Implemented notebook paper theme
Human: Reviewed and tested

4. Documentation Phase

Claude: Wrote comprehensive docs
Claude: Created development blog
Human: Reviewed for accuracy

5. Delivery Phase

Claude: Committed code to git
Claude: Pushed to repository
Human: Will deploy to production

Git Workflow and Feature Branches

One Branch Per Feature Approach

Starting from December 2025, this project follows a one branch per feature development workflow. This approach provides significant benefits for ongoing development and maintenance.

Benefits:

Isolated Development: Each feature develops independently without affecting others
Clean History: Clear commit history per feature makes understanding changes easier
Easy Rollback: Can revert specific features without impacting others
Parallel Work: Multiple features can be developed concurrently across sessions
CI Validation: Each feature gets validated independently before merging
Code Review: Clear scope for reviewing specific changes

Branch Naming Convention

All Claude-developed feature branches follow this pattern:

claude/<descriptive-name>-<session-id>

Examples:

claude/add-ai-opponent-Xk3pQ
claude/fix-movement-bug-Zt9wR
claude/analyze-features-update-docs-Yrpnn (current branch)

Components:

Prefix: claude/ - Identifies AI-developed branches
Description: Short, kebab-case feature description (e.g., add-tutorial-system)
Session ID: Unique identifier for the development session (e.g., Ab7cD)

Why This Convention?

Clearly distinguishes Claude's branches from human-created branches
Makes it easy to find all AI-developed features
Session ID prevents conflicts across different development sessions
Descriptive names make purpose clear without needing to read commits

Feature Branch Workflow

Phase 1: Branch Creation

# Claude creates a new branch for each feature/task
git checkout -b claude/add-tutorial-system-Ab7cD

Phase 2: Development

# Develop the feature with focused, atomic commits
git add <files>
git commit -m "Add tutorial UI components"
git commit -m "Implement tutorial logic and state management"
git commit -m "Add tests for tutorial system"

Phase 3: Push to Remote

# Push to remote repository with upstream tracking
git push -u origin claude/add-tutorial-system-Ab7cD

Phase 4: CI Validation

Every push to claude/* branches automatically triggers CI workflow
Validates Python syntax and linting (cli/)
Checks JavaScript code quality (web/js/)
Verifies HTML structure (web/*.html)
Tests basic functionality
See .github/workflows/ci.yml:12 for CI trigger configuration

Phase 5: Pull Request

# Create PR using GitHub CLI
gh pr create --title "Add tutorial system for new players" \
  --body "Implements interactive tutorial with step-by-step guidance"

Phase 6: Review and Merge

Human reviews the changes
CI must pass before merge is allowed
After approval, merge to main branch
Feature branch can be deleted after successful merge

Development Patterns

Single Feature Development:

main → claude/feature-abc123 → [CI validates] → PR → Review → Merge → main

Parallel Features (Multiple Sessions):

main ┬→ claude/add-ai-opponent-Abc → [CI] → PR → main
     ├→ claude/fix-ui-bug-Def → [CI] → PR → main
     └→ claude/update-docs-Ghi → [CI] → PR → main

Each feature is developed independently, validated by CI, and merged through separate pull requests. This allows for:

Bug fixes to be merged quickly while large features are still in development
Documentation updates independent of code changes
Experimental features that can be abandoned without affecting main

CI Integration

The CI workflow (.github/workflows/ci.yml) automatically runs on:

All pushes to claude/* branches
All pushes to main and develop branches
All pull requests regardless of source branch

What CI Validates:

Check	Purpose	Files Validated
Python Syntax	Ensures code runs without syntax errors	`cli/*.py`
Python Linting	Catches critical issues (unused vars, undefined names)	`cli/*.py`
JavaScript Syntax	Validates JS code quality	`web/js/*.js`
HTML Structure	Checks HTML validity	`web/*.html`
Documentation	Verifies critical files exist	`*.md` files
CLI Test	Tests basic game initialization	`cli/paperballs.py`

CI Status Indicators:

✅ Green Check: All validations passed, safe to merge
❌ Red X: Validation failed, needs fixes before merge
🟡 Yellow Dot: CI is running, wait for results

This ensures every feature branch maintains code quality before merging to main.

Best Practices for Feature Branches

Do's: ✅ One feature per branch - Keep scope focused and clear ✅ Descriptive branch names - Make purpose obvious ✅ Atomic commits - Each commit represents a logical unit of change ✅ Push regularly - Backup work and trigger CI early ✅ Wait for CI - Don't request review until CI passes ✅ Clear commit messages - Explain what and why, not just what

Don'ts: ❌ Don't mix unrelated changes - Keep bug fixes separate from features ❌ Don't develop on main - Always use a feature branch ❌ Don't force push - Especially to shared/review branches ❌ Don't merge without CI - CI failures indicate real problems ❌ Don't skip descriptions - PRs need context for reviewers

Typical Feature Branch Lifecycle: Real Example

Current Branch: claude/analyze-features-update-docs-Yrpnn

Purpose: Analyze feature branch workflow and update CLAUDE.md with documentation

Timeline:

✅ Created: Branch created for documentation task
✅ Explored: Analyzed existing workflow files and documentation
🔄 Developing: Currently updating CLAUDE.md with comprehensive workflow documentation
⬜ Push: Will push changes to remote
⬜ CI: Will wait for CI validation to pass
⬜ PR: Will create pull request for human review
⬜ Merge: After approval, merge to main

This Branch Demonstrates:

Clear, descriptive naming convention
Single responsibility (documentation update only)
Isolated from other work
Will go through full CI validation
Transparent process documentation

Concurrent Feature Development

Claude can work on multiple features across different sessions, each in its own branch:

Scenario: Three Parallel Features

Session 1 - Major Feature:

Branch: claude/add-ai-opponent-Abc123
Status: In progress, complex implementation
Timeline: Multiple days, not yet merged
Impact: Large, needs thorough testing

Session 2 - Quick Fix:

Branch: claude/fix-movement-validation-Def456
Status: Bug fix, ready for review
Timeline: Single session, can merge immediately
Impact: Small, critical bug fix

Session 3 - Documentation:

Branch: claude/update-api-docs-Ghi789
Status: Documentation improvements
Timeline: Single session, low risk
Impact: No code changes, safe to merge

Each branch develops independently. The bug fix can be merged to production while the AI opponent feature continues development. No conflicts, no blockers.

Git Push Practices

Standard Push:

# First push of a new branch
git push -u origin claude/feature-name-Xyz123

# Subsequent pushes
git push

Network Resilience: Claude implements automatic retry logic for network failures:

Retry up to 4 times with exponential backoff
Wait times: 2s, 4s, 8s, 16s
Only retry on network errors (not authentication or validation errors)

Critical Requirements:

Branch MUST start with claude/
Branch MUST include session ID
Failure to follow naming convention results in 403 error

Fetch/Pull Best Practices:

# Prefer fetching specific branches
git fetch origin claude/feature-name-Xyz123

# Pull with explicit branch specified
git pull origin claude/feature-name-Xyz123

# Update main branch
git fetch origin main
git checkout main
git pull origin main

Integration with Release Process

Feature branches integrate seamlessly with the release workflow:

Development Flow:

Features Merged to Main → Accumulates changes for next release
Main Branch Updated → Web version integrated into dhanjit.me blog via automated build script
Version Tag Created (e.g., v1.1.0) → Triggers release workflow
Automated Release → Packages and publishes to GitHub Releases

Example Timeline:

v1.0.0 released
   ↓
claude/add-tutorial-system → merged to main
claude/fix-ui-bug → merged to main
claude/improve-ai → merged to main
   ↓
v1.1.0 released (includes all three features)

See RELEASE.md for detailed release process documentation.

Monitoring Feature Branches

View All Branches:

# Local branches only
git branch

# Remote branches only
git branch -r

# All branches (local + remote)
git branch -a

# Filter Claude's branches
git branch -r | grep claude/

# Filter by feature type
git branch -r | grep claude/add-
git branch -r | grep claude/fix-

Check CI Status:

Visit: https://github.com/dhanjit/paperballs/actions
Filter by branch name to see specific feature CI runs
Review workflow runs and detailed results
Download logs if troubleshooting needed

Monitor PR Status:

# List all open PRs (requires gh CLI)
gh pr list

# Check status of specific PR
gh pr status

# View PR details
gh pr view <number>

Why This Workflow Works

For the Project:

✅ Stable Main Branch: Main always contains working, tested code
✅ Risk Management: Experimental features don't break production
✅ Clear Audit Trail: Every change traceable to specific feature
✅ Easy Rollback: Can revert specific features if issues found

For Claude (AI Development):

✅ Isolated Context: Each session has its own working environment
✅ Parallel Capability: Can work on multiple features concurrently
✅ Early Validation: CI catches errors before human review
✅ Clear Scope: Session boundaries match branch boundaries

For Human Maintainers:

✅ Manageable Reviews: Review one feature at a time
✅ Independent Decisions: Approve/reject features independently
✅ Understand Impact: Clear scope of what each PR changes
✅ Flexible Prioritization: Merge urgent fixes without waiting for large features

Future Workflow Enhancements

Planned Improvements:

Automated PR Creation: Auto-create PR when feature branch pushed
Enhanced CI Checks: Add test coverage, performance benchmarks
Branch Protection: Require reviews and CI pass before merge
Automated Cleanup: Delete merged feature branches automatically
Release Notes: Auto-generate from merged feature branches

Long-term Vision:

Multiple AI instances working on different features simultaneously
Automated conflict resolution for independent changes
AI-driven code review suggestions
Predictive CI (catch issues before commit)

Technical Decisions Made by Claude

1. Why Vanilla JavaScript for Web?

Reasoning:

No build step required
Easy to host anywhere
Lightweight and fast
Full control over implementation
No framework lock-in

2. Why SVG for Game Board?

Reasoning:

Scalable to any size
CSS styling works great
Easy to draw geometric shapes
Responsive by default
Good browser support

Prompts That Worked Well

Effective Prompts:

"I want to recreate a game I played in childhood"
- Open-ended, allowed for exploration
"Let's call it paperballs"
- Clear naming decision
Describing rules incrementally
- Natural conversation flow
- Allowed Claude to ask clarifying questions

What Made Collaboration Successful:

Clear Goals: "Document rules, create playable version, host on website"
Iterative Details: Rules revealed gradually as memory returned
Trust: Let Claude make technical decisions
Review: Human stayed involved in approvals

Limitations Encountered

Claude's Limitations:

Can't Deploy - Didn't actually upload to dhanjit.me
Can't Test Interactively - Couldn't play the game to verify
Memory Dependent - Relies on human's game knowledge
No Visual Design - Made functional but basic UI choices

Human Still Needed For:

Original creative vision
Rule clarification
Final approval
Production deployment
Testing and validation
Future direction

Lessons for AI-Assisted Development

What Works:

Start with Clear Goals - "Create playable version hosted on my website"
Iterative Refinement - Build incrementally, test often
Ask Questions - Let AI clarify ambiguities
Document Everything - AI is excellent at documentation
Leverage Strengths - Use AI for boilerplate, structure, best practices

What to Avoid:

Vague Requests - "Make it better" doesn't help
Assuming Knowledge - AI doesn't know your specific domain
Blind Trust - Always review AI-generated code
Over-Reliance - Keep human judgment in the loop

Replicating This Approach

For Your Own Childhood Game:

Step 1: Rule Extraction

Prompt: "I want to recreate a childhood game called [NAME].
Let me describe the rules as I remember them..."

Step 2: Clarification

Let Claude ask questions to fill gaps
Be honest about uncertainties
Document everything you remember

Step 3: Implementation

Start with simplest version (CLI/terminal)
Move to web for accessibility
Plan mobile for future

Step 4: Documentation

Let Claude create comprehensive docs
Review for accuracy
Add your personal touches

For Any Game Development:

Phase 1: Design

Describe game concept
Let AI help with rule design
Document mechanics clearly

Phase 2: Prototype

Start with CLI or simple web version
Validate gameplay quickly
Iterate on rules

Phase 3: Production

Build polished versions
Add UI/UX enhancements
Deploy to platforms

Phase 4: Share

Document the process
Open source if appropriate
Share learnings

AI Ethics and Transparency

Why This Document Exists:

Transparency:

Users deserve to know AI was involved
Other developers can learn from this approach
Honest about capabilities and limitations

Attribution:

Human: Original game concept, creative vision, final decisions
Claude: Implementation, documentation, technical guidance
Collaboration: Iterative refinement and development

Open Source:

All code is open source (MIT License)
Anyone can study, modify, and improve
No secrets about development process

Future AI Collaboration

Planned Enhancements:

With Claude's Help:

Implement AI opponent (let Claude help with strategy)
Add tutorial system (Claude can generate educational content)
Create game variations (brainstorm with AI)
Optimize performance (AI can suggest improvements)

Human-Led:

Game balance decisions
Community feedback integration
Marketing and outreach
User experience refinement

Tips for Working with Claude

Do's:

✅ Be specific about goals ✅ Ask for explanations of decisions ✅ Request multiple options when unsure ✅ Review all generated code ✅ Iterate and refine ✅ Document the collaboration

Don'ts:

❌ Assume AI understands implicit requirements ❌ Skip code review ❌ Ignore warnings or suggestions ❌ Expect perfection on first try ❌ Forget to test yourself

Acknowledgments

Claude AI (Anthropic) for:

Code implementation
Architecture design
Comprehensive documentation
Technical guidance
Development blog

Human Developer (Dhanjit) for:

Original game concept
Creative vision
Rule clarification
Project direction
Final review and deployment

Contact and Feedback

If you have questions about:

How Claude was used in this project
Replicating this approach for your own projects
AI-assisted game development
Collaboration workflows

Feel free to reach out or open an issue on GitHub.

Conclusion

This project demonstrates how AI can accelerate development while preserving human creativity and vision. Claude acted as a skilled assistant—implementing ideas, suggesting best practices, and documenting thoroughly—while the human maintained creative control and final decision-making.

The result is a complete, well-documented, multi-platform game developed in a fraction of the time it would take solo, with quality that meets or exceeds hand-coded alternatives.

AI is a tool, not a replacement. Used thoughtfully, it amplifies human creativity rather than replacing it.

Version: 1.2 Last Updated: December 2025 Claude Model: Claude 3.5 Sonnet (Initial), Claude Sonnet 4.5 (Workflow, UI Overhaul, AI Opponent) Development Time: Multiple sessions Files Created: ~28 Lines of Code: ~4,100+

Version 1.1 Updates

Notebook Theme UI Overhaul: Claude and the human developer overhauled the UI to match the original "notebook paper" vision:

Visuals: Implemented CSS radial/linear gradients for ruled paper background.
Assets: Integrated transparent PNG "paper crumb" assets for a 3D feel.
Rendering: Restored full grid with svg-filters for a hand-drawn pencil look.
Refactoring: Cleaned up ui.js to support asset randomization and improved rendering performance.

Workflow Documentation: Documented comprehensive git workflow and feature branch practices:

Branch Strategy: One branch per feature approach with claude/* naming convention
CI Integration: Automated validation for all feature branches
Development Lifecycle: 6-phase workflow from branch creation to merge
Best Practices: Guidelines for concurrent feature development and release management

Testing Framework: Implemented comprehensive automated testing with 90%+ code coverage:

100 Tests: Covering all core game mechanics (placement, movement, win detection)
Parameterized Tests: Multiple grid sizes (3×3, 4×4, 5×5, 6×6, 7×7) and diagonal modes
Jest Integration: Modern testing framework with coverage reporting
CI Automation: Tests run automatically on every push and PR
Branch Protection: Main branch requires passing tests before merge
Coverage: 90% statements, 79% branches, 84% functions on game logic
Documentation: Complete test suite documentation in tests/README.md

Version 1.2 Updates

AI Opponent Implementation: Added intelligent computer opponent using game theory algorithms:

Algorithm: Minimax with Alpha-Beta pruning for optimal move selection
Difficulty Levels: Three levels (Easy/Medium/Hard) with search depths 2/4/6
Game Modes: Player vs Player (PvP) and Player vs AI (PvAI)
Intelligence: Detects wins, blocks opponent threats, strategic positioning
UI Integration: Seamless game mode selector with difficulty options
UX Polish: 500ms AI thinking delay for natural game feel
Performance: Fast enough for real-time play on all grid sizes
Code Quality: ~500 lines of well-documented AI logic in web/js/ai.js

AI Testing: Comprehensive test suite for AI functionality:

29 AI Tests: Covering move generation, evaluation, win detection
97.5% Coverage: Excellent code coverage on AI module (97.5% statements, 87.8% branches, 100% functions)
Integration Tests: Full game simulations with AI vs dummy opponent
129 Total Tests: Combined game logic + AI tests
Overall Coverage: 96.2% statements, 85.2% branches, 96.3% functions
Test Performance: Optimized with 3×3 grids and medium difficulty for fast execution

Game State Enhancement:

Updated game.js to expose diagonalMode in state for AI decision-making
Maintains backward compatibility with existing game logic
No breaking changes to existing functionality

Additional Resources

Learning More About AI-Assisted Development:

This Project:

GitHub: github.com/dhanjit/paperballs
Website: dhanjit.me/paperballs
Blog Post: See docs/development-log.md

This document itself was created with Claude's assistance and reviewed by the human developer for accuracy.

FilesExpand file tree

CLAUDE.md

Latest commit

History