Community写作与编辑github.com

mdesoeuv/claude_skills

编写非平凡技术选择的架构决策记录。当用户说“我们应该用X还是Y”、“记录我们选择的原因”、“写一个ADR”时使用,或者当变更引入新服务、数据存储、供应商、模式或跨领域约定时使用。

claude_skills 是什么?

此技能指导用户编写架构决策记录(ADR),以确保未来工程师不会重新打开已解决但未记录原因的问题。它提供了一个标准模板,包含上下文、决策、备选方案、后果和后续行动等部分。该技能支持通过$ARGUMENTS变量传入决策标题,并自动生成对应的文件名。适用于需要记录新技术选型、服务引入或模式变更的场景,旨在帮助团队在18个月后仍能理解决策的初衷。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mdesoeuv/claude_skills/tree/HEAD/skills/adr

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

架构决策记录

ADR的存在是为了确保在十八个月后,没有人会在不知道原因的情况下重新打开一个已解决的问题,并且当上下文发生变化时,可以有意地重新审视该决策。

存放位置

docs/adr/NNNN-short-title.md,按顺序编号。检查目录以获取下一个编号和项目模板;如果存在模板,请遵循它。

模板

# NNNN. <决策形式的标题:"为订单服务使用Aurora PostgreSQL">

日期:YYYY-MM-DD
状态:提议 | 已接受 | 被NNNN取代 | 已弃用
决策者:<姓名或团队>

## 上下文
<哪些力量在起作用:需求、约束、当前的痛点、截止日期、合规性、
团队技能、成本预算。两到四段。事实,而非观点。>

## 决策
<一句话或两句话,现在时态:"我们将……">

## 考虑的选项
### 选项A:<名称>
优点 / 缺点 / 大概成本 / 运营负担
### 选项B:<名称>
…

## 后果
<变得更容易的事情,变得更困难的事情,我们现在需要做的事情(迁移、培训、
新的运行手册),我们明确接受的风险。>

## 后续行动
- [ ] <具体任务,如已知可指定负责人>

编写指南

  • 编写上下文,使新人在阅读决策前认同问题确实存在。
  • 在相同的维度上比较选项:成本、运营负担、锁定风险、团队熟悉度、交付时间、安全性/合规性。有数据时请提供数字(每月成本估算、RTO/RPO、吞吐量)。
  • 诚实地陈述落选选项的优势。对替代方案进行歪曲的ADR将不被信任。
  • 后果包括负面后果。"我们现在有两个数据库需要备份"属于此部分。
  • 保持在两页以内。链接到技术调研、基准测试和工单,而不是内联它们。
  • 当被取代时,更新旧ADR的状态并双向链接。

当$ARGUMENTS给出时

将其用作标题;从其中推导出文件名。

Individual skills in this repo

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

相关技能