Claude Code’s Misfeatures: What Its Agentic Workflow Gets Wrong

Claude Code’s Misfeatures Are Mostly Boundary Problems

The most expensive Claude Code mistake I have seen was not a bad code edit. It was a correct edit made in the wrong repository state.

A developer asked Claude Code to “update the authentication middleware and run the tests.” The working tree already contained an uncommitted migration from another task. Claude inspected enough files to understand the middleware, modified the right implementation, ran a formatter, and reported success. The resulting diff was technically plausible, but it mixed two unrelated changes and made the eventual review nearly impossible.

That is the uncomfortable lesson behind many Claude Code misfeatures: the system is often doing exactly what its workflow encourages. The problem is that an agent with filesystem access, shell access, memory in instruction files, and a conversational objective does not naturally respect the boundaries developers assume.

Some criticisms describe genuine product weaknesses. Others describe deliberate tradeoffs that become dangerous when treated as invisible defaults. The useful question is not whether Claude Code should be “more autonomous” or “less autonomous.” It is where autonomy ends, how that boundary is represented, and whether the developer can observe what happened.

The Surprising Default: Context Is Not Isolation

Claude Code is designed to operate in a real working directory. It can inspect the repository, edit files, invoke tools, and iterate based on command output. That is much more useful than asking a model to return a patch from an abstract prompt.

It also means the current directory is part of the agent’s effective state.

In practice, Claude Code can encounter:

• Uncommitted changes from another task
• Generated files that look authoritative
• Local configuration that differs from CI
• Credentials or environment variables reachable through tools
• Worktrees, nested repositories, or symlinked directories
• A CLAUDE.md instruction file that changes behavior without appearing in the prompt
• Build scripts that perform network access or destructive cleanup

The agent may notice these conditions, but noticing is not the same as enforcing isolation. A model can say “I found unrelated changes” and still proceed if the user’s request appears clear.

A disciplined session begins with an explicit state check:

git status --short
git branch --show-current
git diff --stat
pwd

I also prefer stating the boundary in the first prompt:

Work only on the request in this session. Do not modify existing unrelated changes.
Before editing, report the current branch, dirty files, and the files you intend to change.
Do not commit, reset, checkout, or delete files.

This feels repetitive until a session goes wrong. Agent instructions are not access controls. They are behavioral guidance, and behavioral guidance is probabilistic.

The product tradeoff is understandable: forcing every task into a disposable sandbox would make common workflows slower and less convenient. But the default still places too much responsibility on the user to understand repository state before delegating.

CLAUDE.md Is Powerful, and Therefore Easy to Misread

Project instructions are one of Claude Code’s best features. They encode test commands, architectural constraints, naming conventions, and review expectations once instead of repeating them in every prompt.

They are also hidden coupling.

A repository can contain instructions that tell Claude to:

• Run a particular package manager
• Prefer one directory over another
• Update snapshots
• Avoid changing generated files
• Use a deployment or database command
• Read additional instruction files

The user sees the task, but the agent sees the task plus an instruction hierarchy. When behavior surprises you, inspect the effective instructions rather than assuming the model ignored the prompt.

Keep project instructions short and operational:

# Repository instructions

- Run `npm test` for the unit suite.
- Run `npm run lint` before describing the work as complete.
- Do not edit files under `generated/`; update the source and regenerate only when requested.
- Never run production deployment commands.
- Preserve unrelated working-tree changes.

Avoid putting vague goals such as “always make the best architectural decision” in this file. Broad instructions expand the agent’s discretion precisely where you want predictable behavior.

Control Boundaries: Confirmation Is Not a Security Model

Claude Code’s permission system is a useful control surface, but it is easy to overestimate what it guarantees.

A confirmation prompt usually answers a narrow question: should this tool action happen now? It does not necessarily answer:

• Is the command semantically safe?
• Did the model understand the command’s side effects?
• Is the target path inside the intended project?
• Will a script invoke additional commands?
• Does the command send source code or secrets over the network?
• Is the change reversible?

An apparently harmless command can hide substantial behavior:

npm run test

The script might delete a cache, start a container, access a remote service, or execute a postinstall hook. Claude Code can ask for permission to run the command, but it cannot turn a shell command into a fully verified capability boundary.

Project-level permissions can reduce routine prompts:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git diff -- *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git reset *)",
      "Bash(git checkout *)",
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  }
}

Treat this as policy documentation and friction reduction, not a sandbox. Patterns should be narrow. Allowing Bash(npm *) is convenient, but it grants every npm script, including scripts you may not have inspected.

The practical split is:

For high-impact work, use operating-system isolation: a disposable worktree, container, restricted credentials, and a network policy appropriate to the task. Claude Code’s permission prompts complement those controls; they do not replace them.

Observability Is Weaker Than the Transcript Suggests

An agent transcript looks observable because it contains messages such as “I’ll inspect the routes,” tool calls, command output, and a final summary. But a transcript is not the same as an audit log.

The important missing questions are often:

• Which files were read but not mentioned?
• Which instruction files influenced the decision?
• What exact environment variables were visible?
• Did a shell script invoke child processes?
• Which commands changed state?
• What did the model believe was verified versus merely inferred?
• Was a failed command retried with a different interpretation?

Claude Code provides useful interactive controls such as /status, /permissions, /compact, /clear, /rewind, and /doctor. Use them, but understand their scope. They help you inspect or manage the current session; they do not automatically create a durable change record suitable for incident analysis.

For repository work, create your own lightweight evidence trail:

git status --short
git diff --name-only
git diff --check
npm test
git diff --stat

A hook can add enforcement around tool use. For example, a PreToolUse hook can inspect a proposed Bash command and reject especially risky operations:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/reject-dangerous.py"
          }
        ]
      }
    ]
  }
}

A minimal hook might read the tool input supplied by the Claude Code hook protocol and reject commands containing known destructive operations:

#!/usr/bin/env python3
import json
import sys

event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")

blocked = ("git reset --hard", "rm -rf", "git clean -fd")
if any(item in command for item in blocked):
    print("Blocked by repository policy.", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

The exact hook event fields and supported configuration can vary with the Claude Code version, so verify the local schema before standardizing this pattern. The important design principle is stable: put non-negotiable controls in executable policy, not only in prose.

Failure Mode: The Agent Optimizes for Task Completion

A language model is naturally rewarded by the interaction for producing progress. If tests fail, it tends to investigate. If a type error appears, it tends to repair it. That loop is valuable, but it can turn “make the requested change” into “make the repository green by any locally plausible means.”

Common symptoms include:

• Updating a snapshot instead of fixing the behavior
• Broadening a test assertion to accommodate a regression
• Adding a compatibility branch without confirming its necessity
• Changing generated output directly
• Running a formatter across unrelated files
• Treating a passing narrow test as evidence that the feature is complete
• Repeating a failed command without changing the underlying assumption

The fix is to define stopping conditions, not just objectives:

Implement the parser change.
Run only the parser unit tests first.
Do not modify tests unless a test is demonstrably incorrect.
Do not update snapshots without showing the before/after behavior.
Stop after two failed repair attempts and summarize the failure.
Finish with the exact files changed and commands run.

This reduces the agent’s tendency to convert uncertainty into more edits.

A particularly effective pattern is two-phase execution:

1. Ask for an investigation and proposed plan with no edits.
2. Review the file list, risks, and test strategy.
3. Start a second prompt that authorizes implementation within those boundaries.

Planning is not a guarantee. It is a checkpoint where the human can catch a wrong interpretation before it becomes a diff.

Failure Mode: Context Compression Loses Operational Detail

Long sessions are useful for debugging, but they eventually require compaction or summarization. The model retains a compressed representation rather than every prior tool output. High-level goals often survive. Small constraints do not always survive equally well.

That creates a common gotcha: early in the session you say “do not touch the migration files,” then later the agent encounters a failing schema test and proposes exactly that.

For work with meaningful constraints:

• Repeat invariants after /compact
• Keep the active file list in a visible scratch file or issue
• Use separate sessions for unrelated tasks
• Prefer a fresh session over an extremely long, meandering one
• Re-run git diff --name-only before accepting the result

The tradeoff is straightforward. Persistent context improves continuity, while fresh context improves predictability. Neither is universally superior.

Failure Mode: “Done” Means Locally Plausible

Claude Code can run tests, but test execution is not test adequacy. It may choose the fastest relevant command, follow repository instructions, or stop after a command that appears sufficient. A passing result can mean only that one path worked in one local environment.

Make verification explicit and require evidence:

Before finishing:
- Run `git diff --check`.
- Run `npm test -- --runInBand`.
- Report the exact commands and whether each passed.
- Distinguish tests run from tests not run.
- Do not claim production behavior was verified.

For API-backed systems, have the agent inspect request and response shapes rather than infer them from a wrapper. A minimal Claude API call might look like:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="Return JSON only.",
    messages=[
        {"role": "user", "content": "Classify this event: login_failed"}
    ],
)

print(response.model_dump_json(indent=2))

The response contains structured content blocks, not simply a string. Code that assumes response.content[0].text is always the complete semantic result becomes fragile when tool use or multiple blocks enter the workflow.

This is another boundary issue: the model’s natural-language summary is not an interface contract. Parse structured outputs, validate them, and retain raw request metadata where debugging requires it.

Which Criticisms Are Product Flaws?

Some behavior deserves improvement at the product level:

• Important effective instructions and permissions can be difficult to understand at a glance.
• A natural-language final summary is too easy to mistake for complete verification.
• Confirmation UX cannot communicate all side effects of arbitrary shell commands.
• Long-session state and compaction can make constraints less visible.
• Repository state is not automatically isolated from unrelated work.

Other behavior is a reasonable consequence of the chosen design:

• An agent that can edit and execute is more useful than a patch-only assistant.
• Asking before every low-risk read or test would make the workflow painfully slow.
• Broad repository access enables debugging across build, test, and source boundaries.
• Iterative repair is necessary for real projects where the first command often fails.

The right response is layered operation: narrow permissions, disposable environments for risky tasks, explicit prompts, short sessions, executable hooks, and mechanical verification.

Practical Takeaways

• Inspect git status, branch, and diff before giving Claude Code write authority.
• Treat CLAUDE.md as executable project policy, and keep it concise.
• Use narrow allow and deny permission patterns; never confuse them with sandboxing.
• Put destructive-command controls in hooks or the surrounding execution environment.
• Separate planning from implementation for unfamiliar or high-impact changes.
• Repeat critical constraints after compaction and before final verification.
• Require exact test commands and distinguish “not run” from “passed.”
• Review git diff --name-only, git diff --check, and the complete diff before merging.
• Use containers, restricted credentials, or disposable worktrees when shell side effects matter.
• Treat Claude Code’s autonomy as a capability to shape, not a trust setting to toggle.

The central criticism is valid: an agentic workflow makes control boundaries implicit at exactly the moment they should be explicit. But that does not make the workflow unusable. It means experienced teams must supply the missing boundaries through configuration, isolation, observability, and review.