source-driven-development

name	source-driven-development
description	将每个实现决策扎根于官方文档。当需要权威、有来源引用的代码且不包含过时模式时使用。当使用任何正确性很重要的框架或库构建时使用。

源码驱动开发

概述

每个框架特定的代码决策必须由官方文档支持。不要凭记忆实现——验证、引用，并让用户看到你的来源。训练数据会过时，API 会被弃用，最佳实践会演变。此技能确保用户得到他们可以信任的代码，因为每个模式都追溯到他们可以检查的权威来源。

何时使用

• 用户想要遵循给定框架的当前最佳实践的代码
• 构建将在整个项目中复制的样板代码、启动代码或模式
• 用户明确要求文档化的、已验证的或"正确的"实现
• 实现框架推荐方法重要的情况（协议编解码、并发模型、持久化、副本一致性、认证）
• 审查或改进使用框架特定模式的代码
• 任何时候你将凭记忆编写框架特定代码

何时不使用：

• 正确性不依赖于特定版本（重命名变量、修复拼写错误、移动文件）
• 在所有版本中工作相同的纯逻辑（循环、条件判断、数据结构）
• 用户明确想要速度优先于验证（"快速做就行"）

流程

检测 ──→ 获取 ──→ 实现 ──→ 引用
  │          │           │            │
  ▼          ▼           ▼            ▼
 什么       获取        遵循         展示你
 技术栈？   相关文档    文档化的模式  的来源

步骤 1：检测技术栈和版本

阅读项目的依赖项文件以识别确切版本：

go.mod          → Go（标准库、gRPC-Go、自研 Raft 库版本）
Cargo.toml      → Rust（tokio、rocksdb、raft-rs）
CMakeLists.txt  → C/C++（内核模块、存储引擎）
requirements.txt / pyproject.toml → Python（自动化与测试脚本）

明确陈述你发现的内容：

检测到的技术栈：
- Go 1.22（来自 go.mod）
- RocksDB 9.x（来自 CMake 依赖）
- protobuf 27.x / gRPC 1.6x
→ 获取相关模式的官方文档。

如果版本缺失或不明确，询问用户。不要猜测——版本决定了哪些模式是正确的。

步骤 2：获取官方文档

获取你正在实现的功能的具体文档页面。不是首页，不是完整文档——是相关的页面。

来源层级（按权威顺序）：

优先级	来源	示例
1	官方文档	grpc.io/docs、rocksdb.org、pkg.go.dev、docs.rs
2	官方博客 / Changelog	go.dev/blog、github.com/facebook/rocksdb/releases
3	协议与标准参考	RFC（rfc-editor.org）、Raft 论文、Linux man-pages
4	内核/工具链兼容性	kernel.org 文档、Go/Rust 版本 release notes

不是权威来源——永远不要引用为主要来源：

• Stack Overflow 答案
• 博客文章或教程（即使是很流行的）
• AI 生成的文档或摘要
• 你自己的训练数据（这正是重点——验证它）

精确获取你要的内容：

坏：获取 gRPC 首页
好：获取 grpc.io/docs/languages/go/basics/

坏：搜索"rocksdb write stall 排查"
好：获取 github.com/facebook/rocksdb/wiki/Write-Stalls

获取后，提取关键模式并注意任何弃用警告或迁移指南。

当官方来源相互冲突时（例如迁移指南与 API 参考矛盾），向用户提出差异并验证哪种模式对检测到的版本实际有效。

步骤 3：遵循文档化模式实现

编写与文档展示相匹配的代码：

• 使用文档中的 API 签名，而非凭记忆的
• 如果文档展示了做某事的新方法，使用新方法
• 如果文档弃用了某个模式，不要使用已弃用的版本
• 如果文档没有覆盖某些内容，将其标记为未验证

当文档与现有项目代码冲突时：

检测到冲突：
现有代码库对 WAL 写入使用互斥锁逐条串行化，
但 RocksDB wiki 推荐通过 WriteBatch 做 group commit 批量落盘。
（来源：github.com/facebook/rocksdb/wiki/WriteBatch）

选项：
A) 使用文档推荐模式（WriteBatch 批量提交）——与当前文档一致
B) 匹配现有代码（互斥锁逐条写入）——与代码库一致
→ 你更喜欢哪种方案？

提出冲突。不要静默地选择一个。

步骤 4：引用你的来源

每个框架特定的模式都获得一个引用。用户必须能够验证每个决策。

在代码注释中：

// gRPC 服务端通过 keepalive 参数检测半开连接，替代自研心跳
// 来源：https://pkg.go.dev/google.golang.org/grpc/keepalive#ServerParameters
svr := grpc.NewServer(grpc.KeepaliveParams(keepalive.ServerParameters{
    Time:    10 * time.Second,
    Timeout: 3 * time.Second,
}))

在对话中：

我对副本同步长连接的保活使用了 gRPC 官方 keepalive 参数，
而非自研心跳协议。

来源：https://grpc.io/docs/guides/keepalive/
"gRPC sends HTTP/2 pings on the transport to detect if the
connection is down"

引用规则：

• 完整的 URL，不缩短
• 尽可能使用带锚点的深层链接（例如 /keepalive#ServerParameters 优于 /keepalive）——锚点在文档重组中比顶级页面更持久
• 当支持一个非显而易见的决策时，引用相关段落
• 推荐平台特性时包含内核版本/工具链版本支持数据（如 io_uring 需要 Linux 5.1+）
• 如果你找不到某个模式的文档，明确说明：

未验证：我找不到此模式的官方文档。这是基于训练数据，
可能已过时。在生产中使用前请验证。

关于你无法验证的内容的诚实比虚假的信心更有价值。

常见合理化借口

合理化借口	现实
"我对这个 API 有信心"	信心不是证据。训练数据包含看似正确但在当前版本下会出错的过时模式。验证。
"获取文档浪费 Token"	幻觉生成一个 API 浪费更多。用户调试一个小时，然后发现函数签名变了。一次获取可以防止数小时的返工。
"文档不会包含我需要的东西"	如果文档没有覆盖它，那是有价值的信息——该模式可能不是官方推荐的。
"我提一下它可能过时就行"	免责声明没有帮助。要么验证并引用，要么清楚地标记为未验证。模棱两可是最糟糕的选择。
"这是个简单的任务，不需要检查"	带有错误模式的简单任务会变成模板。用户在发现现代方法存在之前，将你已过时的锁模式复制到十几个模块中。

红旗警告

• 编写框架特定代码而没有检查该版本的文档
• 对 API 使用"我相信"或"我认为"而非引用来源
• 实现一个模式却不知道它适用于哪个版本
• 引用 Stack Overflow 或博客文章而非官方文档
• 使用已弃用的 API 因为它们出现在训练数据中
• 在实现之前没有阅读 go.mod / Cargo.toml 等依赖项文件
• 交付代码时没有为框架特定决策提供来源引用
• 当只有一页相关时获取整个文档站点

验证

使用源码驱动开发实现后：

• 框架和库版本已从依赖项文件中识别
• 已为框架特定模式获取了官方文档
• 所有来源都是官方文档，而非博客文章或训练数据
• 代码遵循当前版本文档中展示的模式
• 非平凡决策包含带有完整 URL 的来源引用
• 没有使用已弃用的 API（已对照迁移指南检查）
• 文档与现有代码之间的冲突已向用户提出
• 任何无法验证的内容已显式标记为未验证