When AI Creates Documentation Faster Than You Can Clean It

TL;DR: AI generated 100+ docs in 2 weeks. Great for exploring ideas. Terrible for findability. The fix wasn't cleanup—it was 5-layer automation (gitignore, pre-commit hooks, CI, cleanup scripts, cursor rules) to prevent proliferation.

I'm building an AI assistant using Cursor with Claude. The AI is prolific—it generates planning docs, architecture explorations, implementation notes at 10x human speed.

After two weeks: over 100 markdown files in the root directory.

Then something broke.

What broke

Week 2, I needed to find the security architecture notes I'd written 5 days earlier. Spent 20 minutes grepping through files with "SECURITY" in the name:

SECURITY_REVIEW_FEEDBACK.md (outdated)
SECURITY_IMPLEMENTATION_DRAFT_v2.md (wrong version)
TEMP_SECURITY_NOTES.md (already deleted locally, but still in git)

Found it eventually: buried in PLANNING_PHASE_4_REVISED.md.

That was the moment I realized: AI's documentation speed is a feature until it becomes a liability.

Over 100 markdown files. Most stale within 48 hours. All cluttering the repo.

The pattern: AI loves creating new docs. It doesn't clean up old ones.

What Doesn't Work: Manual Cleanup

I tried discipline. "I'll just clean up as I go."

That lasted three days.

The problem: AI moves faster than my cleanup habits. By the time I remembered to delete a planning doc, there were five new ones.

Manual processes don't scale when your collaboration tool never sleeps.

What Works: Automated Prevention

I stopped trying to clean up after AI. I started preventing proliferation.

1. `.gitignore` Patterns

Block temporary files from ever being committed:

# Temporary session files
TEMP_*.md
*_TEMP.md
*_DRAFT*.md
 
# Planning exploration
PLANNING_*.md
EXPLORATION_*.md
 
# AI-generated scratch
scratch/
temp/

2. Pre-Commit Hook

Catch files that slip through:

#!/bin/bash
# .git/hooks/pre-commit
 
if git diff --cached --name-only | grep -E "TEMP_.*\.md"; then
  echo "🚨 ERROR: Attempting to commit temporary file"
  echo "These files must be deleted after reading."
  exit 1
fi

Physically impossible to commit temp files.

3. GitHub Actions CI Check

Final safety net:

# .github/workflows/hygiene.yml
name: Repository Hygiene
 
on: [push, pull_request]
 
jobs:
  check-temp-files:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for temporary files
        run: |
          if git ls-files | grep -E '^TEMP_.*\.md$'; then
            echo "🚨 Temporary files found in repository!"
            exit 1
          fi

Even if pre-commit is bypassed, CI catches it.

4. Cleanup Script

For local hygiene:

# package.json
{
  "scripts": {
    "cleanup:temp": "find . -name 'TEMP_*.md' -o -name '*_DRAFT*.md' | xargs rm -f"
  }
}

Runs at each commit via pre-commit hook. Keeps workspace clean automatically.

5. Cursor Rules

Enforce document creation patterns:

## Documentation Rules
 
**TEMP files:**
- Only create when context < 10%
- Must be deleted within 24 hours
- Never commit to git
 
**Planning docs:**
- Store in `docs/planning/`
- Not in root directory
- Name with date: `YYYY-MM-DD-description.md`
 
**Implementation docs:**
- Store in `docs/implementation/`
- Update when code changes
- Link to related code files

AI now knows where to put things. I don't have to remember.

The Enforcement Hierarchy

Layer 1: .gitignore (prevents accidental staging)
Layer 2: Pre-commit hook (blocks commits, runs cleanup)
Layer 3: CI check (blocks PRs)
Layer 4: Cleanup script (runs automatically)
Layer 5: Cursor rules (AI knows the rules)

Why all five? Because I'll bypass layer 1 ("just this once"). Layer 2 stops me. If I disable hooks, layer 3 catches it. Layer 4 cleans automatically. Layer 5 prevents AI from creating the mess in the first place.

What to Automate

Block these patterns from commits:

Temporary session files: TEMP_*.md, *_TEMP.md
Planning explorations: PLANNING_*.md, EXPLORATION_*.md
Draft versions: *_DRAFT*.md, *_v[0-9]*.md
AI scratch work: scratch/, temp/, .ai/
IDE artifacts: .cursor/, .vscode/settings.json (team-specific)

Keep these for collaboration:

Architecture decisions: docs/architecture/
Implementation plans: docs/implementation/
Runbooks: docs/runbooks/
API contracts: docs/api/

Rule of thumb: If it's valuable in 2 weeks, put it in docs/. If it's stale in 48 hours, block it from commits.

Lessons Learned

1. Discipline Fails, Automation Scales

Discipline works when you move slowly. AI moves fast. You need automated guardrails, not good intentions.

2. Git History Isn't a Filing Cabinet

Committing everything "because we can always look back" creates noise. Git history should show intentional decisions, not brainstorming artifacts.

3. Make Bad Patterns Impossible

Don't rely on remembering to clean up. Make proliferation impossible via automation.

Your Checklist

Copy these into your project today:

[ ] Add temp file patterns to .gitignore
[ ] Create pre-commit hook blocking temp files
[ ] Add CI check for repository hygiene
[ ] Add cleanup script to package.json (runs at commit)
[ ] Add cursor rules for document creation patterns
[ ] Document what belongs in docs/ vs what's temporary

What I'm doing now

The automation is live. Every temp file gets auto-blocked. Every planning doc goes in docs/planning/ or gets deleted. Cleanup script runs at each commit.

The repo is clean not because I'm disciplined, but because the system doesn't give me a choice.

Three weeks in, zero clutter in the root. The automation works.

Now I can find what I need in seconds instead of minutes. And when I hit context reset, the important docs are in docs/, not scattered across 100+ temp files.

The Pattern

This isn't about AI specifically. It's about any tool that generates artifacts faster than you can curate them.

AI just makes the problem obvious in days instead of months.

The insight: When your collaboration tool never sleeps, manual processes don't scale. Automate the guardrails.

Discipline fails. Automation scales.