Menu
记录决策和文档。在做出架构决策、修改公共 API、发布功能，或需要记录未来工程师和智能体理解代码库所需的上下文时使用。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | documentation-and-adrs |
| description | 记录决策和文档。在做出架构决策、修改公共 API、发布功能，或需要记录未来工程师和智能体理解代码库所需的上下文时使用。 |
记录决策，而不仅仅是代码。最有价值的文档捕获的是为什么——导致了某个决策的上下文、约束和权衡。代码展示构建了什么；文档解释为什么以这种方式构建以及考虑了哪些替代方案。这一上下文对于未来在代码库中工作的人类和智能体至关重要。
何时不使用： 不要为显而易见的代码编写文档。不要添加重述代码已经表达的内容的注释。不要为一次性原型编写文档。
ADR 捕获重要技术决策背后的推理。它们是你能编写的价值最高的文档。
在创建 ADR 之前，检查可用的仓库上下文以获取已建立的约定——现有的 ADR、项目指令以及与 ADR 相关的配置或工具（例如 .adr-dir 文件）。已建立的约定优先于以下默认值。匹配：
docs/adr/*.md、Documentation/Decisions/*.rst、MADR 布局或 adr-tools 设置。匹配现有目录、文件扩展名和标记语言（Markdown vs reStructuredText）。ADR-004-Title.rst、0004-title.md……）；不要从 001 重新开始或引入第二种方案。如果现有证据冲突，提出冲突而非沉默地引入另一种方案。仅当无法确定任何约定时才应用以下默认值。
将 ADR 存储在 docs/decisions/ 中，使用顺序编号（除非项目已使用其他位置——见上文）：
# ADR-001：使用 Raft 作为元数据复制协议
## 状态
已接受 | 被 ADR-XXX 取代 | 已弃用
## 日期
2025-01-15
## 上下文
我们需要为分布式元数据服务选择复制协议。关键需求：
- 强一致性（元数据变更必须线性一致）
- 少数派故障下仍可写入（5 节点容忍 2 个故障）
- 团队能够正确实现并长期运维该协议
- 有生产环境验证过的实现可参考
## 决定
使用 Raft，基于 etcd raft library 实现。
## 考虑的替代方案
### Paxos
- 优点：理论成熟，学术界验证充分
- 缺点：难以正确实现，Multi-Paxos 的工程细节缺少权威描述
- 拒绝原因：实现和运维成本过高，团队无法长期维护自研 Paxos
### 主从异步复制
- 优点：实现简单，写入延迟低
- 缺点：主节点故障时可能丢失已确认的写入，故障切换依赖外部仲裁
- 拒绝原因：元数据服务不能接受已确认数据的丢失
### EPaxos
- 优点：无 Leader，多地域部署延迟更低
- 缺点：冲突处理复杂，社区实现不成熟
- 拒绝原因：当前单地域部署用不上，复杂度不值
## 后果
- 元数据写入需过半节点确认，延迟增加约一次跨机 RTT
- Leader 选举期间（秒级）写入不可用，客户端需要重试逻辑
- 团队需要理解 Raft 的日志复制与快照机制（有 etcd 等参考实现，风险可控）
- 读请求可通过 ReadIndex / Lease Read 优化，无需每次走日志复制
提议 → 已接受 → （被取代 或 已弃用）
注释为什么，而非是什么：
// 坏：重述代码
// 将计数器增加 1
counter += 1
// 好：解释非显而易见的意图
// 限流使用滑动窗口——在窗口边界重置计数器，
// 而非按固定周期，以防止窗口边界的突发流量击穿阈值
if now.Sub(windowStart) > windowSize {
counter = 0
windowStart = now
}
// 不要注释自解释的代码
func totalShards(replicas []*Replica) int {
total := 0
for _, r := range replicas {
total += r.Shards
}
return total
}
// 不要留下现在就应该做的 TODO 注释
// TODO: 添加错误处理 ← 直接添加
// 不要留下被注释掉的代码
// oldImplementation := func() { ... } ← 删除它，git 有历史记录
// 重要：此函数必须在向其他节点通告本节点之前调用。
// 如果在加入集群之后再设置，节点会以空配置参与
// Leader 选举，可能引发双主。
//
// 完整的设计原理见 ADR-003。
func (n *Node) SetInitialConfig(cfg Config) {
// ...
}
对于公共 API（gRPC、REST、内部库接口）：
// CreateNamespace 创建一个新的命名空间。
//
// name 必填且长度不超过 200 个字符；replicas 为 0 时使用集群默认值。
// 返回带有服务端生成的 ID 和创建时间的命名空间元数据。
// 如果 name 为空或超长返回 ErrInvalidArgument；
// 如果调用方未认证返回 ErrUnauthenticated。
//
// 示例：
//
// ns, err := client.CreateNamespace(ctx, &pb.CreateNamespaceRequest{Name: "orders"})
// log.Println(ns.Id) // "ns_abc123"
func (c *Client) CreateNamespace(ctx context.Context, req *pb.CreateNamespaceRequest) (*pb.Namespace, error) {
// ...
}
service MetadataStore {
// 创建命名空间
rpc CreateNamespace(CreateNamespaceRequest) returns (CreateNamespaceResponse);
}
message CreateNamespaceRequest {
// 命名空间名称，必填，最长 200 字符
string name = 1;
// 副本数，0 表示使用集群默认值
int32 replicas = 2;
}
message CreateNamespaceResponse {
string id = 1;
int64 create_time_unix_ms = 2;
}
每个项目都应该有一个涵盖以下内容的 README：
# 项目名称
一段话描述这个项目做什么。
## 快速开始
1. 克隆仓库
2. 安装依赖项：`go mod download`
3. 设置环境：`cp config.example.toml config.toml`
4. 启动本地开发集群：`make run-dev`
## 命令
| 命令 | 描述 |
|---------|-------------|
| `make run-dev` | 启动本地开发集群 |
| `make test` | 运行测试 |
| `make build` | 编译发布产物 |
| `make lint` | 运行 Linter |
## 架构
项目结构和关键设计决策的简要概述。
链接到 ADR 以获取详细信息。
## 贡献
如何贡献、编码标准、PR 流程。
对于已发布的功能：
# Changelog
## [1.2.0] - 2025-01-20
### 新增
- 快照增量传输：Follower 落后时按增量同步快照（#123）
- 节点扩缩容事件的 metrics 上报（#124）
### 修复
- Leader 快速切换时日志条目被重复应用（#125）
### 变更
- 单次复制批次上限调整为 50 条日志（原为 20），以提升高延迟链路的吞吐（#126）
对 AI 智能体上下文的特殊考虑：
| 合理化借口 | 现实 |
|---|---|
| "代码是自文档化的" | 代码展示是什么。它不展示为什么、哪些替代方案被拒绝或适用哪些约束。 |
| "API 稳定后我们再写文档" | 当你编写文档时 API 稳定得更快。文档是设计的第一个测试。 |
| "没人看文档" | 智能体会看。未来的工程师会看。三个月后的你自己会看。 |
| "ADR 是额外开销" | 一个 10 分钟的 ADR 可以防止六个月后针对同一决策的两小时争论。 |
| "注释会过时" | 关于为什么的注释是稳定的。关于是什么的注释会过时——这就是为什么你只写前者。 |
编写文档后：
指导稳定的 RPC、存储协议和接口设计。在设计节点间 RPC、存储协议语义、模块边界或任何公共接口时使用。在定义 gRPC service、对象存储或文件系统语义、节点间的类型契约，或确立组件边界时使用。
自动化 CI/CD 流水线设置。在设置或修改构建和部署流水线时使用。当需要自动化质量门禁、在 CI 中配置测试运行器，或建立部署策略时使用。当需要处理 CI 上不稳定（flaky）的测试时使用。
进行多维度代码审查。在合并任何变更之前使用。在审查由你自己、另一个智能体或人类编写的代码时使用。当需要在代码进入主分支之前评估其跨多个维度的质量时使用。当需要评估变更的正确性、可读性、架构与性能，或审查 PR/diff 时使用。
为清晰性而简化代码。在重构代码以提高可读性而不改变行为时使用。当代码可以正常工作但比应有的更难阅读、维护或扩展时使用。在审查已积累不必要复杂性的代码时使用。当组件过度设计、过于炫技而难以维护时使用。当需要清理越来越难读懂的代码时使用。
验证系统的一致性与持久性承诺。在设计或修改复制协议、写路径、崩溃恢复逻辑时使用。当需要证明已确认的写入不丢失、副本间不发散、崩溃后能恢复到一致状态，或评审 fsync/校验和/事务语义时使用。
优化智能体上下文设置。在开始新会话、智能体输出质量下降、在不同任务之间切换，或需要为项目配置规则文件和上下文时使用。