نویسنده ثبت تصمیمات معماری: هر انتخاب فنی را با بافت کامل و موازنهها مستند کنید
Why this prompt matters
Undocumented technical decisions are the single largest source of architectural drift in growing codebases. When the engineers who made a decision leave, their reasoning leaves with them. Future teams reverse correct decisions, repeat past debates, and build on assumptions nobody can verify — costing weeks of engineering time per incident and compounding with every hire who joins without the context.
What we use it for
Your team just decided to switch your mobile API from REST to GraphQL after a performance review, and the lead architect is leaving for three weeks tomorrow. You need a complete decision record committed to the repo before institutional memory walks out the door.
Prompt
Act as a Staff Software Engineer with extensive experience writing Architecture Decision Records (ADRs) for high-scale production systems. CONTEXT: Project/system: [YOUR PROJECT OR SYSTEM NAME] Team size: [NUMBER] engineers Current stack: [YOUR CURRENT TECH STACK — e.g., "Node.js, PostgreSQL, AWS, monolithic Rails app"] Decision date: [DATE] Decision status: [Proposed / Accepted / Deprecated / Superseded] THE DECISION: We have decided to: [STATE THE TECHNICAL DECISION IN ONE SENTENCE — e.g., "adopt GraphQL as our primary API layer, replacing the existing REST endpoints"] CONTEXT AND PROBLEM STATEMENT: [Describe in 2-4 sentences the situation that made this decision necessary. What problem were you trying to solve? What constraints were you working within?] ALTERNATIVES CONSIDERED: Option A: [ALTERNATIVE 1 NAME] - Description: [brief description] - Pros: [what made this attractive] - Cons: [what ruled it out or made it less preferred] Option B: [ALTERNATIVE 2 NAME] - Description: [brief description] - Pros: [what made this attractive] - Cons: [what ruled it out or made it less preferred] Option C (chosen): [YOUR CHOSEN APPROACH] - Description: [brief description] - Why chosen: [the decisive factors] KNOWN RISKS OR CONSEQUENCES: [List 2-4 anticipated consequences of this decision — both positive and negative. Include technical debt created, new capabilities unlocked, things that will become harder, and any reversibility concerns.] TASK: Write a complete Architecture Decision Record following the Michael Nygard format with these sections: 1. Title (ADR-[NUMBER]: [brief decision title]) 2. Status ([Proposed/Accepted/Deprecated/Superseded]) 3. Context (the situation and problem) 4. Decision (what was decided and the core rationale) 5. Alternatives Considered (structured comparison table) 6. Consequences (positive, negative, and neutral outcomes) 7. Compliance (how to verify this decision is being followed) 8. Notes (links to related ADRs, tickets, or documentation) CONSTRAINTS: - Keep the Decision section under 150 words — it should be scannable, not exhaustive - Use plain, precise language that a new team member joining in 18 months will understand without context - Do not hedge or write in passive voice — use active, declarative statements - If the decision has an obvious sunset condition or review date, include it OUTPUT FORMAT: Markdown, suitable for committing to a /docs/decisions/ folder. Use ## for section headers. Include a metadata block at the top with date, deciders, and technical story link.
Result
# ADR-024: Adopt GraphQL as Primary API Layer, Replacing REST Endpoints
**Date:** 2026-06-15
**Status:** Accepted
**Deciders:** Elena Vasquez (Staff Eng), James Park (Backend Lead), Sarah Chen (Mobile Lead)
**Technical Story:** ENG-4821 — API Layer Modernization Q3 2026
---
## Context
Our REST API has grown to 87 endpoints over four years, with the mobile clients over-fetching an average of 3.2x the data they use per screen. The iOS team reports that the checkout screen alone requires seven sequential API calls, creating 1.4s of latency on 4G connections. Adding the new wishlist feature would require three additional endpoints and two new response shapes, extending a pattern we cannot sustain.
## Decision
We adopt GraphQL as the primary API layer for all new features starting Q3 2026. Existing REST endpoints remain in place and will be migrated opportunistically over 12 months, with checkout and product detail prioritized first. We use Apollo Server 5 with Prisma as the ORM bridge, and Apollo Client on both iOS and Android.
## Alternatives Considered
| Option | Pros | Cons | Verdict |
|---|---|---|---|
| Extend REST with BFF layer | Low risk, team knows it | Adds another service to maintain; doesn't fix over-fetching structurally | Rejected |
| gRPC | Strong typing, excellent performance | Requires protobuf tooling on mobile; poor browser support for direct calls | Rejected |
| GraphQL (chosen) | Solves over-fetching at the protocol level; strong mobile client libraries; enables schema-driven development | Learning curve for 4 engineers; N+1 query risk requires DataLoader discipline | Accepted |
| REST with sparse fieldsets (JSON:API) | Stays in REST paradigm | Non-standard; tooling fragmented; mobile teams unfamiliar | Rejected |
## Consequences
**Positive:**
- Mobile clients request exactly the fields they need — estimated 60–70% reduction in payload size on high-traffic screens
- Single endpoint for all queries eliminates sequential waterfall calls
- Schema becomes the living documentation of our data model
- Frontend and mobile teams can iterate on data requirements without backend deploys
**Negative:**
- Four engineers need GraphQL training (Q3 2026, estimated 3 days each)
- N+1 query problems require DataLoader implementation discipline — new code review checklist item added
- GraphQL introspection must be disabled in production (security requirement, ENG-4899)
- REST endpoints will exist alongside GraphQL for 12 months, creating dual maintenance burden during migration
**Neutral:**
- Caching strategy changes: REST HTTP caching no longer applies; Apollo's normalized cache and persisted queries replace it
- API documentation moves from Swagger to GraphQL Playground + auto-generated schema docs
## Compliance
Pull requests introducing new API capabilities must use GraphQL. REST additions require explicit sign-off from the API Guild. Schema linting (eslint-plugin-graphql) runs in CI and blocks merge on rule violations.
## Notes
- Related: ADR-019 (API versioning strategy), ADR-022 (mobile client architecture)
- DataLoader patterns: internal wiki at /eng/graphql-dataloader
- Review date: June 2027 — assess migration progress and REST endpoint sunset timeline
تصمیمات فنی مدام گرفته میشود: از کدام پایگاه داده استفاده کنیم، یک کامپوننت را بسازیم یا بخریم، چگونه یک API را ساختاربندی کنیم، چه زمانی کد موجود را refactor کنیم و چه زمانی آن را گسترش دهیم. بیشتر این تصمیمات با دقت گرفته میشوند — و سپس بلافاصله فراموش میگردند. شش ماه بعد، یک مهندس جدید میپرسد چرا سیستم اینگونه ساختاربندی شده است. هیچکس به خاطر نمیآورد. تیم دوباره درباره همان گزینهها بحث میکند. گاهی مسیر را عوض میکنند و چیزی را برمیگردانند که به دلایلی درست بوده است اما اکنون به فراموشی سپرده شدهاند.
ثبت تصمیمات معماری (ADR) پاسخ صنعت مهندسی به این مشکل است. یک ADR سند کوتاه و ساختاریافتهای است که یک تصمیم فنی مهم را ثبت میکند: بافتی که در آن گرفته شده، گزینههای بررسیشده، موازنههای مربوط و پیامدهای انتخاب. شرکتهایی مانند AWS، Spotify و ThoughtWorks شیوههای ADR را به عنوان استاندارد منتشر کردهاند. مشکل این است که نوشتن یک ADR خوب از ابتدا ۳۰ تا ۴۵ دقیقه زمان میبرد و نیاز به تفکر دقیق درباره آنچه باید گنجانده شود دارد.
این پرامپت کار ساختاری را برای شما انجام میدهد. تصمیم، گزینههای جایگزینی که در نظر گرفتهاید و بافت کلیدی را ارائه دهید — و یک ADR کامل و مستدل تولید میکند که تیم شما میتواند مستقیماً در Repository commit کند.
چه زمانی از آن استفاده کنید
این پرامپت را بلافاصله پس از گرفتن یک تصمیم فنی مهم، پیش از آنکه بافت محو شود، استفاده کنید. بهویژه برای تصمیماتی که معکوسکردن آنها دشوار است، بر اعضای آینده تیم که در جلسه نبودهاند تأثیر میگذارد یا نشاندهنده انحراف معناداری از الگوهای پیشین در پایگاه کد است، ارزشمند است.
چه چیزی این پرامپت را مؤثر میکند
بیشتر تیمهایی که سعی میکنند ADR بنویسند، یا خیلی دیر مینویسند (زمانی که بافت از دست رفته است) یا خیلی مختصر (یک خط که چیزی را انتقال نمیدهد). این پرامپت کامل بودن را الزامی میکند: نیاز به یک وضعیت، پیامدهای صریح و بیانیهای روشن از آنچه رد شده و دلیل آن دارد. خروجی به اندازهای ساختارمند است که مستقیماً در پوشه /docs/decisions/ commit شود و مهندسان آینده از طریق جستجو آن را بازیابی کنند.
سازگارکردن خروجی
این پرامپت از قالب Michael Nygard ADR — پرکاربردترین استاندارد — استفاده میکند، اما میتوانید با افزودن یک دستور فرمتدهی، از آن بخواهید از قالب MADR (ثبت تصمیمات معماری Markdown) یا الگوی سفارشی تیم خود پیروی کند. برای تصمیمات بسیار بزرگ با گزینههای زیاد، پرامپت را به دو فراخوانی تقسیم کنید: یکی برای بررسی موازنهها و دیگری برای نوشتن سند نهایی.