技术提案、架构设计、实现设计:三类设计文档如何区分

AI生成文档已经很容易了，但是AI生成的到底是哪一类文档，最好还是能界定下，否则很容易混用。

很多团队会把 PEP、RFC、架构图、API 文档、协议说明、状态机、表结构都笼统地叫成“设计文档”。这会带来一个实际问题：大家在不同阶段讨论不同粒度的事情，却以为自己在讨论同一件事。

更清晰的分法是把它们拆成三个术语：

• 技术提案：这个变化该不该做？

• 架构设计：系统整体怎么组织？

• 实现设计：模块具体怎么落地？

三类设计文档在开发中的位置

这三个术语不是“写得粗还是写得细”的区别，而是决策层级不同。技术提案决定方向，架构设计决定结构，实现设计决定落地。

三类设计文档的决策层级差异（不是“详略”差异）

一、三个术语的定义

1. 技术提案

首先，技术提案是面向团队、社区或标准组织的决策型文档，用来论证一个重要技术变化是否应该被接受。

它回答的问题是：

• 为什么要做？

• 解决什么问题？

• 影响范围多大？

• 是否破坏兼容？

• 有哪些替代方案？

• 为什么选择这个方案？

• 谁需要达成共识？

典型产物包括：

• PEP

• RFC

• IETF Internet-Draft

• Kubernetes KEP

• Go proposal

• Rust RFC

• GitHub proposal issue

经典例子：

• Python PEP 831: Frame Pointers Everywhere

• https://peps.python.org/pep-0831/

• Rust RFC Book

• https://rust-lang.github.io/rfcs/

• IETF Internet-Draft: IPv8

• https://www.ietf.org/archive/id/draft-thain-ipv8-00.html

• Go Proposal Process

• https://github.com/golang/proposal

• Kubernetes Enhancements / KEPs

• https://github.com/kubernetes/enhancements

技术提案不是单纯的“怎么写代码”。它的核心是**论证与共识**。一份技术提案可以包含架构设计和实现设计片段，但它最重要的任务是回答：

> 这个变化是否值得进入项目、语言、协议或生态？

例如 Rust RFC 流程明确要求重大语言、库、编译器变化通过 RFC 达成共识。Go proposal 流程也把“brief issue → 讨论 → 必要时 design doc → 接受/拒绝 → 实现”作为重要变化的路径。

2. 架构设计

其次，架构设计是系统级设计文档，用来描述系统由哪些核心部分组成，以及这些部分如何协作、部署、扩展和演进。

它回答的问题是：

• 系统分成哪些组件？

• 组件之间如何通信？

• 控制流和数据流是什么？

• 哪些组件承担核心职责？

• 部署拓扑是什么？

• 如何满足可用性、扩展性、安全性和可维护性？

典型产物包括：

• 系统架构图

• 组件图

• 部署图

• 数据流图

• 控制平面 / 数据平面说明

• 高层模块边界说明

经典例子：

• Kubernetes Cluster Architecture

• https://kubernetes.io/docs/concepts/architecture/

• GitLab Architecture Overview

• https://docs.gitlab.com/development/architecture/

• PostgreSQL Architectural Fundamentals 

• https://www.postgresql.org/docs/current/tutorial-arch.html

• PostgreSQL Internals Overview

• https://www.postgresql.org/docs/current/overview.html

最新/热门项目例子：

• OpenClaw Gateway Architecture

• https://docs.openclaw.ai/architecture

• OpenClaw Architecture Overview

• https://clawdocs.org/architecture/overview/

• opencode Architecture Overview

• https://deepwiki.com/sst/opencode/1.2-architecture-overview

架构设计的重点是边界、职责和连接关系。它不应该试图替代每个模块的实现设计。好的架构设计让读者能快速建立系统地图：哪里是入口，哪里是状态存储，哪里做调度，哪里负责执行，哪里承担扩展点。

3. 实现设计

最后，实现设计是模块级或功能级设计文档，用来描述某个具体能力如何被编码实现、验证和交付。

这里我建议用“实现设计”，而不是传统说法“详细设计”。“详细设计”容易被误解成“写得很细”，但“实现设计”更准确：它面向编码落地。

它回答的问题是：

• API 怎么定义？

• 字段含义是什么？

• 状态如何流转？

• 协议消息格式是什么？

• 数据库表怎么设计？

• 并发、幂等、错误、重试怎么处理？

• 测试点在哪里？

典型产物包括：

• API reference

• protocol spec

• schema definition

• state machine

• class/function design

• sequence diagram

• database schema

• implementation notes

经典例子：

• Kubernetes API Conventions

• https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md

• Kubernetes API Reference

• https://kubernetes.io/docs/reference/

• PostgreSQL Frontend/Backend Protocol: Message Formats

• https://www.postgresql.org/docs/current/protocol-message-formats.html

• GitLab Merge Requests API

• https://docs.gitlab.com/api/merge_requests/

最新/热门项目例子：

• OpenClaw Agent Loop

• https://docs.openclaw.ai/agent-loop

• OpenClaw Gateway Protocol

• https://docs.openclaw.ai/gateway/protocol

• OpenClaw Brain & Hands

• https://clawdocs.org/architecture/brain-and-hands/

• opencode Session Management

• https://deepwiki.com/sst/opencode/8-session-management

• opencode Tool System

• https://deepwiki.com/sst/opencode/27-tool-system

• opencode Provider Architecture

• https://deepwiki.com/sst/opencode/22-provider-architecture

实现设计不是把代码提前翻译成文字。它的价值是把接口、状态、异常、协议、数据结构和测试约束说清楚，让开发、测试和调用方对“怎么落地”有共同理解。

二、三者的核心差异

总结：

• 技术提案决定方向。

• 架构设计决定结构。

• 实现设计决定落地。

三、开发流程中的顺序

重大变化通常是：

技术提案 → 架构设计 → 实现设计 → 编码实现 → 测试验证 → 发布反馈

普通功能通常是：

架构设计 → 实现设计 → 编码实现

小功能或 bugfix 可能是：

实现设计 → 编码实现

这不是严格瀑布流程，而是逐步收敛。技术提案负责把“不确定的方向”变成“被接受的方向”；架构设计负责把“方向”变成“系统结构”；实现设计负责把“系统结构”变成“可编码任务”。

开发过程中也会反向修正：

• 实现太复杂 → 回头调整实现设计

• 模块边界不合理 → 回头调整架构设计

• 架构假设不成立 → 回头修改或否决技术提案

四、经典案例：Kubernetes

Kubernetes 是最适合说明这三类文档的开源项目之一。

技术提案：

• Kubernetes Enhancements / KEPs

• https://github.com/kubernetes/enhancements

架构设计：

• Kubernetes Cluster Architecture

• https://kubernetes.io/docs/concepts/architecture/

实现设计：

• Kubernetes API Conventions

• https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md

• Kubernetes API Reference

• https://kubernetes.io/docs/reference/

Kubernetes 的架构设计讲的是 control plane、worker node、`kube-apiserver`、`etcd`、`kube-scheduler`、`kube-controller-manager`、`kubelet`、`kube-proxy` 和 Pods 之间的关系。它帮助读者理解 Kubernetes 集群由哪些大块组成。

Kubernetes 的实现设计则进入 API 对象层面。例如 API Conventions 讨论 `kind`、`apiVersion`、`metadata`、`spec`、`status`、REST verbs、defaulting、concurrency control 等具体规则。它不再只是讲“组件如何协作”，而是规定“对象如何表达、如何更新、如何保持一致”。

这组对比很典型：

• 架构设计：

• Kubernetes 集群有哪些组件，它们如何协作？

• 实现设计：

• 一个 Kubernetes API 对象有哪些字段，这些字段有什么语义？

五、经典案例：PostgreSQL

PostgreSQL 适合说明架构设计和实现设计在粒度上的差异。

架构设计：

• PostgreSQL Architectural Fundamentals

• https://www.postgresql.org/docs/current/tutorial-arch.html

• PostgreSQL Internals Overview

• https://www.postgresql.org/docs/current/overview.html

实现设计：

• PostgreSQL Frontend/Backend Protocol: Message Formats

• https://www.postgresql.org/docs/current/protocol-message-formats.html

PostgreSQL 的架构文档讲 client/server 模型、多进程模型、server process、client frontend、backend process，以及查询如何经过 parser、rule system、planner/optimizer、executor。

而协议消息格式文档直接到字节级别：`AuthenticationOk`、`StartupMessage`、`Query`、`DataRow` 等消息由 `Byte1`、`Int32`、`String`、长度字段等组成。

这组对比可以这样理解：

• 架构设计：

• PostgreSQL 客户端和服务端如何协作，查询如何被处理。

• 实现设计：

• 客户端和服务端之间每一个协议消息的字节格式是什么。

如果你想看更直观的 PostgreSQL 内部进程架构图，可以参考 Hironobu Suzuki 的非官方但很经典的资料：

• The Internals of PostgreSQL: Process Architecture

• https://www.interdb.jp/pg/pgsql02/01.html

六、经典案例：GitLab

GitLab 适合产品工程团队理解“系统组件图”和“业务 API 文档”的区别。

架构设计：

• GitLab Architecture Overview

• https://docs.gitlab.com/development/architecture/

实现设计：

• GitLab Merge Requests API

• https://docs.gitlab.com/api/merge_requests/

GitLab 的架构文档讲 NGINX、GitLab Workhorse、Puma、Sidekiq、Redis、PostgreSQL、Gitaly、GitLab Shell、GitLab Pages、Registry 等组件之间如何连接。

Merge Requests API 文档则进入具体业务接口：路径、请求参数、响应字段、错误码、分页、字段废弃和版本演进。

这组对比是：

• 架构设计：

• GitLab 这个产品由哪些服务组成，服务之间怎么通信。

• 实现设计：

• Merge Request 这个业务能力有哪些 API，参数和返回字段是什么。

七、最新热门项目：opencode

opencode 是一个开源 coding agent 项目。它的官方文档更偏使用、配置和扩展，架构图不算多；但 DeepWiki 对源码做了索引，能快速看到系统架构和内部模块结构。使用 DeepWiki 时要注意：它不是项目官方设计文档，而是源码索引生成的分析材料，适合辅助理解，需要和官方文档、源码互相验证。

架构设计：

• opencode Architecture Overview

• https://deepwiki.com/sst/opencode/1.2-architecture-overview

• OpenCode Official Docs

• https://opencode.ai/docs/

实现设计：

• opencode Session Management

• https://deepwiki.com/sst/opencode/8-session-management

• opencode Tool System

• https://deepwiki.com/sst/opencode/27-tool-system

• opencode Provider Architecture

• https://deepwiki.com/sst/opencode/22-provider-architecture

• opencode Permission and Question System

• https://deepwiki.com/sst/opencode/12-permission-and-question-system

a）opencode 的系统架构可以概括为：

这属于架构设计，因为它说明的是主要组件、通信路径和系统分层。

b）opencode 的实现设计则关注更具体的问题：

• 一次用户 prompt 如何进入 session？

• agent loop 如何推进？

• tool call 如何被权限系统拦截或批准？

• provider/model 如何解析？

• 事件如何同步给 UI？

• 消息如何持久化？

这些问题已经进入编码落地层面。

八、最新热门项目：OpenClaw

OpenClaw 是一个 self-hosted agent / personal assistant 项目。它很适合说明现代 agent 项目中的“系统架构”和“内核/实现流程”的区别。

架构设计：

• OpenClaw Gateway Architecture

• https://docs.openclaw.ai/architecture

• OpenClaw Community Architecture Overview

• https://clawdocs.org/architecture/overview/

实现设计：

• OpenClaw Agent Loop

• https://docs.openclaw.ai/agent-loop

• OpenClaw Gateway Protocol

• https://docs.openclaw.ai/gateway/protocol

• OpenClaw Brain & Hands

• https://clawdocs.org/architecture/brain-and-hands/

OpenClaw 的系统架构以 Gateway 为中心。Gateway 是长期运行的进程，连接聊天渠道、CLI、Web UI、移动节点、插件和 agent runtime。

这张图表达的是架构设计层面的问题：

• 哪些外部入口会进入系统？

• Gateway 承担什么职责？

• LLM、工具、记忆、心跳和插件分别放在哪里？

• 系统如何被组织成一个可运行整体？

OpenClaw 的实现设计则可以看 Agent Loop 和 Gateway Protocol。

Agent Loop 讲的是一次 agent run 如何被执行：输入进入、上下文组装、模型推理、工具执行、流式回复、状态持久化。Gateway Protocol 则讲 WebSocket 传输、`connect` 握手、request/response/event framing、roles、scopes、auth、pairing、versioning 等协议细节。

这张图表达的是实现设计层面的问题：

• 一次输入如何变成模型调用？

• 模型如何触发工具？

• 工具结果如何被持久化？

• 回复如何流式返回？

所以同一个项目里可以同时存在两类图：

• 系统架构图：

• 看 Gateway、渠道、节点、Brain、Hands、Memory 如何组成系统。

• 实现流程图：

• 看 Agent Loop 内部如何把一条消息变成动作和回复。

九、如何判断一份文档属于哪一类

可以用关键词判断。

如果文档主要出现这些内容：

motivation, proposal, alternatives, drawbacks, compatibility, consensus

它多半是：技术提案

如果文档主要出现这些内容：

architecture, component, control plane, data flow, deployment, service, node

它多半是：架构设计

如果文档主要出现这些内容：

API, schema, field, message format, state, protocol, endpoint, error code

它多半是：实现设计

更简单的判断公式是：

• 问“该不该做” → 技术提案

• 问“整体怎么组织” → 架构设计

• 问“具体怎么实现” → 实现设计

十、它们在团队开发中的实际作用

技术提案的作用：

• 避免未经论证的大改动

• 记录背景、权衡和反对意见

• 帮助团队或社区达成共识

• 给后续架构设计设定目标和约束

架构设计的作用：

• 统一系统理解

• 明确模块边界

• 降低跨团队协作成本

• 提前暴露扩展性、安全性、部署和性能风险

实现设计的作用：

• 把架构拆成可开发任务

• 降低接口歧义

• 指导开发和测试

• 减少返工

• 让代码评审有依据

一个很实用的判断是：

• 如果团队在技术提案阶段争论字段名，说明讨论过细。

• 如果团队在实现设计阶段还在争论是否要做这个方向，说明前置决策缺失。

• 如果团队编码时才发现模块边界不清，说明架构设计不足。

十一、常见误区

误区一：技术提案就是架构设计。

纠正：技术提案可以包含架构设计，但它的核心是论证和共识。

误区二：架构设计越详细越好。

纠正：架构设计应该明确边界和关键决策，不应该替代实现设计。

误区三：实现设计就是把代码提前写成文档。

纠正：实现设计不是代码翻译，而是把接口、状态、异常、协议和测试点说清楚。

误区四：所有功能都需要三份文档。

纠正：小变更可以只做实现设计，甚至直接编码；重大变更才需要技术提案。

十二、总结

三者的区别可以压缩成三句话：

• 技术提案解决“为什么做、该不该做”。

• 架构设计解决“系统由什么组成、如何协作”。

• 实现设计解决“具体接口、流程、状态和协议如何落地”。

它们不是文档模板的区别，而是决策层级的区别。

一个成熟项目通常会同时需要这三类文档：

• 技术提案保证方向可被接受。

• 架构设计保证系统结构可演进。

• 实现设计保证代码实现可交付。

读开源项目文档时，如果能分清这三类，你就不容易被“设计文档”这个大词混淆。你能知道当前文档是在讨论方向、结构，还是落地；也能判断一个团队到底缺的是共识、架构，还是实现细节。

–end–