DEV Community: Karun Japhet

The Comfort Plateau AI Built For You

Karun Japhet — Thu, 21 May 2026 06:02:00 +0000

I've spent the last year watching engineers and writers adopt these tools, and the same pattern keeps showing up. The first three months look transformative. The next nine look almost identical to the first three.

The output keeps coming. The confidence keeps building. The skill stops moving.

This isn't a story about AI making people dumber. It's a story about a comfort plateau that didn't exist before, and what it costs to stay on it.

The accessibility breakthrough is real

Draw a spider chart. Hundreds of axes: SQL, contract law, React, radiology, negotiation, Kubernetes, copywriting. Score a human. Most experts look like a star with two or three spikes and a flat field everywhere else. Depth is the point.

Plot AI on the same chart. It's not a 5 on any axis. But it sits at a 2–4 across nearly everything. No individual has ever had a tool this broadly competent.

This is why the gains for newcomers are so large. A BCG study of 758 consultants found below-average performers improved by 43% and above-average performers by 17%. A field study of 5,179 customer-support agents found novices gained 34% in productivity while the most experienced gained almost nothing. Going from "can't do this" to "shipped a thing" used to take months. Now it takes minutes.

This part of the story is good. It's also where most writing about AI stops.

The bicycle you can't draw

Ask a person to rate their understanding of how a bicycle works. They will rate it high. Ask them to draw one from memory. About half of non-cyclists get the chain wrong, looping it around both wheels instead of only the back wheel and pedals. Many draw the frame joining the front and back wheels, which would make steering impossible. Asked to re-rate after the drawing, confidence collapses.

This is the Illusion of Explanatory Depth. People feel they understand things they can't actually explain. The illusion only breaks when you're forced to produce the explanation. Without that production step, confidence sits unchallenged forever.

AI removes the production step.

You don't draw the bicycle. You ask for one. The pedals are in the right place. The chain runs correctly. You ship it. Nothing collapses. The next time you need a bicycle, you ask again, and the feedback loop that would have built a mental model never closes.

I'm not certain the bicycle effect maps perfectly onto code or prose. But the mechanism, fluent output without forced explanation, feels right. And there's now direct evidence: an Anthropic study measured exactly this in January. Junior developers learning an unfamiliar library with AI assistance scored 17% lower on conceptual understanding and debugging than those who learned without it. The code they shipped looked indistinguishable. The judgment behind it did not develop.

"But we had this fear before"

Calculators were supposed to kill arithmetic. Spell-check was going to end literacy. Stack Overflow would breed shallow programmers. Most of those predictions were wrong. A meta-analysis found calculator use, integrated properly, improved math skills. Stack Overflow made code more functional but significantly less secure, and yet didn't atrophy programmers broadly. Why would AI be different?

Because of where it removes the work.

A calculator removes execution. You still set up the problem. The mental model of "I need to multiply these two things and check the units" stays yours. Stack Overflow removes retrieval. You still adapt the answer, integrate it, decide whether it fits.

GPS removes generation, the building of the spatial map. A longitudinal study tracking GPS users over three years found that heavy users showed declining hippocampal-dependent spatial memory. Not because they were already bad navigators. Because they stopped generating maps.

AI is like GPS, not like a calculator. It removes the generation step, the building of the mental model. That's the step that triggers the bicycle collapse. Take it away and the collapse never happens.

The motivated minority objection

There's a real counter-argument: every tool produces a distribution. The top quartile uses it to accelerate; the median plateaus; nothing changes about who pulls ahead. AI is just the latest example.

This is half right. The thing that used to make some people more valuable than others, deep knowledge in their specific domain, matters less now. AI has narrowed that gap on the work it can do. The BCG study showed it explicitly: bottom-half consultants gained more than top-half. The expertise gap is closing on AI-shaped tasks.

But a new axis is opening. Variance among AI users isn't shrinking; it's growing by about 47% in some measures. The new top quartile isn't the people with the deepest domain knowledge. It's the people who can sit with an AI output and ask: what would I have to draw to know if this is right? The ones who treat fluency as a warning, not a signal.

That's a skill the AI cannot give you. By design, it removes the very moment that develops it.

The plateau is where the squeeze is

There's an external reason this matters now, not just a personal one. The roles being compressed aren't the ones at the top of any skill chart. They're the ones whose required skill sits at or below what AI already provides. AI raises the floor. Roles at or under the floor get cheaper, fewer, or absorbed into someone else's job. Roles above the floor, where the work requires understanding deep enough to explain and not just outputs polished enough to ship, don't.

The comfort plateau is the floor. Stay there and the work you're doing is work AI already does. The work AI cannot do for you is the work that will keep belonging to humans.

What this asks of you

Try this. Take something you shipped with AI last week. Explain how it works, out loud, without looking. Notice where the explanation gets thin.

If most of it gets thin, that's the plateau. Not a failure of effort. A failure of friction.

Five years from now, the largest skill gap in knowledge work won't be between people who use AI and people who don't. It will be between people who let the fluency pass unchallenged and people who insisted on drawing the bicycle themselves.

The tool will keep working either way. The growth will not.

The Judgement Pyramid: Reasoning vs Measurement

Karun Japhet — Wed, 20 May 2026 06:00:16 +0000

A team I was talking to had built a code-review skill in Claude Code. It looked good: a careful prompt, a set of rules, and examples. Then it shipped a PR with a nested recursive loop inside another recursive loop. Cyclomatic complexity any static analyser (PMD, radon, ESLint's complexity rule) would have flagged in milliseconds. The skill missed it.

The team's response was to iterate the skill. More examples. More rules. A few more lines of prompt. The context window kept ballooning. I think the skill wasn't the problem. The placement was. The LLM was being asked to reason about something a tool can measure.

The Judgement Pyramid

Every check in your AI-assisted workflow runs at one of three layers.

The metaphor borrows from the testing pyramid: a stack ordered by cost and reliability. This one orders by how much judgement the check needs. The bottom is measurement: questions with a deterministic answer for a given input. The middle is soft judgement: style, design quality, naming, abstraction fit. The top is irreducible human judgement: does this serve the user, the team, the business.

Cost climbs with judgement too. Not money, necessarily. Cognitive load. Time. Attention. The bottom layer runs in milliseconds and costs nothing. The middle burns tokens and produces a different answer each time you ask. The top costs a person's focus, which is the most finite thing in the system.

The rule is simple: push every check to the lowest layer that can do it reliably.

Reasoning vs measurement

The useful question isn't can the LLM do this. Usually it can. The question is should it.

You wouldn't format code by hand. You'd run a formatter. Not because you can't think about indentation, but because thinking about indentation is wasted thinking. A formatter is the right tool because formatting is a measurement, not a judgement.

Cyclomatic complexity is a measurement. Coverage delta is a measurement. So is dead-code detection. So is whether two functions are near-duplicates, whether the import resolves, whether the test contains an assertion, whether the file ends with a newline. All of these have deterministic answers for a given input.

If a check has a deterministic answer for a given input, it's measurement. If it depends on context, taste, or domain knowledge, it's judgement.

Measurement belongs at the bottom of the pyramid. Judgement belongs higher.

Apex creep

Work creeps up the pyramid. The LLM is the most visible tool in the room, so checks gravitate toward it, even when a linter would do the job faster, cheaper, and more reliably. I'll call this apex creep: the steady drift of work toward the most expensive layer that can technically do it.

You recognise the symptom. A review skill that keeps growing. A prompt that gains a few lines every sprint. A team that keeps tuning the LLM to catch a class of bug a static analyser would flag for free. Each iteration adds more rules and more examples. The skill works harder. The placement is still wrong.

Apex creep is a placement bug. The fix is not a smarter LLM. The fix is moving the check to the layer that handles it deterministically.

The push-down move

Two questions to ask of every check in your harness.

Is this reasoning, or measurement? If measurement, push it to a deterministic tool. Sonar, Spotless, Ruff, ESLint, coverage gates, pre-commit hooks, complexity calculators. Write a script if no tool exists. That's how just lint got built, and that's the Unix-philosophy move for agentic coding. Hooks fire on tool calls; CI fires on PRs; pre-commit fires on commit. Pick the cheapest layer that catches the failure and run it there.

This is shift-left for AI checks: push verification as early and as cheap as it goes.

What goes to the LLM? Everything that genuinely needs context, taste, or cross-cutting judgement. REST endpoint shape. Naming. Abstraction fit. Whether the test asserts what the story actually asked for. Whether the change matches the intent of the design. The LLM is good at this kind of work. Once you stop using it as a linter, you've given it room to be good at it.

What goes to the human is the top of the pyramid: does this serve the goal, and is the LLM's middle-tier work good enough.

The bottom rung isn't free

Some failures hide below the bottom, in places where the obvious deterministic tool won't catch them.

A hallucinated import name fails on import or test run. A slopsquatted package (a real package whose name mimics a popular one, but malicious) doesn't. Both are LLM-shaped failures. The hallucinated import is caught by the bottom layer you already have. The slopsquatted package isn't.

That's not an argument for moving the check upward. It's an argument for adding the right deterministic tool to the bottom: lockfiles, allowlists, supply-chain scanners, sandboxed installs. Match the deterministic tool to the failure mode. Don't reach for the LLM because the bottom seems thin.

This isn't a new idea

The top and the bottom have always existed. Humans have done judgement work since there's been work. Compilers, type checkers, linters, formatters, test runners, CI pipelines: the deterministic floor under us has been growing for fifty years. Most of what we call "engineering practice" is arguments about where to draw the line: what to automate, what to keep manual, what the cost-benefit looks like.

Some teams over-rotated. They under-automated and called it craft, paying a cognitive tax forever to avoid investing in a tool once. Others over-rotated the other way and spent more building the automation than they ever saved.

The LLM didn't replace either layer. It added a new one in the middle: cheaper than a human, more flexible than a script, but slower and less reliable than a script on anything a script can already check. The pyramid is the same shape it's always been. We just have a new layer to misplace work on.

Audit your harness

Harness engineering is the work of 2026. Agents take longer tasks, run for longer horizons, and make more decisions before a human sees the output. The deterministic floor underneath them is the difference between an autonomous workflow you trust and one you babysit. Get placement right and autonomy compounds. Get it wrong and every increment of agent capability costs you more in review.

So open your review skill. Open your pre-commit hooks. Open the prompts you've written for grooming, testing, ops investigation. Go line by line. For each check, ask: reasoning, or measurement? If measurement, the LLM doesn't belong on it. Push it down.

Most teams discover their pyramid is top-heavy not because they planned it that way, but because the LLM was the easiest place to add a rule. Apex creep is what happens when "add a rule" defaults to "add a prompt."

Push it down.

Multi-Agent Development Workflows with Claude Code

Karun Japhet — Tue, 19 May 2026 21:31:53 +0000

Single-agent Claude Code is pair programming. One developer, one task, full attention.

I've been running three or four agents against a project backlog simultaneously. Not because single-agent broke, but because groomed cards were sitting idle.

Here's what that looks like in practice.

The shift: from writing code to shaping work

When you use Claude Code as a single agent, you're pair programming. That's powerful when you're exploring a problem or designing an approach. But if you have independent cards groomed and ready, you're leaving throughput on the table.

Your role shifts. Instead of writing code alongside one agent, you shape the work before it starts and judge it when it's done. You groom cards, make design decisions, dispatch work, and review output. The agents write the code. Addy Osmani calls this the factory model: you're no longer building software, you're building the factory that builds your software. The spec becomes the primary deliverable, and the harness (task tracking, isolation, quality gates, review) is the factory floor.

Steve Yegge's Gas Town post maps this journey in eight stages, from IDE copilot to building your own orchestrator. I started multi-agent work at stage 6: three or four terminal windows, each running Claude Code on a different card. You realise quickly that you're the bottleneck. The agents can move faster than you can review, approve, and redirect. The answer isn't more attention from you. It's giving the agents more autonomy with safety nets: quality gates that catch problems automatically, structured dispatch so agents find their own work, and a review workflow for when they're done.

This post is my version of stage 8. The tooling is still maturing, and this harness will look different in six months. This is the April 2026 version.

Anthropic's 2026 Agentic Coding Trends Report says multi-agent "doesn't make sense for 95% of agent-assisted development tasks." That's probably true for ad-hoc coding. But if you have a groomed backlog of independent cards, running them in parallel is the logical next step to move through the backlog quicker.

Two modes, not a progression

These aren't stages you graduate through. They're modes you switch between based on what you're doing right now.

Thinking mode (single agent)

When you're exploring, designing, or working through a single problem. Grooming cards, writing acceptance criteria, debugging something complex. The value is in the conversation, not the throughput.

This is pair programming. Full attention on one thing.

Throughput mode (parallel workers)

When you have multiple cards ready to go. Each worker gets a card, a worktree, and runs independently. You review their output when they're done.

Choose based on card complexity and dependencies:

Sub-agents for small, independent cards (roughly 15-minute tasks):

Quick fixes, config changes, bounded features
Research running in background
Automated code review of completed work
Short-lived: no auto-compaction, so longer tasks can exhaust the context window
Cheaper: minimal context startup, returns summaries only

Agent teams for substantial cards or cards with cross-card dependencies:

Multi-file features that need to read large parts of the codebase
Cards where the agent needs sustained autonomy and may hit context limits
Each teammate is a full Claude Code session with auto-compaction, so they can sustain longer work
More expensive: each teammate loads full project context independently

Agent teams also handle coordination. When cards genuinely depend on each other, teammates can communicate directly via peer-to-peer messaging (SendMessage), shared task lists with dependency tracking, and auto-unblocking. Vertically-sliced stories following the INVEST principle produce fewer cross-card dependencies than horizontal slicing, but they don't eliminate them. Real dependencies exist even in well-groomed backlogs.

Real coordination cases:

One card updates a shared schema; other in-flight cards need to know before they merge
Large refactors that can't be one card, where agents need to agree on new interfaces
Adversarial debugging: competing hypotheses where agents share findings

Agent Teams require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (v2.1.32+) and are still experimental. No session resumption, task status can lag, one team per session.

How to choose

Situation	Mode	Why
Exploring, grooming, designing	Thinking	You need the dialogue
One thing that needs full attention	Thinking	Conversation > throughput
Multiple small, bounded cards ready	Throughput (sub-agents)	Fast, cheap, parallel
Multiple substantial cards	Throughput (agent teams)	Full context, sustained autonomy
Cards with cross-card dependencies	Throughput (agent teams)	Agents need to communicate
Research while you work	Throughput (sub-agents)	Background tasks
Review of completed work	Throughput (sub-agents)	Fresh context, separate reviewer

Rate limits are the real parallelism ceiling. They're pooled across all sessions on your account. Opus has the strictest limits. Plan for this when dispatching multiple workers.

The harness: making throughput mode reliable

Dispatching multiple agents is easy. Getting reliable output is hard. The harness (task tracking, isolation, quality gates, review) is what makes multi-agent development repeatable.

Layer 0: the upstream gate

The most important quality gate happens before any code is written.

Careful grooming is what makes the whole pipeline work. Clear description, specific acceptance criteria, explicit non-goals. As Ankit Jain puts it, "the most valuable human judgment is exercised before the first line of code is generated, not after."

I spend more time grooming cards than I do reviewing agent output. That ratio feels right. Groom in your main Claude Code session, use the conversation to think through edge cases, and write precise acceptance criteria. The card is the spec.

Layer 1: task tracking

Agents need to discover available work, claim it atomically, and track what's been tried. A TODO list isn't enough.

I'm using Beads for this. It stores data locally via Dolt, gives agents programmatic access, and handles dependencies between tasks. The key commands:

bd ready lists tasks with no open blockers
bd update <id> --claim atomically claims a task
bd show <id> gets full card details including previous notes and rejection feedback

A /dispatch skill wraps this into a workflow: find available cards via bd ready, present them for selection, claim each one, and spawn a worker per card with worktree isolation.

For multi-developer setups, a centralized tool (GitHub Issues, Linear) may be more practical. Beads' strength is agent-native programmatic access. See also The Claude Protocol and Metaswarm for existing harness implementations.

Layer 2: isolation

Without worktree isolation, parallel agents can't write to the same files. With it, each agent gets its own branch and working directory.

A worker agent definition (.claude/agents/worker.md):

---
model: sonnet
isolation: worktree
background: true
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
permissionMode: acceptEdits
---

isolation: worktree gives each worker its own git worktree. background: true means the dispatch doesn't block waiting for workers to finish. model: sonnet keeps costs down for development work (swap to opus for complex cards).

Supporting config:

.worktreeinclude copies gitignored files (like .env) into new worktrees
WorktreeCreate hooks handle dependency installation
Scope each agent via CLAUDE.md to prevent merge conflicts across worktrees

Anthropic's C compiler case study used this pattern with 16 parallel agents. They hit duplicate work and merge conflicts. Tighter scoping and atomic task claiming address both.

Layer 3: quality gates

Two categories: automated (hooks that block the agent) and manual (human judgment during review). I underestimated how large agent-generated diffs get when the card isn't tightly scoped. The diff size guard was an afterthought; it's now one of the more useful gates.

Automated gates (fail-fast pyramid)

Run fastest and cheapest first, most expensive last:

Formatting (PostToolUse on Write/Edit, instant). Auto-fix, not a gate.
Linting / static analysis (seconds). Fast, deterministic.
Type checking (seconds). Catches interface mismatches.
Secret detection (PreToolUse on Edit/Write). Blocks before secrets hit disk.
Unit tests (minutes). The foundation.
Diff size guard (instant). Reject if change exceeds threshold. Prevents comprehension debt.
Automated code review (subagent, 30-90s). Separate agent reviews the diff.

The code review subagent must be a separate agent with its own context window. As Nick Tune writes, "asking the main agent to mark its own homework is obviously not a good approach." Hamilton Greene's 9-agent approach achieves roughly 75% useful suggestions versus less than 50% from single-agent review.

Hook implementation:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "./scripts/detect-secrets.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE_PATH\"" }]
      }
    ],
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "./scripts/quality-gate.sh" }]
      }
    ]
  }
}

Exit code 0 proceeds. Exit code 2 blocks with feedback (the agent gets the stderr message and iterates). Lint, tests, and code review fire on TaskCompleted (runs once when the agent says "done"). Secret detection fires on PreToolUse (blocks before the write). See hooks reference.

Manual gates

What automated checks can't catch:

Scope adherence. Did the agent build what the card asked for, or add unrequested features?
Architectural coherence. Does the implementation fit the architecture of the rest of the system, or did the agent invent its own patterns?
Business logic correctness. Models infer patterns statistically, not semantically.
Comprehension check. If you can't understand the diff, it's too large or too novel.

Layer 4: review gates

For trunk-based development without PRs, the worktree branch is the review surface. git diff main from the worktree shows exactly what would change on merge.

A /review-worktree skill handles this:

Cross-references bd list --label review:pending with git worktree list
Shows commit history and diff summary for the selected worktree
Options: view full diff, view specific file, run tests, run review agent, approve, reject
Approve: merge to main, close card, clean up worktree
Reject: reopen card with feedback comment visible to the next worker via bd show

For PR-based teams, the agent creates a PR from the worktree branch. Standard review process.

Layer 5: the feedback loop

When work is rejected, the card reopens with a comment explaining why. On the next dispatch, the worker agent sees the rejection feedback via bd show. It has context on what was tried and why it failed.

When an agent is stuck, the card goes to blocked with a needs-help label and a note explaining what was tried. The human reviews and either re-grooms the card or splits it.

What it looks like in practice

Here's a walkthrough on credit-card-lending using Agent Teams. Three cards groomed and ready. The session starts with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enabled.

Check the backlog and create the team

> bd ready --plain

bd-c4a1  P1  Add payment grace period calculation     customer
bd-e2f7  P1  Fix SSN validation accepting 000 prefix  customer
bd-b8d3  P2  Add CSV export to transaction history     reporting

> Create a team with three teammates, one for each card. Each teammate should use the worker agent definition and get its own worktree.

Creating team "sprint-work"...

Spawning teammate "grace-period" for bd-c4a1...
  Worktree: work/bd-c4a1-payment-grace-period
  Card claimed.

Spawning teammate "ssn-fix" for bd-e2f7...
  Worktree: work/bd-e2f7-fix-ssn-validation
  Card claimed.

Spawning teammate "csv-export" for bd-b8d3...
  Worktree: work/bd-b8d3-csv-export-transactions
  Card claimed.

Team "sprint-work" running. Ctrl+T to toggle task list. Shift+Down to
cycle between teammates.

Monitor progress

The shared task list shows what each teammate is working on. Ctrl+T toggles it:

Tasks:
  [in_progress] bd-c4a1: Add payment grace period calculation (grace-period)
  [completed]   bd-e2f7: Fix SSN validation accepting 000 prefix (ssn-fix)
  [in_progress] bd-b8d3: Add CSV export to transaction history (csv-export)

While teammates work, I stay in the lead session. Groom next sprint's cards, explore a design problem, whatever needs thinking. Teammates message the lead if they're stuck or need clarification.

Review completed work

ssn-fix and csv-export have finished. I review each worktree diff from the lead session.

> Show me the diff for ssn-fix's worktree

Commits (main..HEAD):
  a3f8c21 Fix SSN validation to reject 000 and 999 prefixes
  e7b2d14 Add test cases for invalid SSN prefixes

Changed files:
  src/.../customer/validation/SsnValidator.java      | 12 ++++++--
  src/.../customer/validation/SsnValidatorTest.java  | 28 ++++++++++++++++

Small, focused fix. Two files, clear test coverage. Merge it.

> Merge ssn-fix's worktree to main

Merging work/bd-e2f7-fix-ssn-validation into main... done
Closing bd-e2f7... done
Removing worktree... done

Now the CSV export:

> Show me the diff for csv-export's worktree

Commits (main..HEAD):
  b1c4e89 Add CSV export endpoint for transaction history
  d5a7f23 Add PDF export endpoint for transaction history
  f9e1b34 Add export format selection dropdown to UI

Changed files:
  12 files changed, 847 insertions(+), 23 deletions(-)

Scope creep. The card said CSV export. The teammate added PDF export and a UI component.

> Reject. Send csv-export a message: "Card asked for CSV export only.
  PDF export and UI dropdown are out of scope. Revert those changes
  and keep only the CSV export."

Message sent to csv-export. Reopening bd-b8d3...

With Agent Teams, the rejection goes directly to the teammate via SendMessage. The teammate receives the feedback, reverts the out-of-scope work, and resubmits. No re-dispatch needed.

This is a common failure mode: agents are eager to build adjacent features. The tighter the acceptance criteria in the card, the less often this happens.

Where it falls apart

Compound reliability

Each agent at 95% success. Five agents chained: roughly 77%. Multi-agent trades reliability for parallelism. The benefit must justify the overhead.

Context loss between agents

Every handoff is lossy compression. Google Research found 39-70% degradation in sequential multi-agent tasks. Subagents summarize results back to the caller; teammates don't get the lead's conversation history. Isolation prevents context pollution but loses nuance.

Token cost

Multi-agent consumes 2-5x more tokens for equivalent work. No published harness has budget limits per task. /usage monitoring is the best we have. This is an unsolved problem.

Time blindness

From the C compiler case study: Claude can't tell time and will spend hours running tests instead of making progress. The harness needs to print progress infrequently and offer fast-test options.

Duplicate work

Without task claiming, multiple agents fix the same bug independently and overwrite each other. I've seen this even with bd's --claim, when two cards touch overlapping files. The C compiler case study hit it at scale with 16 agents targeting the same bug.

The 18-month wall

Without quality gates, the pattern is: early velocity (months 1-3), plateau (4-9), decline (10-15), stall (16-18) as comprehension debt accumulates. CodeRabbit's research found AI-generated code produces 1.7x more issues and performance inefficiencies 8x more often than human code. This is why quality gates matter. Without them, the velocity gains are temporary.

The honest tradeoffs

Model lock-in

Claude Code is locked to Claude models. The orchestration layer (sub-agents, agent teams, skills, hooks, worktrees) doesn't exist in other tools. Your model choice is portable (use Claude API keys with aider, opencode, etc.) but the harness is not. No open-source tool today gives you model flexibility and Claude Code's agent stack. If you're invested in this workflow, you're invested in Claude Code.

When to stay in thinking mode

You're exploring, designing, or grooming. The value is in the conversation.
One task that needs your full attention and steering.
Cost constraint. Throughput mode is 2-5x more expensive per equivalent output.
The work isn't decomposed into independent cards yet. Dispatch without grooming is waste.

The real cost

Anthropic's C compiler project: $20K in API costs for 16 agents producing 100K lines of code. That excludes significant human effort for workflow design, task decomposition, agent management, output review, and integration. Budget for both.

What's next

Today's harness is human-triggered. You run /dispatch when you're ready. The next step is agents that continuously pull from the backlog as cards become ready, with the human as reviewer rather than dispatcher.

The pieces exist: bd ready for discovery, worktrees for isolation, hooks for quality, agent teams for coordination. The missing piece is the continuous loop, and the trust to let it run.

Companies with agentic coding infrastructure report 30-50% acceleration in development cycles. But a February 2026 NBER study of nearly 6,000 executives found 89% of firms report zero productivity change from AI. The gap between those groups isn't model quality. It's the infrastructure around the model.

That's been the consistent lesson: harness design matters as much as prompt design.

Structuring Claude Code for Multi-Repo Workspaces

Karun Japhet — Thu, 26 Mar 2026 19:38:34 +0000

Claude Code understands one repo at a time. Most teams have thirty.

Microservices, shared libraries, infrastructure-as-code, frontend apps, data pipelines, all in separate git repos. Start Claude Code in one and ask about another, and it has no context. It doesn't know the workspace exists.

Here's how I've been setting this up to work across repositories.

The problem

When you start Claude Code in orders/order-service, it has no idea that orders/orders-ui exists next door, or that shared libraries live in shared/, or that the data team's Spark jobs are in analytics/. Every session starts with you explaining the workspace layout.

The same problem shows up when someone new joins the team. They clone one repo, but they don't know what other repos exist, how they relate, or where to look for shared infrastructure.

A bootstrap repo as the workspace root

The approach I landed on: a bootstrap repo that sits above all the other repos as the workspace root. It doesn't contain application code. It contains:

A repo manifest listing every repo, where it lives, and what it does
Context files that Claude Code picks up from the directory tree
Tasks for common cross-repo operations (pull all, search all, check status)

I use mani as the repo manager, but the ideas apply regardless of tooling. You could do this with a shell script and a list of repos.

Directory structure

workspace/
  mani.yaml                  # imports per-product configs
  CLAUDE.md                  # org-level context
  mani.d/
    orders.yaml              # order management (3-tier)
    shipping.yaml            # shipping & logistics (3-tier)
    analytics.yaml           # data platform (Spark, Airflow, APIs)
    assist.yaml              # agentic AI system (FastAPI, LangGraph, React)
    shared.yaml              # shared libraries and services
    infra.yaml               # infrastructure repos
  orders/
    CLAUDE.md                # team-level context (tracked in bootstrap)
    order-service/           # Spring Boot (gitignored)
    payment-service/         # Spring Boot (gitignored)
    orders-ui/               # React (gitignored)
    reporting-service/       # Spring Boot + PostgreSQL (gitignored)
    pricing-engine/          # Vert.x, not Spring Boot (gitignored)
  shipping/
    CLAUDE.md
    shipment-service/        # Spring Boot + MongoDB
    shipping-ui/             # Angular
    carrier-service/         # Spring Boot, reactive
  analytics/
    CLAUDE.md
    airflow-dags/            # Python, Airflow
    spark-jobs/              # PySpark on EMR
    metrics-service/         # Kotlin, Micronaut
    dashboard-ui/            # React
  assist/
    CLAUDE.md
    agent-service/           # FastAPI + LangGraph
    conversation-service/    # Spring Boot + WebSocket
    chat-ui/                 # React + streaming chat
  shared/
    CLAUDE.md
    react-lib/
    java-commons/
    feature-toggles/
  infra/
    CLAUDE.md
    terraform-modules/
    ci-templates/
    cluster/

Each indented directory under a product (order-service/, orders-ui/, spark-jobs/, etc.) is a separate git repo, cloned by the repo manager and gitignored by the bootstrap repo. The CLAUDE.md files at each level are tracked in the bootstrap repo.

Three layers of context

Claude Code walks up the directory tree looking for CLAUDE.md files. If you start it in orders/order-service, it reads:

orders/order-service/CLAUDE.md (repo-level, committed in that repo)
orders/CLAUDE.md (team-level, committed in bootstrap)
workspace/CLAUDE.md (org-level, committed in bootstrap)

Each layer adds context without repeating what the others provide.

Layer 1: Organisation

The org-level CLAUDE.md covers things that apply everywhere:

Warning that this is a multi-repo workspace (check git rev-parse --show-toplevel before git operations)
How to discover repos (point to the manifest file)
Which products exist and what they own
Common cross-repo operations

Keep this short. Claude reads it on every session regardless of which repo you're in.

Layer 2: Team

The team-level CLAUDE.md covers conventions shared across repos in that group. The content varies by product type:

A 3-tier product (like orders or shipping) might cover:

Backend stack (Java 21, Spring Boot 3.5, Gradle, MongoDB)
Frontend stack (React 19, Vite, TypeScript)
Build and test commands for each
The one exception (the pricing engine uses Vert.x, not Spring Boot)

A data platform (like analytics) might cover:

Orchestration (Airflow DAGs, triggered via async-job-service)
Processing (PySpark on EMR, containerised Python jobs on ECS)
Multi-region support (pipelines run per-region with region-specific config)

An agentic system (like assist) might cover:

Agent framework (FastAPI + LangGraph for orchestration)
Backing services (Spring Boot for persistence, WebSocket for streaming)
Frontend (React with streaming UI patterns)

I learned not to list repos here. Lists go stale. Instead, tell Claude where to look: "This group's repos are defined in mani.d/orders.yaml. Each project has a desc field. Check that file for the current list."

Layer 3: Repository

This lives in each repo and is maintained by the team that owns it. Build commands, architecture notes, test instructions, things specific to that codebase. This is standard Claude Code usage, nothing new.

Project descriptions in the manifest

One-line descriptions in the repo manifest make a big difference for discovery. When Claude reads the manifest, it knows what each repo does without cloning or exploring it.

projects:
  order-service:
    desc: Order lifecycle management and fulfilment
    url: git@gitlab.com:acme/order-service.git
    path: orders/order-service
    tags: [orders, java]

  pricing-engine:
    desc: Vert.x real-time pricing engine
    url: git@gitlab.com:acme/pricing-engine.git
    path: orders/pricing-engine
    tags: [orders, java]

  orders-ui:
    desc: React UI for order management and reporting
    url: git@gitlab.com:acme/orders-ui.git
    path: orders/orders-ui
    tags: [orders, ui]

The desc field costs almost nothing to maintain and saves Claude from guessing or asking.

Cross-repo tasks

A repo manager like mani lets you define tasks that run across repos:

tasks:
  update-repos:
    desc: pull latest for all repos
    target: all
    cmd: |
      current=$(git rev-parse --abbrev-ref HEAD)
      if [[ -n $(git status -s) ]]; then
        git fetch origin $branch
        echo "FETCHED (dirty working tree on $current)"
      elif [[ "$$current" != "$branch" ]]; then
        git fetch origin $branch
        echo "FETCHED (on branch $current, not $branch)"
      else
        git pull --rebase origin $branch
      fi

This one pulls latest on repos that are clean and on the default branch, and fetches (but doesn't touch) repos with work in progress. The data is available locally either way, so the next pull is fast.

Other useful tasks: search across all repos, check which repos have uncommitted changes, trigger CI pipelines.

The gitignore trick for team-level CLAUDE.md files

The bootstrap repo gitignores all sub-repo directories. But the team-level CLAUDE.md files need to be tracked in bootstrap, inside those same directories. The fix:

# Use dir/* instead of dir/ so exceptions work
orders/*
!orders/CLAUDE.md

orders/ ignores the directory entirely (git won't look inside). orders/* ignores everything inside it but lets you exclude specific files.

Skills, hooks, and commands

Claude Code supports skills, hooks, and custom commands configured in the .claude/ directory of a repo. These have always worked at the repo level. The bootstrap structure gives you two more levels:

Org level (in the bootstrap repo's .claude/):

Skills that work across all repos. I have one that queries SonarQube for any repo in the workspace, auto-detecting the project key from the current directory.
Pre-commit hooks (gitleaks for secret detection, applied to the bootstrap repo itself).
Shell scripts for operations that span teams, like auditing which repos still need a branch migration.

Team level (in each team's CLAUDE.md or tracked config):

Build conventions that apply to all repos in a team but not the whole org. A team with ten Spring Boot services can document the shared Gradle convention plugins once, in the team CLAUDE.md.

Repo level (in each repo, as before):

Repo-specific skills, hooks, and commands. Nothing changes here.

The layering means you write a SonarQube skill once at the org level and it works in any repo. You document ./gradlew spotlessApply once at the team level and every repo in that team inherits the context.

Partial and full checkouts

Not everyone needs the whole workspace. Most developers I work with only clone their team's repos:

workspace/
  mani.yaml
  CLAUDE.md
  orders/
    CLAUDE.md
    order-service/
    payment-service/
    orders-ui/

They still get the org-level and team-level CLAUDE.md files. Claude Code still understands the team's conventions and knows how to discover the rest of the organisation through the manifest.

A platform engineer or architect who works across teams clones everything. They get the full context at every level.

The repo manager handles both. You can tag repos by team and clone selectively (mani sync --tags orders) or clone everything (mani sync). Either way, the layered context works because CLAUDE.md files at each level are already in place.

What this gets you

When someone starts Claude Code in any repo in the workspace, it already knows:

What the repo does and how to build it
What other repos exist in the same team and how they relate
How to navigate to shared libraries, infrastructure, and deployment configs
Common conventions and exceptions

If you want to try this, start small. Create a bootstrap repo, add a CLAUDE.md with your workspace layout, and list your repos in a manifest with one-line descriptions. You can add team-level context and cross-repo tasks as the structure proves useful.

Agentic Patterns Developers Should Steal

Karun Japhet — Thu, 19 Mar 2026 05:13:51 +0000

Production agentic systems decompose problems and use the right tool for each step. Most developers hand the AI the whole problem.

That's the gap. Teams building production AI workflows have developed patterns for making AI reliable. Developers using AI coding assistants like Claude Code, Cursor, or Copilot mostly haven't adopted them yet.

These patterns aren't theoretical. They're practical and don't require special tooling.

The Patterns

Pattern	What most devs currently do	What devs should be doing
Deterministic tool delegation	Ask AI to do everything	Use tools for solved problems, AI orchestrates
Verification loops	Accept first output	Generate → evaluate → revise
Context engineering	Dump everything in	Curate what the model sees
Upfront planning	One big prompt	Reviewable plan before execution
Persistent memory	Start fresh each session	Cross-session learning, codified constraints
Structured guardrails	Hope for the best	Execution-layer constraints, hooks, gates
Observability	Look at the output	Structured traces, quality measurement
Multi-agent specialisation	One agent does everything	Separate agents for separate concerns
Human-in-the-loop checkpoints	Trust everything or nothing	Consequence-based approval tiers

Here's what each one looks like. Some link to deeper posts.

Deterministic Tool Delegation

The pattern: Don't let the AI make decisions it doesn't need to make. If a deterministic tool can handle something (refactoring, formatting, linting, data validation), use the tool. The AI's job is orchestration, not execution.

What most developers do instead: Ask the AI to rewrite code for a rename, follow a style guide from memory, or process data it doesn't need to see.

Why it matters: Every unnecessary decision is a degree of freedom. Every degree of freedom is an opportunity to get something wrong, burn tokens, and produce a result you can't reproduce. Deterministic tools give you the same output every time.

I wrote about this in depth in The Unix Philosophy for Agentic Coding.

Verification Loops

The pattern: Instead of accepting the first output, create a generate-evaluate-revise cycle. The agent produces work, a separate pass critiques it against explicit criteria, and the agent revises.

What most developers do instead: Prompt, receive, accept or reject. The interaction model is single-shot.

Why it matters: LLMs produce plausible output that can be subtly wrong. Research shows 10-20 percentage point improvements on coding benchmarks from reflection alone. Anthropic's own guidance identifies the evaluator-optimizer workflow as one of the core composable patterns.

What this looks like in practice: After asking your AI assistant to implement a feature, follow up with: "Review what you just wrote. Check for edge cases, error handling, and whether it follows patterns in this codebase. List problems, then fix them." For high-stakes changes, use a separate session as an independent reviewer.

This pattern is also the foundation of test-driven development with AI: write the test first, let the AI implement, then the test itself becomes the verification loop. I've touched on this in the TDD workflow in intelligent Engineering: In Practice.

Context Engineering

The pattern: Deliberately architect what information the model sees, when it sees it, and in what form. Treat context as a finite resource, not an infinite scratchpad.

What most developers do instead: Paste entire files, full error logs, and broad descriptions, trusting the model to extract what's relevant.

Why it matters: Including irrelevant data actively worsens output quality. Models have attention patterns that favour the start and end of context, with the middle getting less focus. More context is not always better context.

I wrote a full post on this: Context Engineering for AI-Assisted Development. The short version: curate your CLAUDE.md for signal density, use .claudeignore to exclude noise, provide the two or three most relevant files rather than the entire directory, and start fresh sessions when context degrades.

Upfront Planning

The pattern: Before any code is written, create an explicit plan that decomposes the work into steps with dependencies and acceptance criteria. Review the plan before execution begins.

What most developers do instead: Give the AI a single prompt describing what they want and let it figure out the approach. "Add user authentication" becomes one big prompt rather than a sequence of reviewable steps.

Why it matters: Internal planning by the model is invisible and unreviewable. An explicit plan is where you catch architectural mistakes that are expensive to fix after implementation. It also prevents the "AI rewrote half the codebase and something is broken but I don't know where" problem.

What this looks like in practice: For any task that touches more than two files: "Before implementing, create a plan. List the files you'll modify, the changes in each, the order of changes, and how you'll verify each step works." Review the plan before saying "proceed."

This is central to the design discussion workflow I use.

Persistent Memory

The pattern: Retain lessons, decisions, and discovered patterns across sessions. Build institutional knowledge over time rather than starting from zero each conversation.

What most developers do instead: Every session starts fresh. They rediscover the same issues, re-explain the same conventions, and re-learn the same codebase quirks.

Why it matters: Without cross-session memory, the AI makes the same mistakes repeatedly and you correct it repeatedly. Codified constraints prevent the same mistakes from recurring.

What this looks like in practice: Maintain a CLAUDE.md that evolves. When you discover a gotcha ("the payments service returns 200 even on failures, check the response body"), add it immediately. When the AI makes a mistake, codify the prevention rule. Over time, your context docs accumulate the institutional knowledge that makes the AI genuinely useful on your specific project.

I cover this in detail in the Foundation and Context Documentation layers of the intelligent Engineering stack.

Structured Guardrails

The pattern: Define explicit boundaries around which decisions the AI can make autonomously and which it should escalate. This includes architectural constraints ("don't introduce a new database without discussing it"), scope boundaries ("only modify files in this module"), and approval gates for high-impact changes.

What most developers do instead: Give the AI full autonomy without defining what's in and out of scope. The agent makes architectural decisions, introduces new patterns, or changes public APIs without checking whether that's what you intended.

Why it matters: A prompt might be ignored as context fills up. A pre-commit hook won't be. Deterministic enforcement catches what prompt-based instructions miss.

What this looks like in practice: Define boundaries in your CLAUDE.md ("never modify migration files without asking"). Use pre-commit hooks for formatting, linting, and security checks. Set up Claude Code hooks for auto-formatting and blocking sensitive operations. Let low-risk operations run freely. Pause high-risk ones for review.

I wrote a hands-on tutorial on this: Level Up Code Quality with an AI Assistant.

Observability

The pattern: Systematic tracking of what the AI did, what worked, what failed, and using that data to improve future interactions.

What most developers do instead: Look at the output. No structured feedback, no trend tracking, no quality measurement over time.

Why it matters: The METR study found developers estimated they were 24% faster with AI when they were actually 19% slower. Gut feel is unreliable. Without measurement, you don't know if the AI is helping, and you can't systematically improve your workflows.

This is the least mature pattern in the list. The tooling barely exists for individuals and is fragmented across teams. I explore the current state, the gaps, and what we'd like to see in Observability for AI-Assisted Development.

Multi-Agent Specialisation

The pattern: Instead of one generalist agent handling everything, use multiple specialised agents with focused context, specific tool access, and defined roles.

What most developers do instead: One session, one agent, planning, implementation, and review all in the same context window.

Why it matters: Each agent gets a fresh, focused context window rather than one bloated context trying to hold planning, implementation, review, and testing simultaneously. Specialisation also lets you use different models for different tasks (a thinking model for planning, a fast model for implementation).

What this looks like in practice: Claude Code recently started offering to clear context when you accept a plan, giving the implementation phase a fresh, focused window with only the plan carried forward. Planning and implementation benefit from separate contexts.

Take it further. Build an agentic team with a backlog: a planning agent that decomposes work into tasks, implementation agents that execute them, QA agents that test, and review agents that validate. Each agent has specific skills and focused context for its role. Claude Code's Agent Teams and subagent features support this natively. Anthropic's engineering team built an entire C compiler using 16 agent teams, producing 100,000 lines of Rust code. Codex has similar multi-agent capabilities.

Anthropic's internal benchmarks showed a 90% improvement with multi-agent (Opus lead + Sonnet subagents) over solo Opus on complex tasks. Tekion deployed persona-driven agents across 1,300 engineers and saw 50-85% productivity gains, compared to 30-40% with raw LLM prompting. The trade-off is tokens: multi-agent workflows use 2-3x more tokens, but for significant features, the quality improvement justifies the cost.

Human-in-the-Loop Checkpoints

The pattern: Rather than either fully trusting the AI or micromanaging every line, define structured approval gates based on the consequence of the action.

What most developers do instead: Operate in one of two modes. Either review everything line-by-line (treating the AI as fancy autocomplete) or accept large chunks with only a cursory glance. A formatting change and a database schema change get the same level of scrutiny.

Why it matters: Not all changes carry the same risk. A tiered approach gives you speed where it's safe and control where it matters.

What this looks like in practice: Define personal approval tiers:

Auto-approve: Formatting, import organisation, adding type annotations
Quick review: New functions, test additions, single-file refactors
Careful review: Public API changes, database operations, auth logic
Full review with plan: Multi-file refactors, new architectural patterns, build/deploy changes

Use small, frequent git commits as checkpoints. If something goes wrong, you can revert to a known-good state without losing everything. Before accepting a change, ask yourself: if this is wrong, what breaks and how hard is it to fix?

Where to Start

You don't need all nine patterns at once. Start with the ones that address your biggest pain points:

Code quality issues? Start with structured guardrails and verification loops.
AI keeps making the same mistakes? Start with persistent memory and context engineering.
Large diffs that are hard to review? Start with upfront planning and human-in-the-loop checkpoints.
Spending too much on tokens? Start with deterministic tool delegation and context engineering.
Not sure if AI is helping? Observability is still largely unsolved, but start by establishing baselines now so you can measure later.

Stop handing the AI the whole problem. Break it down and use the right tool for each step.

This is part of a series on applying patterns from agentic systems to AI-assisted development. See also: The Unix Philosophy for Agentic Coding and Observability for AI-Assisted Development.

Observability for AI-Assisted Development

Karun Japhet — Sat, 14 Mar 2026 12:57:41 +0000

Developers using AI estimate they're 24% faster. A randomised controlled trial measured them at 19% slower.

That's from METR's 2025 study. These were experienced open-source developers working on their own codebases with tools they chose. Their self-assessment was off by over 40 percentage points.

If your perception of AI's impact is that unreliable, what are you actually measuring?

You Need a Baseline First

If you didn't measure before AI, measuring with AI won't work.

You can't attribute improvements to AI if you don't know what "before" looked like. Cycle time, deployment frequency, change failure rate, MTTR, value delivered per sprint: these need to exist as baselines before you introduce a new variable. Otherwise you're guessing, and as the METR study shows, our guesses aren't great.

I've seen teams adopt AI coding assistants and then ask "how do we know it's helping?" three months later. The real question is six months earlier: "how do we measure effectiveness?" If you didn't have that defined before AI, you won't have it now.

What Exists Today

The tooling for observability in AI-assisted development is fragmented. Cost visibility is reasonable. Quality visibility is nearly zero.

Claude Code is the most transparent. It ships with native OpenTelemetry support, tracking tokens, cost, tool calls, and session duration. The /cost command shows real-time spend. /stats visualises daily usage, session history, and model preferences. /insights goes further, analysing your sessions to surface project areas, interaction patterns, and friction points. Commits are auto-tagged with a co-author line, giving you a built-in "was this AI-generated?" marker in your git history. Anthropic provides an official monitoring guide with Grafana dashboard configs and a Docker Compose setup, and the community has built importable dashboards and plugins. The infrastructure for collecting data exists. What to do with it is the harder question.

OpenAI Codex CLI tags commits with a co-author line and supports OTel export for logs and traces. The enterprise dashboard tracks daily users by product, code review completion rates, review priority and sentiment, and session-level message counts. It's adoption-focused: who's using what and how much. No quality metrics, no incident correlation, no rework tracking. Individual developers get /status for rate limits but no cost visibility.

Aider has the most configurable commit attribution of any tool (co-author trailers include the model name). But no OTel, no dashboard, no persistent cost history.

GitHub Copilot offers team-level dashboards: acceptance rates, DAU/MAU, feature adoption. It's oriented toward "is our license worth it?" rather than "is the output good?" No commit tagging.

Cursor exposes very little. A "Year in Code" summary and an "AI Share of Committed Code" metric. No tracing, no commit tagging, no event-level data.

Cline shows per-request cost in the UI (one of its standout features) and supports OTel export at the enterprise tier. No commit tagging.

Amazon Q Developer has the richest built-in analytics dashboard of any tool: acceptance rates, lines of code by feature type, code review counts, per-language breakdowns. But it's admin-only, subscription-based (no per-token tracking), and publishes to CloudWatch rather than OTel.

Some of us have built our own layers on top. We use Claude Code Usage Monitor to track token usage as a proxy for understanding consumption patterns. It isn't perfect, isn't always accurate, but it gives you a feeling for where your usage goes. A few engineers on our teams have personal Grafana dashboards tracking their own AI metrics. But these aren't centralised, aren't standardised, and aren't as useful as they could be.

The picture across the industry: cost visibility is reasonable if you're willing to set it up. Commit tagging is inconsistent (Claude Code and Codex do it by default, most others don't). Quality visibility is nearly zero everywhere.

What's Missing

The gaps fall into three levels: what individual developers need, what teams need, and what organisations need.

For the Individual Developer

No effort distribution. You know how much you spent in tokens. You don't know where that effort went. Imagine if your AI assistant could tell you: "This week, 40% of your AI time went to test writing, 30% to refactoring, 20% to feature work, 10% to debugging. Your test-writing sessions had the highest acceptance rate. Your debugging sessions cost the most tokens per useful output." That would let you consciously decide where AI is worth using and where you're better off working without it.

Limited failure pattern detection. Claude Code's /insights is the closest thing we have: it analyses sessions and surfaces friction points. That's a real start, and most other tools don't offer anything comparable. But it's still a snapshot of recent sessions, not a long-running trend line. If the AI keeps making the same category of mistake (wrong import paths, ignoring your test conventions, using a deprecated API), you want something that surfaces "you've corrected the AI on import paths 12 times this month" and suggests adding it to your CLAUDE.md. Some people maintain a manual lessons-learned.md where they log AI mistakes. It works, but it's ad hoc.

No context effectiveness feedback. CLAUDE.md files are checked in, reviewed in PRs, and engineered for effectiveness over time, much like prompts. The feedback loop exists but it's manual and slow. You notice the AI getting something wrong, update the file, and see if it improves. What's missing is the measurement that closes the loop: did that change actually improve output quality, or did it just feel like it did? The METR perception gap applies here too.

For the Team

No aggregate failure patterns. If three engineers on the same team are all hitting the same AI failure mode, that's not three individual problems. It's a systemic context gap: a missing architectural convention, an undocumented pattern, a guardrail that should exist but doesn't. No tool surfaces this today.

No RCA correlation. Claude Code tags commits with a co-author line. That's the "was this AI-generated?" link in the RCA chain. But other tools don't do this consistently. And even with the tag, nobody is aggregating that data: correlating AI-tagged commits with incident rates, rework rates, or review times over time. Traditional RCA follows a clear chain (incident → deployment → commit → PR → review → root cause). AI adds a question to that chain: was the reviewer's miss caused by a large AI-generated diff? Was the AI missing context it should have had? Is this a known AI weakness that should be in the team's guardrails?

The velocity flatline problem. We've seen this firsthand. Teams get faster with AI. Then velocity flattens. Not because AI stopped helping, but because teams redirected the extra capacity to paying off debt or solving problems they found interesting. That's not necessarily bad, but if you're not tracking what work goes where, you can't tell the difference between "team is investing in sustainability" and "team is coasting."

The fix we found: track work against cards. Measure total value delivered, not just pace. Make sure the extra capacity from AI shows up as increased value, not just different work. This is a process fix, not a tooling fix. No observability tool surfaces this today.

For the Organisation

No cross-team maturity view. Some teams will be excellent at AI-assisted development. Others will struggle. As a CTO, you need to know which is which, and more importantly, what the effective teams are doing differently. Are they better at context engineering? More disciplined about review? Today, finding this out requires manual investigation.

No automated "are we improving?" picture. This is the hardest gap. Drawing a full picture of whether an engineering organisation is improving has always required someone to build that view manually. AI hasn't changed that. It's just added another variable.

The data exists. Commits are tagged. Tickets track value. CI tracks quality. AI tools track cost and usage. But nobody is stitching them into a coherent picture that answers: "Is AI helping us deliver more value, or is it making us feel faster while quality degrades?"

What We'd Like to See

Here's what I wish existed:

AI timesheets. Not for billing. For self-awareness. Show me where my AI time goes, which task types have the best return, and where I'm burning tokens for low value. Let me compare across weeks and see trends.

Automated RCA tagging. Correlate AI-tagged commits with downstream incidents, reverts, and rework. Not to blame the tool, but to know where to invest in better review, context, or guardrails.

Context effectiveness scoring. When I change my CLAUDE.md, show me whether output quality improved for the task types I was targeting. Even a rough signal (fewer corrections needed, lower rework rate) would be valuable.

Failure pattern aggregation. Surface repeated AI mistakes at the team level. If the same failure shows up across engineers, flag it as a context gap, not an individual problem.

The org-wide picture, stitched together. Combine git data, ticket data, CI data, and AI usage data into a view that answers: are we delivering more value? Is quality holding? Where should we invest next?

Questions for Solution Builders

If you're building in this space, here are the questions I'd want answered:

Can the "are we improving?" picture be automated? The data is there (git, tickets, CI, AI usage). Can you stitch it together without someone manually maintaining a dashboard? Can you infer value delivery trends from data that already exists?
How do you measure context effectiveness without controlled experiments? A/B testing CLAUDE.md configurations isn't practical in real workflows. What proxy signals can tell us whether a context change helped?
What does a useful AI timesheet look like? Not session-level token counts, but task-level effort distribution. How do you classify AI sessions by task type without requiring the developer to manually tag them?
How do you surface failure patterns across a team? Individual correction patterns are noisy. Aggregate patterns are signal. What's the right level of abstraction?
How do you separate "AI made us faster" from "we redirected capacity"? Velocity metrics alone can't tell you this. What combination of signals can?
How do you handle the perception gap? Developers believe they're faster. Measurement sometimes shows otherwise. How do you present this data in a way that's constructive rather than demoralising?

These aren't rhetorical questions. If you're building tools in this space, I'd like to hear your answers.

This is the second post in a series on applying patterns from agentic systems to everyday AI-assisted development. The first, The Unix Philosophy for Agentic Coding, covers deterministic tool delegation.

The Unix Philosophy for Agentic Coding

Karun Japhet — Sat, 14 Mar 2026 12:57:26 +0000

Most people use AI coding agents backwards. They hand the agent a problem and ask it to solve the whole thing. The agent reads, reasons, generates, and hopes for the best.

There's a better way. One that's cheaper, more predictable, and already well understood. It's the Unix philosophy, applied to how we work with AI.

The Pattern

The Unix philosophy boils down to: do one thing well, compose small tools, let the shell orchestrate. When you work with an AI coding agent, the agent is the shell.

Here's how I think about it:

Break the problem down. Don't hand the agent a big, vague goal. Decompose it into sub-problems.
If a tool exists, use it. Refactoring, formatting, linting, deployment: these are solved problems. Don't ask the AI to reinvent them.
If no tool exists, build one. A small, deterministic script is better than an LLM making judgment calls where none are needed.
The agent orchestrates. It decides what to do, in what order, with which tools. That's where its intelligence adds value.

The principle is simple: don't let AI make decisions it doesn't need to make.

Every unnecessary decision is a degree of freedom. Every degree of freedom is an opportunity for the model to get something wrong, burn tokens, and produce a result you can't reproduce.

What Goes Wrong Without This

When you ask an AI agent to do something a deterministic tool already handles, you get:

Inconsistency. LLMs aren't deterministic. Run the same prompt twice, get different results. A tool gives you the same output every time.
Wasted tokens. Generating 200 lines of reformatted code costs tokens. Running Prettier or Ruff costs nothing.
More failure modes. The model might miss edge cases a dedicated tool handles by design. A refactoring tool knows about downstream dependencies. An LLM might not.
Slower feedback loops. Generating code, reviewing it, finding the error, regenerating: that cycle is slower than calling a tool that gets it right the first time.

Examples

Refactoring

I want to rename a method. The method is used across dozens of files.

The naive approach: ask the agent to read the codebase, find all references, and rewrite them. The agent will try. It might miss some. It might introduce a formatting inconsistency along the way. You'll spend time reviewing a diff that's harder to trust.

The better approach: the agent calls IntelliJ's refactoring tools via MCP. One command. Every reference updated. Downstream dependencies handled. No formatting changes. No guesswork.

Refactoring is a solved problem. I wouldn't ask a teammate to do a manual find-and-replace across a codebase. I wouldn't ask an AI agent to either.

Analysing CSV Data

I have a set of CSVs I need to extract insights from.

The naive approach: hand the files to the agent and ask it to read, validate, extract, and summarise everything. The agent will try. It might misparse a column, silently drop malformed rows, or hallucinate a trend that isn't there. You won't know unless you check every step. Large CSVs make this worse. Hundreds of thousands of rows won't fit in a context window, and even if they did, you're burning tokens on data the model doesn't need to see. The agent doesn't know which rows matter until it's processed all of them.

The better approach: build a small CLI that pre-processes the data first. Validate schemas, flag missing values, confirm row counts, filter to the relevant subset, compute the aggregations that don't need intelligence. This is deterministic work. Then pass the clean, reduced output to the agent for the part that actually needs judgment: identifying patterns and summarising insights.

No tool existed for this specific validation, so I asked the agent to build one. That's the pattern. Build the tool, then use the tool. The agent wrote a script I can run repeatedly with predictable results. Now it's free to focus on what it's good at.

Code Formatting

I want my code to follow our team's style guide.

The naive approach: include the style guide in the prompt and ask the agent to follow it. It will mostly comply. It will sometimes get creative (especially as context fills up). You'll find inconsistencies across files that are annoying to track down.

The better approach: let the agent write code however it wants, then run Prettier, Black, Ruff, or ESLint. Zero ambiguity. The agent doesn't need to think about formatting at all, which means fewer tokens spent and fewer decisions that could go wrong.

Skills, Hooks, and Tools

If you use Claude Code, you'll know about skills (composable prompt-driven capabilities) and hooks (event-driven automation). These are the wiring. But wiring without workers doesn't accomplish much.

A good skill is composable. A great skill is composable and delegates to deterministic tools instead of taking on responsibilities it doesn't need. If a skill invokes a CLI tool, an API, or a build system instead of asking the LLM to reason through a solved problem, that skill will be faster, cheaper, and more reliable.

The same applies beyond Claude Code. Cursor rules, Windsurf workflows, any AI assistant: the pattern holds. Build your workflows so the AI orchestrates tools, not replaces them.

The Bigger Picture

This isn't just about code formatting and refactoring. The same principle applies to deployment pipelines, database migrations, CI/CD workflows, building CLIs for business operations. Anywhere a deterministic tool can guarantee a correct result, use it. Reserve the LLM for the parts that genuinely need judgment: understanding intent, choosing an approach, reasoning about trade-offs, writing novel logic.

Not every problem needs this treatment. For exploratory work, prototyping, or genuinely novel problems, letting the agent roam is the right call. But for the repeatable parts of your workflow, reach for a tool.

The best AI workflows I've built look like Unix pipelines. Small, focused tools. A smart orchestrator composing them. The AI's value isn't in doing everything. It's in knowing what to do and calling the right tool to do it.

Thanks to Carmen Mardiros whose talk at Data Engineers London helped crystallize this thinking.

intelligent Engineering: In Practice

Karun Japhet — Sat, 03 Jan 2026 18:32:40 +0000

Principles are easy. Application is hard.

I've written about intelligent Engineering principles and the skills needed to build with AI. But I kept getting the same question: "How do I actually set this up on a real project?"

This post answers that question. I'll walk through the complete setup, using a real repository as a worked example. Not a toy project. Not a weekend experiment. A codebase with architectural decisions, test coverage, documentation, and a clear development workflow.

Here's what it looks like in action:

The intelligent Engineering Stack

Before diving into details, here's the mental model I use. intelligent Engineering isn't one thing. It's layers that enable each other:

This diagram shows Claude Code's primitives. Other AI assistants have different building blocks: Cursor has rules and .cursorrules, Windsurf has Cascade workflows. The layers matter more than the specific implementation.

The screencast showed the workflow. The rest of this post explains what makes it work, layer by layer from top to bottom.

The Two Phases of intelligent Engineering

Shaping AI is preparation. You define agentic workflows, set up tooling, provide context, and build a prompt library. Context includes coding guidelines, architecture patterns, and deployment patterns. This is the work before you write code.

Leading AI is execution. You move through the development cycle: ideation, research, feature specs, architecture, stories, code, test, deploy. This is the work of building software, with AI as a collaborator.

The screencast showed Leading AI in action. But Leading AI only works well when Shaping AI is done right. Most of this post focuses on Shaping AI, the setup that makes everything else possible.

We've written more about this framework on the Sahaj website.

Level 4: The Workflow

This workflow mirrors how many teams already work: pick up a card, groom it, discuss the approach, TDD the implementation. Your team might work differently. intelligent Engineering is about shaping AI to match your existing practices, not adopting a prescribed workflow. The stack exists to encode how your team works. You should be shaping AI, not letting it shape you. This example shows one approach; yours will look different.

Here's what the screencast showed, step by step:

1. Pick Up Work

> /pickup

## Available Stories by Priority

### P0 - Critical
- #23 - S01.3: Profile Completion [module:customer]

Which card would you like to pick up?

2. Design Discussion

Here's what the design discussion looks like:

I've read #23 and the customer domain docs. Here's my understanding:

**What we're building:**
- Profile completion endpoint (PUT /api/v1/customers/{id}/profile)
- Validation: name, DOB (18+), SSN format, address
- SSN encryption before storage

**Proposed approach:**
1. Add ProfileRequest DTO with validation annotations
2. Extend CustomerService with completeProfile method
3. Add encryption service for SSN

**Questions:**
- Should SSN validation reject obvious invalid patterns (000-00-0000)?
- Should we allow profile updates after initial completion?

This is Leading AI in action. The AI proposes, the human validates and refines. Agreement on approach before code.

3. TDD Implementation

Test-Driven Development (TDD) is a discipline where you write tests before code. The cycle is Red-Green-Refactor: write a failing test (red), write minimum code to pass (green), clean up (refactor). Kent Beck's Test-Driven Development by Example is the canonical reference.

With agreement on approach, the TDD skill takes over:

Running in interactive mode...

RED: Writing test for profile completion with valid data

The TDD skill supports multiple review modes that control when you review AI's work. Interactive mode pauses after each red-green cycle; batch and autonomous modes give more flow with less oversight.

The AI writes a failing test:

@Test
void shouldCompleteProfile_whenAllFieldsValid() {
    var request = aProfileRequest()
        .withFirstName("John")
        .withLastName("Doe")
        .withDateOfBirth(LocalDate.of(1990, 1, 15))
        .withSsn("123-45-6789")
        .build();

    var result = customerService.completeProfile(customerId, request);

    assertThat(result.status()).isEqualTo(PROFILE_COMPLETE);
}

And runs it:

Test written. Running...
❌ FAILED: completeProfile method doesn't exist

RED confirmed. Ready for GREEN?

This continues through each acceptance criterion with small commits after each cycle.

4. Context Updates

If you use /pickup to start work, context updates happen automatically when the story completes. The /update-context command is for when you need to update docs outside the standard workflow:

> /update-context

Recent changes:
- Added ProfileRequest DTO
- Added completeProfile to CustomerService
- Added SSN encryption

Context docs to review:
- docs/context/domain/customer.md (profile rules)
- docs/context/modules/customer-module.md (new endpoint)
- docs/context/current-state.md (mark feature built)

Proceed with updates?

5. Push to Main

Trunk-based development. Small commits. Direct to main.

git push origin main

Story auto-closes via the Closes #23 footer in the final commit.

That's the workflow. Now let's understand what makes it possible.

Level 3: The Interaction Layer

This is how you interact with the AI during development. The examples use Claude Code primitives, but the concepts transfer to other tools:

Tool	Equivalents
Cursor	Rules (`.cursorrules`), custom instructions
GitHub Copilot	Custom instructions (`.github/copilot-instructions.md`)
Windsurf	Workflows, rules
OpenAI Codex	AGENTS.md, skills

Claude Code organizes these into distinct primitives: commands, skills, and hooks. Each serves a different purpose.

Design Principles

Whether you use Claude Code, Cursor, or another tool, these principles apply:

Description quality is critical. AI tools use descriptions to discover which skill to activate. Vague descriptions mean skills never get triggered. Include what the skill does AND when to use it, with specific trigger terms users would naturally say.

# Bad
description: Helps with testing

# Good
description: Enforces Red-Green-Refactor discipline for code changes.
             Use when implementing features, fixing bugs, or writing code.

Single responsibility. Each command or skill does one thing. /pickup selects work. /start-dev begins development. Combining them makes both harder to discover and maintain.

Give goals, not steps. Let the AI decide specifics. "Sort by priority and present options" beats a rigid sequence of exact commands. The AI can adapt to context you didn't anticipate.

Include escape hatches. "If blocked, ask the user" prevents infinite loops. AI will try to solve problems; give it permission to ask for help instead.

Progressive disclosure. Keep the main instruction file concise. Put detailed references in separate files that load on-demand. Context windows are shared: your skill competes with conversation history for space.

Match freedom to fragility. Some tasks need exact steps (database migrations). Others benefit from AI judgment (refactoring). Use specific scripts for fragile operations; flexible instructions for judgment calls.

Test across models. What works with a powerful model may need more guidance for a faster one. If you switch models for cost or speed, verify your skills still work.

Commands

Commands are user-invoked. You type /pickup and something happens.

Here's the command set I use:

Command	Purpose
`/pickup`	Select next issue from backlog
`/start-dev`	Begin TDD workflow on assigned issue
`/update-context`	Review and update context docs after work
`/check-drift`	Detect misalignment between docs and code
`/tour`	Onboard newcomers to the project

Each command is a markdown file in .claude/commands/ with instructions for the AI:

# Pick Up Next Card

You are helping the user pick up the next prioritized story.

## Instructions

1. Fetch open stories using GitHub CLI
2. Sort by priority (P0 first, then P1, P2)
3. Present options to the user
4. When selected, assign the issue
5. Show issue details to begin work

The /tour command walks through project architecture, module structure, coding conventions, testing approach, and domain glossary. It turns context docs into an interactive onboarding experience.

Skills

Skills are model-invoked. The AI activates them automatically based on context. If I ask to "implement the registration endpoint," the TDD skill activates without me saying /tdd.

Skill	Triggers On	Does
`tdd`	Code implementation requests	Enforces Red-Green-Refactor
`review`	After code changes	Structured quality assessment
`wiki`	Wiki read/write requests	Manages wiki access

The TDD skill is the one I use most:

Trigger: User asks to implement something, fix a bug, or write code

Workflow:

RED: Write a failing test, run it, confirm it fails
GREEN: Write minimum code to pass, run tests, confirm green
REFACTOR: Clean up while keeping tests green
COMMIT: Small commit with issue reference

Review modes control how much human oversight:

Mode	Review Point	Best For
Interactive	Each Red-Green cycle	Learning, complex logic
Batch AC	After each acceptance criterion	Moderate oversight
Batch Story	After all criteria complete	Maximum flow
Autonomous	Agent reviews continuously	Speed with quality gates

I typically use interactive mode for unfamiliar code and batch-ac mode for well-understood patterns. I mostly use batch-story and autonomous modes for demos, though they'd suit repetitive work with well-established patterns.

The review skill provides structured feedback:

## Code Review: normal mode

### Blockers (0 found)

### Warnings (2 found)
1. **CustomerService.java:45** Method exceeds 20 lines
   - Consider extracting validation logic

### Suggestions (1 found)
1. **CustomerServiceTest.java:112** Test name could be more specific

### Summary
- Blockers: 0
- Warnings: 2
- Suggestions: 1
- **Verdict**: NEEDS ATTENTION

The autonomous TDD mode uses this skill with configurable thresholds. "Strict" interrupts on any finding. "Relaxed" only stops for blockers.

Hooks

Hooks are event-driven. They run shell commands or LLM prompts at specific lifecycle events: before a tool runs, after a file is written, when Claude asks for permission.

Event	Use Case
`PostToolUse`	Auto-format files after writes
`PreToolUse`	Block sensitive operations
`UserPromptSubmit`	Validate prompts before execution

Example: auto-format with Prettier after every file write:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$FILE_PATH\""
      }]
    }]
  }
}

The credit-card-lending project doesn't use hooks yet. They're next on the list.

Other Primitives

Claude Code has additional constructs I haven't used in this project:

Primitive	What It Does	When to Use
Subagents	Specialized delegates with separate context	Complex multi-step tasks, context isolation
MCP	External tool integrations	Database access, APIs, custom tools
Output Styles	Custom system prompts	Non-engineering tasks (teaching, writing)
Plugins	Bundled primitives for distribution	Team-wide deployment

Start with commands, skills, and context docs. Add the others as your needs grow.

Level 2: Context Documentation

Context is what the AI knows about your project. I've seen teams underinvest here. They write a README and call it done, then wonder why AI assistants keep making the same mistakes.

What's missing is your engineering culture. The hardest part isn't the tools, it's capturing what your team actually does. For example, code reviews are hard because most time goes to style, not substance. "Why isn't this using our logging pattern?" "We don't structure tests that way here." Without codification, AI applies its own defaults. The code might work, but it doesn't feel like your code.

When you codify your team's preferences, AI follows YOUR patterns instead of its defaults. Style debates shift left: instead of the same argument across a dozen pull requests, you debate once over a document. Once the document reflects consensus, it's settled.

What to Document

I've settled on this structure:

File	Purpose
`overview.md`	Architecture, tech stack, module boundaries
`conventions.md`	Code patterns, naming, git workflow
`testing.md`	TDD approach, test structure, tooling
`glossary.md`	Domain terms with precise definitions
`current-state.md`	What's built vs planned
`domain/*.md`	Business rules for each domain
`modules/*.md`	Technical details for each module

The credit-card-lending project extends this with integrations.md (external systems) and metrics.md (measuring iE effectiveness). Adapt the structure to your domain's needs.

These docs exist for both AI and human consumption, but discoverability matters. New team members shouldn't have to hunt through docs/context/ to understand what exists. The credit-card-lending project solves this with a /tour command: run it and get an AI-guided walkthrough covering architecture, conventions, testing, and domain knowledge. This transforms static documentation into an interactive onboarding flow. Context docs become working tools, not forgotten reference material.

Context Doc Anatomy

Every context doc starts with "Why Read This?" and prerequisites:

# Testing Strategy

## Why Read This?

TDD principles, test pyramid, and testing tools.
Read when writing tests or understanding the test approach.

**Prerequisites:** conventions.md for code style
**Related:** domain/ for business rules being tested

---

## Philosophy

We practice Test-Driven Development as our primary approach.
Tests drive design and provide confidence for change.

This helps AI tools (and humans) know whether they need this file and what to read first.

Dense facts beat explanatory prose. Compare:

"Our testing philosophy emphasizes the importance of test-driven development. We believe that writing tests first leads to better design..."

vs.

"TDD: Red-Green-Refactor. Tests before code. One assertion per test. Naming: should{Expected}_when{Condition}."

The second version is what AI tools need. Save the narrative for human-focused documentation.

Living Documentation

Stale documentation lies confidently. It states things that are no longer true. You write tests to catch broken code. Your documentation needs the same capability.

The credit-card-lending project handles this two ways:

Definition of Done includes context updates: Every story card lists which context docs to review. The AI won't let you forget. You can bypass it by working without your AI pair or deleting the prompt, but the default path nudges you toward keeping docs current.
Drift detection: A /check-drift command compares docs against code

The second point catches what the first misses. I've seen projects where features get built but current-state.md still shows them as planned. Regular drift checks catch this before it causes confusion.

Patterns for Teams

The examples above work within a single repository. At team and org level:

Shared context repository: A company-wide repo with organization-level conventions, security requirements, architectural patterns. Each project references it but can override.

Team-level customization: Team-specific CLAUDE.md additions for their domain, their tools, their workflow quirks.

Prompt library: Reusable prompts for common tasks. "Review this PR for security issues" with the right context attached.

Level 1: Foundation

The foundation is what the AI sees when it first encounters your project.

CLAUDE.md

This is your project's instruction manual for AI assistants. It goes in the repository root and contains:

Project context: What this is, what it does
Git workflow: Commit conventions, branching strategy
Context file references: Where to find domain knowledge, conventions, architecture
Tool-specific instructions: Commands, scripts, common tasks

Here's an excerpt from the credit-card-lending CLAUDE.md:

# CLAUDE.md

## Project Context
Credit card lending platform built with Java 25 and Spring Boot 4.
Modular monolith architecture with clear module boundaries.

## Git Workflow
- Trunk-based development: push to main, no PRs for standard work
- Small commits (<200 lines) with descriptive messages
- Reference issue numbers in commits

## Context Files
Read these before working on specific areas:
- `docs/context/overview.md` - Architecture and module structure
- `docs/context/conventions.md` - Code standards and patterns
- `docs/context/testing.md` - TDD principles and test strategy

CLAUDE.md is dense and factual, not explanatory. It tells the AI what to do, not why. The "why" lives in context docs.

Project Structure

Structure matters because AI tools use file paths to understand context. I've found this layout works well:

project/
├── CLAUDE.md                    # AI instruction manual
├── .claude/
│   ├── commands/                # User-invoked slash commands
│   └── skills/                  # Model-invoked capabilities
├── docs/
│   ├── context/                 # Dense reference documentation
│   │   ├── overview.md
│   │   ├── conventions.md
│   │   ├── testing.md
│   │   └── domain/
│   ├── wiki/                    # Narrative documentation
│   └── adr/                     # Architectural decisions
└── src/                         # Your code

The separation between context/ (for AI consumption) and wiki/ (for humans) is intentional. Context docs are dense facts. Wiki pages explain concepts with diagrams and narrative. ADRs (Architectural Decision Records) capture why significant decisions were made. This context prevents future teams from wondering "why did they do it this way?"

Takeaways

The credit-card-lending repository demonstrates everything discussed above. Here's what I learned applying it.

What Worked

Small batches: Most commits are under 100 lines. This makes review meaningful and rollbacks clean.

Context primacy: The AI reads conventions.md before writing code. It knows our test naming patterns, package structure, and error handling approach without me repeating it.

TDD skill with review modes: Interactive mode for complex validation logic. Batch-ac mode for straightforward CRUD operations.

Living documentation: Every completed story updates current-state.md. I know what's built by reading one file.

What We Learned

Context docs need maintenance: Early on, I'd update code without updating context docs. The AI would then generate code following outdated patterns. The /check-drift command catches this now.

Skills are better than scripts: I started with bash scripts for workflows. Moving to skills let the AI adapt to context instead of following rigid steps.

Design discussion matters: Agreeing on approach before coding feels slow. In reality, it saves rework.

Getting Started

Ready to try this? Here's a path:

If You're Starting Fresh

Create CLAUDE.md with your project context
Add docs/context/conventions.md with your coding standards
Start with one command: /start-dev for TDD workflow
Add context docs as you need them

If You Have an Existing Project

Create CLAUDE.md capturing how you want the project worked on
Document your most important conventions
Add the /update-context command so documentation stays current
Gradually expand context as you work

Try It Yourself

Clone the example repository and explore:

git clone https://github.com/javatarz/credit-card-lending
cd credit-card-lending

Run /tour to get an interactive walkthrough of the project structure, setup, and key concepts. Then try /pickup to see available work or /start-dev to see TDD in action.

The branch blog-ie-setup-jan2025 contains the exact state referenced in this post.

What's Next

If you try this approach, I'd like to hear what works and what doesn't. The practices here evolved from experimentation. They'll keep evolving.

Credits

The intelligent Engineering framework was developed in collaboration with Anand Iyengar and other Sahajeevis. It was originally published on the Sahaj website.

intelligent Engineering: A Skill Map for Learning AI-Assisted Development

Karun Japhet — Thu, 01 Jan 2026 05:58:05 +0000

Principles are useful, but they don't tell you what to practice.

In my previous post on intelligent Engineering principles, I outlined the ideas that guide how I build software with AI. Since then, I've had people ask: "Where do I start? What skills should I build first?"

This post answers that: a map of the skills that make up intelligent Engineering, organised into a learning path you can follow whether you're an individual contributor looking to level up or a tech leader building your team's AI fluency.

What is intelligent Engineering?

intelligent Engineering is a framework for integrating AI across the entire software development lifecycle, not just code generation.

Writing code represents only 10-20% of software development effort. The rest is research, analysis, design, testing, deployment, and maintenance. intelligent Engineering applies AI across all of these stages while keeping humans accountable for outcomes.

I've already written about the five core principles in detail. This post focuses on the skills that make those principles actionable.

The Skill Map

Master the skills at each stage before moving to the next. Skipping ahead creates gaps that AI will expose.

1. Foundations

The 2025 DORA report confirmed what many suspected: AI amplifies your existing capability, magnifying both strengths and weaknesses.

If your fundamentals are weak, AI won't fix them. It will make the cracks more visible, faster.

This map assumes you already have solid computer science fundamentals: data structures, algorithms, and an understanding of how systems work (processors, memory, networking, databases, etc.). AI doesn't replace the need to know these.

Version control fluency

Git workflows, meaningful commits, safe experimentation with branches. AI generates code quickly. If you can't safely integrate and roll back changes, you'll spend more time cleaning up than you save.

How to build this:

If you haven't used branches and pull requests regularly, start a side project that forces you to
Read Pro Git (free online) - chapters 1-3 cover the essentials
Learn git worktrees - you'll need them for multi-agent workflows in the Advanced section

Testing fundamentals

The test pyramid still applies. Unit, integration, end-to-end. AI can generate tests, but knowing which tests matter, when to push tests up or down the pyramid, and reviewing their quality is your job. Build intuition for what belongs at each layer.

How to build this:

Practice writing tests before code (TDD) on a small project
Read Test-Driven Development: By Example by Kent Beck, the foundational TDD book
Read Growing Object-Oriented Software, Guided by Tests by Steve Freeman and Nat Pryce for TDD in practice
Apply Martin Fowler's test pyramid rule: if a unit test covers it, don't duplicate at higher levels. Push tests down: unit test business logic, integration test service interactions, end-to-end only for critical user paths

Code review discipline

You'll review more code than ever. AI-generated code often looks plausible but handles edge cases incorrectly. Strengthen your eye for subtle bugs.

What to watch for in AI-generated code:

Security vulnerabilities: SQL injection, unsafe data handling, hardcoded secrets. AI often generates patterns that work but aren't secure.
Edge cases: Null handling, empty collections, boundary conditions. AI tends to handle the happy path well but miss edge cases.
Business logic errors: AI can't understand your domain. Verify that the code does what the business actually needs, not just what the prompt described.
Architectural violations: Does the code respect your layer boundaries? Does it follow your ADRs? AI doesn't know your architectural constraints unless you tell it.
Code smells: Duplicated logic, overly complex methods, inconsistent patterns. AI doesn't always match your codebase conventions.
Hallucinated APIs: Functions or methods that look real but don't exist. Always verify imports and dependencies.

How to build this:

Review pull requests on open source projects you use
Read Code Review Guidelines from Google's engineering practices
Practice the "trust but verify" mindset: assume AI code needs checking, not approval

Code quality intuition

Can you recognize maintainable, clean code vs technically-correct-but-messy? AI generates code fast. If you can't tell good from bad, you'll accept garbage that costs you later.

How to build this:

Read Clean Code by Robert Martin
Refactor old code you wrote, or practice on clean code katas - notice what makes code hard to change

Documentation practices

Documentation becomes AI context. Quality documentation into the system means quality AI output. Poor docs mean the AI hallucinates or makes wrong assumptions.

How to build this:

Document a project you're working on as if a new teammate needs to understand it
Read Docs for Developers for practical guidance

Architecture understanding

Data flow, component boundaries, dependency management. AI tools need you to describe constraints clearly. If you don't understand the architecture, you can't provide good context.

How to build this:

Draw architecture diagrams for systems you work with
Read Fundamentals of Software Architecture by Richards and Ford for trade-offs and patterns
Read Designing Data-Intensive Applications by Kleppmann for distributed systems and data architecture
For microservices specifically, read Building Microservices by Sam Newman

2. AI Interaction

The skills specific to working with AI systems. You're learning to communicate with a system that's capable but context-limited, confident but sometimes wrong.

Prompt engineering basics

Specificity matters. Vague requests get vague results.

Bad prompt:

Write a function to parse dates

Good prompt:

Write a Python function that:
- Parses ISO 8601 date strings (e.g., "2025-12-31T14:30:00Z")
- Handles timezone offsets
- Returns None for invalid input
- Include docstring and type hints

The difference isn't cleverness - it's precision.

Key techniques:

Technique	What It Is	When to Use
Specificity	Precise requirements over vague requests	Always - the biggest lever
Few-shot prompting	Show 1-3 examples of input → output	Team patterns, consistent formatting
Chain of thought	"Think step-by-step: analyze, identify, explain, then fix"	Debugging, complex reasoning
Role prompting	"Act as a senior security engineer reviewing for vulnerabilities"	When expertise framing helps
Meta prompting	Prompts that generate or refine other prompts	Org-level standards, team templates
Explicit constraints	"Don't use external libraries. Keep it under 50 lines."	Avoiding common failure modes

Few-shot example:

Convert these function names from camelCase to snake_case:

Example 1: getUserById -> get_user_by_id
Example 2: validateEmailAddress -> validate_email_address

Now convert: fetchAllActiveUsers

Chain of thought example:

Debug this function. Think step-by-step:
1. What is this function supposed to do?
2. Trace through with input X - what happens at each line?
3. Where does the actual behavior differ from expected?
4. What's the fix?

How to build this:

Spend a week being deliberate about prompts. Write down what you asked, what you got, and what you wish you'd asked.
Read Anthropic's Prompt Engineering Guide
Reference promptingguide.ai for comprehensive techniques

Context engineering

A clever prompt won't fix bad context. Context engineering is about curating what information the model sees: project constraints, coding standards, relevant examples, what you've already tried.

This is the 80% of the skill. Prompt engineering is maybe 20%.

I've written a detailed guide on this: Context Engineering for AI-Assisted Development.

How to build this:

Create a project-level context file (e.g., CLAUDE.md) for your current codebase
Add coding standards, architectural constraints, common patterns
Notice when AI output improves because of better context

Understanding model behaviour

You don't need to become an ML engineer, but knowing the basics helps.

What to understand:

Concept	Why It Matters
Context windows	Why your 50-file codebase overwhelms the model. Why it "forgets" earlier instructions. (Anthropic's context window docs)
Training data & fine-tuning	Why Claude excels at code review. Why some models are verbose, others concise.
Knowledge cutoff	Why the model doesn't know about libraries released last month.
Hallucinations	Models confidently generate plausible-looking nonsense. Verify APIs exist. Test edge cases.
Cost per token	Why Opus is expensive for exploration but worth it for complex reasoning. (Anthropic pricing)

Model strengths (from my experience):

Model	Strengths
Claude	Thoughtful about edge cases, good at following complex instructions, strong code review
GPT	Fast, good at general tasks, wide knowledge
Gemini	Larger context windows, good at multimodal tasks

These observations come from my own work. Models evolve quickly - what's true today may change next quarter.

How to build this:

Try the same task with different models. Note where each excels.
Read model release notes when new versions come out
Track which models work best for your common tasks

Understanding tool behaviour

Here's something that trips people up: the same model behaves differently in different tools.

Cursor's Claude is not the same as Claude Code's Claude is not the same as Windsurf's Claude. Why? Each tool wraps the model with its own system prompt.

Aspect	Model Nuances (Intrinsic)	Tool Nuances (Extrinsic)
What it is	Differences baked into the model itself	Differences from how the tool wraps the model
Examples	Context window, reasoning style, training data, cost	System prompts, UI, context injection, available commands
What to learn	Model strengths for different tasks	How your tool injects context, what its system prompt optimizes for

This means: instructions that work well in Claude Code might not work the same in Cursor, even with the same underlying model. The tool's system prompt and context injection change the behavior.

How to build this:

Try the same prompt in multiple tools. Notice the differences.
Read your tool's documentation on how it manages context
Understand what your tool's system prompt optimizes for (coding, conversation, etc.)

3. Workflow Integration

Making AI a standard part of how you build software, not a novelty you occasionally use.

Tool configuration

Configure your AI tools for your team's context. This isn't a one-time setup. Rules files need tuning. Context evolves. Tools update frequently.

Each tool has its own configuration mechanism:

Claude Code uses CLAUDE.md files
Cursor uses rules
Windsurf uses memories

Instructions that work in one tool won't transfer directly to another because system prompts differ.

How to build this:

Document your configuration so teammates can get productive quickly
Review and update configuration monthly as tools evolve

Specs-before-implementation

Define what to build before AI generates code. AI generates code that matches a spec well. It struggles to determine what the spec should be.

Write the spec first - acceptance criteria, edge cases, constraints. Then let AI implement.

How to build this:

Practice writing specs for features before touching code
Include: what it should do, what it shouldn't do, edge cases to handle

Test-driven mindset with AI

Write tests first. Let AI implement to pass them. This flips the usual flow: instead of "generate code, then test it", you "define the contract, then fill it in."

The tests become your spec. When AI has an executable target (tests that must pass), it produces better code than when interpreting prose requirements.

How to build this:

Try TDD on a small feature: write failing tests, then ask AI to make them pass
Review the generated code - does it just satisfy the tests or is it actually good?

Human review gates

AI-generated code requires the same (or stricter) review as human-written code. Build the habit of treating AI output like code from a confident junior developer: often correct, sometimes subtly wrong, occasionally completely off base.

How to build this:

Set a personal rule: no AI-generated code merged without reviewing every line
Track your AI acceptance rate. If you're accepting >80% without modification, you might be over-trusting.

Small batches

Generate less, review more. A 1000-line AI diff is harder to review than a 100-line one. Work in small chunks. Commit often.

How to build this:

Break tasks into steps that produce <200 lines of change
Commit after each step passes review

Quality guardrails

Integrate linting, static analysis, and security scanning into your workflow. These catch issues AI introduces. Shift left. Catch problems early.

How to build this:

Set up pre-commit hooks for linting and formatting
Add security scanning to CI (e.g., Snyk, Semgrep)

Living documentation

Documentation updated atomically with code changes. When code changes, docs change in the same commit. This keeps your AI context current.

How to build this:

Include doc updates in your definition of done
Review PRs for documentation staleness

4. Advanced / Agentic

Skills for autonomous AI workflows. These are powerful but risky - more autonomy needs stronger guardrails.

Agentic workflow design

Tools like Claude Code, Cursor, and Windsurf can run shell commands, edit files, and chain actions. Know what your tool can do and design workflows that leverage it.

How to build this:

Start with supervised agents - review each step before allowing the next
Read Claude Code's GitHub Actions integration for CI/CD examples

Task decomposition

Break complex work into subtasks an agent can handle. Good decomposition is a skill in itself. Too big and the agent loses focus. Too small and you spend all your time orchestrating.

How to build this:

Practice breaking features into agent-sized tasks (~30 min of work each)
Notice which decompositions lead to better agent output

Guardrails for agents

More autonomy needs stronger guardrails. Sandboxing, approval gates, rollback procedures. Agents make mistakes. Build systems that catch them.

How to build this:

Never give agents write access to production
Implement approval gates for destructive operations

Engineering culture codification

Turn your team's standards, patterns, and guidelines into structured artifacts that AI can use. This is how you scale intelligent Engineering beyond individuals.

When you document coding standards, architectural patterns, and review checklists in a format AI can consume, every team member (and AI tool) operates from the same playbook.

How to build this:

Start with a CLAUDE.md (or equivalent) that captures your team's conventions
Add architectural decision records (ADRs) that AI can reference

Multi-agent orchestration

Running parallel agents (e.g., using git worktrees). Coordinating results. This is emerging territory.

How to build this:

Try running two agents on independent tasks
Notice coordination challenges and develop patterns for handling them

CI/CD integration

Running AI reviews on pull requests. Automated code analysis. Scheduled agents for maintenance tasks.

How to build this:

Set up Copilot code review or similar on your repo
Start with comment-only (no auto-merge) until you trust it

Learning Paths

Not everyone starts from the same place.

For Developers New to AI Tools

Start here: Foundations + AI Interaction basics

Get comfortable with one AI tool. GitHub Copilot is a good starting point for its low cost and tight editor integration. For open source alternatives, try Aider or OpenCode.
Spend 2-4 weeks using it for completion and simple generation.
Practice prompting: be specific, iterate, learn what works.
Move to a more capable tool (Claude Code, Cursor, Windsurf) once you're comfortable.
Build your first context file.

Expected ramp-up: 4-8 weeks to feel productive.

For Developers Experienced With AI

Start here: Workflow Integration + Advanced

Audit your current workflow. Where are you using AI effectively? Where are you over-trusting?
Strengthen context engineering. Create comprehensive project context files.
Set up guardrails: linting, security scanning, review checklists.
Experiment with agentic workflows under supervision.
Integrate AI into CI/CD.

Expected ramp-up: 2-4 weeks to significantly improve your workflow.

For Tech Leaders Building Team Capability

Whether you're a Tech Lead, Engineering Manager, Principal Engineer, or anyone else responsible for growing your team's capability, this section is for you.

Start here: The 2025 DORA AI Capabilities Model

The report identified seven practices that amplify AI's positive impact:

Clear AI stance: Establish expectations for how your team uses AI.
Healthy data ecosystem: Quality documentation enables quality AI outputs.
Strong version control: Rollback capability provides a safety net for experimentation.
Small batches: Enable quick course corrections.
User-centric focus: Clear goals improve AI output quality.
Quality internal platforms: Standardised tooling scales AI benefits.
AI-accessible data: Make context available to AI tools.

Actions:

Assess your team against these practices. Where are the gaps?
Don't change everything at once. Introduce AI at one delivery stage at a time.
Expect a learning curve: 2-4 weeks of reduced productivity before gains appear.
Invest in guardrails before acceleration.
Measure impact with DORA metrics: deployment frequency, lead time, change failure rate, time to restore.

Common Pitfalls

Starting with advanced tools: If you skip fundamentals, you'll produce more code, faster, with worse quality. The problems compound.

Ignoring context engineering: Most teams spend all their energy on prompt engineering. Context engineering matters far more. Good context makes mediocre prompts work; perfect prompts can't fix missing context. And context scales: set it up once, benefit every interaction.

Over-trusting AI: "The AI suggested it" is not an acceptable answer in a post-mortem. You're accountable for what ships.

Under-trusting AI: Some developers refuse to adopt AI tools, treating them as a passing fad. The productivity gap is real. Healthy skepticism is fine, but refusing to engage is risky. For tech leaders: DORA's research on AI adoption shows that addressing anxieties directly and providing dedicated exploration time significantly improves adoption.

No guardrails: AI makes it easy to move fast. Without automated quality checks, you'll ship bugs faster too. Smarter AI needs smarter guardrails. If you don't have linting, security scanning, and CI checks, add them before increasing your AI usage. For legacy codebases without tests, start with characterization tests to capture current behaviour before refactoring. Michael Feathers' Working Effectively with Legacy Code is the definitive guide here. AI can accelerate this process, but verify every generated test passes against the real system without any changes to production code.

Confusing model and tool behaviour: When AI output is wrong, is it the model's limitation or the tool's system prompt? Knowing the difference helps you fix it. To diagnose: try the same prompt in a different tool or the raw API. If the problem persists across tools, it's likely a model limitation. If it only happens in one tool, check how that tool injects context.

Trying to measure productivity improvement without baselines: You can't prove AI made your team faster if you weren't measuring before. Worse, once estimates become targets for measuring AI impact, developers adjust their estimates (consciously or not). Skip the productivity theatre. Instead, measure what matters: features shipped, customer value delivered, time from idea to production, team satisfaction.

What's Next

This skill map is a snapshot. The tools evolve weekly. New capabilities emerge monthly.

If you're on this journey, I'd like to hear what's working for you. What skills have I missed? What resources have you found valuable?

Coming up: Putting these skills into practice. I'll walk through setting up intelligent Engineering on a real project, covering tool configuration, context files, and workflow patterns that work.

Context Engineering for AI-Assisted Development

Karun Japhet — Thu, 01 Jan 2026 05:57:49 +0000

Same model, different tools, different results.

If you've used Claude Sonnet in Claude Code, Cursor, Copilot, and Windsurf, you've noticed this. The model is identical, but the behavior varies. This isn't magic. It's context engineering.

In intelligent Engineering: Principles for Building With AI, I mentioned that "context is everything" and that "context engineering matters more than prompt engineering." But I didn't explain what that means or how to do it. This post fills that gap.

The Whiteboard

Imagine you're in a day-long strategy meeting. There's one whiteboard in the room. That's all the shared space you have.

Your teammate is brilliant. They can see everything on the board and reason about it. But here's the thing: they have no memory outside this whiteboard. What's written is all they know. Erase something, and it's gone.

Before the meeting started, someone wrote ground rules at the top: "Focus on Q1 priorities. Be specific. No tangents." This section doesn't get erased. It frames everything that follows. (That's the system prompt.)

The meeting begins. You add notes, diagrams, decisions. The board fills up. You need to add something new, but there's no space. What do you erase? The detailed debate from 9am, or the decision it produced? You keep the decision, erase the discussion. (That's compaction.)

Three hours in, you notice something odd. Your teammate keeps referencing the top and bottom of the board, but seems to miss what's in the middle. Important context from 10:30am is right there, but they're not looking at it. The middle of the board gets less attention.

Someone raises a topic that needs last quarter's data. Do you copy the entire Q4 report onto the board? No. You flip open your notebook, find the one relevant chart, add it to the board, discuss it, then erase it when you move on. (That's just-in-time retrieval.) The notebook stays on the table. You reference it when needed, but it doesn't consume board space.

By afternoon, old notes are causing problems. A 9am assumption turned out to be wrong, but it's still on the board. Your teammate keeps building on it. The board is poisoned with outdated information. You need to actively clean it up.

There's too much on the board now. Some notes are written in shorthand. Others are cramped into corners with tiny handwriting. Your teammate can technically see it all, but finding anything takes effort. Attention is diluted. (That's context distraction.)

For a complex sub-problem, you send two people to side rooms with fresh whiteboards. They work independently, then return with one-page summaries. You add the summaries to your board and integrate the findings. You never needed their full whiteboards. (That's sub-agents.)

The whiteboard is your teammate's entire context window. What's on it is all they can work with. Your job is to curate what goes on the board so they can focus on what matters.

What This Means Technically

The whiteboard story maps directly to how AI models process information.

System Prompts vs User Prompts

The ground rules at the top of the board are the system prompt. You didn't write them. They were there when you walked in, set by whoever built the tool. They define how the model behaves, what it prioritizes, what it can do.

What you add during the meeting is the user prompt. Your requests, your context, your questions. It works within the frame the system prompt establishes.

The model sees both. But system prompts carry more weight because they come first and set expectations.

The Context Window

The whiteboard's physical dimensions are the context window. There's a fixed amount of space. Everything competes for it: system instructions, conversation history, files you've pulled in, tool definitions, and the model's own output. When it fills up, something has to go.

Lost in the Middle

Remember how your teammate focused on the top and bottom of the board but missed the middle? That's a real phenomenon. Research shows a U-shaped attention curve: information at the start and end of context gets more attention than information in the middle.

This means:

Cramming everything into context can hurt performance
Position matters: put important information first or last
As context grows, accuracy often decreases

In Patterns for AI-assisted Software Development, I described LLMs as "teammates with anterograde amnesia." They can hold information, but only within the context window. Understanding how to manage that window is key.

The Attention Budget

Even with everything visible on the board, your teammate can only actively focus on so much while reasoning. Each item costs attention. Add more, and something else gets less focus. Think of it as a budget: every token you add depletes some of the model's capacity to focus on what matters.

How Different Tools Set Up the Room

Here's why the same model behaves differently across tools: different rooms have different ground rules at the top of the board.

Take Claude Sonnet 4.5. Same teammate. But put them in different rooms:

Room (Tool)	Top of the board says
Claude Code	"Work autonomously. Read files, run terminal commands, complete multi-step tasks."
Cursor	"Stay in the editor. Complete code inline, understand the open file, suggest edits."
Copilot	"Autocomplete as they type. Quick suggestions, stay out of the way."
Windsurf	"Maintain flow. Remember preferences across sessions, keep continuity."

Your teammate reads the top of the board and behaves accordingly. That's why the same model feels different in each tool. The system prompt shapes everything.

This also explains why prompts don't transfer directly between tools. A prompt that works well in Claude Code might fail in Cursor because the framing is different.

What Goes Wrong

When context fails, it fails in predictable ways. Recognizing these patterns helps you diagnose problems.

Context Poisoning

Early errors compound. Your teammate builds on incorrect assumptions, reinforcing mistakes with each exchange. By the time you notice, the board is thoroughly polluted with wrong information.

Fix: Use backtrack to undo recent turns. Claude Code, Cursor, and Windsurf all support this. If the pollution runs deeper, compact to summarize past the bad section. Clear is the nuclear option when context is unsalvageable.

Context Distraction

Too much information competes for attention. The model can technically process it all, but signal gets lost in noise.

On the whiteboard: shorthand, tiny writing, notes crammed into corners. Your teammate can see it all, but finding anything takes effort.

Fix: Keep context lean. Compact proactively. Don't dump everything onto the board.

Context Confusion

Mixed content types muddle the model's understanding. Code snippets, prose explanations, JSON configs, and error logs all blur together. The model can't distinguish what's an instruction versus an example versus context.

On the whiteboard: sticky notes, diagrams, tables, arrows, different colored markers. Your teammate can't parse what type of information to use for what purpose.

Fix: Use focused tools. Don't overload the board with too many formats or capabilities.

Context Clash

Contradictory instructions coexist. "Prioritize speed" in one corner. "Prioritize quality" in another. Your teammate sees both, doesn't know which to follow, and produces something incoherent.

Fix: Keep instructions centralized and current. Review your context files periodically for contradictions.

Managing Context Well

Five techniques make a difference.

Just-in-Time Retrieval

Don't paste your whole codebase onto the board. Reference specific files and let the tool search.

Bad: "Here's my entire src/ directory. Now fix the bug."
Good: "There's a bug in the date parser. Check src/utils/dates.ts."

The notebook stays on the table. You flip it open when needed, find the relevant page, add it to the discussion, then move on.

Compaction

Context fills up during long sessions. Compaction summarizes conversation history, preserving key decisions while discarding noise.

When to compact:

After completing a major task (before starting the next one)
During long sessions when you notice drift
Before context hits limits (proactively, not reactively)

You can provide custom instructions when compacting: "focus on architectural decisions" or "preserve the error messages we encountered." This guides what gets kept versus summarized away.

My preference hierarchy:

Small tasks with /clear - fresh context beats compressed context
Early compaction with custom instructions - you control what matters
Early compaction with default prompt - still gives thinking room
Late compaction - avoid this

Late compaction (waiting until 95% capacity) is the worst option. The model has no thinking room, and the automatic summarization is opaque. You lose nuance without knowing what disappeared. Early compaction, ideally with custom instructions, gives you control and leaves space for the model to reason. Steve Kinney's guide to Claude Code compaction covers the mechanics well.

Structured Note-Taking

For complex, multi-hour work, maintain notes outside the conversation:

A NOTES.md file tracking progress
Decision logs capturing why you chose specific approaches
TODO lists that persist across compactions

The model can reference these files when needed, but they're not consuming context constantly. The notebook on the table, not copied onto the board.

Sub-Agents

For large tasks, send people to side rooms with fresh whiteboards:

Main agent coordinates the overall task
Sub-agents handle specific, focused work with clean context
Sub-agents return condensed summaries
Main agent integrates results without carrying full sub-task context

This mirrors how teams work: delegate, get summaries, integrate. Claude Code supports this pattern for parallel issue work using git worktrees.

Tool-Specific Tips

Each tool has different mechanisms for managing what goes on the board.

Claude Code:

CLAUDE.md files load automatically at session start. Keep them focused and current.
Hierarchical loading: user-level, project-level, directory-level. More specific overrides more general.
Trust the tool's search. Don't paste file contents manually unless retrieval fails.
Use /compact between logical units of work.

Cursor:

Rules files inject instructions with different scopes: global, project, file-type specific.
Use @-mentions deliberately. More files isn't better; relevant files are better.
Keep rule files short. They add to every interaction.

Copilot:

Lighter touch. Works best for autocomplete and quick suggestions.
Less configurable context, so prompt quality matters more.

Windsurf:

Memories persist across sessions automatically.
Good for maintaining preferences and patterns over time.

Aider, Cline, and similar terminal-based tools follow the same principles. Different mechanisms, same underlying constraints. For a deeper comparison, see How to choose your coding assistants.

The Core Principle

Anthropic's engineering team puts it well in their guide to context engineering:

Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.

More context isn't better. Relevant context is better. Your job is to curate what goes on the board so your teammate can focus on what matters.

Context drives quality. But "quality context" doesn't mean volume. It means signal: information the model needs to reason correctly. Everything else dilutes attention.

What's Next

Context engineering is a skill that develops with practice. Start by noticing when your tools perform well and when they drift. Ask why. Usually, the answer is in the context.

Take a few minutes to examine how your tool handles context. Where do instructions go? How do files get included? What happens during long sessions?

Understanding this is the difference between fighting your tools and working with them.

Coming up: Context engineering is one piece of the puzzle. In intelligent Engineering: A Skill Map for Learning AI-Assisted Development, I map out the full landscape of skills worth building.

intelligent Engineering: Principles for Building With AI

Karun Japhet — Sat, 27 Dec 2025 17:46:56 +0000

Software engineering is changing. Again.

I've spent the last two years applying AI across prototyping, internal tools, production systems, and team workflows. I've watched it generate elegant solutions in seconds and confidently produce complete nonsense. I've seen it save hours on boilerplate and cost hours debugging hallucinated APIs.

One thing has become clear: AI doesn't make engineering easier. It shifts where the hard parts are.

The teams I've seen succeed with AI aren't the ones using it everywhere. They're the ones using it deliberately, knowing when to trust it, when to verify, and when to ignore it entirely.

Here's a working set of principles I've found useful. They aren't finished and will evolve with the tools. But they help keep me grounded in what actually matters.

intelligent Engineering Principles

These principles fall into two buckets: what is new, and what remains timeless but more important than ever.

AI-Native Principles

These principles exist because of AI. They address challenges that didn't matter before.

AI augments, humans stay accountable.

AI can help you move faster and see options you'd miss on your own. But it can't own the outcome. Engineering judgment stays with you. When something breaks in production, "the AI suggested it" isn't an acceptable answer.

Context is everything.

AI output reflects what you put in. Vague requests get vague results. Bring useful context: project constraints, coding standards, relevant examples, what you've already tried.

As systems grow, context management becomes a discipline of its own. How do new teammates get AI tools primed with the right information? How do you keep that context current? When context exceeds what fits in a prompt, you'll need solutions like modular documentation.

Smarter AI needs smarter guardrails.

Faster generation demands sharper review. AI-produced code still needs validation: Is it correct? Secure? Does it solve the right problem?

Shape AI deliberately.

I've seen teams adopt whatever AI tools are trending without asking whether they fit. Six months later, half the codebase assumed Copilot's import ordering, onboarding docs referenced prompts that no longer worked, and no one remembered why. Decide upfront: where does AI help us? Where does it not? What happens when we switch tools?

Learning never stops.

At the start of 2025, AI practices evolved weekly. By year's end, monthly. That's still faster than most teams are used to. What didn't work three months ago might work now. The only way to know is to keep experimenting.

I've settled on 90% getting work done, 10% experimenting. Try new ways to solve the same problem. Revisit old problems to see if there's a simpler solution now. Check if techniques you learned last quarter still make sense.

Timeless Foundations

These aren't new, but AI makes them more important.

Learn fast, adapt continuously.

Start small, validate often, and shorten feedback loops. If an AI-assisted workflow isn't helping, change it. Don't let sunk cost keep you on a bad path.

Fast doesn't mean good.

AI makes it easy to generate code fast. That doesn't mean the code is worth keeping. Unmaintainable, insecure, or rigid solutions cost more than they save. Build the right thing, not just the quick thing.

What This Looks Like in Practice

Here's what this means day-to-day:

I use AI to draft implementations, then spend more time reviewing than I saved generating. The review is where the real work happens.
When AI suggests an approach, I ask "why?" If I can't explain the choice to a teammate, I don't use it.
I've learned to be specific. "Write a function to parse dates" gets garbage. "Parse ISO 8601 dates, handle timezone offsets, return None for invalid input" gets something useful.
I treat AI output like code from a confident junior developer: often correct, sometimes subtly wrong, occasionally completely off base.

The craft hasn't changed. I still need to understand the problem, reason about edge cases, and take responsibility for what ships.

Skills Worth Building

Principles guide decisions. Skills make them possible.

Here's what I've found worth investing in:

Context engineering matters more than prompt engineering. A clever prompt won't fix bad context. I spend more time curating what information the model sees than crafting how I ask for things. Project documentation, coding standards, relevant examples. These matter more than prompt tricks.

Understanding tokens and context windows helps. You don't need to become an ML engineer. But it helps to know why your 50-file codebase overwhelms the model, or why it "forgets" earlier instructions.

Agentic workflow primitives matter more than AI theory. You won't build RAG systems from scratch. You'll use tools with these built in. What matters is configuring them: hooks that customize behavior, skills that extend capabilities, context management that keeps information relevant. I spend more time learning how my tools' hooks work or how to structure context files than reading ML papers.

For a comprehensive guide to building these skills, see A Skill Map for Learning AI-Assisted Development.

Why This Matters

I've seen what happens when teams adopt AI without thinking it through. Prototypes that demo well but collapse under real load. Codebases where no one understands why decisions were made because "the AI suggested it." Bugs that take days to track down because the generated code looked plausible but handled edge cases incorrectly.

The failure mode isn't dramatic. It's slow erosion: teams that gradually stop reasoning deeply because the model provides answers quickly.

The alternative isn't avoiding AI. It's using it with intention. The engineers I've seen do this well have gotten faster and more thoughtful. They use AI to handle the routine and focus on the hard problems.

What's Next

These principles aren't final. I expect to revise them as tools improve and as I learn what actually works versus what sounds good in theory.

If you're experimenting with AI in your engineering work, I'd be curious to hear what's working for you. What would you add? What would you challenge?

Credits

This blog would not have been possible without the review and feedback from Greg Reiser, George Song and Karthika Vijayan for reviewing multiple versions of this post and providing patient feedback 😀.

This content has been written on the shoulders of giants (at and outside Sahaj).

Level Up Code Quality with an AI Assistant

Karun Japhet — Sat, 27 Dec 2025 17:46:40 +0000

Using AI coding assistants to introduce, automate, and evolve quality checks in your project.

I have talked about teams needing to have a world class developer experience as a pre-requisite for a well functioning team. When teams lack such a setup, the most common response is a lack of time or buy in from stakeholders to build these things. With AI coding assistants being readily available to most developers today, the engineering effort and the cost investment for the business lesser reducing the barrier to entry.

Current State

This post showcases an actual codebase that has not been actively maintained for over 5 years but runs a product that is actively used. It is business critical but did not have the necessary safety nets in place. Let us go through the journey, prompts inclusive, on how to make the code quality of this repository better, one prompt at a time.

The project is a Django backend application that exposes APIs. We start off with a quick overview of the code and notice that there are tests and some documentation but a lack of consistent way to run and test the application.

The Journey

I am assuming you are running these commands using Claude Code (with Claude Sonnet 4 in most cases). This is equally applicable across any coding assistant. Results will vary based on your choices of models, prompts and the codebase.

Setting up Basic Documentation and Some Automation

If you are using a tool like Claude Code, run /init in your repository and you will get a significant part of this documentation.

Can you analyse the code and write up documentation in README.md that
 clearly summarises how to setup, run, test and lint the application.
Please make sure the file is concise and does not repeat itself. 
Write it like technical documentation. Short and sweet.

Next step is to start setting up some automation (like just files) to help make the project easier to use. This will take a couple of attempts to get right but here is a prompt you can start off with

Please write up a just file. I would like the following commands
`just setup` - set up all the dependencies of the project
`just run` - start up the applications including any dependencies
`just test` - run all tests
If you require clarifications, please ask questions. 
Think hard about what other requirements I need to fulfill. 
Be critical and question everything. 
Do not make code changes till you are clear on what needs to be done.

This will give you a base structure for you to modify quickly and get up and running. If you README.md has a preferred way to run the application (locally vs docker), the just will automatically use it. If not, you will have to provide clarification.

Setting up pre-commit for Early Feedback

Let’s start small and build on it.

Please setup pre-commit with a single task to run all tests on every push.
Update the just script to ensure pre-commit hooks are installed locally
 during the setup process.

We probably didn’t need to be this explicit but I find managing context and keeping tasks small mean I move a lot quicker.

Curating Code Quality Tools

Lets begin by finding good tools to use, create a plan for the change and then execute the plan. Start off by moving Claude Code to Plan mode (shift+tab twice)

What's a good tool to check the complexity of the python code this
 repository has and lint on it to provide the team feedback as a 
 pre-commit hook?

It came back with a set of tools I liked but it assumed that the commit will immediately go green. In an existing large codebase with tech debt, this will not happen. Let’s break this down further.

The list of tools you're suggesting sound good. 
The codebase currently will have a very large number of violations. 
I want the ability to incrementally improve things with every commit. 
How do we achieve this?

Creating a Plan

After you iterate on the previous prompt with the agent, you will get a plan that you’ll be happy with. The AI assistant will ask for permission to move forward and execute the plan but before doing so, it will be worth creating a save state. Imagine this as a video game save, if something goes wrong, come back and restore from this point. This also allows you to clear context since everything is dumped to markdown files on disk.

Can you create a plan that is executable in steps?
Write that plan to `docs/code-quality-improvements`.
Try to use multiple background agents if it helps speed up this process.

Give it a few minutes to analyse the code. In my case, the following files were created. README.md says that “Tasks within the same phase can be executed in parallel by multiple Claude Code assistants, as long as prerequisites are met”. You are ready to hit /clear and clear out the context window.

Phase 1 sets up the basic tools, phase 2 configures them, phase 3 focuses on integration and automation and phase 4 adds monitoring and focuses on improving the code quality.

Before executing the plan, I commit the plan (docs/code-quality-improvement). This allows me to track any changes that have been made. When executing the plan, I do not check in the changes made to the plan. This allows me to drop the plan at the end of the process. As a team, we have discussed potentially keeping the plan around as an artifact. To do so, you would have to ask Claude Code to use relative paths (it uses absolute paths when asking for files to be updated in the plan).

Executing the Plan

I would like to improve code quality and I have come up with a plan to do 
so under `docs/code-quality-improvement`.
Can you analyse the plan and start executing it? The `README.md` has a 
quick start section which tasks about how to execute different phases of the 
plan. As you execute the plan, mark tasks as done to track state.

You will notice that Claude Code will add dependencies to requirements-dev.txt and try to run things without installing them. Also, it will add dependencies that do not exist. Stop the execution (by pressing Esc ) and use the following prompt to course correct

For every pip dependency you add to `requirements-dev.txt`, please run 
`pip install`. 
Before adding a dependency to the dependency file, please check if it is 
available on `pip`.

Once phase 1 and phase 2 of the plan are complete, the following files are created and ready to be committed.

When the quality gates are added on phase 3, run the command once to test if everything works and create another commit. After this, I had to prompt it once more to integrate the lint steps into a simplified developer experience.

Please add `just lint` as a command to run all quality checks

Test the brand new lint command and then run a commit. Ask claude code to proceed to phase 4.

You might see Claude Code doubt a plan that it has created. It is a good question because the system is functional but if we prefer the more advanced checks, we should request it pushes on with Phase 4 implementation.

After phase 4, we have a codebase that checks for code quality every time a developer is pushing code. Our repository has pre-commit hooks for linting, runs all quality checks once before pushing. The quality checks will fail if the code added has unformatted files, imports in the wrong order, flake8 lint issues or functions with higher code complexity. It checks this only in the files being touched (because we told it that we had debt that needs to be reduced and all checks will not pass by default)

You still have debt, lets go over fixing this in the next step.

Fixing Existing Debt

Tools like isort can highlight issues and fix them. You should start off running such commands to fix the code. On most codebases, this will touch almost all of the files. The challenge with this is that all the issues that cannot be fixed automatically (like wildcard imports) will need to be fixed manually. This is where you make a choice either to fix issues manually or automatically. If you’re using Claude Code to fix these issues and there is a large number, you’re probably going to pay in upwards of $10 for this session on any decent sized codebase. I recommend moving to GitHub Copilot’s agent to help push down costs here.

Ask your coding assistant of choice to run the lint command and fix the issues. Most of them will stop after 1–2 attempts because the list is large. You can tell it to “keep doing this task till there are no linting errors left. DO NOT stop till the lint command passes”. If your context file (CLAUDE.md) does not talk about how to lint, be explicit and tell your coding assistant what the command to be run is.

What is Left?

If you look at the gradual-tightening task, it created a command to analyse the code and keep being gradually more strict. This command can either be run manually or automatically on a pipeline. One of the parameters it changes is the max-complexity which is set to 20 by default. This complexity will be reduced over a period of time. Similarly, the complexity check tasks have a lower bar to begin with and should be improved periodically to tighten the quality guidelines on this repository.

While our AI coding pair has helped design and improve the code quality to a large extent, the last mile has to be walked by all of our teammates. We now have a strong feedback mechanism for bad code that will fail the pipeline and stop code from being committed or pushed. The last bit requires team culture to be built. On one of my teams, we had a soft check in every retro to see if every member had made the codebase a little bit better in a sprint. A sprint is 10 days and “a little bit” can include refactoring a tiny 2–3 line function and making it better. The bar is really low but the social pressure of wanting to make things better motivated all of us to drive positive change.

Having a high quality codebase with a good developer experience is not a pipe dream and making it a reality is easier than ever with AI coding assistants like Claude Code or Copilot. What have you been able to improve recently? 😃