Heavy Chain Engineering logo
All posts

The Claudish Tax: What Four Months of Opus Prose Cost Us, and How to Sweep It Out

September 30, 2026

#AI#Software Engineering#Technical writing #documentation#llm
The Claudish Tax: What Four Months of Opus Prose Cost Us, and How to Sweep It Out

A few weeks ago, I wrote about forcing Claude Code to speak human. Last week, I wrote about ripping AI ceremony out of a codebase.

This memo is the follow-up, because the problem is far wider and more expensive than I initially realized.

Working across multiple engineering organizations, I keep hitting the same wall whenever I open a README.md, an architectural spec, or a CLAUDE.md. Sentences lack verbs. Concrete actions have mutated into abstract nouns. Thoughts trail off into comma-spliced fragments. Engineers find themselves reading single paragraphs three times without understanding what the software actually does—and when asked, the authors cannot explain it either.

Engineers call this dialect "Claudish." It is not a cosmetic quirk; it is a compounding operational liability.

Below is an analysis of how this happened, the community evidence documenting it, why it degrades agentic systems, and the exact prompt and workflow we use to sweep it out of codebases.

1. The Findings: Diagnosing the Dialect

Where It Came From

Between the releases of Claude Opus 4.8 (May 28) and Claude Opus 5 (July 24), Claude developed three distinct linguistic tics:

  1. Severe over-nominalization: Converting active processes into passive, Latinate nouns ("performs the execution of queries" instead of "executes queries").
  2. Dropped finite verbs: Stranding participial fragments without subjects or actions ("The runner, built.").
  3. Trailing negation: Ending sentences on a negative afterthought instead of stating what actually happened ("X names Y no one asked for", "X and Y, never touched").

Opus 5.5, released September 22, is about 90% better in my experience. But during that four-month window, engineering teams adopted Claude Code at a breakneck pace. Teams did not just leave this output in ephemeral chat windows. They checked it into git repositories as product requirement documents (PRDs), system roadmaps, technical specifications, automated tests, internal architecture guides, and customer documentation.

The Community Evidence

If you have noticed your repository documentation becoming dense and unnatural, you are not alone. The wider engineering and research community has spent months documenting this pattern:

  1. Academic Attention to the Dialect: The University of Waterloo published a Q&A with Professor Yuntian Deng, who built a translator for Claudish's compressed, information-dense output. He also raises the possibility that the language of AI agents will start reshaping how humans communicate with one another.
  2. Developer Fatigue and Trope Catalogs: Engineer and researcher Werner Robitza cataloged these rhetorical tells in The One Thing I Hate About Claude, calling out repetitive formulas ("It's not X, it's Y", "Honest caveat: X") and the "highly compressed half-sentences" that make AI-generated text painful to read. He credits Ethan Mollick with coining the term "Claudish."
  3. The Community "Un-Slop" Movement: On Hacker News, developers trade drop-in fixes such as Reduce Claudish and Show HN: Claude Style Patch, written specifically to strip away performative prose and restore simple English.

2. Why This Matters: The Agentic Contagion Effect

Clear writing has always been essential for human collaboration. In an AI-augmented organization, clear writing is equally critical for machine collaboration.

The damage of Claudish compounds across four layers:

[Claudish Spec in Repo]
   │
   ├──> [Human Misunderstanding]
   │
   ▼
[Ingested as Context]
   │
   ▼
[Downstream Agent Emulates Dialect]
   │
   ▼
[Degraded Code & Test Quality]
  1. Cognitive Overhead for Humans: Complex technical domains are inherently difficult. Obscuring system invariants beneath convoluted grammar forces engineers to spend mental energy decoding prose instead of reasoning about architecture.
  2. Context Contamination Across Agents: LLMs mirror the tone and syntax of the context they consume. As I observed when analyzing how to corral Gemini for agentic coding, an agent fed a vague, Claudish dispatch packet mirrors that style in its output. A Claudish architecture doc produces a Claudish implementation spec, which leads to bloated tests and fragile code.
  3. Compounding Errors in Multi-Agent Pipelines: The more insidious case is a long-running, multi-step pipeline where agents hand work to other agents. Every unclear handoff adds confusion, confusion raises the error rate at that step, and error rates multiply across a pipeline. If each step is 95% reliable, a ten-step pipeline gets everything right only about 60% of the time.
  4. Industry Drag: Thousands of engineering teams now have this prose embedded in their core repositories. My estimate is that, left untouched, it will cost the industry tens to hundreds of millions of dollars in confusion, debugging, and wasted context windows, and that without an active cleanup this technical debt will linger for 6 to 18 months. We are paying this tax ourselves: we are sweeping Claudish out of every one of our own repositories so that both humans and agents can understand them.

3. The Theoretical Fix: Style Over Ceremony

I learned this lesson myself, years before AI existed, during my graduate school qualifier, and the mistake was entirely mine. I buried my first draft—which covered concepts in statistical thermodynamics—under so much flowery academic prose that it took too much effort to parse the text and get to the ideas. That was folly. I'm not Shakespeare.

Later, during my postdoc at Dartmouth, computer scientist Tom Cormen (co-author of Introduction to Algorithms) handed me a slim volume: Style: Lessons in Clarity and Grace by Joseph M. Williams.

Williams' central thesis is simple:

  • Make the real characters your grammatical subjects.
  • Turn their key actions into active, finite verbs.
  • Keep your sentences focused and direct.

In software engineering, the primary purpose of language is to transmit technical concepts accurately with minimal friction. Anything that obstructs that transmission is waste.

4. Real-World Evidence: Before and After

During a recent prose sweep across a 33-file client repository, we applied these principles directly. Below are representative transformations from that sweep, with sensitive identifiers generalized:

Example 1: Restoring Finite Verbs and Eliminating Fragments

Target File Before (Claudish Fragment) After (Plain English)
CLAUDE.md FastAPI + PostgreSQL, pooled multi-tenancy with row-level security, React app in frontend/. The app runs on FastAPI and PostgreSQL. It pools multi-tenancy with row-level security, and serves a React frontend from frontend/.
operations.md The files, lowest precedence first: We list the configuration files below in ascending order of precedence:
operations.md Nothing raises. The dispatcher skips delivery and logs the event without raising an exception.
migrations.md One head, always. CI counts the heads. Maintain a single migration head at all times. The continuous integration pipeline counts revision heads.
migrations.md downgrade() is written, not stubbed. Implement reversible downgrades (downgrade()) rather than leaving stubs.

Example 2: Eliminating Nominalizations (The Noun Problem)

Target File Before (Abstract Noun Bloat) After (Active Verb Formulation)
README.md A customer's spreadsheet into rows: staging, an id map, resume... Stages and imports spreadsheet data into database rows with ID mapping and resume guarantees.
storage.md 1. Size, so nothing large is parsed... 1. Enforce size limits before parsing large payloads.
storage.md 2. Content sniff, from the bytes... 2. Inspect content bytes.
storage.md 3. Virus scan... 3. Scan for viruses.

Example 3: Concept Before Identifier

Target File Before (Naked Symbol Leading) After (Concept-First Framing)
tenancy.md common/tenancy.py applies the filter. tests/invariants/test_table_scope.py reads metadata. The tenancy module (common/tenancy.py) applies the filter. The table-scope invariant test (tests/invariants/test_table_scope.py) inspects metadata.

5. The Solution: Repository Sweep Runbook

Remediating this debt across your repository is inexpensive and parallelizes cleanly.

Model Selection

  • Recommended: Use a fast, disciplined model with low-to-medium reasoning overhead (such as Gemini 3.8 Flash on medium thinking within Antigravity). It adheres tightly to editorial constraints without over-theorizing.
  • Avoid: Heavy reasoning models or unconstrained Opus models for this specific task. Their default training distributions often regress right back into the pseudo-academic fluff you are trying to eliminate.

Step-by-Step Execution Plan

  1. Branch and Isolate: Cut a dedicated working branch:
    git checkout -b docs/plain-english-cleanup
  2. Build the Target Inventory: Enumerate your documentation root (docs/), repository guides (README.md, CONTRIBUTING.md, ARCHITECTURE.md), and agent configurations (CLAUDE.md, .cursorrules).
  3. Partition and Dispatch: Divide non-overlapping directory trees across parallel subagents using the prompt below.
  4. Verify Invariants: Run your test suite and linters to confirm no code identifiers or architectural invariants were altered:
    git diff --stat
pytest # or npm test
  5. Commit: Commit the verified diff cleanly:
    git commit -m "docs: sweep Claudish prose and restore plain English"

The Sweep Prompt

Copy and paste this prompt to execute the sweep across your codebase:

# TASK: Strip "Claudish" / "Cloddish" Prose and Restore Plain English

You are performing a comprehensive documentation and codebase prose sweep to eliminate "Claudish" (also known as "Cloddish") writing patterns.

Your mission: Strip pseudo-academic bloat, weak nominalizations, and fragmented phrasing across our documentation while preserving 100% of the underlying technical facts, system invariants, architecture rules, and code identifiers.

---

### The Problem: Over-Nominalization & The "Noun Problem"

Large language models (particularly Opus 4.8 / 5) suffer from a severe linguistic crutch: **turning processes into abstract nouns** and **dropping finite verbs in favor of trailing participial fragments**. Sentences end up reading like cognitive page faults:

- Instead of saying what a component *does*, they describe an abstract entity *performing the execution of an action*.
- Instead of complete Subject-Verb-Object (SVO) sentences, they emit robotic phrases like *"The runner, built."* or verbless bullet lists.

This obscures system state, inflates word count, and creates operational risk through avoidable human misunderstanding.

---

### Non-Negotiable Invariants

1. **Zero Semantic Drift:** Do not change what the code or system does. Retain every technical constraint, security invariant, architecture rule, and workflow requirement.
2. **Preserve Code Identifiers Exactly:** Never rename database tables, columns, API routes, environment variables, CLI flags, file paths, or symbol names.
3. **Em-Dashes (`—`) Are Allowed:** Do not strip, ban, or police em-dashes.
4. **Pass All Repository Checks:** All pre-commit hooks, linters, and verification checks must pass cleanly on the resulting branch.

---

### Core Writing Rules

#### 1. Attack Nominalizations (Convert Nouns to Active Verbs)

Find abstract nouns ending in `-tion`, `-ment`, `-ance`, `-ence`, and `-ity` paired with weak verbs (*provides, performs, handles, is responsible for*), and convert them into strong, active verbs.

| Claudish (Bad) | Plain English (Good) |
| :--- | :--- |
| *provides validation for incoming payloads* | *validates incoming payloads* |
| *performs the execution of database queries* | *executes database queries* |
| *responsible for the persistence of tenant data* | *persists tenant data* |
| *facilitates the establishment of connections* | *connects to* |
| *the instantiation of the service occurs at startup* | *the system creates the service at startup* |

#### 2. Kill Robotic Trailing Modifiers and Restore Finite Verbs

Write in complete Subject-Verb-Object (SVO) sentences. Eliminate lazy comma-spliced participial phrases.

| Claudish (Bad) | Plain English (Good) |
| :--- | :--- |
| *The runner, built, processes events.* | *After we build the runner, it processes events.* |
| *FastAPI + PostgreSQL, pooled multi-tenancy, isolating tenants.* | *The app runs on FastAPI and PostgreSQL. It pools connections and isolates tenants.* |
| *The payload, verified against schema, writes to disk.* | *The handler validates the payload against the schema and writes it to disk.* |

#### 3. Concept Before Identifier

Introduce the human concept first, then provide the technical symbol or identifier in parentheses or as reference. Do not lead sentences with naked code symbols unless writing reference tables.

| Claudish (Bad) | Plain English (Good) |
| :--- | :--- |
| *`DATABASE_URL` determines which cluster handles queries.* | *The application routes queries using the database connection string (`DATABASE_URL`).* |
| *`TenantMixin` provides `tenant_id` to models.* | *Every tenant-scoped model inherits tenant isolation (`TenantMixin`), which supplies the `tenant_id` column.* |

#### 4. Cut Academic Throat-Clearing

Delete empty transitional filler:

- Drop: *"It is important to note that..."* → Just state the fact.
- Drop: *"Serves as the foundational mechanism for..."* → *"Powers..."* or *"Provides..."*
- Drop: *"In order to facilitate..."* → *"To..."*

---

### Step-by-Step Execution Plan

1. **Branch & Isolate:**
   - Create a clean working branch: `git checkout -b docs/plain-english-cleanup`.
2. **Build the Target Inventory:**
   - Scan root documentation (`README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`), the docroot (`docs/`), agent rules (`.claude/rules/`, `.cursorrules`, etc.), and inline architecture specs.
   - Output a numbered checklist of target files.
3. **Partition & Process:**
   - Walk the files (or divide non-overlapping directories across parallel agents).
   - Apply the linguistic rules directly using search-and-replace or targeted file edits.
4. **Verify & Diff:**
   - Run repo validation and test scripts (`pytest`, `npm test`, linters, pre-commit checks).
   - Inspect `git diff --stat` to verify net reduction in line count and zero accidental code changes.
5. **Commit:**
   - Commit with a message like: `docs: plain-English prose cleanup across core documentation`.

Jason Vertrees is the founder of Heavy Chain Engineering, which helps lower middle-market vertical SaaS companies and PE firms turn scattered AI usage into measurable delivery leverage — 85% faster feature velocity, six-to-eight-week projects shipped in days. If you want help building an AI-native engineering organization, book an AI Delivery Assessment or email jason.vertrees@gmail.com.