meme-search: Instructions file for Claude Code

CLAUDE.md

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

📁 File Organization Guidelines

⚠️ IMPORTANT - Temporary Documentation Files:

• All temporary markdown files created without explicit user request MUST be saved to /plans/temp/
• Examples: exploration notes, research summaries, draft documentation, intermediate analysis
• Permanent documentation (user-requested plans, design docs) goes in /plans/
• The /plans/temp/ directory is git-ignored and not tracked in version control

🤖 Task Agent Usage Guidelines

IMPORTANT: Use specialized Task agents liberally for exploration, planning, and research tasks.

When to Use Task Agents

Explore Agent (use subagent_type=Explore):

• Understanding codebase structure and architecture
• Finding where features are implemented across multiple files
• Exploring error handling patterns, API endpoints, or design patterns
• Questions like "How does X work?", "Where is Y handled?", "What's the structure of Z?"
• Set thoroughness: quick (basic), medium (moderate), or very thorough (comprehensive)

Plan Agent (use subagent_type=Plan):

• Breaking down complex feature implementations
• Designing multi-step refactoring approaches
• Planning architectural changes or migrations

General-Purpose Agent (use subagent_type=general-purpose):

• Multi-step tasks requiring multiple tool invocations
• Documentation lookups via WebSearch/WebFetch
• Complex searches across many files with multiple rounds

Documentation Lookup Pattern

When encountering unfamiliar libraries, frameworks, or patterns:

1. Use Task agent with WebSearch/WebFetch to look up official documentation
2. Search for: Rails 8 features, Playwright APIs, Python FastAPI patterns, etc.
3. Example: "Look up Rails 8 Turbo Stream documentation to understand real-time updates"

Examples

// ❌ Don't: Manually grep/glob through unfamiliar codebase
grep -r "webhook" .

// ✅ Do: Use Explore agent
Task(subagent_type="Explore",
     prompt="Find all webhook implementations and explain how webhooks work in this Rails+Python microservices architecture",
     thoroughness="medium")

// ❌ Don't: Guess how to implement without research
// Implement feature based on assumptions

// ✅ Do: Use general-purpose agent for documentation lookup
Task(subagent_type="general-purpose",
     prompt="Research Rails 8 ActionCable best practices for WebSocket broadcasting, then summarize the recommended pattern for real-time updates")