Agentic Engineering with Claude Code: What It Actually Looks Like

Addy Osmani recently drew a sharp line between vibe coding and agentic engineering. Vibe coding is the YOLO version: prompt, accept, run, paste the error back, repeat. Agentic engineering is the disciplined version: AI handles implementation while you own architecture, quality, and correctness.

I've been living on the agentic engineering side for the past several months, using Claude Code to build production systems. Not prototypes. Not weekend hacks. Systems that handle real inventory, real orders, real money.

Here's what the workflow actually looks like when you do this every day.

Dimension	Vibe Coding	Agentic Engineering
Planning	Prompt and see what happens	Spec written before any code
Code review	Accept everything, fix later	Review every diff like a human PR
Testing	Paste errors back, hope for the best	Verification gate — agent loops until tests pass
Context	Start fresh each session	CLAUDE.md compounds over time
Architecture	Emerges accidentally	Decided upfront, enforced by spec
Scale	Solo, single session	Multi-agent teams with dependency graphs
Failure mode	Demos great, breaks in production	Slower start, reliable at scale

The spec-first workflow

Every feature starts with a spec file, not a ticket. The spec lives in the repo as a markdown file and contains everything an agent needs to implement the feature: problem statement, constraints, expected behavior, edge cases, and verification criteria.

The difference between a ticket and a spec is precision. A ticket says "add retry logic to the sync service." A spec says why retries are needed, what the retry strategy should be (exponential backoff, max 3 attempts, circuit breaker at 50% failure rate), how to verify it works (specific test scenarios), and what not to do (don't retry on 4xx errors, don't introduce new infrastructure dependencies).

The verification gate is the critical piece. Every spec includes a verification section with a test script or checklist. If the tests fail, the agent iterates autonomously. If they pass, a human reviews the diff. This dramatically reduces review burden: you're checking whether the approach is right, not whether the code works.

For well-specified features, the agent produces a diff that passes review 70-80% of the time. The remaining 20-30% needs human judgment, usually around edge cases the spec didn't anticipate.

Teaching your AI: the CLAUDE.md pattern

The most important file in any agentic engineering setup is CLAUDE.md. It lives at the repo root and teaches the AI about your codebase: architecture decisions, coding conventions, commands, and patterns to follow.

The key insight: CLAUDE.md is living documentation. Every time you discover a bug pattern, learn something new, or establish a convention, you add it to the file. Some real examples:

• "Never use rounded-xl for cards, always use rounded-lg" added after the agent generated inconsistent UI across pages
• "All API response fields must use snake_case, no camelCase aliases" added after frontend-backend mismatches
• "Always include a verification script in specs" added after shipping a bug when we skipped testing

After a few months, our CLAUDE.md files are 500+ lines. Every lesson learned is encoded. New team members, human or AI, inherit all of it. The document compounds in value over time, and the agent's output quality improves measurably with each rule you add.

You can also use hierarchical CLAUDE.md files. A root file for project-wide context, and subdirectory files for domain-specific rules (for example, a frontend-specific CLAUDE.md with strict UI design system constraints).

Sub-agents and parallel execution

Claude Code can spawn specialized sub-agents scoped to specific directories. In a full-stack project, you might configure a backend agent for your API layer and a frontend agent for your UI layer. Each agent only modifies its designated directory, maintains focused context, and can work in parallel with the other.

This is the simplest form of parallelization: you describe a feature that spans frontend and backend, and Claude splits the work between two agents running simultaneously. The context isolation means each agent has a smaller, more relevant context window, which produces better output than a single agent juggling everything.

Agent teams: multi-agent sprints

This is where things get interesting. For large features spanning 20+ tasks with complex dependencies, Claude Code supports coordinated agent teams.

The workflow has three phases:

Phase 1: Scope. You point Claude at a feature request and ask it to create a scope document. It explores the codebase, identifies gaps and mismatches, and produces a detailed scope doc with change specs per component.

Phase 2: Sprint plan. From the scope doc, Claude breaks the work into discrete tasks, identifies dependencies between them, and designs a parallelization strategy. The output is a sprint doc with a task table and dependency graph.

Phase 3: Team execution. You tell Claude to assign the sprint plan to an agent team. It creates a team, wires all tasks with dependency relationships, spawns agents, and coordinates throughout: relaying blockers, monitoring progress, shutting down agents when their work completes.

On one recent feature, we used this workflow to ship 28 tasks across 4 phases. The backend agent tackled the critical path first (aligning data schemas), and once that unblocked downstream work, the frontend agent picked up its remaining 14 tasks. The entire feature landed in a single sprint.

The coordination is what makes this work. When a backend agent finishes a schema change, the lead relays the finalized structure to the frontend agent so it doesn't waste time re-reading files. When an agent goes idle unexpectedly, you ping it for a status update. When an agent's work is done, you shut it down.

The sprint plan is the contract. Agents work autonomously from it. Without one, they duplicate work or miss dependencies. We tried the "just build feature X" approach early on, and it produced inconsistent results. The structured pipeline (scope, then sprint plan, then execution) is what makes agent teams reliable.

The economics

Here's what actually changed in our workflow.

Over a five-week sprint on one project, we shipped 1,371 commits, averaging 40 per day, peaking at 126 on a single day during an agent team sprint. The test suite grew from roughly 200 tests to over 7,600 across unit, API, contract, and end-to-end layers.

The aggregate time savings across test generation, documentation, UX audits, API specs, boilerplate, debugging, and agent team sprints was roughly 85% compared to how long the same work would have taken without AI assistance.

But the gains aren't uniform. For well-specified features where the domain is well-understood, we see 2-3x throughput improvement. For exploratory features where the spec is thin, the improvement is marginal. The agent spends as much time asking questions as it saves writing code.

The bottleneck has shifted from writing code to writing specs. Which is where the bottleneck should have been all along. Good specs produce good output. Vague specs produce vague output. The agent is a force multiplier on the clarity of your thinking.

What I got wrong

Three failure modes I keep hitting:

Specs that were too vague. Early specs read like tickets. "Implement caching for the product catalog." That's not a spec, that's a wish. A good spec specifies the cache strategy, TTL, invalidation triggers, memory budget, and what happens on a cold cache. The agent won't push back on ambiguity. It will just make assumptions.

Not enough negative constraints. The agent is eager. Without explicit "don't do this" instructions, it will add infrastructure dependencies, introduce new abstraction layers, or refactor adjacent code you didn't ask it to touch. Negative constraints are as important as positive requirements. Every CLAUDE.md should have a "Don't" section.

Skipping the verification step. When you're in a hurry, it's tempting to eyeball the diff instead of running the test script. Every time we've done this, we've shipped a bug. The verification gate exists for a reason. Trust the process even when it feels slow.

The irony Addy pointed out is true: agentic engineering actually rewards good engineering practices more than traditional coding does. The better your specs, the better the AI's output. The more comprehensive your tests, the more confidently you can delegate. The more documented your architecture, the less the agent invents on its own.

Where this is heading

The trajectory is clear: the workflow keeps getting more autonomous. Agent teams today need a human lead coordinating. That coordination will itself be automated. The sprint plan format will become a standard. The CLAUDE.md pattern will become an industry convention.

But the core loop won't change. Somebody has to decide what to build and why. Somebody has to write the spec that encodes that decision with enough clarity that an agent can execute it. Somebody has to review the output and catch what the tests can't.

Agentic engineering doesn't replace engineering. It raises the bar for what engineering means. The developers who thrive won't be the ones who prompt the fastest. They'll be the ones who think the clearest about what they're building, then use agents to build it at a pace that wasn't possible before.

---

For the conceptual framework behind "agentic engineering" vs. "vibe coding," see Addy Osmani's Agentic Engineering. For documentation on Claude Code's agent teams feature, see the official docs.