从 Notion 规格到可执行实施：解析 awesome-codex-skills 中 notion-spec-to-implementation 的 API 功能实战示例

从 Notion 规格到可执行实施：解析 awesome-codex-skills 中 notion-spec-to-implementation 的 API 功能实战示例

【免费下载链接】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 仓库中的notion-spec-to-implementation技能展开，以 examples/api-feature.md 这一端到端示例为骨架，完整还原"从一条用户请求出发，借助 Notion MCP 工具链，将产品规格（Spec）自动转化为分阶段实施计划、20 个可执行任务，并建立 Spec ↔ Plan ↔ Task 双向链接"的完整工作流。读完本文，你将掌握该技能的核心调用序列（notion-search→notion-fetch→notion-create-pages→notion-update-page）、任务数据库 Schema 的正确读取方式、任务拆分与估算规则，以及如何将该模式复用到你自己的功能开发项目中。

一、技能定位与适用场景

notion-spec-to-implementation是 awesome-codex-skills 仓库中面向 Notion 工作流自动化的一项 Codex 技能。其核心定位在 SKILL.md 的 frontmatter 中定义得非常明确：

Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.

即：把 Notion 中的 PRD / 功能规格文档，转化为相互关联的实施计划、任务清单，并持续跟踪状态更新。它最适合三类场景：

• 功能实现（Feature Implementation）
• API 开发（API Development）
• 技术类项目（Technical Projects）

api-feature.md 正是针对"API 开发"场景给出的完整 walkthrough：用户只提交了一句请求——"Create an implementation plan for the User Profile API spec"，Agent 便自动完成了从查规格、解析、规划、建任务到回写规格的全部动作。技能目录中还包含 database-migration.md（数据库迁移）与 ui-component.md（UI 组件）两个同构示例，说明这套流程对不同类型的规格文档具有通用性。

二、工作流总览与前置条件

2.1 核心调用链

整个技能的执行严格遵循一个固定工具序列。该序列在 SKILL.md 的 Quick start 中被概括为五步：

1. 用Notion:notion-search定位规格，再用Notion:notion-fetch获取其完整内容；
2. 按 reference/spec-parsing.md 的模式解析需求与歧义点；
3. 用Notion:notion-create-pages创建计划页（在 quick 与 full 两种模板中选择）；
4. 找到任务数据库、确认 Schema，再用Notion:notion-create-pages创建任务；
5. 用Notion:notion-update-page建立 Spec ↔ Plan ↔ Tasks 的相互链接，并持续维护状态。

而 evaluations/spec-to-tasks.json 中的expected_behavior进一步将这个序列规范化为可验证的行为断言：Notion:notion-search (2x) → Notion:notion-fetch (2x) → Notion:notion-create-pages (Nx)——即先找规格、再找任务数据库（两次搜索），先取规格内容、再取数据库 Schema（两次获取），最后批量建页。这份评估文件同时给出了 12 条success_criteria，包括"必须先搜索再获取""任务大小控制在 1–2 天""任务属性与数据库 Schema 完全一致""使用parent: { data_source_id: 'collection://...' }落库"等，可作为 Agent 自检清单。

2.2 前置条件：Notion MCP 连接

在 SKILL.md 的 Workflow 第 0 步明确要求：如果任何 MCP 调用因 Notion MCP 未连接而失败，必须先暂停并完成连接设置。具体步骤为：

1. 添加 Notion MCP 服务：

   codex mcp add notion --url https://mcp.notion.com/mcp

2. 启用远程 MCP 客户端：在config.toml中设置[features].rmcp_client = true，或运行codex --enable rmcp_client；
3. 用 OAuth 登录：

   codex mcp login notion

登录成功后用户需要重启 codex，Agent 应在当轮给出结论并提示用户重启后从第 1 步继续。这是整个技能能跑通的环境前提，务必先行验证。

三、实战示例拆解：User Profile API 规格转实施计划

以下严格按 examples/api-feature.md 的七个执行步骤展开，每一步都会补充相应的参考模板与源码依据。

3.1 Step 1：定位并获取规格（Fetch Specification）

用户请求是"Create an implementation plan for the User Profile API spec"。Agent 首先在 Notion 内部搜索规格页：

Notion:notion-search query: "User Profile API spec" query_type: "internal"

命中结果为位于 Engineering Specs 下的"User Profile API Specification"页面。随后用notion-fetch按页面 ID 拉取完整内容：

Notion:notion-fetch id: "user-profile-api-spec-page-id"

这一步对应的规范模式见 reference/spec-parsing.md 的 "Finding the Specification" 一节：搜索关键词通常采用"[Feature Name] spec"或"[Feature Name] specification"；如果命中多个结果，应询问用户使用哪一个；如果没有命中，则向用户索要 URL 或 ID。

3.2 Step 2：解析规格内容（Parse Specification）

获取到的规格全文被完整提取，其结构是典型的"需求型规格"（Requirements-Based Spec），包含以下五个板块：

Overview：RESTful API for user profile management（用户资料管理的 RESTful API）

功能需求（Functional Requirements）：

• FR-1: 按 ID 获取用户资料（Get user profile by ID）
• FR-2: 更新用户资料（name、bio、avatar）
• FR-3: 上传资料头像（Upload profile avatar）
• FR-4: 获取用户公开资料（限定字段）
• FR-5: 按姓名搜索用户（Search users by name）

非功能需求（Non-Functional Requirements）：

• NFR-1: 响应时间 < 200ms（p95）
• NFR-2: 支持 1000 并发用户
• NFR-3: 头像上传 < 5MB
• NFR-4: GDPR 合规（数据可迁移性）

API 端点（5 个）：

GET /api/v1/users/:id PUT /api/v1/users/:id POST /api/v1/users/:id/avatar GET /api/v1/users/:id/public GET /api/v1/users/search

数据模型（Data Model）：

• id (UUID)
• email (string, unique)
• name (string)
• bio (text, max 500 chars)
• avatar_url (string)
• created_at (timestamp)
• updated_at (timestamp)

安全要求（Security）：

• 认证：JWT bearer token
• 授权：用户只能更新自己的资料
• 限流：每用户 100 req/min

验收标准（Acceptance Criteria）：

• AC-1: 所有端点返回正确的 HTTP 状态码
• AC-2: 校验错误返回 400 并携带错误详情
• AC-3: 未授权访问返回 401
• AC-4: 超过限流返回 429
• AC-5: 头像图片存储在 S3

关于解析方法论，reference/spec-parsing.md 给出了系统的提取策略：

• 需求识别：关注 "Must / Should / Will" 语句、编号需求（REQ-1）、用户故事（As a... I want...）、验收标准章节和功能清单；
• 分类归组：功能需求（系统做什么）、非功能需求（性能/安全/可扩展性/可用性/合规）、约束（技术/业务/时间线约束）；
• 优先级提取：将 "Critical / Must have / P0"、"Important / Should have / P1"、"Nice to have / Could have / P2"、"Future / Won't have / P3" 映射到实施阶段；
• 验收标准解析：显式标准直接转成 checklist；隐式标准从需求推导（例如"支持上传 100MB 文件"应推导出"超过 100MB 被拒绝并报错"）；同时要确保标准可测试——"系统很快"不可测，"页面 2 秒内加载"才可测；
• 歧义处理：对于不清晰的需求，使用 "Clarifications Needed" 块记录当前文本、待澄清问题、影响范围与临时假设；缺失信息、冲突需求（如 REQ-1 与 REQ-5 矛盾）也需单独成块记录并创建澄清任务。

3.3 Step 3：创建实施计划（Create Implementation Plan）

解析完成后，Agent 用notion-create-pages在指定的父页面下创建计划页：

Notion:notion-create-pages parent: { page_id: "engineering-plans-parent-id" } pages: [{ properties: { "title": "Implementation Plan: User Profile API" }, content: "[Implementation plan]" }]

关于计划深度的选择，SKILL.md 的 Workflow 第 2 步给出了明确的决策规则：

• 简单改动（Simple change）→ 使用 reference/quick-implementation-plan.md；
• 多阶段功能/迁移（Multi-phase feature/migration）→ 使用 reference/standard-implementation-plan.md；
• 计划页必须包含：overview（概述）、linked spec（关联规格）、requirements summary（需求摘要）、phases（阶段）、dependencies/risks（依赖与风险）、success criteria（成功标准），并链接回规格文档。

本示例属于典型的多阶段功能，生成的标准计划包含以下完整结构：

概述（Overview）：构建用户资料管理 RESTful API，包含 CRUD 操作、头像上传与搜索功能。

关联规格（Linked Specification）：通过<mention-page url="...">User Profile API Specification</mention-page>提及页标签链接回原规格。

需求摘要（Requirements Summary）：功能需求全部标注 ✅（获取用户资料、更新资料字段、带图像处理的上传头像、公开资料视图、按名搜索）；非功能需求（性能 p95 < 200ms、可扩展 1000 并发、头像 < 5MB 存 S3、GDPR 数据可迁移）；验收标准清单（正确状态码、输入校验、JWT 认证、限流、S3 存储）。

技术方案（Technical Approach）：

• 架构（Architecture）：Express.js (Node.js) + PostgreSQL + AWS S3（头像存储）+ Redis（资料缓存）+ PostgreSQL 全文搜索；
• 关键设计决策（Key Design Decisions）：
  1. JWT 认证：无状态认证，可水平扩展；
  2. S3 存储头像：存储卸载，可无缝对接 CDN；
  3. Redis 缓存：降低高频访问资料的数据库负载；
  4. 限流：令牌桶算法，按用户维度限制。

实施阶段（Implementation Phases）——这是计划的核心，共 5 个阶段、12 个工作日：

依赖（Dependencies）：

• 外部依赖：AWS S3 bucket（已就绪 ✅）、Redis 实例（已就绪 ✅）、PostgreSQL 数据库（已就绪 ✅）；
• 内部依赖：JWT 认证服务（已存在）、用户数据库表（已存在）、日志基础设施（已存在）；
• Blockers：目前无（None currently）。

风险与缓解（Risks & Mitigation）——采用"概率 × 影响 × 缓解"三元结构：

时间线（Timeline）：

总工期12 个工作日（约 2.5 周）。

成功标准（Success Criteria）：

• 技术成功：5 个端点全部实现；压测验证 p95 < 200ms；支持 1000 并发；全部验收标准达成；测试覆盖率 > 80%；安全扫描通过；API 文档完备；
• 业务成功：用户资料更新可用；头像上传稳定可靠；搜索结果 < 500ms 内返回相关结果；上线第一周零严重 bug。

资源（Resources）：文档类（原规格、认证服务文档、AWS S3 设置指南）、相关工作（用户认证 API 可参考的模式、文件上传服务的头像上传参考）、外部参考（Express.js 最佳实践、AWS S3 SDK 文档、PostgreSQL 全文搜索指南）。

进度跟踪（Progress Tracking）：5 个阶段状态全部 ⏳ Not Started，整体进度 0%，最新更新记录"Implementation plan created on October 14, 2025"。

值得注意的是，以上计划结构完全对应 reference/standard-implementation-plan.md 的模板骨架——该模板本身就是"Overview → Linked Specification → Requirements Summary → Technical Approach → Implementation Phases → Dependencies → Risks & Mitigation → Timeline → Success Criteria → Resources → Progress Tracking"的十一段式结构，本文示例正是其真实落地形态。

3.4 Step 4–5：查找任务数据库并获取 Schema

计划创建后，Agent 需要找到承载任务的数据源。先搜索：

Notion:notion-search query: "Tasks database" query_type: "internal"

命中"Engineering Tasks"数据库，再用notion-fetch获取其 Schema：

Notion:notion-fetch id: "tasks-database-id"

获取到的 Schema 为：

• Data source:collection://tasks-db-uuid
• Properties:Name（title）、Status（select）、Priority（select）、Related Tasks（relation）、Story Points（number）、Tags（multi_select）

关于这一步的操作要点，reference/task-creation.md 的 "Finding the Task Database" 一节做了详细说明：搜索关键词可用"Tasks"或"Task Management"或"[Project] Tasks"；获取数据库后要识别<data-source url="collection://...">标签并提取 collection ID 作为 parent 参数；同时记录必填属性、属性类型与用于链接的 relation 属性。而 evaluations/spec-to-tasks.json 的success_criteria也强调："Database schema is fetched and data source identified from<data-source>tags"——即数据源 ID 必须从 fetch 结果中的<data-source>标签提取，这正是后续批量建任务能否落库的关键。

3.5 Step 6：批量创建实施任务（Create Implementation Tasks）

拿到 Schema 后，Agent 用notion-create-pages以data_source_id为 parent 创建任务页（任务落在数据库内而非普通页面）。示例以 Phase 1 的"搭建数据库 Schema"任务为例，展示了完整调用：

Notion:notion-create-pages parent: { data_source_id: "collection://tasks-db-uuid" } pages: [{ properties: { "Name": "Setup database schema for User Profile API", "Status": "To Do", "Priority": "High", "Related Tasks": ["impl-plan-page-id", "spec-page-id"], "Story Points": 3, "Tags": "backend, database, api" }, content: "## Context\nImplementation task for <mention-page url=\"...\">User Profile API Specification</mention-page>\n\nPart of <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page> - Phase 1\n\n## Objective\nCreate database schema for user profile storage\n\n## Requirements\nBased on spec data model:\n- id (UUID, primary key)\n- email (string, unique index)\n- name (string, not null)\n- bio (text, max 500 chars)\n- avatar_url (string, nullable)\n- created_at (timestamp)\n- updated_at (timestamp)\n\n## Acceptance Criteria\n- [ ] Migration file created\n- [ ] Schema includes all required fields\n- [ ] Indexes on email (unique) and name (search)\n- [ ] Constraints validated (bio length, email format)\n- [ ] Migration tested on dev database\n- [ ] Rollback migration created\n\n## Technical Approach\n```sql\nCREATE TABLE user_profiles (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n email VARCHAR(255) UNIQUE NOT NULL,\n name VARCHAR(255) NOT NULL,\n bio TEXT CHECK (length(bio) <= 500),\n avatar_url TEXT,\n created_at TIMESTAMP DEFAULT NOW(),\n updated_at TIMESTAMP DEFAULT NOW()\n);\n\nCREATE INDEX idx_user_profiles_email ON user_profiles(email);\nCREATE INDEX idx_user_profiles_name ON user_profiles USING gin(to_tsvector('english', name));\n```\n\n## Dependencies\n- Blocked By: None\n- Blocks: All Phase 2 tasks\n\n## Estimated Effort\n3 story points (half day)\n" }]

该示例任务完整体现了 reference/task-creation-template.md 的结构要求：Context（关联规格 + 所属计划阶段）、Objective（目标）、Requirements（从规格数据模型提炼）、Acceptance Criteria（可测试的 checklist）、Technical Approach（含可直接执行的 SQL 迁移与索引 DDL）、Dependencies（Blocked By / Blocks）、Estimated Effort。示例中注明"Create similar tasks for all phases - 20 tasks total"，即 5 个阶段共生成 20 个任务。

围绕任务创建，reference/task-creation.md 还给出了丰富的实操规则：

任务粒度（Size Guidelines）：好的任务应 1–2 天可完成、有单一明确交付物、可独立测试、依赖最小；超过 3 天需继续拆分；小于 2 小时则过于细碎，应与相关工作合并。同时按阶段调整粒度：早期阶段可接受较大任务（如"设计数据库 Schema"），后期阶段应为小而精确的任务（如"修复表单校验 bug"）。

任务类型（Task Types）：Setup（环境准备）、Implement（功能实现）、Integrate（组件对接）、Test（验证质量）、Document（文档产出）、Fix（缺陷修复）、Refactor（代码质量改进），每种类型都有推荐的标题前缀（如 "Setup: ..."、"Implement: ..."）。

排序策略（Sequencing）：识别关键路径（数据库 Schema → API 基础 → 核心业务逻辑 → 前端集成 → 测试 → 部署）；识别可并行轨道（后端开发、前端开发、基础设施三条 Track）；按阶段分组排序。

优先级（Priority Assignment）：P0/Critical（阻塞一切、核心功能、安全需求、数据完整性）、P1/High（重要功能、面向用户的功能、性能需求）、P2/Medium（锦上添花、优化）、P3/Low（未来增强、边界情况、外观改进）。

估算（Estimation）：Story Points 换算为 1 点=几小时、2 点=半天、3 点=一天、5 点=两天、8 点=3–4 天（应考虑拆分）；直接时间估算为 2–4 小时小任务、1 天中任务、2 天大任务、3+ 天需再拆分；估算需综合复杂度、未知项、依赖、测试要求与文档需求。

任务关系（Task Relationships）：父子模式（大功能拆子任务）、依赖链模式（A 阻塞 B 阻塞 C）、关联模式（并行工作围绕同一中心任务）。

命名规范：具体化（"Implement user login with email/password" 而非 "Add login"）、带上下文（"Dashboard: Add revenue chart widget"）、使用动作动词（Implement / Build / Create / Integrate / Fix / Test / Document / Refactor 等）。

3.6 Step 7：将计划回链到规格（Link Plan Back to Spec）

闭环的最后一步是用notion-update-page在规格页的验收标准之后追加"Implementation"区块，实现双向链接：

Notion:notion-update-page page_id: "user-profile-api-spec-page-id" command: "insert_content_after" selection_with_ellipsis: "## Acceptance Criteria..." new_str: " --- ## Implementation **Implementation Plan**: <mention-page url="...">Implementation Plan: User Profile API</mention-page> **Implementation Tasks**: See plan for full task breakdown (20 tasks across 5 phases) **Status**: Planning complete, ready to start implementation "

至此，三类产物通过<mention-page>提及页标签相互串联：计划页链接规格页，规格页回链计划页，任务页同时链接规格与计划。正如 SKILL.md Workflow 第 4 步所总结的——"Plan links to spec; tasks link to both plan and spec"，双向链接使工程师可以在规格、计划、任务之间无缝导航。

3.7 输出给用户的总结摘要

整个流程完成后，Agent 向用户输出的总结摘要（Summary Provided to User）包含以下信息层次：

• 计划概览：Feature（User Profile API）、Duration（12 天 / ~2.5 周）、Phases（5：Foundation → Core → Avatar → Search → Testing）、Tasks（20 个任务）、Target Launch（October 28, 2025）；
• 各阶段简述：Phase 1 数据库 Schema / S3 和 Redis / API 脚手架（2 天）；Phase 2 GET/PUT 用户资料 / 认证与校验 / 限流（3 天）；Phase 3 图片上传与校验 / S3 集成 / 图片处理（2 天）；Phase 4 用户搜索 / 公开资料端点（2 天）；Phase 5 单元与集成测试 / 性能测试 / 文档（3 天）；
• 关键交付物：5 个 REST API 端点、S3 头像上传、用户搜索、完整测试、API 文档；
• 已创建链接：✅ 计划页、✅ 规格已回写计划链接、✅ 任务数据库中的 20 个任务、✅ 所有任务均链接到计划与规格；
• 下一步建议：评审并批准计划、为团队成员分配任务、启动 Phase 1（Foundation）、每日站会跟踪进度。

四、示例背后：闭环中的进度跟踪机制

虽然示例止步于"规划完成"，但技能的完整闭环还包含持续进度跟踪，这部分规范集中在 reference/progress-tracking.md，与示例末尾的 Progress Tracking 章节一脉相承：

• 更新频率：活跃开发期每日更新（任务状态、进度备注、阻塞项）；阶段完成时做里程碑更新（标记阶段完成、里程碑摘要、时间线调整）；任务状态流转时做状态变更更新（To Do → In Progress → In Review → Done / Blocked）；
• 进度备注格式：每日进度（Completed / In Progress / Next Steps / Blockers / Decisions Made / Notes）、里程碑摘要（Completed Tasks / Deliverables / Metrics / Challenges Overcome / Learnings / Impact on Timeline）；
• 计划页维护：整体进度百分比、各阶段状态（✅ 完成 / 🔄 进行中 / ⏳ 未开始）、任务统计、时间线对比表（Original vs Current）；
• 阻塞项管理：记录状态、影响、解锁所需动作、负责人、目标解决时间；解决后更新 Resolution；需要升级时在任务中更新状态并 @ 相关人员；
• 度量跟踪：速度（Velocity）、质量（测试覆盖率、评审通过率、bug 数）、进度（需求完成数、验收标准达成数、测试通过数）；
• 利益相关方沟通：周报模板与高管摘要模板（🟢 On Track / 🟡 At Risk / 🔴 Behind）；
• 自动化跟踪：通过查询任务数据库按 Status 聚合生成统计（To Do / In Progress / Blocked / In Review / Done），并基于平均速度（如 6 tasks/week）计算预计完成时间；
• 最佳实践：及时更新不积压、表述具体、用量化指标、即时上报阻塞、链接实际工作产物、记录决策缘由、如实汇报、以实施计划页为唯一事实源。

五、示例中演示的关键能力（Key Features）

api-feature.md 末尾系统总结了该示例所演示的四项核心能力，这也是判断 Agent 执行质量的标准：

1. Spec Parsing（规格解析）

• 提取功能与非功能需求；
• 识别 API 端点；
• 记录数据模型；
• 捕获验收标准；
• 理解安全需求。

2. Implementation Planning（实施规划）

• 拆分为逻辑阶段；
• 合理排序工作（foundation → features → testing）；
• 识别依赖关系；
• 估算每阶段工作量；
• 创建现实的时间线。

3. Task Creation（任务创建）

• 生成 20 个具体任务；
• 每个任务包含上下文、验收标准、技术方案；
• 任务同时链接规格与计划；
• 正确标注依赖关系。

4. Bidirectional Linking（双向链接）

• 计划链接到规格；
• 规格更新以链接回计划；
• 任务同时链接两者；
• 所有产物之间轻松导航。

六、如何在自己的项目中使用该技能

结合 SKILL.md 与 evaluations/spec-to-tasks.json，在自己的 Codex 环境中落地此技能，建议按如下清单执行：

1. 环境就绪：按本文 2.2 节完成 Notion MCP 添加、rmcp_client 启用与 OAuth 登录，并重启 codex；
2. 搜索优先：无论找规格还是找任务数据库，都先用notion-search而非直接猜测 ID；多结果时询问用户；
3. Schema 驱动建任务：用notion-fetch读取数据库后，务必从<data-source>标签提取collection://...ID，且任务属性名要与 Schema 完全一致（title 属性、Status、Priority、relation 属性等）；
4. 按模板规划与建任务：简单改动走 quick-implementation-plan.md，多阶段功能走 standard-implementation-plan.md；任务内容套用 task-creation-template.md，粒度控制在 1–2 天；
5. 建立双向链接：计划页用<mention-page>提及规格，规格页用notion-update-page的insert_content_after追加 Implementation 区块，任务页的 relation 属性同时指向规格与计划；
6. 持续跟踪：按 progress-tracking.md 的节奏维护状态，用 milestone-summary-template.md 收尾每个阶段；
7. 对照评估基准自检：以 evaluations/spec-to-tasks.json 的success_criteria作为行为验收标准——工具序列正确、数据源识别正确、任务粒度合理、验收标准可测、依赖关系完整、全部任务回链规格。

如果你想进一步了解同一技能体系在其他场景的表现，可对照阅读同目录下的 examples/ui-component.md（UI 组件：7 个任务）与 examples/database-migration.md（数据库迁移）示例，以及配套的 evaluations/basic-spec-implementation.json 评估基准——它们共同构成了一套可复制、可验证的"Notion 规格 → 实施落地"自动化范式。

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