CC Workflow Studio 实现计划模板 plan-template.md 深度解析：Spec 驱动开发中的技术决策与结构设计

AI 应用Agent 工作流开发工具MCP 服务【免费下载链接】cc-wf-studioCC Workflow Studio项目地址https://gitcode.com/gh_mirrors/cc/cc-wf-studio点击查看免费下载plan-template.md是 CC Workflow Studio 仓库内 Spec 驱动开发Spec-Driven Development流程的核心产物模板它承接功能规格书spec.md与探索报告research.md把「要做什么」翻译成「怎么做、用什么技术、怎么组织代码、怎么守住质量底线」的可执行实施计划。本文以 plan-template.md 为骨架结合仓库内真实生成案例 001-cc-wf-studio/plan.md 与配套脚本完整讲解模板每个字段的填写方式、宪章五原则的门禁机制以及计划文档如何驱动后续任务分解与工程落地读完即可在自己的功能分支上独立产出一份高质量实现计划。一、实现计划在 Spec 驱动开发流程中的位置在 CC Workflow Studio 中每个功能特性都在specs/[###-feature-name]/目录下沉淀一套文档其标准产出关系如下见 plan-template.md 的「项目结构」小节specs/[###-feature]/ ├── plan.md # 本文件由 /speckit.plan 命令产出 ├── research.md # Phase 0 产出技术调研由 /speckit.plan 命令产出 ├──># Implementation Plan: CC Workflow Studio **Branch**: 001-cc-wf-studio | **Date**: 2025-11-01 **Input**: Feature specification from /specs/001-cc-wf-studio/spec.md and user requirement: webviewはReact with typescript で作成してviteでビルドする形で実装したい注意这里的输入不只包含规格书路径还把用户的关键技术约束「Webview 用 React TypeScript Vite 实现」原样保留——这正是实现计划区别于规格书的地方规格书只讲「做什么」计划必须把「怎么做」的用户意图显式固化下来。三、概要Summary从规格书到技术方案的浓缩「概要」小节要求从功能规格书提取两件事主要需求与来自调研的技术方案。它通常用 24 句话讲清楚三块内容这个功能解决什么问题产品视角采用什么技术栈与架构技术视角数据如何存储、如何对外输出实现视角。真实案例的填写堪称范本作为 VSCode 扩展开发一个以可视化编辑器设计、管理「Claude Code 的 SlashCommands Sub-Agent 组合工作流」的工具。用户可像 AWS Step Functions 那样拖放节点并将其导出为可执行的.claude配置文件Sub-Agent 配置、SlashCommand。技术方案Webview 用 React TypeScript Vite 实现画布用 React Flow工作流定义以 JSON 保存于.vscode/workflows/导出时以 Markdown 输出到.claude/agents/与.claude/commands/。这段概要已经隐含了后续所有技术决策的锚点UI 形态Webview、编辑器引擎React Flow、存储位置本地文件系统、导出目标Claude 配置格式可以被读者、评审者、以及后续的 LLM Agent 直接引用无需再翻回冗长的规格书。四、技术上下文Technical Context一张可执行的决策清单这是模板信息密度最高的部分通过一组「键: 值」字段把技术方案的每个维度钉死。模板给出的字段与填写指引如下字段含义填写示例言語/バージョン编程语言与版本TypeScript 5.x (VSCode Extension Host), React 18.x (Webview UI)主要な依存関係核心依赖库VSCode Extension API 1.80, React Flow, Zustand, Vite 5ストレージ数据存储方案本地文件系统 (.vscode/workflows/*.json)テスト测试框架与分层vscode/test-cli Mocha、Vitest RTL、WebdriverIOターゲットプラットフォーム目标平台VSCode 1.80 (Windows/Mac/Linux)プロジェクトタイプ工程类型single / web / mobile决定源码结构パフォーマンス目標性能指标UI 操作响应 500ms、50 节点流畅渲染制約约束条件postMessage 通信、仅支持本地环境規模/スコープ规模与范围单工作流最大 50 节点、2 种节点类型模板注释明确要求本节内容必须替换为项目真实的技术细节不能保留占位符对于尚未确认的项必须显式标注NEEDS CLARIFICATION由后续research.md的 Phase 0 调研来回答。仓库真实案例 001-cc-wf-studio/plan.md 逐项填写如下可作为最佳实践参考Language/Version: TypeScript 5.x (VSCode Extension Host), React 18.x (Webview UI) Primary Dependencies: Extension: VSCode Extension API 1.80, Node.js 18 Webview: React 18, Vite 5, React Flow, Zustand (状态管理) Storage: 本地文件系统 (.vscode/workflows/*.json, .claude/agents/*.md, .claude/commands/*.md) Code Quality: Biome (ESLint Prettier 替代品, Rust 高速实现) Testing: Extension: vscode/test-cli Mocha Webview: Vitest React Testing Library E2E: WebdriverIO wdio-vscode-service Target Platform: VSCode 1.80 (Windows/Mac/Linux) Project Type: VSCode 扩展 (Extension Host Webview 架构) Performance Goals: UI 操作响应 500ms (NFR-007); 50 节点流畅 (NFR-001); 工作流定义加载 1秒 (10KB 以下, NFR-002) Constraints: 遵循 VSCode Extension API 约束; Webview 通信基于 postMessage; 仅本地支持 (NFR-003) Scale/Scope: 单工作流最大 50 节点; 多工作流并发管理; 2 种节点类型 (Sub-Agent、AskUserQuestion)值得注意的细节性能指标直接引用了规格书中的 NFR 编号如 NFR-007、NFR-001、NFR-002实现了「规格书 → 计划 → 验收」的可追溯闭环。这里的调研结论如选用 Zustand 的理由、React Flow 内部状态管理都能在 research.md 中找到支撑——该调研报告记录了 Zustand 相比 Redux Toolkit、Jotai、Context API 的取舍过程这正是「技术上下文 Phase 0 调研」组合的价值所在。五、Constitution Check宪章五原则的门禁闸口Constitution Check 是模板中最具「工程治理」色彩的环节。模板注释给出两道时间闸门Phase 0 调研之前必须通过Phase 1 设计完成后要复检。它要求对照仓库根目录的 constitution.mdCC-WF-Studio Constitution v1.0.0逐条勾选确认。宪章五原则及其在计划模板中的检查项如下原则计划阶段的检查要点I. 代码质量可读性与文档化、命名规则、复杂度是否可控II. 测试驱动开发是否规划测试先行、契约/集成/单元测试分层、覆盖率 ≥ 80% 目标III. UX 一致性统一 UI 模式、错误信息清晰、无障碍a11y考量IV. 性能基准API p95 200ms或说明 N/A、数据库优化、前端加载目标V. 可维护性与可扩展性模块化与松耦合、配置管理、语义化版本策略真实案例 001-cc-wf-studio/plan.md 的填写展示了「每条勾选都附带具体落点」的正确姿势例如代码质量TypeScript 类型自我文档化、公共函数强制 JSDoc/TSDoc、循环复杂度 10、组件 props 不超过 5 个TDD用户故事 → 测试用例 → 实现的顺序契约测试用 VSCode API 模拟、集成测试覆盖 Extension↔Webview 通信与文件 I/O、单元测试聚焦工作流转换与校验覆盖率最低 80%导出与文件生成等关键逻辑 100%UX采用 VSCode Webview UI Toolkit、AWS Step Functions 风格设计、键盘操作Tab/Enter/Arrow与 ARIA 角色标注性能说明本地文件 I/O 不适用 API p95 指标N/A同时把 Webview 初始化 3 秒、工作流加载 1 秒、React Flow 虚拟化支撑 50 节点等目标写实可维护性Extension Host命令注册/文件操作、WebviewUI、Domain Logic工作流转换/校验三层分离常量集中到constants.ts版本用 Semantic Versioning。模板特别约定如果某项违反宪章例如不得不引入第四个工程或 Repository 模式必须在末尾的「复杂度追踪」表中记录理由——这是宪章「复杂性的正当化」条款见 constitution.md 的「コードレビュープロセス」章节在计划文档中的落点。六、项目结构Project Structure把抽象方案落成目录计划必须给出可执行的目录规划模板将其拆成两个部分。6.1 文档结构本功能的文档产出即本文第一节展示的specs/[###-feature]/目录树它界定了plan.md、research.md、data-model.md、quickstart.md、contracts/、tasks.md各自的角色与产出命令防止文档缺位或职责混淆。6.2 源代码结构仓库根下的三种可选布局模板提供了三种工程形态的目录模板并要求「删除未使用的选项、用真实路径展开、不要把选项标签带进最终计划」# 选项 1: 单工程默认 src/{models, services, cli, lib}/ tests/{contract, integration, unit}/ # 选项 2: Web 应用检测到 frontend backend 时 backend/src/{models, services, api}/ backend/tests/ frontend/src/{components, pages, services}/ frontend/tests/ # 选项 3: 移动端 API检测到 iOS/Android 时 api/同 backend ios/ 或 android/平台特有结构真实案例的选择与展开节选核心骨架src/ ├── extension/ # Extension Host 侧 │ ├── extension.ts # 入口 │ ├── commands/ # open-editor.ts / export-workflow.ts / save-workflow.ts │ ├── services/ # workflow-service.ts / export-service.ts / file-service.ts │ └── models/ # workflow.ts / claude-config.ts ├── webview/ # Webview UI (React Vite) │ ├── src/{main.tsx, components/(WorkflowEditor/NodePalette/PropertyPanel/nodes/canvas), services/(vscode-bridge.ts), types/} │ ├── vite.config.ts │ └── package.json ├── shared/ # 两端共享代码 │ └── types/workflow-definition.ts tests/{extension/(unit, integration, contract), webview/(unit, integration)}最后以「Structure Decision」一句话记录决策依据采用 VSCode 扩展标准结构Extension Host 与 Webview 分离Webview 由 Vite 独立构建后由 Extension Host 加载公共类型统一放shared/供两侧引用。对照当前仓库实际目录packages/vscode/src/extension/、packages/vscode/src/webview/、packages/vscode/src/shared/可以确认这份计划结构最终真实落地——计划文档与最终代码之间保持着高一致性。七、复杂度追踪Complexity Tracking违反宪章的备案簿模板要求仅在 Constitution Check 存在需要正当化的违规时才填写表格形式为违规项需要的理由更简单的替代方案为何被否决例如: 第 4 个工程当前需求为什么 3 个工程不够例如: Repository 模式具体问题为什么直接 DB 访问不够真实案例 001-cc-wf-studio/plan.md 中该表为空并注明「违规正当化无设计满足全部原则」——这是一个健康信号复杂度追踪表是「异常备案」而非「例行公事」留空本身就是经过思考的结论。八、下游链路从 plan.md 到任务清单与脚本支撑实现计划的价值要在下游兑现仓库配套脚本把它固化成流水线创建功能分支与规格create-new-feature.sh 根据功能描述生成分支名自动过滤停用词、截断至 GitHub 的 244 字节限制、自动递增编号如001-feature-name创建specs/[###-feature-name]/spec.md并设置SPECIFY_FEATURE环境变量生成实现计划setup-plan.sh 将 plan-template.md 复制到plan.md同时校验当前必须处于###-feature-name格式的功能分支前置校验check-prerequisites.sh 在进入各阶段前检查plan.md以及可选tasks.md是否齐备并汇总research.md、data-model.md、contracts/、quickstart.md的就绪状态路径约定common.sh 统一提供FEATURE_SPEC、IMPL_PLAN、TASKS、RESEARCH、DATA_MODEL、QUICKSTART、CONTRACTS_DIR等路径变量支持 git 与非 git 仓库两种模式按数字前缀关联同名功能分支与规格目录任务分解tasks-template.md 承接 plan.md 的结构决策与优先级按「Setup → Foundational阻塞所有用户故事→ 按优先级 P1/P2/P3 的每个用户故事 → Polish」划分阶段任务 ID 标注[P]可并行与[Story]所属用户故事保证每个故事可独立实现、独立测试、独立交付 MVP 增量。九、仓库中的真实案例全景与使用建议CC Workflow Studio 仓库的packages/vscode/specs/下沉淀了 9 个功能规格目录如001-cc-wf-studio、001-mcp-node、001-skill-node、001-slack-workflow-sharing等每个目录都包含由本模板生成的plan.md构成了一组宝贵的「模板 × 实例」对照教材。结合模板设计与真实案例可以提炼出以下实践准则规格与实现分离spec.md只描述用户价值与验收标准技术细节全部沉淀到 plan.mdchecklists/requirements.md 中「规格不得包含实现细节」的检查项与之互为印证不确定性显式化技术上下文中未定项一律标记NEEDS CLARIFICATION由 Phase 0 调研research.md在进入设计前闭环指标可追溯性能目标直接引用规格书 NFR 编号让验收有据可依勾选必有落点Constitution Check 的每个勾选都要写出具体落实方式如「props ≤ 5」「覆盖率 ≥ 80%」而非空勾文档产出可执行结构决策必须落到真实目录与命令供 tasks-template.md 直接生成含精确文件路径的任务项。对希望将 Spec 驱动开发引入自己团队的读者建议直接从复制 plan-template.md、spec-template.md、tasks-template.md 与配套 Bash 脚本开始再对照仓库内真实生成的功能目录如 001-cc-wf-studio 的整套文档演练一遍完整流程——这也是本仓库为工程实践提供的最具复用价值的资产。赞分享AI 应用Agent 工作流开发工具MCP 服务【免费下载链接】cc-wf-studioCC Workflow Studio项目地址https://gitcode.com/gh_mirrors/cc/cc-wf-studio点击查看免费下载相关推荐CC Workflow Studio Bugfix PR 模板fix-template.md实战指南Problem/Solution 结构与 Changesets 驱动的修复提交流程CC Workflow Studio Bugfix PR 模板fix template.md实战指南Problem/Solution 结构与 ChangeAI 应用Agent 工作流开发工具MCP 服务CC Workflow Studio AI 工作流精炼数据模型深度解析conversationHistory 设计与实现CC Workflow Studio AI 工作流精炼数据模型深度解析conversationHistory 设计与实现 本篇技术指南以 CC WorkfloAI 应用Agent 工作流开发工具MCP 服务ui-skills 的 improve-ui 设计计划模板plan-template.md深度解析从证据链到可执行交接的完整指南ui skills 的 improve ui 设计计划模板plan template.md深度解析从证据链到可执行交接的完整指南 导读 本文围绕 ui sAI 技能MCP 服务前端上一篇OpenClaw 集成 Voyage AI 记忆嵌入 Provider插件安装、Memory 配置与批量索引原理下一篇Web-Dev-For-Beginners 银行项目实战基于 Node.js 与 Express 的 Bank API 启动、端点解析与前端联调指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考