Scratch Workspace Management

This skill covers proper use of the .claude/.scratch/ directory for temporary, exploratory, and draft work.

Purpose

The scratch workspace provides a gitignored location for:

• Draft implementations
• Experimental code
• Temporary test files
• Planning documents
• Any work-in-progress that shouldn't be committed

Setup Checklist

Before creating scratch files:

1. Ensure directory exists

   mkdir -p .claude/.scratch
   

2. Verify gitignore

   Check .gitignore contains:

   .claude/.scratch
   

   If missing, add it:

   echo '.claude/.scratch' >> .gitignore
   

Directory Structure

Organize scratch files by purpose:

.claude/
├── .scratch/
│   ├── drafts/           # Work-in-progress implementations
│   │   └── feature-x.ts
│   ├── experiments/      # Exploratory code
│   │   └── perf-test.js
│   ├── notes/            # Planning and notes
│   │   └── architecture.md
│   └── temp/             # Truly temporary files
└── settings.json         # Claude settings (NOT scratch)

Best Practices

DO

• Create subdirectories for organization
• Use descriptive file names
• Clean up when work is complete
• Move finalized code to proper project locations

DON'T

• Put sensitive data in scratch (still on disk)
• Use scratch for files that should be committed
• Leave stale scratch files indefinitely
• Put scratch files outside .claude/.scratch/

Workflow

Starting Exploratory Work

# Create scratch area
mkdir -p .claude/.scratch/experiments

# Work on experiment
# ... create files in .claude/.scratch/experiments/

Promoting to Real Code

When scratch work is ready:

1. Review and refine the code
2. Move to appropriate project location
3. Delete scratch version
4. Commit the promoted code

Cleanup

Periodically clean scratch:

# Review what's in scratch
ls -la .claude/.scratch/

# Remove old experiments
rm -rf .claude/.scratch/experiments/old-test/

Integration with Other Tools

With Git

The .claude/.scratch directory is gitignored, so:

• git status won't show scratch files
• git add . won't stage scratch files
• Scratch files won't appear in commits

With IDE

Most IDEs will show .claude/.scratch in the file tree. You can:

• Add to IDE's exclude patterns
• Keep visible for easy access
• Use IDE's "mark as excluded" feature

Common Patterns

Draft Implementation

.claude/.scratch/drafts/
└── new-feature/
    ├── index.ts
    ├── types.ts
    └── test.ts

Performance Experiment

.claude/.scratch/experiments/
└── perf-comparison/
    ├── approach-a.ts
    ├── approach-b.ts
    └── benchmark.ts

Architecture Notes

.claude/.scratch/notes/
└── refactor-plan.md

Troubleshooting

Scratch files appearing in git status

# Verify gitignore entry
grep -r ".claude/.scratch" .gitignore

# If missing, add it
echo '.claude/.scratch' >> .gitignore

Directory doesn't exist

mkdir -p .claude/.scratch

Accidentally committed scratch files

# Remove from tracking but keep locally
git rm -r --cached .claude/.scratch
git commit -m "chore: remove scratch files from tracking"