企业官网建设流程全解析

本文以 architecture-decision-record 仓库中《Konventioner for filnavne》（丹麦语版"ADR 文件命名约定"）文档为核心骨架，结合仓库内的 skill 定义、模板与示例，系统讲解 ADR（Architecture Decision Record，架构决策记录）文件的命名规范、背后的设计动机、实际落地步骤与常见变体。读完本文，你将掌握一套可直接照抄的 ADR 文件命名规则，能解释"为什么文件名要用命令式动词短语 + 小写 + 连字符 + .md 扩展名"，并能在自己的 git 仓库中从零搭建一套规范、可检索、可维护的 ADR 目录。

一、为什么 ADR 需要一套文件命名规范

ADR 通常以纯文本文件（Markdown）的形式存放在代码仓库中，例如choose-database.md。当团队的 ADR 数量从几条增长到几十条、上百条时，文件名就成了这套"架构知识库"的第一层索引：它决定了文件在目录列表中的排序、在 git 历史中的可读性、在搜索引擎与代码检索工具中的可发现性，以及跨系统复制、迁移时的兼容性。

仓库丹麦语文档 Konventioner for filnavne 明确指出：如果你选择把 ADR 写成普通文本文件，那么"值得为你自己确立一套 ADR 文件名约定"（kan det være nyttigt at fastlægge din egen konvention for ADR-filnavne）。这与仓库英文原版 File name conventions for ADRs 的表述完全一致——它不是强制标准，而是一套经过实践检验、推荐优先采纳的约定。

仓库在主索引 locales/da-001/index.md 的"Indhold"（内容）中也将"Konventioner for filnavne"列为独立章节，说明命名约定是 ADR 实践体系中与模板、写作建议并列的一等公民。

二、推荐的文件名格式：先看四个示例

仓库文档给出的推荐约定有一个"特定格式"（et bestemt format），并附了四个示例：

choose-database.md （选择数据库） format-timestamps.md （格式化时间戳） manage-passwords.md （管理密码） handle-exceptions.md （处理异常）

这四个示例不是随机挑选的。逐一对照仓库中的实际资源：

• choose-database.md对应英文示例 choosing-a-database-technology（该示例是一份完整的 Nygard 风格 ADR：Status / Context / Decision / Rationale / Consequences）；
• format-timestamps.md对应英文示例 timestamp-format，丹麦语版本见 tidsstempelformat，内容为选择 ISO 8601 纳秒精度时间戳格式YYYY-MM-DDTHH:MM:SS.NNNNNNNNNZ的完整决策记录；
• manage-passwords.md对应仓库中的 Secrets storage（密码/机密存储）主题；
• handle-exceptions.md则展示了"处理异常"这类跨语言、跨框架的通用架构决策该如何命名。

观察这些示例可以发现一个共同特征：文件名本身就是对这份 ADR 决策主题的完整、独立、自解释的概括。任何人只看到文件名，就能大致判断这份记录讨论什么。

三、三条核心规则详解

仓库文档将命名约定归纳为三条规则，下面逐条展开，并结合仓库源码层面的证据说明其动机。

规则 1：使用现在时的命令式动词短语（imperative verb phrase）

原文（丹麦语）：Navnet er en bydemåde i nutid.—— 名称是现在时的命令式（祈使）形式。

即文件名应以动词开头、以"去做某事"的语气描述决策主题，例如choose-database.md而非database.md或chosen-database.md。

文档给出的动机有两层：

1. 提升可读性（forbedrer læsbarheden）：命令式短语天然构成一个完整语义单元，"选择数据库"比孤立的"数据库"更能传达决策意图；
2. 与提交信息（commit message）格式保持一致（passer til vores format for commit-beskeder）：git 社区广泛采用的提交信息约定（如 Conventional Commits 之前的经典 50/72 规范）同样推荐使用命令式现在时，例如Add tests、Fix memory leak、Choose database。当 ADR 文件名与提交信息风格一致时，git log 与目录列表并排阅读时体验非常统一。

仓库 skill 文件 skills/architecture-decision-record-skill/SKILL.md 第 3 节"Name the file"对此给出了完全一致的表述，并补充说明这一约定在 ADR 生态中是通用的（Convention used across this ecosystem）：

• A present-tense imperative verb phrase, e.g.choose-database.md,format-timestamps.md,manage-passwords.md,handle-exceptions.md.
• Lowercase with dashes.
• .mdextension.

规则 2：全部小写并使用连字符（kebab-case）

原文（丹麦语）：Navnet bruger små bogstaver og bindestreger (ligesom i dette repository).—— 名称使用小写字母和连字符（与本仓库一致）。

文档给出的动机是：这是在可读性与跨系统可用性之间取得的平衡（en balance mellem læsbarhed og brugbarhed på tværs af systemer）。

为什么是"平衡"？因为：

• 可读性：连字符分隔单词比完全粘连（choosedatabase.md）更易读；比下划线（choose_database.md）在 URL 中更友好（下划线在部分 markdown 渲染器与 URL 规则中可能被特殊处理）；
• 跨系统可用性：小写避免了大小写敏感文件系统（Linux、部分容器文件系统）与大小写不敏感系统（macOS 默认、Windows）之间因Choose-Database.md与choose-database.md混用而产生的冲突；连字符避免了下划线在 shell 通配符、编程语言标识符转换等场景中的边缘问题。

仓库自身就是这条规则的活证据：locales/下所有示例、模板、文档目录名（如choosing-a-database-technology、decision-record-template-by-michael-nygard）均采用小写 + 连字符风格。

规则 3：扩展名使用 markdown（.md）

原文（丹麦语）：Filendelsen er markdown. Det kan være praktisk til enkel formatering.—— 扩展名是 markdown，便于简单排版。

选择.md的实践价值：

• 无需专用工具，任意文本编辑器即可编辑；
• git 与绝大多数代码托管平台原生渲染，在 Web 界面直接呈现标题、列表、代码块等结构；
• 便于与代码一同走评审、版本化、diff 流程；
• 为后续工具链（搜索索引、LLM 检索、站点生成）提供标准化输入格式。

仓库配套的 Claude Code skill 在 SKILL.md 中同样规定.md扩展名，说明这是贯穿"文档 + 自动化工具"两层的一致约定。

四、结合仓库实现：从命名到落地的完整工作流

命名约定不是孤立的，它必须放进"建目录 → 命名 → 选模板 → 写作 → 提交 → 迭代"的完整流程才有意义。仓库的丹麦语主索引 locales/da-001/index.md 中"如何使用 git 开始使用 ADR"一节给出了基础流程，skill 文件则给出了更完整的步骤。

第 1 步：检查或创建 ADR 目录

如果项目已有 ADR 目录，先遵循已有约定（skill 建议用git ls-files快速探测）：

git ls-files | grep -iE '(^|/)(adr|adrs|decisions?)(/|$)'

如果不存在，按仓库推荐创建顶层目录。命名上要注意一个经验事实：文档 locales/da-001/index.md 与英文版都提到，很多团队更偏爱decisions/而不是adr/——因为"architecture"一词与"ADR"缩写会让部分开发者望而却步，而decisions这个词能容纳更广的内容（供应商决策、计划决策、排期决策等），且"decision record"去掉"record（记录）"一词后，人们更愿意把工作进展写进去。

mkdir adr # 或 mkdir decisions

第 2 步：按约定命名文件

对每个 ADR 创建一条文本文件。基础命名（本仓库文档推荐）：

vi adr/choose-database.md

如果项目采用编号制（许多工具如 adr-tools 的惯例），则在命令式短语前加零填充序号。skill 文件明确给出了这一变体：

0007-choose-database.md

编号的作用：保证文件在目录列表中按决策时间顺序稳定排序，且每条 ADR 拥有全局唯一 ID，便于在状态字段、后续 ADR 中被引用（如Superseded by 0009-...）。

第 3 步：套用模板撰写内容

命名确定后，按模板填充内容。仓库推荐的默认模板是 Michael Nygard 的经典四段式，见 decision-record-template-by-michael-nygard：

# Title ## Status What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? ## Context What is the issue that we're seeing that is motivating this decision or change? ## Decision What is the change that we're proposing and/or doing? ## Consequences What becomes easier or more difficult to do because of this change?

以仓库中的完整示例 choosing-a-database-technology 为参照：其 Status 为Accepted，Context 阐述了三类数据库（关系型、文档型、事件型）的权衡，Decision 明确选择文档数据库，Consequences 说明后续需要投入的学习成本与数据模型适配工作。这样一份文档存入adr/choose-database.md后，文件名与内容首尾呼应。

第 4 步：提交到 git

将 ADR 文件纳入版本控制：

git add adr/choose-database.md git commit -m "Add ADR: choose database"

注意提交信息同样使用命令式现在时——这正是规则 1 中"文件名与提交信息格式一致"的落地点。

五、命名约定之外的配套纪律

命名只是起点。仓库写作指南 writing-guide.md 与主索引中"写好 ADR 的建议"章节补充了几条与命名强相关的纪律：

1. 一条 ADR 只承载一个决策（Specific）：如果一次决策包含多个架构要点，应拆成多个文件，分别按各自主题命名；
2. 为易变信息打时间戳（Timestamped）：成本、排期、扩展规模等会随时间变化的内容要注明记录时间；
3. 默认不可变（Immutable）：已接受的 ADR 不直接改写原文，而是通过追加带日期的补充信息，或新建一条 ADR 来取代旧记录。取代时，旧文件状态改为Superseded by <link>，新文件注明Supersedes <link>——而正确的文件命名（如编号制）能让这种"取代链"在目录列表中就一眼可辨。

六、命名约定常见变体与选择建议

仓库文档推荐的是"无编号 + 命令式短语"的轻量方案，但 skill 文件明确说明：编号与否、目录用adr/还是decisions/，都应"跟随项目已有约定"。常见变体总结如下：

无论选哪种，三条核心规则（命令式现在时、小写 + 连字符、.md扩展名）都建议保留——它们是仓库文档、英文原版与 skill 文件三方共同确认的通用约定。

七、小结

• ADR 文件命名约定是一套"小规则、大价值"的实践：它同时服务人工阅读、git 历史、跨系统兼容与自动化工具链；
• architecture-decision-record 仓库推荐的三条规则：现在时命令式动词短语 + 小写连字符（kebab-case）+.md扩展名；
• 命名应与完整工作流（建adr/或decisions/目录、套用 Nygard 模板、命令式提交信息、编号或不可变纪律）配套使用；
• 想深入实践的读者，可直接查阅仓库中的 丹麦语原文档、英文原版、skill 定义 以及 示例目录，将这套约定直接复制到自己的项目中使用。