Why Claude Code Routines Replaced Our Prompt Library — Reusable, Versioned, Shareable Agent Workflows

TL;DR: Prompts in Notion/Docs rot — context drifts, models change, no execution. Routines are executable YAML: “run tests → on failure analyze → patch → re-run until green.” Versioned in git, shared across team, invoked via Cmd+Shift+P. 12 Routines cover refactors, deploys, debugging, ADRs, migrations. Routines library →

The Context

Two-dev team, ~120 hrs/mo AI coding. Jan–May 2026: maintained a Notion “Prompt Library” — 50+ prompts for refactors, test generation, debugging, deployments. Problems: prompts grew stale as codebase evolved; no execution (copy-paste to chat); no version control; model updates (Sonnet 3.5 → 3.7) changed behavior silently. June 2026: Claude Code launched “Routines” — reusable, versioned agent workflows defined in YAML, invoked from VS Code command palette.

What We Tested

Approach	Format	Execution	Versioned	Shareable	Verdict	Why
Notion Prompt Library	Markdown	❌ Copy-paste	❌	⚠️ Manual	❌	Rot; no execution; drift
VS Code Snippets	JSON	❌ Text only	✅	✅	❌	No agent logic; static
Custom Scripts (bash/Node)	Code	✅	✅	✅	⚠️	High maintenance; brittle
Claude Code Routines	YAML + natural language	✅ Agent runs	✅ Git	✅ Command palette	✅ Primary	Agent executes; self-healing prompts; team-shared

The Pivot Point

June 4, 2026: Needed to refactor payment module (12 files, Stripe Connect onboarding). Old way: Notion prompt → copy to Cursor Composer → 3 context resets → manual test runs → 2 hours. New way: Cmd+Shift+P → "Claude Code: Run Routine" → refactor-module → Routine runs: reads files, writes plan, executes edits, runs test suite (fail), analyzes failures, patches 3 files, re-runs (pass), runs migration, deploys to staging, verifies health checks — 18 minutes, zero resets. The Routine YAML (47 lines) now lives in .claude/routines/refactor-module.yaml, committed to repo. Teammate runs same Routine next day — identical result.

What We Use Now

Routines Library (.claude/routines/, 12 files, all versioned):

Routine	Trigger	Purpose	Key Steps
fix-tests.yaml	Daily / pre-commit	Test-to-green loop	Run suite → on fail: analyze → patch → re-run until green
refactor-module.yaml	Architecture changes	Multi-file refactor with guards	Read module → write plan → execute → test → migrate → deploy
deploy-staging.yaml	Pre-merge / daily	Full deploy pipeline	Build → test → deploy → health checks → rollback on fail
debug-repro.yaml	Bug with reproduction	Debugging with exec	Write failing test → reproduce → analyze → fix → verify
write-adrs.yaml	Architecture decisions	ADR scaffolding	Interview → draft ADR → review → commit
migrate-supabase.yaml	Schema changes	Safe migrations	Generate → review → apply → verify → seed
scaffold-feature.yaml	New feature start	Boilerplate + tests	Spec → generate → test → Storybook
update-deps.yaml	Weekly	Dependency updates	Audit → update → test → PR
lint-fix.yaml	Pre-commit	Auto-lint	Run lint → fix → re-run
performance-audit.yaml	Monthly	Perf regression	Lighthouse → analyze → report
security-scan.yaml	Pre-release	Security audit	SAST → deps audit → secrets scan
onboarding-dev.yaml	New hire	Environment setup	Scripts → verify → first PR guide

Invocation: Cmd+Shift+P → “Claude Code: Run Routine” → select → runs in terminal panel.

Team Sharing: Routines committed to repo. New hire: git clone → claude-code install → Cmd+Shift+P → Run Routine → onboarding-dev. Day one productive.

Maintenance: Weekly review (Mon 9am) — any Routine fail? Update YAML. Model upgrade (Sonnet 3.5→3.7): re-run all Routines, fix drift.

When You’d Choose Differently

• Solo dev, <5 Routines needed: Prompt library in Notion/Obsidian fine. Routine overhead not worth it.
• No Claude Code access: If team uses Cursor/Copilot only, prompt snippets + scripts are the alternative.
• Highly dynamic/experimental tasks: Routines excel at repeatable workflows. One-off exploration still needs chat.
• Non-terminal workflows: If your agent work is pure research/writing (Codex/ChatGPT), Routines don’t apply.

Tool Crucible Rating

Dimension	Rating (1–5)	Notes
Overall	5	Turns prompt engineering into software engineering
Ease of Use	4	YAML + natural language; low barrier; command palette UX
Value	5	60% refactor time reduction; eliminates prompt rot
Support	4	Anthropic ships Routines updates weekly; Discord active

---

This is part of our AI Coding Tool Evaluation series. See full comparison: Claude Code Routines Library 2026