SillySpec

Appearance

故障排查 ​

安装类 ​

Claude Code 找不到 /sillyspec 命令 ​

症状： 输入 /sillyspec:init 提示命令不存在。

解决方案：

  1. 确认 Claude Code 版本 ≥ 1.0.0：

    bash
    claude --version

  2. 确认 SillySpec 已正确安装到 Claude Code 的 slash commands 目录：

    bash
    ls ~/.claude/commands/sillyspec/

    应该看到 14 个 .md 文件。

  3. 如果命令目录不对，重新创建符号链接或复制文件。

安装后命令不生效 ​

解决方案： 重启 Claude Code 会话。Slash commands 在启动时加载。

运行类 ​

"No HANDOFF file found" ​

症状： 执行 /sillyspec:continue 或 /sillyspec:status 时报错。

解决方案：

  • 新项目需要先执行 /sillyspec:init 或 /sillyspec:scan。
  • 如果是恢复工作，执行 /sillyspec:resume。

Subagent 执行超时 ​

症状： /sillyspec:execute 中某个子任务长时间无响应。

解决方案：

  1. 使用 /sillyspec:status 查看当前进度。
  2. 使用 /sillyspec:state 保存当前状态。
  3. 重新启动 Claude Code 会话后 /sillyspec:resume。

规范文件格式错误 ​

症状： /sillyspec:propose 或 /sillyspec:plan 生成的文件无法被后续命令识别。

解决方案： 确认 .sillyspec/ 目录结构完整：

.sillyspec/
├── HANDOFF
├── specs/
│   └── <name>/
│       ├── proposal.md
│       ├── design.md
│       └── tasks.md

网络类 ​

API 调用失败 ​

症状： Claude Code 提示网络错误或 API rate limit。

解决方案：

  1. 检查网络连接：

    bash
    curl -s https://api.anthropic.com/health

  2. 如果使用代理，确认代理配置：

    bash
    echo $HTTPS_PROXY
echo $HTTP_PROXY

  3. Anthropic API 有速率限制，大量并行 subagent 可能触发。减少并发或等待重试。

智谱 GLM 配置 ​

使用智谱 GLM 作为后端模型 ​

SillySpec 默认配合 Claude Code（Anthropic）使用。如果想搭配智谱 GLM：

  1. 配置 API Key：

    bash
    export ZHIPUAI_API_KEY="your-api-key"

  2. 注意模型差异： GLM 模型的上下文窗口和指令跟随能力与 Claude 不同，复杂 prompt 可能需要调整。

  3. 建议： 如果遇到模型理解偏差，检查 prompt 中是否有 Claude 特有的指令格式，适当简化。

Git 相关 ​

规范文件未被 Git 跟踪 ​

解决方案： 确保 .sillyspec/ 不在 .gitignore 中：

bash
# 移除 .gitignore 中的 .sillyspec 条目（如果有）
git add .sillyspec/
git commit -m "chore: add sillyspec spec files"

分支管理 ​

SillySpec 生成的规范建议放在独立分支上，与主开发流程解耦：

bash
# 创建规范分支
git checkout -b spec/<feature-name>

# 规范确认后合并到开发分支
git checkout main
git merge spec/<feature-name>