# Create CLAUDE Files Plan

## Overview
This document outlines the strategy for creating comprehensive CLAUDE.md documentation files throughout the Storyteller SDK JavaScript codebase to provide context-aware guidance for AI assistants and developers.

## Goals
1. **Improve AI Assistant Effectiveness** - Provide domain-specific context in each major area of the codebase
2. **Accelerate Developer Onboarding** - Document patterns and conventions specific to each module
3. **Maintain Consistency** - Ensure all contributors follow established patterns
4. **Reduce Errors** - Prevent common mistakes by documenting gotchas and requirements

## Proposed CLAUDE.md File Structure

### Tier 1: Critical Path Files (High Priority)
These files are in the most frequently modified areas and would provide immediate value:

#### 1. `/src/CLAUDE.md`
- Overview of source code architecture
- Component hierarchy and relationships
- Service singleton patterns
- Common development workflows for src changes

#### 2. `/src/row/CLAUDE.md`
- List view component patterns
- Base class requirements
- How to add new row/grid views
- Styling conventions for row components

#### 3. `/src/stories/CLAUDE.md`
- Stories API service architecture
- Command pattern implementation
- Cache management strategies
- Story state management

#### 4. `/src/clips/CLAUDE.md`
- Clips API service architecture
- Clips vs Stories differences
- Swiper integration notes
- Clips player lifecycle

#### 5. `/demo/CLAUDE.md`
- Demo site architecture
- How to test SDK changes
- Adding new demo features
- Environment configuration for testing

### Tier 2: Core Infrastructure (Medium Priority)
These provide important context for infrastructure changes:

#### 6. `/src/infrastructure/CLAUDE.md`
- Service layer patterns
- Base service requirements
- Error handling strategies
- Logging conventions

#### 7. `/src/infrastructure/activity/CLAUDE.md`
- Analytics event patterns
- Delegate implementation
- Adding new activity types
- Event data requirements

#### 8. `/src/configuration/CLAUDE.md`
- Theme system architecture
- Configuration model patterns
- Adding new configuration options
- Theme inheritance rules

#### 9. `/src/storyView/CLAUDE.md`
- Story player architecture
- Player state management
- Navigation handling
- Engagement unit integration

#### 10. `/src/clipsView/CLAUDE.md`
- Clips player architecture
- Video player management
- Swiper.js integration
- Performance considerations

### Tier 3: Specialized Features (Lower Priority)
These are for specific feature areas:

#### 11. `/src/polls/CLAUDE.md`
- Poll system architecture
- Vote tracking
- Results display
- Integration with stories

#### 12. `/src/quizzes/CLAUDE.md`
- Quiz system architecture
- Score tracking
- Question types
- Results handling

#### 13. `/src/ads/CLAUDE.md`
- Ad integration patterns
- Ad configuration
- VAST support
- Ad tracking

#### 14. `/webpack/CLAUDE.md` (or in root with webpack configs)
- Webpack configuration overview
- Build target differences
- Bundle optimization
- Adding new entry points

## Content Template for Each CLAUDE.md

Each CLAUDE.md file should follow this structure:

```markdown
# [Module Name] CLAUDE.md

## Overview
Brief description of what this module does and its role in the SDK.

## Architecture
- Key patterns used
- Important classes/services
- Data flow

## Common Tasks
### Task 1: [Common development task]
Step-by-step instructions with code examples

### Task 2: [Another common task]
Step-by-step instructions with code examples

## Patterns & Conventions
- Naming conventions specific to this module
- Required patterns to follow
- Anti-patterns to avoid

## Dependencies
- What this module depends on
- What depends on this module
- External libraries used

## Testing
- How to test changes in this module
- Existing test patterns
- Mock requirements

## Gotchas & Important Notes
- Common mistakes to avoid
- Performance considerations
- Security requirements
- Breaking change considerations

## Related Files
- Links to related CLAUDE.md files
- Important source files
- Configuration files
```

## Implementation Strategy

### Phase 1: Foundation (Week 1)
1. Create Tier 1 files (5 files)
2. Test with actual development tasks
3. Refine based on usage

### Phase 2: Infrastructure (Week 2)
1. Create Tier 2 files (5 files)
2. Cross-reference with Tier 1 files
3. Update root CLAUDE.md with references

### Phase 3: Features (Week 3)
1. Create Tier 3 files (4 files)
2. Add webpack configuration docs
3. Final review and consistency check

## Success Metrics
- Reduced time to implement new features
- Fewer architectural pattern violations
- Improved AI assistant accuracy
- Faster developer onboarding

## Maintenance Plan
1. Update CLAUDE.md files when architecture changes
2. Review quarterly for accuracy
3. Add new files as new modules are created
4. Remove files when modules are deprecated

## Next Steps
1. Review and approve this plan
2. Create Tier 1 files
3. Test with development team
4. Iterate based on feedback
5. Continue with Tier 2 and 3

## Notes
- Each CLAUDE.md should be concise but comprehensive
- Focus on "how to work with this code" rather than "what this code does"
- Include actual code examples from the codebase
- Reference specific files with relative paths
- Keep synchronized with root CLAUDE.md