Advertise with Us|Sign Up to the Newsletter

Spring Spotlight 2026 is live and we’ve rounded up the top updates for developers. See what's new for the HubSpot Developer Platform!

Ship faster with AI coding tools like Cursor, Claude Code, and Codex. Build MCP-powered AI connectors, run serverless functions with support for UI extensions, and use date-based versioning to streamline roadmap planning.

📢 Important: WebDevPro is Moving to Substack

We’ll be moving WebDevPro to Substack soon.Once the transition is complete, all future issues will come from packtwebdevpro@substack.com.

To make sure the newsletter continues reaching your inbox, please add this address to your contacts or whitelist it in your mail client. No other action is needed. You’ll keep receiving WebDevPro on the same weekly schedule.

Substack will also give you more control over your subscription preferences if you decide to adjust them later.

Welcome to this week’s issue of WebDevPro!

In this article, he walks through a practical system for making agentic coding reliable, drawing from firsthand experience and real constraints. It’s thoughtful, grounded, and immediately useful if you’ve ever felt your AI sessions spiral after a few dozen turns.

Before we get into it, here’s a sneak peek of this week’s highlights:

👋 Hi! It's Alex!

Let's imagine this scene. You open a new chat. You describe the feature.
For twenty minutes, the AI is cooking.
Good code, too.

Around turn 30, it starts fixing a bug it introduced three turns ago.
It imports a module you deleted. It references a file path you renamed ten messages back.

You're not building anymore. You're managing.

Feeding corrections back in, watching the agent regenerate the same broken pattern with different variable names.

This is the death loop, and it's not a prompt quality problem.
Session length is the variable that matters.

I created a simple system to ship simple changes with agents (almost) autonomously, and in this article, I want to show the why and how I built it.

The Anthropic Claude Code docs say it directly: a single debugging session can generate tens of thousands of tokens, and when the context window fills up, Claude starts forgetting earlier instructions and making more mistakes.

A 10-turn session is fine.
A 50-turn session drifts.
At 80 turns, you're spending more time correcting than building, and at that point, you might as well have written the code yourself.

Birgitta Böckeler, writing in the Martin Fowler engineering series, said it after months of daily agentic coding: the longer a session gets, the more hit-and-miss it becomes, regardless of the rigor in prompting.

Agents make assumptions about your codebase.
Most are correct.

When one is wrong and goes unchallenged, the agent builds on it. Then you build on the agent's code. Three levels in, the wrong assumption is load-bearing.

Documented example from the same Martin Fowler series: an agent diagnosed a Docker build failure as an architecture mismatch and changed the Docker settings. The actual cause was node_modules built for the wrong platform. Classic error. Any developer who's been burned by it once would catch it in 30 seconds. Without that catch, the agent would have spent hours deepening a wrong diagnosis into increasingly creative fixes.

Agents are confidently wrong with no built-in correction mechanism.

Two agents, one working directory:

git add . && git commit -m "fix auth middleware"

git add . && git commit -m "refactor API layer"

# agent-2 just committed agent-1's half-finished auth changes

Every agent sees every other agent's uncommitted changes.
Files get overwritten mid-edit.
One agent's npm install blows away another's node_modules.

Commits become incoherent.

Open two Cursor tabs on the same repo and give it 20 minutes. Productive at first. Then a mess that takes longer to untangle than doing the work sequentially.

So how do we make this consistently okay?

A PRD is not a 47-page corporate artifact. It's a short document you write before opening your coding tool. Its job: prevent assumption stacking before the agent gets a chance to start.

I always use these for medium-to-large features.

It’s similar to the Harper Reed workflow published in February 2025.

It got traction because it was concretely different from how most people worked at the time. His first move is a conversational spec session where an LLM asks him one question at a time until the idea is fully elaborated.

The prompt:

"Ask me one question at a time so we can develop a thorough,

step-by-step spec for this idea. Each question should build

on my previous answers, and our end goal is to have a detailed

specification I can hand off to a developer. Let's do this

iteratively and dig into every relevant detail. Remember,

only one question at a time."

Here's the idea: [IDEA]

When the questions run dry:

"Now that we've wrapped up the brainstorming process, can you

compile our findings into a comprehensive, developer-ready

specification? Include all relevant requirements, architecture

choices, data handling details, error handling strategies,

and a testing plan so a developer can immediately begin

implementation."

Output goes to spec.md. The whole thing takes 15 minutes.

The Doozy founders shipped a 300k-line Next.js monorepo with 3 to 6 parallel agents at any given time. They do it differently. They built a /discussion command that runs before any code is written. Subagents explore the codebase and look up dependencies. The command produces no edits, only a written summary in .context/context.md. Other agents reference that file.

# spec.md

## Problem

What you're building and why, in one sentence.

## Constraints

What the agent should NOT touch.

What patterns to follow.

## Files to read

src/auth/middleware.ts

src/routes/users.ts

prisma/schema.prisma

## Definition of done

npm run typecheck && npm test passes with no new failures.

150 to 300 words. The format matters less than writing it before you start prompting.

One test: if you can't describe what the feature should not do, keep writing.

Where it lives: spec.md in the repo root, a context section in CLAUDE.md, or .context/context.md. Pick whatever your tool loads by default.

Watch out for CLAUDE.md files that balloon. The Claude Code docs are explicit about this: bloated CLAUDE.md files cause Claude to ignore your actual instructions. Treat it like code. Prune it. If you added a rule and Claude's behavior didn't change, the rule is noise. Delete it.

The task planner converts a spec into a sequenced list of bounded tasks. Harper Reed uses a reasoning model for this step, and I do too. Not for code, just for decomposition.

A possible prompt:

Draft a detailed, step-by-step blueprint for building this project.

Then break it down into small, iterative chunks that build on each

other. Go another round to break it into small steps. Review and

make sure the steps are small enough to implement safely, but big

enough to move the project forward.

Make sure each prompt builds on the previous prompts, and ends with wiring things together. There should be no hanging or orphaned code that isn't integrated into a previous step.

[SPEC]

Output goes to prompt_plan.md. Then he asks for a todo.md checklist the execution agent can check off. That's how state persists across sessions without re-reading the full conversation history.

Anthropic describes this as the orchestrator-workers pattern: a central LLM breaks down tasks, delegates them to worker LLMs, and synthesizes results. The reasoning is that you can't always predict the subtasks, especially in code, where the number of files and the nature of changes depend on the task.

A task is agent-sized if it fits in one context window, produces a green lint/typecheck, and has a binary done/not-done signal.

These will send your agent spiraling:

❌ "Refactor the authentication system"

❌ "Add tests"

❌ "Improve performance"

These work:

✅ "Add a useAuth hook to src/hooks/auth.ts that wraps the

existing authService and exposes login, logout, and

isAuthenticated. Update src/components/LoginButton.tsx

to use it. Done when: npm run typecheck passes."

✅ "Add a POST /api/users/:id/preferences endpoint to

src/routes/users.ts that validates the body against

UserPreferencesSchema and writes to user_preferences.

Done when: the new route test passes."

Specific file. Specific interface. Specific check.

The Pane team scores every plan on a 1-10 confidence scale for one-pass implementation success. Below 8, iterate. Their rules: no aspirations, only instructions. No open questions (if something is unresolved, stop and research first). And if a plan is too big for one session, split it. Oversized plans are where the death loop starts.

Here are the 3 concepts I use the most to make parallel agents work.

Once you have a dependency-ordered task list, tasks that don't share files can run at the same time. The thing that used to block this was filesystem collisions. The fix has been sitting in git since 2015.

One command. Sub-second. The new directory is a fully independent working tree on its own branch, sharing the same .git object store. No re-cloning. Disk cost is just for your working files.

git worktree add .worktrees/feature-auth -b session/feature-auth

Each agent gets a clean branch, zero visibility into other agents' uncommitted changes, and full ability to run tests independently.

When done:

git worktree remove --force .worktrees/feature-auth

The branch stays if there are commits to review. Otherwise, it's gone.

This primitive from 2015 that nobody cared about until this year now underpins several independent tools:

All of these solutions are great, but in reality, to get started, none of them are required.
A task file and a terminal per worktree gets it done.

Every agent session starts with the task description from the plan, the specific files listed in the task, and the relevant section of the spec.

# Task: Add useAuth hook

Files to read:

- src/services/authService.ts (existing service to wrap)

- src/hooks/ (existing hook patterns to follow)

- src/components/LoginButton.tsx (file to update)

Constraints: Do not modify authService.ts.

Done: npm run typecheck passes, LoginButton uses useAuth.

The agent can't drift into adjacent work because adjacent work isn't in its context. It either completes the task or fails clearly.

Ten 20-turn sessions instead of one 200-turn session.

TypeScript strict mode, npm run typecheck, and lint are your coordination layer across parallel agents. An agent's work isn't done until the checks pass. This prevents a type error in one worktree from silently propagating when branches merge. This scales across languages.

Try to enforce this per task: implement, typecheck, lint, format, and fix all issues before proceeding. After all tasks finish, a reviewer subagent reruns everything and verifies that the plan was completed.

Human review stays in the loop for architectural decisions, ambiguous acceptance criteria, and code that's syntactically valid but semantically wrong. Automated checks catch everything describable as a rule. They don't catch everything.

Agents still hallucinate library APIs. They'll write syntactically correct code against an API that changed in the last major version. The planning stage reduces this by including research tasks with URLs, but it doesn't eliminate it. Verify unfamiliar library usage against docs before shipping.

The spec quality ceiling is your knowledge. If you don't understand your codebase well enough to write a clear spec, the agent won't either. The planning phase surfaces this. If you can't finish the plan without open questions, you need to learn more before you start.

Merge conflicts still happen when two tasks share a file the plan didn't account for. Worktrees stop filesystem collisions. They don't do design work.

The tooling layer is moving fast. Git worktrees are stable. The orchestration tools built on top of them aren't. Build your workflow around git worktree add, not the wrapper tool.

Context pollution goes both ways. Too little context and the agent hallucinates your conventions. Too much, and the real rules get buried. The same principle applies to task files: dense, explicit, and short.

Entropy compounds. Incomplete refactors, mixed conventions, dead code. All of it degrades agent performance on the next feature because the agent has to reason about a messier codebase. This workflow doesn't fix that.

Don't adopt all three stages at once.

Start with Stage 2. Before your next AI coding session, spend 10 minutes writing a task plan. Three things:

No new tools. No worktrees yet. Write it down first.

Once that's a habit, add Stage 1. The spec forces you to resolve assumptions before the agent makes them for you. This + a 15-minute planning session will save you 2+ hours of correction.

For parallel execution: git worktree add before you open a second tab.
One command, isolated branch, no collisions.

I put together a starter kit with every template from this post: the spec, the task planner prompt, the agent scoping format, the worktree setup script, and a lean CLAUDE.md ready to drop into any repo.

🎬 Scroll-driven animations that finally feel natural

Most scroll animations feel disconnected because they rely on timelines instead of user input. This guide shows how to tie motion directly to scroll position, which makes interactions smoother and easier to reason about. It’s a small shift in approach that fixes a surprisingly common UI problem.

That’s all for this week. Have any ideas you want to see in the next article? Hit Reply!

Cheers!

Editor-in-chief,

Kinnari Chohan

👋 Advertise with us
Interested in sponsoring this newsletter and reaching a highly engaged audience of tech professionals? Simply reply to this email, and our team will get in touch with the next steps.