30 Claude Prompts for Tech Specs

You are a software architect who documents decisions after they are made in chat. <context> My team just spent an hour in Slack debating a technical decision and reached a conclusion, but nobody wrote it down. </context> <inputs> - Slack thread or summary of the debate: [PASTE THREAD OR SUMMARY] - Decision reached: [DECISION REACHED] - Decision date: [DECISION DATE] </inputs> <task> Turn the debate into a proper architecture decision record with context, decision, and consequences. </task> <constraints> Use only what was actually discussed, do not invent options nobody raised. Keep the consequences section honest about downsides, not just upsides. </constraints> <format> Return in markdown with sections: Status, Context, Decision, Consequences, Alternatives Considered. </format>

You are a platform engineer responsible for keeping the ADR log consistent. <context> I know the decision I want to make but writing the full ADR from a blank page is slowing me down. </context> <inputs> - Decision title: [DECISION TITLE] - Options considered: [OPTIONS LIST] - Chosen option and why: [CHOSEN OPTION AND REASONING] </inputs> <task> Fill out a complete ADR using our standard template, expanding my short notes into full sentences. </task> <constraints> Do not add options I did not list. Keep the tone neutral and factual, not persuasive. </constraints> <format> Return in markdown with sections: Title, Status, Context, Decision, Consequences, Alternatives Considered, Date. </format>

You are a senior engineer who has seen decisions come back to bite teams that skipped the consequences section. <context> I have a decision and a rationale but I keep writing a thin consequences section that only lists benefits. </context> <inputs> - The decision: [THE DECISION] - Why we chose it: [RATIONALE] - Known risks so far: [KNOWN RISKS] </inputs> <task> Write a balanced consequences section covering both the benefits and the real costs, including migration effort and what becomes harder later. </task> <constraints> Include at least two negative consequences, not just positives. Be concrete, avoid saying something 'might' happen without saying under what condition. </constraints> <format> Return two lists: Positive Consequences and Negative Consequences, each with three to five bullet points. </format>

You are an architect updating a decision the team made a year ago that no longer fits. <context> We have an old ADR that is now outdated because our scale or requirements changed, and I need to formally supersede it. </context> <inputs> - Old ADR summary: [OLD ADR SUMMARY] - What changed since then: [WHAT CHANGED] - New decision: [NEW DECISION] </inputs> <task> Write a new ADR that supersedes the old one, explaining what changed and why the original reasoning no longer holds. </task> <constraints> Do not disparage the original decision, it was reasonable given what was known at the time. Reference the old ADR by name. </constraints> <format> Return in markdown with sections: Status (Supersedes [OLD ADR ID]), Context, What Changed, New Decision, Consequences. </format>

You are a tech lead cleaning up a backlog of undocumented decisions before an audit. <context> We have a list of decisions that were made informally over the past months and never got written up as ADRs. </context> <inputs> - List of undocumented decisions: [LIST OF DECISIONS] - Team size and context: [TEAM CONTEXT] - Audit deadline: [AUDIT DEADLINE] </inputs> <task> Sort this list by which decisions most urgently need a written ADR, based on how hard they would be to reconstruct later and how much they affect other teams. </task> <constraints> Group into High, Medium, Low urgency. Give one sentence of reasoning per item, not a paragraph. </constraints> <format> Return a table with columns: Decision, Urgency, Reason. </format>

You are a principal engineer evaluating whether to build a capability in-house or buy a vendor solution. <context> My team is deciding whether to build a feature ourselves or integrate a third-party service, and leadership wants a clear comparison. </context> <inputs> - Capability needed: [CAPABILITY NEEDED] - Vendor options considered: [VENDOR OPTIONS] - Team capacity available: [TEAM CAPACITY] - Budget constraint: [BUDGET CONSTRAINT] </inputs> <task> Produce a build versus buy trade-off matrix comparing cost, time to ship, ongoing maintenance, and vendor lock-in risk. </task> <constraints> Be honest about hidden costs of building, like ongoing maintenance headcount. Do not favor either option, present the trade-offs neutrally. </constraints> <format> Return a table with rows Cost, Time to Ship, Maintenance Burden, Lock-in Risk, and columns Build and Buy. </format>

You are a database architect advising on a storage layer decision. <context> We are choosing a database for a new service and need to justify the choice to the rest of engineering. </context> <inputs> - Data access patterns: [ACCESS PATTERNS] - Expected data volume: [DATA VOLUME] - Consistency requirements: [CONSISTENCY REQUIREMENTS] - Candidate databases: [CANDIDATE DATABASES] </inputs> <task> Compare the candidate databases against our access patterns and consistency needs, and recommend one with a clear rationale. </task> <constraints> Address at least one real weakness of the recommended option, not only its strengths. Avoid recommending based on popularity alone. </constraints> <format> Return a short comparison table followed by a recommendation paragraph of three to five sentences. </format>

You are a staff engineer writing a memo on service architecture direction. <context> Our team is debating whether to split a growing monolith into services, and the debate keeps going in circles without a written comparison. </context> <inputs> - Current system size and team size: [SYSTEM AND TEAM SIZE] - Pain points today: [CURRENT PAIN POINTS] - Deployment and on-call setup: [DEPLOYMENT SETUP] </inputs> <task> Write a memo comparing staying monolithic versus splitting into services, focused on our actual pain points, not general theory. </task> <constraints> Ground every point in our stated pain points and team size, not textbook arguments. State clearly if the pain points do not justify a split yet. </constraints> <format> Return in markdown with sections: Current Pain, Case for Splitting, Case for Staying, Recommendation. </format>

You are a performance engineer balancing infrastructure cost against latency targets. <context> We can hit a lower latency target but it costs more in infrastructure, and I need to present the trade-off to my manager. </context> <inputs> - Current latency and cost: [CURRENT LATENCY AND COST] - Target latency: [TARGET LATENCY] - Options to get there, such as caching, regional deployment, or bigger instances: [OPTIONS UNDER CONSIDERATION] - Deadline for the decision: [DECISION DEADLINE] </inputs> <task> Build a trade-off table showing each option's expected latency improvement, cost delta, and implementation effort. </task> <constraints> Use rough but specific estimates, not exact numbers you cannot know. Flag which option has the best cost to improvement ratio. </constraints> <format> Return a table with columns: Option, Latency Improvement, Cost Delta, Effort, Notes. </format>

You are an engineering manager deciding which technical debt to pay down this quarter. <context> My team has a long list of known technical debt items and limited time, and I need to prioritize which ones to fix. </context> <inputs> - List of debt items: [LIST OF DEBT ITEMS] - Available engineering time: [AVAILABLE TIME] - Recent incidents caused by debt: [RECENT INCIDENTS] </inputs> <task> Rank the debt items by the trade-off between effort to fix and risk or velocity cost of leaving them, using the incident history as evidence. </task> <constraints> Do not rank every item as high priority, force real differentiation. Reference the incident history where it applies to an item. </constraints> <format> Return a ranked table with columns: Debt Item, Effort, Risk If Unfixed, Priority. </format>

You are a backend engineer writing an API specification before implementation starts. <context> I need to define a new REST endpoint clearly enough that another team can build a client against it without asking me questions. </context> <inputs> - Resource name: [RESOURCE NAME] - Operations needed: [OPERATIONS, e.g. CREATE, READ, UPDATE, DELETE] - Auth model: [AUTH MODEL] - Example use case: [EXAMPLE USE CASE] </inputs> <task> Write a specification for this API covering endpoints, request and response shapes, status codes, and error format. </task> <constraints> Use realistic field names and types, not placeholder text. Include at least one error response example, not only the happy path. </constraints> <format> Return in markdown with a table of endpoints and a JSON example for one full request and response cycle. </format>

You are an API architect deciding how to version a public API. <context> We are about to ship breaking changes to an API that external partners depend on, and we need a versioning strategy before we ship anything. </context> <inputs> - Current API consumers: [CURRENT CONSUMERS] - Type of breaking change planned: [BREAKING CHANGE DESCRIPTION] - Release timeline: [RELEASE TIMELINE] </inputs> <task> Recommend a versioning approach and write a short doc explaining how consumers will migrate and how long the old version stays supported. </task> <constraints> Name a specific deprecation window in weeks or months, not 'eventually'. Address how we communicate the change to consumers. </constraints> <format> Return in markdown with sections: Recommended Approach, Deprecation Timeline, Consumer Communication Plan. </format>

You are a systems engineer designing an event schema for an event-driven architecture. <context> We are adding a new event type to our message bus and need the schema reviewed before other services start consuming it. </context> <inputs> - Event name and trigger: [EVENT NAME AND TRIGGER] - Fields needed by consumers: [FIELDS NEEDED] - Existing similar events, if any: [SIMILAR EXISTING EVENTS] </inputs> <task> Design the event schema, including field names, types, and whether each field is required, and note how it should evolve without breaking consumers. </task> <constraints> Follow the naming pattern of the existing similar events if given. Call out any field that might need to change shape later and how to version it. </constraints> <format> Return a JSON schema example followed by a short list of forward-compatibility notes. </format>

You are a developer relations engineer writing a migration guide for a breaking API change. <context> We shipped a breaking change to our API and I need to write a guide that helps consuming teams migrate without a support ticket flood. </context> <inputs> - What changed: [WHAT CHANGED] - Old behavior: [OLD BEHAVIOR] - New behavior: [NEW BEHAVIOR] - Migration deadline: [MIGRATION DEADLINE] </inputs> <task> Write a migration guide that shows the old and new usage side by side and gives a step-by-step path to update. </task> <constraints> Use a concrete before and after code example, not a description of the change in words only. State the deadline clearly near the top. </constraints> <format> Return in markdown with sections: What Changed, Before and After Example, Migration Steps, Deadline. </format>

You are a senior backend engineer reviewing an API contract before another team starts building against it. <context> A teammate proposed an internal API contract and I want a second opinion before we commit to it. </context> <inputs> - Proposed API contract: [PASTE CONTRACT OR SCHEMA] - Known future requirements: [FUTURE REQUIREMENTS] - Consuming team: [CONSUMING TEAM] </inputs> <task> Review the contract for consistency, missing error cases, and fields that will likely need to change once the future requirements land. </task> <constraints> Focus on structural issues, not naming style preferences. Call out anything that would be a breaking change to fix later if shipped as is. </constraints> <format> Return a numbered list of issues, each tagged as Structural, Missing Case, or Future Risk. </format>

You are a senior engineer drafting a request for comments for a new internal service. <context> I want to propose building a new internal service and need an RFC that other engineers can give real feedback on. </context> <inputs> - Service purpose: [SERVICE PURPOSE] - Teams that would depend on it: [DEPENDENT TEAMS] - Rough scope, in or out: [IN SCOPE AND OUT OF SCOPE] </inputs> <task> Draft an RFC covering motivation, proposed design, scope boundaries, and open questions for reviewers. </task> <constraints> State scope boundaries explicitly, list what is out of scope, not only what is in scope. Keep the proposed design section high level, this is not a full spec. </constraints> <format> Return in markdown with sections: Motivation, Proposed Design, In Scope, Out of Scope, Open Questions. </format>

You are the author of an RFC responding to reviewer comments before a final decision. <context> My RFC got several comments raising concerns and I need to respond to each one clearly before we can close the review. </context> <inputs> - Reviewer comments: [PASTE COMMENTS] - My current thinking on each: [YOUR RESPONSES OR NOTES] - RFC title: [RFC TITLE] </inputs> <task> Turn my rough response notes into clear, respectful replies to each comment, updating the proposal where the comment changed my thinking. </task> <constraints> Do not dismiss a comment without addressing its concern directly. If a comment changes the design, say so plainly, do not bury the change. </constraints> <format> Return a list matching each original comment to a clear response, marked Addressed, Partially Addressed, or Declined With Reason. </format>

You are a staff engineer writing an executive summary for a technical proposal going to leadership. <context> My full technical proposal is long and leadership needs a short summary before they will read further or approve budget. </context> <inputs> - Full proposal content: [PASTE FULL PROPOSAL] - Ask from leadership, such as budget, headcount, or approval: [SPECIFIC ASK] - Decision deadline: [DECISION DEADLINE] </inputs> <task> Write an executive summary that states the problem, the proposed solution, the cost, and the specific ask in a form a non-technical leader can act on. </task> <constraints> Maximum 200 words. No technical jargon without a one-clause explanation. State the ask as the last sentence, not buried in the middle. </constraints> <format> Return a single paragraph followed by one bolded sentence stating the ask. </format>

You are a tech lead flagging a dependency your proposal creates for another team. <context> My proposal requires work or a decision from another team, and I want to communicate that dependency clearly instead of surprising them later. </context> <inputs> - What we need from the other team: [SPECIFIC ASK] - Why we need it: [REASON] - Timeline we are working against: [TIMELINE] </inputs> <task> Write a short, direct message to the other team explaining the dependency, why it exists, and what we need from them by when. </task> <constraints> Be specific about the ask, not vague like 'let us know your thoughts'. Acknowledge this is a request on their time, not an assumption they will say yes. </constraints> <format> Return a short message of four to six sentences, ready to send as a message or doc comment. </format>

You are an engineering lead who decided not to move forward with a proposed RFC. <context> We are closing an RFC without approving it and I want to document why clearly so the idea does not get relitigated without new information. </context> <inputs> - RFC summary: [RFC SUMMARY] - Reasons for rejection: [REASONS] - Conditions under which we would revisit it: [REVISIT CONDITIONS] </inputs> <task> Write a rejection rationale memo that respects the effort put into the proposal while being clear about why we are not moving forward now. </task> <constraints> Be direct about the reasons, do not soften them into vague language. State the specific conditions that would justify revisiting it. </constraints> <format> Return in markdown with sections: Decision, Reasons, Conditions for Revisiting. </format>

You are an SRE turning a design doc into an operational runbook. <context> We shipped a system based on a design doc, and now on-call needs a runbook instead of the original design reasoning. </context> <inputs> - Design doc content: [PASTE DESIGN DOC] - Known failure modes so far: [KNOWN FAILURE MODES] - Alerting in place: [CURRENT ALERTS] </inputs> <task> Extract the operational parts of the design doc into a runbook: what can fail, how to detect it, and first steps to mitigate. </task> <constraints> Drop the original design rationale and history, on-call needs actions, not context. Use imperative steps, not descriptive prose. </constraints> <format> Return in markdown with sections: Known Failure Modes, Detection, Mitigation Steps, Escalation. </format>

You are a tech lead auditing old architecture documentation for accuracy. <context> We have architecture docs that are a year or more old and I suspect parts no longer reflect the current system. </context> <inputs> - Old doc content: [PASTE OLD DOC] - What has actually changed since: [KNOWN CHANGES SINCE] - Last review date: [LAST REVIEW DATE] </inputs> <task> Compare the doc against the known changes and flag which sections are likely stale, outdated, or misleading now. </task> <constraints> Do not rewrite the doc, only flag what is likely wrong and why. Be specific about which sentence or section is affected. </constraints> <format> Return a list of flagged sections, each with the original text quoted and a note on why it is likely stale. </format>

You are an incident commander writing follow-up documentation after a postmortem. <context> Our postmortem surfaced a decision we should formally document going forward, and it should not just live in the incident doc. </context> <inputs> - Postmortem summary: [PASTE POSTMORTEM SUMMARY] - Decision or change coming out of it: [RESULTING DECISION] - Incident ID: [INCIDENT ID] </inputs> <task> Extract the architectural decision from the postmortem and write it up as a standalone ADR, referencing the incident as context. </task> <constraints> Reference the incident by name or ID, do not restate the entire postmortem. Keep the ADR focused on the decision, not the timeline of the incident. </constraints> <format> Return in markdown with sections: Status, Context (Incident Reference), Decision, Consequences. </format>

You are a senior engineer helping a new hire ramp up on the system architecture. <context> A new engineer is joining my team and I want to check our onboarding docs actually cover what they will need to know. </context> <inputs> - Current onboarding doc content: [PASTE ONBOARDING DOC] - New hire's role and prior experience: [ROLE AND EXPERIENCE LEVEL] - Start date: [START DATE] </inputs> <task> Identify gaps in the onboarding doc, specifically architectural context a new hire at this experience level would need but is not covered. </task> <constraints> Assume no prior knowledge of our specific system, but do assume general engineering competence at the stated experience level. List gaps, do not write the missing content. </constraints> <format> Return a numbered list of gaps, each with a one-sentence explanation of what is missing and why it matters early on. </format>

You are an engineering director preparing a quarterly architecture review for leadership. <context> I need to summarize the quarter's major architecture decisions and trade-offs for a leadership review meeting. </context> <inputs> - List of ADRs or decisions made this quarter: [LIST OF DECISIONS] - Notable incidents or debt tackled: [INCIDENTS OR DEBT ADDRESSED] - Upcoming architecture priorities: [UPCOMING PRIORITIES] </inputs> <task> Summarize the quarter's architecture decisions, what they cost or saved, and what is coming next, for an audience that is not deep in the technical details. </task> <constraints> Keep each decision to two sentences. Translate technical trade-offs into business impact where possible, cost, risk, or speed. </constraints> <format> Return in markdown with sections: Decisions This Quarter, Incidents and Debt Addressed, Upcoming Priorities. </format>