DEV Community: mufeng

The Real AI Productivity Hack Is Not a Better Prompt

mufeng — Sat, 04 Jul 2026 00:47:04 +0000

I used to think the next jump in AI productivity would come from writing better prompts.

Longer prompts. More precise prompts. Prompts with role definitions, tone rules, examples, constraints, and output formats.

After reading a book on Agent Skills, I think that framing is too small.

The real bottleneck is not that I fail to explain a task once. The real bottleneck is that I keep explaining the same class of task again and again: how I want an article structured, how I review code, how I prepare App Store release notes, how I generate visuals, how I check a draft before publishing.

At some point, “using AI” quietly turns into “managing AI manually.”

The book’s most useful idea is simple:

AI productivity does not come from making every prompt longer. It comes from turning repeated work into executable, maintainable, testable skills.

That changed how I think about AI work.

A Skill Is Not a Prompt
A prompt is a temporary instruction inside one conversation.

A skill is a reusable operating manual for an agent.

That difference sounds small until you use AI every day. A prompt tells the model what you want right now. A skill tells the agent how a category of work should be done every time:

when to activate
what input to read
what steps to follow
which tools or scripts to call
what output to produce
what must never happen
where the agent should stop and ask for human judgment
That last part matters.

The goal is not to remove the human from the work. The goal is to stop spending human attention on the same low-level instructions.

For me, the most obvious candidates are not exotic:

a writing style skill
a code review skill
an iOS release checklist skill
an App Store release notes skill
a book notes skill
a weekly review skill
These are not tasks I cannot do. They are tasks where I keep repeating the same standards, preferences, caveats, and checks.

That repetition is the real cost.

The Useful Split: Judgment, Mechanics, and Workflow
One of the cleanest distinctions in the book is this:

prompts handle semantic judgment
scripts handle deterministic mechanics
skills orchestrate the whole workflow
This sounds obvious, but many AI workflows fail because they give the model the wrong job.

For example, asking a model to decide where an article needs illustrations is reasonable. Asking it to reliably rename files, validate image dimensions, split long documents, or calculate table values is usually a mistake.

Those are deterministic jobs. They should be handled by scripts or strict tools.

The model is better used for judgment:

choosing the angle of an essay
identifying the weak part of a draft
comparing two architecture options
explaining a tradeoff
turning rough material into clear language
The skill sits above both. It says: when this kind of task appears, use the model for the judgment parts, use scripts for the mechanical parts, and preserve the checkpoints where a human decision is required.

That is a much more durable pattern than trying to put everything into one giant prompt.

Context Is a Workbench, Not a Warehouse
Large context windows make it tempting to dump everything into the conversation.

Style guides. Prior chats. Examples. Templates. API docs. Drafts. Personal preferences. All of it.

The book argues for the opposite discipline: load the right material at the right time.

That is how skills should be designed. The main SKILL.md should not become a warehouse. It should contain the core workflow:

trigger conditions
inputs and outputs
main steps
hard constraints
failure modes
references to load only when needed
Long templates, examples, API notes, and style samples belong in separate reference files.

This is not just about token savings. It is about attention. The more unrelated material you push into context, the easier it becomes for the model to miss the one rule that actually matters.

Context should feel like a workbench: only the tools needed for the current job should be on it.

Good Workflows Are Not Fully Automatic
The dangerous version of AI automation is the one that looks efficient because it removes every pause.

Become a Medium member
Give the agent source material. Let it choose the angle. Let it write the draft. Let it polish the draft. Let it generate images. Let it publish.

That looks like a productivity win. Often it is just a way to outsource the most important decisions.

The better workflow is more selective.

For writing, I want AI to:

analyze source material
propose several angles
stop
let me choose the angle
draft from that angle
revise against my standards
prepare platform-specific versions
The pause is not friction. It is the point.

The same applies to development. AI can propose implementation plans, write tests, scan for regressions, and generate release notes. But architecture decisions, product tradeoffs, and publish decisions still need human ownership.

AI can do the prep work. It should not silently take over the judgment.

Skills Need Engineering, Not Decoration
A useful skill should be treated more like a small software product than a clever note.

That means it has a lifecycle:

define the real problem
build the smallest usable version
run it on real tasks
record failure modes
add tests or examples
refactor when the file becomes too large
keep improving it as the work changes
The most useful part of a skill is often not the elegant workflow. It is the “gotchas” section.

That is where you record the failures that keep happening:

the agent forgot to read the reference template
the output sounded too generic
the script handled the wrong file path
the model rewrote sections it should have preserved
the task needed a human checkpoint before publishing
This is where personal experience becomes operational memory.

If the same mistake happens twice, it probably belongs in the skill. If the same task happens three times, it is probably a candidate for a skill.

The Security Boundary Is Part of the Design
Skills become more serious when they can read files, write files, call scripts, access the network, or publish content.

At that point, they are not just prompts. They are operational tools.

So the safety rules need to be designed in from the beginning:

limit where the skill can read and write
avoid destructive actions without confirmation
back up before overwriting important files
test publishing workflows with fake data first
remove local paths, secrets, and personal assumptions before sharing a skill publicly
inspect third-party skills before running their scripts
This is not paranoia. It is basic engineering hygiene.

The more capable the agent becomes, the more explicit the boundaries must be.

What I Am Going to Try First
The book made the idea feel concrete enough that I can turn it into a weekly habit.

This week, I would start with three small skills.

First: a writing style skill.

Not a giant manifesto. Just a role, three style principles, a short banned-phrase list, and a few examples of what “good” looks like.

Second: an iOS or app release checklist skill.

The first version only needs to cover version number, release notes, screenshots, privacy text, and a final manual confirmation before submission.

Third: a gotchas section for existing skills.

Take the last three AI outputs that were disappointing. Convert each failure into a specific rule. Do not patch for one example. Capture the pattern.

There is also one experiment worth running immediately:

Take a piece of material you want to turn into an article. Do not ask AI to write the article. Ask it to do only two things: analyze the material and propose three angles. Then stop and choose the angle yourself.

If the final article improves, the human checkpoint paid for itself.

The Shift
The book did not make me want to use AI more.

It made me want to manage AI less manually.

That is the real shift: from temporary instruction to reusable workflow; from prompt accumulation to experience engineering; from asking AI to remember my preferences to writing those preferences into a system that can be maintained.

Better prompts still matter.

But the real compounding return comes when the prompt stops being a one-off instruction and becomes part of a skill.

Disclosure: this essay was adapted from my Chinese reading notes and drafted with AI assistance.

Two Ways Claude Code Calls Codex: One-Shot Subprocess vs. Persistent App Server

mufeng — Fri, 19 Jun 2026 09:59:31 +0000

"Claude Code calls Codex" sounds like one feature. It's at least two different process models, and they have almost nothing in common past the name.

The first spawns a one-shot subprocess with codex exec. You hand it one explicit instruction, it produces a file or a structured result, and it exits. The second runs a persistent runtime with codex app-server and talks to it over JSON-RPC, managing threads, turns, reviews, and interrupts for work that needs to carry state across rounds.

Both let Claude Code borrow Codex. They differ on startup cost, protocol, permissions, error recovery, and the kind of task they fit. Get the distinction wrong and you either over-engineer a one-shot job or reach for a stateless call on work that needs to resume.

The conclusion first: two architectures, not two commands

Dimension	`codex exec` one-shot subprocess	`codex app-server` persistent service
Reference implementation	baoyu `codex-imagegen` backend	OpenAI Codex Plugin for Claude Code
Process shape	Spawned per task, exits when done	Long-running, reused within a session
Transport	Launch args, stdin, JSONL event stream	JSON-RPC requests and notifications
State model	Single run, no dependence on the last	Thread holds multiple turns, can resume
Permission posture	The example uses `danger-full-access`	Review is read-only; task can switch to `workspace-write`
Typical task	Image gen, file generation, single deterministic op	Code review, long delegated tasks, multi-turn work
Main risk	Full-access child, cold start every time	More protocol and lifecycle complexity

The one-line test:

If you need to run once and get a single verifiable artifact, reach for codex exec.
If you need ongoing collaboration, retained context, and the ability to cancel or resume, reach for codex app-server.

Version scope: keep the numbers honest

The first thing this writeup exposed wasn't architecture. It was version accounting. I had carried over the original draft's phrasing about "the current local version," and only after checking the install records did I confirm that the marketplace source and the active plugin were not the same snapshot.

Local commands and plugin records show:

Codex CLI is 0.140.0.
The OpenAI Codex Plugin for Claude Code is 1.0.4, commit 807e03a.
The baoyu-skills marketplace source snapshot is 2.5.1, commit 441ca30.
But Claude Code's installed-plugin record still points baoyu-skills at the earlier 1.111.1 snapshot.

So the accurate way to state the baoyu-codex-imagegen analysis below is this:

It's based on the baoyu-skills v2.5.1 source snapshot in the local marketplace, not a claim that the active plugin has been upgraded to v2.5.1.

This is easy to miss. The marketplace source, the cached snapshot, and the active version can all be different commits. Read the directory name or the changelog alone and you'll write "the version I read" when you mean "the version actually running."

Path one: `codex exec`, Codex as a one-shot operator

What it solves

The baoyu-codex-imagegen skill has a narrow job: let a non-Codex host like Claude Code call the image_gen tool built into the Codex CLI, and save the result to a chosen path.

Tasks like that share a shape:

Clear input boundary, usually a prompt, an aspect ratio, and an output path.
Clear result boundary, usually one file and one line of structured status.
No need for multiple rounds, and no need to restore prior context.

So it skips a persistent service and spawns directly:

codex exec \
  --json \
  --sandbox danger-full-access \
  --skip-git-repo-check \
  -

If a reference image exists, it appends one or more --image arguments.

Why each flag is there

exec runs non-interactively for scripting. OpenAI's CLI docs position it as the execution path for automation and CI: run, return a result, done.

--json turns process output into line-delimited JSON events, or JSONL. The caller doesn't parse terminal display text; it reads structured events for the thread, tool calls, usage, and the final message.

--sandbox danger-full-access is here because this implementation needs Codex to copy the image from its default generation directory to an arbitrary target path the caller specifies, so it grants full file permissions.

That is not a general best practice. OpenAI's docs recommend workspace-write for automation and say to avoid unnecessary full access unless the runtime is already isolated.

--skip-git-repo-check lets Codex run outside a Git repo, since image jobs may launch from a temp or plugin directory rather than a trusted repository.

The trailing - tells Codex to read the instruction from stdin. The wrapper writes the task contract with child.stdin.write(instruction) and then closes stdin.

The task contract is the real work

This path doesn't pass the user prompt straight through. It wraps a strict instruction, roughly:

TASK:
Generate an image and save it to the given path.

STEPS:
1. You must call the built-in image_gen.
2. Copy the result to the target path.
3. Check that the target file exists.
4. Return one line of JSON only.

HARD CONSTRAINTS:
- Do not call an external image API.
- Do not fake the image with a script.
- You must use image_gen to produce real pixels.

This is the "sub-agent as operator" design:

Fixed input structure.
Fixed set of allowed tools.
Fixed file side effects.
Fixed output format.
Explicit prohibitions.

For an automated pipeline, the constraints matter more than the phrasing. The caller wants a verifiable result, not an open conversation.

Don't trust self-reported success: three checks

The engineering detail worth keeping is that this implementation does not call the job done just because Codex replied "success."

It checks, in order:

Whether the JSONL events contain a thread ID.
Whether an image actually appears under $CODEX_HOME/generated_images/{threadId}/.
If the directory check fails, whether the tool calls include a cp or mv from the generation directory to the target path.
Whether the target file actually exists and has a byte count above zero.

Failure becomes a structured error:

agent_refused
no_image_gen_tool_use
timeout
codex_not_installed
spawn_failed

The point isn't the image. It's a general principle:

An agent's natural-language reply is a claim. Files, events, and repeatable checks are evidence.

Where it fits and where it doesn't

Good fit:

Single image or file generation.
A code transform with clear boundaries.
One-off analysis that returns structured JSON.
Automation that doesn't need inherited context.

Limits:

Every run pays process and model cold-start cost.
No cross-run state by default.
With danger-full-access, the trust boundary is very wide.
Timeout, cancellation, and recovery usually fall to the wrapper to build.

Path two: `codex app-server`, Codex as a stateful service

The OpenAI Codex Plugin for Claude Code does not re-run codex exec per command. It starts codex app-server and manages an ongoing session over JSON-RPC.

OpenAI's docs define the App Server's core abstraction in three layers:

Thread: a conversation that persists.
Turn: one round of user input and agent execution inside a thread.
Item: events inside a turn, such as messages, reasoning, commands, and file edits.

Direct connection and broker

The plugin supports two connection modes.

Direct:

Claude Code
    |
    | stdin/stdout JSONL
    v
codex app-server

The client starts codex app-server itself and sends line-delimited JSON-RPC over stdio.

Broker:

Claude Code command
    |
    | Unix socket
    v
Broker
    |
    | reuse
    v
codex app-server

The plugin stores the broker endpoint in CODEX_COMPANION_APP_SERVER_ENDPOINT so review, rescue, and status commands in the same Claude Code session share one Codex runtime.

If the broker returns the busy error -32001, or the connection hits ENOENT or ECONNREFUSED, the plugin drops the broker and starts an App Server directly to retry.

That's one more layer than a one-shot subprocess, and it buys:

Runtime reuse within a session.
Thread persistence.
Background task management.
Cancel and resume.
Permission isolation between review and task.

Handshake: initialize first

Once the App Server connection is up, the client sends initialize, then an initialized notification.

The plugin passes this client identity:

{
  "title": "Codex Plugin",
  "name": "Claude Code",
  "version": "1.0.4"
}

It also uses optOutNotificationMethods to unsubscribe from some token-level delta events, keeping the structured notifications that are worth more to the caller and cutting noise.

Session model: threads and turns

The key RPC methods the plugin uses:

Method	Purpose
`thread/start`	Create a new thread
`thread/name/set`	Name a thread
`thread/resume`	Resume an existing thread
`thread/list`	Query past threads
`turn/start`	Start a turn in a thread
`review/start`	Start a code review
`turn/interrupt`	Interrupt a running turn

So the App Server isn't a single-round wrapper that "sends a prompt and waits." It's a managed session runtime.

Review and task have different permissions

The plugin keeps the two actions separate.

Review runs read-only, on a temporary thread, through review/start. It returns findings and does not touch code.

Task defaults to read-only. Pass --write and it switches to workspace-write. It can save the thread, and it can continue prior work with --resume or --resume-last.

This is closer to what an engineering system's default should look like than "run everything with full access." Set the minimum permission by the nature of the task, then decide whether to widen write scope.

Hooks wire Codex into the Claude Code lifecycle

The plugin registers three Claude Code hooks:

SessionStart: prepare the shared runtime.
SessionEnd: clean up the broker and session resources.
Stop: an optional stop-gate review.

With the review gate on, every time Claude Code is about to stop, it can have Codex check whether the last round has a blocking problem.

The value isn't "one more model." It's putting a second model inside the delivery flow:

Claude makes a change
    |
    v
Codex reviews independently
    |
    +-- ALLOW: stop is permitted
    |
    +-- BLOCK: return findings, keep working

It has a cost. The official plugin README warns that the review gate can create long Claude/Codex loops and burn through usage fast, so don't turn it on unconditionally.

How to choose

When `codex exec` fits

Use a one-shot subprocess when most of these hold:

The task is a single round.
The result can be verified by a file or JSON.
You don't need to restore prior context.
Cold-start cost is acceptable.
The caller can handle timeout and retry on its own.

Examples: generate an image, convert input to a fixed format, run one analysis on a file, run a check once in CI.

When `codex app-server` fits

Use the persistent service when you need:

Multiple rounds of conversation.
Thread resumption.
Background runs and status queries.
Interruption of a running task.
Separate review and write permissions.
Integration with Claude Code's session lifecycle.

Examples: review a branch continuously, delegate a long investigation, let Codex change code and then add tests, or run an automatic second-model gate before stopping.

How this was verified

This published version doesn't lean on the draft's description. I redid a minimal verification.

The steps I ran:

Read the draft and listed every factual claim about versions, commands, RPC methods, and permissions.
Ran codex --version, codex exec --help, and codex app-server --help to confirm the current CLI's commands and flags.
Checked the OpenAI plugin manifest, install records, app-server.mjs, codex.mjs, and the hook config.
Checked spawn.ts, main.ts, the version file, and the Git commit in the baoyu marketplace source.
Cross-checked against the OpenAI Codex CLI, App Server, Codex Plugin, and Claude Code Hooks docs.
Recorded "current active version" and "source snapshot I actually read" separately.

The mistake and the lesson

I first took the draft's baoyu-skills v2.5.1 as "the current local version." On further checking, the v2.5.1 marketplace source does exist locally, but Claude Code's installed-plugin record still points at an earlier snapshot.

Without checking the install record, that phrasing looks reasonable and is wrong.

The lesson:

When you analyze a local plugin, record at least the marketplace HEAD, the install cache path, the plugin manifest, and the commit. No single one of those stands in for "the version actually running."

Practical advice

One-shot tasks: hardcode the output contract

Don't write "generate an image for me" or "check my code." An automation prompt should include at least:

Goal
Allowed tools
Input and output paths
Prohibitions
Verification steps
Final return format

That cuts the uncertainty of an agent improvising, and it lets the caller judge success or failure.

Long tasks: resume with the delta only

When you resume a thread, send only what changed:

Continue the last task. Apply the first fix and add the matching test.

There's no reason to re-paste the whole background. Repeating context adds noise and can make the model misread the task boundary.

Review tasks: bind every finding to evidence

Whether you run a standard review or an adversarial one, require each finding to carry:

The file or diff actually examined.
A reproducible failure path.
A clear risk level.
A split between fact, inference, and open question.

A "might be a problem" with no evidence rarely makes it into an engineering decision.

Permissions: start at the smallest scope

The order of preference:

read-only
    |
    v
workspace-write
    |
    v
danger-full-access

Widen only when the task genuinely needs a larger file scope and the runtime is trusted.

Closing

"Claude Code calls Codex" is not one calling convention.

codex exec is a one-shot, stateless subprocess that's easy to wrap. It fits single tasks with clear boundaries and verifiable results.

codex app-server is a stateful, resumable, manageable agent service. It fits code review, task delegation, and complex work that needs ongoing collaboration.

The real selection criteria aren't "which is more advanced." They are:

Does the task need state?
Can the result be verified in one shot?
Do you need interruption, resume, and background management?
Can permissions be graded by action?
Is the extra protocol complexity worth it?

Simple tasks get a simple process. Ongoing collaboration gets a stateful service. Draw that line clearly and the system gets easier to understand and to maintain.

References

Your blog is invisible to AI. Here's the 1999 fix.

mufeng — Mon, 15 Jun 2026 03:49:58 +0000

A quick story about a dead protocol, a confused chatbot, and the ten minutes that gave my blog a new kind of reader.

Hey friends,

A small thing happened the other day that I haven't been able to stop thinking about.

I dropped a link to my blog into Claude and asked it to read a few of my recent posts. It came back and told me: can't fetch it. The page returned an empty shell — undefined | loading. My blog runs on NotionNext, the content renders client-side with JavaScript, and AI crawlers don't execute JS. All it got was the skeleton that exists before the page comes to life.

I stared at that spinner for a few seconds, and something clicked: in the AI era, a site built only for human eyes is worth only half of what it could be.

The other half belongs to machine readers. And the door to those readers was already built back in 1999. It's called RSS.

If you've been around the internet long enough, you just felt a little nostalgia twinge. Stay with me — this turned out to be one of the highest-leverage things I've done for my writing in years.

What RSS actually is

One sentence: RSS is a read-only API your blog exposes to the world.

It's a static XML file listing your most recent posts in reverse-chronological order — title, link, publish date, and either a summary or the full text. Any program can grab it with a single HTTP request. No JavaScript, no login, no API key.

If you're technical, picture a public GET /articles?limit=20 endpoint whose response format hasn't changed in over two decades. A protocol defined in 1999, and every reader today still parses every feed. In web terms, that's a living fossil.

It solves exactly one problem: readers no longer have to keep reopening your site to check for updates. Someone adds your feed to their reader, the reader polls it on a schedule, new posts get pushed to them. The subscription lives entirely in their hands — no algorithm, no rate limit, no platform taking a cut.

(Sound familiar? It's basically what you're doing by reading this email. A newsletter is RSS with a friendlier face.)

Why we forgot about it

The platforms won.

When Google Reader shut down in 2013, control over information flow shifted from subscription to recommendation. Twitter/X, TikTok, Instagram — algorithms decide what you see and feed your attention on a drip. Subscription is too "dumb" for that business model: it won't guess what you like, won't manufacture anxiety, won't keep you scrolling.

So RSS retreated to the corner, kept alive by a small group: programmers, content creators, deep readers.

But here's the twist — that small group is exactly the audience an independent writer most wants. People still using an RSS reader actively curate their own sources. They don't scroll a feed; they choose their springs. Get into their list and you've earned a long-term seat at the table: they read everything you publish, not the one piece an algorithm happened to surface.

Why AI is bringing it back

Two shifts changed my mind.

One: machines are your blog's new readers. People now ask ChatGPT and Claude to summarize your work, point assistants at your site to track updates, and let agents pull your content into research. Most of those crawlers don't run JavaScript — so a client-rendered blog is a blank page to them. RSS is pure server-side XML; any AI can parse it in one line. When I sent Claude my RSS link instead, it instantly read every recent post. Same content — the HTML page is a welded-shut door, the feed is an open window.

Two: AI fixes RSS's old fatal flaw. Subscription used to die under its own weight — a hundred feeds, hundreds of daily updates, no human can keep up. An LLM dissolves that. More people now let AI sweep every source once a day and produce a linked digest, surfacing only the few pieces worth reading closely. You pick the sources, AI does the skimming, you keep the deep reading.

In the algorithm era, a platform uses AI to feed you. In the RSS + LLM era, you use AI to feed yourself. The controls have flipped.

Do it in ten minutes

Confirm you have a feed. Most frameworks ship one for free. Try yourdomain.com/rss/feed.xml or /atom.xml (NotionNext / Hexo / Hugo), yourdomain.com/feed (WordPress), or yourdomain.com/rss (Ghost). See XML? It works.
Make it visible. Put an RSS link (with the orange icon) in your footer or About page, and confirm your HTML <head> has the auto-discovery line:

   <link rel="alternate" type="application/rss+xml" title="RSS" href="https://yourdomain.com/rss/feed.xml" />

Use it yourself. Install Feedly, Reeder, or Folo. Subscribe to five writers you admire plus your own blog. Live with it a week and feel the difference between information finding you and you chasing it.

Want to go further? Use n8n or GitHub Actions to pull your feeds on a schedule, send the updates to an LLM API for a daily digest, and push it to your inbox or Telegram. An evening's work — probably the highest-ROI personal infrastructure you'll ever build.

The honest limits

It won't reach a mass audience. Most people don't know what RSS is. Bulk traffic still comes from social and search. RSS serves the small high-value slice — and the machines.
Almost no engagement data. No open rates, no idea who's reading. For dashboard people, it feels like writing in the dark.
Full text vs. summary is a real tradeoff. Full text is kind to readers but invites scrapers; summaries drive clicks but degrade the experience. My take: ship full text. An independent writer's enemy was never being reposted — it's not being read at all.

One last thing

After years of building software, I keep coming back to one conviction: the good protocols outlive the platforms. Email is older than every social app and won't die. HTTP has watched products rise, throw their banquet, and collapse. RSS has been pronounced dead more times than anyone can count — and in the AI era, it found its second spring.

Platforms change. Algorithms change. Whichever channel is hot this quarter will change. But the need for an open, machine-readable outlet anyone can subscribe to does not.

Spend ten minutes today: find your feed, surface it, subscribe to it. Then hand the link to your AI assistant and watch it read back every post you've ever written.

That's the moment you realize your blog just gained a whole new audience that's always online.

Until next time,
Joey

If a friend would find this useful, forward it along. And if someone shared this with you — you can subscribe below to get the next one straight to your inbox.

Your AI Agent Is Underperforming Because of Your Harness, Not the Model

mufeng — Thu, 11 Jun 2026 05:08:36 +0000

The pattern is familiar: your AI agent produces garbage output, so you switch to a better model. Things improve for a few days, then the same problems resurface. You upgrade again.

Here's what you're probably missing: the model is just one input. The rest is harness — and that's almost always where the real problem lives.

What Is a Harness?

The cleanest definition comes from engineer Vtrivedy, who coined the term:

Agent = Model + Harness. If you're not the model, you're the harness.

A harness encompasses everything except the model itself:

System prompts, CLAUDE.md / AGENTS.md files, Skill definitions
Tool descriptions, MCP servers, and their technical specifications
Execution environment: filesystem, sandboxes, headless browsers
Subagent orchestration: spawning logic, task handoffs, routing
Hooks: deterministic enforcement layers (linting, formatting, permission checks)
Observability: cost monitoring, latency tracking, logs

This entire surface area is yours to design, not the model provider's.

Claude Code, Cursor, Codex, Cline — these tools might run on identical underlying models, but the behavior you experience is dominated by the harness each one provides. The underlying model might be identical across two setups; the behavior you see will be completely different.

This leads to a counterintuitive but well-supported finding:

A decent model with a great harness consistently outperforms a great model with a bad harness.

Why Engineers Default to Model-Blaming

When an agent does something nonsensical, blaming the model is the path of least resistance. It's the most visible component, and failures often look like reasoning problems.

But most failures are legible if you look closely:

Agent ignored a coding convention → Add it to AGENTS.md
Agent ran a destructive command → Write a Hook to block it
Agent got lost in a 40-step task → Split into Planner and Executor subagents
Agent consistently ships broken types → Wire a type-checker signal into the loop

As HumanLayer frames it: "It's not a model problem. It's a configuration problem."

Consider the performance benchmarks: a leading model running inside an off-the-shelf framework often scores dramatically lower than the exact same model running in a custom, highly-tuned harness. The model's capabilities didn't change — the harness is what unlocks them.

The Ratchet: Every Failure Becomes a Rule

The most important habit in harness engineering is treating agent failures as permanent signals, not one-off flukes to retry and forget.

Think of a mechanical ratchet: it only moves forward, never backward.

When an agent makes a mistake, you don't retry and hope for better luck. You engineer a permanent fix so the same exact failure cannot happen again.

Example: An agent submits a PR with commented-out tests. It gets merged into main.

Wrong response: Fix it manually. Move on.

Harness response:

Add to AGENTS.md: "Never comment out tests. Delete or fix them."
Add a pre-commit Hook that flags .skip( in any diff automatically.
Update the Reviewer subagent's instructions: commented-out tests are a blocking issue.

Three layers. Same failure is structurally impossible now.

Constraints should be added when you observe a real failure, and removed when a more capable model makes them redundant. Every line in a good system prompt should trace back to a specific, historical failure. A harness that grows without bound is just as broken as one that never grows.

CLAUDE.md Is a Failure Log, Not Documentation

This is the mistake I see most often. Engineers treat CLAUDE.md like a README written for an AI: project overview, tech stack, coding conventions. Useful — but incomplete.

Mature harnesses treat CLAUDE.md differently: every rule should trace back to a specific, real incident. If you can't remember the failure that generated a rule, it's probably noise that dilutes the signal of the rules that actually matter.

Examples of rules with provenance:

"Never use any type without explicit authorization" → From a production bug after TypeScript checks were bypassed.
"Run the full test suite before committing, even for one-line changes" → From a regression where a small fix touched adjacent logic without running tests.
"Back up configuration files before modifying" → From an agent that overwrote a production config.

Rules derived from real incidents carry weight in the agent's reasoning. Rules written speculatively get treated as suggestions — not because the model is bad, but because they lack the contextual authority that real constraints carry.

Context Engineering: The Harness Layer People Miss

There's a component of harness design that gets less attention than it deserves: context management.

Antonio Gullí, Engineering Director at Google, defines Context Engineering in Agentic Design Patterns:

Not information dumping. Carefully selecting, trimming, and packaging context. To get AI to peak accuracy, you must give it short, focused, powerful context.

This distinguishes Context Engineering from the more common Prompt Engineering. Prompt Engineering asks: How should I phrase this request? Context Engineering asks: What should already be in front of the agent before it even sees the request?

The discipline applies to every part of the harness:

Tool descriptions: Concise and precise, not comprehensive
Skill files: Exact schemas and templates the agent needs, not everything
System prompts: Specific constraints from real failures, not generic guidelines

An agent drowning in context doesn't perform better — it performs worse. Every line in your CLAUDE.md or system prompt is doing Context Engineering. Noise in equals noise in the agent's reasoning.

Two-Tier Configuration: Team Brain + Personal Brain

Claude Code's configuration architecture is worth understanding as a design pattern applicable to any agent harness.

Project .claude/ — lives in the repo, committed to Git
Team-shared rules, hooks, security policies, workflow definitions. Every engineer who clones the repo inherits the full agent behavior constraints automatically. This is an engineering asset, maintained alongside code.

Global ~/.claude/ — personal directory, stays out of Git
Personal coding style preferences, cross-project shortcuts, individual tool configurations.

The separation enforces the right ownership boundaries: team standards are reliable and shared, personal preferences are free and local. New team members inherit your agent setup the moment they clone the repository.

What Changes When You See It This Way

Once you internalize Agent = Model + Harness, the questions you ask about AI tools shift.

Before:

Which model has better code generation?
What's the context window size?
What's the price per token?

After:

How mature is this harness?
What does the failure recovery path look like?
How are harness rules maintained over time?
What's the observability story?

The model is table stakes at this point. The harness is the differentiator.

Anthropic's engineering team published this framing directly:

The gap between what today's models can theoretically do and what you actually see them doing is largely a harness gap.

The ceiling isn't the model. The floor you're operating at is almost entirely determined by your harness.

Start Here

Open your CLAUDE.md, or create one if it doesn't exist.

Think about the last thing your agent got wrong. Not a model failure — a behavioral failure. Something it did that violated an expectation.

Write one rule. Note where the failure came from. One sentence is enough.

That's the first notch on the ratchet. Over months, this file becomes a compressed history of your collaboration — every line representing a mistake that was never repeated.

The harness isn't designed. It's earned.

I write about practical AI engineering, agent design, and building production systems with Claude. Follow for more.

How to Make AI Coding Agents Actually Follow Engineering Process

mufeng — Sun, 07 Jun 2026 15:53:26 +0000

The problem isn't that AI coding agents write bad code.

The problem is that they skip steps.

Ask an agent to fix a bug—it reads a few files, guesses a cause, patches the code. Ask it to add a feature—it starts writing before anyone's agreed on what the feature actually does. Ask it to refactor—it touches unrelated files, reformats half the codebase, and hands you a diff too large to review.

None of this is stupidity. It's the absence of process discipline.

Software development has always required workflow constraints: clarify before implementing, plan before coding, test before shipping, debug root causes not symptoms, verify before declaring done. The question is whether your AI agent follows them—or bypasses them entirely.

Superpowers is a plugin framework for Claude Code and Codex that encodes those constraints as loadable, composable agent workflows. This is what it is, when to use it, and how to get started.

What "Skills" Actually Are

The word "skill" is overloaded in AI contexts. Here it means something specific: a workflow protocol that loads into an agent session and constrains how the agent approaches a category of task.

Not "be more careful." Not a style guide. A specific sequence of steps with defined inputs, outputs, and verification gates.

The analogy is a checklist for a surgeon or a pilot—not because either lacks expertise, but because cognitive discipline under pressure requires procedural anchors.

The core Superpowers Skills cover the major failure modes in AI-assisted development:

Skill	Failure Mode It Prevents	What It Produces
`brainstorming`	Implementing the wrong thing	Clarified scope with edge cases surfaced
`writing-plans`	Drifting mid-implementation	Executable task list: file scope + verification per step
`test-driven-development`	"Works on my machine" guesswork	RED-GREEN-REFACTOR cycles that lock behavior first
`systematic-debugging`	Shotgun-patching symptoms	Root cause hypotheses, evidence-based elimination, minimal fix
`verification-before-completion`	"Should be done" claims	Actual test runs, browser paths, or device checks
`requesting-code-review`	Merging unreviewed code	Severity-ranked risk list before merge
`using-git-worktrees`	Task bleed across workstreams	Isolated workspaces with clean baseline

These aren't independent tips—they chain into a complete development pipeline:

Vague requirement
  → brainstorming  (scope + edge cases)
  → writing-plans  (executable task list)
  → test-driven-development  (behavior locked by tests)
  → requesting-code-review  (risks surfaced)
  → verification-before-completion  (actually verified)

The Key Insight: Process Errors vs. Code Errors

AI agents will get better at writing correct code over time. They won't automatically get better at following process—unless process is encoded somewhere.

The bugs Superpowers Skills prevents aren't syntax errors or logic bugs. They're:

Building the wrong feature because nobody asked the right clarifying questions
Writing code that "looks complete" but has zero coverage on the edge cases that matter
Patching a symptom while the root cause persists
Refactoring that expands scope until the diff is unmergeable
Shipping because the agent said "done" without running anything

A more capable model doesn't fix these. A faster agent arguably makes them worse—more code written in the wrong direction before anyone catches it.

A Real Example: Adding Invoice Export

Imagine you tell an agent: "Add a billing export feature."

Without workflow constraints, it will probably find the billing service, write an endpoint, add a download button, and report completion. Whether that implementation handles empty data, unauthorized requests, large datasets, or export format edge cases depends entirely on whether the model guessed right.

With Superpowers Skills, the flow looks like this:

Step 1: `brainstorming`

Before touching any files, the agent surfaces questions:

Export format: PDF, CSV, or Excel?
Date range limits?
Permission checks required?
Sync download or async background job?
What does the user see on failure?

This isn't bureaucracy. This is the list of decisions that will otherwise get made silently—by the model, in the wrong direction.

Step 2: `writing-plans`

A compliant plan doesn't say "implement invoice export." It says:

1. Add exportInvoiceCsv(userId, range) to billing service.
   Verify: unit tests covering empty data, normal data, unauthorized access.

2. Wire export endpoint in API routes.
   Verify: 403 on missing permissions, valid text/csv response on success.

3. Add download button to billing page.
   Verify: file downloads on click, loading and error states render correctly.

Every task has a file scope and a verification gate. That's what makes it executable instead of aspirational.

Step 3: `test-driven-development`

Tests first. Not as documentation—as behavior contracts:

describe("exportInvoiceCsv", () => {
  it("exports invoices as csv rows", () => {
    const csv = exportInvoiceCsv([
      { id: "inv_001", amount: 1999, currency: "USD" },
      { id: "inv_002", amount: 2999, currency: "USD" },
    ]);

    expect(csv).toContain("id,amount,currency");
    expect(csv).toContain("inv_001,1999,USD");
    expect(csv).toContain("inv_002,2999,USD");
  });
});

Write the failing test. Confirm it fails. Implement the minimum to pass. Confirm it passes. Then refactor. The order matters.

Step 4: `requesting-code-review`

Before merge, the review targets:

Does this match the agreed plan?
Any authorization gaps?
Large dataset edge cases?
Unhandled error states?
Files changed outside the agreed scope?

Step 5: `verification-before-completion`

Depending on project type:

Project Type	Verification Method
Web app	Start dev server, walk the critical path in browser
Backend service	Run tests, type check, hit the endpoint
CLI tool	Run the command, check actual output
iOS app	Test on real device (especially IAP, StoreKit, permissions)
SDK / Library	Unit tests + integration tests + example project

The principle: evidence over claims. "I think it's done" is not verification.

How to Install

Claude Code

/plugin install superpowers@claude-plugins-official

Or via the Superpowers marketplace:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex CLI

/plugins

Search superpowers, select Install Plugin.

Codex App

Sidebar → Plugins → Coding category → Superpowers → +

When to Use vs. Skip

Not every task needs a full workflow. A typo fix doesn't need a plan. A one-liner doesn't need TDD.

The right mental model is risk-proportional discipline:

Task	Recommended Approach
Typo fix, config lookup	Direct action—just verify the output
Single-file small change	Optional workflow; at minimum verify
Bug with unclear root cause	`systematic-debugging` required
New feature	`brainstorming` + `writing-plans` + TDD
Cross-module refactor	Plan + verification strongly recommended
Pre-merge / pre-deploy	`requesting-code-review` + `verification-before-completion`

Skills should add friction proportional to the blast radius of getting it wrong.

Three Skills to Start With

If you're integrating Superpowers into an existing project, don't try to use everything at once. Start with three:

1. `systematic-debugging`

Tell the agent:

"Use systematic-debugging. Do not modify any code yet. List your root cause hypotheses first, then we'll validate them one by one."

This stops the shotgun-patch reflex before it starts.

2. `writing-plans`

Before any non-trivial feature or change:

"Use writing-plans. Produce an executable plan first. I'll confirm before you implement anything."

This surfaces scope creep before it happens, not after you're reviewing a 500-line diff.

3. `verification-before-completion`

Add this to your project's CLAUDE.md or AGENTS.md:

"Before declaring any task complete, use verification-before-completion. Run tests, verify in browser or device, report exactly what you checked and what the result was."

This closes the gap between "I think it works" and "I confirmed it works."

The Broader Pattern: Startup Superpowers

Startup Superpowers—a companion project that applies the same framework to startup validation—illustrates why this pattern generalizes beyond coding.

It applies the same idea (codify a professional workflow into loadable agent protocols) to hypothesis tracking, competitor research, customer interviews, and MVP scoping. Available slash commands:

Command	Purpose
`/whats-next`	Assess current stage, recommend next action
`/competitors`	Map direct and indirect competitors
`/market-research`	Research customers, pricing, and trends
`/hypotheses`	Write testable hypotheses with evidence tracking
`/interviews`	Design scripts and analyze transcripts
`/surveys`	Design surveys and manage responses
`/mvp`	Design the minimum testable product

Everything is stored as Markdown in a startup/ directory—version-controllable, agent-readable, no SaaS dependency.

That's the actual pattern: take a repeatable professional workflow, encode it as agent steps with defined inputs and outputs, make it loadable in any session, and store all state in files the agent can read and write. The AI doesn't get smarter. The process gets stable.

Summary

Superpowers Skills solves a specific problem: AI coding agents that know how to write code but don't know how to do software development.

The six questions it forces an agent to answer before declaring a task complete:

Did you clarify the requirements before implementing?
Did you make a verifiable plan before writing code?
Did you write tests before the implementation?
Did you find the root cause before patching?
Did you get a review before merging?
Did you actually verify—not just assume—that it works?

Without workflow constraints, developers have to ask these questions themselves, every session, every task. With Superpowers, the constraints are stable, loadable, and consistent across sessions, developers, and projects.

If you're using AI coding agents in real projects today, start with three skills: systematic-debugging, writing-plans, and verification-before-completion. They won't make development magical. They'll make your agent behave like a collaborator with engineering discipline instead of one without it.

Superpowers: github.com/obra/superpowers
Startup Superpowers: github.com/SergeiGorbatiuk/startup-superpowers