企业官网建设流程全解析

Notion 决策日志数据库（ADR）实战指南：awesome-codex-skills 的知识捕获体系详解

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

本文以 awesome-codex-skills 仓库中 decision-log-database.md 为核心，系统讲解如何在 Notion 中构建用于追踪架构决策记录（ADR）的决策日志数据库——从属性 Schema 设计、JSON 创建方式、六段式决策页模板，到基于 Notion MCP 的完整捕获工作流与视图/最佳实践。读完本文，你将掌握一套"从对话中提炼决策 → 结构化落库 → 可检索可追溯"的完整方案，可直接复用到团队 Wiki 建设中。

一、为什么需要决策日志数据库

软件团队的架构与技术决策散落在会议纪要、聊天记录和各类文档中，事后往往难以回答三个问题：当时为什么这样选？考虑了哪些替代方案？这个决定现在还有效吗？决策日志数据库（Decision Log Database）正是为解决这个问题而设计——它借鉴 ADR（Architecture Decision Records，架构决策记录）的思想，把"决策"本身作为一等公民持久化，并附上背景与理由。

在 awesome-codex-skills 的 知识捕获技能（SKILL.md） 中，决策日志是与团队 Wiki、How-To 指南、FAQ、学习笔记、技术文档并列的六大内容类型之一。该数据库的定位与选型在 database-best-practices.md 中有明确说明："Track decisions" 场景即使用 Decision Log 数据库。它服务于一个核心目的：

Purpose: Track important decisions with context and rationale. （记录重要决策，并保存其背景与决策理由。）

二、数据库 Schema 设计详解

决策日志数据库的核心是一张属性表。每个属性对应 Notion Database 中的一个 Property，类型与选项直接决定记录的规范程度。完整 Schema 如下：

2.1 字段设计要点

• Decision（title 类型）：Notion 数据库的主标题属性。建议用一句话动词短语概括决策，如 "Use PostgreSQL for Primary Database"，便于在列表视图与搜索中快速识别。
• Status（select）：生命周期状态机，四个取值覆盖决策全生命周期：Proposed（提议中）→Accepted（已接受）→Superseded（已被取代）→Deprecated（已废弃）。这是决策"保鲜"的关键字段。
• Domain（select）：领域分类维度，Architecture（架构）、Product（产品）、Business（业务）、Design（设计）、Operations（运维）五个选项，用于跨团队筛选与统计。
• Impact（select）：影响级别High / Medium / Low，用于优先级排序与高层汇报。
• Deciders / Stakeholders（people）：均为人员类型，前者记录"谁做的决定"，后者记录"谁受影响"，便于后续追溯与通知。
• Related Decisions（relation）：关系属性，链接到其他决策记录，显式表达决策之间的依赖与上下文。

2.2 在源码中的印证

这份 Schema 并非孤立设计，而是与技能的工作流与评估用例严格对齐：

• SKILL.md 第 2 步要求"确认必需属性（title, tags, owner, status, date, relations）"，与上述字段一一对应；
• 评估用例 decision-record.json 的success_criteria明确要求"属性设置正确（Decision, Date, Status: Accepted, Domain: Architecture, Impact）"，说明这些字段是验证模型行为是否达标的硬性标准。

三、创建决策记录：JSON 用法示例

原文档给出了向数据库写入一条决策记录的 JSON 示例，这是调用 Notion MCPnotion-create-pages时的属性负载：

{ "Decision": "Use PostgreSQL for Primary Database", "Date": "2025-10-15", "Status": "Accepted", "Domain": "Architecture", "Impact": "High", "Deciders": [tech_lead, architect], "Stakeholders": [eng_team] }

3.1 字段填写规范

• Decision：直接作为页面标题；
• Date：ISO 格式日期字符串YYYY-MM-DD，记录决策作出当日而非文档创建日；
• Status：新纪录通常为Accepted或Proposed，随决策推进流转；
• Deciders / Stakeholders：填入 Notion 成员（person），需使用成员标识而非显示名。

3.2 更完整的 MCP 调用形态

在 decision-capture.md 中，可以看到一条带完整上下文的实际调用，包含date:Date:start与date:Date:is_datetime这类日期属性的精确写法：

{ "parent": { "data_source_id": "decision-log-collection-id" }, "pages": [{ "properties": { "Decision": "Migrate to GraphQL API", "date:Date:start": "2025-10-16", "date:Date:is_datetime": 0, "Status": "Accepted", "Domain": "Architecture", "Impact": "High" }, "content": "[Full decision record with context, rationale, alternatives...]" }] }

两点实操细节值得注意：

1. parent使用data_source_id指向决策日志数据库本身（而不是某个父页面），记录才会以数据库条目的形式落库；
2. 日期属性需按 Notion API 的复合写法传递：date:Date:start指定起始日期，is_datetime: 0表示仅记录日期、不包含时间。

如果目标数据库尚未创建，可参考 database-best-practices.md 中的Notion:notion-create-database示例，先以 JSON 定义select选项（如 Type、Status 的颜色与取值），再用Notion:notion-fetch拉取已建库的确切属性名与类型后再写入。

四、决策页内容模板：六段式结构

数据库属性回答了"什么时间、谁、在哪类领域、影响多大"，而决策页正文则承载完整推理过程。原文档要求每条决策记录至少包含六个部分：

• Context：为什么需要这个决策（背景与动机）
• Decision：最终决定了什么
• Rationale：为什么选择这个方案
• Options Considered：考虑过的替代方案及其权衡
• Consequences：预期结果（正面与负面）
• Implementation：决策将如何落地执行

4.1 完整示例：REST 迁移 GraphQL

decision-capture.md 以"客户 API 从 REST 迁移到 GraphQL"为例，给出了可直接套用的完整正文模板，各节要点如下：

Context（背景）：REST API 已膨胀到 50+ 端点且模式不一致，前端与移动端频繁请求新端点，导致 API 臃肿、维护负担重、过度/欠度取数、迭代缓慢、错误处理不一致。

Decision（决策）：客户向 API 迁移到 GraphQL，内部服务仍保留 REST。

Rationale（理由）：客户端按需取数、单端点自文档化 Schema、类型安全可代码生成、更好的开发者体验，且已是客户端 API 的行业标准。

Options Considered（备选方案）：用"方案 + 优点/缺点 + 结论"三件套逐一对比——

Consequences（后果）：正面（前端/移动端开发提速、维护负担下降、类型安全与工具链改善、单端点简化部署）；负面（3–4 个月迁移周期、团队需培训、需解决缓存策略、监控调试模式不同）。

Implementation（实施）：明确为 5 步计划——搭建 GraphQL 服务（Apollo Server）→ Schema 设计工作坊 → 从新功能开始渐进迁移 → REST 与 GraphQL 双轨运行 → 下线旧 REST 端点；并给出时间线（2025 Q4 启动、2026 Q1 完成）、Owner 与成功指标（响应时间提升 30%、客户端取数效率、新端点请求减少等）。

建议把"Consequences"写成正/负两栏清单（正面收益 + 负面权衡），而非单一结论——这正是评估用例 decision-record.json 中"Consequences include both positive (benefits) and negative (trade-offs)"的验收要求。

五、从对话到决策记录：Notion MCP 完整工作流

决策日志数据库在 awesome-codex-skills 中并非手工维护，而是由 SKILL.md 定义的捕获工作流自动驱动。整体流程五步：

1. 定义捕获目标：明确内容类型（决策、How-To、FAQ、Wiki 条目、学习笔记、文档页）与目标受众；
2. 定位目标数据库：从reference/下各*-database.md指南中挑选正确的库（决策场景即本库），确认必需属性；
3. 抽取与结构化：从对话中提取事实、决策、行动项与理由；对决策类内容，重点记录备选方案、理由与结果；
4. 在 Notion 创建/更新：用Notion:notion-create-pages按 Schema 写入，更新时先用notion-fetch拉取再notion-update-page修改；
5. 链接与曝光：添加与 Hub 页、相关文档、团队的 relation/backlink，并附摘要与变更记录。

5.1 前置条件：接入 Notion MCP

若 MCP 调用因未连接而失败，按 SKILL.md 第 0 步完成接线：

# 1. 添加 Notion MCP codex mcp add notion --url https://mcp.notion.com/mcp # 2. 启用远程 MCP 客户端（二选一） # a) 在 config.toml 中设置 [features].rmcp_client = true # b) 或运行时开启 codex --enable rmcp_client # 3. OAuth 登录 codex mcp login notion

登录成功后需重启 codex，再回到第 1 步继续。

5.2 决策捕获的四个关键动作

以"记录 REST → GraphQL 迁移决策"为例，decision-capture.md 展示了标准动作序列：

1. 抽取决策：从对话中识别出 Decision、Context、Alternatives、Rationale 四要素；
2. 查找决策库：Notion:notion-search，query 用 "architecture decisions" 或 "ADR"，命中 "Architecture Decision Records" 数据库；
3. 拉取 Schema：Notion:notion-fetch获取确切的属性名与类型（Decision/Date/Status/Domain/Impact/Deciders/Stakeholders）；
4. 创建记录：Notion:notion-create-pages写入属性负载与六段式正文，最后从架构 Wiki 加入链接并在 Slack 通知团队。

5.3 调用链上的工具

六、视图设计：让决策库可读可用

光有数据不够，还要让不同角色能以最顺手的方式浏览。原文档定义了五个开箱即用的视图：

• Recent Decisions（最近决策）：按 Date 降序排序，回答"最近发生了什么"；
• Active Decisions（有效决策）：筛选Status = "Accepted"，回答"当前哪些决定仍然生效"；
• By Domain（按领域）：按 Domain 分组，回答"各领域分别有什么决策"；
• High Impact（高影响）：筛选Impact = "High"，回答"哪些决策影响面最大"；
• Pending（待定）：筛选Status = "Proposed"，回答"还有哪些决定悬而未决"。

这五个视图覆盖了决策管理的核心查询模式：时间维度（Recent）、有效性维度（Active）、分类维度（By Domain）、优先级维度（High Impact）与待办维度（Pending）。在 Notion 中，每个视图都是一次排序/筛选/分组的组合，可随团队需要继续扩展，例如按 Deciders 筛选或按 Related Decisions 展开依赖链。这与 database-best-practices.md 中"为常见用例创建视图、用关系连接内容"的原则一脉相承。

七、最佳实践与质量保障

原文档给出五条维护规范，结合仓库中的评估体系可进一步收敛为可执行的检查清单：

1. 及时记录（Document immediately）：在决策作出当下、上下文还新鲜时立刻记录——评估用例强调"Captured decision while context fresh"是成功关键；
2. 保留备选方案（Include alternatives）：展示考虑过什么、为何未选——即模板中 Options Considered 的"Pros/Cons + 拒绝理由"；
3. 跟踪被取代的决策（Track superseded）：决策变更时把旧记录状态更新为Superseded，保持历史可追溯；
4. 链接相关决策（Link related）：用 relation 属性表达依赖关系，形成决策网络而非孤立条目；
5. 定期复审（Review periodically）：周期检查旧决策是否仍然有效，及时标记Deprecated。

此外，database-best-practices.md 提供了更通用的数据库治理建议：保持简单（先核心属性，按需扩展）、统一命名（title/status/tags/owner）、包含元数据（时间戳、维护者、复核日期）、启用发现（善用标签与视图）、为扩展规划（尽早考虑筛选与关系）。落到决策库上，还建议"把 Schema 写进数据库描述、每季度审查属性、培训团队统一用法"。

7.1 用评估用例验证捕获质量

仓库的 evaluations/README.md 与 decision-record.json 提供了可直接套用的验收标准，用于检验一次决策捕获是否合格：

• 能从对话上下文识别出"这是一条决策记录"；
• 输出严格遵循 Context → Decision → Rationale → Options Considered（含 Pros/Cons）→ Consequences → Implementation 结构；
• 决策陈述清晰（如"选 PostgreSQL 而非 MongoDB"），被拒方案也带理由；
• Consequences 同时包含正面收益与负面权衡；
• 若写入数据库，属性设置正确（Decision、Date、Status: Accepted、Domain: Architecture、Impact）；
• 记录带日期、状态为 Accepted，使用正确的工具名（notion-search/notion-fetch/notion-create-pages）。

值得一提的是，验收标准刻意强调"具体可测试"优于"模糊表述"（Good："Preserves exact bash commands from conversation"vs. Bad："Creates good documentation"），这一原则同样适用于团队日常复盘：给每条决策记录设定可量化的成功指标，而不是停留在"记录得不错"。

八、总结

决策日志数据库（ADR）是知识捕获体系中"决策可追溯"的核心载体。通过 decision-log-database.md 定义的八属性 Schema、JSON 写入方式与六段式内容模板，配合 SKILL.md 的 MCP 工作流、decision-capture.md 的完整范例与 decision-record.json 的验收标准，团队可以将散落在对话中的技术抉择，沉淀为结构化、可链接、可复盘的长期资产——当三个月后有人问起"为什么我们的数据库是 PostgreSQL"时，一条带完整背景与权衡的决策记录就是最好的答案。

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills