DEV Community: claude

How I Use SDD (Spec-Driven Development)

Davi Orlandi — Mon, 05 Oct 2026 13:17:04 +0000

If you follow tech the way I do, you've probably already felt lost with the flood of innovations launching every week since AI took off (or at least opened Twitter/LinkedIn and thought "okay, I became obsolete in 3 days"). Today I'll share a bit of my experience with one of them: Spec-Driven Development.

What is SDD?

SDD, or Spec-Driven Development, is a software development framework where the specification comes before the code. Instead of generating code unchecked, we define functional and technical specifications that guide development, serve as documentation and history, and help enrich the context LLMs use throughout the process.

There are many ways to use SDD. You can rely on ready-made setups like cc-sdd for Claude Code, or Spec Kit Command for Cursor, which already ship with ready-to-use commands. You can also build your own commands on top of these setups to fit your day-to-day workflow. It's common to have agents, skills, or commands specialized for each company's workflows — "How to deploy the backend", "Security acceptance criteria", and so on.

Workflow

SDD implementations vary by use case, but most go through these phases:

Functional Spec

This is where we describe requirements functionally. Use as little technical language as possible (yes, that's harder than it sounds).

You can start from an idea, a task from tools like Jira via MCP, or even a bug. Example:

Users complete onboarding but receive no follow-up. That reduces engagement and doesn't guide them through the next steps inside the platform.

Since this is a discovery moment, the AI starts asking questions:

AI: Which users should we implement this for?

You: All newly registered users who finished onboarding.

AI: Exactly when should the email be sent?

You: Immediately after confirming that onboarding completed successfully.

AI: What are the functional requirements?

You:

Detect the moment onboarding completes

Trigger the email only once per user

Personalize the email with basic data (name, etc.)

Implement retry if the email service fails

Log successes and errors

These refinements produce a Functional Spec — everything needed to describe the technical details of the implementation.

That document should also include clear acceptance criteria, which serve as the validation baseline throughout the flow.

The spec must be editable and have an approval mechanism. In almost every case, you'll iterate with the LLM until you land on something satisfactory.

This phase can be started with commands like:

/sdd.spec functional Envio de email de onboarding

Some setups use flags such as:

--clarify when something isn't clear
--approve when you consider the spec ready

Technical Spec

With the functional specification defined, translate the business requirements into technical details. You can start with:

/sdd.spec technical

Example:

AI: What technology stack will you use?

You: Node.js with Express for the service, integration with an email provider (e.g. SES or similar), and a queue (e.g. SQS or PubSub) for asynchronous processing.

AI: What API design approach?

You: Event-driven architecture. The trigger will be based on the user.onboarding.completed event, with asynchronous communication.

AI: Which services or platforms will be integrated?

You: An email service for sending, a messaging system for the queue, and possibly a template service. Also integration with the auth system to keep data consistent.

AI: What are the performance requirements?

You:
Event processing latency under 5 seconds
Ability to handle spikes without losing events
Failure rate under 1 percent with automatic retry

AI: How will reliability be ensured?

You:
Use a queue to decouple processing
Retry with exponential backoff
Dead-letter queue for unprocessed events
Idempotency to avoid duplicates

Just like in the functional phase, this step produces a technical document that should be reviewed and approved.

Don't let technical details rewrite the functional requirements — though in the real world, technology often ends up shaping business specs anyway.

Tasks

By now we've turned an idea into two clear things: what to do and how to do it. Next comes execution.

Translate the spec into clear, actionable tasks — exactly what the LLM or the developer should do, with no ambiguity. Start with:

/sdd.plan

The AI then generates something like:

AI: Here are the suggested tasks:

TASK-001: Implement consumer for the user.onboarding.completed event

TASK-002: Create email-sending service with provider integration

TASK-003: Implement idempotency logic to avoid duplicates

TASK-004: Create email template with personalization

TASK-005: Wire the full flow from event to send

TASK-006: Add logs and metrics

AUTO-TASK-001: Create unit tests

AUTO-TASK-002: Create integration tests

These tasks can be saved in files such as tasks.json or individually as TASK-001.md, containing:

Status such as wip, done, or canceled
Assignee
Dependencies
Possibility of parallelization

You can refine with:

/sdd.plan --refine

And then approve with:

/sdd.plan --approve

This phase matters because it turns the spec into something executable. There should be no ambiguity here — only clear tasks.

Implementation

With everything approved, enter the implementation phase:

/sdd.build

During this phase, the AI executes the tasks and continuously validates the acceptance criteria from the functional spec, keeping the implementation aligned with the plan.

Because the tasks are already well defined and decoupled, some tools let you parallelize executions that have no dependencies.

One example is Claude Agent Teams, which let you run multiple agents in parallel, each responsible for part of the system. Instead of a single AI doing everything sequentially, you can have:

One agent implementing services
Another writing tests
Another handling integration

All at the same time, respecting the dependencies defined in the tasks.

This works especially well with SDD because the tasks are already well scoped — you don't need to manually coordinate who does what; the structure of the spec enables that split.

Following the flow:

AI: Creating branch feature/email-onboarding

AI: Starting task execution.

AI: Running TASK-001: Event consumer

AI: Consumer created successfully. Want to validate with tests?

You: Yes.

AI: Tests ran successfully.

AI: Running TASK-002: Email-sending service

AI: Provider integration complete. Retry implemented.

AI: Tests passing.

This process continues until all tasks are done.

Finish

After implementation, wrap up the feature: make sure everything defined in the specs was delivered, validated, and is ready for production.

You can start with:

/sdd.finish

The AI then runs final validations:

AI: Checking task status...

AI: All tasks are complete.

AI: Validating tests...

AI: All tests are passing with adequate coverage.

AI: Validating consistency between specs and implementation...

AI: No divergences found.

AI: Do you want to finish the feature?

You: Yes.

At that point, a few things usually happen:

Mark the feature as complete
Ensure all specs are up to date
Consolidate documentation
Prepare for deploy or merge

Tips & tricks

Don't limit yourself to ready-made setups — you can integrate this flow with day-to-day tools using MCPs like Jira or Linear to generate specs from tasks, GitHub to manage issues, branches, and comments, or Playwright to test a generated frontend.

It's also common to have specialized agents for specific stages — code review, security validation, performance analysis. That makes the flow safer without adding manual complexity for the developer.

Conclusion

You're no longer deciding what to do while writing code. That was already settled in the earlier phases. In a world where LLMs take an active part in development, this shrinks scope, improves delivery quality, and makes the process far more reproducible.

In the end, it isn't about writing more code. It's about thinking better before you code (and letting the AI suffer a bit more in your place).

A Beginner Vibe-Codes a Game — Zero Coding, 3 Days, $45

Johmisking — Mon, 05 Oct 2026 12:37:15 +0000

I had zero coding experience. I didn't even know what a "game engine" was. Still, by describing what I wanted to an AI in plain words, I made a game in 3 days, and getting it to launch cost $45.

This is part 1 of the dev log for Sperm Race, a silly sperm-racing game.

Google Play: Sperm Race
Web version (itch.io): Sperm Race — it came out on itch.io first, then on Google Play.

"Let's make an easy game" took me all the way back to sperm

My goal at the start was simple: "Just make an easy game."

But the more I thought about what "easy" means, the more primal my ideas got. A game with one rule. A game that needs no explanation. A game everyone already knows. Following that line all the way back, I ended up at sperm. Swim forward, reach the egg, done. When you think about it, it's the one race every one of us has already won once.

The moment that thought hit me, I laughed out loud. "Wait, this is funny."

That one reaction set the direction. Not a serious game, but a goofy one that makes you smirk the second you see it.

I didn't know what a game engine was

I had never written code. I didn't know engines like Unity or Godot existed, let alone what they do.

So I started without one. I told Claude (Sonnet) in Korean, "I want to make a game like this," and what came back was a single HTML file that ran right in the browser. Later I wrapped that same file into an Android app and put it on Google Play. Building by describing what you want to an AI instead of writing code yourself has a name now: vibe coding. Looking back, starting without knowing anything was actually faster. No engine to install, nothing to study, and I could play it on day one.

The first prompt: "I want to make a game where a sperm swims to meet the egg"

That one sentence produced the first version. A sperm appeared on screen, and I could move it with my finger.

The problem was the tail. It was stiff as a stick, more matchstick than sperm. So the second thing I said was:

"Add a wave to the tail."

On the left is the stiff tail from the first version; on the right is the next version with the wave. Just making the tail wiggle finally made it look like a living sperm. That's how the main character was born.

Three days of adding, cutting and adding again

After that I couldn't stop. Every time I played a build, the next idea showed up. If it came to mind, I added it. If it didn't work, I cut it. Then I added again.

"Make a map." Now there was somewhere to swim.
"Add obstacles too." Once there was something to dodge, it became a game. This is today's Adventure mode.
"Add sperm racing, like real car racing." A Racing mode with 3 laps around a track.
"Make a mode where they run on their own like horse racing, and I place obstacles." Pick a sperm to root for and help it win with obstacles. This is Derby mode.
"Make a survival mode where you run away, with cancer as the motif." Dodge cancer cells in a maze and survive for 1 minute 30 seconds.

The file dates left in my Downloads folder show how fast it went. I got the first HTML file in the early hours of August 19, and by the next afternoon I had downloaded a new version 16 times. That's "fix this → download the new file → play" four or five times every half day. Meanwhile the code grew from 47 KB to 149 KB. By August 21 I was already taking screenshots for the store.

Graphics and sound effects, all in code

There isn't a single image file in this game. The character, backgrounds, tracks and mazes were all drawn in code by Sonnet.

From left: Adventure, Racing, Derby, Survival. The sperm is one ellipse and a wiggling line, the track is a thick curve, and the maze is glowing straight lines. For a silly game, that simplicity actually worked.

Same with sound effects. There are no sound files; Sonnet synthesized the sounds in code. The only audio file in the game folder is free background music from Pixabay.

The testers' first reaction: "That's so original"

Before launch I showed it to testers. What came back was: "That's so original."

The idea that started with "wait, this is funny" wasn't funny only to me.

Here's what was in the game at launch:

4 modes: Adventure (120 stages), Racing (3 laps), Derby, Survival (last 1 minute 30 seconds)
13 languages
Controls: drag, arrow keys/WASD, gamepad

Multiplayer with friends (up to 10 players in Derby, 4 in the other modes) came later, in an update after launch.

So what did it cost? $45

Item	What I used	Cost
Code	Claude Pro subscription (Sonnet)	$20 (one month)
Graphics	Drawn in code	$0
Background music	Free tracks from Pixabay	$0
Sound effects	Made in code	$0
Launch	Google Play developer registration	$25 (one-time)
Total		$45

I use Claude Max 20× now, but Sperm Race was built entirely on the Pro plan. It was done within a month, so I only paid for one month.

For comparison, if you run a small game through the AI game cost calculator, the standard stack (image and music AI plus Claude Max) comes out at $128–181. Sperm Race came in at about 25–35% of that.

Next time

So far it looks like "AI made a game in 3 days, easy." But the real struggle came after. Building took 3 days; fixing bugs took 14.

Next: 3 days to build, 14 days to fix bugs — why AI pokes at the wrong code when you ask it to "find the bug," and how I ended up finding bugs myself and having the AI fix them.

Originally published at tokensave.app.

Using Opus 5.5 Claude Code with Microsoft Foundry in VS Code

Taswar Bhatti — Mon, 05 Oct 2026 12:17:07 +0000

In my Claude Opus 5.5 for C# developers post I called Opus 5.5 from my own code: the Anthropic.Foundry SDK, Entra ID, and the effort parameter. This time the code calling Opus 5.5 isn't mine. It's Claude Code, running in my terminal and in VS Code, pointed at my Foundry resource.

Microsoft already has a good step-by-step setup guide for Claude Code on Microsoft Foundry in VS Code, so I'm not going to repeat it. If you've never connected Claude Code to Microsoft Foundry, start there. This post is about what happens after it connects, when the model on the other end is Opus 5.5: how to make sure you're actually talking to it, which dial to turn, and where the tokens go when you're not looking.

Why Opus 5.5 Changes the Claude Code Setup

A quick recap of what shipped, and what each change means inside Claude Code:

It's 40% cheaper than Opus 5. $4/M input, $20/M output, and $0.20/M cache reads. Claude Code sessions are mostly re-read context, so the cache price matters more than the headline price.
Medium effort is the default. Claude Code respects that: Opus 5.5 starts at medium, while most other models start at high. You can raise it per session.
Thinking is always on. There's no thinking toggle to hunt for. Effort is the only dial, and MAX_THINKING_TOKENS does nothing on Opus 5.5.
Output is 30%+ faster. You'll feel this in the VS Code panel on long diffs.
More refusals. The expanded safety classifiers apply in Claude Code too. If your repo is security tooling, expect some declines.

The catch: none of this matters if Claude Code isn't using Opus 5.5. And by default, on Foundry, it isn't.

The Short Setup (and the Line Most Guides Miss)

Install Claude Code CLI

Deploy Claude Opus 5.5 from the Foundry Model Catalog to your Foundry resource, same as any other model. Give yourself the Azure AI User or Cognitive Services User role on that resource (either one is enough to call the model), and run az login. No API key: Claude Code falls back to the Azure credential chain when no key is set, so your az login session is the credential. If you plan to use the API Key then you will need to set your env key or the json file to have the ANTHROPIC_FOUNDRY_API_KEY rather.

Remember to install the Extension in VSCode

VSCode Claude

Now the part I care about. Instead of setx-ing environment variables or pasting them into every shell, put them in ~/.claude/settings.json. Both the CLI and the VS Code extension read that file, so you configure Foundry once:

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "your-foundry-resource-name",
    "ANTHROPIC_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5"
  }
}

The two model lines do different jobs, and you want both:

ANTHROPIC_MODEL makes Opus 5.5 the model for the session. This is the line most guides miss. On Foundry, Claude Code's default model is Sonnet 4.5, not Opus. Setting only ANTHROPIC_DEFAULT_OPUS_MODEL remaps the opus alias, but you keep chatting with Sonnet until you switch.
ANTHROPIC_DEFAULT_OPUS_MODEL makes the opus alias (in /model, subagent definitions, and so on) resolve to your Opus 5.5 deployment instead of an older Opus you may not have deployed.

Use your actual deployment name if it isn't claude-opus-5-5. ANTHROPIC_FOUNDRY_RESOURCE takes the resource name only, not a URL. If you need a private endpoint or custom domain, use ANTHROPIC_FOUNDRY_BASE_URL instead. Don't set both.

In VS Code, install the Claude Code extension and add one line to your VS Code settings.json so it doesn't push you toward an Anthropic login:

{
  "claudeCode.disableLoginPrompt": true
}

Then check it, in the terminal or the VS Code panel: /status

You're looking for the API provider set to Microsoft Foundry, your resource name, and your Opus 5.5 deployment as the model. If the model line says Sonnet, the ANTHROPIC_MODEL line isn't being picked up.

Dev takeaway: "Deployed in Foundry" and "used by Claude Code" are two different things. /status is the five-second check that tells you which one you've got.

Effort: The Dial You'll Actually Touch

In the SDK post, effort was a property on the request. In Claude Code it's a session setting, and there are three ways to set it:

/effort sets it for the current session: /effort high, /effort low, or /effort auto to go back to the model default.
The /model picker has an effort slider (left/right arrows). Whatever you pick there is remembered per model, so Opus 5.5 can keep its own setting.
CLAUDE_CODE_EFFORT_LEVEL in the environment or the env block wins over everything else, including /effort.

That last point is easy to trip over: put CLAUDE_CODE_EFFORT_LEVEL in your settings while testing, forget about it, and later /effort high appears to do nothing. For interactive work, leave the env var out and use /effort or the /model slider. Save the env var for scripted or CI runs where you want one fixed level. (The top-level effortLevel user setting also won't apply to Opus 5.5, which is one more reason to use the per-model slider.)

Here's how I map the levels to Claude Code work:

Effort	What I use it for in Claude Code
`low`	"Explain this file", rename a symbol, write a commit message
`medium` (default)	Everyday feature work, bug fixes, writing tests
`high` / `xhigh`	Multi-file refactors, framework migrations, tricky concurrency bugs
`max`	Rarely, and only for the session: `/effort max` when `xhigh` clearly isn't getting there

Thinking tokens are billed as output, at $20/M. Raising effort for the whole day costs you; raising it for one hard problem and dropping back is cheap.

Where the Opus Bill Hides

Pinning everything to Opus 5.5 is easy. The surprise is how much else then runs on Opus 5.5 too.

Background tasks. Claude Code does small jobs behind the scenes, such as generating session titles. On the Anthropic API those go to Haiku. On Foundry they run on your primary model, which is now Opus 5.5, unless you deploy a Haiku model and point ANTHROPIC_DEFAULT_HAIKU_MODEL at it.

Subagents. When Claude Code fans work out to subagents (the Explore agent searching your repo, for example), each one uses the main conversation's model unless something says otherwise. That's Opus 5.5 for every file search. If you deploy a cheaper model, route subagents to it:

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "your-foundry-resource-name",
    "ANTHROPIC_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6"
  }
}

Again, those are deployment names, so use yours. Opus 5.5 does the planning and the edits in the main conversation; a cheaper model does the searching and reading.

Only reference models you actually deployed. Foundry has no startup model check, so Claude Code won't warn you about a typo or a missing deployment when it launches. You find out mid-session. While drafting this post, a subagent in my own session died with:

The model claude-sonnet-4-5 is not available on your foundry deployment.

It had tried a model my resource didn't have. Everything else kept working, which is exactly why it's easy to miss. If you only deployed Opus 5.5, leave the Sonnet and Haiku lines out and accept that everything runs on Opus.

Dev takeaway: with one deployment, every token is an Opus token. That can be fine, since Opus 5.5 is cheaper than Opus 5, but make it a decision rather than a surprise.

Make the $0.20 Cache Reads Count

Cache reads at $0.20/M are the best part of the Opus 5.5 price sheet, and Claude Code is a cache-heavy workload: every turn re-sends your instructions, CLAUDE.md, and the conversation so far. Caching is on automatically. Three things decide whether you actually get those cheap reads:

The default cache lifetime on Foundry is 5 minutes. Step away for coffee, come back, and the next turn re-writes the whole context at full price. For long sessions with gaps, set ENABLE_PROMPT_CACHING_1H to 1 in the env block. One-hour cache writes are billed at a higher rate than 5-minute writes, so this pays off for long, stop-and-start sessions, not quick ones. (Recent Claude Code versions also have CLAUDE_CODE_PROMPT_CACHE_TTL=1h, which applies only to the main conversation.)
Pick your model at the start and stay on it. Switching from Opus 5.5 to Sonnet and back mid-session throws away the cache each time.
Set up MCP servers before you start. Some Azure-hosted deployments reject Claude Code's tool search, so it loads all MCP tools up front. Then connecting or removing an MCP server mid-session resets the cache.

Refusals Show Up in Your Editor Now

In the SDK post I made refusal handling a required pattern, because a refusal is a successful HTTP response with no answer in it. In Claude Code you don't write that handler, but you'll still see the result: Opus 5.5 declines more requests than Opus 5 in the biology, cybersecurity, and reasoning-extraction categories.

If you work on security tooling (scanners, fuzzers, detection rules), you'll occasionally hit a decline on a request that looks reasonable to you. Rephrase the request with the defensive context, or do that piece by hand. Don't try to engineer around the classifier; on a work resource, that's a conversation for your security team, not a prompt trick.

Checking What You Actually Spent

Inside Claude Code, run /usage (/cost is an alias). On Foundry you get the session's token counts, a prompt cache line, and an estimated dollar cost at list price. That estimate is great for "did turning effort up just double my session?", and the cache line tells you whether the 5-minute or 1-hour setting is actually working.

It is not your bill. The real numbers live in Azure Cost Management for the Foundry resource, at whatever price your agreement gives you. Anthropic's usage dashboards don't see Foundry traffic at all. For per-developer numbers across a team, Claude Code can export usage through OpenTelemetry. Tagging the Foundry resource (team=..., env=dev) makes chargeback easier.

When Something's Off

These are the Opus 5.5-specific problems I'd check first:

Symptom	Likely cause	Fix
`/status` shows Sonnet, not Opus 5.5	Only `ANTHROPIC_DEFAULT_OPUS_MODEL` is set	Add `ANTHROPIC_MODEL` with your Opus 5.5 deployment name
`model ... is not available on your foundry deployment`	An alias or subagent points at a model you didn't deploy	Deploy it, or remove that line from `env`
`/effort` seems to do nothing	`CLAUDE_CODE_EFFORT_LEVEL` is set and overrides it	Remove the env var for interactive use
Bill higher than `/usage` suggests per session	Background tasks and subagents running on Opus 5.5	Deploy Haiku/Sonnet and set the Haiku and subagent model lines
Every turn after a break is expensive	5-minute cache lifetime expired	`ENABLE_PROMPT_CACHING_1H=1` for long sessions
VS Code panel asks you to sign in to Anthropic	Login prompt not disabled	`"claudeCode.disableLoginPrompt": true`
`401` / `403`	Missing role, or `az login` in the wrong tenant	Azure AI User or Cognitive Services User on the resource; `az login --tenant <id>`

One more: there's no /logout on Foundry. To switch accounts or tenants, change your az login.

Bottom Line

Opus 5.5 is the first Opus worth testing as your all-day default in Claude Code. It's cheaper, faster, and medium effort is enough for most work. But "default" has to be deliberate on Foundry. Set ANTHROPIC_MODEL, confirm it with /status, decide whether background tasks and subagents should really run on Opus, and turn effort up only for the problem that needs it.

Configure it once in ~/.claude/settings.json, and the CLI and VS Code both pick it up. Then keep an eye on /usage for a week before you roll it out to the team.

Building AI features in C#? I write about practical, no-hype prompt engineering and Azure AI patterns for .NET developers. Check out Prompt Engineering for .NET Developers — free, no Python required. You can also subscribe for more posts.

AGENTS.md vs CLAUDE.md: Claude Code reads both now, just not at once.

Manpreet Singh — Mon, 05 Oct 2026 12:00:31 +0000

Two files, one job: tell a coding agent about your repo. For a year the answer to "which one?" was simple. Claude Code read CLAUDE.md. Almost everything else read AGENTS.md. If you used both kinds of tool, you kept two files and watched them drift apart.

On 18 September that changed. Claude Code 2.1.277 started reading AGENTS.md natively. Some of the top results for this question still say it doesn't.

Claude Code reads AGENTS.md now. But only when there's no CLAUDE.md, and a single CLAUDE.local.md switches it off.

Here's the current picture, the one setup that works on every version, and the part none of the comparison posts measure: what the file costs you on every turn, and what's missing from it.

The short answer

From Anthropic's memory docs, as of today:

Claude Code reads AGENTS.md only when there's no CLAUDE.md. That means no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder you're working in or any folder above it. Your personal ~/.claude/CLAUDE.md doesn't count, so that still loads alongside.
The trap. Add a CLAUDE.local.md for your own notes and your team's AGENTS.md quietly stops loading. Nothing tells you.
You can change the rule. In /config, "Project instructions" can be set to read either file (the default), both, or only CLAUDE.md.
Nearly everything else reads AGENTS.md. Codex, Cursor, Copilot, Jules, Amp, Windsurf, Zed and more, per the list at agents.md. Gemini CLI is the odd one out: it reads GEMINI.md unless you point it elsewhere.

One more thing to check before any of that applies to you:

$ claude --version
2.1.257 (Claude Code)

That's the CLI on my own machine. It's older than 2.1.277, so here an AGENTS.md on its own would be invisible to Claude Code, whatever the docs say. If your team updates at different speeds, some of you are reading the file and some aren't.

Which one should you use?

Only Claude Code touches the repo? Keep CLAUDE.md. There's no AGENTS.md in this website's repo, because Claude Code is the only agent that works on it. A second file would be a second thing to keep true.

Several tools, or a team on mixed versions? Make AGENTS.md the one real file, and make CLAUDE.md a single line:

@AGENTS.md

That's the setup Anthropic's docs recommend. Claude Code pulls the file in and never loads it twice, and it works on old versions too, because it doesn't depend on the new support at all. Two details that trip people up: an import inside a code fence is silently ignored, and on Windows a symlink instead of an import needs admin rights or Developer Mode, and Claude's own edit tools refuse to write through one.

What not to do is keep two hand-maintained copies. On the long-running GitHub issue asking for AGENTS.md support, it's a recurring complaint: the copies drift, and each agent ends up following different rules.

What the file costs you

Whichever file you pick, it's read at the start of every session and then sent again on every turn, like everything else in the conversation. So its size isn't a one-off. Here's this repo's CLAUDE.md, checked by a small linter:

$ npx -y github:manpreet171/bridle agents CLAUDE.md
Linting CLAUDE.md

  ✔ 2 runnable command block(s)
  ✘ does not say how to install / set up
  ✘ does not say how to run the tests
  ✔ how to build or run it
  ! 3 angle-bracket field(s), e.g. <slug> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ✔ 12 prohibition(s) — the agent knows where the edges are
  ✔ size: 916 words ≈ 1474 tokens, re-sent every turn

FAIL — 2 problem(s). Your agent is reading this file on every run.

The two failures don't apply here: it's a static site with no install step and no test suite. A general linter checks for a general project, so read it as a list of questions, not a verdict.

The size line is the one that matters. About 1,500 tokens, on every turn. This project has run about 9,300 turns of Claude Code, so this one file accounts for roughly 14 million tokens, sent at the cheaper cached rate. That's an estimate, but the shape isn't. I measured where the rest of a session's tokens go in a separate post.

Does a longer file make the agent worse at following it? Anthropic's memory docs say to aim for under 200 lines, and its best-practices guide warns that bloated files get ignored. The research is more mixed. An ETH Zurich study found files written by people raised success rates slightly, files generated by an AI lowered them, and both added roughly 20% to cost. A study of 1,650 Claude Code sessions found no measurable effect of length on following one simple rule. Length isn't proven to hurt. It is proven to cost.

What's missing from it

A file can be long and still not say the thing you actually need it to. Here's the same project from the other direction: not what the file says, but what I keep typing to the AI because the file doesn't say it.

$ npx -y toldya --dry
toldya · 13 sessions (1 Aug – 5 Oct) · 975 of your messages · 58 corrections

You keep telling your AI:
   1.   7×  keep it simple   (6 sessions)
   2.   3×  Don't confuse me   (3 sessions)

And 8 times you told it to try or check again: its first go missed.

916 words of rules, and neither line is in there. The two corrections I gave most often in this repo had never been written down, so every new session started without them and I typed them again.

That's the real answer to "which file?". The name decides which tools read it. What's in it decides whether it was worth reading.

What belongs in it

What it can't work out on its own. The odd build command, the folder that looks unused but isn't, the deploy that happens on push.
The edges. What it must never touch, and what needs a person. Those are the lines that prevent damage.
What you keep correcting. If you've typed it three times, it's a rule. Write it in your own words.
Not documentation. Explaining the codebase is what the code is for. Every paragraph the agent could have read in the repo is a paragraph you pay for on every turn.
Not generated filler. The ETH study's sharpest finding was that AI-written context files made results worse. Write it yourself, briefly.

Check your own

$ claude --version                             # 2.1.277 or later to read AGENTS.md
$ npx -y github:manpreet171/bridle agents CLAUDE.md   # or AGENTS.md
$ npx -y toldya --dry                          # what you keep repeating

Both tools are free, read only your own files, and change nothing unless you say yes. bridle reads the instruction file; toldya reads your Claude Code history.

This is how we set agents up for clients. One short file that says what the agent can't guess and where the edges are, checked against what people actually keep correcting. Not a template, and never a generated one.

Sources: every terminal block is a real run in this website's repo on 5 Oct 2026, the toldya one trimmed by one line (a link). Loading rules are from Anthropic's memory docs and the Claude Code changelog for 2.1.277. Tool support is from agents.md. The studies are arXiv 2602.11988 and arXiv 2605.10039.

Originally published at singhlabs.dev.

Claude Code says it's done. Check the diff, not the paragraph.

Manpreet Singh — Mon, 05 Oct 2026 11:58:50 +0000

"Done. All tests pass, and nothing else was touched." You read it, it's late, you merge.

Claude Code's own issue tracker is full of what happens next. A test suite whose total quietly changed from 4,992 to 4,966 before the "ALL PASSED". Six tests marked skip. A project reported 100% complete that an audit put nearer 60%.

The summary isn't a lie. It's written to explain the work, and nobody explains the parts they'd rather you didn't see.

Asking the agent to try harder doesn't fix that. Checking does. Here's what goes wrong, what doesn't work, and what happened when I held this site's own Claude Code summaries up against their real diffs.

The four ways "done" isn't done

Read enough of those issues and the same four shapes keep coming back:

The tests got easier, not the code better. A test skipped, an assertion loosened, a test command narrowed to the ones that pass. The suite is green because there's less of it.
The count got reframed. A failure becomes "a flaky timeout". A smaller total gets reported as everything passing.
Intent got ticked off as work. A to-do marked done because it was planned, or a stub counted as a feature.
A file changed and never got mentioned. The quietest one, and the one that bites three days later.

It's common enough to measure. A study of 20,574 real agent sessions found inaccurate self-reporting was about 23% of all the misbehaviour it caught, and a growing share over time. Anthropic's own best-practices guide says it plainly: Claude stops when the work looks done.

What doesn't work

Asking "did you actually do it?" The same model that wrote the summary checks it with the same blind spot. In one report it said yes three times.

A rule in CLAUDE.md. One reporter had a 250-line file, memory notes and hooks, and still got false "done"s. In another, the rule against skipping tests was right there in context and got broken anyway. A rule asks. A check doesn't need to.

What I found in my own sessions

Most writing on this describes the problem. Almost none of it shows a real summary next to its real diff, so I did that with two pieces of work Claude Code finished on this website today. For each one I took the summary it gave me at the end, word for word, and ran it through plumb, a small tool that holds a summary against git diff and prints only what doesn't match.

The first was publishing a blog post, along with a fix to a script:

$ plumb check summary.md --base a12ccca
plumb — 9 files changed, 1 named in the summary

changed but never mentioned  (read these first)
  · .assetsignore modified
  · LOG.md modified
  · assets/blog/og-claude-code-token-usage.png added
  · baggage/index.html modified
  · blog/claude-code-token-usage/index.html added
  · blog/feed.xml modified
  · blog/index.html modified
  · sitemap.xml modified

8 things the summary did not tell you.

Eight flags. I went through them one by one. Seven were things the summary did describe, just not by file name: it gave the post's URL, called the image "the social card", and said "that folder is now excluded from publishing" instead of naming .assetsignore.

One wasn't. baggage/index.html: Claude added a link to a product page while publishing the post, and the summary never said so anywhere. Harmless, as it happens. But I only know it's harmless because I looked.

The second was a batch of SEO fixes: 21 files changed, and again only one named by path. This time the summary described all 20 others in categories, "19 pages and the sitemap", and every one checked out. plumb also flagged two files as "mentioned but not changed", which the summary had only referred to. Nothing was missing.

So, across two real summaries: 30 files changed, 2 named by path, one change genuinely left out. No skipped tests, no removed guards. Neither summary lied. One still hid a change, and I'd have merged it without blinking.

What actually works

Read the diff, not the paragraph. /diff in Claude Code, or git diff --stat, shows every file that changed. The summary is a guide to the diff, never a replacement for it.
Make it end with a file list. Ask for every file it touched, by path, at the end of each task. My two summaries were noisy to check because they talked in categories. A list turns "did it mention everything?" into a mechanical question.
Check on every stop, automatically. Claude Code's Stop hook receives the agent's last message, so a check can run the moment it says it's finished. trust issues is a free plugin that does exactly that: the same four checks, every time, with nobody remembering to run them.
Count the tests, before and after. If the number went down, ask why before you read anything else.
Get a second pair of eyes that didn't do the work. Anthropic's guide suggests a separate verification step that checks nothing outside the task changed. A fresh session doesn't share the first one's reasons for skipping a test.

Try it on yours

Save the agent's last message to a file, then:

$ npm install -g github:manpreet171/plumb
$ plumb check summary.md                # against your uncommitted changes
$ plumb check summary.md --base main    # against a branch or commit

Exit code 1 means it found something, so it works as a CI gate too. What it won't do, so you don't over-trust it:

It matches names literally. A URL or a category doesn't count as a mention, which is why my first run flagged seven things that weren't really missing. Ask for a file list and that noise goes away.
It can't tell whether the code works. It finds what was left out of the story, not bugs. Run the tests for that.
Its "quiet cuts" are patterns. It spots a removed assertion or an added .skip, not every possible way to weaken a check.

This is how we build agents for clients. Nothing gets called done because the agent said so. Every run ends with what changed, and something other than the agent checks it.

Sources: the plumb output is a real run (plumb 1.1.0) on 5 Oct 2026, against the exact end-of-task summary Claude Code gave for each piece of work, with the summary file's path shortened. The second run's output is described rather than shown because it lists 20 files. Incidents are from the linked GitHub issues on anthropics/claude-code; the session study is arXiv 2605.29442; hook and review guidance is from Anthropic's best practices and hooks docs.

Originally published at singhlabs.dev.

Where your Claude Code tokens actually go. Output is 0.2%.

Manpreet Singh — Mon, 05 Oct 2026 11:38:18 +0000

You hit the usage limit before lunch. So you do what everyone online says: make the AI talk less. Ban the "Great question!", cut the summaries, install one of the skills that trims its replies.

I wanted to know where the tokens actually go, so I counted. Not estimated. Counted, from the transcripts Claude Code already keeps on your machine: every session still on mine, 173 of them, about 60,000 turns.

Everything Claude wrote back to me was 0.2% of the tokens. The rest was my own session, fed back in.

That number is real, but it isn't the whole story either, because most of those re-sent tokens are cheap ones. This post is both halves: where the tokens go, what they really cost, and the few things that actually move the number.

The count

Here's the summary across every project, straight from the terminal:

$ baggage --all
baggage — 173 sessions, all projects, 60,454 turns

  before you typed anything              75k  tokens
    system prompt, every tool schema, every skill, CLAUDE.md.
    paid again on all 60,454 turns = 4.5B tokens, 17% of the bill,
    whether you called any of it or not.

  conversation you can see             27.8M  tokens
  what the API billed                  26.0B  tokens

  a 934x gap. Some of it is the fixed cost above; the rest
  is everything you picked up being re-sent on every later turn.

  output tokens           56.6M   0.2%
  re-sent context         25.3B   97.5%   <- the bill

Two lines matter. Output (every reply, every line of code Claude wrote, its thinking included) is 56.6 million tokens. Re-sent context is 25.3 billion. That's roughly 450 to 1.

I'm not the first to see this shape. A GitHub issue on Claude Code found the same thing in 30 days of someone else's transcripts, and a dev.to post measured 0.5% output across 32 sessions. Different people, different work, same picture. What none of them show is which things in a session cost the most, and what any of it means for the bill. That's the rest of this post.

Why it works like that

The model has no memory between turns. Every time you press enter, Claude Code sends the whole conversation again: the system prompt, the tool definitions, every file it read, every command output, every reply so far, and then your new message.

Think of a suitcase you have to carry up every flight of stairs. Pack a brick on the second floor of a 200-floor building and you carry it up 198 more flights. A 4,000-token build log that lands at turn 12 of a 200-turn session isn't 4,000 tokens. It's 4,000 sent 188 more times.

So the cost of anything in a session isn't its size. It's its size times the number of turns it stays.

Caching makes it cheaper, not smaller

This is the part most guides get half right. Claude Code caches the conversation, and Anthropic prices a cache read at a tenth of normal input (a twentieth on Opus 5.5, a fortieth on Fable 5.1). Output costs five times input. So 97.5% of the tokens is not 97.5% of the money.

I priced my own split at those published rates, with the one-hour cache a subscription uses. Output comes to 7 to 14% of the cost, depending on the model. Re-reading and re-caching the session is the other 86 to 93%.

Less dramatic than 0.2%. Still the opposite of what "make it talk less" assumes.

On a Pro or Max plan you never see dollars, you see a limit. Anthropic's cost docs say re-read history still draws on your usage, at the cached rate, so a one-line question late in a long session draws usage for the whole session. How heavily a cached token counts against the limit isn't published. I've seen people online insist it's full weight, and others insist it's free. Nobody I found has shown either, so I'm not going to guess.

The floor you pay before you type

That first block of the output is the one nobody shows you. Before you've typed a word, a session already carries the system prompt, the built-in tools, the descriptions of every skill you've installed, your CLAUDE.md files and anything else that loads at start. A typical session on my machine starts at about 75,000 tokens.

It rides along on every turn. Across all my sessions, that floor alone is 17% of everything billed, whether I used any of it or not. It's also the one line you can fix in thirty seconds: every paragraph of CLAUDE.md you don't need is paid again on every turn of every session, and so is the description of every skill you never call.

The heaviest things I carry

Here's one project, this website, with the list of what's costing the most rent, trimmed for length:

$ baggage
baggage — 13 sessions in singhlabs, 9,307 turns

  before you typed anything              84k  tokens
    system prompt, every tool schema, every skill, CLAUDE.md.
    paid again on all 9,307 turns = 779.0M tokens, 18% of the bill,
    whether you called any of it or not.

  output tokens            7.1M   0.2%
  re-sent context          4.2B   98.0%   <- the bill

  HEAVIEST THINGS YOU ARE STILL CARRYING
  (rent = its size x the turns it stayed in context)

   304.4M   19.4%  3769x  assistant reply
   282.4M   18.0%  1376x  your message
   244.2M   15.6%  1415x  claude-in-chrome · browser_batch
    54.6M    3.5%   145x  WebSearch
    25.6M    1.6%   275x  claude-in-chrome · javascript_tool
    21.5M    1.4%    17x  claude-in-chrome · get_page_text
    14.9M    0.9%   159x  Agent

Two things surprised me.

Claude's own replies are the biggest line: 19.4%. Not because they were expensive to write. Writing all of them was part of the 0.2%. They're expensive because each one stays in the session and is sent again on every turn after it. So the "talk less" skills aren't wrong. They're right for the wrong reason: a short reply saves you far more in re-sends than it ever cost to write.

Browser automation is close behind: 15.6%. And that's the text alone: page contents, element lists, logs of each click. baggage doesn't count images, so every screenshot rides along on top of that figure, uncounted. A session that clicks through a website carries a stack of pictures of it.

What actually moves the number

Ranked by what the counts above say, not by what's easiest to write about:

Start fresh between unrelated tasks. /clear drops everything you've been carrying, and Anthropic's docs say it costs nothing. The brick stays on floor two.
Lower the floor. Uninstall skills you don't use, keep CLAUDE.md to what Claude can't work out on its own, and run /context once to see what loads before you type.
Keep big output out of the main session. Send a long log to a file and search it, instead of printing it into the chat where it's carried to the end. Hand noisy exploration and browser work to a subagent, so only its answer comes back.
Don't break the cache mid-session. Per the caching docs, switching model, changing effort, turning on fast mode or changing MCP servers can throw it away, and then the whole session is written to cache again at the higher rate. Decide those at the start.
Shorter replies, for the right reason. Ask for the answer without the essay. It helps, because the essay gets carried.

On a paid plan, /usage now shows which skills, subagents and MCP servers used your allowance. Worth a look before changing anything.

Count your own

The tool that printed everything above is called baggage. It's free, it reads the transcripts already on your machine, and nothing leaves it. The name on npm belongs to someone else, so install it from the repo:

$ npm install -g github:manpreet171/baggage
$ baggage          # this project
$ baggage --all    # every project

What it doesn't tell you, so you don't over-read it:

Tokens, not dollars. The totals are the exact counts the API reported. Pricing them is your model and your plan.
Item sizes are estimates. The list ranks things with a rough four-characters-a-token ruler, the same ruler for everything. The totals above it are exact.
Only what's still on your machine. Claude Code keeps about 30 days of history by default.
One heavy user. These are my numbers. Yours will differ, which is the point of running it.

This is how we work. Measure what's really happening before changing anything, then change the thing the numbers point at. It's the same rule we use when an AI system we build for a business starts costing more than it should.

Sources: both terminal blocks are real baggage runs on my own machine on 5 Oct 2026, the second trimmed to whole lines for length. Prices and cache multipliers are from Anthropic's pricing page; the cost split weights my exact token counts by them. Cache and usage behaviour is from Claude Code's costs and prompt caching docs.

Originally published at singhlabs.dev.

MCP Ecosystem Week 41: When Developer Choice Outpaces Your Allowlist

curatedmcp — Mon, 05 Oct 2026 10:54:39 +0000

Originally published at curatedmcp.com/blog/week-2026-41

MCP Ecosystem Week 41: When Developer Choice Outpaces Your Allowlist

The MCP ecosystem continues its steady climb toward ubiquity in AI-assisted development. This week brought no new catalog entries, but the view counts tell a story platform teams need to hear: developers are gravitating toward integrations that connect their existing tool chains—GitHub, OpenAI, Figma, Anthropic—directly into their coding agents. The question isn't whether your team will use these servers. It's whether you've decided to govern them or discovered them in an audit six months from now.

This Week in MCP

No new servers were added to the CuratedMCP catalog this week. That pause is worth noting. It suggests we're entering a consolidation phase, where platform teams are working through the governance implications of the 80 risk-classified servers already available rather than chasing new additions.

Use this breathing room. If you haven't audited which MCP servers your developers are actually running across Claude Code, Cursor, Windsurf, and GitHub Copilot, now is the time. Shadow usage—servers spinning up without your knowledge—is the governance blind spot we see most often in platform teams shipping AI coding tools at scale.

On the Radar

The five most-viewed servers this week reveal clear patterns in how developers want to extend their AI agents:

GitHub Copilot MCP (98k views) and GitHub MCP (76k views) dominate the list. The first wraps Copilot's own intelligence; the second manages repositories, issues, and workflows directly. Governance consideration: these servers integrate with your source control and CI/CD. Ensure your SSO and RBAC policies enforce per-repository or per-org limits. Token logging matters here—agent-driven GitHub operations can generate audit trails you'll need.

OpenAI MCP (87k views) gives agents direct access to GPT-4o, DALL-E, Whisper, and embeddings. Before allowlisting, clarify your org's multi-model policy. Are developers expected to route through Claude, or can they call competing LLMs? Token spend visibility becomes critical when agents can invoke multiple model providers.

Figma MCP (82k views) opens design files and component tokens to agents. Supply-chain risk consideration: your design system and brand assets flow through this connection. Confirm Figma's auth model (OAuth 2.0, service tokens) aligns with your identity provider. Audit who can access what.

Anthropic Claude MCP (76k views) nests Claude within Claude—useful for specialized reasoning tasks, but introduces recursive LLM calls and compounding token cost. If you're not tracking sub-agent behavior, this server will be a surprise on your monthly bill.

Governance Take

Here's what we're hearing from platform teams in the field: allowlist drift. A security team approves MCP servers for Cursor in Q4. By Q1, developers are spinning up the same servers in Claude Code, and the approval matrix hasn't kept pace. Different IDEs, different enforcement points, no single source of truth.

Add to that the TokenShield gap: most organizations have spend visibility for their primary model provider (usually Anthropic), but the moment agents start invoking GitHub APIs, Figma endpoints, and sub-agent LLM calls, the cost picture fragments. You're paying for tokens. You're also paying for API calls downstream that don't show up in your Claude bill.

The play: build your allowlist once, enforce it everywhere. Map your MCP servers to teams, risk classifications, and cost centers. Log every server invocation—not just token count, but which user, which IDE, which repository access, which external API was called. TokenShield gives you spend visibility and measured, opt-in optimization across your deployed servers. But visibility only matters if your governance layer can act on it.

Govern MCP usage across your team with CuratedMCP — or scan your own stack free at https://www.curatedmcp.com/auditor.

Move a Claude Code task to a teammate without sharing a login

Almast — Mon, 05 Oct 2026 10:47:20 +0000

A coding task often stalls because the person who wrote the brief cannot run it right now. Passing a provider login to someone else blurs who executed the work and what access they had. A better handoff transfers the task specification, then lets the next person work with their own authorized tools.

Here is a small template for doing that. It works as a Markdown issue even if your team never adopts a task platform.

The handoff file

# Task: Add an empty-state message to the projects list

## Outcome
When the API returns zero projects, show:
“No projects yet. Create one to get started.”

## Scope
- Change the projects-list component and its focused tests.
- Keep loading and API-error states distinct from the empty state.
- Do not change the API or create a project automatically.

## Starting point
- Repository: <repo URL>
- Base branch or commit: <exact ref>
- Relevant paths: <component>, <tests>
- Command to run: <project's documented test command>

## Access
- Author may write the brief and review the result.
- Executor uses their own repository and Claude Code access.
- Executor stops if either permission is missing.
- No provider credentials, session cookies, or personal tokens are included.

## Evidence to return
- Commit or pull-request URL
- Files changed
- Test command and actual output
- Screenshot only if captured from the running app
- Any untested behavior or remaining risk

## Acceptance
A reviewer checks the empty, loading, and error states,
then accepts or returns the task with specific changes.

The exact repository paths and command belong in the real task. Leaving them vague forces the executor to rediscover scope and makes review harder.

A worked handoff

Suppose Maya prepares this brief but has no time to implement it. Arun has authorized access to the repository and uses his own Claude Code account. Maya gives Arun the task, not her login. Arun checks out the stated base ref, inspects the three UI states, edits the component, and runs the repository's documented tests.

His delivery should identify the changed files and real commit, name the exact test command and result, and say whether he performed a visual check. Those details must come from the actual run. “Tests passed” is not acceptable unless the executor ran them and can identify the command that produced the result.

Maya then reviews the diff and evidence. If the empty message appears while the API is still loading, she returns the task with that finding. If it meets the acceptance criteria, she accepts it. Delivery and acceptance are different events.

What the separation buys you

This pattern gives a team shared AI execution capacity through transferable work while keeping each person's account and permissions separate. The author owns scope and acceptance criteria. The executor owns the work performed with their own authorized environment. The reviewer owns the verdict.

A task system can preserve those boundaries and make the handoff easier to inspect; Wagglet's discussion of AI task handoffs is one example. The same discipline still matters in a plain issue tracker.

It does not solve missing access, unclear requirements, or unreliable tests. When those are absent, improve the brief or stop the run. Borrowing another person's credentials is not a fix.

This article was drafted with AI assistance.

The best CLAUDE.md rules are hiding in your chat history.

Manpreet Singh — Mon, 05 Oct 2026 10:33:16 +0000

Quick question. What's the one sentence you've typed to your AI more than any other?

Not the one you think you type. The one you actually type.

I didn't know mine either. So I went back through three months of my own Claude Code history and counted. It was "keep it simple." 42 times, across 38 different sessions. And that rule was written nowhere my AI could read it.

Every correction you type and don't write down dies with the session.

If you use Claude Code, Cursor or Codex every day, you have your own "keep it simple." This post is about finding it, writing it down, and checking whether it stuck. At the end there's a one-minute way to see your own top line.

The 42 times

This is a real run on my real history, 143 Claude Code sessions between July and September:

toldya · 143 sessions (2 Jul – 25 Sept) · 6379 of your messages · 528 corrections

You keep telling your AI:
   1.  42×  keep it simple   (38 sessions)
   2.  29×  dont complex this   (18 sessions)
   3.  15×  dont assume   (15 sessions)
   4.  13×  i dont want later on   (12 sessions)
   5.   9×  dont think too much   (9 sessions)

And 71 times you told it to try or check again: its first go missed.

Numbers one and two are the same complaint, one with my typo. Together that's 71 times I told my AI to stop overbuilding. The last line is a different 71: "try again" and "check again", which isn't a rule, just an honest measure of how often the first attempt missed.

This isn't a complaint about Claude. It's genuinely good at what I use it for. It's that every one of those corrections was a rule I never wrote down.

Why your AI forgets everything

A coding agent doesn't remember yesterday. Each session starts from zero. What you corrected on Tuesday afternoon is gone by Wednesday morning.

The one thing it reliably reads at the start of every session is a small text file in your project called CLAUDE.md. Other tools use AGENTS.md, same idea.

Think of it as a sticky note on the monitor for a brilliant new colleague with amnesia. They wake up every day with no memory of you. The note is the only thing that carries over. If it's not on the note, it's gone.

Everyone says "just add a rule"

Every CLAUDE.md guide gives the same advice: when your AI repeats a mistake, add a rule for it. It's good advice. I agree with it.

The gap is that you don't notice you're repeating yourself. My "keep it simple" came up in 38 sessions, across different projects, weeks apart. Each time it felt like a one-off. I never once thought "this is the thirtieth time." Repetition across days is invisible from inside the day.

That's why none of my top five were in my CLAUDE.md. Not laziness. I just had no idea.

Why grep lies to you

Claude Code keeps your history on your own machine, as text files in ~/.claude/projects. So the obvious move is to search it. I searched for "keep it simple." It said 747. The real number was 42.

Same history, same phrase. 18 times too big.

The files hold everything, not just what you typed: the AI repeating your words back, summaries written when a chat gets long, tool output, logs and briefs you pasted. Counting properly means keeping only the short messages you typed, dropping questions and pastes, and grouping the ways you say the same thing. "Don't complicate it", "dont complex this" and "dont comlicate that" are one habit, not three.

So I built a tiny thing

It's called toldya, as in "I told you so." A free command-line tool that does the counting above, then offers to write the results onto the sticky note for you. One command, Node 18 or newer, no account:

npx toldya --all

It reads your Claude Code history on your machine, shows the list above, and asks about each one: y adds it as a rule, n skips it, e lets you reword it first. Nothing is written without a yes. Or pick by number:

npx toldya --all --add 1,2,3 --to CLAUDE.md

Added 3 rules to CLAUDE.md. Run toldya again in a week to see if they stuck.

## Things I kept repeating
- Keep it simple.
- Dont complex this.
- Dont assume.

Yes, it keeps my typo. They're your words. Fix them with e.

Did it stick?

Adding a rule doesn't mean the AI follows it. The file can be read perfectly and the rule can still not land.

So toldya remembers which rules it added, and when. Run it again a week later and each rule shows how often you said it before it went in, and how often since. If "keep it simple" drops from 42 to near zero, the rule works. If it keeps climbing, the wording isn't landing.

I can't show you a "since" number yet. The tool is a few days old, so there is no "since" to count. That's the honest state of it.

And because it made me laugh: npx toldya --all --card draws your top repeats as a picture, on your machine, with a "Save as PNG" button. Nothing is uploaded.

Mine. Drawn earlier the same day, one "keep it simple" ago.

The part I got wrong

I had a bigger idea first: a team version that reads a project's pull-request review comments, finds what reviewers keep writing, and turns that into rules.

Before building it, I pulled the last 1,000 review comments from each of Next.js, React, Astro, Supabase and Cal.com, and ran the same counting on them. Almost nothing repeated as a rule. The top "repeats" were "This is changed now" (13 times), "Fixed in the latest commit" (9) and "Thanks for the test" (7). That's conversation. Reviewers write about the code in front of them.

People correcting their own AI are the opposite: the same handful of sentences, in the same words, for months. So the team version got dropped.

What it doesn't do

Claude Code only, for now. Codex stores history elsewhere and I haven't tested it on real files, so I'm not claiming it.
It matches words, not meaning. It won't connect "use the logger" with "why is there a console.log here?". That would need a model, and I wanted it small, free and local.
It sees only the history you have. Claude Code keeps about 30 days by default.
It needs a pattern. A phrase must appear three times, in two different sessions. New to Claude Code? You may get "nothing repeated yet." Good result.
It sends nothing anywhere. Only your own messages are read. No account, no telemetry, no network calls.

Try it in a minute

The safe version only shows the report and changes nothing:

npx toldya --all --dry

The code is at github.com/singhlabsdev/toldya, MIT, zero dependencies. If it finds something useful, a star helps other people find it. And I'd genuinely like to know your top line. Mine is "keep it simple." 42 times.

This is how we build. Small tools that count what really happened instead of guessing, run on your machine, and ask before they change anything. The same rule goes into the agents we build for businesses.

Sources: every terminal block is a real toldya run on my own Claude Code history on 25 Sep 2026. The 747 is a plain grep of the same files that day. The review-comment figures come from the last 1,000 comments per repo, fetched from the GitHub API the same day.

Originally published at singhlabs.dev.

I Audited My AI's Briefing File. It Had Turned Into a Diary.

Ted — Mon, 05 Oct 2026 10:13:25 +0000

Coding agents like Claude Code read a plain-text briefing file before they do anything else. Mine is called CLAUDE.md, and it sits in the home directory of the small server I run my automation on. It tells the agent who I am, what's installed, which services run where, what the cron jobs do, and the handful of rules I don't want broken. It loads into every session, whatever I'm working on.

I'd been adding to it for six months. After two model releases in ten days, I ran Claude Code's new prompt audit on it (/checkup prompt-audit). The audit reads your instruction files and flags text written for older models: ALL-CAPS warnings, "think step by step", rigid scripts. It writes a report and a patch and changes nothing until you say so.

I expected it to find shouting. It found almost none. What it found instead was more useful, and it changed how I think about the file.

What I expected

The audit's main checklist is about prompting habits that used to help and now hurt. Older models needed forceful instructions to follow anything reliably, so people wrote IMPORTANT: and NEVER everywhere. Current models follow instructions closely and literally, so the same shouting makes them over-apply a rule and behave rigidly in situations it was never meant for.

My file had exactly one of those: a rule in capitals about using a site-specific command-line tool only for the site it was built for. The fix was to say it at normal volume and keep the reason: "the other sites have no command center." Two other spots used capitals for emphasis, but they stated facts, not rules, so the audit left them alone.

That was the whole outdated-prompting section of the report. One finding.

What it actually found

A quarter of the file was history.

The cron section was meant to list my scheduled jobs. Over the months its header had grown into an 880-word paragraph about what I'd removed: which jobs were cut on which date, why, where the backups went, the traffic numbers that made me drop three sites, which repository was left untouched. Every entry had been accurate when I wrote it. None of it was something the agent needed to do anything.

Several facts had quietly gone wrong.

The file listed the Gemini CLI at a specific path. It wasn't installed there, or anywhere.
It gave a version for one of my agent gateways that was two months out of date.
It listed four API keys in my environment file. There were more than a dozen.
It listed the tools wired into my voice assistant and was missing one.

None of these would cause a crash. They'd cause a confident wrong answer: the agent telling me "use the Gemini CLI at this path" and spending a turn finding out it isn't there.

One rule was a security habit dressed as documentation.

Under my blog's repository it said: "Git push requires the token in the remote URL", followed by the exact command to paste a GitHub token into the repo's config. That was true once, because nothing else was set up to handle the login. But it's an instruction, so every time the agent pushed, it would write a live credential into a plain-text file. I'd already cleaned that exact pattern out of two other repos a few weeks earlier, and the instruction file was still teaching it.

The flip

I'd been treating CLAUDE.md as documentation, a notebook about my server that the agent happens to read.

It isn't documentation. It's a prompt that runs every session, and every sentence in it is a sentence the model acts on.

Once you see it that way, the findings stop looking like housekeeping:

History in a prompt isn't a record, it's noise the model has to work around. "Removed on 2026-08-25, backup at this path, 82 days of rank history pruned" reads as context to me. To a model that treats everything in its instructions as relevant, it's a pile of half-relevant facts competing with the ones that matter. The one useful rule hidden in that paragraph ("these jobs were removed on purpose, so check before adding them back") was the part hardest to find.
A stale fact in a prompt isn't out-of-date documentation, it's a wrong instruction. A wiki page with an old version number just sits there. The same line in a prompt gets acted on.
A how-to in a prompt isn't a note, it's a standing order. "Put the token in the URL" stopped being a description of how I once got a push to work. It became the default.

The audit's own guide puts it in one line: the job is to find "specific instructions that no longer fit", not to make prompts shorter. My file didn't have an old-model problem. It had the problem every long-lived config file gets: it kept accumulating and nothing ever removed anything.

What I changed

The patch had nine hunks, each tied to one finding, so I could take or skip them one at a time. I took all of them.

Moved the history out. The 880-word paragraph went verbatim into a separate cron-history.md that isn't loaded automatically. The cron header is now one line with the job count and a pointer: "read it before re-adding a removed job." The schedule itself stayed.
Fixed the facts. Dropped the Gemini line, corrected the version, listed the real key names, and added the missing voice-agent tool.
Kept rules, dropped stories. Several sections had a current rule with an incident wrapped around it, like "Seen on 2026-09-22: a session started at 14:48 picked up the new package but still ran the old code…" The rule (restart the process after a config change, because clearing the session isn't enough) stayed, with its reason. The timestamped story went.
Fixed the token rule properly, not just the wording. I set git to use the GitHub CLI's existing login for pushes (gh auth setup-git), confirmed a dry-run push worked, and only then replaced the line with "plain git push, never put a token in the remote URL." Then I checked every local repo for a token in its remote URL. There were none.

Two smaller things went too. I removed account-balance figures from a list of fallback models, since balances drift and nothing on the machine could confirm them. I also moved four skills for a framework I'd stopped using out of the global skills folder: their descriptions were loading into every project.

The file went from about 3,700 words to 2,760. That wasn't the goal, just a side effect of removing what didn't belong.

What the audit left alone, and why that matters

The audit has an explicit list of things it must not delete, and it followed it. It kept:

the rules that carry a reason, like "don't re-optimize this page's title, the low click rate comes from the search results layout, not the title";
two identical copies of a scaffold file in two project folders, because they agree;
my one-line note that I prefer short, direct answers, because that's context about me, not an outdated trick.

That restraint is the part I'd have got wrong doing this by hand. My instinct with a bloated file is to cut it hard, and a hard cut removes exactly the lines that only I could have written: the reasons. The model can work out how to be thorough by itself. It can't work out why I don't trust a particular page's metrics.

If you keep one of these files

Some things I'm doing differently now:

Write the rule, not the story. If a line describes something that happened, ask what the agent should do differently because of it, and write that sentence instead.
Give history its own file. A changelog is valuable. It just shouldn't load into every session. Point to it from the briefing file, and the agent can read it when it's relevant.
Check facts against the machine, not your memory. Paths, versions and key names drift silently. The audit caught four because it checked them, not because they looked wrong.
Read every how-to as a standing order. If you wouldn't want the agent to do it every time without asking, it doesn't belong in the file as an instruction.

The file is shorter now, but that isn't the improvement. The improvement is that everything left in it is something I actually want the agent to act on.

How To Write Playwright tests in minutes with Playwright MCP and Claude Code

Jakob Norlin — Mon, 05 Oct 2026 09:44:22 +0000

This article was originally published on the Endform blog.

By the end of this walkthrough you'll have a single Playwright test that Claude Code wrote against your live app, that you've reviewed in two passes, run repeatedly to check for flakiness, and committed next to the plain-English scenario it came from. The trick that makes it trustworthy: the agent reads locators off the running page through the Playwright MCP server instead of guessing them from your source code.

You need four things installed before step 1, so start there.

Before you start

Confirm all four of these first. Skipping one is the most common reason step 1 fails.

Node.js 20 or newer. Check with node --version. The MCP server launches through npx, so Node is required no matter how you installed Claude Code.
Claude Code, installed and signed in. Check with claude --version.
A Playwright project. You need playwright.config.ts at the repo root. No project yet? Run npm init playwright@latest to scaffold one.
An app to test. Local dev server or staging URL, either works. Playwright can start it for you when the config says so.

Got all four? Connect Claude Code to a browser.

The problem this setup solves

Here's a failure pattern you've probably lived through: Claude Code writes an end-to-end test, it passes locally, you merge, and CI goes red a day later on what looks like flakiness. The test was wrong from the start, it just had no way to show it.

The reason is where the locators came from. Reading your components without ever opening the app, an agent spots a button with a class like .btn-primary and writes a selector against it. Then a component library or some runtime logic rewrites that class on its way to the DOM, and by the time the browser renders, the selector points at a hashed string, a restructured node, or nothing. Nobody caught it because nobody ran the test against a real page. CI is the first thing that does.

Compare the two ways the same button gets targeted:

// Hallucinated: guessed from training data, does not exist on this page
await page.locator("#submit-btn").click();

// Grounded: read from the accessibility tree Claude Code can see
await page.getByRole("button", { name: "Place order" }).click();

Anthropic's Model Context Protocol is what closes the gap. The Playwright MCP server hands Claude Code a live browser: it can open the app, walk the accessibility tree, and build locators out of the roles and names the page actually exposes. It's working from a structured snapshot rather than a screenshot, which keeps the locators stable and the token cost low, because the model reasons over text it can already read. Same model, better inputs. Nothing here is a capability upgrade, only an access one.

Step 1: Register the Playwright MCP server

A single command wires the server into Claude Code:

claude mcp add playwright -- npx -y @playwright/mcp@latest

That entry gets saved to your local config, and the server process spins up the next time you open a session. -y skips the install confirmation npx would otherwise wait on, and @latest grabs the newest published build so you're not stuck on a stale cache.

By default this is a personal, single-project entry. Working on a team? Add --scope project, which writes the same config to a .mcp.json at the repo root so everyone shares one server without redoing setup:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Don't trust it until you've checked it. Run claude mcp list and look for ✔ Connected. Immediately after adding, you may catch a ✘ Failed to connect while npx is still pulling the package in the background; run the command again a few seconds later and it usually clears.

If retrying doesn't clear it, the problem is elsewhere. Claude Code runs the server as a subprocess in its own environment, and that subprocess can't always resolve npx the way your interactive shell does. Homebrew-installed Node on macOS is the usual culprit. Give it the absolute binary path instead of trusting PATH:

claude mcp remove playwright
claude mcp add playwright -- $(which npx) -y @playwright/mcp@latest

Run claude mcp list once more and wait for ✔ Connected before continuing.

Connected only means the process is alive. It doesn't prove Claude Code can actually drive a browser yet. Open a session and call the tool by name, otherwise Claude Code might reach for a Bash command instead of the MCP server:

Using Playwright MCP, open [your app's local URL] and tell me the page title and the first heading you see.

If it answers with something concrete off the page, not a hedge and not a generic description, the tool works. That answer is coming from a live snapshot rather than memory, which is the entire reason you connected it.

These commands are current as of August 2026. MCP tooling changes quickly, so if a command here stops matching what you see, check the official Playwright MCP repo. Server verified and driving a browser, the next hurdle is login.

Step 2: Get past the login wall with storage state

Nearly every test worth writing sits behind authentication. A checkout, a settings screen, an admin panel, all of them dead ends if the agent can't clear the sign-in page.

The MCP server has no idea about your suite's existing auth. It either carries its own browser profile across sessions or, in isolated mode, boots logged out every time. Either way it's disconnected from however your tests currently authenticate.

Fix it by launching the server with a session already loaded:

npx @playwright/mcp@latest --isolated --storage-state .auth/user.json

--isolated holds the profile in memory rather than writing it to disk, so every session starts fresh. --storage-state reads a saved authenticated session from a file, and anything that changes mid-session gets thrown away at the end. But that file has to exist first.

Playwright's auth docs suggest a dedicated setup test that signs in and saves the session:

import { test as setup } from "@playwright/test";

const authFile = ".auth/user.json";

const password = process.env.TEST_USER_PASSWORD;
if (!password) {
  throw new Error("TEST_USER_PASSWORD is not set");
}

setup("authenticate", async ({ page }) => {
  await page.goto("https://your-app.example.com/login");
  await page.getByLabel("Email").fill("test-user@example.com");
  await page.getByLabel("Password").fill(password);
  await page.getByRole("button", { name: "Log in" }).click();
  await page.waitForURL("**/dashboard");
  await page.context().storageState({ path: authFile });
});

Wire it to run automatically by adding a setup project in playwright.config.ts that the browser projects depend on:

projects: [
  { name: 'setup', testMatch: /auth\.setup\.ts/ },
  {
    name: 'chromium',
    use: { storageState: '.auth/user.json' },
    dependencies: ['setup'],
  },
],

Run it once:

npx playwright test --project=setup

When it finishes, .auth/user.json holds a live authenticated session, and auth.setup.ts is now part of the suite, so login logic lives in exactly one place.

Worth doing if your app allows it: create a throwaway test user through an API or seed script before login and tear it down after. Claude Code pokes at the app while it explores, and a disposable account keeps it from mutating a shared login someone else is on.

With the file in place, re-register the server so it loads that session:

claude mcp remove playwright
claude mcp add playwright -- npx -y @playwright/mcp@latest --isolated --storage-state .auth/user.json

For teams, mirror it in .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state",
        ".auth/user.json"
      ]
    }
  }
}

For messier auth flows, Endform's Playwright MCP guide goes deeper on this.

Now that Claude Code browses as a logged-in user, it's time to write the prompt that turns a described flow into a committable test.

Step 3: Build the prompt in three parts

This step is where a shippable test and a throwaway one diverge. Rather than one rambling paragraph that asks for a test and hopes, split the prompt into three parts that each do one job.

Part one is environment setup: the app-specific facts the agent can't deduce on its own.

The website under test is at https://staging.yourapp.com.
You're already logged in as a test user through the storage state configured earlier.
The test user's cart currently holds one item, a placeholder t-shirt priced at $24.99.

Part two is the scenario, phrased the way you'd brief a teammate, not as pseudocode:

# Guest checkout with a saved card
1. Open the cart page.
2. Proceed to checkout.
3. Confirm the shipping address shown is the default one.
4. Select the saved Visa card ending in 4242.
5. Place the order.
6. Confirm the order confirmation page shows an order number and the correct total.

Keep this as a markdown file in the repo next to the tests it drives, not buried in a chat log. Playwright Test Agents work the same way: a planner writes the scenario as markdown, and a later step compiles it into code. Splitting the two into separate, reviewable artifacts is worth carrying over here.

This part is also the one nobody on the team can write better than you. The environment facts are just facts, and the system prompt below is boilerplate you reuse everywhere. The scenario is the only part carrying judgment: does the address get confirmed before payment, does the saved card matter more than a fresh one, is the confirmation total worth asserting or is a loaded page enough? An agent can't rank those. Someone who knows the product has to.

Part three is the system prompt, the standing rules that ride along on every test and describe what "good" looks like, not just what to do:

You are a Playwright test generator.
Explore the app using the Playwright MCP tools before writing any code, don't generate steps from assumption alone.
Prefer getByRole, getByLabel, and getByTestId locators over CSS selectors or XPath.
Don't add manual waitForTimeout calls, rely on Playwright's built-in auto-waiting and retrying assertions instead.
Group related steps with test.step for readability in the trace viewer.
Assert on outcomes a user would actually see, not on incidental implementation details.
Save the finished test to the tests directory, run it, and keep iterating until it passes.

You don't have to write this cold. Debbie O'Brien, a longtime Playwright advocate and ex-member of Microsoft's Playwright team, keeps a public set of prompt files for exactly this, a better base than reinventing it.

Stacked together, this is the full message to Claude Code:

You are a Playwright test generator.
Explore the app using the Playwright MCP tools before writing any code, don't generate steps from assumption alone.
Prefer getByRole, getByLabel, and getByTestId locators over CSS selectors or XPath.
Don't add manual waitForTimeout calls, rely on Playwright's built-in auto-waiting and retrying assertions instead.
Group related steps with test.step for readability in the trace viewer.
Assert on outcomes a user would actually see, not on incidental implementation details.
Save the finished test to the tests directory, run it, and keep iterating until it passes.

The website under test is https://staging.yourapp.com.
You're already logged in as a test user through the storage state configured earlier.
The test user's cart currently holds one item, a placeholder t-shirt priced at $24.99.

# Guest checkout with a saved card
1. Open the cart page.
2. Proceed to checkout.
3. Confirm the shipping address shown is the default one.
4. Select the saved Visa card ending in 4242.
5. Place the order.
6. Confirm the order confirmation page shows an order number and the correct total.

The proof this prompt works is watching the agent call the MCP tools to explore before it writes any test code. A "explore first" instruction only counts if the agent obeys it. Three parts, three jobs, one message. Next, the generation itself.

Step 4: Let it generate the test

One look at the page isn't where Claude Code stops. It keeps navigating and reading through the MCP server until it has actually seen every element the scenario names. That's what separates this from feeding a model a plain-English description and hoping.

Watch a run and the sequence is plain: open the page, click through the scenario's steps, read back what each returned, and only then start writing assertions. It writes the spec last, runs it, and keeps tweaking until it passes instead of handing you untested code.

A real example: on a logout scenario, two headings both matched "Secure Area," so Playwright threw a strict mode violation, because a locator meant to act on one element matched several. Claude Code read the error, diagnosed it, and appended exact: true so the locator demanded the full heading text rather than a substring. That correction landed in the same pass, no nudge from the developer.

A checkout with a cart, saved card, and confirmation page runs the same loop, step by step, until green. Here's a second flow to show it's not a one-off.

Endform's guide to shipping quality end-to-end tests with Playwright MCP has a scenario worth reusing: check that a newly created team shows up in an activity log. Sign in, confirm a signup event is already logged, create a team, confirm the new event lands. Endform walks through the scenario and the review, not the code, so here's a plausible test around that flow, in the shape Claude Code would generate it against a live app:

import { test, expect } from "@playwright/test";

test("new team activity appears in the activity log", async ({ page }) => {
  await test.step("open the activity log", async () => {
    await page.goto("https://staging.yourapp.com/dashboard");
    await page.getByRole("link", { name: "Activity" }).click();
  });

  await test.step("confirm the signup event is already logged", async () => {
    await expect(page.getByText("you signed up")).toBeVisible();
  });

  await test.step("create a new team", async () => {
    await page.getByRole("button", { name: "Create a new team" }).click();
    await page.getByLabel("Team name").fill("QA Playground");
    await page.getByRole("button", { name: "Create team" }).click();
  });

  await test.step("confirm the new team event appears in the log", async () => {
    await expect(page.getByText("you created a new team")).toBeVisible();
  });
});

Notice how deliberate the file is. Every link and button name is text Claude Code read off the page. The test.step blocks track the scenario one to one, so a failure drops you straight on the broken step. No manual waits anywhere, because the retrying assertions cover timing.

You end up with a runnable file that clears its first run more often than not, precisely because each locator was verified against the page before a line got written. That still isn't the same as a good test, which is what step 5 is for.

Step 5: Review it in two passes

Passing once doesn't earn a test a place in the suite. Run two review passes, because they catch different things: one on the code, one on the meaning.

Pass one is the code. Read it and ask if you'd have written it this way. Generated tests tend toward the baroque, redundant checks, extra steps, logic that folds down to less, and trimming that is usually the first win. Hold the locators to the priority you set (getByRole and getByTestId over CSS or XPath), swap out anything brittle, and make sure each assertion proves something a user would notice rather than just confirming an action didn't throw. The test.step groupings should read the way a person would narrate the flow.

Pass two is the one no linter will ever do for you, and it's the one that matters more. Put the scenario next to the finished test and ask whether the thing being verified still matches what the scenario meant, not just whether it's green. Tests drift here quietly. On that logout test, Claude Code noticed the login banner showed once and got eaten by the stored session, so it retargeted the assertion to the permanent heading before wrapping up. Useful that it caught it, but it happened during generation, not review, and that's the point: next time it might not, and this pass is your backstop.

The first draft gets much faster; the judgment moves into refinement. And that judgment, what the product does, what risk you're covering, what the scenario is really asserting, is yours to bring. Both passes done, one last check remains.

Step 6: Verify, then commit

The commands below use this tutorial's logout test as the example. A test that passed while being generated still hasn't earned your trust. Run it again, clean, outside the generation loop:

npx playwright test tests/logout.spec.ts

A single green run tells you almost nothing about reliability. Fire it several times in a row:

npx playwright test tests/logout.spec.ts --repeat-each 5

--repeat-each reruns the same test N times in one invocation. It's among the fastest ways to smoke out a test that's green most runs and red occasionally, the exact flakiness that tends to surface only once it hits CI.

Repeats clean? Commit the test together with the markdown scenario behind it:

git add tests/logout.spec.ts tests/scenarios/logout.md
git commit -m "Add logout test with scenario spec"

Committing them together keeps intent attached to implementation. Whoever reads the diff later sees what the test was meant to prove, not just the assertions.

One thing to check before that first commit: your .gitignore. A freshly scaffolded Playwright project ignores playwright/.auth/, its default spot for storage state. But this setup writes to .auth/ at the repo root, a different path the default rule doesn't cover, which means a live authenticated session can slip into history unnoticed.

Add the right path first:

echo ".auth/" >> .gitignore

That one line keeps the session out of your repo history by intent rather than luck.

Verified, stable over repeats, and committed alongside its scenario, the test is a dependable addition. What gets harder from here: longer flows, data that shifts between runs, and auth beyond a plain login form.

Where this workflow falls down

Trust comes from being straight about where Claude Code struggles, not just where it shines. Four things break it fairly predictably.

Long multi-step flows. The longer the flow, the more the agent loses the thread, since each step starts from a fresh snapshot rather than the whole sequence before it, and long MCP sessions dropping browser context is a known issue. Splitting the flow into smaller scenarios and stitching them later holds up better.

Data that changes between runs. The agent tends to assert against whatever it saw at generation time, a timestamp, an order ID, a count, and those move on the next run. Assertions last longer when they target something stable: a confirmation state, a completed action, the presence of a result, not the exact value from one run.

Deep conditionals. While generating, the agent only travels one branch, one role, one account state, one flag. Branches it never walks stay invisible to it. Prompt each branch on its own, or write the conditional logic yourself, rather than expecting one pass to find every path.

OAuth and third-party auth. Usually the first wall you hit. Redirects out to Google, Microsoft, or any external identity provider leave your app, and the agent's control loop isn't built to follow through the handoff. One developer automating GitHub's OAuth earned a temporary IP ban for it, and other providers can react to automated logins the same way, which makes this genuinely fragile. The move is to authenticate in a separate setup step, save the session with storageState, and generate against an app that's already logged in.

None of these shrink the workflow's value. They just mark where a scenario needs prep before you hand it over.

What comes next: keeping the suite fast

We opened with a test that looked done and broke in CI regardless. Claude Code explored the real app through Playwright MCP, checked what was on the page, and produced a test you reviewed, verified, and committed.

That changes the economics of test creation. Once a trustworthy test costs minutes instead of hours, teams write more of them, and a bigger suite brings its own problem. Those tests still run in CI, and as the count climbs, the bottleneck moves from writing tests to running them fast without flakiness.

Endform runs every Playwright test on its own isolated machine in parallel, which keeps suite duration predictable no matter how many you add.

I Gave My AI Coding Agent 5 Skills and It Stopped Rewriting the Same Files

The Android AI Architect — Mon, 05 Oct 2026 09:22:38 +0000

Most AI coding setup advice stops at "install Claude Code." That's the easy part.

The hard part is what happens three weeks in: the agent keeps rewriting the same helper file, forgets the project conventions, writes code without tests, and you spend more time reverting than shipping.

Skills are just instructions your agent reads

An agent skill is a markdown file with a name, a description, and a procedure. No plugin system, no framework, no build step. Drop it in a directory the agent watches and it applies that procedure when the task matches.

The difference is between hoping the agent does the right thing and telling it exactly what right means for your codebase.

The five that changed my workflow

feature-plan - before writing any code, produce a plan: what changes, which files, what could break. Skipping this is how you get 400 lines of code nobody wanted.

test-write - write the test first, then make it pass. The skill encodes the pattern and makes the agent follow it instead of retrofitting tests onto code it already wrote.

code-review - a review pass with a specific checklist. Catches the things you skim past at 1am: unhandled null, a missing await, an N+1 query that won't matter until you have 10,000 users.

bug-fix - reproduce, isolate, fix, verify. In that order. The most common waste in agent-assisted debugging is changing code before you can reproduce the bug, then changing it again.

refactor - safe refactoring with verification at each step, so cleanup doesn't become an outage.

Wiring it up

Drop the folder in. Point your agent at the skills directory. For Claude Code the config is a JSON file; for Cursor there's a .cursorrules file. Both are in the pack.

The real payoff isn't the individual procedures. It's that they're consistent, so your agent stops improvising a different approach every session.

What this doesn't replace

Type hints, tests, and code review. Skills make your agent more consistent, not more competent. A skill that says "write good code" is useless; a skill that says "before editing any file, read CLAUDE.md and follow the existing naming convention" changes behavior.

Be specific or be ignored.

The one that gets skipped

Nobody wires up their MCP servers and skills on day one. They install the editor, write a prompt, feel productive, and never revisit it.

The setup takes twenty minutes. Not doing it costs you the same three weeks of drift every three weeks, forever.

I packaged these five skills plus a Cursor config, project rules, and starter templates into the MCP Vibe Coder Pack:

MCP Vibe Coder Pack - https://baradigitaltools.gumroad.com/l/mcp-vibe-coder-pack

There's also a bundle that adds 20 freelance prompts and a remote jobs dataset, if you're trying to turn the shipping into income:

Vibe Coder Power Pack - https://baradigitaltools.gumroad.com/l/vibe-coder-power-pack