decision-and-rfc SKILL.md skillA
decision-and-rfc from webkubor/writing-standard-skills is an agent skill: a SKILL.md folder an AI agent loads when a task calls for it.
mdr add webkubor/writing-standard-skills/decision-and-rfc@git:20261025.4eaa475Pins git:20261025.4eaa475 in mdr.lock. Pin the fingerprint instead.
- Audit grade
- A, 17 of 17 checks passed
- Kind
- SKILL.md skill
- Repository
- webkubor/writing-standard-skills
- Path
skills/decision-and-rfc/SKILL.md- Versions recorded
- 1
- Latest version
- git:20261025.4eaa475, committed Oct 25, 2026
- Size
- 7,182 bytes
- Repository stars
- 6
- License
- MIT
架构决策记录（ADR）、技术提案（RFC）与重大方案论证的表达规范。基于第一性原理、权衡对齐（Trade-offs）与可证伪性。拒绝报喜不报忧，要求显式声明放弃的代价与推翻条件。触发："写方案 / 架构决策 / ADR / RFC / 技术提案 / 选型报告 / 为什么选这个 / 方案对比 / 技术立项 / 重构方案"。.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# 架构决策记录（ADR）与技术方案（RFC）表达规范
架构与方案的本质是**在冲突的约束中做权衡（Trade-offs）**。没有完美的架构，只有适合当前阶段约束的妥协。
**只写优点、不写代价的技术方案，是不诚实的欺骗。** 一份深度的架构决策，必须清晰交代：**为什么现有机制不可用、选它的代价是什么、放弃了哪些备选方案，以及在什么条件下本方案必须被推翻。**
---
## 零、ADR / RFC 五步骨架（The Decision Skeleton）
动笔撰写任何技术提案、重构方案或架构决策前，按此骨架填空：
```
① 本质矛盾 第一性原理下钻 · 当前物理瓶颈是什么 · 不做该方案的年化代价
② 决策结论 选了什么方案 · 核心架构图 · 数据流与契约约束
③ 权衡矩阵 获得了什么 vs 付出了什么代价 · 引入的新复杂度由什么机制兜底
④ 方案墓碑 考虑过的备选方案 B/C · 在当前什么事实下被否决（防止后人重复讨论）
⑤ 推翻条件 可证伪性 · 当什么指标突破阈值时，本架构必须被推翻重做
```
---
## 一、关键段落表达规范
### 1. 本质矛盾（Problem Definition）
- **先问第一性原理**：问题本质是性能不够、模型能力不足、还是流程设计错误？
- **量化不做该方案的代价**：
```text
❌ “当前日志记录比较分散，排查问题不太方便，因此需要统一日志中心。”
✅ “当前 5 台服务器日志分散在各机本地，跨机事故定位需串行 SSH 查 5 次，平均 MTTR 为 42 分钟；
上月因日志分散导致的定位超时事故共 3 起，累计中断 114 分钟。”
```
### 2. 权衡矩阵与代价显式化（Trade-offs）
- 必须包含专门的小节：**「我们付出了什么代价（Costs & Limitations）」**。
- 交代三件事：
- **性能/延迟代价**：增加了几毫秒网络延迟？增加了几倍磁盘读写？
- **心智/学习代价**：团队理解新方案需要多长时间？API 是否破坏既有习惯？
- **运维兜底代价**：新依赖挂了怎么办？是否有无状态降级预案？
### 3. 弃用方案墓碑区（Rejected Alternatives）
- **防止团队陷入“月经周期式重提旧方案”的内耗**。
- 记录格式：
```markdown
### 弃用方案：自建 Kafka 消息队列
- **为什么考虑过**：吞吐量极大，生态成熟。
- **为什么在当前阶段否决**：
1. 需至少 3 节点 ZooKeeper/KRaft 集群，每月闲置硬件成本增加 ¥1200+；
…Read the whole file at its exact version.
How to install
mdr add webkubor/writing-standard-skills/decision-and-rfc@sha256:49a39d12c68ebda3The line at the top of this page pins the label git:20261025.4eaa475, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
[](https://markdownregistry.com/a/art_b5z4jon4mo5d5pwx)
3 badge image fetches in 30 days. What the badge shows.
Versions
The registry has recorded 1 version of this file, committed on Oct 25, 2026.
Audit of the latest version
- pass: Frontmatter block present
- pass: Frontmatter declares a name
- pass: Frontmatter declares a description
- pass: Size between 200 bytes and 200 KB (7182 bytes)
- pass: No zero-width or bidi control characters
- pass: No instruction hidden inside an HTML comment
- pass: No link to an exfiltration or paste host
- pass: No credential-shaped string
- pass: No instruction to send local credentials anywhere
- pass: No text hidden with inline styles
- pass: No prompt-injection phrasing
- pass: No curl or wget piped into a shell
- pass: No recursive delete of root, home or parent
- pass: No instruction to read or print local credentials
- pass: No base64 blob over 200 characters
- pass: No link to a raw IP address
- pass: No script tag
Source
webkubor/writing-standard-skills · 6 stars · license MIT · pushed 2026-11-06 · branch main
API
GET https://markdownregistry.com/api/v1/artifacts/art_b5z4jon4mo5d5pwx GET https://markdownregistry.com/api/v1/resolve?ref=webkubor/writing-standard-skills/decision-and-rfc GET https://markdownregistry.com/api/v1/blob/49a39d12c68ebda3702e592b0879bda21037250203d85fd672a584019bb15a67
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
Guides: the SKILL.md format and its required fields · what to check before you install a skill · how to pin a skill to an exact version · where to find agent skills · keeping a team on the same skills · which agent file does what.