日常工作知识库

Appearance

💡 SpecFlow 命令行 (CLI) 与 AI 技能模式深度对比与最佳工程实践 ​

知识库归档：site/ai/specflow-cli-vs-ai-skills.md
适用对象：58 业财产研架构组、前端/后端 AI 辅助开发工程师、CI/CD 运维团队

📌 一、 核心架构边界与角色定位 ​

SpecFlow 提供了 命令行工具链 (@specflow/cli) 与 AI 技能库 (/specflow-*) 两层交付体系。二者在不同运行模式下的物理能力与定位如下：

⚖️ 二、 执行模式三维对比矩阵 ​

维度对比场景 A：Terminal 命令行单独敲 CLI 命令场景 B：AI 会话中敲 CLI 命令 (如 specflow task)场景 C：AI 会话中敲 Slash 技能 (如 /specflow-task)
物理执行者纯静态 Node.js CLI 进程 (无 LLM)AI Agent 智能体 + CLI 脚手架AI Agent 智能体 + CLI 脚手架
Reasoning 推理❌ 无 (走静态正则与模版)✅ 具备大模型深度 Reasoning✅ 具备大模型深度 Reasoning
源码改写能力❌ 仅探查文件，若 Diff=0 触发死门禁拦截✅ 物理改写真实源码 (replace_file_content)✅ 物理改写真实源码 (replace_file_content)
规范锁仓与 MR❌ 业务源码未改动时绝对阻断发 MR✅ 物理双仓 Commit 锁仓并发起真实 MR✅ 物理双仓 Commit 锁仓并发起真实 MR
推荐适用场景CI/CD 流水线门禁 / 快速拉取美事草稿AI 交互式研发 / 命令行驱动物理编码AI 交互式研发 / Slash 快捷技能驱动

❓ 三、 核心 FAQ 疑难解答 ​

Q1: 在本地 Terminal 敲 CLI 只是一个静态检测器与门禁拦截盘，要实现代码物理重构必须依赖技能吗？ ​

答：是的，完全正确！ 在终端 Shell 中直接执行的 specflow 命令是没有接入 LLM 大语言模型的静态 Node.js 脚本。它在 P3 阶段无法像 AI Agent 那样具备推理能力去修改复杂的 Vue/Java 业务源码。其核心职责在于：

  1. 项目规范仓脚手架建站 (init)；
  2. 美事在线文档拉取与标准化规格归档 (specify)；
  3. CodeGraph 关系图谱提取与 Spec-Kit 防伪产物生成 (plan)；
  4. CI/CD 静态代码门禁审计、覆盖率校验与双表归档 (review/report)；
  5. 物理死门禁：检测到业务仓代码 Diff === 0 时硬阻断，阻止发 API 创建废单 MR。

Q2: 如果在当前 AI 会话中执行 CLI 命令（如 specflow task），能达到跟执行 /specflow-task 技能一样的效果吗？ ​

答：在 AI 会话中能达到 100% 完全相同的高质量物理落地效果！ 在 AI 会话（如 Antigravity / Claude Code / Cursor / Trae）中，当您输入 specflow task 或敲击 /specflow-task 时：

  1. CLI 担当脚手架与探针：AI Agent 调用 CLI 提取受影响物理文件（如 src/components/bursement/annex.vue）、内部方法名及 AST 上下文；
  2. AI Agent 担当推理与物理编码主体：AI Agent 触发 Reasoning 思考能力，分析源码结构，物理调用 replace_file_content 代码编辑工具将前置拦截逻辑写入到真实业务代码中；
  3. CLI 担当锁仓与 MR 提交器：编码完成后，AI Agent 再次联动 CLI 执行物理双仓 Commit 锁仓并成功在 iGit 发起真实包含代码变更的 MR。

🚀 四、 最佳工程实践指南 (Best Engineering Practices) ​

  1. 终端 (Shell Terminal) 最佳实践：

    • 适合用于初始化项目规范 (specflow init --anchor-path ./reimburse-pc)；
    • 适合用于快速将美事在线文档拉取并转换成 SDD 5 维草稿 (specflow specify --doc-url ...)；
    • 适合作为 CI/CD 自动化门禁流水线进行质量审计与数据归档 (specflow report)。

  2. AI 会话 (IDE Agent Session) 最佳实践：

    • 全面使用 AI 技能/命令完成研发：无论是敲 CLI 命令还是用 /specflow-* 快捷指令，均可全自动化完成 5 维契约定义 -> research.md 防伪技术调研 -> data-model.md 实体流设计 -> 真实业务代码修改 -> iGit 物理 MR 提交 的全闭环工程。