Skip to content

English · 简体中文

SpecStamp 使用指南

本页是终端 CLI 使用指南，所以流程示例统一使用主命令 specstamp；使用 /tmp 临时环境时，把 specstamp 换成 /tmp/specstamp-demo/venv/bin/specstamp。在 Codex 中应改用对应的 $sdlc-* 技能，例如使用 $sdlc-next，不要输入 specstamp next；Claude Code 使用 /sdlc-*。codex-sdlc 只作为兼容已有脚本的终端入口继续保留。

新项目接入

specstamp init

在 Git 项目里初始化。非 Git 目录使用 specstamp init-plain。

已有项目接入

  1. 初始化：specstamp init。
  2. 按 specstamp next 的提示创建或确认当前 DRAFT。
  3. 归档旧资料：specstamp material DRAFT-001 --title "需求说明" --type requirement --file 需求说明.md。
  4. 记录讨论结论：specstamp discuss --file 讨论记录.json。

旧需求文档、技术方案、设计稿和截图建议先原样归档，再开始拆需求。归档时保留原始内容和文件哈希。

需求与设计整理

  • specstamp discuss --file 讨论记录.json：追加结构化需求讨论。
  • specstamp capture --file 结论记录.json：记录中途结论。
  • specstamp grill：记录需求、设计、任务规划或任务运行的质询结果。
  • specstamp design：导入技术方案原文引用。
  • specstamp design-summary DRAFT-001 --file design-summary.v1.json：导入总体设计说明。
  • specstamp design-plan DRAFT-001 --file design-plan.v1.json：导入开发设计总计划。
  • specstamp design-artifact DRAFT-001 --file design-artifact.v1.json：导入模块化设计产物。
  • specstamp draft：写入、查看或刷新 DRAFT 工作包。
  • specstamp start --file formal.v3.json：正式建档。

需求、设计等内容使用结构化 JSON 记录，由 AI 助手生成，CLI 负责校验和保存。

任务计划与执行

  • specstamp tasks REQ-001 --plan-file task-plan.v2.json --tasks-dir tasks --coverage-file task-coverage.v1.json：导入任务计划和任务合同。
  • specstamp plan REQ-001：补齐或调整需求任务计划。
  • specstamp plan-add-task REQ-001 "任务标题"：追加任务。
  • specstamp plan-amend-task REQ-001 T-001：修改未完成任务。
  • specstamp plan-reorder REQ-001 T-002,T-001：重排任务顺序。
  • specstamp plan-depends REQ-001 T-003:T-001,T-002：设置任务依赖。
  • specstamp plan-close REQ-001 T-001,T-002：关闭任务。
  • specstamp task REQ-001 T-001：推进任务。
  • specstamp task-read-confirm REQ-001 T-001 --manifest-sha256 <清单哈希>：确认已读取完整任务清单。
  • specstamp task-run-check REQ-001 T-001：复核任务基线和允许修改范围。
  • specstamp task-evidence REQ-001 T-001 --kind test --source-file 测试结果.txt --sha256 <证据哈希> --command "pytest -q" --exit-code 0 --result passed：登记测试或验收证据。
  • specstamp task-done REQ-001 T-001：完成任务并自动验证。
  • specstamp task-restore REQ-001 T-001：按反馈恢复任务。
  • specstamp task-pause REQ-001 T-001：暂停进行中任务。
  • specstamp fix：为已完成任务插入修复任务。
  • specstamp audit：插入已完成任务质量复查任务。
  • specstamp regression REQ-001：执行需求或任务范围回归。

任务完成前必须登记证据：命令、整数退出码、结果、来源文件和 SHA-256 原值。

需求变化

  • specstamp change-plan REQ-001：规划待处理需求变更。
  • specstamp change-create REQ-001 --request-key <稳定请求键>：创建变更工作区。
  • specstamp change-package REQ-001 CHG-001 --package 变更包.json --projected-requirement 预计需求.json --projected-design 预计设计.json --projected-test-matrix 预计测试矩阵.json --projected-reference-index 预计引用索引.json --projected-task-plan 预计任务计划.json：校验并提交完整变更包。
  • specstamp change-protect REQ-001 CHG-001：核对变更审核并保护受影响活动任务。
  • specstamp change-accept REQ-001 CHG-001：确认变更并生成新的生效版本。
  • specstamp review create：创建审核请求；review submit 提交审核结果；review status 读取审核状态。

备份与恢复

  • specstamp backup：备份当前项目或指定需求。
  • specstamp backup-list：查看备份候选。
  • specstamp backup-clean：清理旧备份，保留数量可通过参数控制。
  • specstamp restore --dry-run：只预览恢复计划；specstamp restore --select 列出候选；确认后执行 specstamp restore --confirm。

Agent 入口同步

specstamp agent-sync --dry-run   # 只读预览
specstamp agent-sync --confirm   # 写全局目录
specstamp agent-sync --check     # 只读检查

specstamp agent-sync --confirm 会同步 Codex、通用 Agent 和 Claude Code 三套入口，并清理重复入口。同步前先看 specstamp agent-sync --dry-run 的输出，同步后执行 specstamp agent-sync --check 确认。

同步完成后，按照当前场景使用对应入口：

使用场景 示例
终端 specstamp next
Codex $sdlc-next
Claude Code /sdlc-next

状态、交接与导出

  • specstamp status：查看当前项目状态。
  • specstamp next：查看当前最推荐的下一步。
  • specstamp export：导出当前项目的阶段交付记录。
  • specstamp export-requirement REQ-001：导出指定需求记录。
  • specstamp finish：生成本轮正式交接。
  • specstamp handoff：输出可复制到新会话的交接提示词。
  • specstamp docs REQ-001：生成需求维护文档。
  • specstamp accept REQ-001：确认需求真正结束。

安装体检

  • specstamp doctor：检查安装或项目状态。
  • specstamp doctor-install：检查本机安装情况。
  • specstamp doctor-repair：重建 SQLite 和 Markdown 快照。
  • specstamp doctor-deep：深度体检，只读检查人工改动、备份和代码图谱状态。