企业官网建设流程全解析

导读

Planguage 是一种以关键字驱动的规划语言（planning language），其核心价值在于把模糊的表述转变成可验证、可测试、可追踪的陈述。architecture-decision-record 仓库将其收录为 11 套 ADR 模板之一（模板总览），并配套给出了完整的模板文档与仓库维护技能中的模板骨架。读完本文，你将掌握 Planguage 的 13 个核心关键字语义，学会把"非功能性需求/架构约束"写成带 Tag、Priority、Assumptions、Risks 等字段的可测试条目，并能在真实 ADR 中组合使用它们。

什么是 Planguage？

Planguage（Planning Language）是一种面向规划、需求与规格说明的受控语言。它不规定文章的散文结构，而是提供一套固定的关键字（keyword）词汇表，要求作者用这些关键字把一段需求或决策拆解为结构化的字段。每个字段承载一类确定的信息：标识、摘要、正文、理由、优先级、干系人、状态、负责人、版本等。这样做的直接收益是：

• 需求/决策陈述变得精确：每个信息点都有明确归属字段，不再依赖自然语言的行文风格；
• 陈述变得可测试：配合量化表达（如吞吐量、延迟、可用性目标），评审者可以判断"达标"与否；
• 记录变得可追溯：Tag 与 Revision 保证每条陈述有唯一身份和版本历史；
• 文档变得可治理：Owner、Author、Status、Priority 让责任、流程与资源占用一目了然。

本仓库中的模板文档将其定位为一种"更偏向质量保障（quality assurance oriented）"的 ADR 写法，与 Michael Nygard 的极简模板、MADR 的选项对比模板形成互补（见 ADR 模板清单 中 "ADR example templates" 一节对该模板的评价）。

Planguage 的 13 个核心关键字详解

以下内容完整继承自仓库模板文档，并结合仓库技能中的模板骨架补充取值说明与使用建议：

仓库技能中的模板骨架对这套词汇表做了精炼归纳，并注明其思想源头是 iaria.org 发布的教程《Specifying Effective Non-functional Requirements》——这也解释了为什么 Planguage 特别适合描述非功能性需求（性能、可用性、安全、可维护性等）：这类需求若不用结构化字段与量化目标表达，极易在评审时被"凭感觉"接受。

为什么在 ADR 中用 Planguage：让决策可测试、可追溯

架构决策记录（ADR）的本职是"记录一次重要架构决策及其上下文与后果"。大多数经典模板（Nygard、MADR 等）擅长讲清 Context / Decision / Consequences 的叙事，但对质量属性目标与约束条件的刻画往往偏软。Planguage 恰好补齐这一环：

• 把"目标"写成可验证陈述：普通写法是"系统应具备高可用性"；Planguage 写法则要求给出Requirement的量化目标与Priority，评审时即可判定是否达标；
• 把"为什么"沉淀为 Rationale：避免后人只看到"选了什么"而看不到"为何这样选"，这与仓库 ADR 编写建议 强调的 Rationale、Specific、Timestamps、Immutable 原则同源；
• 把"前提与风险"显式化：Assumptions与Risks字段迫使作者列出当前环境中的隐含前提与潜在负面因素，使决策的适用边界一目了然。

从仓库源码结构看，Planguage 模板与其它 10 套模板并列存放于 templates 目录，属于"更偏向质量保障"的一档（见 locales/en-us/index.md 中 "ADR example templates" 一节的定位描述），适用于对非功能性要求敏感的系统（如高并发平台、金融与医疗场景、合规敏感项目）。

实战：把 Planguage 关键字组合进一份 ADR

Planguage 不是对 ADR 叙事的替代，而是一种字段化增强。推荐的结构是：保留 ADR 的标题与结论性描述，再用 Planguage 字段承载关键的非功能性约束。下面给出一个可复制、可运行的示例骨架（基于仓库模板文档的关键字集合组织）：

# 为订单服务引入 Redis 缓存以降低数据库读负载 Tag: ADR-CACHE-ORDER-001 Gist: 引入 Redis 作为订单查询的读缓存，将热点读请求从主库剥离。 Requirement: 缓存命中率 >= 95%（生产流量压测验证）；读接口 P95 延迟 <= 80ms。 Rationale: 订单列表与详情存在明显热点读模式，主库读负载接近容量上限； 引入缓存可在不扩库的情况下满足增长预期，成本可控。 Priority: Must（本迭代必须落地）；预计投入 2 人/周。 Stakeholders: 订单后端团队、SRE、数据平台组。 Status: draft Owner: <订单后端负责人> Author: <本 ADR 撰写人> Revision: 1 Date: 2026-10-12 Assumptions: ① 订单数据变更可容忍秒级延迟；② 缓存失效风暴不会出现 （已设计随机过期时间）；③ 现有监控体系可观测缓存命中率。 Risks: ① 缓存与库数据不一致引发读旧数据投诉；② Redis 故障时 需快速降级回源，否则可能放大主库压力。 Defined: 见团队术语表 glossary.md 中 "缓存命中率" 条目。

要点说明：

• Tag采用ADR-<主题>-<序号>形式，保证跨文档引用稳定，也便于与仓库推荐的文件命名规范（小写、连字符、祈使式动词短语）配合使用；
• Requirement给出量化目标（命中率、延迟），使Status从draft推进到committed时具备可验证的验收口径；
• Assumptions与Risks显式记录前提与降级方案，当假设被证伪（如延迟容忍度变化）时，评审者可依据Revision与Date回溯修订历史；
• 若后续决策替代本 ADR，可按仓库建议新建 ADR 并以superseded标注状态，而不是直接修改原记录（对应编写好 ADR 的建议中的 Immutable 原则）。

仓库证据：模板文档与维护技能中的落点

本仓库为 Planguage 模板提供了两处可直接查阅的实现证据：

1. 模板文档：locales/en-us/templates/decision-record-template-using-planguage/index.md（英文原版，同目录下另有 README.md）；中文版位于 locales/zh-001/模板/使用planguage的决策记录模板/index.md，可用于对照术语翻译。
2. 维护技能中的模板骨架：skills/architecture-decision-record-skill/reference/templates.md 的 "Planguage (formal, testable non-functional requirements)" 一节，以代码块形式给出了精简的字段列表（含draft | reviewed | committed等状态取值），并注明"这不是一个完整的 ADR 结构，而是一套让需求/决策精确且可测试的关键字词汇表"——这是理解 Planguage 定位的关键注释。

此外，仓库的多语言站点内容也镜像了该模板，说明它已进入站点的内容发布管线。若你希望让 AI 编码助手按本仓库规范自动书写此类 ADR，可将仓库自带的 architecture-decision-record-skill 复制到项目的.claude/skills/目录中使用。

最佳实践小结

1. 把 Planguage 当"字段清单"而非"写作框架"：先按任意 ADR 模板组织叙事，再用 Planguage 关键字提炼非功能性约束与治理字段；
2. 量化优先：Requirement尽量给出可测量目标，否则Status: committed缺乏验收依据；
3. Tag 一经分配不再变更：修订走Revision/Date递增，替代走新 ADR +superseded状态；
4. Assumptions 与 Risks 要显式：它们是决策适用边界的"护栏"，也是触发复审的信号源；
5. Defined 尽量指向术语表：避免在单条目内重复定义，保持术语全局一致；
6. 与仓库其它文档协同：可结合文件命名规范、好 ADR 编写建议以及把决策当作代码的适配度函数（用自动化检查持续验证决策是否被遵守）共同落地。

Planguage 的价值不在"换一种格式"，而在迫使作者把话说清楚。当团队把每一条架构决策的非功能性约束都用 Tag、Requirement、Assumptions、Risks 表达出来时，ADR 就从"归档文档"变成了可评审、可测试、可治理的工程资产。