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:

1. A repo manifest listing every repo, where it lives, and what it does
2. Context files that Claude Code picks up from the directory tree
3. 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:

1. orders/order-service/CLAUDE.md (repo-level, committed in that repo)
2. orders/CLAUDE.md (team-level, committed in bootstrap)
3. 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.

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

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.

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:

1. 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?

2. 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?

3. 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?

4. 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?

5. 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?

6. 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.

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:

1. Break the problem down. Don’t hand the agent a big, vague goal. Decompose it into sub-problems.
2. If a tool exists, use it. Refactoring, formatting, linting, deployment: these are solved problems. Don’t ask the AI to reinvent them.
3. If no tool exists, build one. A small, deterministic script is better than an LLM making judgment calls where none are needed.
4. 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.

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:

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:

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.

The TDD skill is the one I use most:

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

Workflow:

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

Review modes control how much human oversight:

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.

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:

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:

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:

1. 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.
2. 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

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

If You Have an Existing Project

1. Create CLAUDE.md capturing how you want the project worked on
2. Document your most important conventions
3. Add the /update-context command so documentation stays current
4. 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.

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:

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:

Model strengths (from my experience):

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.

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

1. 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.
2. Spend 2-4 weeks using it for completion and simple generation.
3. Practice prompting: be specific, iterate, learn what works.
4. Move to a more capable tool (Claude Code, Cursor, Windsurf) once you’re comfortable.
5. Build your first context file.

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

For Developers Experienced With AI

Start here: Workflow Integration + Advanced

1. Audit your current workflow. Where are you using AI effectively? Where are you over-trusting?
2. Strengthen context engineering. Create comprehensive project context files.
3. Set up guardrails: linting, security scanning, review checklists.
4. Experiment with agentic workflows under supervision.
5. 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:

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

Actions:

1. Assess your team against these practices. Where are the gaps?
2. Don’t change everything at once. Introduce AI at one delivery stage at a time.
3. Expect a learning curve: 2-4 weeks of reduced productivity before gains appear.
4. Invest in guardrails before acceleration.
5. 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.

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:

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:

1. Small tasks with /clear - fresh context beats compressed context
2. Early compaction with custom instructions - you control what matters
3. Early compaction with default prompt - still gives thinking room
4. 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.

I’ve spent the last two years applying AI across prototyping, internal tools, production systems, and team workflows. I’ve watched it produce an elegant solution in seconds, then confidently generate code calling APIs that don’t exist. I’ve seen it save hours on boilerplate and cost hours debugging hallucinated dependencies.

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. “Write unit tests for an ISO 8601 date parser, including edge cases for timezone offsets, leap seconds, and malformed input—then implement a function that passes them” gets something I can actually trust.
• 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).

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? 😃

Coding assistants like Cursor, Windsurf, Claude Code, Gemini CLI, Codex, Aider, OpenCode, JetBrains AI etc. have been making the news for the last few months. Yet, the choice of tools is a lot harder and limited for some of us than it seems.

TL;DR: OpenCode > Claude Code > Aider > Copilot > *

Understanding the tools

Not all tools are created equal. Tools evolve fairly rapidly so the examples listed here might be invalid fairly soon.

You can plot the different types of coding assistants on a graph showcasing the amount of human involvement required (lesser involvement = more automation). The first GitHub Copilot release I used allowed tab completions. It would either complete single lines or entire blocks of code. You could describe your intent by creating a function with a good name or by writing a comment. GitHub Copilot then supported inline prompting or chat sessions.

Coding agents are the current state of the art toolset for most developers on a day to day basis. They allow you to have conversations with them and you should treat them as team mates, albeit ones with anterograde amnesia.

Some problems can be parallelised and background agents triggered locally are incredibly powerful. Claude code supports subagents is frequently used for analysis and solving multiple issues in parallel using git worktrees. Similarly, some people hook up agents to remote instances for things like code reviews using Claude code or Copilot.

The extreme version of this is pure vibe coding. There is enough content out there about why this is a bad idea and the number of issues on real systems because of this.

Challenges with using these tools

When picking up a tool, I have started looking at different aspects of these tools

Choice of models

LLMs change quite quickly. Claude Sonnet 3.7 started off being the favourite model for most developers I know. When Claude Sonnet 4 came out at the same cost as 3.7, it became the new favourite model. Claude Opus 4 is great for larger codebases but expensive.

As I write this (mid-July 2025), the word on the street is that Grok 4 is currently the best model on the block. Choose something that has good coding insights and a large context window. Claude Sonnet has some of the smaller context windows but is tuned quite well for software development.

Cursor supports most of the best models and provides diversity. Tools like Claude Code and Gemini CLI are built and maintained primarily for use with a single model.

Ease of use

This one is fairly subjective and dependent on the developer’s preference. Tools like Cursor are VS Code forks and thus provide tight integration with the editor. Others like Claude Code, Codex and Gemini CLI run on the terminal. Claude Code provides decent integration with the IDEs from the JetBrains family and thus provide good support to pair with your AI assistant.

Speed factors into ease of use too. While Jetbrains AI is the best integrated tool amongst all of these (if you prefer using their IDEs), their AI tool is one of the slowest. Slower tools mean slower feedback cycles. Slower feedback cycles are some of the worst things for dev experience.

Cost per change

Cost pays a huge part in someone’s choice of tools and running LLMs are fairly expensive to run. Most tools charge you per use, some by tokens, some by APIs. Since we’re in the relatively early days of these tools and they are competing to capture the market, some still provide fixed investment offers in exchange for “unlimited plans.

Cursor used to be $20/month with unlimited usage till June 2025. While all “unlimited” usage is rate limited, if the usage limits are generous or the rate limits are not severe, users can manage to have a decent developer experience. More recently, Cursor updated their prices to make the $20/month Pro plan for “light users”. Daily users are recommended to use their $60/month Pro+ plan and power users are recommended to use their $200/month Ultra plan. Users on reddit have complained about how the Ultra plan is insufficient, though Cursor’s documentation says that it should be sufficient. This seems to primarily be because of heavy Claude Opus 4 usage, one of the most expensive models.

Another fixed usage tool is Claude Code for individuals with it’s Pro and Max plans. The $100/month Max plan seems to be the sweet spot for most heavy users and is probably the best value for money, at least until you look at the licensing.

Google’s Gemini CLI, at launched, announced the most insane free tier (that allows you to spend an estimated $620/day) but at the cost of training on your projects. More on this, in the next section. The free tier might not be this generous forever so if the “training on your data” bit isn’t a concern, enjoy Google’s generosity.

IP ownership indemnity and licensing

Licensing is a complicated topic and I go off of the advice that people much more qualified than me give in this space. The current understanding of this space is that you want to be on

1. company licensing (avoid individual licenses)
2. a tool that does not train on your data
3. provides you indemnity against IP claims

You should avoid individual licenses since the protections usually apply to you, not the organisation you work for. If you work with a services company and create IP for your clients, you want to avoid the risk of the protections not covering your clients.

Avoid tools that train on your data if you’re building something commercially. If you’re on a FOSS tool/system, you can ignore this fact. Google Gemini CLI’s free tier is a great example of this. They get to use your data to make the system better in exchange for you having a good coding assistant free of cost.

Anthropic, the creator of Claude Code, indemnifies its commercial users against lawsuits. Most other tools tend to do this too. Interestingly, Cursor does not, at least as of the writing of this article. Their MSA provides this protection, however, they only do this for customers signing up for more than 250 seats. This may change in the future and talking to their support is the best way to clarify this.

What do I use and recommend at this point?

For team members who are new to using coding assistants, start off with Copilot where users will appreciate the fixed cost. Learn, experiment. Strengthen your core skills in this new world: Prompt Engineering and Context Engineering (more on these skills in another blog).

When you have mastered these skills, you should consider moving to an API based tool that allows you to switch between models. Personally, I’m a fan of the Claude Sonnet and Opus models over OpenAI (and to some extent, Gemini). If you can manage costs well, move to Claude Code (or an open source tool like OpenCode or Aider). I would put OpenCode above Claude Code due to it’s flexibility.