Skip to content

English · 简体中文

SpecStamp 快速开始

目标：十分钟内完成 SpecStamp 首次体验。

本页的安装和初始化命令在终端中执行，所以统一使用 specstamp。完成 Agent 入口同步后，在 Codex 中使用 $sdlc-*，在 Claude Code 中使用 /sdlc-*。

环境要求

  • macOS 或 Linux 等 POSIX 系统
  • Python 3.10 或更高版本
  • 需要联网安装运行依赖（jsonschema、pypdf）

第一步：安装

方式一：从 PyPI 临时体验（不写全局目录）

python3 -m venv /tmp/specstamp-demo/venv
/tmp/specstamp-demo/venv/bin/pip install specstamp

虚拟环境和示例项目都写在 /tmp/specstamp-demo/ 下，不碰全局目录，也不修改项目源码。

方式二：完整受管安装（会写全局目录）

需要同步 Agent 入口时，克隆仓库并在项目根目录执行：

git clone https://github.com/muyuqingqiu/specstamp.git
cd specstamp

然后执行：

python3 scripts/install_specstamp.py --dry-run-agent-sync
python3 scripts/install_specstamp.py --confirm-agent-sync
export PATH="$HOME/.local/bin:$PATH"
  • --dry-run-agent-sync 只读预览，不写文件。
  • --confirm-agent-sync 会创建仓库内的 .venv，建立 $HOME/.local/bin/specstamp 主入口和 $HOME/.local/bin/codex-sdlc 兼容入口，并同步三套 Agent 入口：
  • $HOME/.codex/skills（Codex 技能）
  • $HOME/.agents/sdlc 和 $HOME/.agents/skills（通用 Agent）
  • $HOME/.claude/commands（Claude Code 命令）

在 Codex 中使用 SpecStamp

在已经初始化的项目中打开 Codex，然后调用同步好的技能：

$sdlc-status
$sdlc-next

在 Claude Code 中使用 SpecStamp

在已经初始化的项目中打开 Claude Code，然后使用同步好的命令：

/sdlc-status
/sdlc-next

这里不要把客户端内的示例写成 specstamp ...：specstamp 是终端 CLI，$sdlc-* 和 /sdlc-* 才是对应客户端里的调用形式。

第二步：初始化一个项目

mkdir -p /tmp/specstamp-demo/project
cd /tmp/specstamp-demo/project
/tmp/specstamp-demo/venv/bin/specstamp init-plain

在 Git 项目里使用 specstamp init。初始化只创建 .codex-sdlc/ 目录和项目辅助文件，不创建需求、不拆任务。

第三步：查看下一步

/tmp/specstamp-demo/venv/bin/specstamp next

specstamp next 会告诉你当前最推荐的下一步。specstamp status 可以查看当前项目状态。

记录第一条需求

需求、讨论结论等业务内容以结构化 JSON 记录，CLI 不直接写自由文本。通常由 AI 助手把对话整理成 JSON，再用命令落盘：

/tmp/specstamp-demo/venv/bin/specstamp discuss --file 需求记录.json

记录中途结论可以使用：

/tmp/specstamp-demo/venv/bin/specstamp capture --file 结论记录.json

验证安装

完整安装后执行：

specstamp --help
specstamp version
specstamp doctor-install

specstamp doctor-install 是只读检查，会核对命令入口、运行依赖和技能来源，有问题时输出中文修复提示。

项目清理

  • 项目内：先用 specstamp clean 预览会清理哪些 SpecStamp 项目数据，确认后执行 specstamp clean-confirm。
  • 全局安装目前没有一键卸载命令。需要移除时，只删除安装器创建的 $HOME/.local/bin/specstamp、$HOME/.local/bin/codex-sdlc 两个入口和受管条目，不要直接删除整个 Codex、通用 Agent 或 Claude Code 目录。

常见失败处理

  • 命令找不到：先执行 export PATH="$HOME/.local/bin:$PATH"。
  • 受管环境缺失：按提示重跑安装脚本。
  • 指定了 CODEX_SDLC_PYTHON 但解释器不可用：先 unset CODEX_SDLC_PYTHON，再重新安装。