DEV Community: The AI Leverage Weekly

How to Write an Architecture Decision Record with AI

The AI Leverage Weekly — Wed, 15 Jul 2026 09:01:00 +0000

Architecture Decision Records (ADRs) are one of those things every team agrees they should write and almost no one actually writes. The doc feels bureaucratic, the moment to capture the decision has already passed, and staring at a blank template is its own kind of tax. AI removes most of that friction. Here's a step-by-step walkthrough you can follow right now to produce a solid ADR in under 10 minutes.

What an ADR Actually Needs to Contain

Before prompting anything, know your target. A useful ADR has five sections:

Title — short, verb-first (e.g., "Use PostgreSQL for transactional storage")
Status — Proposed / Accepted / Deprecated / Superseded
Context — what problem forced this decision, what constraints existed
Decision — what you chose and why
Consequences — trade-offs, risks, follow-up work

If you can answer those five things out loud, you have everything AI needs.

Step 1: Brain-Dump Your Context

Don't clean up your thoughts first. Paste the raw context directly into the prompt. Messy input is fine — the model's job is to structure it.

I need to write an Architecture Decision Record. Here's the raw context:

We're choosing between Redis and a Postgres-based queue (using SKIP LOCKED)
for our background job system. The team is small, we already run Postgres,
and we want to avoid adding another infra dependency. Redis is faster but
we'd have to operate it separately. We picked Postgres queue. The main
downside is throughput ceiling around ~500 jobs/sec which is fine for now.

Write a complete ADR using this structure:
- Title
- Status: Accepted
- Context
- Decision
- Consequences (separate positive and negative)

Use plain prose, not bullet points inside the sections. Keep it under 300 words.

Step 2: Review the Output Against Your Actual Constraints

AI will produce a clean draft, but it fills gaps with reasonable assumptions. Read it critically for two things:

Accuracy — did it faithfully represent your constraints, or did it invent ones that sound plausible?
Specificity — are numbers, system names, and timelines correct?

Fix anything that's wrong before it becomes the permanent record.

Step 3: Stress-Test the Consequences Section

The consequences section is where most ADRs go shallow. Use a follow-up prompt:

Review the Consequences section of this ADR. What risks or trade-offs
are missing? What operational, scaling, or team-knowledge implications
should be added? Be specific, not generic.

[paste your current ADR draft]

Add whatever surfaces that you actually agree with. Discard generic filler.

Step 4: Generate the File and Drop It in Your Repo

ADRs belong in version control, next to the code they govern. Use this prompt to get the final file:

Format the following ADR as a Markdown file ready to commit.
Filename convention: NNNN-short-title.md (I'll supply the number).
Add a "Date" field after Status.

[paste final ADR]

Commit it to docs/decisions/ or wherever your team keeps them. If you don't have a folder yet, create it — this is the first one.

The Workflow at a Glance

Step	What you do	What AI does
1	Brain-dump raw context	Structures it into ADR format
2	Review for accuracy	—
3	Request consequence audit	Surfaces missing trade-offs
4	Paste final draft	Formats for commit

The whole thing takes 10 minutes the first time, less after that. The team gets a permanent record of why a decision was made — which is the only thing that matters six months later when someone wants to re-litigate it.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=medium_w10

How to Debug a Failing Test with AI (Step-by-Step)

The AI Leverage Weekly — Mon, 13 Jul 2026 09:00:47 +0000

How to Debug a Failing Test with AI (Step-by-Step)

A test is red. The error message is vague. You've stared at the diff for ten minutes and nothing jumps out. This is exactly where AI earns its keep — not by guessing, but by systematically surfacing the class of failure you're dealing with before you've wasted an hour going in the wrong direction. Here's the exact workflow I use, with copy-paste prompts you can drop in today.

Step 1: Collect the Full Failure Context Before You Prompt

AI can only help as much as the context you give it. Before you open a chat window, gather:

The full test output (not just the last line — the whole stack trace or assertion diff)
The test code itself
The function or module under test
Any recent changes to either (a one-line git diff summary is fine)

Don't summarize yet. Raw output is better than your interpretation at this stage.

Step 2: Use the Diagnostic Prompt

Paste everything you collected into this prompt. The goal of this first message is triage — classify the failure before you start fixing it.

You are a senior software engineer helping me debug a failing test.

Here is the failing test:
[PASTE TEST CODE]

Here is the function/module it tests:
[PASTE IMPLEMENTATION CODE]

Here is the full test output:
[PASTE FULL ERROR / STACK TRACE]

Recent changes (if any): [BRIEF DESCRIPTION OR GIT DIFF SNIPPET]

Do the following:
1. Identify the category of failure (assertion mismatch, unexpected exception, setup/teardown issue, flaky timing, wrong mock, etc.)
2. State the most likely root cause in one sentence.
3. List up to three hypotheses, ranked by probability.
4. Suggest the smallest possible code change to confirm hypothesis #1 before fixing anything.

That last instruction — smallest change to confirm, not fix — is the key. AI will default to handing you a fix. You want a diagnostic step first, because if hypothesis #1 is wrong, the fix is wrong too.

Step 3: Confirm Before You Fix

Run the diagnostic the AI suggests. It's usually something like adding a console.log, asserting an intermediate value, or temporarily hardcoding input to isolate the boundary. Once you know which hypothesis is correct, go back:

Hypothesis #1 was correct. The root cause is [what you confirmed].

Now give me the minimal fix — only change what is necessary to make this test pass without altering the contract of the function. Explain each change in one line.

Asking for a minimal fix and requiring explanations keeps the AI from over-engineering a solution that touches things you didn't break.

Step 4: Handle Flaky Tests Differently

If the test passes sometimes and fails sometimes, the diagnostic prompt above still works — but add this line before your closing instructions:

"This test is intermittent. Focus specifically on timing issues, shared state, test ordering dependencies, and non-deterministic data."

Flakiness almost always traces back to one of those four categories. Telling the AI upfront prevents it from chasing assertion logic that isn't the real problem.

Step 5: Validate the Fix Doesn't Just Pass — It Tests the Right Thing

Once the test is green, run one more prompt:

Here is the original test and the fix we applied:
[PASTE BOTH]

Does the test still meaningfully verify the intended behavior, or did the fix change what is being tested in a way that reduces coverage? Point out any assertions that became weaker or any edge cases that are no longer exercised.

This is the step most people skip, and it's where AI adds real value beyond just making CI green. A test that passes because you changed the assertion threshold isn't a fixed test — it's a hidden regression.

This pattern — triage, confirm, fix minimally, validate coverage — is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version above is enough to get value on its own.

A Note on What AI Gets Wrong Here

AI will occasionally misread a stack trace and chase a symptom instead of the cause. Two guardrails help:

Never skip Step 2's confirmation step. If you jump straight to the fix, you lose the ability to catch a misdiagnosis cheaply.
If the AI's hypothesis doesn't match what you see in the code, say so explicitly. "That hypothesis doesn't fit because X. Revise." Models course-correct well when you push back with evidence.

Putting It Together

The full flow takes about five minutes of prompting for most failures. The payoff is that you stop debugging by vibes — scrolling, tweaking, re-running — and start debugging by elimination. AI doesn't replace the engineer; it just makes the triage loop faster and more systematic.

Copy the two main prompts above into a scratch doc or a snippet manager and reach for them the next time a test goes red.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. It's one concrete AI workflow per issue, aimed at working engineers who don't have time to wade through hype. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=long_w10

AI Handled Two of My Hardest Weekly Tasks — Here's What the Data Showed (Week 9 Roundup)

The AI Leverage Weekly — Fri, 10 Jul 2026 09:00:59 +0000

AI Handled Two of My Hardest Weekly Tasks — Here's What the Data Showed (Week 9 Roundup)

This week I went deep on two things that have historically eaten a disproportionate chunk of my time: getting oriented in an unfamiliar codebase and writing SQL queries against schemas I don't own.

Let me give you the real numbers.

Getting up to speed on an unfamiliar codebase

On a recent project, a teammate handed me a ~40,000-line service I'd never touched. Old me would've spent half a day reading files, tracing call stacks, and pestering whoever built it with questions.

This time I fed the entry points and key modules into an AI assistant and asked structured questions — "what does this module own?", "what are the failure modes here?", "where does state live?" — iterating the way you'd interrogate a knowledgeable colleague.

Result: I had a working mental model in about 45 minutes. I filed my first meaningful PR in that codebase before lunch. That's a task that used to bleed into day two.

Writing SQL from plain English

Later in the week, I needed to pull a fairly complex report from a schema I hadn't worked with before — multi-table joins, some window functions, a few edge cases around NULLs.

I described what I needed in plain English, pasted in the relevant table definitions, and iterated on the output through three rounds of prompting. Total time: ~18 minutes. The query ran clean on the first real test against production data.

For context, my baseline for a query that complexity, working from scratch, is closer to 45–60 minutes — and that includes the debugging loop.

What this week actually confirmed

Both workflows share the same underlying mechanic: you're not outsourcing the thinking, you're compressing the orientation phase. The AI gets you to the point where your actual expertise kicks in, faster. That's where the leverage is.

The weeks where I see the biggest gains aren't the ones where AI writes something for me end-to-end — they're the weeks where it eliminates the slow ramp-up that happens before I'm even doing real work.

That pattern is worth paying attention to.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=roundup_w9

How to Use AI to Write SQL Queries from Plain English

The AI Leverage Weekly — Wed, 08 Jul 2026 09:00:31 +0000

If you've ever stared at a complex schema and spent 20 minutes writing a query you could describe in one sentence, this walkthrough is for you. I'll show you exactly how to prompt an AI assistant to generate accurate, production-ready SQL from plain English — including the context you need to provide, the prompts that work, and how to verify what comes back.

Why Most "AI + SQL" Attempts Fail

The usual failure mode: you paste a vague question into ChatGPT or Claude, get back a query that looks plausible, run it, and get wrong results or an error. The fix isn't a better AI — it's a better prompt. AI models write SQL accurately when you give them the same context a senior teammate would need.

Step 1: Give the AI Your Schema

Never ask for a query without first providing your table definitions. Copy the CREATE TABLE statements directly from your database.

-- Paste this into your prompt first
CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  customer_id INT NOT NULL,
  status VARCHAR(20) NOT NULL,  -- 'pending', 'shipped', 'cancelled'
  total_amount NUMERIC(10, 2),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE customers (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  signup_date DATE NOT NULL,
  plan VARCHAR(20) DEFAULT 'free'  -- 'free', 'pro', 'enterprise'
);

If your schema is large, include only the tables relevant to your question.

Step 2: Write the Prompt

Use this template every time:

You are a SQL expert working with PostgreSQL.

Here are my table definitions:
[PASTE SCHEMA HERE]

Write a query that: [PLAIN ENGLISH DESCRIPTION]

Requirements:
- Use CTEs if the logic has more than one step
- Add a comment explaining any non-obvious join condition
- Do not use SELECT * — name every column

Example request:

Write a query that returns, for each pro or enterprise customer who signed up
in the last 90 days, their email, total number of orders, and total spend —
but only where total spend exceeds $500. Sort by total spend descending.

What the AI returns:

-- Customers on paid plans, signed up in the last 90 days
WITH recent_paid_customers AS (
  SELECT id, email
  FROM customers
  WHERE plan IN ('pro', 'enterprise')
    AND signup_date >= CURRENT_DATE - INTERVAL '90 days'
),
customer_order_totals AS (
  SELECT
    c.email,
    COUNT(o.id)          AS order_count,
    SUM(o.total_amount)  AS total_spend
  FROM recent_paid_customers c
  -- Left join so customers with zero orders still appear; filter below
  JOIN orders o ON o.customer_id = c.id
  WHERE o.status != 'cancelled'
  GROUP BY c.email
)
SELECT
  email,
  order_count,
  total_spend
FROM customer_order_totals
WHERE total_spend > 500
ORDER BY total_spend DESC;

Clean, readable, and correct on the first try — because the prompt had enough context.

Step 3: Verify Before You Run

Ask the AI to explain the query back to you in plain English:

Explain this query step by step. Call out any assumptions you made
about the data or business logic.

This surfaces hidden assumptions fast. If the explanation doesn't match your intent, correct it in the next message — the model retains the schema context in the same conversation.

Step 4: Iterate for Edge Cases

Follow up with edge-case questions in the same thread:

What happens if a customer has no orders at all? Will they appear in results?
Rewrite using a LEFT JOIN if needed so they show up with zero values.

The model will revise the query and explain the change. This loop — generate, explain, stress-test, revise — usually gets you to a production-safe query in three to four messages.

The Workflow, Condensed

Paste relevant CREATE TABLE statements
Use the prompt template: role + schema + plain English goal + formatting requirements
Ask for a plain-English explanation to catch wrong assumptions
Stress-test edge cases in the same conversation thread
Run EXPLAIN ANALYZE on the result for any query touching large tables

That's the full loop. No magic — just structured context.

How to Use AI to Understand an Unfamiliar Codebase

The AI Leverage Weekly — Mon, 06 Jul 2026 09:01:15 +0000

You've just been handed a codebase you've never seen before. No walkthrough, sparse docs, and the person who built it has moved on. You need to ship something in it by end of week. This is one of the most common — and most draining — situations in engineering, and AI actually handles it well if you know how to prompt it. Here's a step-by-step walkthrough you can follow right now.

Step 1: Get a High-Level Map Before You Touch Any File

Don't start by opening random files. Start by asking AI to orient you from the top down.

Paste in the root directory tree (just the folder/file names — no code yet) and use this prompt:

I'm trying to understand a codebase I've never worked in before.
Here is the top-level directory structure:

[PASTE DIRECTORY TREE HERE]

Based on this structure:
1. What is the likely purpose of this application?
2. What architectural pattern does it appear to follow (e.g. MVC, layered, event-driven)?
3. Which directories should I read first to understand the core domain logic?
4. What questions should I be asking that this structure alone can't answer?

This gives you a mental scaffolding before you wade into implementation details. The fourth question is the most valuable — it surfaces what to look for next.

Step 2: Explain a Specific File Without Reading Every Line

Once you have a target file, paste it into the chat and ask for a structured breakdown rather than a summary. Summaries tend to be vague. A structured breakdown forces the model to be specific.

Here is a file from a codebase I'm ramping up on:

[PASTE FILE CONTENTS]

Please explain it with the following structure:
- **Purpose**: What is the single responsibility of this module?
- **Inputs / Outputs**: What does it receive and what does it produce or affect?
- **Dependencies**: What does it rely on that I should also understand?
- **Side effects**: Does it write to anything, emit events, or mutate shared state?
- **Gotchas**: Any non-obvious logic, edge cases, or things that could confuse a new reader?

The "Gotchas" section alone has saved me from misreading code more times than I can count. Models are good at spotting patterns that are technically valid but semantically surprising — things like a function named getUser that also writes a log entry.

Step 3: Trace a Request or Data Flow End-to-End

Understanding individual files isn't enough — you need to know how they connect. Pick an entry point (an API route, a queue consumer, a CLI command) and ask AI to walk the execution path with you.

Paste in 2–3 files that you suspect are in the same call chain and prompt:

I'm trying to understand how a request flows through this system.
Here are several files I believe are connected:

[FILE 1 — paste contents]
[FILE 2 — paste contents]
[FILE 3 — paste contents]

Please trace what happens when [describe the trigger, e.g. "a POST request hits /api/orders"].
Show the sequence of function calls across these files,
note where data is transformed, and flag any steps where the flow is unclear or could break.

This is where AI pays for itself in ramp-up scenarios. Manually tracing a call chain across 4–5 files used to take a full afternoon. With the right prompt, you have a working model in 10 minutes that you can then verify.

Step 4: Generate a "New Contributor Cheat Sheet"

Once you've used steps 1–3 to develop a mental model, consolidate it. Have the AI produce a reference doc you can keep open while you work.

This pattern is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version below is enough to get value on its own.

Based on everything we've discussed about this codebase, generate a "New Contributor Cheat Sheet" with:
1. One-paragraph system overview
2. Key modules and their responsibilities (bullet list)
3. The 3–5 files a new engineer must read before making any changes
4. Common pitfalls or conventions that aren't obvious from the code alone
5. Glossary of any domain-specific terms used in the codebase

Paste this into your team's internal docs or a personal note. The next time you hit a confusing area of the codebase, you have a foundation to ask more precise questions from.

What This Workflow Is Actually Doing

Each step moves from abstract to concrete: structure → file → flow → reference. You're using AI as a structured reading partner, not an autocomplete. The quality of what you get back scales directly with the specificity of your prompt — generic questions produce generic answers.

A few practical notes:

Context window matters. For large files, trim dead code or test fixtures before pasting. Focus the model on the logic, not the noise.
Always verify. AI will occasionally misread intent, especially in codebases with unconventional patterns. Use its output as a hypothesis to confirm, not a fact to accept.
Iterate. The cheat sheet from Step 4 will have gaps. Go back, paste the confusing parts, and refine.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. It's built for engineers who want to work faster without cutting corners. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=long_w9

AI Wrote Half My Week — Here's What the Numbers Actually Looked Like (Week 8 Roundup)

The AI Leverage Weekly — Fri, 03 Jul 2026 09:00:30 +0000

AI Wrote Half My Week — Here's What the Numbers Actually Looked Like (Week 8 Roundup)

This week had a clear through-line: using AI not as a novelty, but as a multiplier on two of the most time-consuming communication tasks in engineering — refactoring legacy code and writing pull request descriptions.

Here's what actually happened, with real numbers.

The Refactoring Session

On a recent project, I had a service with a module that hadn't been meaningfully touched in about three years. Nested conditionals, no tests, naming that made sense to someone in 2021 but nobody since. I ran it through a structured AI refactoring workflow — the kind I wrote about this week — and tracked the time.

Manual refactoring estimate (based on similar past work): ~4 hours.

Actual time with AI-assisted prompts, including review and sanity-checking the output: 1 hour 20 minutes.

That's not magic. That's systematic prompting: ask for a plain-language summary first, identify the hotspots, then refactor incrementally rather than all at once. The AI didn't understand the business logic — I did. It handled the mechanical transformation; I handled the judgment calls.

The PR Description Problem

The second theme this week was pull request descriptions. On the same project, I counted: over the last sprint, roughly 60% of PR review cycles included at least one round-trip comment that existed purely because the description was unclear — missing context, no "why this change," no callouts for reviewers.

I switched to generating first-draft PR descriptions with AI (prompt: diff in, structured description out), then editing for accuracy. Review round-trips dropped. Not eliminated — but the first-pass questions got sharper because reviewers had more to work with upfront.

What This Week Confirmed

Speed gains from AI are real, but they're not random. They show up consistently in two places: mechanical transformation (restructuring code, reformatting text) and blank-page problems (starting a description, a doc, a test). The judgment layer still belongs to the engineer. That's not a caveat — that's the workflow.

Week 8 down. The pattern is getting clearer every Friday.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. It's the one email I actually write for engineers who want to work smarter without the hype. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=roundup_w8

How to Write a Pull Request Description with AI

The AI Leverage Weekly — Wed, 01 Jul 2026 09:01:01 +0000

How to Write a Pull Request Description with AI

Writing a good PR description takes longer than it should. You've already done the hard work — the code is done — but now you're staring at a blank text box trying to summarize context, motivation, and testing notes while your brain is already on the next task. AI handles this well. Here's a step-by-step walkthrough you can use today.

Why PR Descriptions Get Skipped (or Written Badly)

Bad PR descriptions slow down review cycles. Reviewers ask questions that are already answered in the diff, or they approve without really understanding the change. The fix isn't discipline — it's reducing the friction of writing a good description in the first place.

Step 1: Get Your Raw Diff

Start by pulling the diff between your branch and main:

git diff main...HEAD > pr_diff.txt

If the diff is large (500+ lines), focus on the meaningful parts — skip lockfile changes and generated files:

git diff main...HEAD -- '*.ts' '*.py' '*.go' > pr_diff.txt

Step 2: Paste the Diff into Your AI Tool with This Prompt

Open your AI tool of choice (ChatGPT, Claude, Gemini — all work here) and use this prompt:

You are a senior engineer writing a pull request description for a code review.

Here is the diff:

<paste diff here>

Write a pull request description with the following sections:
1. **What changed** — a 2–3 sentence plain-English summary of what this PR does.
2. **Why** — the motivation or problem being solved.
3. **How to test** — concrete steps a reviewer can follow to verify the change locally.
4. **Notes for reviewer** — anything non-obvious, edge cases to watch, or follow-up work deferred.

Be specific. Reference actual function names, files, or logic from the diff. Do not be vague.

Step 3: Review and Edit the Output

The AI output will be 80–90% usable. Your job is to:

Fix any context it couldn't infer from the diff alone (e.g., why this ticket existed)
Add a link to the issue or ticket
Trim anything that's redundant with the diff itself

This takes 2–3 minutes, not 15.

Step 4: Save a Template for Your Team

Once you've done this a few times, extract the structure into a .github/pull_request_template.md file in your repo:

## What changed


## Why


## How to test
- [ ] Step 1
- [ ] Step 2

## Notes for reviewer

Now the AI output maps directly to the template fields. Every PR on your team starts from the same skeleton, and the quality floor rises across the board.

The Full Prompt, Ready to Copy

You are a senior engineer writing a pull request description for a code review.

Here is the diff:

[PASTE DIFF]

Write a pull request description with the following sections:
1. **What changed** — a 2–3 sentence plain-English summary of what this PR does.
2. **Why** — the motivation or problem being solved.
3. **How to test** — concrete steps a reviewer can follow to verify the change locally.
4. **Notes for reviewer** — anything non-obvious, edge cases to watch, or follow-up work deferred.

Be specific. Reference actual function names, files, or logic from the diff. Do not be vague.

This workflow takes about 5 minutes the first time and under 2 minutes once it's part of your routine. Better descriptions mean faster reviews — that's a compounding win on every PR you ship.

The Best AI Prompts for Refactoring Legacy Code

The AI Leverage Weekly — Mon, 29 Jun 2026 09:00:47 +0000

The Best AI Prompts for Refactoring Legacy Code

Legacy code doesn't come with a manual. You inherit a function that's 300 lines long, has no tests, and the original author is long gone. You know it needs to change, but touching it feels like defusing a bomb blindfolded. AI tools won't rewrite your entire codebase for you — but with the right prompts, they dramatically shrink the time between "I don't understand this" and "I can safely change this." Here are the prompts I reach for, in the order I actually use them.

1. Start with a plain-English explanation of what the code does

Before you touch anything, you need to understand it. Paste the function or module and ask:

Explain what this code does in plain English. Describe:
1. Its purpose (what business problem it solves)
2. Its inputs and outputs
3. Any side effects or external dependencies
4. Edge cases it appears to handle
5. Anything that looks unusual or potentially buggy

Here is the code:
[paste code]

This gives you a mental model fast. Don't skip it — even if you think you understand the code, the AI often surfaces a side effect or edge case you glossed over.

2. Identify the smell before you prescribe the fix

Jumping straight to "refactor this" produces mediocre results. Instead, ask for a diagnosis first:

Review the following legacy code and list every code smell you can identify.
For each smell: name it, quote the specific lines involved, and explain why it's a problem.
Do not suggest fixes yet — just audit.

[paste code]

Getting a structured smell list forces the AI to slow down and reason about the code rather than produce a cosmetically cleaner version of the same mess.

3. Ask for a refactoring plan, not just refactored code

Once you have the smell list, ask for a sequenced plan before asking for any new code:

Given the code smells you identified, produce a step-by-step refactoring plan.
Order the steps from lowest risk to highest risk.
For each step, explain: what changes, why it's safe to do in isolation, and what could break.
Do not write code yet.

This is the prompt that saves the most time. A plan exposes assumptions you can challenge before you've committed a line of code. It also gives you natural stopping points if you're time-boxed.

4. Generate a characterization test suite before refactoring

Legacy code without tests is a minefield. Use the AI to generate "characterization tests" — tests that document current behavior, not ideal behavior:

Write a suite of unit tests for the following function that captures its current behavior exactly — including any behavior that looks wrong.
The goal is not to test correctness; the goal is to detect if refactoring changes the output.
Use [your test framework, e.g. Jest / pytest / RSpec].

[paste code]

Run these tests, commit them, and now you have a safety net. Any refactoring that breaks a test is a regression you need to understand before merging.

5. Refactor one smell at a time, not all at once

Now you're ready to change code. Do it incrementally:

Refactor ONLY the following problem from the code below: [name one smell from your list, e.g. "extract the nested conditional into a separate function"].
Do not change any other logic.
Show me the before and after side by side and explain every change you made.

[paste code]

This pattern is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version above is enough to get value on its own.

Scoping the prompt tightly is the key move. When you ask AI to "refactor everything," it over-reaches and introduces changes you didn't ask for, review, or understand. One smell per prompt keeps the diff reviewable.

6. Ask for a risk assessment on your final diff

Before you open the PR, paste your final diff and ask:

Review this diff. Identify any changes that:
- Could introduce a regression
- Change behavior in a way that isn't obvious from the variable/function names
- Should be covered by a test that doesn't exist yet

Be specific. Quote the lines you're concerned about.

Treat this like a second pair of eyes on your PR — one that reads every line without getting bored.

The sequence matters as much as the prompts

These six prompts are most effective in order: understand → audit → plan → safety-net → change → validate. Skipping steps (especially the characterization tests) is how you end up with a "refactored" codebase that breaks in production on an edge case nobody thought to test.

None of these prompts require a specific AI tool — they work with whatever assistant you're already using. The discipline is in the sequence, not the syntax.

We Saved 6 Hours of QA Time This Week Using AI — Here's the Breakdown (Week 7 Roundup)

The AI Leverage Weekly — Fri, 26 Jun 2026 09:01:03 +0000

We Saved 6 Hours of QA Time This Week Using AI — Here's the Breakdown (Week 7 Roundup)

This week had a clear throughline: AI doing the tedious, time-consuming work that engineers hate but can't skip — and the numbers were actually surprising.

The Case That Made It concrete

Midway through the week, a service I was responsible for had a module with 23 functions, zero unit tests, and a refactor deadline approaching fast. Historically, writing that test suite from scratch would eat up most of a day — probably 5–6 hours of mechanical, low-satisfaction work.

Using an AI-assisted workflow to generate the test scaffolding function by function, I had a working first draft of the full suite in under 90 minutes. That's not a rounding error. That's the difference between shipping the refactor this sprint and punting it to the next one.

The output wasn't perfect — about 20% of the generated tests needed meaningful corrections, mostly around edge cases and mock setup. But starting from a structured draft instead of a blank file changed the whole shape of the work. I was reviewing and refining, not grinding.

The Other Half of the Week

The second major theme was debugging. A gnarly stack trace came in from a service in a part of the codebase I hadn't touched in months. The kind of error where you'd normally spend 45 minutes just reorienting yourself before you even start diagnosing.

Feeding the trace to an AI model with the right context got me to the probable root cause in one structured pass. Not magic — it still took judgment to confirm the fix — but the triage phase that usually burns the most time was compressed dramatically.

What the Week Actually Proved

These weren't toy examples or tutorials. Both were real work, under real time pressure. The pattern that held across both:

AI front-loads the structural work (scaffolding, triage, orientation)
Engineers handle the judgment layer (correctness, context, edge cases)
The split saves hours, not minutes

The engineers who are winning with AI right now aren't the ones with the cleverest prompts. They're the ones who've figured out exactly which part of their workflow to hand off.

How to Use AI to Debug a Stack Trace (Step-by-Step)

The AI Leverage Weekly — Wed, 24 Jun 2026 09:00:33 +0000

How to Use AI to Debug a Stack Trace (Step-by-Step)

You've got a wall of red text, a stack trace you don't fully recognize, and no obvious starting point. AI can turn that trace into a clear diagnosis and a fix — in under two minutes. Here's exactly how to do it.

Why Raw Stack Traces Are Hard to Parse Alone

Stack traces are dense. They mix your code with framework internals, third-party library frames, and sometimes async noise that obscures the actual origin of the error. The mental overhead of filtering signal from noise is where most debugging time gets wasted. AI is surprisingly good at this — not because it "knows" your system, but because it can pattern-match against thousands of similar traces and explain each layer in plain language.

Step 1: Copy the Full Stack Trace — Don't Trim It

Resist the urge to paste only the top three lines. The root cause is often buried lower in the trace. Copy everything, including the error type, message, and every frame.

Step 2: Use This Prompt Template

Open your AI assistant (ChatGPT, Claude, Gemini — any capable model works) and paste this:

You are a senior engineer helping me debug a runtime error.

Here is the full stack trace:
---
[PASTE YOUR FULL STACK TRACE HERE]
---

Please do the following:
1. Identify the root cause of the error in plain English.
2. Pinpoint the exact line or frame where the error originates (not just where it surfaces).
3. Explain why this error occurs — what condition triggered it.
4. Suggest a concrete fix with a code example.
5. List any other places in a typical codebase where this same pattern might cause the same error.

That fifth point is the one most developers skip — and it's where you stop patching and start preventing.

Step 3: Add Context to Get a Sharper Answer

After the initial response, follow up with:

Here is the function where the error originates. Does this change your diagnosis?

[PASTE THE RELEVANT FUNCTION OR METHOD]

This two-pass approach — trace first, code second — gives the model enough context to go from "here's what's probably wrong" to "here's exactly what's wrong."

Step 4: Ask for a Reproduction Case

Write a minimal code snippet that would reproduce this error so I can verify the fix before applying it.

This forces the model to commit to a specific understanding of the bug. If the reproduction case doesn't match what you're seeing, you've caught a hallucination before it costs you time.

Step 5: Validate the Fix, Then Ask for a Test

Here is the fix I applied: [PASTE FIX]. Now write a unit test that would have caught this error before it reached production.

You've just turned a debugging session into a regression test — automatically.

What This Workflow Actually Gets You

A plain-English explanation you can share with a teammate or put in a PR description
A fix you can verify before applying
A unit test that closes the loop
A checklist of similar patterns to audit in the rest of the codebase

This entire flow takes five minutes once you have the prompt structure memorized.

I break down one workflow like this every week in The AI Leverage Weekly — practical AI techniques for engineers, no fluff, free. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=medium_w7

How to Generate Unit Tests from a Function Using AI

The AI Leverage Weekly — Mon, 22 Jun 2026 09:01:20 +0000

You have a function, you need tests, and you're staring at a blank file. AI can generate a solid first draft of your unit test suite in under a minute — but only if you prompt it correctly. This walkthrough shows you exactly how to do it, step by step, with copy-paste prompts and real output patterns you can adapt immediately.

Why the Naive Prompt Fails

Most engineers start with something like "write tests for this function" and paste their code. The output is usually technically correct but shallow: happy-path only, no edge cases, no error conditions, no boundary values. It looks like coverage but isn't.

The fix isn't a fancier AI model — it's a better prompt structure.

Step 1: Frame the Function with Context

Before pasting code, tell the AI what the function is supposed to do, what it promises to callers, and what test framework you're using. One short paragraph of context doubles the quality of the output.

I have a TypeScript function that validates a user-submitted email address
before it's stored to the database. It should return true for valid emails
and false for invalid ones. I'm using Vitest with the `describe/it/expect`
pattern. No mocking is needed — the function is pure.

Here is the function:

[PASTE FUNCTION HERE]

Generate a comprehensive unit test suite. Cover: the happy path, boundary
cases (empty string, null, very long strings), malformed inputs
(missing @, multiple @, special characters), and any edge cases implied
by the implementation itself.

That last line — "edge cases implied by the implementation itself" — is the key instruction. It forces the model to read the actual logic rather than generating generic tests.

Step 2: Ask for a Test Plan Before the Code

For non-trivial functions, add one extra step: ask for the test plan first, review it, then ask for the implementation. This costs 30 seconds and catches gaps before they get baked into code.

Before writing any test code, list every test case you plan to cover for
the function above. Group them by: (1) valid inputs, (2) invalid inputs,
(3) boundary/edge cases, (4) error conditions. Use plain English, one
line per case. I'll confirm the list before you write any code.

Scan the list. You'll almost always spot a case the model missed — and more importantly, a case you would have missed too. Add it back in plain English before you proceed.

Step 3: Generate the Tests

Once the plan is approved, run the generation prompt:

Now write the full Vitest test suite based on the test plan above.
Requirements:
- One `describe` block named after the function
- One `it` block per test case, with a descriptive string that reads like a
  sentence ("returns false when the input is an empty string")
- No external dependencies or mocks unless the function requires them
- If any test case requires a fixture or factory, define it at the top of
  the describe block
- Add a one-line comment above any test that is non-obvious

The descriptive it strings matter. They're your documentation. When a test fails in CI at 2am, a string like "returns false when the input is an empty string" tells you exactly what broke without opening the file.

Step 4: Audit the Output for Coverage Gaps

Don't ship the AI output directly. Run this audit prompt against the generated suite:

Review the test suite you just wrote. Identify any of the following that
are missing or weakly covered:
1. Return value correctness (not just truthiness)
2. Side effects the function might have
3. Thrown exceptions or error types
4. Performance-sensitive paths (very large inputs)
5. Any assumption in the code that isn't tested

For each gap, either add a test case or explain why it's intentionally
excluded.

This is where the real value compounds. The model will often find its own blind spots when asked directly — things like checking the type of a return value, not just its truthiness, or confirming an exception has the right message, not just that it was thrown.

This pattern is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version above is enough to get value on its own.

Step 5: Parametrize Repetitive Cases

If the audit reveals many similar inputs that differ only in data, ask the model to refactor to a parametrized format:

Refactor any test cases that share the same assertion logic but differ
only in input data into a `it.each` table. Keep non-repetitive tests as
individual `it` blocks.

This cuts file length dramatically and makes it obvious when you need to add another row versus a whole new test.

The Full Prompt Order at a Glance

Context prompt — framework, function purpose, constraints
Test plan prompt — review before any code is written
Generation prompt — structured output requirements
Audit prompt — coverage gap check
Refactor prompt — parametrize repetitive cases

Working through all five steps for a typical utility function takes about 10 minutes. The result is a test suite that would have taken 45–60 minutes to write by hand — and usually has better edge case coverage than the manual version.

One More Tip: Anchor to Your Existing Test Style

If your codebase already has tests, paste one existing test file alongside your prompt and add: "Match the style, naming conventions, and structure of the example test file below exactly." The AI will mirror your patterns, which means the output requires almost no style cleanup before review.

I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. It's the fastest way to build a repeatable AI-assisted engineering practice. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=long_w7

How Switching AI Tools Mid-Sprint Cost Us a Day (And What We Learned) — Week 6 Roundup

The AI Leverage Weekly — Fri, 19 Jun 2026 09:01:06 +0000

This week's two pieces — one on writing better Git commit messages with AI, and one comparing Claude and ChatGPT for code review — were both born from the same messy sprint where I made a mistake that cost real time.

Here's what happened.

Midway through a feature branch, I switched from the AI tool I'd been using for code review to a different one, mostly out of curiosity. I wanted to test a head-to-head comparison in a live context rather than a synthetic one. The model switch was seamless. The workflow wasn't.

The new tool had a different "grain" — it flagged different things, used different idioms in its suggestions, and didn't carry any of the soft context I'd built up through earlier prompts in the session. I had to re-explain patterns we'd already established. I re-reviewed two files I'd already cleared. Net result: roughly a day's worth of focused review time became a day and a half, and I caught one genuine regression — a missing null check on an edge case — that I'm not confident the original tool would have caught.

So the lesson wasn't "tool X is better than tool Y." It was that consistency in tooling during a sprint has its own compounding value, and switching mid-flow carries a real context-switching cost that doesn't show up in any benchmark.

That framing fed directly into the commit message piece too. One thing I tracked this week: AI-assisted commit messages across 34 commits on two branches. Compared to my previous sprint's messages (which I still have in the log), the assisted ones averaged 2.1x longer, contained explicit "why" context in 79% of cases vs. ~20% before, and two of them directly prevented a "what did this change actually do?" question during a sync. Measurable. Mundane. Worth doing.

The throughline this week: AI tooling rewards deliberate, consistent workflows more than it rewards novelty. Picking the best tool matters less than building repeatable habits around whatever you pick.