Communitygithub.com

architecture-decision-records

在 Claude Code 工作階段中擷取架構決策，並將其結構化為 ADR。自動偵測決策時刻，記錄背景、考慮過的替代方案及理由。維護 ADR 日誌，讓未來開發者理解程式碼庫為何如此設計。

architecture-decision-records 是什麼？

此技能旨在於 AI 輔助開發會話（如 Claude Code）中，自動或半自動地產生架構決策記錄（ADR）。它能偵測使用者討論架構權衡、比較技術選項或明確要求記錄的時刻，並根據 Michael Nygard 的輕量級 ADR 格式，自動生成結構化的 Markdown 文件。技能支援完整的 ADR 生命週期管理，包括提議、接受、棄用和取代狀態，並自動維護一個索引文件（docs/adr/README.md）以供快速查閱。主要適用於 Claude Code 及類似平台，透過標準化文件產生流程，確保團隊的架構知識不會遺失在對話或程式碼審查中。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

架構決策記錄 (Architecture Decision Records)

在編碼過程中即時捕捉架構決策。與其讓決策只存在於 Slack 討論串、PR 評論或某人的記憶中，此技能能產生命結構化的 ADR 文件，並與程式碼共存。

啟用時機

  • 使用者明確表示「讓我們記錄這個決定」或「將此記錄為 ADR」
  • 使用者在重要的替代方案之間做出選擇（框架、函式庫、模式、資料庫、API 設計）
  • 使用者說「我們決定...」或「我們選擇 X 而非 Y 的原因是...」
  • 使用者問「為什麼我們選擇 X？」（讀取現有 ADR）
  • 在規劃階段討論架構權衡取捨時

ADR 格式

採用 Michael Nygard 提出的輕量級 ADR 格式，並針對 AI 輔助開發進行調整：

# ADR-NNNN：[決策標題]

**日期**：YYYY-MM-DD
**狀態**：proposed | accepted | deprecated | superseded by ADR-NNNN
**決策者**：[參與人員]

## 背景

是什麼問題促使我們做出這個決策或改變？

[2-5 句話描述情境、限制條件及影響因素]

## 決策

我們提議或正在進行的改變是什麼？

[1-3 句話清楚陳述決策]

## 考慮過的替代方案

### 替代方案 1：[名稱]
- **優點**：[好處]
- **缺點**：[壞處]
- **不選原因**：[拒絕該方案的具體原因]

### 替代方案 2：[名稱]
- **優點**：[好處]
- **缺點**：[壞處]
- **不選原因**：[拒絕該方案的具體原因]

## 後果

這個改變讓哪些事情變得更容易或更困難？

### 正面
- [好處 1]
- [好處 2]

### 負面
- [權衡 1]
- [權衡 2]

### 風險
- [風險與緩解措施]

工作流程

捕捉新的 ADR

偵測到決策時刻時：

  1. 初始化（僅限首次） — 如果 docs/adr/ 不存在，請在使用者確認後才建立該目錄、一個內含索引表格標頭的 README.md，以及一份供手動使用的空白 template.md。未經明確同意，不得建立檔案。
  2. 識別決策 — 提取正在進行的核心架構選擇
  3. 收集背景 — 是什麼問題促使了這個決策？存在哪些限制？
  4. 記錄替代方案 — 考慮過哪些其他選項？為什麼被拒絕？
  5. 陳述後果 — 有哪些權衡取捨？什麼變得更容易／更困難？
  6. 分配編號 — 掃描 docs/adr/ 中的現有 ADR 並遞增編號
  7. 確認並寫入 — 將 ADR 草稿呈現給使用者審查。只有在獲得明確批准後，才寫入 docs/adr/NNNN-decision-title.md。如果使用者拒絕，則丟棄草稿，不寫入任何檔案。
  8. 更新索引 — 附加到 docs/adr/README.md

讀取現有 ADR

當使用者問「為什麼我們選擇 X？」時：

  1. 檢查 docs/adr/ 是否存在 — 如果不存在，回應：「在此專案中找不到任何 ADR。您想開始記錄架構決策嗎？」
  2. 如果存在，掃描 docs/adr/README.md 索引以尋找相關條目
  3. 讀取匹配的 ADR 檔案，並呈現背景與決策章節
  4. 如果找不到匹配項，回應：「找不到該決策的 ADR。您想現在記錄一個嗎？」

ADR 目錄結構

docs/
└── adr/
    ├── README.md              ← 所有 ADR 的索引
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 供手動使用的空白範本

ADR 索引格式

# 架構決策記錄

| ADR | 標題 | 狀態 | 日期 |
|-----|------|------|------|
| [0001](0001-use-nextjs.md) | 使用 Next.js 作為前端框架 | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | 使用 PostgreSQL 而非 MongoDB 作為主要資料儲存 | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | 使用 REST API 而非 GraphQL | accepted | 2026-02-01 |

決策偵測訊號

留意對話中表示架構決策的模式：

明確訊號

  • 「我們用 X」
  • 「我們應該用 X 而不是 Y」
  • 「這個權衡取捨是值得的，因為...」
  • 「將此記錄為 ADR」

隱含訊號（建議記錄 ADR — 未經使用者確認不要自動建立）

  • 比較兩個框架或函式庫並得出結論
  • 做出有明確理由的資料庫綱要設計選擇
  • 選擇架構模式（單體 vs 微服務、REST vs GraphQL）
  • 決定驗證／授權策略
  • 在評估替代方案後選擇部署基礎設施

良好 ADR 的要素

應做

  • 具體明確 — 使用「使用 Prisma ORM」，而非「使用 ORM」
  • 記錄原因 — 理由比結果更重要
  • 包含被拒絕的替代方案 — 未來開發者需要知道考慮過什麼
  • 誠實陳述後果 — 每個決策都有權衡取捨
  • 保持簡短 — ADR 應能在 2 分鐘內閱讀完畢
  • 使用現在式 — 「我們使用 X」而非「我們將會使用 X」

不應做

  • 記錄瑣碎決策 — 變數命名或格式化選擇不需要 ADR
  • 寫成長篇大論 — 如果背景章節超過 10 行，就太長了
  • 忽略替代方案 — 「我們就選了它」不是有效的理由
  • 未標示就補記錄 — 如果記錄過去的決策，請註明原始日期
  • 讓 ADR 過時 — 被取代的決策應參考其替代者

ADR 生命週期

proposed → accepted → [deprecated | superseded by ADR-NNNN]
  • proposed：決策正在討論中，尚未確定
  • accepted：決策已生效並正在遵循
  • deprecated：決策已不再相關（例如功能已移除）
  • superseded：較新的 ADR 取代了此決策（務必連結替代者）

值得記錄的決策類別

類別範例
技術選擇框架、語言、資料庫、雲端服務商
架構模式單體 vs 微服務、事件驅動、CQRS
API 設計REST vs GraphQL、版本策略、驗證機制
資料建模綱要設計、正規化決策、快取策略
基礎設施部署模式、CI/CD 管線、監控堆疊
安全驗證策略、加密方式、機密管理
測試測試框架、覆蓋率目標、端對端 vs 整合測試的平衡
流程分支策略、審查流程、發布節奏

與其他技能的整合

  • 規劃代理：當規劃代理提出架構變更時，建議建立一個 ADR
  • 程式碼審查代理：標記那些引入架構變更但沒有相應 ADR 的 PR

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

accessibility

Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA. Use when building or auditing UI that must meet WCAG 2.2 Level AA, or when reviewing a change for keyboard, contrast, or screen-reader support.

affaan-m/content-engine

Create platform-native content systems for X, LinkedIn, TikTok, YouTube, newsletters, and repurposed multi-platform campaigns. Use when the user wants social posts, threads, scripts, content calendars, or one source asset adapted cleanly across platforms.

affaan-m/ECC

Multi-platform content distribution across X, LinkedIn, Threads, and Bluesky. Adapts content per platform using content-engine patterns. Never posts identical content cross-platform. Use when the user wants to distribute content across social platforms.

affaan-m/fal-ai-media

Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.

affaan-m/manim-video

日本語翻訳：このファイルは manim-video 用の日本語翻訳が必要です

affaan-m/remotion-video-creation

Remotion のベストプラクティス - React で動画を作成する。3D、アニメーション、音声、字幕、チャート、トランジションなどをカバーするドメイン固有の29のルール。

affaan-m/video-editing

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

agent-architecture-audit

Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature. Use when an agent or LLM feature misbehaves and the failing layer is unknown, or before shipping an agent stack.

agent-eval

Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics. Use when choosing between coding agents, or when a change to an agent setup needs measured pass rate, cost, and time rather than an impression.

agent-harness-construction

Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates. Use when defining or revising an agent

agentic-engineering

Operate as an agentic engineer using eval-first execution, decomposition, and cost-aware model routing. Use when planning or executing engineering work that agents will carry out end to end.

agentic-os

Build persistent multi-agent operating systems on Claude Code. Covers kernel architecture, specialist agents, slash commands, file-based memory, scheduled automation, and state management without external databases. Use when building a persistent multi-agent system on Claude Code with its own memory, commands, and scheduling.

agent-introspection-debugging

Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports. Use when an agent run fails and you need a reproducible diagnosis instead of a retry.

agent-payment-x402

Add x402 payment execution to AI agents with per-task budgets, spending controls, and non-custodial wallets. Supports Base through agentwallet-sdk and X Layer through OKX Payments / OKX Agent Payments Protocol. Use when an agent must pay for something itself and needs per-task budgets, spending controls, and a non-custodial wallet.

agent-self-evaluation

Use after completing any non-trivial task. The agent self-rates its output on 5 axes — accuracy, completeness, clarity, actionability, conciseness — with concrete evidence per criterion. Produces a structured 1-5 scorecard with specific improvement suggestions.

agent-sort

Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.

ai-first-engineering

Engineering operating model for teams where AI agents generate a large share of implementation output. Use when setting team process, review gates, or ownership rules for a codebase largely written by agents.

ai-regression-testing

Regression testing strategies for AI-assisted development. Sandbox-mode API testing without database dependencies, automated bug-check workflows, and patterns to catch AI blind spots where the same model writes and reviews code. Use when adding regression coverage to AI-assisted code, or when the same model both wrote and reviewed a change.

android-clean-architecture

Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns. Use when structuring modules, layers, or data flow in an Android or KMP project.

angular-developer

Generates Angular code and provides architectural guidance. Trigger when creating projects, components, or services, or for best practices on reactivity (signals, linkedSignal, resource), forms, dependency injection, routing, SSR, accessibility (ARIA), animations, styling (component styles, Tailwind CSS), testing, or CLI tooling.

相關技能

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community