react-spring 仓库中的 speckit-plan基于 spec-kit 模板驱动实现规划工作流深度解析【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-springspeckit-plan是 react-spring 仓库中.claude/skills/下内置的一个 Claude Code 技能Skill对应 spec-kit 工具链的/speckit-plan命令负责把一份功能规格说明Feature Spec转化为结构化的设计产物实现计划plan.md、研究文档research.md、数据模型data-model.md、接口契约contracts/与快速上手手册quickstart.md。本文以 SKILL.md 为骨架结合仓库内.specify/的脚本与模板、specs/下已落地的真实计划文件完整还原这条「从输入到设计产出」的规划流水线帮助你在任何 spec-kit 项目中复现同样的实施规划流程。一、技能定位它解决什么问题speckit-plan的 frontmatter 明确声明了它的职责与运行边界name: speckit-plan description: Execute the implementation planning workflow using the plan template to generate design artifacts. argument-hint: Optional guidance for the planning phase compatibility: Requires spec-kit project structure with .specify/ directory metadata: author: github-spec-kit source: templates/commands/plan.md user-invocable: true disable-model-invocation: false几个关键约束值得注意必须存在.specify/目录技能在前置检查与 Outline 阶段都直接依赖.specify/extensions.yml、.specify/scripts/bash/setup-plan.sh、.specify/memory/constitution.md等路径没有这套目录结构就无法运行。react-spring 仓库恰好完整携带了这套结构。user-invocable: true它既可由用户主动以/speckit-plan斜杠命令触发也可被模型调用argument-hint允许传入可选指导性参数$ARGUMENTS命令必须先考虑该输入再继续。它的产出是「设计产物」而非「代码」规划阶段Phase 0–1结束即上报具体任务拆分交给后续的/speckit-tasks命令见 plan-template.md 中对各产物归属的注释tasks.md标注为/speckit-tasks command - NOT created by /speckit-plan。二、整体工作流两条 Hook 带包裹的五步 Outlinespeckit-plan的执行结构可以概括为「一次规划两条扩展钩子带」[Pre-Execution: before_plan hooks] ↓ Outline 1. Setup → 运行 setup-plan.sh --json 解析 FEATURE_SPEC / IMPL_PLAN / SPECS_DIR / BRANCH Outline 2. Load context → 读取规格、宪章、计划模板 Outline 3. Execute plan → 按模板填充 门禁评估 Phase 0 研究 Phase 1 设计 Outline 4. Stop report → 上报分支、计划路径、产物清单 ↓ [Post-Execution: after_plan hooks]before_plan钩子在规划开始前检查after_plan钩子在规划产物上报之后检查两条钩子带的判定逻辑完全一致详见下一节。这种设计把「规划本身」和「规划前后需要插入的扩展行为」解耦规划流程永远只做一件事扩展点全部收敛到.specify/extensions.yml的hooks.before_plan/hooks.after_plan两个键下。react-spring 仓库的 .specify/extensions.yml 及其 .specify/extensions/git/ 目录内含speckit.git.commit、speckit.git.feature、speckit.git.initialize等命令的.md定义与配套 bash/powershell 脚本就是这套扩展机制的落地产物。三、Pre-Execution Checks扩展 Hook 的判定规则规划开始前技能会先检查项目根目录是否存在.specify/extensions.yml存在则读取hooks.before_plan键下的条目YAML 无法解析时静默跳过不中断流程。按enabled字段过滤显式enabled: false的钩子被剔除没有enabled字段的钩子默认视为启用。condition表达式不在此处求值这是技能刻意设定的边界——只有无condition字段或为 null/空的钩子才被视为可执行定义非空condition的钩子一律跳过把条件求值留给专门的 HookExecutor 实现。斜杠命令名转换规则命令名中的点.替换为连字符-例如speckit.git.commit→/speckit-git-commit。对每个可执行钩子按其optional标志输出不同的提示块。可选钩子optional: true输出## Extension Hooks **Optional Pre-Hook**: {extension} Command: /{command} Description: {description} Prompt: {prompt} To execute: /{command}强制钩子optional: false则直接要求执行并等待结果## Extension Hooks **Automatic Pre-Hook**: {extension} Executing: /{command} EXECUTE_COMMAND: {command} Wait for the result of the hook command before proceeding to the Outline.如果没有任何钩子注册或.specify/extensions.yml不存在则静默跳过。after_plan阶段复用完全相同的过滤、命名与输出逻辑仅将文案中的 Pre-Hook 换成 Hook如**Optional Hook**/**Automatic Hook**。四、Outline 五步从 Setup 到 Report4.1 Setup解析路径上下文第一步在仓库根目录运行.specify/scripts/bash/setup-plan.sh --json解析出四个关键变量FEATURE_SPEC规格文件、IMPL_PLAN计划文件、SPECS_DIR特性目录、BRANCH当前分支。技能特别提示参数中包含单引号如Im Groot时要使用转义语法I\m Groot或尽量改用双引号。仓库中 setup-plan.sh 的实现印证了这份约定它source同目录的common.sh调用get_feature_paths解析全部路径然后复制 plan 模板到 IMPL_PLAN模板缺失时退化为创建空文件并输出 Warning。--json模式优先用jq组装 JSON无jq时回退到printf手工转义输出FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH、HAS_GIT五个字段。路径解析的优先级逻辑在 common.sh 的get_feature_paths中定义得更为完整SPECIFY_FEATURE_DIRECTORY环境变量显式覆盖.specify/feature.json中的feature_directory键由/speckit.specify持久化read_feature_json_feature_directory提供jq → python3 → grep/sed三级安全解析任何解析失败都返回空值继续向下回退基于分支名前缀在specs/下查找匹配目录find_feature_dir_by_prefix支持001-feature-name顺序前缀与20260319-143022-feature-name时间戳前缀两种命名多前缀冲突时报 ERROR。同时check_feature_branch强制校验分支命名3 位数字前缀或时间戳前缀排除畸形时间戳除非feature.json已固定了一个存在的特性目录非 git 仓库则跳过该校验并给出 Warning。文件系统操作统一使用绝对路径文档与 Agent 上下文文件中的引用则使用项目相对路径——这也是Key rules中反复强调的纪律。4.2 Load context加载三类上下文读取FEATURE_SPEC即specs/特性/spec.md读取.specify/memory/constitution.md项目宪章规划阶段的门禁依据加载已被 setup 步骤复制好的IMPL_PLAN模板。仓库中的 constitution.md 与 plan-template.md 即为此处加载的对象。plan 模板给出了目标结构Summary、Technical Context含 Language/Version、Primary Dependencies、Storage、Testing、Target Platform、Project Type、Performance Goals、Constraints、Scale/Scope 九个栏目、Constitution Check、Project Structure、Complexity Tracking。4.3 Execute plan workflow填充模板并执行门禁按 IMPL_PLAN 模板结构执行填充 Technical Context未知项必须标记为NEEDS CLARIFICATION禁止猜测填充 Constitution Check内容取自 constitution.md评估门禁gates若违反而无正当理由直接 ERRORPhase 0生成research.md解决全部NEEDS CLARIFICATIONPhase 1生成data-model.md、contracts/、quickstart.mdPhase 1 收尾运行 agent 脚本更新 Agent 上下文把CLAUDE.md中!-- SPECKIT START --与!-- SPECKIT END --标记之间的计划引用指向新建的 IMPL_PLAN设计完成后复评 Constitution Check。react-spring 仓库的 CLAUDE.md 尾部恰好保留了这段标记区的现场!-- SPECKIT START -- For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan: [specs/003-remix-to-react-router-7/plan.md](https://link.gitcode.com/i/f99d56193d3f00672445c777477654fa) !-- SPECKIT END --可见本仓库当前活跃的计划正是specs/003-remix-to-react-router-7/plan.md。4.4 Stop and reportPhase 2 之前收手命令在 Phase 2 规划结束后结束。需要上报三件事当前分支BRANCH、IMPL_PLAN 路径、已生成的设计产物清单。规划到此为止——任务拆分tasks.md不在本技能职责内。4.5 上报后检查 after_plan 钩子遵循与 before_plan 完全相同的判定规则enabled 过滤、condition 不解释、点号转连字符、按 optional 区分输出只是把 Pre-Hook 换成 Hook。五、Phase 0Outline ResearchPhase 0 的输入是 Technical Context 中的未知项清单输出是research.md。转换规则非常机械每个NEEDS CLARIFICATION→ 一条研究任务每个依赖项 → 最佳实践任务每个集成点 → 模式调研任务。任务派发模板For each unknown in Technical Context: Task: Research {unknown} for {feature context} For each technology choice: Task: Find best practices for {tech} in {domain}调研结果按固定三元组格式汇总到research.mdDecision: [最终选择]Rationale: [选择理由]Alternatives considered: [评估过的其他方案]这份「决策 理由 备选」格式的价值在于它让技术选型可追溯、可质疑也为后续 PR 评审提供决策档案。仓库 specs/001-migrate-to-pnpm/research.md、specs/002-vitest-browser-migration/research.md 与 specs/003-remix-to-react-router-7/research.md 即是该模板的真实产物。六、Phase 1Design ContractsPhase 1 的前置条件是research.md已完成产出三块内容6.1>specs/003-remix-to-react-router-7/ ├── plan.md # 本命令的输出 ├── spec.md # 功能规格输入 ├── research.md # Phase 0 输出 ├── contenteditable="false">【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考