我的 Vibe Coding 最佳实践——ADR文档

Posted 2026-06-26 | stdout

工作和业余也用AI写代码，大大小小项目都经历了。从 rules, skills, spec, agent 到 harness 都玩过了

从AI嘴里发现一条比较稳的套路——ADR文档

rule, skills, spec 这些东西最大的问题就是瞎jb指挥。ADR 的好处是记录why，以及决策演变历史。

---
title: 如何使用 ADR
id: ADR-001
date: 2026-06-26 09:01:21
status: accepted
---

ADR

ADR（Architecture Decision Record，架构决策记录）的核心目标很简单：记录为什么做出了某个重要技术决策，而不是记录系统长什么样。

目前比较常见的是 MADR、Nygard ADR 两种风格，但组织方式都大同小异。

一个团队通常会按下面几个层次组织。

1. 一个 ADR 对应一个决策

不要一个 ADR 写整个系统设计。

好的粒度例如：

ADR-001 使用 PostgreSQL 作为主数据库
ADR-002 API 使用 REST 而不是 GraphQL
ADR-003 服务间通信采用 gRPC
ADR-004 用户认证采用 OAuth2 + JWT
ADR-005 使用事件驱动 Outbox Pattern

而不是

系统架构设计.md

因为几年以后，很难知道某个结论为什么来的。

2. 编号保持永久

一般都会固定编号。

adr/

0001-use-postgresql.md
0002-use-rest-api.md
0003-use-grpc.md
0004-use-oauth2.md

编号一旦存在，就不要修改。

即使后来废弃：

0003-use-grpc.md
Status: Superseded by ADR-0018

这样引用不会失效。

3. Status 非常重要

一般都有状态。

Proposed
Accepted
Deprecated ❌
Superseded 🔄
Rejected ⛔️

例如：

Status: Accepted
Date: 2026-06-19 01:02:03

如果后来换了：

Status: Superseded
Superseded by: ADR-0018

而新的 ADR：

ADR-0018
Supersedes: ADR-0003

形成完整历史。

4. 一个 ADR 的典型模板

---
title: ADR-008 使用 PostgreSQL
id: ADR-008
date: 2026-06-18 12:32:46
status: accepted
---


## Context

目前需要：

- ACID
- JSON 查询
- 成熟生态

候选：

- PostgreSQL
- MySQL
- MongoDB

## Decision

选择 PostgreSQL。

## Consequences

优点：

- SQL 功能完整
- JSONB 支持优秀
- 社区成熟

缺点：

- 运维复杂度略高
- 分库分表方案需要额外设计

可以再加：

Alternatives

Decision Drivers

Trade-offs

References

5. 按领域组织，而不是按时间（可选）

在一个目录，用文件名体现领域：

008.backend.use-grpc.md
010.security.use-oauth.md
012.frontend.react-query.md

这样编号保持连续，查找也方便。

6. ADR 之间允许引用

例如：

ADR-0015

Context

依赖：
- ADR-0002
- ADR-0008

Decision

由于 ADR-0008 已经确定 PostgreSQL，
因此 Outbox Pattern 可以直接利用事务。

形成决策网络，而不是孤立文档。

7. ADR 只记录"为什么"

这是很多团队最容易犯的错误。

不要写：

Controller
Service
Repository

这是设计文档。

ADR 应该写：

为什么不用 MongoDB？

为什么不用 GraphQL？

为什么采用 Saga？

为什么拆成多个 Service？

为什么 Event Sourcing 被放弃？

重点永远是 Why，而不是 What。

8. 和设计文档分开

过去很多团队会这样组织：

文档	回答的问题
RFC / Proposal	未来准备怎么做？
ADR	为什么这样做？
Architecture Doc	系统如何组织？
Design Doc	某个功能如何实现？
Runbook	如何运维？

流程是 RFC → ADR → Design Doc → Code。

RFC 用于讨论方案，达成决策后沉淀为 ADR；随后具体实现细节写入设计文档，最终落实到代码。这样既保留了决策依据，又避免 ADR 演变成冗长的设计说明。

在AI 时代，更简洁，易维护的方式是：

ADR 形成决策历史；
DESIGN.md （小项目也可以直接放 README.md）反应当前设计，大量引用 ADR 而不是重复。
迭代排期（spec，phase文档等）引用ADR作为缘由

AI编写的项目，到后期，泥潭就是大量的docs。ADR 的好处是不用修订，全面引用+supersed。保证决策链清晰，低上下文成本

ADR