The Rutter Pattern: AI Memory Through Continuous Refinement

“A rutter was a small book containing the detailed observation of a pilot who had been there before. It recorded magnetic compass courses between ports and capes… the how we got there and how we got back: how many days on a special tack, the pattern of the wind… where there were friends and where foes.” — James Clavell, Shōgun

Pilots who survived the age of sail had rutters — small books of extracted wisdom from accumulated voyages. Safe passages, dangerous shoals, where to find friends and foes.

Your AI workflow needs the same thing.

Two Artifacts, Two Purposes

Working with Claude Code, I’ve landed on two complementary artifacts:

The park document captures everything. The durable artifacts keep only what matters for the next voyage.

The Voyage Log: Park Documents

The park protocol is a slash command that compresses a session into an AI-optimized summary. Run /session:park at the end of a working session and it captures:

• Decisions made and their rationale
• Mistakes and learnings — what didn’t work initially
• Technical details — bug root causes, configurations, API patterns
• Improvements needed — gaps in documentation, missing tools

Here’s a simplified example:

# Park: API Integration Refactor
**Date:** 2025-12-13

## What Happened
Refactored the data sync pipeline to handle rate limiting.

## Key Outcomes

- Added exponential backoff to API calls
- Discovered the `/export` endpoint supports pagination
- Fixed timezone bug in date parsing

## Lessons

- ✅ Rate limiting pattern worked first try
- ❌ Spent 40 minutes debugging case-sensitive config keys
- 💡 The `/export` endpoint is more reliable than `/highlights` for bulk operations

## .claude Improvements

- [ ] Add rate limiting pattern to CLAUDE.md
- [ ] Create skill for API debugging workflow

This is the voyage log. Everything that happened, including dead ends and what you’d do differently.

The Rutter: Durable Artifacts

When patterns prove themselves across multiple sessions, they graduate from park documents to durable artifacts. In Claude Code, this means:

The park document asks “what happened?” The rutter asks “what should every future session know?”

From Voyage Log to Rutter

The park-apply command extracts learnings and routes them:

## Park Apply Summary

### Learnings Extracted

#### Code Patterns (→ CLAUDE.md)
- **Python `and` truthiness**: Returns value, not boolean
- **React key stability**: Never include editable content in keys

#### Anti-Patterns (→ Skills)
- `python-gotchas`: Added Decimal serialization
- `wsl-cross-platform`: Added PowerShell curl warning

#### Tech Debt (→ Issue tracker)
- Created: Remove instructor dependency

Notice the routing. A universal one-liner goes to CLAUDE.md. A detailed debugging workflow becomes a Skill. A technical reference goes to REFERENCE.md. The rutter is not one file — it’s the whole Claude Code configuration layer.

What Doesn’t Make the Cut

A park document might include:

• “Tried three different API endpoints before finding the right one”
• “Spent 40 minutes debugging a typo in the config file”
• “Refactored the approach twice before settling on the final design”

The rutter keeps:

• “Use /api/v2/export for bulk operations — it’s paginated and more reliable”
• “Config keys are case-sensitive in production but not locally”

The voyage was interesting. The rutter is useful.

When to Update the Rutter

Not after every session. After enough sessions to see patterns:

• When the same mistake happens twice
• When a workaround becomes standard practice
• When you notice yourself explaining the same thing to fresh contexts
• When a technique proves itself across multiple projects

The rutter captures what held up, not what seemed good at the time.

The Refinement Loop

1. Park after sessions — Run /session:park to capture raw experience
2. Review periodically — Run /session:apply to extract recurring patterns
3. Promote to artifacts — Route learnings to CLAUDE.md, Skills, or Commands
4. Prune what didn’t hold — Remove instructions that caused problems

The rutter gets better by removing what didn’t work, not by adding everything new.

Real Example: WSL + Docker

From my prompt-kit configuration:

In CLAUDE.md (the one-liner version):

- Use `host.docker.internal` for host access, not `localhost`

In Skills (the detailed workflow):

## WSL + Docker Gotchas

- Socket-based port checks instead of PowerShell curl
- Build-time vars need `--force-recreate --build`
- LAN IPs (192.168.x.x) for cross-container networking
- Run `docker compose` from WSL, not Windows CMD

This emerged from five different debugging sessions across three projects. Each time I hit one of these, I’d park it. Eventually the pattern was clear enough to extract — some to CLAUDE.md for quick reference, the rest to a dedicated skill for deeper context.

The Punchline

The pilots who survived the age of sail didn’t have better ships. They had better rutters.

Build park documents for raw experience. Build durable artifacts for extracted wisdom. Let experience accumulate, then distill.

Sources:

• James Clavell, Shōgun (1975)
• prompt-kit — Claude Code configuration system with park protocol and artifact templates
• park.md — The park protocol definition
• park-apply.md — The extraction workflow