用途
该技能是一份编写架构决策记录（Architecture Decision Records，简称 ADR）的写作指南，面向 VedaGhosham 项目，内容基于该项目 docs/architecture-decisions/ 目录下已有的 13 份 ADR 提炼而成。其目标是帮助开发者写出高质量、可长期维护的 ADR，把项目中重要的技术决策连同背景、理由、实现方式和权衡取舍完整记录下来。
什么是 ADR
ADR 用于记录项目开发过程中做出的重要技术决策，通常包含：做了什么决策、为什么做（问题背景）、如何实现（含代码示例）、权衡取舍（获得了什么、失去了什么）、考虑过的替代方案。
何时编写 ADR
当决策满足以下条件时应编写 ADR：影响整个系统（如数据库选型、框架选择、部署策略）；难以逆转（如 DynamoDB 单表设计、monorepo 结构）；涉及重大权衡（如 tRPC 与 REST、Remix 与 Next.js 的取舍）；设定架构模式（如实体结构、错误处理、认证方式）；需要为未来保留上下文（解释为何选择该方案而非替代方案）。
资料中给出的 ADR 示例包括：选择 DynamoDB 单表设计（ADR-004）、选择 tRPC 而非 REST（ADR-005）、邮件黑名单管理策略（ADR-015）、从数据库加载最新用户数据而非使用 JWT（ADR-001）、使用 pnpm workspaces 的 monorepo（ADR-009）。
不属于 ADR 的决策示例：给实体新增字段（常规变更）、重构组件（实现细节）、修复 bug、更新依赖（维护任务）。
文件命名与文档结构
命名规范为 docs/architecture-decisions/adr-NNN-kebab-case-title.md，其中 NNN 为补零的三位数字（001、002、015 等），标题为描述性的小写连字符格式，编号通过查看现有 ADR 确定下一个可用值。示例：adr-001-fresh-user-data.md、adr-005-trpc-over-rest.md、adr-015-email-blacklist-bounce-management.md。
每份 ADR 遵循统一结构：标题（# ADR-NNN: 清晰简洁的描述）、头部字段（Date 采用 YYYY-MM-DD 格式、Status、Context 一行摘要），随后依次为 Problem（问题描述，含 2-4 个替代方案及各自问题）、Decision（决策及理由）、Implementation（实现细节与代码示例）、Benefits（收益）、Trade-offs（权衡：获得什么、失去什么、为何可接受）、Comparison（对比表格）、Real-World Example（真实场景示例）、Future Considerations（未来考量）、Related Files（相关文件）、References（参考链接）。
写作规范要点
标题需清晰具体，例如「ADR-001: Load Fresh User Data from Database (Not Stale JWT)」，避免「User Data」这类模糊表述。状态取值包括 Proposed（考虑中）、Accepted（已采纳并实现）、Deprecated（不再推荐）、Superseded（被其他 ADR 取代，需引用 ADR-XXX）。
问题部分应说明背景（至少 3-5 段）、展示问题或替代方案的代码示例、列出 2-4 个替代方案并说明各自权衡。决策部分采用「Use [方案] for [用途]」的格式，并列出带证据的理由。实现部分应展示可运行代码（而非伪代码）、在注释中标注文件路径、用行内注释解释关键模式，覆盖基础设施/配置、核心业务逻辑、API 层、前端集成、测试/监控等主要方面。收益部分用加粗标注收益名称，并尽量量化（百分比、时间、成本）。权衡部分分别列出「获得」与「失去」，并逐条解释为何可接受。对比部分用表格跨维度比较替代方案，使用 ✅（优势）、❌（劣势）、⚠️（部分/有条件）符号。真实案例部分给出具体场景，展示采用替代方案与采用所选方案的逐步流程及量化收益。未来考量部分讨论决策可能的演进方向与当前状态。相关文件部分按类别列出实现该决策的文件路径。参考部分列出相关资源链接与交叉引用的其他 ADR。
代码示例标准
使用代码库中真实可运行的代码而非伪代码；在注释中标注文件路径；为非显而易见的行为添加解释性注释；展示错误与正确写法的前后对比。
写作风格
要求具体而非抽象（如「单表每月 5 美元 vs 多表每月 35 美元，节省 85%」而非「单表更便宜」），尽量使用数字与指标。
适用场景与限制
该技能适用于需要为技术决策建立长期文档记录的开发团队，尤其是采用 TypeScript monorepo、DynamoDB、tRPC 等技术栈的项目。资料中未提供该技能的具体安装方式、收费模式、支持平台或效果数据，这些信息暂未提供。