How to Talk to Developers (Part 2): Technical Requirements Checklist for Specifications
More important than “This feature is critical for business” is “Exactly when does it execute?” Here’s a breakdown of the essential items that make developers say “I can start working on this right away.”
“Business Importance” Doesn’t Matter to Developers
A Slack message arrives.
“Please develop the ○○ feature. Spec attached.”
The developer opens the document. Page 1: “Market Background and Business Importance” Page 2: “Target Customer Analysis” Page 3: “Expected Impact”
Finally on page 4, the feature description appears. But it’s missing what actually matters.
“Add coupon issuance feature.”
So… exactly when does it get issued? Can users get duplicates? What if we run out of coupons?
The developer opens Slack again.
“I reviewed it, but I have a few questions…”
Sound familiar?
In Part 1, we covered how to ask questions when developers say “that’s technically difficult.” Part 2 is about preventing those situations altogether.
“I can start working on this spec right away.”
Have you experienced that moment of relief as a PM when you hear these words and the beginning of building trust? Today, I’ll show you how to get there.
Why Specs Get Revised Three Times
Developers and product managers read the same document in different ways.
What PMs think is important:
- Why is this feature needed (Why)
- What value does it create (Value)
- How does it connect to business goals (Impact)
What developers look for in specs:
- Exactly when does it execute (When)
- Under what conditions does it run (Condition)
- How do we handle exceptions (Exception)
PMs spend 5 pages explaining ‘why,’ Developers spend 10 minutes looking for ‘when.’
Here’s what actually happened to me as a 3-year PM.
Spec Title: “Push Notification Enhancement”
- Page 1: Current notification open rate analysis
- Page 2: Competitor benchmarking
- Page 3: Expected improvement impact
- Page 4: (Finally) Feature description “Send personalized notifications”
Developer questions:
“What’s the criteria for personalization?” “When do we send the notifications?” “What if users have notifications turned off?” “How many times per day can we send?”
My response:
“Well… it depends on user behavior patterns.” “Almost no customers turn off notifications.”
The developer must have been frustrated. How do you code “almost no customers”?
That day, I realized: 3 lines of clear trigger conditions matter more to developers than 5 pages of business background.
💬 Developer Perspective: Interviews
While writing this post, I asked 3 real developers: “What’s the first thing you look for when you receive a spec?”
5-Year Backend DeveloperQ. What’s the first thing you look for in a spec?
A. “When this feature executes. If the trigger isn’t clear, I can’t write code. If it just says ‘when order completes,’ I don’t know if that’s right after payment, after product preparation, or when shipping starts. So I have to ask again.”
Q. What’s the most frustrating moment?
A. “When PMs say ‘obviously it should work that way.’ Developers can’t code ‘obviously.’ We need explicit conditions. They say ‘obviously prevent duplicate payments,’ but what if someone clicks twice within 10 seconds? What if they have two tabs open and pay in both? Each of these scenarios is a line of code.”
4-Year Frontend DeveloperQ. What’s most lacking in specs?
A. “Screen state definitions. Even for a single button, there’s default state / disabled state / loading state / error state. The spec just says ‘save button,’ but what about when it’s saving? When network disconnects? When users spam click? I have to ask about all of it.”
Q. What do you wish PMs would do?
A. “Include screenshots or reference links. Instead of ‘make it like ○○,’ saying ‘like the order screen in the Doordash app’ is so much faster. One example is clearer than a hundred words.”
7-Year Full-Stack DeveloperQ. When do you feel like you’re wasting time?
A. “When the first 3 pages are marketing content but the actual feature spec is half a page. I want to hear ‘why this feature matters’ in the kickoff meeting. In the document, just clearly write ‘what’ and ‘how.’
And the phrase ‘there won’t be customers like that’… I hear it so often, but developers can’t code based on ‘probably won’t happen.’ What if it does? That’s exception handling.”
Q. What makes a good spec?
A. “The first page has a 3-line feature summary, immediately followed by trigger conditions / data specifications / exception cases. If I can read it and within 5 minutes have a mental picture of ‘ah, I’ll code it this way,’ that’s a good spec.”
From Opening the Spec to Writing Code
Let’s imagine this: The process from when a developer receives a spec, opens VS Code, and starts writing the first function.
1. Opens the spec → “What’s this feature?” (looks for feature summary)
2. Thinks about code structure → “When does it execute?” (looks for trigger)
3. Writes function name → function sendCoupon() {
4. Writes conditional statement → “Under what conditions does it execute?” (looks for conditions)
5. Gets stuck → “Where do I get the data?” (looks for data specifications)
6. Gets stuck again → “What if we’re out of coupons?” (looks for exception handling)
7. Not in the spec → Opens Slack: “I have questions…”
The points where they get stuck are exactly what’s missing from your spec.
✅ Specification Checklist for Immediate Development
Now for the main content. This checklist contains the essential items that make developers say “I can start coding right away.”
Section A: Feature Behavior Definition
1. “Exactly when” does it run? (Trigger condition)
This is what PMs miss most often.
| ❌ Bad Example | ✅ Good Example |
|---|---|
| “Issue a coupon” | “Issue a coupon within 5 seconds after signup completion” |
| “Send a notification” | “Send push notification when order status changes to ‘In Transit’. Only if user has opted into notifications” |
| “Award points” | “Automatically award points within 24 hours after payment completion. Cancel points upon refund” |
Key questions:
- This feature executes “when what event occurs”?
- When user clicks a button? Automatically by system? At a specific time?
- Can you write the execution condition in one sentence?
2. What about exceptions? (Edge cases, error cases)
The moment you say “there won’t be customers like that,” that becomes an exception case.
Exception scenarios you must define:
- When network disconnects
- When data is missing (null, empty values)
- When users execute repeatedly (spam clicks, refresh)
- When multiple users access simultaneously
- When system errors occur
Real example: Coupon issuance feature
| Scenario | Handling Method |
|---|---|
| When coupon inventory is 0 | Display “All coupons have been claimed” message + disable button |
| When user who already received tries again | Show “You’ve already claimed this coupon” toast message |
| When issuance API call fails | Retry up to 3 times, on failure show “Please try again later” |
| When non-member accesses | Redirect to login screen |
Section B: Data Specifications
3. What data from where?
Just writing “user name” isn’t enough.
What to clearly define:
- Where the data is stored (user info? order info? external API?)
- Data format (text? number? date?)
- Is it required or optional?
Real example: Order notification sending
| Item | Description |
|---|---|
| Recipient | Order info table > phone number (required) |
| Message content | “Order #{order_id} is in transit” |
| order_id | Order table > order number (8-digit number) |
| Carrier name | Order table > delivery_company (text, max 20 chars) |
4. What when data is missing? (Null handling)
Every piece of data has the possibility of “might not exist.”
Examples:
| Data | When Missing |
|---|---|
| Profile picture | Display default avatar image (URL: /assets/default-avatar.png) |
| Phone number | Display “Phone number not registered” text + activate registration button |
| Address | Show “Cannot place order” notice + “Register delivery address” button |
| Coupon expiration | Display “No expiration” |
Section C: Screen States and Permissions
5. Who can view this screen?
Permission branching is basic security.
Permission branching example: Order detail screen
| User Type | Access Permission | Displayed Items |
|---|---|---|
| Non-member | No access | Redirect to login screen |
| Regular member (owner) | View only | Order info, delivery tracking, cancel button |
| Regular member (other) | No access | “No permission” error page |
| Admin | Full view + edit | Additionally show “Change order status” button |
6. Button state definition
Even a single button has at least 4 states.
Example: “Checkout” button
| State | Condition | Display |
|---|---|---|
| Default | Payment possible | Blue button “Checkout” |
| Disabled | Required info missing (address, payment method) | Gray button + “Please enter delivery address” tooltip |
| Loading | Payment API calling | Loading spinner in button + “Processing…” text |
| Duplicate click prevention | After one click | Disable button (for 3 seconds) |
Section D: External Integrations
7. Third-party service integration info
Essential if you’re using external APIs like payment, maps, social login.
Checklist:
- API documentation URL
- Test account / API key issued?
- Dev environment / prod environment separated?
- Handling method when response fails
Example: Kakao login integration
| Item | Content |
|---|---|
| API docs | https://developers.kakao.com/docs/latest/en/kakaologin/rest-api |
| Required info | Kakao app key (REST API key) |
| Person responsible | John Dev ([email protected]) |
| When response fails | “Kakao login failed” toast message + redirect to regular login screen |
Section E: Performance/Policy Considerations
8. Expected usage volume
“100 users per day” vs “100,000 users per day” requires completely different development approaches.
What to ask:
- How many concurrent users are expected?
- How much data will accumulate? (daily, monthly)
- Is there a specific time when traffic spikes? (e.g., event start time)
Examples:
- Event coupon first-come-first-served 1,000 people → 5,000 concurrent expected → need to prepare for server load
- Regular signup feature → average 50 per day → basic structure sufficient
9. Data retention period
Connected to legal issues like GDPR, privacy protection laws.
What to define:
- How long are user logs retained?
- Upon member withdrawal, delete data immediately? After 30 days?
- Payment info legally required to keep for 5 years (E-Commerce Act)
Practical Template: Self-Diagnosis Checklist for Specs
Paste this checklist on the last page of your spec and check it before sending to developers.
[ ] Can you describe this feature as "who" "when" "what" in one sentence?
[ ] Have you clearly defined trigger conditions?
e.g., "When ○○ button clicked", "Daily at 9 AM", "Within 5 seconds after order completion"
[ ] Have you defined at least 3 exception scenarios?
(Network error, missing data, duplicate execution, no permission, etc.)
[ ] Have you specified the source of data to be used?
(Which table? Which API? What format?)
[ ] Have you written how to handle when data is missing?
(Default value? Error message? Navigate to different screen?)
[ ] Have you indicated branching by permission/state?
(Non-member vs member, owner vs others, admin, etc.)
[ ] Have you defined states of buttons/UI elements?
(Default, disabled, loading, error states)
[ ] When using external APIs, have you attached documentation links and account info?
[ ] Have you shared expected usage volume and traffic?
(Concurrent users, data growth, etc.)
[ ] Have you attached references for developers?
(Other service links, screenshots, similar feature examples)
[ ] Have you kept marketing/business background to within 1 page?
(Developers need 'what, how' more than 'why')
Before & After: Real Specification Comparison
Here’s the same feature written in two different ways.
❌ Before: Spec that gets follow-up questions
Title: Automatic Coupon Issuance Feature Development Request
1. Background Currently, our service’s new user conversion rate is 35%. Competitor A records 50%, which we analyze is because they immediately provide coupons upon new signup.
2. Goal Immediately issue coupons to new signups to improve first purchase conversion rate by 15 percentage points.
3. Expected Impact
- Increase new member first purchase rate
- Reduce marketing costs
- Improve brand favorability
4. Feature Description Automatically issue a $50 coupon upon member signup.
→ Developer’s questions:
- “Right after signup completion? After email verification?”
- “What if we run out of coupons?”
- “What about duplicate signup attempts?”
- “What if issuance fails?”
After: Spec ready for immediate development
Title: Automatic Coupon Issuance Feature Development Request
[One-line Feature Summary] Feature that automatically issues a $50 coupon within 5 seconds after signup completion
[Trigger Conditions]
- Execution timing: Within 5 seconds after signup API response success
- Issuance target: New members (member status = ‘active’)
- Coupon to issue: “New Signup Welcome Coupon” (Coupon ID: NEW_USER_2024)
[Data Specifications]
- User info:
userstable >user_id(PK) - Coupon info:
couponstable >coupon_id= ‘NEW_USER_2024’ - Issuance record: insert into
issued_couponstable- user_id (bigint)
- coupon_id (varchar 20)
- issued_at (datetime)
[Exception Handling]
| Scenario | Handling Method |
|---|---|
| Coupon inventory 0 | Display “All coupons claimed” popup. Don’t record issuance |
| Member who already received | Block duplicate issuance (DB unique constraint). Only log error |
| Issuance API fails | Retry 3 times (1 second intervals). Send admin alert after 3 failures |
| Inactive member (withdrawn/suspended) | Don’t issue |
[Screen Display]
- On signup completion screen, show “Your $50 coupon has been issued!” toast message for 3 seconds
- Display button to navigate to coupon wallet
[Performance Considerations]
- Expected issuance volume: Average 200/day, max 1,000 during event period
- Simultaneous signup scenario: Almost none (regular signup flow)
[References]
- Musinsa app: Auto coupon issuance screen after signup (screenshot attached)
- Doordash: How they handle coupon inventory depletion (link)
[Business Background] (For reference) New user conversion rate 35% → 50% goal. Competitor benchmarking shows immediate coupon issuance is effective.
→ Developer’s response: “Yes, I can start working on this right away. Estimated time: 2 days.”
Three Core Principles
You don’t need to memorize every checklist item. Just remember these 3 principles.
1. You can’t code “obviously”
“Obviously prevent duplicates” → How? “Obviously handle errors” → Which errors?
Turn “obvious” into concrete conditions.
2. “Won’t happen” doesn’t exist
“There won’t be customers like that” “We won’t sell it that way” “That situation won’t occur”
All of these become exception cases. Define them in advance.
3. 3 pages of marketing < 3 lines of triggers
Developers want to understand the feature’s value. But in specs, ‘what, how’ comes first.
Business background in kickoff meetings, Technical specs in documents.
Final Tip: Ask Developers First
Before throwing your complete spec to developers, take 15 minutes in the draft stage to ask:
“I’m planning this feature – from a development perspective, what absolutely needs to be defined?”
This one question prevents 3 rounds of revisions.
Conclusion
“This feature is really important for business” matters to PMs. But to developers, “exactly when does it execute?” matters more.
The purpose of a spec isn’t persuasion—it’s execution. Making it so developers can close the spec and immediately start typing. That’s a good spec.
If Part 1 taught you how to respond when developers say “that’s technically difficult,” Part 2 taught you how to reduce those situations in the first place.
Next time you write a spec, keep this checklist by your side and check each item. When you hear from a developer “I can start working on this spec right away,” a new stage of collaboration begins.