💻 Coding
Software Engineer Prompt: Design Doc From Ticket and Notes
Turn a ticket, your system notes, constraints, and traffic numbers into a one-page design doc with options, capacity math, a rollout plan, and open questions.
0Reviews
Prompt
Act as a staff software engineer who turns a ticket, notes on the current system, and the team's constraints into a one-page technical design doc, compares the options honestly, and does the capacity math only with the numbers the engineer provides. Inputs: - Ticket or problem statement: [Ticket] - Current system: services, data stores, and how requests flow: [CurrentSystem] - Hard constraints (budget, latency, compatibility, deadlines): [Constraints] - Options the team is considering: [Options] - Traffic and load numbers: [TrafficNumbers] - Team and time available: [TeamAndTime] Generate: 1. Context and problem: what is broken or missing, in three sentences, from Ticket. 2. Goals and non-goals for this design. 3. Options table: each option from Options checked against every item in Constraints, with pros, cons, and a pass or fail per constraint. 4. Recommended design: components touched, request flow, data and API changes, and why it beats the other options. 5. Capacity math: show every calculation from TrafficNumbers, and mark any number that still needs measuring. 6. Rollout plan: feature flag or staged rollout, metrics to watch, and the rollback step. 7. Risks and open questions, each with a suggested owner from TeamAndTime. 8. Test plan: unit, integration, and load tests tied to the goals. Rules: - Use only the systems, tools, and numbers in the inputs; write "needs measuring" instead of guessing a latency or a cost. - Keep the design doc to one page of headings and short bullets.
Instructions
Paste your own ticket, system notes, constraints, and real traffic numbers. Works on ChatGPT, Claude, and Gemini. Remove secrets, credentials, and anything your company does not allow in AI tools, and have the team review the numbers before the design is approved. Never paste API keys, tokens, passwords, private keys, connection strings, or customer data; replace them with placeholders.
Generated Output
This image was generated using the prompt above.
Examples
Example Input
Ticket: Add per API key rate limiting to the public search endpoint. A few API keys caused p95 latency spikes last month. CurrentSystem: Node.js Express API on 4 hosts, each with its own nginx in front; a Redis cluster already used for sessions; Postgres for data. Requests are spread evenly across the 4 hosts. Constraints: no new paid services this quarter; return HTTP 429 with a Retry-After header; added latency under 5 ms at p95; existing API keys keep working. Options: A) nginx limit_req keyed on the API key on each host. B) token bucket per API key in Express middleware, stored in Redis with one Lua script call per request. C) a managed API gateway. TrafficNumbers: peak 1,200 requests per second in total; the top 5 API keys send 40% of peak traffic; target limit 20 requests per second per key with bursts up to 40. TeamAndTime: 2 backend engineers and 1 SRE, 3 weeks
Example Output
DESIGN DOC: Per API key rate limiting for search 1. CONTEXT AND PROBLEM A few API keys send enough traffic to push search p95 latency up for everyone. There is no per key limit today. We need one that returns 429 with Retry-After and adds under 5 ms at p95. 2. GOALS AND NON-GOALS Goals: enforce 20 requests per second per key with bursts up to 40; 429 plus Retry-After; existing keys keep working. Non-goals: per plan pricing tiers, limits on other endpoints, abuse detection. 3. OPTIONS A) nginx limit_req per host. No new paid service: pass. 429 + Retry-After: needs extra config, verify. Under 5 ms: likely, needs measuring. Accuracy: fail. Each of the 4 hosts counts on its own, so with even spreading a key could get up to 4 x 20 = 80 requests per second. B) Redis token bucket in middleware. No new paid service: pass (Redis cluster exists). 429 + Retry-After: pass, set in code. Under 5 ms: one Redis call per request, needs measuring. Accuracy: pass, one shared count across hosts. C) Managed API gateway. No new paid service: fail. 4. RECOMMENDED DESIGN: Option B Request flow: nginx, then Express rate limit middleware, then the search handler. The middleware runs one Lua script per request that refills and takes a token from the bucket for that key (capacity 40, refill 20 per second) and returns allowed or the wait time. Denied requests get 429 with Retry-After set from the wait time. No Postgres or API contract changes. 5. CAPACITY MATH - Redis load: 1 script call per request x 1,200 requests per second at peak = 1,200 calls per second, on top of current session traffic. - Per host: 1,200 / 4 = 300 requests per second. - Top 5 keys: 40% x 1,200 = 480 requests per second, about 96 per key if evenly split. At 20 per key they are held to 5 x 20 = 100 requests per second, so about 380 requests per second at peak would get 429s. - Other keys: 1,200 - 480 = 720 requests per second; unaffected unless one exceeds 20. - Added latency of the Redis call: needs measuring in staging against the 5 ms p95 limit. 6. ROLLOUT PLAN Week 1: build middleware behind a flag in log-only mode (count would-be 429s, block nothing). Week 2: review log-only counts per key; contact the top 5 key owners with the new limit. Week 3: enforce on 1 of 4 hosts, then all 4. Watch p95 latency, 429 rate, Redis CPU. Rollback: turn the flag off; requests skip the middleware. 7. RISKS AND OPEN QUESTIONS - Redis down: fail open or fail closed? Owner: SRE. - Do the top 5 keys belong to partners who need a higher limit? Owner: backend engineer 1. - Is 1,200 calls per second safe for the session Redis cluster? Owner: SRE, load test. 8. TEST PLAN Unit: bucket refill and burst math, Retry-After value. Integration: with a full bucket, 41 requests sent at once return 40 allowed and one 429 with Retry-After. Load: replay peak traffic of 1,200 requests per second in staging and measure added p95.