从 Spec 到实现的全链路技能评估：awesome-codex-skills 中 notion-spec-to-implementation 评测体系深度解析-二趣网

从 Spec 到实现的全链路技能评估：awesome-codex-skills 中 notion-spec-to-implementation 评测体系深度解析

【免费下载链接】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

导读：本文聚焦 notion-spec-to-implementation 技能目录下的 evaluations/README.md 评估文档，系统讲解如何用结构化评测场景验证"Notion 规格说明（Spec）→ 实现计划 → 任务 → 进度追踪"这条自动化链路在 Codex 各模型（Haiku、Sonnet、Opus）上的稳定性与正确性。读完本文，你将掌握评测文件的组织方式、两个内置评估场景的预期行为与成功标准、评估运行的完整步骤，以及如何为新场景编写可量化、可回归的验收指标。

一、为什么需要"技能评估"：评测体系的定位与目的

notion-spec-to-implementation是 awesome-codex-skills 仓库中把 Notion 上的 PRD/功能规格转化为可执行实现产物的 Codex 技能。技能本身解决的是"文档到代码"的翻译问题，而 evaluations/README.md 解决的问题则是：如何证明这个翻译过程是可靠的。

根据评估文档，该评测体系的核心目的包括五个层面：

准确地发现并解析规格页面（Finds and parses specification pages accurately）
把规格拆解为可执行的实现计划（Breaks down specs into actionable implementation plans）
创建 Codex 可以落地实现、且带有清晰验收标准（acceptance criteria）的任务（Creates tasks that Codex can implement with clear acceptance criteria）
跟踪进度并更新实现状态（Tracks progress and updates implementation status）
在 Haiku、Sonnet、Opus 三个模型上保持一致的表现（Works consistently across Haiku, Sonnet, and Opus）

最后一条尤其关键：技能评估不仅是功能正确性测试，更是一种跨模型的一致性回归测试。因为不同模型在解析自然语言、抽取结构化需求、拆解任务粒度上的能力存在差异，评测需要保证无论由哪个模型驱动，技能的端到端产出（搜索规格 → 提取需求 → 制定计划 → 建任务 → 追踪进度）都能稳定收敛到同一套质量基线。

二、评估文件清单：两个内置评测场景

评测场景以 JSON 文件形式存放在 notion-spec-to-implementation/evaluations/ 目录下，每个文件都是一个自包含的"可执行评测用例"：包含场景名称、依赖的技能、用户查询（query）、期望行为步骤（expected_behavior）与成功标准（success_criteria）。这种"查询 + 步骤 + 验收"的结构，使得评测既可以被 Agent 自动执行，也可以被人工逐步核验。

2.1 basic-spec-implementation.json：规格转实现计划

文件 basic-spec-implementation.json 测试的是"把一份规格转成实现计划"的基础工作流，覆盖技能最核心的链路。

场景：根据规格实现用户认证（User Authentication）功能。

期望行为（12 步调用链）：

使用Notion:notion-search以 "User Authentication spec"、"auth spec" 等关键词搜索规格页；
若未找到或结果有歧义，向用户索要规格页 URL/ID；
使用Notion:notion-fetch按搜索结果中的 URL/ID 抓取规格页；
依据 reference/spec-parsing.md 中的解析模式，抽取需求、验收标准与约束；
区分功能需求（用户故事、特性、工作流）与非功能需求（性能、安全）；
按照 reference/standard-implementation-plan.md 的模板结构创建实现计划；
计划须包含：Overview（概述）、Linked Spec（关联规格）、Requirements Summary（需求摘要）、Technical Approach（技术方案）、Implementation Phases（实现阶段）；
将工作拆解为多个逻辑阶段，每个阶段包含 Goal（目标）、Tasks checklist（任务清单）、Estimated effort（预估工作量）；
从规格内容中识别依赖与风险；
使用<mention-page url='...'>将计划页链接回原始规格页；
使用Notion:notion-create-pages创建计划页，标题如 "Implementation Plan: User Authentication"；
将计划页放置到合适位置（询问用户，或建议放在项目/规格页的父级下）。

成功标准（success_criteria）：规格必须先经notion-search找到再 fetch；计划须包含清晰的概述与mention-page标签链接的规格；需求必须来自真实规格内容而非泛化模板；工作被拆成多个阶段（通常 3~5 个）；每个阶段有 Goal、复选框任务与工作量预估；依赖与风险节包含规格中的具体细节；验收标准在计划中被引用；整体遵循正确的工具序列Notion:notion-search → Notion:notion-fetch → Notion:notion-create-pages。

2.2 spec-to-tasks.json：规格直接生成任务

文件 spec-to-tasks.json 测试的是"从规格在任务数据库中创建具体任务"的场景，且明确声明同时依赖spec-to-implementation与task-manager两个技能，覆盖了数据库集成（database integration）这一更复杂的路径。

场景：阅读 Payment Integration 规格，在 Tasks 数据库中创建实现任务。

期望行为（14 步调用链）：

用Notion:notion-search搜索 Payment Integration 规格，找不到则向用户索要 URL；
用Notion:notion-fetch抓取规格全文；
依据 reference/spec-parsing.md 模式解析工作项；
依据 reference/task-creation.md 的拆解模式把工作拆成大小合适的任务；
用Notion:notion-search定位 Tasks 数据库；
用Notion:notion-fetch抓取数据库以获取 schema、属性名与数据源；
从 fetch 结果中的<data-source>标签识别正确数据源；
（推荐）先创建实现计划页再建任务；
为每个任务调用Notion:notion-create-pages，parent 使用{ data_source_id: 'collection://...' }；
按 schema 设置任务属性：Title、Status（To Do）、Priority、Related Tasks（链接到规格）；
任务描述包含上下文、来自规格的验收标准与依赖；
用<mention-page>把任务链接回规格页，任务之间按依赖相互链接；
合理排序任务（setup → implementation → testing，参照 reference/task-creation.md）；
汇报摘要："Created X tasks for Payment Integration: [task list with links]"。

成功标准：先搜索规格再 fetch；先搜索任务数据库再 fetch schema；从<data-source>标签识别数据源；创建至少 3~5 个覆盖规格范围的任务；任务粒度符合 reference/task-creation.md 的 1~2 天标准；每个任务有从规格抽取的清晰验收标准；任务通过关系属性正确排序与依赖；所有任务用mention-page链接回规格；任务属性与数据库 schema 完全一致；parent 正确使用data_source_id: 'collection://...'；工具调用序列为Notion:notion-search (2x) → Notion:notion-fetch (2x) → Notion:notion-create-pages (Nx)。

可以看到，两个评测文件在结构上完全同构（发现 → 抓取 → 解析 → 规划 → 创建 → 链接），但在输出产物上互为补充：一个产出计划页，一个产出数据库任务。二者共同构成"规格驱动开发"的两条主路径。

三、运行评估：从评测文件到可验证结果

评估文档给出了 8 个标准运行步骤，结合 SKILL.md 中的环境准备说明，可以归纳为完整的三阶段流程：

前置条件：连接 Notion MCP

运行评估前必须先确保 Notion MCP 已连通，否则所有Notion:notion-*工具调用都会失败。SKILL.md 明确给出了配置命令：

# 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 步继续。

评估执行步骤（对应 README 的 8 步）：

启用spec-to-implementation技能；
提交评测文件中的 query（例如 "Create an implementation plan for the User Authentication spec page"）；
验证技能是否先通过搜索找到规格页（而非直接凭猜测 fetch）；
检查需求是否被准确解析；
确认实现计划按阶段创建；
验证任务是否具有清晰、可实现的验收标准；
检查任务是否正确链接回规格；
分别在 Haiku、Sonnet、Opus 三个模型上重复测试。

其中第 3、6、7 步是判断"技能真的在工作"还是"模型在自由发挥"的关键分水岭——它们要求产物之间存在结构化的关联证据（搜索命中 → 链接回源），而不是仅仅输出一段看起来合理的文本。

四、预期技能行为：四条质量检查线

评估文档将"预期技能行为"拆成四条可验证的检查线，每条线都对应技能工作流中的一个环节，也与 SKILL.md 中的 Workflow（定位规格 → 选择计划深度 → 创建任务 → 链接产物 → 跟踪进度）一一对应。

4.1 Spec 发现与解析（Spec Discovery & Parsing）

对应 SKILL.md 第 1 步"Locate and read the spec"。评估要求技能：

在 Notion 中搜索规格页面；
抓取完整的规格内容；
准确抽取全部需求；
识别技术依赖；
理解验收标准；
记录歧义与缺失细节。

reference/spec-parsing.md 为此提供了可复用的解析方法：搜索时用"[Feature Name] spec"或"[Feature Name] specification"作为查询词并设置query_type: "internal"；抓取后按"需求型规格 / 用户故事型规格 / 技术设计文档 / PRD"四类常见结构分别抽取（功能需求、非功能需求、验收标准、用户画像、业务目标、成功指标等）；并通过 "Must/Should/Will"、"REQ-1"、"As a... I want..." 等信号词定位需求，按 Critical/P0、Important/P1、Nice to have/P2、Future/P3 划分优先级。对模糊需求、缺失信息、冲突需求，文档要求用标准化的 Clarifications / Missing Information / Conflicting Requirements 块记录，不能默默跳过。

4.2 实现规划（Implementation Planning）

对应 SKILL.md 第 2 步"Choose plan depth"：简单变更用 reference/quick-implementation-plan.md（Spec / Summary / Tasks / Timeline / Status 五段式）；多阶段特性或迁移用 reference/standard-implementation-plan.md（Overview / Linked Specification / Requirements Summary / Technical Approach / Implementation Phases / Dependencies / Risks / Timeline / Success Criteria / Progress Tracking 完整结构）。评估要求：

创建实现计划页；
把工作拆成逻辑阶段，标准三段为：
- Phase 1: Foundation/Setup（基础与搭建）
- Phase 2: Core Implementation（核心实现）
- Phase 3: Testing & Polish（测试与打磨）
包含时间预估；
识别阶段间依赖；
链接回原始规格。

标准计划模板中的每个阶段都要求给出 Goal、任务清单（以- [ ]复选框形式配合<mention-page>内链）与 Estimated effort，并在末尾附上 Timeline 里程碑表格（Milestone / Target Date / Status）与 Success Criteria（技术成功 + 业务成功）。

4.3 任务创建（Task Creation）

对应 SKILL.md 第 3 步"Create tasks"。评估要求技能：

找到或识别任务数据库；
抓取数据库 schema 以获取属性名；
以正确属性创建任务；
每个任务具备：清晰具体的标题、上下文与描述、验收标准（清单格式）、合适的优先级与状态、指向规格页的链接；
任务粒度适中（不大不小）；
任务间依赖被记录。

reference/task-creation.md 给出了粒度黄金标准：单个任务 1~2 天可完成、单一明确交付物、可独立测试、最少依赖；超过 3 天属于"过大"需继续拆分，少于 2 小时属于"过碎"应合并。创建时通过Notion:notion-create-pages以parent: { type: "data_source_id", data_source_id: "collection://tasks-db-uuid" }写入数据库，并设置 Status（To Do）、Priority、Relation 属性与 Due Date。任务命名采用动作动词约定（Setup / Implement / Integrate / Test / Document / Fix / Refactor 前缀），例如 "Implement: User login flow" 而非模糊的 "Add login"。

4.4 进度追踪（Progress Tracking）

对应 SKILL.md 第 5 步"Track progress"。评估要求：

实现计划包含进度标记；
任务可以随工作推进被更新；
状态更新链接到已完成的工作；
阻塞项或变更被记录。

reference/progress-tracking.md 定义了更新节奏（每日更新、里程碑更新、状态变更更新三类）、状态机（To Do → In Progress → In Review → Done，外加 Blocked 分支）、标准化的进度笔记格式（Completed / In Progress / Next Steps / Blockers / Decisions Made / Notes），以及计划页上的 Overall Progress 百分比、阶段状态（✅/🔄/⏳）与任务汇总统计。配套的 progress-update-template.md 与 milestone-summary-template.md 分别覆盖日常更新与阶段收尾两种场景，确保"计划页 = 唯一事实源（source of truth）"。

五、创建新的评估场景：六条编写指南

评估文档为扩展评测覆盖度给出了六条指导原则，核心是用组合矩阵铺开评测空间：

测试不同类型的规格：特性（features）、迁移（migrations）、重构（refactors）、API 变更、UI 组件——对应仓库中 examples/ 下的 api-feature.md、database-migration.md、ui-component.md 等端到端走读示例；
变化复杂度：从单一阶段的简单规格到多阶段的复杂实现；
测试任务粒度：技能是否产出大小合适的任务；
纳入边界情况：模糊规格、冲突需求、缺失细节；
测试数据库集成：在不同 schema 的既有任务数据库中创建任务；
测试进度追踪：任务完成后实现计划能否同步更新。

编写新评测时，可完全复用 basic-spec-implementation.json 与 spec-to-tasks.json 的 JSON 骨架——name（场景名）、skills（依赖技能数组）、query（模拟用户输入）、expected_behavior（带编号的步骤化期望）、success_criteria（可判定的通过条件）——只需替换业务场景与验收断言。这种结构化设计让评测用例天然具备"可机器断言、可人工复核、可跨模型回归"三种用途。

六、成功标准示例：如何写出"好"的验收标准

评估文档用 Good/Bad 对照的方式给出了写验收标准的纪律——这本身就是评估体系设计哲学的核心：一切断言必须可观察、可判定、可复现。

好的标准（具体、可测试）：

"Searches Notion for spec page using feature name"（用特性名搜索 Notion 规格页）
"Creates implementation plan with 3 phases: Setup → Core → Polish"（创建含 3 个阶段的实现计划）
"Creates 5-8 tasks in task database with properties: Task (title), Status, Priority, Sprint"（创建 5~8 个任务并携带正确属性）
"Each task has acceptance criteria in checklist format (- [ ] ...)"（每个任务有清单格式的验收标准）
"Tasks link back to spec using mention-page tag"（任务用 mention-page 标签链接回规格）
"Task titles are specific and actionable (e.g., 'Create login API endpoint' not 'Authentication')"（任务标题具体可执行）

坏的标准（模糊、不可测试）：

"Creates good implementation plan"（创建好的实现计划——什么是"好"？）
"Tasks are well-structured"（任务结构良好——如何度量？）
"Breaks down spec appropriately"（适当地拆解规格——何为适当？）
"Links to spec"（链接到规格——用什么方式、链接到哪？）

写坏标准很容易，因为它不需要任何领域知识；写好标准则必须把断言下沉到可观测的产物属性（阶段数量、属性名集合、清单语法、内链标签、标题动词），这正是 evaluations/README.md 全文一以贯之的度量哲学。同样的判断标准也适用于技能内部的验收标准抽取——reference/spec-parsing.md 明确要求把 "System is fast" 改写成 "Page loads in < 2 seconds" 这类可测试表述，隐含的验收标准也要从需求推导（如"支持 100MB 上传"应推导出"100MB 以内成功 / 超过 100MB 被拒绝并报错 / 显示进度条 / 可取消"四条断言）。

七、评估体系与技能资产的整体闭环

最后把评估文档放回技能包整体来看：notion-spec-to-implementation目录是一个"参考文档 + 模板 + 示例 + 评测"四层配套的完整资产结构——

SKILL.md：技能入口，定义五步工作流与 MCP 配置方式；
reference/：8 份解析模式与模板（spec-parsing、quick/standard-implementation-plan、task-creation 及其模板、progress-tracking、progress-update、milestone-summary）；
examples/：3 份端到端走读示例，覆盖 API 特性、数据库迁移、UI 组件三类典型场景；
evaluations/：本篇文章主体——2 个 JSON 评测场景 + 运行指南 + 预期行为 + 新场景编写规范 + 成功标准示例。

评估文档正是这个资产体系的"质检关卡"：参考文档定义了技能应该怎么做，评测定义了如何证明技能做对了。对于希望在 Codex CLI/API 之上构建"规格驱动开发"工作流的团队，这套评测模式可以直接迁移：把业务 PRD 写成标准化规格，用notion-search → notion-fetch → notion-create-pages → notion-update-page的工具链自动产出计划与任务，再按本文的 Good 标准为每个产物编写可回归的验收断言，最终形成"规格 → 计划 → 任务 → 进度"全链路可观测、可度量、可跨模型复现的自动化交付闭环。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析