SillySpec

Appearance

常见问题 ​

安装相关 ​

Claude Code 里看不到 /sillyspec 命令 ​

  1. 确认你在项目根目录下启动了 Claude Code（不是在子目录）
  2. 检查文件结构：ls .claude/commands/sillyspec/ 应该有 14 个 .md 文件
  3. 退出 Claude Code，重新进入项目目录
  4. 如果用了 VS Code 插件，尝试重启 VS Code

init.sh 执行失败 ​

  • 网络问题：curl -I https://github.com 检查连通性，考虑使用代理或 npm 全局安装方式
  • 权限问题：chmod -R 755 .claude/
  • 磁盘空间：df -h 确认有足够空间（SillySpec 本体不到 1MB）

npm install 权限错误 ​

bash
# 推荐方案：用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

使用相关 ​

execute 阶段的 Subagent 是并行还是串行？ ​

默认按依赖关系并行执行没有相互依赖的任务。你可以通过 PLAN.md 中的依赖声明控制并行度。如果不想并行，在 plan 阶段手动调整依赖关系即可。

SillySpec 和原版三个工具（Spec/Wave/Subagent）有什么区别？ ​

SillySpec 不是简单的组合，而是做了深度整合：

  • 命令间自动传递上下文（init 的输出直接作为 brainstorm 的输入）
  • 统一的文档格式和目录结构
  • Token 优化：共享项目上下文，减少重复读取
  • 更友好的中文提示词

棕地项目可以直接走绿地流程吗？ ​

可以，但会跳过对现有代码的分析。如果你的项目已经有一定规模，建议先用 scan 了解现状，否则 AI 可能生成与现有代码风格不一致的代码。

概念相关 ​

什么是 SDD（Spec-Driven Development）？ ​

SDD = 先写规格再写代码。就像 TDD 先写测试一样，SDD 先写需求规格文档，让 AI 和人类在动手前对齐目标。好处是减少返工、减少歧义。

scan 扫描太慢了怎么办？ ​

scan 默认是快速扫描模式，只读配置文件和目录结构，通常几十秒完成。如果之前用过旧版（全量扫描）觉得慢，可以放心使用新版的快扫模式。

如果项目很大，深扫（--deep）确实需要更长时间。建议：

  1. 先用快速扫描了解项目概况
  2. 确定需要深入分析的区域后，用 /sillyspec:scan api --deep 只深扫特定区域
  3. 避免对大型 monorepo 全量深扫

什么是棕地（Brownfield）和绿地（Greenfield）？ ​

  • 绿地：从零开始的新项目，没有历史包袱
  • 棕地：已有代码的项目，需要考虑现有架构和约定

SillySpec 对两种场景有不同的起始流程（init vs scan），后续流程一致。

什么是 Wave？ ​

Wave（波次）= 一个可独立交付的迭代单元。一个大项目被拆成多个 Wave，每个 Wave 产出一组可用的功能。类比敏捷中的 Sprint，但更强调交付的独立性。

什么是 Subagent？ ​

Subagent = Claude Code 派生的子代理。在 execute 阶段，主 Claude 会为每个任务创建一个 Subagent，多个 Subagent 可以并行工作，大幅提升执行效率。

工作区相关 ​

什么是工作区模式？ ​

工作区模式适用于一个仓库包含多个子项目（monorepo）的场景。使用 --workspace 参数初始化后，SillySpec 会在 .sillyspec/config.yaml 中记录所有子项目，支持共享规范文件和跨项目的统一管理。

工作区和单项目模式有什么区别？ ​

  • 单项目：一个 .sillyspec/ 配置，一组规格文档
  • 工作区：顶层 .sillyspec/config.yaml 管理多个子项目，每个子项目有自己的 .sillyspec/，可以共享规范文件

如何从单项目迁移到工作区？ ​

  1. 运行 /sillyspec:workspace，按照引导添加现有项目为子项目
  2. 将需要共享的规范文件移到 .sillyspec/shared/
  3. 对每个子项目单独运行 /sillyspec:scan 或 /sillyspec:init

兼容性 ​

支持什么模型？ ​

SillySpec 依赖 Claude Code，因此支持 Claude Code 支持的所有模型。推荐使用 Claude Sonnet 4 或更高版本以获得最佳效果。

支持什么编辑器？ ​

  • Claude Code CLI（终端）
  • VS Code + Claude Code 插件
  • JetBrains IDE + Claude Code 插件

只要能运行 Claude Code 的环境都可以使用 SillySpec。