From 99a18cb5acb592e6eda61048284cc6aa1bb06db3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Jan 2026 11:29:17 +0000 Subject: [PATCH] Add comprehensive CLAUDE.MD guide for AI assistants - Created detailed repository overview and structure documentation - Documented YAML schemas for lessons, modules, and videos - Added video script markdown format conventions - Included content workflow and best practices - Documented learning pathways and topic areas - Added common tasks and git workflow guidelines --- CLAUDE.MD | 227 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 CLAUDE.MD diff --git a/CLAUDE.MD b/CLAUDE.MD new file mode 100644 index 00000000..3110b680 --- /dev/null +++ b/CLAUDE.MD @@ -0,0 +1,227 @@ +# CLAUDE.MD - AI Assistant Guide for Content-Public + +## Repository Overview + +This is an educational content repository containing course materials for data science, machine learning, software engineering, and cloud/DevOps topics. The content is organized into units, lessons, and learning pathways. + +## Repository Structure + +``` +Content-Public/ +├── Content/ # Main content directory +│ ├── units/ # ✅ Production-ready course modules +│ ├── icebox/ # 🧊 Concept library / in-progress content +│ ├── to-do-complete/ # 📝 Content needing completion +│ ├── to-do-edit-and-deploy/ # 🚀 Content ready for editing/deployment +│ ├── archive/ # 📦 Old/legacy content +│ ├── backlog/ # 📋 Planned but unstarted content +│ ├── templates/ # 📄 YAML and markdown templates +│ ├── brand-assets/ # 🎨 Design assets +│ └── guidelines/ # 📚 Content guidelines +├── Pathways/ # Learning pathways/course bundles +└── test.ipynb # Test notebook +``` + +## Content Organization + +### Status Hierarchy + +1. **units/** - Production content, ready for learners +2. **to-do-edit-and-deploy/** - Content ready for final review and deployment +3. **to-do-complete/** - Content needing completion +4. **icebox/** - Concept library with 20+ topics in various stages +5. **backlog/** - Planned content not yet started +6. **archive/** - Legacy content, no longer in use + +### Topic Areas (in units/) + +- Cloud-and-DevOps +- Data-Analytics +- Data-Engineering +- Data-Handling +- Deep-Learning +- Essentials +- MLOps +- Machine-Learning +- Natural Language Processing +- Software-Engineering + +## File Formats and Schemas + +### lesson.yaml + +Every lesson must have a `lesson.yaml` file with the following structure: + +```yaml +id: +description: +prerequisites: + - + - +``` + +**Important**: +- `id` must be a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) +- `description` should be concise and learner-focused +- `prerequisites` is a list of UUIDs referring to other lessons that must be completed first + +### module.yaml + +Module-level configuration: + +```yaml +id: +description: +``` + +### video.yaml + +Video-specific metadata (when applicable): + +```yaml +id: +# Additional video-specific fields +``` + +### Video Scripts (video/script.md) + +Video scripts follow a specific markdown format: + +**Structure**: +- Use HTML comments for section headers: `` +- Use bullet points (`-`) for narration text +- Use underscores for actions/instructions: `_do this action_` + +**Example**: +```markdown + + +- This lesson covers Docker volumes +- We'll learn how to persist data outside containers + +_open terminal_ + + + +- To create a volume, use the docker volume create command + +_run `docker volume create myvolume`_ +``` + +## Working with Content + +### Creating New Content + +1. **Start with templates**: Use files in `Content/templates/` as starting points +2. **Generate UUIDs**: All lessons and modules need unique UUIDs +3. **Follow the structure**: + ``` + Lesson Name/ + ├── lesson.yaml + ├── video/ + │ └── script.md + └── [other assets] + ``` + +### Moving Content Through Workflow + +Content typically flows through this pipeline: +1. **backlog/** → Initial concept +2. **icebox/** → Development/drafting +3. **to-do-complete/** → Needs finishing touches +4. **to-do-edit-and-deploy/** → Ready for review +5. **units/** → Published and live + +### Editing Existing Content + +When modifying content: +- **Always preserve UUIDs** - Never change existing lesson/module IDs +- **Check prerequisites** - Ensure prerequisite chains remain valid +- **Maintain format** - Follow existing conventions for scripts and YAML +- **Test links** - If lessons reference each other, verify the connections + +## Learning Pathways + +The `Pathways/` directory contains predefined learning tracks: +- Python Essentials +- Machine Learning Essentials +- Deep Learning Essentials +- SQL Essentials +- Git & GitHub +- Pandas +- The Command Line +- Web Scraping +- Essential Data and File Types +- Intro to Data Engineering + +Each pathway is a curated sequence of lessons from various units. + +## Best Practices + +### DO: +- Use templates from `Content/templates/` for consistency +- Generate valid UUIDs for new content +- Write clear, learner-focused descriptions +- Follow the video script format with HTML comments and action markers +- Check prerequisites are valid UUIDs +- Keep content organized by topic area +- Use the workflow directories (to-do-*, icebox, etc.) + +### DON'T: +- Modify UUIDs of existing lessons +- Create lessons without proper YAML metadata +- Skip prerequisites - they ensure learning progression +- Mix production and draft content in `units/` +- Ignore the templates - they ensure consistency + +## Common Tasks + +### Finding a Specific Lesson +```bash +# Search by topic +find Content/units -name "*Docker*" -type d + +# Search by UUID +grep -r "ed1216b9-8db3-45d0-9940-e33cbc0beba1" Content/ +``` + +### Validating YAML Files +```bash +# Find all lesson.yaml files +find Content/ -name "lesson.yaml" + +# Check for required fields +grep -A 3 "^id:" Content/units/path/to/lesson.yaml +``` + +### Moving Content +When moving content between workflow stages: +1. Ensure all dependencies are in the right state +2. Verify UUIDs are intact +3. Update any pathway references if needed + +## Content Guidelines + +- **Clarity**: Content should be beginner-friendly where appropriate +- **Progression**: Lessons should build on prerequisites logically +- **Completeness**: Each lesson needs both YAML metadata and content +- **Consistency**: Follow the established formats and conventions +- **Modularity**: Lessons should be self-contained but well-connected + +## Git Workflow + +- Branch naming: Use descriptive names with `claude/` prefix +- Commits: Clear, descriptive commit messages +- Push: Always to the designated branch +- Don't push directly to main without approval + +## Additional Resources + +- Check `Content/guidelines/` for detailed content guidelines +- Refer to `Content/templates/` for up-to-date template examples +- Review `Content/brand-assets/` for visual consistency + +--- + +**Last Updated**: 2026-01-06 +**Maintained by**: RShahData