القائمة
Capture significant architectural decisions as immutable, versioned MADR 4.0 records. Use when a choice is hard to reverse, affects multiple teams, or sets a long-lived constraint.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Build production integrations with Anthropic Claude (Claude 4.5 Sonnet, Claude Opus 4, Claude Haiku 4) via the Messages API — system prompts, multi-turn conversations, tool use (function calling), prompt caching, extended thinking, vision, batched requests, and streaming. Use when wiring Claude into backends, agentic workflows, or evaluating it against other foundation models. Requires ANTHROPIC_API_KEY.
Deploy Cloudflare Workers, Pages, and Workers-with-static-assets safely using Wrangler 4.x with versioned uploads, gradual deployments, preview/production environments, secret bindings, observability, and one-command rollback. Use when shipping edge workloads, API routes, or full-stack apps to Cloudflare. Requires CLOUDFLARE_API_TOKEN with scoped permissions or an authenticated Wrangler session.
Deploy static sites, framework apps (Next.js, Astro, Remix, SvelteKit, Nuxt), Edge Functions, and serverless Functions to Netlify with deploy previews, branch deploys, atomic production promotion, scoped env vars, and instant rollback. Use when releasing on Netlify via CLI, API, or Git-triggered builds. Requires NETLIFY_AUTH_TOKEN (PAT) and NETLIFY_SITE_ID.
Transcribe audio with OpenAI speech-to-text models (gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1) using prompt-guided terminology, segment-level timestamps, optional diarization via post-processing, and reliable artifact delivery. Use when converting interviews, calls, podcasts, or meeting recordings into reviewable text. Requires OPENAI_API_KEY.
Deploy Web Services, Private Services, Background Workers, Cron Jobs, Static Sites, PostgreSQL, and Key-Value (Redis-compatible) on Render via Blueprints (`render.yaml`) or the Render API with preview environments, zero-downtime rolling deploys, health checks, env-group secret scoping, and one-click rollback. Use when releasing services, applying schema migrations, or syncing infra-as-code on Render. Requires RENDER_API_KEY (owner- or workspace-scoped).
Operate Sentry end-to-end — error monitoring, performance tracing, session replay, profiling, release health, source-map upload, ownership routing, alert tuning, issue triage, and CI integration via sentry-cli — across web, mobile, and backend stacks. Use when instrumenting an app, wiring releases into deploy pipelines, or running incident-grade triage. Requires SENTRY_AUTH_TOKEN (org-scoped, `project:releases project:write`), project DSN, and (for source maps) `org` + `project` slugs.
| name | architecture-decision-record |
| description | Capture significant architectural decisions as immutable, versioned MADR 4.0 records. Use when a choice is hard to reverse, affects multiple teams, or sets a long-lived constraint. |
ADRs make architectural intent legible. They convert tribal knowledge into a durable, searchable log of context, options, and consequences so future contributors understand why, not just what. Adopt MADR 4.0 (2025) as the canonical schema and keep records co-located with the code they govern.
| Concern | Recommended |
|---|---|
| Schema | MADR 4.0 (adr.github.io) |
| Storage | docs/adr/NNNN-title.md in the owning repo |
| Tooling | adr-tools v4, log4brains, or Backstage TechDocs |
| Lifecycle states | Proposed, Accepted, Deprecated, Superseded |
| Review | PR-based, CODEOWNERS-gated, async RFC channel |
| Index | Auto-generated README.md rolled up in Backstage |
docs/adr/ directory and CODEOWNERS entry.flowchart LR
A[Trigger: significant decision] --> B[Draft ADR Proposed]
B --> C[Async review on PR]
C --> D{Consensus?}
D -- yes --> E[Merge as Accepted]
D -- no --> B
E --> F[Implement + link from code]
F --> G{Context changed?}
G -- yes --> H[New ADR Supersedes prior]
G -- no --> E
Proposed.// see ADR-0042).Supersedes: ADR-0042.# ADR-NNNN: <Short title of decision>
- Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
- Date: YYYY-MM-DD
- Deciders: @handle1, @handle2
- Consulted: @teamA
- Informed: #channel
## Context and Problem Statement
<2-4 sentences. What forces are at play? Link tickets, metrics, ADRs.>
## Decision Drivers
- <Quality attribute or constraint>
- <Cost / time-to-market>
## Considered Options
1. <Option A>
2. <Option B>
3. Do nothing
## Decision Outcome
Chosen option: "<Option B>", because <justification>.
### Consequences
- Positive: <…>
- Negative: <…>
- Neutral: <…>
## Pros and Cons of the Options
### <Option A>
- Good, because …
- Bad, because …
## More Information
Links, benchmarks, prototypes, related ADRs.
| Pitfall | Symptom | Mitigation |
|---|---|---|
| Retrofitting ADRs months later | Vague context, no alternatives | Write at decision time; allow short ADRs |
| Editing accepted ADRs | Audit trail lost | Supersede via new ADR; keep originals immutable |
| One-option ADRs | Rubber-stamp culture | Require >=2 alternatives + "do nothing" |
| ADRs in a wiki | Drifts from code | Co-locate in repo under docs/adr/ |
| No index | Discoverability collapses | Auto-generate index in CI |
docs/adr/NNNN-kebab-title.md.docs/adr/README.md index grouped by status.adr-tools v4 - https://github.com/npryce/adr-tools