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 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

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

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.

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 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 →