从 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 ImplementationAPI 开发API Development技术类项目Technical Projectsapi-feature.md 正是针对API 开发场景给出的完整 walkthrough用户只提交了一句请求——Create an implementation plan for the User Profile API specAgent 便自动完成了从查规格、解析、规划、建任务到回写规格的全部动作。技能目录中还包含 database-migration.md数据库迁移与 ui-component.mdUI 组件两个同构示例说明这套流程对不同类型的规格文档具有通用性。二、工作流总览与前置条件2.1 核心调用链整个技能的执行严格遵循一个固定工具序列。该序列在 SKILL.md 的 Quick start 中被概括为五步用Notion:notion-search定位规格再用Notion:notion-fetch获取其完整内容按 reference/spec-parsing.md 的模式解析需求与歧义点用Notion:notion-create-pages创建计划页在 quick 与 full 两种模板中选择找到任务数据库、确认 Schema再用Notion:notion-create-pages创建任务用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 未连接而失败必须先暂停并完成连接设置。具体步骤为添加 Notion MCP 服务codex mcp add notion --url https://mcp.notion.com/mcp启用远程 MCP 客户端在config.toml中设置[features].rmcp_client true或运行codex --enable rmcp_client用 OAuth 登录codex mcp login notion登录成功后用户需要重启 codexAgent 应在当轮给出结论并提示用户重启后从第 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包含以下五个板块OverviewRESTful API for user profile management用户资料管理的 RESTful API功能需求Functional RequirementsFR-1: 按 ID 获取用户资料Get user profile by IDFR-2: 更新用户资料name、bio、avatarFR-3: 上传资料头像Upload profile avatarFR-4: 获取用户公开资料限定字段FR-5: 按姓名搜索用户Search users by name非功能需求Non-Functional RequirementsNFR-1: 响应时间 200msp95NFR-2: 支持 1000 并发用户NFR-3: 头像上传 5MBNFR-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 Modelid (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 CriteriaAC-1: 所有端点返回正确的 HTTP 状态码AC-2: 校验错误返回 400 并携带错误详情AC-3: 未授权访问返回 401AC-4: 超过限流返回 429AC-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 / Wont 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架构ArchitectureExpress.js (Node.js) PostgreSQL AWS S3头像存储 Redis资料缓存 PostgreSQL 全文搜索关键设计决策Key Design DecisionsJWT 认证无状态认证可水平扩展S3 存储头像存储卸载可无缝对接 CDNRedis 缓存降低高频访问资料的数据库负载限流令牌桶算法按用户维度限制。实施阶段Implementation Phases——这是计划的核心共 5 个阶段、12 个工作日阶段时间目标关键任务交付物工作量Phase 1: FoundationDay 1–2搭建核心基础设施建数据库 Schema、配置 S3 bucket、搭建 Redis 缓存、创建 API 脚手架具备 DB/存储/缓存的可用骨架2 天Phase 2: Core EndpointsDay 3–5实现主要 CRUDGET 用户资料、PUT 更新资料、输入校验、JWT 认证中间件、限流带认证的可用 CRUD3 天Phase 3: Avatar UploadDay 6–7基于 S3 的头像管理头像上传端点、图片校验大小/格式、图片处理与缩放、带签名 URL 上传 S3头像上传/更新功能2 天Phase 4: Search Public ProfileDay 8–9完成剩余功能用户搜索、公开资料端点、搜索索引、搜索查询优化搜索与公开资料可用2 天Phase 5: Testing OptimizationDay 10–12生产级质量单元测试、集成测试、性能测试、安全审计、API 文档测试完备、有文档、生产就绪3 天依赖Dependencies外部依赖AWS S3 bucket已就绪 ✅、Redis 实例已就绪 ✅、PostgreSQL 数据库已就绪 ✅内部依赖JWT 认证服务已存在、用户数据库表已存在、日志基础设施已存在Blockers目前无None currently。风险与缓解Risks Mitigation——采用概率 × 影响 × 缓解三元结构风险概率影响缓解措施图片处理性能MediumMedium用后台任务队列处理立即返回签名上传 URLS3 上传失败LowMedium指数退避重试逻辑临时回退本地存储限流复杂度LowLow使用成熟库express-rate-limit Redis store搜索性能MediumMedium添加数据库索引必要时再评估 Elasticsearch时间线TimelineMilestoneTarget DateStatusPhase 1 CompleteOct 16⏳ PlannedPhase 2 CompleteOct 19⏳ PlannedPhase 3 CompleteOct 21⏳ PlannedPhase 4 CompleteOct 23⏳ PlannedPhase 5 CompleteOct 26⏳ PlannedProduction DeployOct 28⏳ Planned总工期12 个工作日约 2.5 周。成功标准Success Criteria技术成功5 个端点全部实现压测验证 p95 200ms支持 1000 并发全部验收标准达成测试覆盖率 80%安全扫描通过API 文档完备业务成功用户资料更新可用头像上传稳定可靠搜索结果 500ms 内返回相关结果上线第一周零严重 bug。资源Resources文档类原规格、认证服务文档、AWS S3 设置指南、相关工作用户认证 API 可参考的模式、文件上传服务的头像上传参考、外部参考Express.js 最佳实践、AWS S3 SDK 文档、PostgreSQL 全文搜索指南。进度跟踪Progress Tracking5 个阶段状态全部 ⏳ 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获取其 SchemaNotion:notion-fetch id: tasks-database-id获取到的 Schema 为Data source:collection://tasks-db-uuidProperties:Nametitle、Statusselect、Priorityselect、Related Tasksrelation、Story Pointsnumber、Tagsmulti_select关于这一步的操作要点reference/task-creation.md 的 Finding the Task Database 一节做了详细说明搜索关键词可用Tasks或Task Management或[Project] Tasks获取数据库后要识别data-source urlcollection://...标签并提取 collection ID 作为 parent 参数同时记录必填属性、属性类型与用于链接的 relation 属性。而 evaluations/spec-to-tasks.json 的success_criteria也强调Database schema is fetched and data source identified fromdata-sourcetags——即数据源 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\nsql\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、DependenciesBlocked 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 TypesSetup环境准备、Implement功能实现、Integrate组件对接、Test验证质量、Document文档产出、Fix缺陷修复、Refactor代码质量改进每种类型都有推荐的标题前缀如 Setup: ...、Implement: ...。排序策略Sequencing识别关键路径数据库 Schema → API 基础 → 核心业务逻辑 → 前端集成 → 测试 → 部署识别可并行轨道后端开发、前端开发、基础设施三条 Track按阶段分组排序。优先级Priority AssignmentP0/Critical阻塞一切、核心功能、安全需求、数据完整性、P1/High重要功能、面向用户的功能、性能需求、P2/Medium锦上添花、优化、P3/Low未来增强、边界情况、外观改进。估算EstimationStory 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包含以下信息层次计划概览FeatureUser Profile API、Duration12 天 / ~2.5 周、Phases5Foundation → Core → Avatar → Search → Testing、Tasks20 个任务、Target LaunchOctober 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 1Foundation、每日站会跟踪进度。四、示例背后闭环中的进度跟踪机制虽然示例止步于规划完成但技能的完整闭环还包含持续进度跟踪这部分规范集中在 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 Featuresapi-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 环境中落地此技能建议按如下清单执行环境就绪按本文 2.2 节完成 Notion MCP 添加、rmcp_client 启用与 OAuth 登录并重启 codex搜索优先无论找规格还是找任务数据库都先用notion-search而非直接猜测 ID多结果时询问用户Schema 驱动建任务用notion-fetch读取数据库后务必从data-source标签提取collection://...ID且任务属性名要与 Schema 完全一致title 属性、Status、Priority、relation 属性等按模板规划与建任务简单改动走 quick-implementation-plan.md多阶段功能走 standard-implementation-plan.md任务内容套用 task-creation-template.md粒度控制在 1–2 天建立双向链接计划页用mention-page提及规格规格页用notion-update-page的insert_content_after追加 Implementation 区块任务页的 relation 属性同时指向规格与计划持续跟踪按 progress-tracking.md 的节奏维护状态用 milestone-summary-template.md 收尾每个阶段对照评估基准自检以 evaluations/spec-to-tasks.json 的success_criteria作为行为验收标准——工具序列正确、数据源识别正确、任务粒度合理、验收标准可测、依赖关系完整、全部任务回链规格。如果你想进一步了解同一技能体系在其他场景的表现可对照阅读同目录下的 examples/ui-component.mdUI 组件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从 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 ImplementationAPI 开发API Development技术类项目Technical Projectsapi-feature.md 正是针对API 开发场景给出的完整 walkthrough用户只提交了一句请求——Create an implementation plan for the User Profile API specAgent 便自动完成了从查规格、解析、规划、建任务到回写规格的全部动作。技能目录中还包含 database-migration.md数据库迁移与 ui-component.mdUI 组件两个同构示例说明这套流程对不同类型的规格文档具有通用性。二、工作流总览与前置条件2.1 核心调用链整个技能的执行严格遵循一个固定工具序列。该序列在 SKILL.md 的 Quick start 中被概括为五步用Notion:notion-search定位规格再用Notion:notion-fetch获取其完整内容按 reference/spec-parsing.md 的模式解析需求与歧义点用Notion:notion-create-pages创建计划页在 quick 与 full 两种模板中选择找到任务数据库、确认 Schema再用Notion:notion-create-pages创建任务用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 未连接而失败必须先暂停并完成连接设置。具体步骤为添加 Notion MCP 服务codex mcp add notion --url https://mcp.notion.com/mcp启用远程 MCP 客户端在config.toml中设置[features].rmcp_client true或运行codex --enable rmcp_client用 OAuth 登录codex mcp login notion登录成功后用户需要重启 codexAgent 应在当轮给出结论并提示用户重启后从第 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包含以下五个板块OverviewRESTful API for user profile management用户资料管理的 RESTful API功能需求Functional RequirementsFR-1: 按 ID 获取用户资料Get user profile by IDFR-2: 更新用户资料name、bio、avatarFR-3: 上传资料头像Upload profile avatarFR-4: 获取用户公开资料限定字段FR-5: 按姓名搜索用户Search users by name非功能需求Non-Functional RequirementsNFR-1: 响应时间 200msp95NFR-2: 支持 1000 并发用户NFR-3: 头像上传 5MBNFR-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 Modelid (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 CriteriaAC-1: 所有端点返回正确的 HTTP 状态码AC-2: 校验错误返回 400 并携带错误详情AC-3: 未授权访问返回 401AC-4: 超过限流返回 429AC-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 / Wont 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架构ArchitectureExpress.js (Node.js) PostgreSQL AWS S3头像存储 Redis资料缓存 PostgreSQL 全文搜索关键设计决策Key Design DecisionsJWT 认证无状态认证可水平扩展S3 存储头像存储卸载可无缝对接 CDNRedis 缓存降低高频访问资料的数据库负载限流令牌桶算法按用户维度限制。实施阶段Implementation Phases——这是计划的核心共 5 个阶段、12 个工作日阶段时间目标关键任务交付物工作量Phase 1: FoundationDay 1–2搭建核心基础设施建数据库 Schema、配置 S3 bucket、搭建 Redis 缓存、创建 API 脚手架具备 DB/存储/缓存的可用骨架2 天Phase 2: Core EndpointsDay 3–5实现主要 CRUDGET 用户资料、PUT 更新资料、输入校验、JWT 认证中间件、限流带认证的可用 CRUD3 天Phase 3: Avatar UploadDay 6–7基于 S3 的头像管理头像上传端点、图片校验大小/格式、图片处理与缩放、带签名 URL 上传 S3头像上传/更新功能2 天Phase 4: Search Public ProfileDay 8–9完成剩余功能用户搜索、公开资料端点、搜索索引、搜索查询优化搜索与公开资料可用2 天Phase 5: Testing OptimizationDay 10–12生产级质量单元测试、集成测试、性能测试、安全审计、API 文档测试完备、有文档、生产就绪3 天依赖Dependencies外部依赖AWS S3 bucket已就绪 ✅、Redis 实例已就绪 ✅、PostgreSQL 数据库已就绪 ✅内部依赖JWT 认证服务已存在、用户数据库表已存在、日志基础设施已存在Blockers目前无None currently。风险与缓解Risks Mitigation——采用概率 × 影响 × 缓解三元结构风险概率影响缓解措施图片处理性能MediumMedium用后台任务队列处理立即返回签名上传 URLS3 上传失败LowMedium指数退避重试逻辑临时回退本地存储限流复杂度LowLow使用成熟库express-rate-limit Redis store搜索性能MediumMedium添加数据库索引必要时再评估 Elasticsearch时间线TimelineMilestoneTarget DateStatusPhase 1 CompleteOct 16⏳ PlannedPhase 2 CompleteOct 19⏳ PlannedPhase 3 CompleteOct 21⏳ PlannedPhase 4 CompleteOct 23⏳ PlannedPhase 5 CompleteOct 26⏳ PlannedProduction DeployOct 28⏳ Planned总工期12 个工作日约 2.5 周。成功标准Success Criteria技术成功5 个端点全部实现压测验证 p95 200ms支持 1000 并发全部验收标准达成测试覆盖率 80%安全扫描通过API 文档完备业务成功用户资料更新可用头像上传稳定可靠搜索结果 500ms 内返回相关结果上线第一周零严重 bug。资源Resources文档类原规格、认证服务文档、AWS S3 设置指南、相关工作用户认证 API 可参考的模式、文件上传服务的头像上传参考、外部参考Express.js 最佳实践、AWS S3 SDK 文档、PostgreSQL 全文搜索指南。进度跟踪Progress Tracking5 个阶段状态全部 ⏳ 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获取其 SchemaNotion:notion-fetch id: tasks-database-id获取到的 Schema 为Data source:collection://tasks-db-uuidProperties:Nametitle、Statusselect、Priorityselect、Related Tasksrelation、Story Pointsnumber、Tagsmulti_select关于这一步的操作要点reference/task-creation.md 的 Finding the Task Database 一节做了详细说明搜索关键词可用Tasks或Task Management或[Project] Tasks获取数据库后要识别data-source urlcollection://...标签并提取 collection ID 作为 parent 参数同时记录必填属性、属性类型与用于链接的 relation 属性。而 evaluations/spec-to-tasks.json 的success_criteria也强调Database schema is fetched and data source identified fromdata-sourcetags——即数据源 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\nsql\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、DependenciesBlocked 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 TypesSetup环境准备、Implement功能实现、Integrate组件对接、Test验证质量、Document文档产出、Fix缺陷修复、Refactor代码质量改进每种类型都有推荐的标题前缀如 Setup: ...、Implement: ...。排序策略Sequencing识别关键路径数据库 Schema → API 基础 → 核心业务逻辑 → 前端集成 → 测试 → 部署识别可并行轨道后端开发、前端开发、基础设施三条 Track按阶段分组排序。优先级Priority AssignmentP0/Critical阻塞一切、核心功能、安全需求、数据完整性、P1/High重要功能、面向用户的功能、性能需求、P2/Medium锦上添花、优化、P3/Low未来增强、边界情况、外观改进。估算EstimationStory 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包含以下信息层次计划概览FeatureUser Profile API、Duration12 天 / ~2.5 周、Phases5Foundation → Core → Avatar → Search → Testing、Tasks20 个任务、Target LaunchOctober 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 1Foundation、每日站会跟踪进度。四、示例背后闭环中的进度跟踪机制虽然示例止步于规划完成但技能的完整闭环还包含持续进度跟踪这部分规范集中在 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 Featuresapi-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 环境中落地此技能建议按如下清单执行环境就绪按本文 2.2 节完成 Notion MCP 添加、rmcp_client 启用与 OAuth 登录并重启 codex搜索优先无论找规格还是找任务数据库都先用notion-search而非直接猜测 ID多结果时询问用户Schema 驱动建任务用notion-fetch读取数据库后务必从data-source标签提取collection://...ID且任务属性名要与 Schema 完全一致title 属性、Status、Priority、relation 属性等按模板规划与建任务简单改动走 quick-implementation-plan.md多阶段功能走 standard-implementation-plan.md任务内容套用 task-creation-template.md粒度控制在 1–2 天建立双向链接计划页用mention-page提及规格规格页用notion-update-page的insert_content_after追加 Implementation 区块任务页的 relation 属性同时指向规格与计划持续跟踪按 progress-tracking.md 的节奏维护状态用 milestone-summary-template.md 收尾每个阶段对照评估基准自检以 evaluations/spec-to-tasks.json 的success_criteria作为行为验收标准——工具序列正确、数据源识别正确、任务粒度合理、验收标准可测、依赖关系完整、全部任务回链规格。如果你想进一步了解同一技能体系在其他场景的表现可对照阅读同目录下的 examples/ui-component.mdUI 组件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
