Claude MD Example for Machine Learning Project

Markdown files are the backbone of effective communication with Claude Code in machine learning workflows. Whether you are documenting datasets, writing model specifications, or creating training pipelines, structuring your prompts as well-organized markdown unlocks Claude’s full potential. This guide provides practical examples of using .md files for ML projects, showing you how to leverage Claude skills and build reproducible workflows.

Why Markdown Files Work Well with Claude

Machine learning projects involve complex specifications, data transformations, and model configurations that benefit from structured documentation. Markdown files provide a clean, readable format that Claude can parse and understand precisely. Unlike free-form conversation, markdown prompts allow you to define clear sections, code blocks, and hierarchical instructions that guide Claude’s responses.

When you work on ML projects, you typically deal with multiple stakeholders, varying environments, and complex dependencies. Using .md files as prompt templates ensures consistency across sessions and team members. You can version control your prompts alongside your code, making experiments reproducible and debuggable.

Structuring ML Project Prompts

A well-structured ML project prompt includes several key sections that help Claude understand your context and requirements. Consider this practical example:

# Model Training Prompt

## Project Context
- Objective: Build a sentiment classifier for customer reviews
- Dataset: 50,000 labeled reviews (positive/negative)
- Framework: PyTorch 2.0
- Target accuracy: 92%

## Data Specifications
- Input: Text reviews (max 512 tokens)
- Output: Binary classification (positive/negative)
- Preprocessing: Lowercase, remove special characters, tokenize with BERT tokenizer

## Requirements
1. Create data loading pipeline with proper train/val/test splits
2. Implement data augmentation for text (backtranslation, synonym replacement)
3. Use BERT-base-uncased as the backbone
4. Add custom classification head with dropout
5. Implement early stopping based on validation F1 score

## Constraints
- Training time under 4 hours on single GPU
- Model size under 150MB
- Inference latency under 50ms per sample

## Output Format
Provide complete training script with:
- Data loading and preprocessing
- Model architecture
- Training loop with metrics tracking
- Evaluation function
- Export script for inference

This structured approach gives Claude clear boundaries and expectations, resulting in more usable output. The sections break down complex requirements into digestible components that Claude processes systematically.

Using Claude Skills in ML Workflows

Claude’s ecosystem includes specialized skills that enhance ML workflows. When working with machine learning projects, several skills prove particularly valuable:

The tdd (test-driven development) skill helps you write comprehensive tests for your ML pipelines. Instead of manually crafting test cases, you can use TDD principles to validate data transformations, model outputs, and inference functions. This is essential for production ML systems where unexpected data or model behavior can cause significant issues.

# ML Testing Prompt with TDD Skill

## Context
Testing a scikit-learn pipeline for customer churn prediction

## Requirements
Using TDD principles, write tests for:
1. Data preprocessing steps handle missing values correctly
2. Feature engineering produces expected output shapes
3. Model predicts within reasonable confidence bounds
4. Pipeline serialization/deserialization works correctly
5. Edge cases (empty input, single class) are handled gracefully

## Test Framework
- pytest for test execution
- Hypothesis for property-based testing
- Coverage target: 90%

The pdf skill enables you to extract information from research papers and documentation. You can use it to process academic papers, extract model card information from PDFs, or parse documentation for implementation details. This is particularly useful when implementing new architectures based on research.

The xlsx skill helps you analyze experiment results stored in spreadsheets. When running multiple experiments, you often track hyperparameters and results in Excel files. Claude can read these files, perform statistical analysis, and generate insights about which configurations work best.

The supermemory skill provides persistent context across sessions. For long-running ML projects, you can maintain project memory that includes architectural decisions, failed experiments, and lessons learned. This helps maintain consistency when you return to a project after weeks or months.

Documenting ML Projects with Markdown

Beyond prompts, markdown serves as an excellent format for ML project documentation. A comprehensive project README guides both human collaborators and Claude when working on the project:

# Customer Sentiment Classifier

## Project Structure

├── data/ │ ├── raw/ # Original datasets │ ├── processed/ # Cleaned and transformed data │ └── splits/ # Train/val/test partitions ├── src/ │ ├── data/ # Data loading and preprocessing │ ├── models/ # Model architectures │ ├── training/ # Training loops and utilities │ └── evaluation/ # Metrics and evaluation logic ├── notebooks/ # Exploratory analysis ├── configs/ # Configuration files ├── results/ # Experiment outputs └── tests/ # Test suite

## Current Best Model
- Architecture: BERT-base-uncased + classification head
- Validation F1: 0.934
- Test F1: 0.921
- Training time: 2.5 hours on A100 GPU

## Key Decisions
1. Used BERT instead of RoBERTa due to smaller model size
2. Applied class weighting to handle imbalanced dataset
3. Implemented gradient accumulation for larger effective batch size

## Known Limitations
- Performance degrades on reviews longer than 512 tokens
- Struggles with sarcasm and irony detection
- Requires GPU for acceptable inference speed

Automating ML Pipelines with Claude

You can create reusable markdown templates for common ML tasks. These templates accelerate your workflow and ensure consistency:

# Experiment Configuration Template

## Experiment Name
[Descriptive name]

## Hypothesis
[What you expect to happen and why]

## Configuration
### Model
- Architecture: [model name]
- Hyperparameters: [key parameters]

### Data
- Dataset: [name and version]
- Preprocessing: [steps applied]
- Augmentation: [techniques used]

### Training
- Epochs: [number]
- Batch size: [size]
- Learning rate: [rate]
- Optimizer: [name]
- Scheduler: [type if applicable]

## Success Metrics
- Primary: [main metric to optimize]
- Secondary: [additional metrics]
- Target values: [specific thresholds]

## Expected Runtime
- Training: [estimated time]
- Evaluation: [estimated time]

Version Control for ML Prompts

Treating your prompts as code offers significant advantages. Store prompt templates in your repository alongside your ML code. This practice enables you to track how your interactions with Claude evolve over time, compare prompt effectiveness, and share successful patterns with your team.

When you find a prompt that produces excellent results, document why it works. Include the prompt version in your experiment tracking. This creates a feedback loop where your ML development process continuously improves.

Using Claude with well-structured markdown files transforms how you develop machine learning projects. The combination of clear prompts, appropriate skills, and comprehensive documentation creates a powerful workflow that scales with your project complexity.

Built by theluckystrike — More at zovo.one