Play Framework evolutions are numbered sequentially: 1, 2, 3, each a SQL file. When you add a new evolution, you take the next number. The problem is that every other PR merging to master that week was also adding evolutions. Each time one landed, it took the number mine was using.

Rebase. Renumber. Push. Wait. Another PR merges. Rebase again.

There had to be a better way.

The ask

The fix wasn’t complicated. Check if the evolution number on my branch conflicts with what’s on master. If it does, renumber to the next available slot, rerun code generation, and force-push. The steps were mechanical. Doing them four times in a week was the problem. This felt like a great fit for Claude Code’s recently released feature: routines.

So I described it to Claude in one sentence.

Can you monitor this daily for breaking changes to the PR and keep it up to date with master? Resolving any issues with the evolution if the number gets taken again and updating the PR accordingly.

That’s the entire prompt. No pseudo-code. No step-by-step instructions. Just the constraint and the desired outcome.

What Claude generated

Claude wrote a routine to handle the full workflow. A routine is a saved prompt that runs on a schedule against a repository. Routines can run on Anthropic’s cloud infrastructure or locally on your machine. I used a local routine for this one.

Here’s the generated routine, sanitized and condensed. This is what Claude produced from the one-sentence ask above.

Monitor PR #1234 on org/repo and keep the branch in a
mergeable state with master. The PR adds one database
evolution. Evolution-number collisions with other PRs
merging to master are the recurring issue.

## Workflow

1. Check PR state via `gh pr view` — if not OPEN, stop.

2. Find our evolution file by grepping for the index
   identifier in the evolutions directory.

3. Check for collision — does master already have a file
   at our evolution number?

4. If no collision and branch is current with master,
   stop silently. No "all clear" comments.

5. If collision: capture our SQL content, find the highest
   evolution number on master, renumber to master_max + 1,
   reset to master, write the file at the new number.

6. Rerun sbt evolutions and code generation. If sbt fails
   (local Postgres not reachable), proceed but flag it.

7. Commit, force-push with lease, update the PR body to
   reflect the new evolution number.

8. Post a PR comment summarizing what changed: which
   master PR landed at the old number, the rename from
   N.sql to M.sql, and anything needing manual follow-up.

## Constraints
- Don't touch other PRs. Don't merge this one.
- Force-push with lease is fine on this feature branch.
- Only comment when you take action or something needs
  manual attention.
- Idempotent: running twice with no upstream changes
  should do nothing the second time.

In short: check the PR state, find the evolution file, detect whether master already has a file at the same number, and if so, renumber to the next available slot, rerun code generation, force-push, and comment on the PR with a summary. If nothing changed, do nothing and stay quiet.

Two things stand out.

First, the constraints section. I didn’t specify most of those. Claude inferred the boundaries from the problem description: don’t merge, don’t touch other PRs, be idempotent, stay quiet when there’s nothing to do. Those are the constraints an experienced developer would set. The routine arrived with them already in place.

Second, the idempotency requirement. A routine that runs daily needs to be safe to run twice. Claude treated that as a given rather than something I needed to spell out.

The routine handled four more renumbers that week without me touching it. Each morning it checked, and on the days a collision had occurred overnight, it renumbered, pushed, and left a comment on the PR explaining what changed.

The mental model

The pattern here isn’t specific to Play evolutions or database migrations. It applies to any mechanical maintenance task on a long-lived PR. Describe the constraint, not the steps. I didn’t write the bash commands or the git operations. I described the problem (evolution numbers collide when other PRs merge) and the desired outcome (keep my PR mergeable). Claude filled in the implementation because the steps follow directly from the constraint.

This is the same dynamic that makes Claude Code effective for coding tasks: the more precisely you describe what you need and why, the better the output. The difference with routines is that the automation keeps running until the PR merges.

If you’re babysitting a PR this week, describe the problem. Let the agent write the automation.

If you’re building AI into your engineering workflows and want to move faster without the trial-and-error, let’s talk about how I can help.

Further reading

• Claude Code Routines documentation for setup and scheduling options
• How I Use Claude Code for more on integrating Claude into daily development work

The lost-in-the-middle problem doesn’t disappear at 1M tokens. Content in the center of the window still gets less attention than content at the beginning and end. Opus 4.7 uses a new tokenizer that improves model performance, but it also means files you read consume context in subtly different ratios than before. Anthropic’s docs note the new tokenizer can use up to 35% more tokens per equivalent input compared to previous models. And adaptive thinking, now the only supported thinking mode in 4.7 (fixed budgets are removed), consumes context dynamically. The model thinks longer on harder problems and shorter on easy ones. That thinking counts against your window.

If you’re coming from my earlier post on Understanding Claude Code’s Context Window, everything there still applies. The fundamentals haven’t changed. What has changed is the ceiling, and the set of controls available to you.

Here are seven workflow adjustments I’ve made since Opus 4.7 dropped. Each one addresses a specific constraint I hit in daily production use.

1. Front-Load Context in Your First Turn

One of the big changes from Opus 4.6 to Opus 4.7 is that it no longer reads between the lines. Opus 4.6 was better at taking a vague prompt and “figuring it out”. Opus 4.7, however, no longer does this. You need to provide good context to the model to achieve good results. The first message in the session anchors everything that follows.

Structure your first turn to include three things: what you want and why, which files or areas of the codebase are relevant, and what “done” looks like.

Here’s an example. Instead of this:

Add rate limiting to the API

Try this:

Add rate limiting to the webhook ingestion endpoint in
packages/gateway/src/routes/webhooks.ts. We're getting
hammered by a misbehaving integration that sends duplicate
events. Use the existing Redis connection in src/lib/redis.ts.
Rate limit by client IP, 100 requests per minute. Add tests
in __tests__/webhooks.test.ts. Don't change the event
processing logic in src/lib/event-handler.ts.

The second version tells Opus 4.7 exactly what to touch, why, and what to leave alone. You define the “what” and the constraints. Let the model propose the “how.”

One thing to watch for: don’t turn your first message into a specification document. If you find yourself writing more than a paragraph or two, you’re probably trying to control implementation details that the model should decide. Name the files, the constraints, and the definition of done. Stop there.

2. Switch Effort Levels Mid-Session

Thinking tokens count against your context window. A single xhigh response on a complex problem can use significantly more tokens than the same question at high. Over the course of a session, this adds up fast.

Opus 4.7 introduced xhigh effort and replaced the old fixed thinking budgets with adaptive thinking. At xhigh, the model almost always engages deep reasoning on complex work and skips thinking on simpler tasks. That’s useful for architecture decisions, complex debugging, and multi-file refactors. It’s overkill for renaming a variable across twenty files.

Here’s how I handle it. I start sessions at xhigh for the initial planning and implementation work. When I shift to mechanical tasks, I drop the effort level:

/effort high

Rename the files, run the migration, update the imports. Then when I need deep analysis again:

/effort xhigh

In practice: you spend the first part of a session at xhigh implementing a feature, then need to update some test fixtures and rename a few constants. Drop to high or even medium for that work. When you’re ready to debug a failing integration test, go back to xhigh.

The gotcha here is context switching cost. Don’t toggle effort every other message. Batch your mechanical tasks together and run them at a lower effort level in one block. Then switch back for the next piece of deep work.

3. Compact at 60%, Not When You See a Warning

Autocompact triggers when your context window is nearly full. By the time that happens with a 1M window, you’ve been running with degraded output quality for a while. The lost-in-the-middle effect doesn’t wait for you to run out of room. It starts affecting responses well before you hit the ceiling.

My rule of thumb: check /context periodically and compact when you hit around 60%. That sounds like a lot to throw away, but consider the flip side. You still have 400K tokens after compacting, which is twice the entire Sonnet 4.5 window.

Here’s what /context output looks like in a session approaching that threshold:

Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-7 · 610k/1000k tokens (61%)

After a proactive compact:

Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-7 · 85k/1000k tokens (8.5%)

That’s a fresh start with all the important decisions preserved. Much better than letting autocompact fire at capacity and losing coherence.

The trade-off with early compaction is that you lose conversational nuance. Specific phrasings, detailed file contents, and turn-by-turn reasoning all get compressed into a summary. This is why Tip 4 exists.

4. Steer Your Compaction

Running /compact without guidance lets the model decide what to keep and what to drop. This works reasonably well for short sessions, but in a long session with multiple decisions, the model often drops specifics that matter for the next phase of work.

Always pass steering instructions when you compact. Name the topics and the decisions you need preserved.

Here are three examples from real sessions:

/compact Preserve the auth refactor decisions: we chose
JWT with rotating refresh tokens over session cookies,
the token service is in src/lib/auth/tokens.ts, and
the migration adds a refresh_tokens table.

/compact Keep the schema changes we made to the proposals
table (added status enum, soft delete columns, and the
client_id foreign key). Preserve the repo pattern decision
from packages/shared/src/db/repos/proposals.ts.

/compact We're moving to phase 2 of the API implementation.
Preserve the route structure decisions (REST for CRUD,
webhooks for async events) and the middleware chain order.
Drop the debugging of the TypeScript config issues.

Keep your steering to two or three sentences. Name the topics, not every detail. The model will fill in the specifics from the conversation history. You are giving it a priority list, not writing the summary yourself.

5. Use Subagents for Context Isolation

I covered subagents in detail in my context window post, but Opus 4.7 shifts the default behavior. In my experience, Opus 4.7 spawns fewer subagents on its own compared to earlier models (Anthropic’s release notes confirm this as a deliberate behavior change). It’s more inclined to do work inline, which means exploration output that used to be isolated now accumulates in your main context.

That’s fine for focused tasks. It becomes a problem when you need to explore a large area of the codebase or review a significant diff. The fix: explicitly request subagent delegation.

The key is scoping what comes back. Instead of:

Review the changes on this branch

Try:

Have a subagent review the changes on this branch against
main. Report back: any bugs, any missing test coverage,
and any patterns that don't match our existing conventions.
Don't include the full diff in the report.

Good candidates for subagent delegation:

• Code reviews: The subagent reads every changed file, but your main context only gets the summary.
• Codebase exploration: “Have a subagent map out how the notification system works across packages/gateway and packages/agents.”
• Test analysis: “Spawn a subagent to check which tests cover the payment flow and identify gaps.”
• Pattern audits: “Use a subagent to find all places we handle errors in route handlers and check for consistency.”

The gotcha with subagents is that they don’t share your conversation history. If you made a decision earlier in the session that affects how the subagent should evaluate something, include that decision in the delegation prompt. The subagent starts fresh.

6. Use Rewind to Recover from Failed Approaches

Every failed approach leaves artifacts in your context: the wrong implementation, the correction, the explanation of why it was wrong. With Opus 4.7’s literal instruction following, this creates a real problem. The model may anchor on parts of a failed attempt even after you have corrected course, because that failed code is still in the conversation history.

The /rewind command (or double-tap Escape) rolls back to a previous point in the conversation. This removes the failed approach from context entirely, as if it never happened.

Here’s when to use rewind versus inline correction:

Rewind when the approach is fundamentally wrong. You asked for a webhook handler and got a giant switch statement, but your codebase uses an event routing pattern. Correcting inline means the model has both patterns in context and may blend them.

Correct inline when the details need adjustment. The approach is right but a method name is wrong, or it missed an edge case. The cost of the correction in context is low, and the model benefits from seeing the refinement.

A practical example: I asked Claude to implement a notification dispatch system. The first attempt built a synchronous pipeline. My codebase uses BullMQ for async job processing. Rather than explaining why synchronous was wrong and asking it to redo the work, which would leave both approaches in context, I rewound and rephrased:

Implement notification dispatch using our existing BullMQ
job infrastructure in packages/agents/src/lib/queue.ts.
Each notification type gets its own job processor.
Follow the pattern in the heartbeat-runner for job setup.

Clean context. Clear direction. No conflicting signals.

One warning: rewind is destructive. If the failed approach contained useful insights (it identified the right files to modify, or surfaced a constraint you hadn’t considered), note those before rewinding. You can include them in your rephrased prompt.

7. Know When to Clear, Compact, or Continue

Quality degrades gradually in long sessions. You won’t see a cliff. Responses get slightly less precise, slightly more generic, slightly more likely to miss constraints you established earlier. A 1M window means sessions can run much longer, which makes the decision of when to stop harder, not easier.

Here’s the decision framework I use:

Continue when you’re mid-task, below 60% context usage, and working on a single coherent thread. The model has strong recall of recent decisions and the work is flowing.

Compact when you’ve finished a phase and are starting the next one. You need the architectural decisions but not the turn-by-turn implementation details. This is where Tip 4’s steering instructions matter most.

Clear when the next task is unrelated to what you’ve been doing. Also clear when the model starts repeating itself, when you’ve already compacted multiple times in the session, or when you’ve persisted your plan externally (in a TODO file, a Linear issue, or a CLAUDE.md update).

Start a new session when you need different MCP servers, when you’re switching to a different branch, or when you’re doing parallel worktree work. Each worktree should get its own session. I covered why in Extending Claude Code with Worktrees for True Database Isolation.

The full session lifecycle follows a natural arc. Start with a strong first prompt (Tip 1) at xhigh effort (Tip 2). During the working phase, delegate exploration to subagents (Tip 5) and rewind failed approaches (Tip 6). When you hit around 60% context, compact proactively (Tip 3) with steering instructions (Tip 4). Then decide whether to continue, clear, or start fresh (Tip 7).

Session Start
  ├── Tip 1: Front-load context in first turn
  ├── Tip 2: xhigh for deep work, high/medium for mechanical
  │
  │   [Working...]
  │
  ├── Tip 5: Delegate exploration to subagents
  ├── Tip 6: Rewind failed approaches
  │
  │   [~60% context used]
  │
  ├── Tip 3: Proactive /compact
  ├── Tip 4: Steer the compaction
  │
  │   [Continue or...]
  │
  └── Tip 7: Clear / New session when needed

The Mental Model

The 1M context window isn’t five times more room. It’s five times more rope.

With a 200K window, context pressure forced discipline. You had to be deliberate about what went into the window because you would run out. With 1M tokens, poor habits go unnoticed much longer before the consequences show up. That makes discipline harder, not easier.

The one principle behind all seven tips: active context management beats passive accumulation. Front-load your intent. Control your effort levels. Compact before you need to. Steer the compaction. Isolate expensive exploration. Remove dead ends. Know when to stop.

These aren’t theoretical suggestions. They’re the adjustments I’ve made in my own workflow over the past week of daily Opus 4.7 usage. It rewards precision and punishes ambiguity. Give it clear context, and it delivers.

If this post was the explanation, the cheat sheet is the reference. Two sides: token costs for common MCPs on one, the /clear / /compact / subagent decision tree on the other.

Get the Context Window Cheat Sheet →

Further Reading

• Understanding Claude Code’s Context Window
• How I Use Claude Code: My Complete Development Workflow
• Extending Claude Code with Worktrees for True Database Isolation
• Anthropic: Best practices for using Claude Opus 4.7 with Claude Code

The question was concrete. How much of this reference data does the model actually need? I used uditgoenka/autoresearch, a Claude Code skill based on Andrej Karpathy’s autoresearch, to find out. After over 65 autonomous iterations, it cut the matrix to 303 lines (28% smaller) while maintaining 98.1% output quality.

Here’s the prompt optimization pattern, the results, and what surprised me about how robust LLMs are to reference data reduction.

The Autoresearch Pattern

Andrej Karpathy’s autoresearch introduced the core idea: give an AI agent a metric to optimize and let it loop. Modify, measure, keep or revert, repeat.

Udit Goenka built a Claude Code skill that brings this pattern to arbitrary optimization tasks, adding a dedicated guard command to prevent regressions.

You define six parameters:

• Goal: what you want to improve
• Scope: which files the agent can modify
• Metric: a number extracted from a shell command (line count, test coverage, score)
• Direction: whether higher or lower is better
• Verify: the command that produces the metric
• Guard: a safety net command that must always pass

Each iteration follows the same cycle: modify, commit to git, verify the metric, run the guard, keep or revert. Every experiment gets committed before verification, so rollbacks are clean. It tracks results in a TSV log and reads its own git history to avoid repeating failed approaches.

The separation between metric and guard is what makes this work. The metric tells autoresearch “did we make progress?” while the guard tells it “did we break anything?” Keeping those independent lets the loop optimize aggressively while the guard catches regressions.

Setting Up the Prompt Optimization Experiment

Scope

I scoped autoresearch to a single file — the reference matrix itself. I didn’t want it touching the agent’s prompt instructions, the recommendation library, or the eval infrastructure. Just the example data.

The alternative was to also let it modify the agent prompt, changing how the matrix is described. But I wanted to isolate the variable: same prompt instructions, same recommendation library, just less example data.

Metric

For the metric, I used line count. It’s simple, deterministic, and directly measures what we care about — how much data gets injected into the prompt. The metric doesn’t measure quality at all. That’s the guard’s job.

Guard

The quality gate was our existing golden-benchmark eval:

EVAL_QUIET=true npx vitest run --config vitest.evals.config.ts \
  src/evals/matrix-generation/golden-benchmark.test.ts

This eval feeds all 166 input categories into the agent, runs the full matrix generation end-to-end via LLM, and compares the output against golden reference data across four dimensions:

1. Input category coverage (did it produce rows for every input category?)
2. Output category accuracy (correct category assignment?)
3. Recommendation overlap (right recommendations from the library?)
4. Assignment accuracy (correct responsible party?)

The guard must exit 0 (all Vitest assertions pass) for a change to be kept. Each guard run took 5 to 7 minutes because it makes a real LLM API call to generate the full matrix.

The 65-Iteration Run

I ran three rounds:

Each iteration took 6 to 8 minutes (mostly the guard eval). Total wall time was roughly 7 to 8 hours across three rounds.

The agent’s approach was systematic. In round 1, it found the free wins: 5 exact duplicate rows, frequency variants (7 rows for different weekly frequencies that could collapse to 2), and severity levels where lower severity was always a subset of moderate. In later rounds, it got more aggressive, reducing most multi-row category groups to single representative entries.

Results After Fixing the Eval Baseline

During the run, I discovered that the original eval had a self-referencing bug. Both the agent prompt and the eval’s golden comparison data imported from the same REFERENCE_MATRIX_CSV constant. Every time autoresearch shrank the reference matrix, it also shrank what the eval compared against. The eval was proving “the model can reproduce a smaller matrix” rather than “the model handles all real-world input categories correctly.”

The fix was straightforward. I split the data into two files:

// src/data/reference-matrix.ts — injected into the agent prompt (optimized)
export const REFERENCE_MATRIX_CSV = `...`; // 303 lines after optimization

// src/data/golden-reference-matrix.ts — used by eval (immutable)
export const GOLDEN_REFERENCE_MATRIX_CSV = `...`; // original 421 lines, never changes

// src/evals/matrix-generation/golden-benchmark.test.ts
// Before: import { REFERENCE_MATRIX_CSV } from '../../data/reference-matrix';
import { GOLDEN_REFERENCE_MATRIX_CSV } from '../../data/golden-reference-matrix';

With the fixed eval, I binary-searched through the git history to find the optimal size. Because autoresearch commits every experiment, the full optimization history was available to test against the corrected eval.

The sweet spot is 303 lines: a 28% reduction maintaining 98%+ overall quality. The quality cliff appears around iteration 35, where the agent removed shared high-severity rows that contained unique recommendation mappings.

At 303 lines, the score breakdown:

• Input category coverage: 100% (all 166 golden categories present)
• Output category accuracy: 100%
• Recommendation overlap: 90.5% (about 32 specific recommendations lost)
• Assignment accuracy: 99.7%
• Overall weighted score: 98.1%

The main quality cost is recommendation overlap. The model still covers all input categories and assigns output categories correctly, but produces slightly fewer recommendation rows per category. For this use case, that’s an acceptable tradeoff: 118 fewer lines in every prompt for a 1.9% quality reduction.

What This Reveals About LLMs and Reference Data

The most useful finding isn’t the 28% number. It’s the degradation curve.

Even at 197 lines (53% cut), the model still hit 95.5%. It correctly covered all input categories and most output categories. The recommendation library (a separate 337-entry file in the prompt) carries much of the mapping knowledge. The reference matrix turned out to be more “example gallery” than “source of truth.” The model uses it to learn output patterns, not to look up specific mappings.

This has implications for any system that injects large reference data into prompts. The model likely doesn’t need all of it. But you need a correct eval to find the actual boundary, and the degradation is gradual, not a cliff. Without a quality gate, you won’t know where that boundary is until users report problems.

Lessons for Running Autonomous Optimization Loops

The guard is what makes it work

Without a quality gate, autoresearch is a deletion loop. The guard is the only thing preventing it from removing everything. This sounds obvious until you see how easy it is to write a guard that doesn’t actually guard.

Separate your optimization target from your eval baseline

If your golden data is the same data you’re optimizing, you’ll always pass. This is easy to do when the reference data serves dual purpose (prompt injection and eval comparison). Split them from the start. The optimization target is mutable. The eval baseline is immutable.

Git-as-memory enables post-hoc analysis

Autoresearch commits every experiment before verification. This is a form of agent memory that pays off after the run ends: I was able to binary-search through the history after fixing the eval, finding the exact commit where quality degraded. Without that history, I would have had to re-run the entire optimization from scratch.

Guard speed determines iteration budget

Fast guards (line count, type checks, unit tests) enable hundreds of iterations overnight. Slow guards (LLM-based evals, end-to-end tests) limit you to 10 to 15 iterations per hour. Plan your guard complexity based on how many iterations you can afford.

Applying This Pattern to Other Prompt Components

The recommendation library (a separate 337-entry reference file also injected into every prompt) is the next candidate for the same treatment. Same loop, same approach, but with the eval separation built in from the start.

The pattern generalizes to any prompt optimization problem: define the metric, build a correct guard, let the agent loop. The constraint is always the guard. A guard that looks correct but measures the wrong thing is worse than no guard at all.

I built a one-page scorecard based on the four layers of agent evaluation — component testing, trajectory visibility, outcome measurement, and production monitoring. It takes two minutes and shows you where your gaps are. Get the Agent Eval Scorecard →

If you’re past the scorecard stage and want hands-on help with eval design or prompt optimization, let’s talk.

Additional Reading

• autoresearch Claude Code skill by Udit Goenka
• autoresearch by Andrej Karpathy

The model is rarely the bottleneck. The codebase is.

The same model, pointed at a codebase with strong tests, clear architecture, and good documentation, produces remarkably consistent output. Point it at a codebase with weak coverage, no architecture docs, and no linting, and you get drift. Not because the model is less capable, but because it has less to work with.

I built the Codebase Readiness Assessment to make this measurable. It scores your repo across eight dimensions on a 0-100 scale. But you don’t need to run the assessment to understand what separates high-scoring codebases from low-scoring ones. Four dimensions account for most of the gap.

Test Foundation

Test foundation carries the most weight in the assessment (25%) because it’s the single biggest lever for agent output quality.

What a low score looks like

An agent makes a change. There are no tests covering that area, so it moves on. The change compiles, maybe even runs, but it broke an assumption three modules away. Nobody finds out until a human reviews the PR, or worse, until production.

I’ve seen this repeatedly: teams with 30-40% test coverage ask an agent to refactor a service object. The agent produces clean code that looks right. But there’s no spec for the edge case where a nil association triggers a downstream error. The agent had no way to catch it because there’s no test to fail.

The other failure mode is slow tests. If your suite takes 20 minutes, the agent can’t iterate. It makes a change, waits, discovers the failure, tries again, waits again. In a fast suite, that feedback cycle takes seconds. In a slow one, the agent burns time and money waiting for results.

What a high score looks like

Codebases that score well here share a few characteristics:

• Coverage above 70% on critical paths. Not 100% everywhere, but thorough coverage on the code that matters: domain logic, service objects, API endpoints. The agent can make changes and get immediate confirmation that nothing broke.
• Suite runs in under 5 minutes. Fast enough that the agent can run tests after every meaningful change, not just at the end.
• Deterministic results. No flaky tests. When the suite says green, it means green. Agents can’t distinguish between a flaky failure and a real one, so flaky tests teach agents to ignore failures.

Don’t stop at unit tests

Unit tests on service objects and models are the foundation, but they only verify isolated behavior. An agent that passes all unit tests can still break a user-facing workflow that spans multiple components.

End-to-end tests give agents confidence across entire flows. A system spec that signs a user in, submits a form, and checks the result tells the agent whether the feature works, not just whether a method returns the right value. This is especially valuable when agents make changes that touch controllers, views, and services in the same PR.

Here’s a simplified system spec from one of my Rails projects. It covers the core user journey: signing in and submitting a video idea for validation.

# spec/system/idea_submission_spec.rb

RSpec.describe "Idea submission" do
  it "allows a signed-in user to submit a video idea" do
    user = create(:user)

    sign_in_as(user, path: new_idea_path)

    select user.channels.first.name, from: "Channel"
    fill_in "Title", with: "Building a Rails AI Agent from Scratch"
    fill_in "Description", with: "Step-by-step tutorial on building an AI agent"
    fill_in "Category", with: "AI Coding"
    click_button "Validate Idea"

    expect(page).to have_content("Building a Rails AI Agent from Scratch")
  end
end

This test touches authentication, the form UI, the controller, the background job, and the results page. If an agent breaks any part of that chain, this spec catches it.

The tradeoff is speed. End-to-end tests are slower and more brittle than unit tests. You don’t need full E2E coverage, but having system specs on your critical user journeys (signup, checkout, the core action your product is built around) gives agents a safety net that unit tests alone can’t provide.

The smallest change that moves the needle

Add coverage to your critical paths first. Don’t chase a coverage number. Instead, identify the three or four service objects or domain models where bugs would hurt the most, and write specs for those. Then add one or two system specs covering your most important user journeys end-to-end. If your suite is slow, add parallel test execution. In a Rails app, that might be as simple as adding the parallel_tests gem. A suite that goes from 15 minutes to 4 minutes fundamentally changes how an agent can work with your code. If you’re running multiple agents in parallel, you’ll also need database isolation per worktree to prevent test data collisions.

If you want to accelerate the process, tools like autoresearch apply this pattern as an autonomous loop: give the agent a measurable goal (like a coverage target), and it iterates, verifies, keeps what works, and discards what doesn’t.

Documentation as Code

Documentation carries 15% of the assessment weight, but in practice it’s the dimension where I see the biggest gap between teams that get good agent output and teams that don’t.

What a low score looks like

Without an agent-facing entry point (a CLAUDE.md, AGENTS.md, or equivalent), an agent has to reverse-engineer your conventions from the code itself. It reads your files, infers patterns, and guesses at intent. Sometimes it guesses right. Often it doesn’t.

Here’s a concrete example. A Rails app uses service objects for all business logic. Controllers call a service, the service does the work, and the result gets rendered. There’s nothing enforcing this in the framework. It’s a team convention. An agent that doesn’t know about this convention puts the logic directly in the controller action. The code works. The tests pass. But it breaks the team’s pattern, and now there’s a 50-line controller action that should have been a service object.

The agent wasn’t wrong. It had no way to know.

What a high score looks like

The key insight is that this entry point file should be a map, not a manual. OpenAI’s Harness Engineering team learned this the hard way: they tried a single large instruction file and it failed because “context is a scarce resource” and “too much guidance becomes non-guidance.” When everything is marked important, agents pattern-match locally instead of navigating intentionally.

Their solution: keep the entry file short (roughly 100 lines) and treat it as a table of contents that points to deeper sources of truth in a structured docs/ directory. The entry file gives agents quick commands and a documentation map. The detail lives in dedicated files the agent reads when it needs them. Whether you call it CLAUDE.md, AGENTS.md, or CURSOR.md, the pattern is the same.

Here’s what this looks like in practice from one of my Rails projects:

## Quick Commands

bin/dev                                # Start dev server
bin/rails spec                         # All tests
bin/ci                                 # Full CI: lint + security + tests
bin/rubocop                            # Lint
bin/brakeman                           # Security scan

## Documentation Map

| Topic | Document |
|-------|----------|
| Stack, patterns, domain model | docs/ARCHITECTURE.md |
| Testing patterns and stack | docs/TESTING.md |
| Credentials, env vars, API keys | docs/CONFIGURATION.md |
| Engineering principles | docs/design-docs/core-beliefs.md |
| Architecture decision records | docs/design-docs/ |

The agent gets commands and a map up front. When it needs to understand the domain model or testing conventions, it follows the pointer. This is progressive disclosure: the agent starts with what it needs immediately and loads deeper context on demand.

Here’s a trimmed excerpt from the ARCHITECTURE.md behind that pointer:

## Domain Model

CreatorSignal validates YouTube video ideas. The core flow:

1. User submits a video **Idea**
2. A **Validation** job is enqueued
3. The **ResearchAgent** runs tools against YouTube, Reddit, X, and HN
4. Results are synthesized into a scored **Go / Refine / Kill** verdict

### Key Models

| Model | Responsibility |
|-------|---------------|
| `User` | Authentication, subscription plan |
| `Idea` | A video idea submitted for validation |
| `Validation` | One run of the research agent against an idea |

### Project Structure

app/
├── components/       # ViewComponent components
├── controllers/
├── jobs/             # ActiveJob jobs (async validation)
├── models/
├── services/         # Research agent, tool orchestration
└── views/            # Hotwire (Turbo frames/streams)

An agent reading this knows what an Idea is, that validation is async through a job, and that orchestration logic lives in app/services/. Those are the conventions that prevent drift.

ADRs (Architecture Decision Records) add a layer that documentation alone can’t. An agent that understands why a particular pattern was chosen can make better decisions when extending it. If your ADR says “we chose event sourcing for the billing domain because of auditability requirements,” the agent won’t try to refactor billing into simple CRUD.

The smallest change that moves the needle

Create an AGENTS.md in your project root with two things: commands (build, test, lint) and a documentation map pointing to deeper files. AGENTS.md is an emerging standard supported by Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Devin, and many others. If you’re using Claude Code, symlink CLAUDE.md to it so both resolve to the same file. Then create an ARCHITECTURE.md covering your stack, domain model, and key conventions. This can take an hour and the effect on agent output is immediate. If you want to automate the scaffolding, the agent-ready plugin generates a starting point based on your existing codebase.

Architecture Clarity

Architecture clarity carries 15% of the assessment weight. It measures whether an agent can understand where code belongs and how components relate to each other.

What a low score looks like

Agents replicate patterns they find in the codebase. If your codebase has clear boundaries (controllers handle HTTP, services handle business logic, models handle persistence), the agent follows those boundaries. If your codebase mixes concerns, the agent mixes concerns.

The most common failure I see: a controller that does everything. It validates input, calls the database, sends emails, enqueues jobs. An agent asked to add a new feature looks at the existing controller, sees that’s where logic goes, and adds more logic to the controller. The agent is doing exactly what the codebase taught it to do.

The subtler version is dependency direction. In a well-layered app, dependencies point inward: controllers depend on services, services depend on models. When that direction is inconsistent (models importing from controllers, services reaching into HTTP request objects), agents produce code with the same tangled dependencies.

What a high score looks like

• Clear layering. Each layer has a single responsibility, and the codebase is consistent about which layer owns what.
• Domain namespacing. Related functionality is grouped by business domain, not just by technical layer. Instead of a flat app/services/ with 40 files, you have app/services/billing/, app/services/onboarding/, app/services/research/. When an agent needs to add billing logic, the namespace tells it exactly where to look and what patterns to follow.
• Predictable file organization. A new developer (or agent) can guess where a piece of code lives based on what it does.
• Dependency direction is consistent. Inner layers don’t reach outward. You don’t see models importing controller concerns.

Domain namespacing is especially powerful for agents because it constrains the search space. An agent working on a billing feature only needs to understand the billing namespace, not the entire codebase. It finds the existing patterns in that namespace and replicates them. Without namespacing, the agent has to scan the whole codebase to figure out where billing logic lives, and it might find three different patterns in three different places.

The smallest change that moves the needle

If you have fat controllers, extract one. Pick your most complex controller action, pull the business logic into a service object, and write a spec for it. The agent will start using that service object pattern for new features. One well-structured example teaches the agent more than any documentation, because it’s a pattern it can directly replicate.

If your codebase has grown past a handful of services, start namespacing by domain. Group related services, jobs, and models under a shared namespace. This compounds quickly: once you have three or four service objects under Billing::, agents start producing new billing code in the same namespace by default. The codebase becomes self-reinforcing.

Feedback Loops

Feedback loops carry 10% of the assessment weight, but their impact is multiplicative. Good feedback loops make everything else work better. Poor ones make everything else work worse.

What a low score looks like

Agents learn from the signals they get back. When the only signal is “tests passed,” the agent has no way to know it introduced a style violation, broke a naming convention, or used a deprecated API. It moves on, confident the change is correct.

Two things make feedback loops weak: narrow signals and slow signals.

Narrow signals mean the agent only hears from one source. Tests tell the agent whether the code works. They don’t tell it whether the code follows your conventions, whether it introduced a security vulnerability, or whether the UI actually renders correctly. Each missing signal is a category of problems the agent can’t self-correct.

Slow signals are just as damaging. If the agent has to wait 20 minutes for a CI run to discover a linting error, it’s already moved on. It’s built three more features on top of code that doesn’t pass lint. Now you’re unwinding multiple changes instead of catching the first one. The closer the feedback is to the moment of the change, the cheaper it is to fix.

There’s also a hierarchy to how you enforce conventions. Anything that can be checked deterministically by a linter should be a lint rule, not a line in your CLAUDE.md. A lint rule catches every violation, every time. A documentation rule depends on the agent reading it and choosing to follow it. If your convention is “methods must be under 20 lines” or “always use frozen_string_literal,” encode it in RuboCop, ESLint, or whatever linter your stack uses. Save documentation for the things that can’t be mechanically enforced: architectural decisions, domain context, workflow conventions.

What a high score looks like

• Pre-commit hooks for immediate feedback. The agent discovers formatting issues, type errors, or lint violations before it even commits.
• CI that runs in under 10 minutes. Fast enough that the agent can push, get feedback, and iterate without burning excessive context.
• Rich error messages. Linting output that says “method too long (25 lines, max 20)” is actionable. A generic “style violation” is not.

Here’s what a CI script looks like when it goes beyond just running tests. This is the bin/ci from the same Rails project:

# config/ci.rb - run with bin/ci

CI.run do
  step "Setup", "bin/setup --skip-server"
  step "Style: Ruby", "bin/rubocop"
  step "Security: Gem audit", "bin/bundler-audit"
  step "Security: Importmap vulnerability audit", "bin/importmap audit"
  step "Security: Brakeman code analysis", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error"
end

Five steps, each giving the agent a different kind of feedback. RuboCop catches style violations. Bundler-audit catches vulnerable gems. Brakeman catches security issues in the code itself. An agent that runs bin/ci gets five signals instead of one.

Browser access as a feedback loop

For web applications, there’s a feedback loop that most teams overlook: giving agents the ability to see what they built.

An agent that can only run tests is working blind on anything visual. It can verify that a controller returns 200, but it can’t tell whether the page actually renders correctly, whether a modal opens, or whether a form submits without errors. Cursor’s team wrote about this: once they gave agents browser access via cloud sandboxes, agents could “iterate until they’ve validated their output rather than handing off the first attempt.” More than 30% of their merged PRs are now created by agents operating autonomously in cloud sandboxes.

You don’t need a full cloud sandbox to get value from this. Claude Code has built-in Chrome support via claude --chrome, and tools like Playwright MCP give agents browser control locally. The agent can navigate to a page, take a snapshot of the DOM, fill in a form, and verify the result. That’s a feedback loop that catches an entire class of issues that unit tests and linters never will.

The smallest change that moves the needle

Add a linter to your CI pipeline. For a Ruby project, that’s RuboCop. For JavaScript/TypeScript, ESLint. For Python, Ruff. One config file, one CI step. The agent immediately starts getting feedback on style and conventions that it wouldn’t otherwise know about.

If you want faster feedback, add pre-commit hooks. The agent runs into the linter before it even pushes, which means it fixes issues in the same context window where it created them. That’s cheaper, faster, and produces cleaner commits.

For web projects, consider adding browser access through Playwright MCP or a similar tool. The agent starts verifying its own UI changes instead of relying on you to catch visual issues in review.

Where to Start

If you’re looking at your codebase and wondering where to start, here’s how I think about prioritization:

1. Fix your test foundation first. Without reliable tests, every other improvement is hard to verify. An agent can’t confidently refactor your architecture if there’s no test suite to catch regressions.
2. Add an AGENTS.md. This is 30 minutes of work that immediately changes agent behavior. It’s the highest-ROI improvement you can make.
3. Add a linter to CI. This closes the feedback gap with minimal effort. The agent starts learning your conventions from automated feedback instead of guessing from code patterns.

These three changes don’t require a major initiative. They’re individual tasks that compound. A codebase with strong tests, clear documentation, and fast feedback loops creates a reinforcing cycle: agents produce better code, which maintains the patterns, which makes future agent output even better.

If you want to see where your codebase stands across all eight dimensions, run the Codebase Readiness Assessment. It takes 60 seconds and gives you a score, a per-dimension breakdown, and a prioritized roadmap.

If your team wants hands-on help closing these gaps, that’s what a Production AI Retainer is built for. Or if you just want to talk through your results, book a free intro call.

Further Reading

• Codebase Readiness Assessment - Run the free assessment on your repo
• Harness Engineering: Leveraging Codex in an Agent-First World - OpenAI’s deep dive on building a million-line codebase entirely with agents
• Agent Computer Use - How Cursor gives agents browser access to verify their own work
• How I Use Claude Code: My Complete Development Workflow - How codebase structure impacts agent output quality
• MCPs vs Agent Skills - Architecture decisions that shape how agents interact with your codebase

I walk through how channels work under the hood, including the Fake Chat plugin for testing, and a practical example building a webhook channel that processes Cal.com bookings via an MCP server bridge. If you want to automate Claude Code or expose it to external services, this covers everything from installation to writing your own custom channel.

This guide is for people who are building real things with Claude Code but haven’t spent much time in the terminal. Designers, product managers, founders who have picked up coding recently. If the terminal feels like reading another language, this is the starting point.

What the Terminal Actually Is

Your computer has two ways to interact with it.

The first is what you’re used to: icons, windows, buttons. You click a file to open it. You drag it to the trash to delete it. The computer shows you what’s happening visually.

The second is the terminal. Instead of clicking, you type. Instead of visual feedback, you get text. It’s the same computer doing the same things, just through a different interface.

The terminal can do everything the graphical interface (sometimes called a GUI, or graphical user interface) can do, and usually faster. When Claude Code searches your entire codebase for a function name, it does that in the terminal because searching thousands of files through a visual interface would be painfully slow.

The terminal comes pre-installed on Mac (it’s called Terminal). Tools like VS Code and Cursor have one built in. When you see Claude Code working, it’s using that built-in terminal.

Files, Folders, and Where You Are

Everything on your computer is either a file or a folder. Files have content (code, images, documents). Folders contain files and other folders.

The terminal uses slightly different words. Folders are called directories. Your project is a directory (usually containing many sub-directories). Same concept, different name.

The terminal always has a current location. Think of it like Finder or Windows Explorer: you’re always looking at a specific folder. In the terminal, that location is called the working directory.

When Claude Code opens in your project, the working directory is your project folder. Every command it runs starts from there.

File paths can be relative or absolute. An absolute path starts from the root of your computer, like /Users/yourname/Projects/my-app/src/App.tsx. A relative path starts from wherever you currently are. If your working directory is /Users/yourname/Projects/my-app, then src/App.tsx points to the same file. Most commands Claude Code runs use relative paths, so knowing your current location matters.

If you’re ever unsure which directory you’re in, you can check by running:

pwd

This prints the full path. Something like /Users/yourname/Projects/my-app. Read-only, nothing changes.

To move to a different directory, use cd (change directory):

cd ~/Projects/my-app

The ~/ is a shortcut that means your home folder (usually /Users/yourname on Mac or /home/yourname on Linux). So ~/Projects/my-app expands to the full path automatically.

You can also move up one level with cd ../:

cd ../

The ../ means “the parent directory,” or one folder up from where you currently are. If you’re in /Users/yourname/Projects/my-app/src, running cd ../ takes you back to /Users/yourname/Projects/my-app.

This is how you navigate to your project before starting Claude Code. If Claude Code isn’t finding the files you expect, it might be running from the wrong directory. Use pwd to check, and cd to move to the right place.

Looking Around: What Claude Code Does First

Before Claude Code makes any changes, it looks around. It needs to understand what exists before it can modify anything. The commands it uses for this are all read-only — they cannot break anything.

ls lists the files and folders in the current directory:

ls
ls src/components

Claude Code might run ls before creating a file to confirm it doesn’t already exist. Or look inside a specific folder to understand what’s there.

cat prints the contents of a file:

cat package.json

When Claude Code reads your package.json to understand your project’s dependencies, this is what it’s doing. Reading, not changing.

One thing to keep in mind: cat is read-only, but be cautious if Claude Code tries to cat files that contain secrets, like .env files with API keys or passwords. Those contents will be visible in your terminal session and sent to Claude as context. Treat secret files the same way you’d treat a password: don’t share them unless you understand where they’re going.

grep searches for text inside files:

grep -r "handleSubmit" src/

The -r here is a flag. Flags modify how a command behaves. They usually start with a dash (-) followed by a letter. In this case, -r tells grep to search recursively, meaning it looks through every file in the src/ folder and all its sub-folders. Without -r, it would only search a single file.

You’ll see flags on many commands. ls -l shows files in a detailed list. rm -r deletes directories. Each flag changes the command’s behavior in a specific way. When you see one you don’t recognize, that’s a good time to ask Claude what it does.

This grep command finds every file in src/ that contains the text handleSubmit. Claude Code uses this constantly to find where things are defined and where they’re used.

All of these commands are exploratory. Nothing gets created, moved, or deleted. If you’re unsure whether to approve a command, ls, cat, and grep are safe.

When Claude Code Actually Changes Things

Reading is safe. Everything else deserves attention.

Creating files and directories:

mkdir src/components/forms
touch src/components/forms/LoginForm.tsx

mkdir creates a directory. touch creates an empty file. Low-risk, but worth understanding what’s being created and where.

Moving and renaming:

mv LoginForm.tsx AuthForm.tsx

mv moves or renames a file. After this runs, LoginForm.tsx no longer exists under that name. Renaming in the terminal is just a move with a new name.

Deleting:

rm old-config.ts
rm -r deprecated/

rm deletes files. rm -r deletes entire directories and everything inside them. There is no trash bin. No undo. The file is gone.

Claude Code shouldn’t be deleting things without telling you what and why. If you see rm -rf, verify that you actually want those files removed before approving. If you are unsure, ask Claude what it’s deleting and why.

Running your project’s tools:

Depending on your project, you’ll see Claude Code use different package managers and tools. A package manager handles your project’s dependencies: the external libraries and code your project relies on so you don’t have to build everything from scratch.

The most common ones are npm (for JavaScript/Node.js projects), pip (for Python), gem (for Ruby), and yarn (an alternative to npm). Claude Code will use whichever one your project is set up with. When Claude Code runs npm install or pip install, it’s downloading packages. npm run build tells npm to run a build script defined in your project.

git is version control. It tracks every change to your code over time, like a detailed save history. git add tells git which files to include in your next save. git commit takes those staged files and saves them as a snapshot in the project’s history.

npm install
npm run build
git add . && git commit -m "Add login form"

These commands do real things. npm install downloads packages to your project. git commit saves your changes to version history. When Claude Code runs these, it’s making moves that affect your project’s state.

Reading a Command Before You Approve

You might see more complicated commands from Claude Code. Take the following example:

find . -name "*.test.ts" | grep "auth"

These are actually sequences of simpler commands combined together, a powerful feature of the terminal that lets you compose tools. To understand it, break it down from left to right:

• find . — search starting from the current directory (. means “here”)
• -name "*.test.ts" — find files that end in .test.ts
• | — take the results and feed them to the next command
• grep "auth" — filter those results to only lines containing “auth”

The full command: “Find all test files and show me the ones related to auth.” That’s read-only. Safe to approve.

The | character is called a pipe. It chains commands together: the output of the first becomes the input of the second. You’ll see it often. When you do, read each side separately, then understand what connects them.

Commands to Think Twice About

Most of what Claude Code runs is safe. A few patterns are worth pausing on.

rm -rf on anything important:

rm -rf src/

This deletes the entire src directory instantly. Claude Code will ask you to approve this command, but once you do, there’s no additional safety net from the operating system. No trash bin, no undo. Be sure about this before approving.

sudo:

sudo npm install -g some-package

sudo runs a command as an administrator. It will prompt you for your computer’s password. Claude Code rarely needs this. If you see it, ask Claude why it’s necessary. And don’t type your password into Claude Code’s prompt. If sudo is truly needed, deny the command, then run it yourself directly in your own terminal after Claude explains what it does.

curl piped into bash:

curl is a command that downloads content from the internet. On its own, it’s harmless. It just fetches a file or a web page. But when you see it piped into bash, it becomes something different:

curl https://example.com/script.sh | bash

This downloads a script from the internet and runs it immediately. The | sends whatever curl fetches straight into bash, which executes it as commands on your computer. Uncommon, but when you see it, understand exactly what you’re downloading before approving.

Pro tip: If you’re not sure what a script contains or whether it’s safe, ask Claude to review it first. Deny the curl | bash command and say something like: “What is this script you are trying to run in bash? Before we run this, can you download the contents and evaluate if it’s safe or not? Help me understand what it does.” Claude can fetch the file, display its contents, and walk you through what each part does so you can make an informed decision.

When a Command Fails

Claude Code commands fail regularly. That’s normal. Here’s what the common errors mean:

• command not found — the tool isn’t installed. Claude Code will usually try to install it, or tell you what you need.
• No such file or directory — the path is wrong. Something about the file name or location doesn’t match.
• Permission denied — you don’t have access to that file or directory.

When something fails, Claude Code will diagnose it and try a different approach. If it gets stuck, copy the error message and paste it back. Errors in the terminal are almost always actionable once you know what they’re saying.

Getting Help with Commands

You don’t need to memorize what every command does. There are two quick ways to get answers.

Ask the command itself. Most terminal commands have a built-in help option. Add --help after the command name:

grep --help
git --help
npm --help

This prints a summary of what the command does and what flags it accepts. The output can be dense, but scanning it for the flag you’re curious about usually answers your question.

Ask Claude. If a command Claude Code wants to run looks unfamiliar, deny it and ask Claude to explain. Something as simple as “What does this command do?” will get you a plain-language breakdown. Claude can explain the command, each flag, and what will happen when it runs. This is one of the most practical ways to learn the terminal while using Claude Code.

You’re Supervising, Not Executing

You don’t need to be a terminal expert to use Claude Code. Your job is to understand enough to supervise what it’s doing.

Supervisors know enough to recognize when something looks right and when something needs a question. That’s the skill worth developing here.

Most of what Claude Code runs is safe. The unsafe things are usually obvious once you know what rm -rf means and when sudo is suspicious. You now know both.

Cheat Sheet & Glossary

I put together a 2-page reference card with every command and term from this post, including safety ratings for each one. Keep it next to your keyboard while you work, or print it out.

Get the free Terminal Cheat Sheet (PDF) →

If you’re new to the terminal and want to use Claude Code confidently, I offer coaching to help you get there. From project setup to understanding what’s happening under the hood, we can work through it together. Book a Claude Code Basics session.

Ask Claude to explain a Rails model and it reads through the file, piecing together what the associations mean, inferring what the enum values map to, and hoping it catches all the scopes. It’s reading text and making educated guesses about structure. Ask it to find all callers of a private method before you delete it and it’s doing a best-effort text scan that can miss dynamic calls or alias references.

That ceiling just got raised. Ruby LSP now has official support in Claude Code.

What Is a Language Server Protocol

LSP is a standard that separates language intelligence from the editor. Before LSP, every editor had to implement its own understanding of every language. After LSP, you write the intelligence once as a language server, and any editor that speaks the protocol gets the benefits.

The language server sits alongside your code and maintains a live semantic model of your project. It tracks definitions, references, and symbol relationships across your entire project. When your editor asks “where is this method defined?” or “what are all the callers of this function?”, the server answers in milliseconds with accurate, complete information.

Ruby LSP is Shopify’s language server for Ruby. It integrates with Standard Ruby for diagnostics. In codebases that use Sorbet or Steep, those tools run as separate language servers and provide type information independently of Ruby LSP. Beyond the core server, there’s a growing community of add-on developers building extensions for it. awesome-ruby-lsp is a good starting point if you want to see what’s available.

What You Get

With Ruby LSP connected, Claude gains semantic code intelligence instead of relying on text search. Here’s what that means in practice.

Go to definition. Claude can jump directly to where a method, class, or constant is defined, including inside gems. No more manually tracking down gem source paths.

Find all references. Before a refactor, Claude can ask the language server for every reference to a symbol across your entire project. Dynamic calls included, because the LSP understands Ruby’s metaprogramming patterns well enough to handle common cases.

Call hierarchy. Claude can trace the full call chain for a method, both incoming callers and outgoing calls, across your entire project. That’s useful when you need to understand the impact of a change before making it.

Hover documentation. Claude can pull the YARD documentation for any method without having to search for it manually.

The difference shows up most in refactoring. When you ask Claude to rename a method or change a signature, it can now ask the LSP for the complete reference list before making a single change. That’s the difference between a confident refactor and a hopeful one.

Installing Ruby LSP in Claude Code

You’ll need Ruby LSP installed as a gem first:

gem install ruby-lsp

If you’re working in a bundled project, add it to your Gemfile in the development group:

group :development do
  gem "ruby-lsp"
end

Then install the plugin from inside Claude Code:

/plugin install ruby-lsp@claude-plugins-official

That’s it. The next time you start a Claude Code session in a Ruby project, the LSP server starts alongside it. You don’t need to configure anything. Install it once and it works.

What Changes in Practice

Here’s what it looks like in a real session. I asked Claude about a model in a Rails app:

❯ Use ruby-lsp and tell me about the membership model

⏺ Searched for 1 pattern (ctrl+o to expand)

⏺ LSP(operation: "documentSymbol", file: "app/models/membership.rb")
  ⎿  Found 6 symbols (ctrl+o to expand)

⏺ Read 1 file (ctrl+o to expand)

⏺ Now let me get hover info on a few key symbols:

⏺ LSP(operation: "hover", symbol: "enum", in: "app/models/membership.rb")
  ⎿  Hover info available (ctrl+o to expand)

⏺ LSP(operation: "findReferences", symbol: "Membership", in: "app/models/membership.rb")
  ⎿  Found 24 references across 12 files (ctrl+o to expand)

⏺ Here's a summary of the Membership model:

  app/models/membership.rb

  A join model representing a user's membership in a tenant (organization).

  Key traits:
  - acts_as_tenant :tenant — multi-tenant scoped via ActsAsTenant
  - belongs_to :tenant, belongs_to :user
  - Roles (integer enum): member (1), admin (2), owner (3)
  - scope :owners — filters members with the owner role
  - Validations: user_id must be unique per tenant (one membership per user per org), role must be present

  Used in 12 files across:
  - Controllers: invitations, memberships, organization settings
  - Services: AcceptInvitation, ConfirmUserEmail
  - Specs: model spec, tenant isolation spec, system specs

  The model is minimal — it's purely a pivot between User and Tenant with role-based access control baked in.

That’s a thorough summary. But I was curious what actually came from the LSP versus what Claude found by reading the file. So I asked:

❯ What information did you get from the lsp vs your own search

⏺ Good question. Here's the breakdown:

  From LSP:
  - documentSymbol — gave me the class name, method names, and line numbers without reading the file
    (associations, scope, validations)
  - hover on enum — confirmed it's ActiveRecord::Enum#enum with a link to the gem source definition
  - findReferences — found all 24 references across 12 files without me doing any grep search

  From my own file read (Read tool):
  - The actual source code content — the enum values (member: 1, admin: 2, owner: 3), the acts_as_tenant
    call, the uniqueness scope on the validation (scope: :tenant_id)

  In practice:
  - LSP gave me structure and cross-references (what symbols exist, where they're used project-wide)
  - The file read gave me content (the actual values and implementation details)

  The documentSymbol result notably omitted the acts_as_tenant call and the enum values — it only surfaced
  Rails macro calls it recognized as meaningful symbols. So LSP alone would have left me with an incomplete
  picture of the model.

That second turn is the honest answer. LSP and file reads are complementary. The LSP gives Claude structure and cross-references instantly: what symbols exist, where they’re called across the project, without spending context window tokens on file searches. The file read fills in the content: actual values, implementation details, anything the symbol index doesn’t capture. Together they produce a more complete picture than either alone.

That kind of structural understanding also changes how refactoring works. When you ask Claude to rename a class or change how something is called across the project, it queries the LSP for the complete reference list before making a single change. It isn’t guessing at usage patterns. It knows them.

One thing worth knowing: Ruby LSP works well without a type system. In my testing without Sorbet or Steep, the heuristic inference still produced accurate results for associations, method definitions, and references. If your codebase does use Sorbet or Steep, those type checkers can run alongside the LSP to improve accuracy further, but they’re not required to get value from this integration.

Text search got Claude surprisingly far. Semantic understanding gets it the rest of the way.

If you want help getting Claude Code dialed in for your Ruby workflow, whether that’s 1:1 or across your team, take a look at how I work with developers and teams.

Further Reading

• Ruby LSP on GitHub
• Ruby LSP documentation
• awesome-ruby-lsp
• Language Server Protocol specification
• Claude Code plugins documentation

Git worktrees solve the file side of this. Each agent gets its own working directory with its own branch. Anthropic recently shipped native worktree support in Claude Code, which handles the Git mechanics automatically. No external scripts to maintain.

But file isolation is only half the problem. A Rails app running in a worktree still points at the same development and test databases as your main checkout. Two agents running specs in parallel will insert conflicting test data, and you’ll get flaky tests with no obvious cause.

Native worktrees handle file isolation. The WorktreeCreate hook handles everything else.

What Native Worktree Support Does

Claude Code now manages worktrees directly. Start a session with the --worktree flag:

claude --worktree my-feature-branch

This creates a new branch and checks it out in a dedicated directory under .claude/worktrees/. The branch name argument is optional. Skip it and Claude generates a random name.

The --worktree flag isn’t the only entry point. You can also:

• Ask Claude mid-session to work in a worktree
• Spawn sub-agents that each get their own worktree automatically
• Set isolation: "worktree" on custom agent definitions so they always run isolated

That last option is worth calling out. If you have an agent that runs specs or does anything destructive, setting isolation at the agent level means you never have to remember the flag. It’s just how that agent works.

One thing to note: .claude/worktrees/ is not added to .gitignore by default. Add it early so worktree directories don’t end up in your commit history.

The .worktreeinclude File

Git worktrees only duplicate tracked files. Anything in your .gitignore won’t carry over. For most Rails apps, that means your .env file, config/master.key, and any other credentials are missing in every new worktree.

Claude Code solves this with .worktreeinclude. It works like a reverse .gitignore. You list the gitignored files that should be copied into each new worktree:

# .worktreeinclude
.env
config/master.key
config/credentials/development.key

When Claude creates a worktree, it reads this file and copies each listed file from the main checkout into the new directory. Your agents stop failing silently because they’re running without credentials.

Where Native Worktrees Fall Short

File isolation is necessary, but it’s not sufficient. Consider this scenario: two agents running your test suite at the same time. Both point at the same test database. Agent A inserts test data. Agent B’s assertions fail because the data doesn’t match what it expected.

You get flaky tests, data collisions, and corrupted state. The root cause is invisible because each agent’s test run passes when run alone.

True isolation for a Rails app requires three things:

1. A separate database per worktree so test runs don’t collide
2. Environment config (credentials, .env files) available in each worktree
3. Dependencies installed so the app can actually boot

The .worktreeinclude file handles environment config. Native worktrees handle the Git mechanics. But nothing handles the database. That’s the gap.

The WorktreeCreate Hook

Claude Code supports lifecycle hooks that run at specific moments during a session. The one we care about is WorktreeCreate. It fires every time a worktree is created, whether from the CLI flag, a mid-session request, or a sub-agent spawn.

This hook was originally designed for teams using version control systems other than Git, like SVN or Mercurial. It’s an extension point that lets you replace the default Git worktree behavior entirely with your own setup logic.

We can use that same extension point to bootstrap a full Rails environment.

Hook Configuration

Add the hook to your Claude Code settings at .claude/settings.json:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": ".claude/hooks/worktree-create.sh",
        "timeout": 60000
      }
    ]
  }
}

The timeout is set to 60 seconds. bin/setup can take a while, especially if it’s running database migrations.

When the hook fires, Claude passes JSON to stdin with the session context, including the working directory and session ID. Your script reads that input, does the setup, and prints the path to the created worktree to stdout. That’s the contract: print the path, exit zero, and Claude uses that directory.

The Setup Script

Here’s the full script. I’ll walk through each section below.

#!/usr/bin/env bash
set -euo pipefail

# WorktreeCreate hook: creates a git worktree, symlinks shared files,
# configures worktree-specific databases, and runs bin/setup.
#
# Input (JSON on stdin): { "name": "<slug>", "cwd": "<project-root>", ... }
# Output (stdout): absolute path to the created worktree directory
# All other output goes to stderr so it doesn't interfere with the path.

INPUT=$(cat)
NAME=$(echo "$INPUT" | jq -r '.name')
PROJECT_DIR=$(echo "$INPUT" | jq -r '.cwd')

WORKTREE_DIR="$PROJECT_DIR/.claude/worktrees/$NAME"

# -------------------------------------------------------------------
# 1. Create the git worktree
# -------------------------------------------------------------------
if [ -d "$WORKTREE_DIR" ]; then
  echo "Worktree directory already exists: $WORKTREE_DIR" >&2
  exit 1
fi

echo "Creating git worktree at $WORKTREE_DIR ..." >&2
git -C "$PROJECT_DIR" worktree add -b "$NAME" "$WORKTREE_DIR" HEAD >&2

# -------------------------------------------------------------------
# 2. Symlink entries from .worktreeinclude
# -------------------------------------------------------------------
INCLUDE_FILE="$PROJECT_DIR/.worktreeinclude"
if [ -f "$INCLUDE_FILE" ]; then
  echo "Symlinking entries from .worktreeinclude ..." >&2
  while IFS= read -r entry || [ -n "$entry" ]; do
    # Skip blank lines and comments
    entry=$(echo "$entry" | sed 's/#.*//' | xargs)
    [ -z "$entry" ] && continue

    SOURCE="$PROJECT_DIR/$entry"
    TARGET="$WORKTREE_DIR/$entry"

    if [ ! -e "$SOURCE" ]; then
      echo "  SKIP (not found): $entry" >&2
      continue
    fi

    # Ensure parent directory exists in the worktree
    mkdir -p "$(dirname "$TARGET")"

    # Remove the file/dir that git checkout placed there (if any)
    rm -rf "$TARGET"

    ln -s "$SOURCE" "$TARGET"
    echo "  Linked: $entry" >&2
  done <"$INCLUDE_FILE"
else
  echo "No .worktreeinclude file found, skipping symlinks." >&2
fi

# -------------------------------------------------------------------
# 3. Configure worktree-specific databases via .env.local
# -------------------------------------------------------------------
# Sanitize the name for use in database names (replace dashes with underscores)
DB_SLUG=$(echo "$NAME" | tr '-' '_')

ENV_LOCAL="$WORKTREE_DIR/.env.local"
echo "Writing worktree-specific database config to .env.local ..." >&2
cat >"$ENV_LOCAL" <<EOF
# Auto-generated for worktree: $NAME
DB_DATABASE=tracewell_development_${DB_SLUG}
DB_TEST_DATABASE=tracewell_test_${DB_SLUG}
EOF
echo "  Development DB: tracewell_development_${DB_SLUG}" >&2
echo "  Test DB:        tracewell_test_${DB_SLUG}" >&2

# -------------------------------------------------------------------
# Output: print the worktree path for Claude Code (must happen before
# any step that could fail so Claude Code can track the session)
# -------------------------------------------------------------------
echo "$WORKTREE_DIR"

# -------------------------------------------------------------------
# 4. Run bin/setup (skip starting the dev server)
# -------------------------------------------------------------------
echo "Running bin/setup --skip-server ..." >&2
(cd "$WORKTREE_DIR" && bin/setup --skip-server) >&2

The script does four things:

Creates the Git worktree. This replicates what Claude does natively, giving us a new branch and working directory.

Copies .worktreeinclude files. We re-implement this behavior since we’re replacing the default worktree creation. Each listed file gets copied from the main checkout into the new worktree.

Writes a .env.local with unique database names. This is the key part. The branch name gets transformed into a Postgres-safe format (hyphens become underscores) and used as a prefix for both the development and test database names. Your database.yml needs to read from these environment variables, falling back to defaults when they’re not set:

# config/database.yml
development:
  url: <%= ENV.fetch("DATABASE_URL", "postgres://localhost/myapp_development") %>

test:
  url: <%= ENV.fetch("TEST_DATABASE_URL", "postgres://localhost/myapp_test") %>

When .env.local exists in the worktree, the app picks up the unique database names. In your main checkout, the defaults apply as usual.

Runs bin/setup. This creates the databases, runs migrations, and installs dependencies. The worktree is fully bootable when the hook finishes.

Each worktree now points at its own development and test database. Two agents can run specs simultaneously without interference.

Cleaning Up with WorktreeRemove

Worktrees accumulate, and so do the databases they create. Claude Code automatically cleans up the worktree directory when you exit a session with no changes, but the databases stick around.

The WorktreeRemove hook mirrors the creation logic in reverse:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": ".claude/hooks/worktree-create.sh",
        "timeout": 60000
      }
    ],
    "WorktreeRemove": [
      {
        "command": ".claude/hooks/worktree-remove.sh",
        "timeout": 60000
      }
    ]
  }
}

The removal script reads the worktree path, derives the database names the same way the creation script did, and drops them:

#!/usr/bin/env bash
set -euo pipefail

# WorktreeRemove hook: drops worktree-specific databases and deletes the
# associated branch. Claude Code handles git worktree removal automatically.
#
# Input (JSON on stdin): { "name": "<slug>", "cwd": "<project-root>", ... }
# All output goes to stderr.

INPUT=$(cat)
NAME=$(echo "$INPUT" | jq -r '.name')
PROJECT_DIR=$(echo "$INPUT" | jq -r '.cwd')
WORKTREE_DIR=$(echo "$INPUT" | jq -r '.worktree_path')

if [ ! -d "$WORKTREE_DIR" ]; then
  echo "Worktree directory not found: $WORKTREE_DIR" >&2
  exit 0
fi

# Move to main repo before removing the worktree so the process cwd stays valid
cd "$PROJECT_DIR"

# -------------------------------------------------------------------
# 1. Drop worktree-specific databases via Rails
# -------------------------------------------------------------------
echo "Dropping databases for worktree: $NAME ..." >&2
(cd "$WORKTREE_DIR" && RAILS_ENV=development bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1) >&2
(cd "$WORKTREE_DIR" && RAILS_ENV=test bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1) >&2

# -------------------------------------------------------------------
# 2. Deregister the git worktree (required before branch can be deleted)
# -------------------------------------------------------------------
echo "Deregistering git worktree at $WORKTREE_DIR ..." >&2
git -C "$PROJECT_DIR" worktree remove --force "$WORKTREE_DIR" >&2

# -------------------------------------------------------------------
# 3. Delete the branch
# -------------------------------------------------------------------
if git -C "$PROJECT_DIR" rev-parse --verify "$NAME" >/dev/null 2>&1; then
  echo "Deleting branch: $NAME ..." >&2
  git -C "$PROJECT_DIR" branch -D "$NAME" >&2
else
  echo "Branch not found, skipping: $NAME" >&2
fi

echo "Worktree '$NAME' removed successfully." >&2

Alternatively, you could skip the hook and run a periodic cleanup script that finds orphaned databases and drops them. The hook approach is cleaner if you want everything automated.

Beyond Rails

These patterns aren’t Rails-specific. Rails conventions make the setup straightforward, but any application with external state has the same gap. Django, Phoenix, Laravel, if your app talks to a database, a cache, or a message queue, Git worktrees alone won’t isolate those resources.

The worktree gives you file isolation. The hook gives you everything else.

The mental model is simple: the WorktreeCreate hook is your opportunity to bootstrap whatever environment your application needs, and the WorktreeRemove hook is your opportunity to tear it down. What you put in those scripts depends entirely on your stack.

I covered the full setup process in a video walkthrough. If you want to see the hook in action, including the database creation and a parallel test run, watch it here.

If you’re looking to set up isolated agent workflows for your team or need help integrating Claude Code into your development process, let’s talk.

Ralph is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: “Ralph is a Bash loop” - a simple while true that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.

This was used in a variety of ways. Two common ones were:

1. Unleash an agent to work on a single task on its own until it was done.
2. Unleash an agent to iterate through a backlog of work until it had completed all of it.

Today we’re going to explore the second one, using an agent loop to iterate through a project backlog.

Where Ralph Wiggum Falls Flat

The Ralph Wiggum plugin provides a command you call inside Claude Code. The session continues until a set of requirements have been met, at which point the loop exits. For example:

/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, bin/rails test and bin/rails lint must pass. Output <promise>COMPLETE</promise> when done."

There is a drawback to this approach though. Running the loop inside of a Claude Code session means we’re eating away at our context window. If you’ve read my blog post on Understanding Claude Code’s Context Window then you know that this can cause poor results as time goes on. This becomes exponentially worse if you are trying to loop through multiple pieces of work. The agent’s context window will be subject to context rot as different streams of work are worked on.

There is a solution though.

Bash Loops

Instead of running a Ralph Wiggum loop inside of the Claude Code instance, we can loop inside bash. In this version every iteration of the loop starts with a fresh context window, avoiding issues with context rot. This works via the --dangerously-skip-permissions flag, which allows Claude Code to run non-interactively without prompting for tool approvals. An example loop looks something like:

while true; do
  SESSION=$((SESSION + 1))
  TIMESTAMP=$(date +%Y%m%d_%H%M%S)
  COMMIT=$(git rev-parse --short=6 HEAD 2>/dev/null || echo "no-git")
  LOGFILE="${LOG_DIR}/${AGENT_NAME}_${TIMESTAMP}_${COMMIT}.log"

  echo "--- Session #${SESSION} starting at $(date) ---"
  echo "    Log: $LOGFILE"

  claude --dangerously-skip-permissions \
    -p "$(cat "$PROMPT_FILE")" \
    --model "$MODEL" \
    &>"$LOGFILE" || true

  echo "    Session #${SESSION} ended at $(date)"
  echo ""

  # Brief pause between sessions to avoid hammering if something is broken
  sleep 5
done

The $PROMPT_FILE is where the real work gets defined. It’s a markdown file that tells the agent exactly what to do during each session. Mine walks the agent through a full lifecycle: orient itself on the project, pick up the next issue from Linear, build the feature, run a code review with subagents, and open a pull request. It also includes guardrails like one issue per session, never break main, and what to do if blocked or stuck for more than 15 minutes.

Let’s walk through how each of these pieces works in practice.

How It All Fits Together

I decided to give this a try on my recent project CreatorSignal that I’ve been building during my live streams. While I’ve seen many people maintaining their backlogs in markdown files or custom Kanban board experiences within Claude Code, I prefer using Linear. I didn’t want to recreate a task management system just for the agent loop. With the Linear MCP in hand, here’s how I set it up.

PROGRESS.md

One of the core pieces is the PROGRESS.md file. While the individual tasks are tracked and maintained in Linear, this file is meant to serve as a sort of “memory” for the agents to understand what has been accomplished from a more holistic level. At the start of each loop, the PROGRESS.md file is read in. At the end of a loop, the agent writes to it what it has accomplished.

Example:

# Progress

## 2026-02-13

### PRX-27: Billing portal (Stripe Customer Portal integration) — DONE
- Created `BillingPortalController` with `show` and `create` actions
- Billing page displays current plan, price, next billing date
- "Manage Subscription" button creates Stripe BillingPortal::Session and redirects
- Free users see upgrade CTA; former subscribers can still access portal for invoices
- Cancellation pending state shown with reactivation option
- 11 request specs + 6 system specs, all passing (266 total)
- PR: https://github.com/dgalarza/CreatorSignal/pull/31
- Branch based on PRX-25 (chain: PRX-17 → PRX-23 → PRX-24 → PRX-25 → PRX-27)

Implementing an Issue

Using the Linear MCP, the agent finds the next highest priority issue to work on. It starts by looking at the “Todo” column and picks the next one up. If there’s nothing in Todo, it checks the backlog instead. From there it reads the issue’s details to understand the work that needs to be done. For the loop to work well, issues need to be spec’d out thoroughly. This gives the agent the highest chance of performing quality work without human supervision.

With an issue selected, the agent moves it to “In Progress”, creates a branch, and starts building. A task is not considered “done” unless the test suite and linters both pass. This is another critical piece for a successful agent loop. The agent must have solid ways of verifying its own work. Without automated checks, it’s difficult for the agent to understand success, and quality drops.

When the agent believes its work is ready, it comments on the Linear issue with a summary of what it built and moves the issue to “In Review”.

Code Review

Similar to my workflow described in How I Use Claude Code, the next step is to spawn subagents to perform code review. The agent uses the Task tool to spin up a reviewer that evaluates the diff against the issue requirements, checking for correctness, test quality, Rails conventions, security, and performance.

The review is posted as a comment on the Linear issue. This provides visibility into the full lifecycle of the work. I can see the main agent’s implementation summary alongside the code review feedback. The agent then resolves any feedback it received and posts a final comment on the Linear issue summarizing its decisions.

Pull Request

After the code review process is complete and feedback is addressed, the agent commits the work and opens a pull request. The Linear issue is moved to “Done”, and the agent writes its progress update to the PROGRESS.md file.

Clean Up

With everything complete, the agent’s last instructions are to check out the main branch and rebase against origin/main so that the next loop starts in a fresh state. The loop then exits cleanly. There’s a built-in pause after each iteration before the next one starts.

Visibility

This loop proved to work well. I connected Slack to my Linear project so I could see notifications coming in as the agent worked through issues. Each time an issue had its status updated, each time an agent completed its work, and each time an agent received and addressed review feedback, I could see the progress in real time.

Improving on the Workflow

While this initial pass at a loop was working well, I had some things I wanted to improve. First, as pull requests were getting opened and merged, some would end up becoming stale with merge conflicts given the speed at which new features were landing. Second, I wanted to be able to leave feedback on a pull request as if I was working with a team member and have it get addressed by the agent as part of the loop.

I solved this by adding a new step to the loop as follows.

Before picking up a new task, the agent runs bin/pr_check. This script looks through my open pull requests for any with the “needs-revision” label. If none need review feedback addressed, it checks for any that have gone stale with merge conflicts.

If a PR like this is found, the loop addresses one PR leaving the next for the next loop iteration. So whenever I had a PR that I felt had feedback I wanted addressed, I would leave comments on it and add the “needs-revision” label. The next time a loop happens the agent will pick it up and address the feedback.

# bin/pr_check
#
# Finds the first open PR that needs attention.
# Returns JSON with PR details if one needs work, or empty output if all clean.
#
# A PR "needs attention" if:
#   1. It has merge conflicts (mergeableStatus == CONFLICTING)
#   2. It has the "needs-revision" label
#
# Usage:
#   bin/pr_check           # returns JSON or empty
#   bin/pr_check --quiet   # exit code only (0 = needs attention, 1 = all clean)
#
# Output format:
#   {
#     "number": 42,
#     "branch": "damian/prx-7-exa-research-tools",
#     "title": "PRX-7: Exa research tools",
#     "url": "https://github.com/...",
#     "reason": "has_feedback",    # or "conflicting" or "conflicting,has_feedback"
#     "conflicting": true,
#     "has_feedback": true
#   }

The loop itself is about a 100 line bash script. I’ll be adding it to my Claude Code workflows this week and sharing it with my newsletter.

What Makes This Work

After running this loop across several sessions, a few things stand out as critical to getting quality results:

1. Fresh context per iteration. Running the loop in bash instead of inside a Claude Code session means each task gets a clean context window. This is the single biggest difference from the Ralph Wiggum approach.
2. Well-spec’d issues. The agent is only as good as the instructions it receives. Vague issues produce vague results. Detailed acceptance criteria and clear scope make all the difference.
3. Automated verification. Requiring passing tests and linters before a task is considered “done” gives the agent a concrete definition of success. Without this, quality drops fast.
4. Linear as the source of truth. Using an existing project management tool instead of reinventing one means I can see the full lifecycle of every issue, from backlog to done, with comments and status updates along the way.

The combination of these pieces turns what could be a chaotic autonomous loop into something that produces reviewable, mergeable work. It’s not perfect, and I still review every pull request before merging, but the amount of ground it covers between review cycles is significant.

Additional Reading

• MCPs vs Agent Skills: Understanding the Difference - The agent loop relies on the Linear MCP as its backbone. This post covers how MCPs and skills serve different roles in your workflow.
• Understanding Claude Code’s Context Window - A deep dive into how the context window works and why fresh context per iteration is so important.
• How AI Agents Remember Things - The PROGRESS.md pattern is essentially agent memory between loop iterations. This video covers how agents persist context across sessions.
• MCPs vs Skills: The Mental Model You’re Missing - The video companion to the blog post above, covering the architectural distinction between MCPs and skills.
• Building CreatorSignal - The livestream series where I’m building CreatorSignal, the project this agent loop runs against.

If you haven’t already, sign up for my newsletter for weekly emails on AI Engineering and agentic development workflows.

If you’re building agent loops or autonomous workflows and want help getting the architecture right, I work with teams on exactly this. Let’s talk.

In this live coding session, I start a brand new Ruby on Rails SaaS app and build user authentication from zero using Claude Code. But this isn’t a “how to build auth in Rails” tutorial. It’s a deep look at how I actually use Claude Code to drive development: plan mode, custom skills, TDD workflows, iterating on Claude’s memory, sub-agent code reviews, and more.

I’ve been asked this question a lot since Anthropic announced Agent Skills back in October 2025. And honestly, the confusion makes sense. Both extend Claude Code’s capabilities. Both can connect to external services. Skills can even run scripts, which sounds a lot like what MCPs do.

But once you understand the mental model, the distinction becomes obvious. Let’s break it down.

What MCPs Actually Do

Model Context Protocol is an open standard for connecting AI applications to external systems. It’s the plumbing that connects Claude to the outside world by exposing tools that can read data, execute actions, and interact with external services.

For example, you can add the Linear MCP and give Claude the ability to read and create issues, or add the Sentry MCP so it can query errors. These are capabilities Claude didn’t have before. MCPs extend what Claude can do.

There’s something you need to consider when adding MCPs though: every MCP you add to Claude Code takes up space in your context window just by being available. Not just when it’s used, but constantly. If you’ve read my post on Understanding Claude Code’s Context Window, you know this matters a lot.

The Anatomy of an MCP Tool

Every MCP tool exposes information to the LLM so it knows when and how to use it. Here’s what Claude sees when the Linear MCP is configured:

│ get_issue (linear-server) [read-only]                                        │
│ Tool name: get_issue                                                         │
│ Full name: mcp__linear-server__get_issue                                     │
│                                                                              │
│ Description:                                                                 │
│ Retrieve detailed information about an issue by ID, including attachments   │
│ and git branch name                                                          │
│                                                                              │
│ Parameters:                                                                  │
│   • id (required): string - The issue ID                                     │
│   • includeRelations: boolean - Whether to include blocking, related,        │
│     and duplicate relations in the response                                  │

The description tells the LLM when and why to use the tool. Some descriptions are verbose, which means they consume more tokens on every single message. The parameter schema is typically JSON that defines the tool’s inputs. And the tool name is what the LLM calls to invoke it.

Here’s why this matters: in Build Efficient MCP Servers: Three Design Principles, I showed how a Claude Code session can have 24% or more of the context window consumed by MCP tool definitions before you’ve even started a conversation. Add a few feature-rich MCP servers and you’ve got precious little space left for actual work.

This used to create a hard practical limit. Too many MCPs and the model would get confused, more likely to pick wrong actions. Anthropic addressed this in January 2026 with MCP Tool Search, which dynamically loads MCP tools on-demand when they would consume more than 10% of context. This helps, but the underlying tension remains: MCP tool definitions compete for context space, which is why skills use a different approach entirely.

The Key Characteristics

MCPs are:

• Single-purpose tools - Each tool does one specific thing
• Autonomous - Claude can call them directly without any instruction from you
• Always loaded - Tool descriptions are in context on every message (or dynamically loaded via MCP Tool Search)
• Bidirectional - Can read from and write to external systems

When you ask Claude “What’s the status of issue TRA-123?”, it can autonomously decide to call the Linear MCP to fetch that information. No skill needed, no special invocation. The capability is just there.

What Agent Skills Actually Do

Since the original announcement of Agent Skills, Anthropic has released Agent Skills as an open standard, and other tools like GitHub Copilot and Cursor now support them as well.

At first glance, skills look simple. They’re essentially a folder with some markdown files and optionally some scripts:

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed docs (loaded as needed)
├── examples.md        # Usage examples (loaded as needed)
└── scripts/
    └── helper.py      # Executable scripts (run, not loaded)

Skills typically live in .claude/skills/ within your project or ~/.claude/skills/ for global availability.

Skills can execute code. But that’s not what makes them special. What makes them special is orchestration. They compose multiple capabilities into a defined workflow.

A tool lets Claude query your database. A skill teaches Claude your company’s specific data model, your naming conventions, your rollback procedures. MCPs are verbs. Skills are playbooks.

The Four Flavors of Skills

In my experience, skills tend to fall into four categories:

Specialized workflows are multi-step procedures for specific domains. Things like a TDD workflow, a PR review process, or a deployment checklist. These are the skills I use most often.

Tool integrations are instructions for working with specific file formats or APIs. Maybe you need Claude to know how to process DOCX files, manipulate PDFs, or query BigQuery a specific way.

Domain expertise captures company-specific knowledge. Your data model, your naming conventions, your rollback procedures. The stuff that lives in tribal knowledge.

Knowledge retrieval bundles reference documentation that Claude can access on demand. API specs, style guides, architectural decision records. Rather than stuffing everything into CLAUDE.md, you package it into a skill that loads only when relevant.

Why Skills Exist: Progressive Disclosure

The key design principle behind skills is progressive disclosure. Unlike MCPs where tool definitions are always present, skills only load their full content when invoked.

The most basic skill is a folder with a SKILL.md file. This file contains YAML frontmatter with metadata (name and description) followed by the actual instructions. For any given skill, only the metadata is persistently available. The description tells the LLM when to invoke the skill, so you need to capture the right semantics for the agent to pick it up appropriately.

Once the skill is invoked, the LLM loads the rest of the SKILL.md file into context and follows its instructions. You can also break skills into separate resource files for different scenarios or workflows. This lets you keep context lean by loading only what’s needed for the current task.

What This Looks Like in Practice

In How I Use Claude Code: My Complete Development Workflow, I described my linear-implement skill that takes a Linear issue and implements a solution following TDD. Here’s how the pieces fit together:

┌──────────────────────────────────────────────────────────────┐
│                        SKILL                                 │
│                 (orchestration layer)                        │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Bundled: scripts/ │ references/ │ assets/               │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│    ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│    │  MCP    │  │  Bash   │  │  File   │  │  Web    │       │
│    │ (Linear)│  │ (tests) │  │ (write) │  │ (fetch) │       │
│    └─────────┘  └─────────┘  └─────────┘  └─────────┘       │
└──────────────────────────────────────────────────────────────┘

The skill sits on top and orchestrates everything. It calls the Linear MCP to fetch issue details. It runs bash commands to execute tests. It writes code files following TDD. It creates PRs via the GitHub CLI.

Without a skill, Claude can do all these things individually. But you have to orchestrate each step manually. Every session, you re-explain the workflow. With a skill, one command triggers the entire workflow. Consistent process every time. Your expertise encoded into Claude’s behavior.

The CLAUDE.md vs Skills Question

A common point of confusion: when should something go in CLAUDE.md versus a skill?

Here’s how I think about it:

CLAUDE.md is for declarative knowledge. What and why. Background context that Claude should just know. “This is Rails 7 with RSpec.” “We use JSON:API format.” “Run tests with bin/rspec.”

Skills are for procedural knowledge. How. Multi-step workflows with defined steps. “When implementing a feature, follow this TDD workflow…” “To deploy, run these 5 steps…”

The analogy that works for me: CLAUDE.md is like an employee handbook (background context). Skills are like training modules (specific procedures).

If you’re copy-pasting the same multi-step instructions into chat repeatedly, that’s a skill waiting to be created. If it’s background context Claude should just know, it belongs in CLAUDE.md.

There’s a practical difference too. CLAUDE.md is always loaded in context, so it should stay lean. Skills use progressive disclosure, so they can be extensive without penalty when not in use.

Putting It Together

Now that we’ve covered what each one does separately, let me show you what it looks like when they work together.

┌─────────────────────────────────────────────────────────────────┐
│  Prompt: "Help me implement Linear TRA-123"                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  SKILL activates (context match)                                │
│  → Loads bundled resources, defines workflow                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              ┌──────────┐       ┌──────────┐
              │   MCP    │       │  Native  │
              │ (Linear) │       │  Tools   │
              │          │       │          │
              │ Fetches  │       │ Bash,    │
              │ issue    │       │ File ops │
              │ details  │       │ for TDD  │
              └──────────┘       └──────────┘
                    │                   │
                    └─────────┬─────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Result: Feature implemented following TDD workflow             │
└─────────────────────────────────────────────────────────────────┘

The MCP gives access to Linear (the capability). The skill orchestrates the workflow (the recipe). Each has its role.

The Two Questions

You might be thinking there’s overlap here. Since skills can have scripts, can’t they also connect to external services? Yes, they can. Skills can include scripts that hit APIs, run curl commands, whatever you need. The difference is that these scripts only run in the context of the skill itself. If you need something more general purpose that Claude can call from any context, you want an MCP instead.

When Claude needs to check Linear issues, it can do that anytime, in any context, without any special setup. That’s an MCP’s job. But when you say “implement this feature,” you want a specific sequence of steps followed in a specific order. That’s a skill’s job.

When I need to decide which to use, I ask myself two questions:

Question 1: Should Claude be able to call this capability anytime, across any context?

If yes, you need an MCP.

If only during a specific workflow, a skill with scripts is fine.

Checking Linear issues? That’s something Claude might need to do in many different contexts. MCP makes sense. Deploying to staging? That’s a specific workflow with defined steps. Skill makes sense.

Question 2: Is this a repeatable workflow with defined steps?

If yes, build a skill (with or without MCPs).

If no, you might not need either. Just ask Claude directly.

If you find yourself explaining the same multi-step process to Claude repeatedly, that’s your signal. That’s when you build a skill.

Common Patterns

Here’s how this plays out in practice:

MCP alone: “Check my Linear issues.” Claude decides to call it autonomously.

Skill using MCP: “Implement TRA-123.” The skill orchestrates the workflow, calling the Linear MCP as one step among many.

Skill with scripts: “Deploy to staging.” The workflow runs deploy scripts that hit external services.

Skill without external calls: “Follow our TDD process.” Pure internal workflow, no external systems needed.

The Mental Model

That’s the mental model. MCPs give Claude capabilities. Skills give Claude orchestration. Or to put it another way:

MCPs = The tools in the toolbox Skills = The recipes that coordinate those tools

MCPs are the plumbing connecting Claude to the outside world. Skills are the playbook of procedural knowledge.

MCPs answer “what can Claude access?” Skills answer “how should Claude approach this task?”

Getting Started

If you’re just getting started, here’s my recommendation:

Start with MCPs. Find one that connects to a tool you already use. Linear, Sentry, your database, whatever. Install it and start calling it. Get a feel for how Claude uses capabilities autonomously.

Watch for patterns. When you notice you’re asking Claude the same multi-step sequence over and over, that’s your signal. That’s when you build a skill.

Keep it simple. Your first skill doesn’t need to be complex. Start with a workflow you repeat weekly, document the steps, and let Claude follow them consistently.

If you want to build your own skill from scratch, check out my video Claude Code Tutorial: Build your first skill in 10 minutes where I walk through creating a TDD workflow skill step by step.

For more examples, sign up for my newsletter. You’ll get access to my claude-code-workflows repo on GitHub, which includes several skills I use daily, including the linear-implement workflow that ties everything together.

Further Reading

• MCPs vs Skills
• Agent Skills - Anthropic Engineering Blog
• Agent Skills Specification
• Understanding Claude Code’s Context Window
• How I Use Claude Code: My Complete Development Workflow
• Build Efficient MCP Servers: Three Design Principles

Working through how to structure your Claude Code setup with the right mix of MCPs and skills? I help engineers and teams design workflows that stick. Learn more.

In this tutorial, I’ll show you my exact Claude Code git worktree setup for running multiple agents on the same repo. No file collisions, no database locks, no branch chaos.

In this step-by-step tutorial, I show you how to create a Claude Code skill from scratch. You’ll learn how Claude Code skills work, where they live, and how to write instructions that make Claude follow proper red-green-refactor TDD.

🔑 The simple framework:

• MCPs = Capabilities (tools that give Claude new powers)
• Skills = Orchestration (workflows that teach Claude processes)

⏱️ Timestamps:

0:00 The Confusion Everyone Has 0:21 Model Context Protocol 2:51 Agent Skills 6:42 CLAUDE.md Confusion 8:03 The Framework

📚 Resources mentioned:

• Understanding Claude Code’s Context Window: https://www.damiangalarza.com/posts/2025-12-08-understanding-claude-code-context-window/
• Claude Code Skills docs: https://agentskills.io/
• MCP documentation: https://modelcontextprotocol.io/

Get my Claude Code workflows + weekly insights: → https://www.damiangalarza.com/newsletter?utm_source=youtube&utm_medium=video&utm_campaign=parallel-agents

→ Want to level up your Claude Code setup? www.damiangalarza.com/claude-code

Affiliate links — I may earn a commission or credits at no cost to you: 🚂 Railway (where I deploy): https://railway.com?referralCode=dgalarza

About me: I’m Damian Galarza, former CTO with 15+ years building SaaS products. I make practical AI tutorials for developers who want to work smarter with tools like Claude Code.

Work with me:

• 1:1 Coaching: https://www.damiangalarza.com/coaching
• Newsletter: https://www.damiangalarza.com/newsletter
• Blog: https://www.damiangalarza.com

#ClaudeCode #claudecodetutorial #AI #DeveloperTools #MCP #Programming #AgentSkills

🎯 Want help setting up MCPs and debugging workflows for your team? Book a 1:1 session: → https://www.damiangalarza.com/coaching/?utm_source=youtube&utm_medium=video&utm_campaign=sentry-mcp

Claude Code is Anthropic’s official CLI tool that lives in your terminal, reads your code, makes edits, and runs commands. In this video, I’ll take you from zero to productive with a real project.

In this post we’ll look at how you can make the most of your available context window in Claude Code, as well as some common pitfalls to avoid.

Understanding the Context Window

Before we can begin to try to optimize our developer workflow we need to get an understanding of what the context window is and how it gets filled. The context window is how much content a large language model can hold onto at one time. Each model has predefined limits to the size of its context window. For example, Claude Sonnet 4.5’s context window is about 200,000 tokens.

What is a Token?

When you send text to an LLM, it doesn’t process words one at a time. Instead, text is broken into tokens—the fundamental units that language models read and generate. A token typically represents 3-4 characters, or roughly 0.75 words in English.

For example, the phrase "Hello world" becomes 2-3 tokens, while a compound word like authentication_middleware might be split into 5-7 tokens despite being a single identifier. Code tends to be more token-dense than prose because of special characters, naming conventions, and syntax. This is why reading source files consumes context faster than you might expect.

Why Token Efficiency Matters

Context windows have limited space, and filling them with code happens fast. But running out of room isn’t the only concern. LLMs suffer from a “lost in the middle” problem. Content at the start and end of the context window gets prioritized, while information in the middle tends to get overlooked. This mirrors how human memory works (we remember beginnings and endings better than middles).

Additionally, our code isn’t the only thing consuming context window space. Our context window is going to be filled by:

MCP Servers

Every MCP server you add is going to take some amount of space in your context window just by being available and present. Every MCP tool definition comes with:

1. Tool name (e.g., mcp__ynab__get_transactions)
2. Description - an explanation as to what the tool does so that the LLM can understand when it might be needed.
3. Parameter Schema - JSON schema definition of all the parameters, types, descriptions and constraints.
4. Usage notes - additional instructions and potentially examples to guide the LLM during its tool choice.

Let’s take a look at an example from the YNAB MCP I built and discussed in Build Efficient MCP Servers: Three Design Principles.

{
    "name": "mcp__ynab__get_transactions",
    "description": "Get transactions from YNAB budget.\n\n    Retrieves transactions with optional filtering by date
   range, account, or category.\n    Returns transaction details including date, amount, payee, category, and
  memo.\n\n    Use this tool when you need to:\n    - View recent transactions\n    - Find transactions in a
  specific date range\n    - Filter transactions by account or category\n    - Check transaction details for
  reconciliation\n\n    Args:\n        budget_id: Budget ID or 'last-used' for default budget\n        since_date:
  Optional start date (YYYY-MM-DD format)\n        until_date: Optional end date (YYYY-MM-DD format)\n
  account_id: Optional account ID to filter by specific account\n        category_id: Optional category ID to filter
   by category\n        type: Optional transaction type ('uncategorized', 'unapproved')\n\n    Returns:\n
  JSON array of transactions with:\n        - id: Transaction ID\n        - date: Transaction date\n        -
  amount: Amount in milliunits (divide by 1000 for dollars)\n        - memo: Transaction memo\n        - cleared:
  Cleared status\n        - approved: Approval status\n        - payee_id: Payee ID\n        - payee_name: Payee
  name\n        - category_id: Category ID\n        - category_name: Category name\n        - account_id: Account
  ID\n        - account_name: Account name\n\n    Example usage:\n        Get all transactions from November 2024:\n
          since_date='2024-11-01', until_date='2024-11-30'\n\n        Get recent uncategorized transactions:\n
    type='uncategorized'\n\n    Note: Amounts are returned in milliunits. Divide by 1000 to get dollar amounts.\n
   ",
    "parameters": {
      "type": "object",
      "properties": {
        "budget_id": {
          "type": "string",
          "description": "Budget ID or 'last-used' for default budget"
        },
        "since_date": {
          "type": "string",
          "description": "Optional start date (YYYY-MM-DD format)",
          "format": "date"
        },
        "until_date": {
          "type": "string",
          "description": "Optional end date (YYYY-MM-DD format)",
          "format": "date"
        },
        "account_id": {
          "type": "string",
          "description": "Optional account ID to filter by"
        },
        "category_id": {
          "type": "string",
          "description": "Optional category ID to filter by"
        },
        "type": {
          "type": "string",
          "enum": ["uncategorized", "unapproved"],
          "description": "Optional transaction type filter"
        }
      },
      "required": ["budget_id"],
      "title": "GetTransactionsArguments"
    }
  }

Token Breakdown

This one tool definition takes up about 663 tokens. Not terrible on its own, but my YNAB MCP has about 15 tools. As you add more and more MCP servers to your stack you are consuming more and more of your context window from tool definitions alone. So it’s important to be careful not to overload your coding assistant with too many MCP servers.

The community has been exploring new ways to make MCP servers more context efficient. One approach Anthropic has written about is allowing code execution within MCP servers. You can learn more about this in Code execution with MCP: Building more efficient agents but the short version is instead of having an MCP server expose lots of different tools, it exposes a single tool or handful of tools which can then execute their own code in a sandboxed environment to achieve results on its own. Anthropic also recently announced a beta feature for advanced tool use in Claude. One of the stand out updates here is moving away from a static tool list to being able lazily load tool definitions via a tool search tool.

Both of these are in their early stages so we’ll continue to need to be careful about how many MCP servers we add to our coding agents and how much of the context window they consume. With that out of the way let’s take a look at a real world scenario of a context window in a development environment and how we can make the best out of it.

A View Into Your Context Window

Claude Code provides us with a command we can run within a session called /context. This command will report back the current state of your context window including how much space everything is taking up. Let’s take a look at the output of /context within Tracewell AI:

Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-sonnet-4-5-20250929 · 101k/200k tokens (51%)
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛶   ⛁ System prompt: 3.1k tokens (1.6%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 19.8k tokens (9.9%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 26.5k tokens (13.3%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Custom agents: 2.8k tokens (1.4%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 4.0k tokens (2.0%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛁ Messages: 8 tokens (0.0%)
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛶ Free space: 99k (49.4%)
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: 45.0k tokens (22.5%)

MCP tools · /mcp
└ mcp__memory__create_entities (memory): 686 tokens
└ mcp__memory__create_relations (memory): 689 tokens
└ mcp__memory__add_observations (memory): 668 tokens
└ mcp__memory__delete_entities (memory): 612 tokens
└ mcp__memory__delete_observations (memory): 666 tokens
└ mcp__memory__delete_relations (memory): 690 tokens
└ mcp__memory__read_graph (memory): 568 tokens
└ mcp__memory__search_nodes (memory): 607 tokens
└ mcp__memory__open_nodes (memory): 609 tokens
└ mcp__sentry__whoami (sentry): 602 tokens
└ mcp__sentry__find_organizations (sentry): 735 tokens
└ mcp__sentry__find_teams (sentry): 1.0k tokens
└ mcp__sentry__find_projects (sentry): 999 tokens
└ mcp__sentry__find_releases (sentry): 1.2k tokens
└ mcp__sentry__get_issue_details (sentry): 1.4k tokens
└ mcp__sentry__get_trace_details (sentry): 1.3k tokens
└ mcp__sentry__get_event_attachment (sentry): 1.3k tokens
└ mcp__sentry__update_issue (sentry): 1.5k tokens
└ mcp__sentry__search_events (sentry): 1.5k tokens
└ mcp__sentry__find_dsns (sentry): 1.0k tokens
└ mcp__sentry__analyze_issue_with_seer (sentry): 1.3k tokens
└ mcp__sentry__search_docs (sentry): 1.8k tokens
└ mcp__sentry__get_doc (sentry): 768 tokens
└ mcp__sentry__search_issues (sentry): 1.5k tokens
└ mcp__sentry__use_sentry (sentry): 968 tokens
└ mcp__context7__resolve-library-id (context7): 887 tokens
└ mcp__context7__get-library-docs (context7): 957 tokens

Custom agents · /agents
└ rails-backend-expert (Project): 444 tokens
└ cybersecurity-expert (Project): 287 tokens
└ prompt-engineer (Project): 609 tokens
└ tailwind-viewcomponent-expert (Project): 417 tokens
└ product-strategy-advisor (Project): 608 tokens
└ regulatory-510k-consultant (Project): 459 tokens

Memory files · /memory
└ User (/home/dgalarza/.claude/CLAUDE.md): 10 tokens
└ Project (/home/dgalarza/Code/tracewell.ai/CLAUDE.md): 4.0k tokens

SlashCommand Tool · 16 commands
└ Total: 2.7k tokens

As you can see this gives us a nice detailed view of our context window, including what percentage of the context window is currently available and a breakdown of what is taking up space. From it we can see that my MCP tools are taking up 26.5k tokens which is about 13.3% of the Claude Sonnet 4.5 context window. Aside from that, we can see that the Custom agents that are defined and available are taking up about 2.8k tokens, my project’s CLAUDE.md is 4k tokens and about 22% of the context window is reserved for autocompacting.

What is autocompacting?

In order to understand autocompacting we first need to understand how a typical conversation flows within the Anthropic API. By default, every call to the Anthropic Claude API has no recollection of previous parts of a conversation. Instead as the consumer of the API we need maintain that conversation history and provide it to the API. Take a look at the following diagram:

You can see that the first request kicks off the conversation with “Add error handling to the auth module”. From there we get a response back from the LLM with the result of what it did. When the user then continues the conversation in request 2, we can see they say “Now add tests for those changes”. You can see here though that we actually end up sending the full conversation history, with our first message, along with the response from the LLM and now our new message. This is a simplified example which doesn’t include tool calling. Any tool call requests would also be in this history as well as the results from tool calling. As your conversation gets longer and longer, more and more of the context window is being taken up. As you approach the limit of the context window space must be freed up. One way to do this is compaction.

Compacting the context window is a context engineering technique to compress a long running conversation or session by summarizing the conversation in order to free up space. This summarization is typically handled by an LLM. This generated summary then becomes the basis of the remainder of the conversation. Compacting the conversation history can sometimes work well. However it’s not an exact science and you are beholden to the LLM to identify the correct things to include in the summary. If you’ve ever had a long running conversation with Claude Code and started feeling like things have started to go off the rails, you might have experienced this. In the long conversation you might end up with multiple autocompact calls where now the LLM is summarizing a summarization along with the rest of the conversation.

Warning signs of problematic autocompact:

• Claude forgets decisions you made earlier in the conversation
• Claude repeats work it already completed
• Claude asks questions you already answered
• Solutions start contradicting earlier approaches

When you notice these symptoms, it’s usually time for a /clear and a fresh start rather than continuing to fight against a degraded context.

Managing Your Context Window

Now that we understand what the context window is, how a conversation’s history occurs and how it impacts the context window let’s explore different ways to manage the context window to make the most out of it.

Delegating to Subagents

Claude Code has the ability to spin off “subagents” when it’s working. These subagents each have their own context window which is separate from the main conversation. This gives us two advantages. First, the subagent’s context window isn’t cluttered with our previous conversation history. Second, and this is the flip side, our main conversation isn’t cluttered with all the details of whatever the subagent was instructed to work on. Instead, it reports back its results. You can see this in action with Claude Opus 4.5 whenever you plan something. It typically delegates its tasks out to subagents to help aid with the plan.

⏺ 3 Explore agents finished (ctrl+o to expand)
   ├─ Explore Tracewell Agent workflow · 23 tool uses · 104.5k tokens
   │  ⎿ Done
   ├─ Explore Tracewell DHF extractions · 28 tool uses · 108.0k tokens
   │  ⎿ Done
   └─ Explore eval framework · 24 tool uses · 101.8k tokens
      ⎿ Done

You can also instruct Claude to invoke a subagent explicitly. Some examples:

• “Have a subagent do a code review of this branch against main”
• “Use a subagent to explore how authentication works in this codebase”
• “Spawn a subagent to research different caching strategies for this use case”

When the subagent completes, you’ll see a summary like this in your main conversation:

⏺ Task agent finished · 15 tool uses · 52.3k tokens
  ⎿ The code review found 3 issues: [summary of findings...]

Notice that the subagent used 52k tokens of its own context, but your main conversation only receives the summary. This is the key benefit: the detailed work happens in isolation.

I’ve found subagents work best for self-contained tasks that require reading lots of files. Code reviews are a natural fit. The subagent can dig through diffs without polluting your main context. The same goes for codebase exploration when you’re trying to understand how an unfamiliar feature works across multiple modules. Research tasks also work well here; you can have a subagent investigate implementation options and report back before you commit to an approach.

Using Custom Agents

Custom agents take subagents to another level. They allow us to define a custom agent with a persona and expertise area which makes use of the same functionality of subagents where they have their own context window. Additionally we can also define what tools it has access to. This is useful if you are defining an agent that you know doesn’t need specific tools so their tool definitions don’t need to take space in the context window.

An agent is a markdown file which lives in either ~/.claude/agents or .claude/agents. You can provide it a name, a description, a model, and tools which it is allowed to use. This is all handled via YAML frontmatter. After the frontmatter you define the agent itself.

Let’s take a look at a practical example.

In Tracewell I have defined a few subagents that you can see in the earlier /context output. The rails-backend-expert doesn’t need access to the Linear MCP so I can choose not to give the agent access to it or any of its tools. This is handled by setting an allow list of what tools you want to give the model access to:

---
name: rails-backend-expert
description: Use this agent when working on Ruby on Rails backend code, including models, controllers, services, jobs, database migrations, API endpoints, background processing, or any server-side Ruby logic.
tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, AskUserQuestion, Skill, SlashCommand, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__delete_entities, mcp__memory__delete_observations, mcp__memory__delete_relations, mcp__memory__read_graph, mcp__memory__search_nodes, mcp__memory__open_nodes, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
model: sonnet
---

You are a Ruby on Rails backend expert. Your role is to help with...

The agent’s full persona and instructions follow after the frontmatter. I recommend using the /agents command to get started. From there Claude will walk you through creating your first agent. When doing so Claude will ask you if you want Claude to generate or manually configure the agent. I recommend going with its recommended approach which is to have Claude create the agent. You can provide a high level prompt and it will then generate the full agent description for you. As part of the wizard for creating the agent Claude will ask you what tools you want the agent to have access to.

Claude Skills

In October 2025 Anthropic announced Agent Skills a way of encapsulating domain expertise or workflows for agents to follow. Skills are organized in folders with a core SKILL.md file which has frontmatter that has required metadata such as the name and the description. The body of the SKILL.md contains the instruction set of the skill itself.

When Claude Code starts, it loads the name and description of every skill available into its context via the system prompt. This allows Claude to use progressive disclosure in determining when to use a skill without loading the entire thing into its context window. This can be a powerful tool that can even potentially replace some MCP servers. This is possible because skills can also contain scripts that Claude can run. Instead of having to always expose tools into the context window via an MCP server you can provide a skill which has scripts that it can run that only get added to the agent’s context window when it is useful.

A great example of this is the Playwright Skill for Claude Code by Bryan Lackey. Previously if you wanted to easily add Playwright to Claude Code for interfacing with your web application, you’d add the playwright-mcp. The playwright-mcp adds 22 tools which consume about 14.3k tokens, which is 7.2% of your context window just by being available.

The skill, by contrast, only adds about 200 tokens at startup for its name and description. The full SKILL.md (around 4-5k tokens) only loads when you actually invoke the skill. If you use Playwright in maybe one out of every five sessions, you’re saving roughly 10k tokens in the sessions where you don’t need it.

Using clear

Another tool at your disposal is to use the /clear command often. This command resets / empties the context window providing a fresh start. I highly recommend that you do this often especially when you have completed a distinct task and are moving onto a new one where the previous conversation history is no longer needed or useful.

Compacting the conversation manually

Along with autocompact you can also manually choose when to compact a conversation. You can do this by running /compact. It takes an optional argument which is instructions on how Claude should perform the compaction. You can guide Claude to make sure that it captures certain information while generating its summary and compacting the conversation. I recommend this when you have made significant progress on your work and are moving onto some related work. Perhaps Claude broke up the work into multiple phases and you just completed phase 1. You could:

1. Use /clear to reset the context window. However, if you didn’t persist the plan / TODO list somewhere you’ll start from scratch.
2. Continue until autocompact kicks in and you let the LLM do the heavy lifting of summarizing / compacting the conversation.

Instead, I’d recommend using the /compact command and instruct Claude to summarize the progress you’ve made so far and start with a “fresh” context window on the next phase of work. I say “fresh” since we aren’t fully clearing the context window but are compressing the previous conversation.

Being Strategic About File Reads

It’s easy to overlook how quickly file reads consume context. Every time Claude reads a file, that content gets added to the conversation history. Large files, broad grep results, or reading several files in sequence can eat through your available context faster than you’d expect.

A few things I’ve learned to do:

• When I know roughly where something is, I’ll point Claude to specific line ranges rather than having it read entire files. For example: “Look at the authenticate method in app/services/auth_service.rb around lines 45-80” instead of just “check the auth service”
• I try to use targeted grep patterns before asking Claude to read files. Narrowing down candidates first means fewer files loaded into context. For example, instead of “find where we handle webhook failures”, I might say “grep for webhook.*fail or handle.*webhook in app/services/ and show me the matches before reading any files.” This way Claude identifies the 2-3 relevant files first rather than speculatively reading 10 service files looking for the right one.
• For orientation questions like “what does this module do?”, asking Claude to summarize rather than read the whole thing can save significant tokens

This becomes especially important in larger codebases where a single exploration session can involve dozens of file reads.

Optimizing Your CLAUDE.md

Your project’s CLAUDE.md file loads into every conversation, so it’s worth keeping it lean. Looking back at my /context output, my project’s CLAUDE.md takes up 4k tokens, which is 2% of my context window before I’ve even started working.

A few things to keep in mind:

• Bullet points tend to be more token-efficient than prose
• Put the most critical instructions at the beginning since Claude pays more attention to the start and end of content (that “lost in the middle” problem again)
• Consider whether instructions belong at the project level or could live in your user-level ~/.claude/CLAUDE.md instead
• Periodically audit for outdated instructions that no longer apply

It’s a balancing act. You want enough context for Claude to understand your project’s conventions, but not so much that you’re burning tokens on rarely-relevant details.

Best Practices for Context Window Management

1. Monitor regularly - Run /context at the start of each session to understand your baseline usage
2. Audit your MCP servers - Remove any MCP servers you haven’t used recently; each one consumes tokens just by existing
3. Prefer skills over MCP servers - When building new functionality, consider skills first for better context efficiency through progressive disclosure
4. Clear between tasks - Use /clear liberally when switching between unrelated work
5. Strategic compacting - Use /compact with custom instructions when transitioning between related phases of work
6. Delegate complex work - Use subagents for self-contained tasks to keep their context isolated from your main conversation

Running a team on Claude Code? Context window management gets harder with 5+ engineers making different choices about MCP servers, CLAUDE.md conventions, and workflow patterns. A Production AI Retainer standardizes this across your team.

Conclusion

Context management isn’t just about avoiding limits; it’s about keeping your conversations focused and effective. A cluttered context window leads to degraded responses, just like a cluttered desk makes it harder to find what you need.

The key takeaways: monitor your usage with /context, delegate to subagents for isolated work, and use /clear liberally between tasks. When possible, prefer skills over MCP servers for better context efficiency through progressive disclosure.

Start by running /context in your next Claude Code session to see where your tokens are going. You might be surprised by what you find.

Update: With Claude Opus 4.7’s 1M token context window, the fundamentals here still apply but the ceiling and controls have changed. See 7 Practical Tips for Maximizing Extended Context for workflow adjustments specific to the larger window.

If this post was the explanation, the cheat sheet is the reference. Two sides: token costs for common MCPs on one, the /clear / /compact / subagent decision tree on the other.

Get the Context Window Cheat Sheet →

During this time my workflow has evolved significantly. This is partly from learning how to get the most out of it, but also from the Anthropic team’s continuous improvements to the product. New features are coming out at a rapid pace.

There’s an ongoing debate in our industry. Some developers swear by AI assistants while others remain skeptical. You hear stories about companies claiming developers are no longer needed, alongside dismissals that AI-generated code is always garbage. I find myself somewhere in the middle.

I believe using these tools is a skill in and of itself. When people tell me “it takes longer to get the LLM to do it right” or “I can do it faster myself,” I understand where they’re coming from. When I first started programming, I was slow too. But I got faster with practice. The same applies to working with agentic development tools.

This post walks through my typical Claude Code workflow. While I focus on Claude Code specifically, these concepts apply to many agentic coding tools.

Context is King

One of the biggest complaints I hear from developers goes something like this: “I tried using an AI assistant but it just wouldn’t get it right. I spent so much time trying to get it to do what I wanted and eventually gave up.”

I’ve written about how MCP tools consume the context window before. But context matters in other ways too.

When I dig deeper into these frustrations, I typically ask how they prompted the LLM. The answer is usually a fairly vague prompt. In a smaller codebase this might work fine, but in an established codebase it often falls short. We need to give the LLM a well-structured problem.

One thing I’ve learned is that developers who have experience managing or delegating tasks tend to adapt quickly. They already understand how to break down problems into small pieces for someone else to work on. This is why I spend time breaking down problems into bite-sized chunks—a common practice in agile development.

For example, while building Tracewell AI I work with Linear for issue tracking. Even though I’m typically working alone, being disciplined about creating issues pays off. I often use Claude via the desktop app or terminal to scope out work, break down problems, and create Linear issues. This upfront work makes implementation much smoother.

Tools I Use

My Claude Code setup relies on a few key tools that work together to provide rich context. Each addresses a different aspect of development—project management, error tracking, version control, and memory—creating a network of information that Claude can draw from when planning and implementing features.

Linear MCP Server

The Linear MCP Server is a backbone of my workflow. It gives Claude direct access to project issues, enabling both the creation of backlog items and the delegation of implementation tasks.

Sentry MCP Server

I use Sentry for error tracking, so the Sentry MCP is a natural addition. It allows me to point Claude at an exception for triaging or fixing. While I have Sentry connected to Linear for automatic issue creation, the MCP integration adds another layer of context when investigating errors. If you want to see this workflow in action, check out my video on Debugging Production Issues with AI.

GitHub CLI

This one is critical. If you’ve read the Claude Code Best Practices you’ve likely seen the recommendation to install the GitHub CLI (gh). If you haven’t read that guide, I highly recommend starting there.

Claude Code excels at using the GitHub CLI for tasks like:

1. Opening pull requests
2. Investigating GitHub issues
3. Debugging GitHub Action runs
4. Reviewing PR feedback
5. Performing code review on others’ pull requests

Memory MCP Server

The Memory MCP Server provides Claude with persistent memory across conversations. In my workflow, I use it to store implementation plans so Claude can track progress and maintain context throughout a feature’s development. When Claude creates a plan for a Linear issue, it saves it to the memory graph. This becomes especially useful when work spans multiple sessions.

With these tools in place, let’s look at another core part of my workflow.

Obsidian Notes

I’ve been using Obsidian for notes for over a year, but it never occurred to me to connect it to Claude Code until I heard the Every podcast episode with Noah Brier: How to Use Claude Code as a Second Brain. This significantly changed how I provide context to my development work.

Why is this connection so important? When I’m working on a project, I’m taking notes. At a project kick-off I’m capturing potential solutions, key pieces of code, and product knowledge. These notes go into my vault under paths like 01-Projects/DHF Extraction/2025-11-01-Pairing Session.md. Meeting transcripts end up in the same project folder.

When it’s time to implement, I put Claude in plan mode and instruct it to “Review my notes in 01-Projects/DHF Extraction and help me implement X.” Claude can now gather all the context I’ve assembled to inform its implementation plan.

If you want to learn more about how I process meeting notes in Obsidian, check out my Process Meeting Transcript Skill on GitHub.

To make the most of this, use the /add-dir command to add your Obsidian vault path. This allows Claude Code to reference files in your vault without permission issues.

Putting It All Together

With MCP servers handling project management, error tracking, and memory, plus Obsidian providing my accumulated notes and research, I have all the pieces needed for a comprehensive workflow. All of these tools come together in a Claude Agent Skill that takes a Linear issue by ID and implements a solution. Let me break down this skill.

# Overview

This skill provides a comprehensive workflow for implementing Linear issues with professional software engineering practices. It automates the entire development lifecycle from issue analysis through PR creation, ensuring quality through test-driven development, parallel code reviews, and systematic validation.

## When to Use This Skill

Use this skill when:
- User provides a Linear issue ID (format: `TRA-9`, `DEV-123`, etc.)
- User requests implementation of a Linear issue
- User wants a structured TDD approach with code review
- User needs automated workflow from issue to PR

Examples:
- "Implement TRA-142"
- "Help me build the feature in DEV-89"
- "Work on Linear issue ABC-456"

This sets the stage for what the skill does and when to invoke it. Now let’s look at the core workflow.

# Core Workflow

The skill follows a 14-step process:

1. **Fetch Linear Issue** - Retrieve complete issue details via Linear MCP
2. **Gather Additional Context** - Search Obsidian, Sentry, and GitHub for related information
3. **Move to In Progress** - Update issue status to indicate active work
4. **Create Feature Branch** - Use Linear's suggested git branch naming
5. **Analyze & Plan** - Break down requirements and create implementation plan
6. **Save to Memory** - Store plan in memory graph for tracking
7. **Review Plan** - Present plan for user confirmation
8. **TDD Implementation** - Invoke `tdd-workflow` skill for test-driven development
9. **Parallel Code Reviews** - Invoke `parallel-code-review` skill for comprehensive analysis
10. **Address Feedback** - Invoke `code-review-implementer` skill to systematically fix issues
11. **Validation** - Ensure all tests and linters pass
12. **Logical Commits** - Create meaningful commit history
13. **Create PR** - Generate comprehensive pull request with Linear linking
14. **Final Verification** - Confirm CI/CD pipeline and Linear integration

There’s a lot happening here, but the goal is straightforward: build as much context as possible before implementation begins. The workflow pulls in details from the Linear issue, related Obsidian notes, Sentry exceptions if relevant, and any linked GitHub discussions. For example, a Linear issue might have been extracted from a previous pull request discussion as a follow-up task—pulling that context in gives Claude a much better starting point.

One thing worth highlighting: step 7 (Review Plan) is a key part of this workflow. After gathering context and creating a plan, Claude presents it and waits for my approval before writing any code. This human-in-the-loop checkpoint prevents runaway implementations and gives me a chance to course-correct before significant work begins.

You’ll notice a few other skills referenced in the workflow. These are also available in the claude-code-workflows repo:

tdd-workflow skill A skill that outlines a test-driven development workflow following an outside-in testing approach.

parallel-code-review This workflow spins off two Claude sub-agents to perform code review in parallel. One focuses on Rails and object-oriented best practices while the other performs security analysis.

code-review-implementer A skill that ranks code review feedback by priority and systematically addresses it. High priority feedback is always addressed. Medium and low priority items are presented for my decision before implementation.

Getting Started

If you want to try this workflow yourself, here’s how to get started:

1. Install the MCP servers - Set up Linear, Sentry (if you use it), and Memory MCP servers in your Claude Code configuration.

2. Copy the skills - Clone or copy the skills from my claude-code-workflows repo into your project’s .claude/skills/ directory. You’ll need linear-implement and its dependencies (tdd-workflow, parallel-code-review, code-review-implementer).

3. Customize for your stack - My skills are tailored to Rails projects with specific conventions (POODR principles, Result pattern, RSpec). If you’re using Django, Node, Go, or another stack, you’ll want to adapt the code review criteria and testing workflows to match your conventions.

4. Connect your notes - Use /add-dir to add your Obsidian vault (or wherever you keep project notes) so Claude can reference them.

5. Try it out - Once everything is set up, just type “Implement TRA-142” (substituting your issue ID) and the workflow kicks off automatically.

Claude Code auto-discovers skills in the .claude/skills/ directory, so there’s no additional configuration needed beyond placing the files.

Conclusion

Getting value from agentic development tools requires building the right habits. By investing time upfront in breaking down problems, maintaining good notes, and connecting your tools together, you can create workflows that dramatically improve your productivity.

The key insight is that context matters. The more relevant information you can surface for the LLM, the better its output will be. This is true whether you’re using Claude Code, Cursor, or any other AI-assisted development tool.

If you’re interested in the full skill, you can find it in my claude-code-workflows repo on GitHub.

Further Reading

• Getting Started with Claude Code - Video walkthrough for those new to Claude Code
• Claude Code: Best Practices for agentic coding
• How to Use Claude Code as a Second Brain
• Forward Deployed, Episode 2: Claude Code Skills and the Progressive Disclosure Problem
• Most devs don’t understand how context windows work

If you’re looking to build a workflow like this for your team, I offer coaching and workshops on Claude Code. See how I can help.

I found some existing YNAB MCPs, but most were inactive with limited features. This seemed like a good opportunity to learn MCP design from scratch. What followed was a deep dive into context efficiency that changed how I think about building AI tools.

Understanding Model Context Protocols (MCPs)

The Model Context Protocol (MCP) is a standardized way to extend language models with external capabilities. Unlike traditional APIs where you write code to call endpoints, MCP servers allow AI models to discover and use tools autonomously. The protocol defines how models can:

• Call tools - Execute functions that interact with external systems
• Read resources - Access files, databases, or other data sources
• Receive prompts - Get specialized instructions for specific tasks

When you build an MCP server, you’re essentially creating a set of capabilities that any MCP-compatible AI assistant (like Claude) can use. The model sees your tool descriptions, understands what they do, and calls them as needed to fulfill user requests.

Understanding Context Windows

Before we dive into how to make our MCPs more efficient, it’s important to understand what we’re trying to optimize. When working with LLMs, the context window is the amount of content that the model can “pay attention” to at one time. Each model has a limit to the size of its context window. For example, Claude Sonnet 4.5’s context window is about 200,000 tokens.

What is a Token?

When you send text to an LLM, it doesn’t process words one at a time. Instead, text is broken into tokens—the fundamental units that language models read and generate. A token typically represents 3-4 characters, or roughly 0.75 words in English.

For API responses and JSON data (which is what MCPs work with), tokenization looks like this:

{"name": "Checking"}           // ~7 tokens
"transfer_payee_id"            // ~5 tokens
{"balance": 125000}            // ~6 tokens

The tokenizer breaks JSON into chunks: brackets, keys, values, and punctuation all consume tokens. Every field name has a cost. Field names like "debt_escrow_amounts" and "direct_import_in_error" cost ~4-6 tokens each. When you return an API response with 18 fields per object, you’re paying the token cost for every field name, every time—even when the model doesn’t need them.

Why Token Efficiency Matters

Given the limited size of the context window, it’s critical to consider how much you’re placing inside it. Models work best when they have good context, but there’s a balance to strike:

• Context limits are hard boundaries: Claude Sonnet 4.5’s 200k token limit sounds generous until you realize a naive MCP returning a year of transactions can consume 746,800 tokens—nearly 4x the entire context window. Your tool call would fail before the model could even process it.

• Real sessions are already crowded: In typical Claude Code sessions, MCP tool definitions, system prompts, and memory can consume 50-60% of the context window before you’ve had a single conversation. Every inefficient tool response eats into precious space needed for reasoning and multi-turn conversations.

• Noise degrades performance: Providing superfluous data doesn’t just waste tokens—it forces the model to parse irrelevant fields, increasing the chance of errors or confusion. A focused 262-token summary outperforms a noisy 4,890-token dump of raw data.

The goal isn’t to minimize tokens at all costs. It’s to give the model exactly what it needs, nothing more, nothing less. Let’s look at how this plays out in practice.

The Naive Approach: Direct API Wrapping

When I started building the YNAB MCP, I didn’t yet appreciate how much token efficiency would matter. I started with what seemed obvious: create a thin wrapper around the existing YNAB Python SDK. Each MCP tool would correspond to one API endpoint, passing through the full response. This is a common pattern I’ve seen in many MCP implementations.

# Naive approach: Just wrap the SDK
@mcp.tool()
async def get_budget(budget_id: str) -> str:
    response = ynab_client.budgets.get_budget(budget_id)
    return json.dumps(response.data.budget)  # Return everything

This approach works, technically. The model gets access to the data. But there’s a critical problem: API responses are designed for applications, not for AI context windows.

Traditional applications can process, filter, and cache data efficiently, so APIs return comprehensive data structures optimized for completeness, not token efficiency. A single endpoint might return thousands of fields because the API designers don’t know which specific fields your application needs.

AI models work differently. Every byte consumes precious context window space—space you could use for reasoning, conversation history, or additional tool calls. When you blindly pass through full API responses, you’re asking the model to pay the “context tax” for data it might not even need. Worse, the model has to analyze and determine which parts of that data are actually relevant—a cognitive load that can lead to errors or missed information.

To put this in perspective: tool results compete with everything else for context space. In a real Claude Code session (visible via /context), I saw the context window at 118k/200k tokens (59%)—before I’d even started a conversation. MCP tool definitions alone consumed 47.9k tokens (24%), system tools used 17.3k tokens (9%), custom agents took 2.4k tokens, and memory files added another 2.3k tokens. That’s 59% of the context window used just by the environment.

A naive MCP that returns 30k tokens for a budget overview would push that to 74% in a single tool call—leaving just 52k tokens for the actual conversation, reasoning, and additional tool calls. Every inefficient tool response eats into the space you need for multi-turn conversations.

This changed how I approached the design: MCPs need to be context-aware intermediaries, not transparent proxies. The question shifted from “How do I expose this API to the model?” to “What does the model actually need to help the user?”

Three Design Principles for Context-Efficient MCPs

One of the first things I wanted to do was check my budget overview - see my accounts, categories, and how I’m tracking for the current month. A straightforward use case that any budgeting tool should support.

My initial thought was to create tools that directly wrapped the YNAB API endpoints. Let’s take the accounts endpoint as an example. Here’s what the API returns:

{
  "data": {
    "accounts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Checking Account",
        "type": "checking",
        "on_budget": true,
        "closed": false,
        "note": "Primary checking",
        "balance": 125000,
        "cleared_balance": 120000,
        "uncleared_balance": 5000,
        "transfer_payee_id": "...",
        "direct_import_linked": true,
        "direct_import_in_error": false,
        "last_reconciled_at": "2025-11-05T18:27:20.140Z",
        "debt_original_balance": 0,
        "debt_interest_rates": {},
        "debt_minimum_payments": {},
        "debt_escrow_amounts": {},
        "deleted": false
      }
      // ... 46 more accounts
    ]
  }
}

For my 47 accounts, this API response contains 18 fields per account. Many of these fields are irrelevant for typical budget questions:

• Debt interest rates and minimum payments (only relevant for debt accounts)
• Direct import status (internal system state)
• Cleared vs uncleared balance breakdown (too granular for overview)
• Transfer payee IDs (internal references)
• Last reconciliation date (accounting detail)

When you’re answering budget questions, these internal bookkeeping details just create noise.

A naive wrapper would return all 18 fields × 47 accounts = 9,960 tokens.

But here’s what I actually need to answer questions like “What’s my checking account balance?” or “How much do I have across all accounts?”:

• Account name
• Account type
• Balance
• Whether it’s on-budget
• Whether it’s closed

That’s it. Just 6 fields. Here’s the filtered implementation:

For accounts (47 accounts):

# src/ynab_mcp/ynab_client.py
async def get_accounts(self, budget_id: str) -> list[dict[str, Any]]:
    """Get all accounts for a budget."""
    response = self.client.accounts.get_accounts(budget_id)
    accounts = []

    for account in response.data.accounts:
        # Skip deleted accounts entirely
        if account.deleted:
            continue

        # Return only the fields the model actually needs
        accounts.append({
            "id": account.id,
            "name": account.name,
            "type": account.type,
            "on_budget": account.on_budget,
            "closed": account.closed,
            "balance": account.balance / 1000 if account.balance else 0,
        })

    return accounts

Filtered approach (6 essential fields): 3,451 tokens for 47 accounts

Reduction: 65.4% by removing 12 unnecessary fields that the model doesn’t need for typical budget questions.

The Full Budget Overview

Of course, checking accounts is just one part of viewing your budget. A complete budget overview requires three tool calls:

Naive approach (no filtering):

• Accounts (all fields): 9,960 tokens
• Categories (all, including hidden): 12,445 tokens
• Monthly summary (estimated): ~8,000 tokens
• Total: ~30,405 tokens

Context-efficient approach:

• Accounts (filtered): 3,451 tokens
• Categories (visible only): 8,620 tokens
• Monthly budget summary: 6,808 tokens
• Total: ~18,879 tokens

Workflow reduction: 38% fewer tokens for the same functionality - a complete picture of my budget for the current month. This leaves plenty of room in Claude’s context window for conversation history, reasoning, and additional tool calls.

But it’s not just about saving tokens. By filtering out unnecessary data, I’m also improving model accuracy. When Claude doesn’t see fields like debt_escrow_amounts or direct_import_in_error, it can’t get confused by them or incorrectly incorporate them into calculations. The model focuses on exactly what matters: account names, balances, and budget status.

The key insight: the model doesn’t need to see all the data to work with it effectively. In fact, it works better with less data. By doing the filtering in the tool layer, I kept the context window lean while maintaining full functionality and improving reliability.

The filtering techniques I’d learned from accounts and categories immediately paid off when I tackled the next challenge: helping Claude categorize uncategorized transactions.

Categorizing Transactions

One of the workflows I wanted help with was taking uncategorized transactions and suggesting categories for them. This would help me ensure that my budget was accurate and up-to-date. To do this I created a tool that would fetch all uncategorized transactions from YNAB and get a list of the categories available in the budget.

On the first pass I noticed something unusual. Claude was recommending categories that were hidden in my budget - old categories I no longer used but hadn’t deleted. I quickly realized that the YNAB REST API doesn’t provide a way to exclude hidden categories in the API call itself. That meant I had two options:

1. Include instructions in my tool description telling Claude to ignore hidden categories
2. Filter them out in the tool code before returning data to Claude

I chose option 2. Here’s why: every instruction you add to a tool description consumes context window. More importantly, it puts the burden of filtering on the model. This means we’re knowingly giving the model more data than it needs, forcing it to do more work and potentially allowing the model to make mistakes.

It’s worth emphasizing: tool descriptions themselves consume context tokens. In my Claude Code session, MCP tool definitions consumed 47.9k tokens (24% of the context window) before any tools were even called. Every line of documentation, every parameter description, every usage instruction adds up. This creates a tension: you want clear, helpful descriptions, but verbose documentation eats into the space available for actual tool results and conversation.

The solution isn’t to write minimal descriptions—clarity matters. Instead, keep descriptions focused on what the tool does and its parameters, and handle behavior rules (like “ignore hidden items”) in your implementation code rather than in lengthy instructions. Instead, I implemented filtering at the tool layer:

def _filter_categories(
    self, categories: list[dict[str, Any]], include_hidden: bool = False
) -> list[dict[str, Any]]:
    """Filter categories to exclude hidden/deleted ones by default."""
    filtered = []
    for category in categories:
        # Always skip deleted categories
        if category.get("deleted"):
            continue
        # Skip hidden categories unless explicitly included
        if not include_hidden and category.get("hidden"):
            continue
        filtered.append(category)
    return filtered

Then I exposed this as a parameter in the tool:

@mcp.tool()
async def get_categories(budget_id: str, include_hidden: bool = False) -> str:
    """Get all categories for a budget.

    Args:
        budget_id: The ID of the budget (use 'last-used' for default budget)
        include_hidden: Include hidden categories and groups (default: False)

    Returns:
        JSON string with category groups and categories
    """

This approach gave me the best of both worlds: by default, Claude only sees active categories, but I can still access hidden categories when needed (like when I wanted to identify old balances that needed cleanup). This saved 30.7% of tokens per category list request (from 12,445 to 8,620 tokens by filtering out 69 hidden categories) while improving accuracy.

Design Principle #1: Filter at the Source

Do data filtering in your tool code rather than relying on prompt instructions. This saves tokens and prevents errors.

Historical Spending Analysis

Next, I wanted to be able to ask questions about my historical spending. Questions like “How much did I spend on groceries last month?” or “What categories am I overspending in?” would be really useful.

My first instinct was to create a tool that fetched all transactions for a date range and let Claude analyze them. But I quickly realized this approach had serious problems.

To illustrate, let me show you the real numbers for my 2024 transactions:

• Total transactions in 2024: 3,456
• Fields per transaction: 14 (id, date, amount, memo, account_name, payee_name, category_name, cleared, approved, etc.)
• Average per transaction: ~216 tokens

Now extrapolate this to common queries:

• 1 month of transactions (~284 txns): ~61,368 tokens
• 3 months of transactions (~852 txns): ~184,106 tokens
• 6 months of transactions (~1,704 txns): ~368,213 tokens
• 1 year of transactions (3,456 txns): ~746,800 tokens

The problems with this approach:

1. Token usage: A full year query would consume 746,800 tokens - that’s 3.7x larger than Claude Sonnet 4.5’s entire 200k context window! You literally couldn’t fit a year of transactions in a single request.
2. Speed: Transferring and parsing thousands of transaction objects is slow
3. Analysis burden: Claude would need to group, sum, and calculate averages on raw data
4. Wasted context: Most of those 14 fields per transaction aren’t relevant to “how much did I spend?”

Even a modest 3-month query would consume 184k tokens - using 92% of the available context window just for raw transaction data. This leaves almost no room for Claude to maintain conversation history, reason about the results, or make additional tool calls to answer follow-up questions.

Instead, I realized these calculations could easily be handled in the tool layer. Here’s what the aggregation logic looks like:

async def get_category_spending_summary(
    self,
    budget_id: str,
    category_id: str,
    since_date: str,
    until_date: str,
    include_graph: bool = True,
) -> dict[str, Any]:
    """Get spending summary for a category over a date range."""

    # Fetch transactions from API
    result = await self._make_request_with_retry("get", url, params=params)
    txn_data = result["data"]["transactions"]

    # Aggregate in tool layer
    total_spent = 0
    transaction_count = 0
    monthly_totals = {}

    for txn in txn_data:
        # Filter by category and date range
        if txn.get("category_id") != category_id:
            continue
        if txn["date"] > until_date:
            continue

        # YNAB stores amounts in milliunits (e.g., $125.00 = 125000)
        amount = txn["amount"] / 1000 if txn.get("amount") else 0
        total_spent += amount
        transaction_count += 1

        # Build monthly breakdown
        month_key = txn["date"][:7]  # YYYY-MM
        if month_key not in monthly_totals:
            monthly_totals[month_key] = 0
        monthly_totals[month_key] += amount

    # Calculate average per month
    num_months = len(monthly_totals) if monthly_totals else 1
    average_per_month = total_spent / num_months if num_months > 0 else 0

    # Return only the summary
    return {
        "category_id": category_id,
        "date_range": {"start": since_date, "end": until_date},
        "total_spent": total_spent,
        "transaction_count": transaction_count,
        "average_per_month": average_per_month,
        "monthly_breakdown": [
            {"month": month, "spent": amount}
            for month, amount in sorted(monthly_totals.items())
        ],
    }

The impact was dramatic. Let me show you a real example from my implementation:

Scenario: Analyze 6 months of spending for a single category (22 transactions)

• Before (returning raw transactions): 4,890 tokens
• After (pre-aggregated summary): 262 tokens
• Reduction: 94.6%

The aggregated response includes:

• Total spent
• Average per month
• Transaction count
• Monthly breakdown (array of {month, amount} objects)

That’s everything Claude needs to answer questions like “Am I spending more on groceries this year than last year?” without having to receive, parse, and aggregate dozens of individual transaction records.

Design Principle #2: Pre-Aggregate Data

Pre-calculate aggregations, summaries, and statistics in your tool code. Return insights, not raw data. This keeps your context window lean while still giving the model everything it needs to help users.

While filtering and aggregation solved the token efficiency problem, I ran into a different challenge: the API itself had limitations.

Building Tools for Unsupported Actions

While working on the workflow to have Claude help me categorize transactions, I realized I needed a way to split a transaction across multiple categories. For example, a Costco purchase might include $150 of groceries, $50 of household items, and $30 of gas.

Unfortunately, the YNAB API does not provide a way to convert an existing transaction into a split transaction. The API only allows creating NEW transactions with splits. This was a real limitation - but it presented an opportunity to think creatively about tool design.

Instead of telling users “sorry, the API doesn’t support this,” I created a tool that works within the API’s constraints:

@mcp.tool()
async def prepare_split_for_matching(
    budget_id: str,
    transaction_id: str,
    subtransactions: str,
) -> str:
    """Prepare a split transaction to match with an existing imported transaction.

    This tool fetches an existing transaction's details and creates a new UNAPPROVED split
    transaction with the same date, amount, account, and payee. You can then manually match
    them together in the YNAB web or mobile UI.

    Workflow:
        1. This tool fetches the existing transaction details
        2. Creates a new unapproved split transaction with those details
        3. You manually match them in the YNAB UI
        4. YNAB merges them into one split transaction

    Note:
        - The new split is created as UNAPPROVED for manual matching
        - The sum of subtransaction amounts should equal the original transaction amount
    """

The implementation:

async def prepare_split_for_matching(
    self,
    budget_id: str,
    transaction_id: str,
    subtransactions: list[dict[str, Any]],
) -> dict[str, Any]:
    # Fetch the original transaction details
    original = await self.get_transaction(budget_id, transaction_id)

    # Create a new split transaction with the same details but unapproved
    new_split = await self.create_split_transaction(
        budget_id=budget_id,
        account_id=original["account_id"],
        date=original["date"],
        amount=original["amount"],
        subtransactions=subtransactions,
        payee_name=original.get("payee_name"),
        memo=original.get("memo"),
        cleared=original.get("cleared", "uncleared"),
        approved=False,  # Key: create as unapproved for matching
    )

    return {
        "original_transaction": original,
        "new_split_transaction": new_split,
        "instructions": (
            "A new unapproved split transaction has been created. "
            "Go to YNAB and manually match these two transactions together. "
            "Look for the match indicator in the YNAB UI."
        ),
    }

This solution works because YNAB has a built-in “matching” feature where it can merge a manually-entered transaction with an imported one. By creating the split as unapproved, YNAB’s UI will detect the duplicate and offer to match them. When you accept the match, the imported transaction becomes a proper split transaction.

Is this ideal? No - I’d prefer a direct API endpoint. But it’s a pragmatic solution that works within the constraints of the underlying platform while still providing value to the user.

Design Principle #3: Work Within API Constraints

When an API doesn’t support something directly, look for workflows that combine available operations to achieve the desired outcome.

Real-World Token Reduction Results

Here’s a summary of the optimizations applied across the YNAB MCP, with real measured token counts:

When to Apply Each Technique

Field Filtering (accounts, categories)

• Use when: API returns many fields, but only subset is needed for common queries
• Savings: Moderate (30-65%)
• Complexity: Low - simple field selection
• Example: Remove debt details from non-debt accounts, skip internal IDs like transfer_payee_id, drop reconciliation timestamps

  # Instead of returning all 18 fields, return only what matters
  return {
      "id": account.id,
      "name": account.name,
      "balance": account.balance / 1000,
      "on_budget": account.on_budget
  }
  

Default Filtering with Parameters (hidden categories)

• Use when: Some data is rarely needed but occasionally useful
• Savings: Moderate (30-40%)
• Complexity: Low - add optional boolean parameter
• Example: Hide deleted/archived items by default, expose via include_deleted flag

Pre-aggregation (spending analysis)

• Use when: Model would need to compute summaries from raw data
• Savings: High (90-99%)
• Complexity: Medium - requires aggregation logic
• Example: Return monthly totals instead of individual transactions

Creative Workarounds (split transactions)

• Use when: API doesn’t support desired operation directly
• Savings: Enables new functionality (not about tokens)
• Complexity: High - requires understanding API constraints
• Example: Multi-step workflows that achieve goals indirectly

How to Measure Your Own MCP

You might be wondering how I got these specific numbers. Here’s my methodology—and how you can apply it to your own MCPs.

All the numbers in this post came from real measurements. Here’s how I validated the optimizations, and how you can do the same for your MCP:

1. Set Up Token Counting

Install tiktoken, OpenAI’s tokenizer library (Claude uses a similar tokenization scheme):

pip install tiktoken

Create a helper function to count tokens:

import tiktoken

def count_tokens(text: str) -> int:
    """Count tokens using tiktoken's cl100k_base encoding."""
    encoding = tiktoken.get_encoding("cl100k_base")
    return len(encoding.encode(text))

2. Measure API Responses

Create a script that fetches data both ways and compares:

import json

# Get raw API response
raw_response = api.get_accounts(budget_id)
raw_json = json.dumps(raw_response, indent=2)
raw_tokens = count_tokens(raw_json)

# Get your filtered response
filtered_response = your_mcp_tool.get_accounts(budget_id)
filtered_json = json.dumps(filtered_response, indent=2)
filtered_tokens = count_tokens(filtered_json)

# Compare
reduction = ((raw_tokens - filtered_tokens) / raw_tokens) * 100
print(f"Raw: {raw_tokens:,} tokens")
print(f"Filtered: {filtered_tokens:,} tokens")
print(f"Reduction: {reduction:.1f}%")

3. Test Real Workflows

Don’t just measure individual tools - measure complete workflows users will perform:

# Simulate a budget overview workflow
accounts = your_mcp.get_accounts(budget_id)
categories = your_mcp.get_categories(budget_id, include_hidden=False)
summary = your_mcp.get_budget_summary(budget_id, current_month)

total_tokens = (
    count_tokens(json.dumps(accounts)) +
    count_tokens(json.dumps(categories)) +
    count_tokens(json.dumps(summary))
)

print(f"Budget overview workflow: {total_tokens:,} tokens")

This revealed that my budget overview workflow uses ~19k tokens - well within Claude’s 200k context window with room to spare.

4. Watch for Runtime Warnings

Claude Code will warn you when tool responses exceed ~10k tokens. If you see these warnings frequently, it’s a signal to investigate:

⚠️ Large MCP response (~12.5k tokens), this can fill up context quickly.

These warnings helped me identify which tools needed optimization.

5. Validate Correctness

Token reduction means nothing if your tools return incorrect data. Always verify:

• Does the filtered data answer the user’s questions?
• Are calculations accurate? (spot-check aggregations against raw data)
• Does pagination work correctly? (ensure you’re not computing on partial datasets)

The goal isn’t to minimize tokens at all costs - it’s to return exactly what the model needs, nothing more, nothing less.

Limitations and Trade-offs

This context-efficient approach works well for YNAB, but it’s not without limitations. Before applying these patterns to your own MCP, consider these trade-offs:

Pre-aggregation assumes query patterns. If users ask questions that need raw transaction details (like “show me the memo for my largest grocery purchase”), the aggregated data won’t help. You’ll need additional tools that return raw data for those cases.

Filtering loses flexibility. By removing fields, you can’t answer questions that need those fields without making additional API calls. The key is knowing your use cases. For budget analysis and categorization, these trade-offs are worth it. For transaction-level forensics, you might need different tools.

Caching complexity. Pre-computed aggregations need invalidation strategies when data changes. If your underlying data updates frequently, you’ll need to think carefully about cache freshness and when to recompute.

Development overhead. Writing aggregation logic and filtering code is more work than simple pass-through wrappers. You’re trading implementation time for runtime efficiency. For frequently-used tools, this is usually worth it.

The goal isn’t to optimize every tool to the extreme. It’s to identify the high-impact workflows—the ones users will perform repeatedly—and optimize those intelligently.

Key Takeaways

• Context is expensive: In real Claude Code sessions, MCP tool definitions can consume 24% of the 200k context window before any tools are called
• Measure everything: Use tiktoken to count tokens on API responses before and after optimization
• Filter proactively: Removing 12 unnecessary fields from 47 accounts reduced tokens by 65.4%
• Aggregate strategically: Pre-computing spending summaries reduced a 6-month query by 94.6%
• Design for the model: Ask “What does the model need?” not “What does the API provide?”
• Default to minimal data: Return only what’s necessary by default, with optional parameters for edge cases
• Validate with real workflows: Test complete user flows, not just individual tools, to understand cumulative token impact

Conclusion

Building a context-efficient MCP requires a mindset shift: design for what the model needs, not just what the API provides. The three principles I learned—filter at the source, compute in tools, and work within constraints creatively—apply to any MCP wrapping an external API.

Through careful design, the YNAB MCP achieves dramatic efficiency:

• Budget overview: 38% reduction (30k → 19k tokens)
• Spending analysis: 94.6% reduction (4.9k → 262 tokens)
• Category filtering: 30.7% reduction (12.4k → 8.6k tokens)

These aren’t theoretical—they’re real measurements from actual usage. Context is expensive, and every token matters when you’re building tools for multi-turn conversations.

If you’re building an MCP, start by asking: “What does the model actually need to answer the user’s question?” Not “What does the API return?” That mindset shift makes all the difference.

Further Reading

If you want to dive deeper into MCP development and context optimization:

• Model Context Protocol Specification - Official MCP spec and documentation
• Code Execution with MCP - Anthropic’s engineering blog on building with MCP
• Most devs don’t understand how context windows work - Deep dive into context window fundamentals and practical management strategies
• YNAB API Documentation - The API this MCP wraps
• Anthropic’s Prompt Engineering Guide - Understanding context windows and token efficiency

The full YNAB MCP implementation is available at github.com/dgalarza/ynab-mcp-dgalarza if you want to dive deeper into the code. I’d love to hear about the context optimization techniques you’ve discovered in your own MCP projects.

Building MCP servers or designing Claude Code workflows for your team? I help engineers get this right from the start. Learn more.