The Claude Code Workflow
Let's see what a real Claude Code session looks like with deciduous.
A Complete Session
Here's a realistic session where a user asks Claude to add rate limiting:
> Add rate limiting to the API endpoints
I'll implement rate limiting for your API. Let me first log this goal to the
decision graph.
deciduous add goal "Add rate limiting to API" -c 90 \
-p "User asked: Add rate limiting to the API endpoints"
Created node #47: goal "Add rate limiting to API"
Now I need to decide on the approach. Let me log this decision point:
deciduous add decision "Choose rate limiting strategy" -c 75
Created node #48: decision "Choose rate limiting strategy"
deciduous link 47 48 -r "Deciding implementation approach"
Created edge: #47 -> #48 (leads_to)
I see a few options here:
deciduous add option "Redis-based with sliding window" -c 80
Created node #49: option "Redis-based with sliding window"
deciduous add option "In-memory with token bucket" -c 70
Created node #50: option "In-memory with token bucket"
deciduous link 48 49 -r "Scales across instances, persistent"
deciduous link 48 50 -r "Simpler, but single-instance only"
Looking at your infrastructure (I see you're using Redis for sessions already),
I recommend Redis-based rate limiting. This will scale across your multiple
API instances.
deciduous add action "Implementing Redis rate limiter" -c 85
Created node #51: action "Implementing Redis rate limiter"
deciduous link 48 51 --edge-type chosen \
-r "Redis already in stack, needs horizontal scaling"
Created edge: #48 -> #51 (chosen)
Now let me implement this...
[Claude writes the rate limiter code, creates middleware, adds tests...]
Rate limiting is implemented! Let me record the outcome:
git add -A && git commit -m "feat: add Redis-based rate limiting"
[feature/rate-limiting abc123] feat: add Redis-based rate limiting
4 files changed, 187 insertions(+)
deciduous add outcome "Rate limiting working, 429s returned correctly" \
-c 95 --commit HEAD
Created node #52: outcome "Rate limiting working" [commit: abc123]
deciduous link 51 52 -r "Implementation verified with tests"
Created edge: #51 -> #52 (leads_to)
deciduous sync
Exported graph to docs/graph-data.json
Done! I've added Redis-based rate limiting with sliding window to all API endpoints.
The decision graph has been updated so future sessions will know:
- Why we chose Redis over in-memory (horizontal scaling)
- The commit where this was implemented
- The full decision chain from goal to outcome
What Just Happened
Let's break down the key patterns:
1. Log the Goal First
Claude immediately creates a goal node with -p to capture the user's original request:
deciduous add goal "Add rate limiting" -c 90 -p "User asked: ..."
The -p flag captures the prompt that triggered this work. This is crucial for future context recovery.
2. Decisions Before Code
Before writing any code, Claude logs the decision point and the options being considered:
deciduous add decision "Choose rate limiting strategy" -c 75
deciduous add option "Redis-based with sliding window" -c 80
deciduous add option "In-memory with token bucket" -c 70
This captures the reasoning before it happens, when the context is fresh.
3. Mark Chosen Actions
When Claude picks an approach, it uses the chosen edge type:
deciduous link 48 51 --edge-type chosen -r "Redis already in stack"
This makes it clear which option was selected and why.
4. Link Commits to Outcomes
After committing, Claude links the outcome to the git commit:
deciduous add outcome "Rate limiting working" -c 95 --commit HEAD
This creates traceability between decisions and code.
5. Sync Before Push
Finally, deciduous sync exports the graph for the web viewer:
deciduous sync
The Complete Decision Chain
After this session, the graph contains:
$ deciduous edges
From To Type Rationale
────────────────────────────────────────────────────────────────
47 48 leads_to Deciding implementation approach
48 49 leads_to Scales across instances, persistent
48 50 leads_to Simpler, but single-instance only
48 51 chosen Redis already in stack, needs horizontal scaling
51 52 leads_to Implementation verified with tests
Anyone (human or AI) can now query this to understand:
- What was the goal?
- What options were considered?
- Why was Redis chosen over in-memory?
- Where is the code? (commit abc123)
The Workflow Summary
The Claude Code Workflow
- User makes a request
- Claude logs a goal with the prompt (
-p)
- Claude logs the decision point
- Claude logs options being considered
- Claude implements the chosen approach
- Claude logs the action with
--edge-type chosen
- Claude commits and logs the outcome with
--commit HEAD
- Claude runs
deciduous sync
Mid-Stream Direction Changes
Sometimes the user changes direction during implementation. Capture this:
> Actually, use the token bucket algorithm instead of sliding window
Got it! Let me capture this direction change and adjust.
deciduous add action "Switching to token bucket algorithm" -c 85 \
-p "User said: Actually, use the token bucket algorithm instead"
Created node #53: action "Switching to token bucket algorithm"
deciduous link 51 53 -r "User requested algorithm change"
Created edge: #51 -> #53 (leads_to)
Now I'll update the implementation to use token bucket...
The -p flag captures when the user redirects work mid-stream. This preserves the context of why the approach changed.