GuidesSession Workflow

Session Workflow

A practical guide to working with Claude Code Setup. Sessions usually last 30-90 minutes before context fills up.

The Session Cycle

┌─────────────────┐
│   /catchup      │  ← Start every session here
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Work        │  ← Implement, decide, document
│  (30-90 min)    │     /todo for quick capture
│                 │     /design for complex features
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   /wrapup       │  ← When Ctx hits ~80%
│   /clear        │
└────────┬────────┘
         │
         └──────────→ Next session

Start: /catchup

Every session begins the same way:

/catchup

Claude loads:

  • Recent Git changes
  • Your project’s CLAUDE.md status
  • Relevant Records for in-progress work
  • Coding standards for your tech stack

Output example:

Project: my-api
Tech Stack: Python, FastAPI

Recent changes (last 3 commits):
- Added user authentication
- Fixed rate limiting bug

Records loaded:
- Record 012: Auth design (in progress)

Next step: Implement password reset

Work: The Session

Pick a Task

Look at what /catchup suggested, or check the Current Status table in CLAUDE.md.

Implement

Work normally. Coding standards are loaded already.

Track Decisions

Significant decisions → Create a Record:

Create a Record for why we chose JWT over sessions

Small decisions → Add to Recent Decisions:

Add to Recent Decisions: Using bcrypt with cost=12 for password hashing

When Claude Gets Corrected

When you correct Claude or share project knowledge (“This API expects ISO-8601”, “Never use sudo here”), Claude automatically persists it so the knowledge survives /clear:

  • Personal preferences (“Use German commits”) → User Instructions (global CLAUDE.md)
  • Project preferences (“always use pytest-asyncio”) → Project Instructions (project CLAUDE.md)
  • Project facts (“API expects ISO-8601”) → Recent Decisions table
  • Session context (“Bug is in Auth module”) → Private Note

Claude confirms briefly: “Noted in Recent Decisions.”

When to Re-Plan

If implementation runs into trouble, watch for these signs:

  • Third workaround for the same problem
  • Something invalidates an earlier assumption
  • Scope growing well beyond the original task

When this happens, pause and reconsider instead of pushing through.

Add Tasks That Come Up

Quick reminders:

/todo Add rate limiting to auth endpoints

Complex features (need design):

/design "Add user authentication"

Use /design when the task has multiple parts, needs architecture decisions, or you’re unsure how to implement it. Designs survive /clear - resume anytime with /design --continue.

Watch Context

Your status line shows usage:

Ctx: 45% | Model: opus | Branch: main
LevelAction
0-60%Keep working
60-80%Plan your stopping point
80%+Run /wrapup now

End: /wrapup + /clear

When context approaches 80%:

/wrapup

Claude:

  • Updates CLAUDE.md with current status
  • Creates any new Records
  • Commits changes

Then:

/clear

Your next session starts fresh with /catchup.

Quick Sessions

For small tasks, you might not need the full cycle:

/catchup
Fix the typo in the header
Done - no /wrapup needed for trivial changes
/clear

Use /wrapup when:

  • You made significant progress
  • You created or updated Records
  • The next session needs context

Tips

  • Start with /catchup - Even if you just cleared 5 minutes ago
  • Don’t wait for 100% - Context quality degrades before hitting the limit
  • Add decisions immediately - Not at /wrapup time
  • Short sessions are fine - Better to clear often than lose context
  • Records are cheap - Create them liberally
/delegateCustomizing