How to Ask Engineers Better Technical Questions

A product manager sends a Slack message: "Can we show the discount on the invoice?" The engineer reads it, doesn't know which invoice, which discount, which service generates the PDF, or whether this needs to ship by Friday or is just an idea worth scoping. Five clarifying questions go back. An hour passes before anyone does real work. This is not a two-minute exchange that became a ten-minute one. The engineer had a working model of the problem they were solving before the message arrived, built from the specific files, functions, and edge cases they were holding in mind, and that model is gone the moment they have to switch into figuring out what the PM actually needs. Rebuilding it costs far more than the five minutes the clock shows. Non-engineers, PMs, support staff, and new hires account for most of these interruptions, and not because they're careless. They've never been taught what a complete technical question looks like, because no one teaches that skill the way engineers are taught to write specs. The cost sits at the organizational level: every vague question is a tax on the team's total engineering capacity, paid in rebuilt context rather than in the honest minutes the exchange appears to take.

Engineering specs and technical questions

A well-written engineering spec and a well-formed technical question share the same skeleton: a clear statement of what's wanted, the constraints that bound the answer, and a record of what's already been tried or ruled out. A spec that skips constraints is a wish list, open to any interpretation an engineer wants to give it, and a question that skips constraints forces the engineer to guess at scope before they can even start answering. Specs record dead ends on purpose, so reviewers don't re-litigate approaches that were already tested and discarded. A question that skips this step sends the engineer back down a path the asker already walked, burning a second round of effort on ground that's already been covered once. Consider the contrast directly. "Can we add a field to the database?" presupposes a solution and tells the engineer nothing about why. "I need the orders table to store a tax rate per line item, what's the right place for that?" states the actual need and lets the engineer confirm the approach or redirect it. The second version gives the engineer everything required to answer once, without a follow-up round-trip, because it packs in more information, not politeness. The same logic now governs how engineers write instructions for AI coding agents. Agentic context engineering has produced a widely repeated insight: an agent is only as good as the problem statement and the files it's pointed at. That principle applies with equal force when the "agent" answering the question is a human engineer sitting three desks away.

The four elements every technical question needs before you send it

A complete technical question has four parts, and leaving any one out is what turns a single exchange into three.

Goal: state the outcome you need, not the solution you've already imagined. "Can you add a field to the database?" assumes an implementation before anyone has evaluated whether it's the right one. "I need the orders table to store a tax rate per line item, what's the right place for that?" describes the actual need and leaves the engineer room to propose something better. The goal should describe what the user or the system requires, not the fix the asker pictured on the way to writing the message.

"The checkout flow" The checkout flow" means something different to a frontend engineer than it does to a backend engineer or a data engineer, so an undefined term guarantees the first response will be a clarifying question. Scope also covers who else is affected: other teams, other services, downstream consumers who might break if the change ships. For a large or unfamiliar codebase, pointing the engineer at a known entry point, a specific file, a module name, an endpoint, cuts the search time before any real thinking starts.

Constraints: state what the answer has to work within. Is this needed before the next release, or is it exploratory? Does it have to use the existing stack, or is the legacy billing service off-limits? Can the asker run queries in production, or not? Unstated constraints are the most expensive kind, because the engineer proposes a solution the asker can't actually use, and the whole exchange resets from zero.

"I looked at the docs and the field doesn't seem to exist" helps. "I looked at the v2 API reference and the endpoint returns X but not Y" helps more. For a bug report, the minimum is the exact error message, the steps that reproduce it, and the environment details: OS, version, browser. Naming the obvious things already tried, "I've already restarted the service", keeps the engineer's first response from being a trivial fix the asker tried an hour ago.

Finding scope without knowing the codebase

Not knowing the codebase is a reason to do a specific, lightweight kind of research before sending the question, not a reason to leave scope blank. The goal of that research is the ability to name the thing being asked about, a service, an endpoint, a config file, so the engineer doesn't have to do that naming on the asker's behalf. Tools that let non-engineers ask natural-language questions of a codebase, querying what handles a given feature or tracing where a piece of data flows, produce exactly this kind of named starting point without requiring anyone to read a line of code. Even without that tooling, several low-effort steps narrow scope before a question gets sent: checking existing tickets tied to the feature, reading the README or the architecture doc, or asking a colleague who touched the relevant code recently. Any one of these turns "I don't know what this is called" into a specific name an engineer can act on immediately. The rule of thumb is simple: if the service or file the engineer should look at can be named, include it; if it can't, the pre-question step is to find out. Doctolib's engineering team offers a useful organizational illustration of this principle at scale. After rolling out Claude Code across the team, Doctolib built a centralized repository of prompts, custom commands, and subagents that every developer pulls from during initial setup. The underlying logic transfers directly to human questions: a shared library of "how to ask about X" reduces the research burden on every future person who needs to ask, because the naming work only has to happen once.

Writing the question itself: format, channel, and length

The same four elements, goal, scope, constraints, elimination record, can still fail to get a fast answer if they arrive in the wrong format or through the wrong channel. Format matters first. Engineers scan from the top of a message, so leading with the actual question, not with background, keeps the response aimed at the right target. If the real question is buried in the third paragraph, the engineer may answer the wrong thing, so a short structured form works for most cases: one sentence on what's needed, one on scope, one on constraints, one on what's already been checked. Four lines covers the majority of technical questions completely. Code snippets, error messages, and log output belong in the original question, pasted verbatim along with environment details like the service name, the version, and the exact command that was run, rather than added in a follow-up after the engineer asks for them. Screenshots of text should be avoided, since they can't be searched or copied into a terminal.

Channel matters just as much as format. Async channels, email, tickets, documented Slack threads, suit most technical questions because they let the engineer answer on their own schedule. Synchronous interruption, a direct Slack ping, walking over to someone's desk, is appropriate only when the question is genuinely blocking and time-sensitive, and when the asker has already done the pre-work so the live conversation stays short. The mismatch to avoid is sending a complex, multi-part question as a quick chat message: the engineer either answers poorly under the pressure of real-time chat or delays while the asker expects an instant reply neither format can deliver.

Length follows the same logic. A technical question should run exactly as long as it needs to and no longer. A one-line question missing scope is too short to act on, and a five-paragraph narrative is too long to scan. If a question doesn't fit into the short structured block above, it may actually be two questions, and splitting them serves both the asker and the engineer better than forcing one exchange to carry two problems.

Compare the same underlying issue stated two ways. Poorly formatted: "Hey, is there a way to fix the search thing? It's been acting weird." Well formatted: "Search on the product page (staging) returns zero results for queries under 3 characters. Need this fixed before Thursday's release. Checked the search service logs, no errors thrown. Haven't touched the indexing config yet, want to confirm that's the right place to look before I do." The second version answers itself halfway there.

Handling an answer more complex than expected

Sometimes an engineer's answer reveals the question was harder than it looked. A dependency nobody flagged, a migration risk, a data model problem that wasn't visible from outside the codebase. The instinct at that point is often to push harder for the original ask or to give up on it entirely, and both responses waste the information the engineer just supplied. The better move treats the engineer's answer as new data that updates the question's scope, constraints, and elimination record, and then sends the next question with that update already built in. Doctolib's repository of known patterns, prompts, and subagents offers a working model for this at the team level: by centralizing what's already been solved, the team cut the number of follow-up questions asked about recurring problems. The same principle scales down to a single exchange between two people. A record of past answers functions as a library that narrows the next question before it's even written. When a problem genuinely needs a meeting rather than another message, a well-formed question still does useful work going in: it sets the agenda and keeps the meeting from starting at zero. There's a useful test for whether a question is being managed well. A question that starts narrow and expands as complexity surfaces is being handled correctly. A question that starts vague and never narrows wastes every round of the exchange, no matter how many rounds it takes. Whatever gets discovered in a complex exchange, the constraint uncovered, the approach the team settles on, belongs somewhere others can find it later, whether that's a ticket, a doc, or a team wiki. That's the same principle behind good documentation generally, and it's the same principle behind code intelligence tooling that indexes what a codebase already contains.

How AI agents change the calculus

AI coding agents raise the cost of a vague question, because an agent will produce a confident, plausible, wrong output instead of stopping to ask a clarifying question the way a human engineer would. Development work has shifted its bottleneck from typing speed to review, with the quality of the original specification acting as a major constraint on how much review is needed. That shift tracks the exact problem a well-formed human question is built to solve. A vague task handed to an agent produces a confident, plausible, wrong diff. A precise task, with the right files and the right context attached, produces something close to mergeable on the first pass. That's the same dynamic at play when a vague question to a human engineer produces a confident but off-target answer: the quality of the output tracks the quality of the input, regardless of who or what is generating the response. The four-part framework, goal, scope, constraints, elimination record, maps directly onto how effective agent prompts get structured, because the agent needs the same information a human engineer needs and has even less room to ask a follow-up question naturally. Gartner's definition of enterprise AI coding agents centers on their ability to discover and use relevant context. Context has to be present for an agent to discover it. An agent handed a vague task with no scope information doesn't pause to ask; it fills the gap with an assumption of its own, often the wrong one. Supplying agents with full codebase context, not just the files sitting on one developer's machine, is the infrastructure-level version of the same discipline this piece has described from the start: scope has to be supplied deliberately. It is never something a system, human or automated, should be left to assume.

Building a culture where better questions are the norm, not the exception

Individual discipline around question formatting compounds once it becomes a team norm, because the total interrupt load an engineering team carries reflects that discipline, not just the cost of any single exchange. The organizational version of the four-part framework is a shared template built into whatever tool a team already uses, Jira, Linear, Confluence, Slack, so that every question arrives with scope and constraints at least partly filled in before an engineer ever sees it. Atlassian research has found that developers lose many hours each week to non-coding work, including finding information and switching context between tasks. Team-level question discipline directly shrinks the portion of that loss caused by questions that arrived incomplete. New-hire onboarding is the highest-leverage moment to install this habit, since engineers who join with a framework for asking questions reduce their interrupt load on senior colleagues starting in their first week. The feedback loop reinforces itself: when an engineer gets a well-formed question and can answer it in a single response, acknowledging that explicitly reinforces the behavior that produced it. Documentation of past answers closes the loop at team scale, turning a record of well-answered questions into a searchable library that reduces the next similar question to a lookup rather than an interruption, the same function code intelligence tooling serves at the level of the repository itself. The aim is to make sure that every question that does reach engineers is one they are actually the right person to answer, because everything that could have been resolved beforehand already was.