Documenting 50+ n8n Flows Without Losing Your Mind

Teams with 50+ undocumented n8n workflows that constantly break should not migrate off n8n yet. The real problem is the documentation gap: flows break because nobody knows what each node expects. Fix that first by exporting workflow JSON into Claude Code via MCP, then generating documentation and fragility analysis automatically.

Why n8n flows break

Most n8n failures are not n8n bugs. They are undocumented assumptions: a specific API response shape that changed, a credential that expired, a webhook URL that was hardcoded, or a node that expects a field name that the upstream API renamed. Without documentation, debugging means clicking through every node in the visual editor.

Step 1: export and catalog workflows

# Export all workflows via n8n CLI or API
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "http://localhost:5678/api/v1/workflows" | \
  jq -r '.data[] | "\(.id) | \(.name) | active=\(.active) | nodes=\(.nodes | length)"'

# Export a single workflow to JSON
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "http://localhost:5678/api/v1/workflows/123" > workflow_123.json

Step 2: document with Claude Code

Pull the workflow JSON into a Claude Code session. The n8n MCP server from czlonkowsko gives Claude direct access to read workflows without manual export. Ask Claude to explain what each workflow does, identify fragile nodes, and generate documentation.

Prompt template for Claude Code:

"Read workflow [name]. For each node:
1. What does it do?
2. What input shape does it expect?
3. What credentials does it use?
4. What would break if the upstream API changed its response format?
5. Add documentation annotations to the workflow (no logic changes).
Output a markdown summary and the updated workflow JSON."

Step 3: identify fragile patterns

Common fragility patterns Claude Code identifies across n8n flows:

• HTTP Request nodes scraping websites (break when layout changes)
• Hardcoded field paths in Set/Function nodes
• Missing error handling branches (no Error Trigger node)
• Webhook URLs that reference dev environments
• Credentials shared across workflows (one rotation breaks many)

Step 4: add monitoring

Once documentation reveals what each flow expects, add monitoring: Error Trigger nodes for each critical flow, Slack/email alerts on failure, and a weekly summary of flow health. This is cheaper and faster than migrating 50 flows to a new platform.

When to actually migrate

Migrate off n8n only if: (1) your team outgrew visual workflow editing and wants code-first orchestration, (2) n8n's self-hosted infrastructure costs more than a managed alternative, or (3) specific flows need capabilities n8n cannot provide (complex branching, ML pipelines, real-time streaming). For most teams, documented n8n with proper error handling is the right answer.