Spec Kit 实战 07 · 反模式与故障排查

上一章：团队协作与规格维护 | 返回索引 | 下一章：检查清单与资料来源

阅读指南 出问题的时候，先分清是流程坏了还是工具坏了。前半章是流程反模式：薄 spec、AI 自批 checklist、把生成速度当交付速度；后半章按症状排查工具问题。建议当地图用，出事再来翻。

1. 流程反模式

一句话 Specify 后直接 Implement

症状： Spec 只有功能名，Plan 只有 “Execute”，运行时才发现权限、并发、CORS、迁移或数据流问题。

原因： 把本应在 Clarify/Plan/Analyze 暴露的问题推迟到代码。

修正： 补角色、边界、验收、技术约束和验证；对生产功能运行 Analyze。

【社区实践】NASA Hermes Go/React brownfield 案例明确记录了薄 spec、无指导 plan、跳过 analyze 后出现的 CORS 和数据验证问题。

Specification 写满技术方案

症状： 用户故事变成“使用 Redis、Kafka、微服务实现借书”。

原因： what/why 与 how 无法独立评审，换方案会错误地看成需求变化。

修正： Spec 保留用户可见结果和约束；技术栈、依赖、目录放 Plan/Research。

AI 自己批准 Checklist

症状： AI 生成 checklist，马上把所有项勾为 [x]，然后开始编码。

原因： 生成者兼任批准者，质量 gate 失效。

修正： 自定义 checklist 由 reviewer 所有；缺口回写 Spec/Clarify，而不是在 checklist 里解释掉。

Tasks 按文件而非价值组织

症状： 先建全部 model，再建全部 service，几周后才有第一个可验收故事。

原因： 失去独立 MVP 和 story checkpoint。

修正： 按 Setup、Foundational、每个用户故事、Polish 组织。每个 story 有独立测试。

把 [P] 当无限并行许可

症状： 多个 agent 同时修改同一 route/schema/test 文件。

原因： 忽略 [P] 的“不同文件、无未完成依赖”前提。

修正： 同文件指定 owner 或串行；共享 contract/schema 先合并。

Brownfield 新建平行架构

症状： 博客已有 xxl-job 每分钟任务，Plan 又引入 Redis 队列和第二套调度服务。

原因： 没有先读取现有代码，或用“可扩展”包装无证据设计。

修正： Plan 明确真实入口、复用点和新增依赖证明；没有可测限制就复用现有能力。

把生成速度当交付速度

症状： AI 生成代码后就宣布“完成”，回归、迁移、真实环境和人工验收都没做。

原因： 混淆 implemented、tested、accepted、deployed、online-verified。

修正： 每个状态分别记录证据。

【社区实践】OrangeLoops 案例报告约两小时生成 195 个任务对应代码，但测试、集成修复、数据准备、评审和稳定化持续四天。该数字是作者自报，不是通用基准。

OpenSpec 反模式

症状： delta 复制了整份现行 spec，而不是只写 ADDED/MODIFIED/REMOVED 差异。

原因： 不理解 delta 的评审价值——差异可见才可评审。

修正： 只声明变化的部分；MODIFIED 重写该条 Requirement 的完整正文，其余条目不出现。

症状： MODIFIED 引用的 Requirement 名与现行规格对不上，openspec validate --strict 失败。

原因： 手写未对照主 specs，或主规格已由其他变更改名。

修正： 改 change 的 delta 迁就现行规格（或先归档改名的那个变更），不要反向修改 specs 来凑提案。

症状： 表名、mapper、XML 写进了 spec 或 delta。

原因： 混淆行为契约与技术方案。

修正： 实现细节移入 change 的 design.md；spec 只保留外部可见行为。

症状： 零行为变化的纯重构 change 无法通过校验。

原因： 工具默认变更应携带规格差异。

修正： 确认确实无行为变化后，在 change 目录 .openspec.yaml 声明 skip_specs: true。

症状： tasks 未勾完就归档，或 changes/ 里堆积大量长期不归档的提案。

原因： 把提案当文档堆放处，归档动作被跳过。

修正： openspec validate --archived 加入 CI 作为门禁；归档应当与实现 PR 同批完成，changes/ 像 PR 队列一样保持短。

2. 工具故障排查

specify 找不到

1command -v specify
2uv tool list
3specify version

检查 uv tool/pipx bin 是否进入 PATH。不要用“能看到 Python 包”替代可执行文件验证。

openspec 找不到或归档在 CI 中止

1command -v openspec
2node --version

openspec 找不到多为 npm 全局 bin 不在 PATH 或 Node 低于 20.19.0，安装与排查看第 2 章常见错误表。CI、agent 等无终端环境执行 openspec archive 时必须带 --yes，否则归档在任何改动前停止并以非 0 退出——这是设计行为，不是故障。

初始化在 CI/agent harness 卡住

1specify init my-project --integration codex --non-interactive

必要时使用 --ignore-agent-tools 跳过 agent CLI 检查；这不会替你验证 agent 真实可用。

已有仓库初始化可能覆盖文件

先建立可回滚基线：

1git status --short
2git add -A && git commit -m "20260910_personal-blog_specKitBaseline"
3specify init --here --force --integration codex --non-interactive
4git diff --stat

--force 只应在明确知道目标目录和冲突路径后使用。

Agent 中没有 Spec Kit 命令

1specify integration list
2specify version --features

检查初始化选择的 integration 和 agent 的实际命令目录。不同 agent 可能使用 /speckit-*、$speckit-* 或 /skill:speckit-*。

Plan/Tasks 找不到当前 feature

1cat .specify/feature.json
2echo "$SPECIFY_FEATURE_DIRECTORY"

【版本相关】v1.0.5 通过 feature 指针/环境变量解析，不要只 checkout 分支。

Kiro 收到字面 $ARGUMENTS

来源：Issue 1926，2026-03-20 创建、当前已关闭，访问 2026-09-09。

Kiro 文件 prompt 当时不支持参数替换。应以当前 integrations 文档提供的 Kiro 兼容行为为准，不要复制旧 workaround 到所有 agent。

Preset composition 报 PyYAML 缺失

来源：Issue 4443，2026-09-04 创建、访问时仍开放。

问题场景是隔离安装中的 CLI 环境有 PyYAML，但生成脚本选到另一个系统 Python。检查实际解释器和项目 venv；不要仅因为 specify preset resolve 可用就认定脚本路径也可用。

Windows HTTPS 报 OPENSSL_Applink

来源：Issue 4433，2026-09-03 创建、访问时仍开放。

该问题与 Windows 进程 PATH 中 OpenSSL DLL 冲突有关。记录 Windows、Python、uv、PATH 和命令，在干净环境复现并跟踪上游。不要通过关闭 TLS 验证绕过。

Constitution 越来越长

来源：Issue 4431，2026-09-03 创建、访问时仍开放。

重复运行可能累积 Sync Impact Report。维护者评论将其描述为提交前人工审阅的临时材料。提交前删除历史报告，避免后续 agent 每次读取无用上下文。

Tasks 丢失字段约束

来源：PR 4430，2026-09-08 已合并。

该修复要求 tasks 从 data-model.md 原样携带长度、nullable、enum 和校验规则。

【版本相关】PR 4430 已进入 v1.0.5 Release notes；v1.0.4 早于该 PR 合并，不能把两版行为混用。使用 v1.0.4 时人工检查 tasks.md，使用 v1.0.5 时升级后重新生成并审查任务。

Analyze 报告问题后不知改哪里

修完源头后重跑 Analyze，不要只在报告旁加备注。

3. 适用与不适用

适用

• 多用户故事或跨模块 feature；
• 数据迁移、外部 contract、安全/合规要求；
• Brownfield 的有界新增或现代化；
• 多人/多 agent 需要共享可恢复上下文；
• 工作会跨会话、跨工具或跨团队交接；
• 同一需求需要比较不同技术实现。

应走轻量路径

• 拼写、单行配置、机械重命名；
• 一次性小脚本；
• 需求明确且变更面极小的 bug；
• 还没有稳定问题定义的探索，应先 discovery/assessment；
• 团队无人能确认业务、架构和测试，却期望全自动交付；
• 要求形式化证明：Markdown + LLM guardrail 不是形式化验证。

【社区实践】Matsen 的实践文章认为大型 feature/迁移适合完整 Spec Kit，而普通增量常使用受 Spec Kit 启发的轻量 issue flow。这是个人实践，不是官方规则。

本章完成检查清单

• 能区分流程缺陷与工具安装问题。
• 遇到 Analyze 问题会回到正确源工件。
• 不把未合并 Issue/PR 的方案写成当前正式行为。
• 知道 PR 4430 已包含在 v1.0.5，而不是 v1.0.4。
• 小变更不会机械套用完整流程。

下一章：检查清单与资料来源