上一章：认识 Spec Kit | 返回索引 | 下一章：图书管理系统实战
阅读指南 工具装对，后面的章节才能跟着动手。这一章装两套 CLI，分别初始化新项目（图书系统）和已有项目（博客）。博客初始化前先打可回滚基线，这是 brownfield 的第一条安全带。OpenSpec 也在本章装好，先在图书系统上就位。
场景与目标
这一章处理两件事。图书系统从空目录开始，要装固定版本、初始化 Codex 集成；博客已经有代码，得先拿到可审查的基线，否则 --force 覆盖了受管理文件，你都没法判断改了什么。
CLI 装两套。先装 Spec Kit（Python CLI）完成上面两个初始化，再装 OpenSpec（npm CLI，要求 Node.js 20.19+）并初始化图书系统。两者的目录互不冲突，specs/、.specify/ 和 openspec/ 各管各的；博客的 OpenSpec 初始化推迟到第 5 章试点收尾再做。
环境要求
【官方能力】【版本相关】v1.0.5 文档列出的基础要求：
- Python 3.11+；
uv（推荐）或pipx；- 一个受支持的 AI coding agent；
- Git 仅在启用 git 扩展时需要。
安装固定版本
1uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.5
2specify version
3specify check期望 specify version 报告 CLI 1.0.5。specify check 检查 CLI 型 agent；IDE 型 agent 可能被跳过，这不等于初始化失败。
PyPI 路径：
1uv tool install specify-cli==1.0.5
2# 或
3pipx install specify-cli==1.0.5【社区实践】团队应在 onboarding 或 tool version 文件中记录安装方式和版本。直接跟随 main 会使模板、命令和生成行为在成员之间漂移。
新项目：初始化图书系统
开始前状态
1workspace/
2└── （尚无 library-system/）命令
1specify init library-system --integration codex --non-interactive
2cd library-system如果希望显式选择脚本实现：
1specify init library-system --integration codex --script sh --non-interactive--script 可选 sh、ps、py。macOS/Linux 默认适合 sh，Windows 常用 ps。
初始化后状态
具体 agent 目录随集成变化。Codex skills 集成的典型结构：
1library-system/
2├── .specify/
3│ ├── memory/constitution.md
4│ ├── templates/
5│ ├── scripts/bash/ # 本例 macOS 默认 sh 变体
6│ ├── integration.json
7│ └── .gitignore
8└── .agents/skills/
9 ├── speckit-constitution/
10 ├── speckit-specify/
11 ├── speckit-plan/
12 └── ...【版本相关】不要照抄目录判断成功。运行：
1specify integration list
2specify version --features并在 agent 中确认实际命令。Codex 通常使用 $speckit-*；本文后续仍写官方规范形式 /speckit.*。
可选：启用 Git 工作流
1specify extension add git【官方能力】该扩展可以初始化 Git、创建编号/时间戳 feature 分支、校验分支和按配置自动提交。默认 auto-commit 关闭。
【人工决策】是否启用由团队决定。没有 Git 时，核心 specs/ 工件仍可创建。
已有项目：初始化个人博客
开始前状态
1personal-blog/
2├── src/main/java/com/example/blog/
3│ ├── controller/
4│ ├── service/
5│ ├── mapper/
6│ └── job/
7├── src/main/resources/
8│ ├── mapper/
9│ └── db/ddl/
10├── src/test/java/com/example/blog/
11└── pom.xml先确认仓库可回滚（commit 命名沿用项目 日期_项目_事项 风格）：
1cd personal-blog
2git status --short
3git add -A
4git commit -m "20260910_personal-blog_specKitBaseline"再初始化：
1specify init --here --force --integration codex --non-interactive
2git status --short
3git diff --stat【官方能力】--here 在当前目录初始化；非空目录需要 --force。它会添加 .specify/ 与 agent 集成文件，不会推断现有业务规格，也不会重写整个应用。
人工评审初始化 diff
逐项确认：
- 只新增预期的
.specify/和 agent 集成文件； - 现有 README、CI、agent 配置是否发生冲突；
.specify/memory/constitution.md当前只是待完善的共享项目文件；- 现有应用代码与测试未被改动。
安装 OpenSpec 并初始化图书系统
【版本相关】OpenSpec 基线：@fission-ai/openspec 1.13.0（2026-09-10 确认）。它用一份现行能力规格（openspec/specs/）加变更提案（openspec/changes/）管理需求的长期演进；本资料在第 3 章的交付收尾和第 5 章的老项目接入中会实际使用它。
安装
1node --version # 需 20.19.0 及以上
2npm install -g @fission-ai/openspec@latest
3openspec --version与 specify 一样：固定团队版本，把安装方式记进 onboarding 文档，避免跟随 latest 漂移。
新项目：初始化 library-system
1cd library-system
2openspec init --tools codex【官方能力】init 是交互式命令；--tools 显式指定 AI 工具（claude、codex、cursor 等，逗号分隔，all 全装）。初始化后的目录与 Spec Kit 共存：
1library-system/
2├── .specify/ # Spec Kit 基础设施
3├── .agents/skills/ # Spec Kit 命令（speckit-*）
4├── openspec/
5│ ├── specs/ # 现行能力规格（当前为空）
6│ ├── changes/ # 变更提案（当前为空）
7│ └── config.yaml # profile 与 workflow 配置
8└── ... # 工具命令目录（/opsx:* 说明文件）逐项确认（沿用 brownfield 的 diff 审查习惯）：
- 只新增
openspec/与工具命令目录，.specify/、specs/未被触碰； - agent 中出现
/opsx:*命令（Codex 显示为$openspec-*），与$speckit-*并存； openspec list可运行（此时应显示无进行中的变更）。
已有项目何时引入
personal-blog 这一步先不初始化 OpenSpec：第 4 章的增量练习仍用 Spec Kit，等第 5 章的标签筛选试点稳定收尾，再在那一章的末尾引入。先让试点证明价值，再上工具——和本章开头"先有可回滚基线再 --force"是同一个顺序。
常见错误、原因与修正
| 症状 | 原因 | 修正 |
|---|---|---|
openspec: command not found | npm 全局 bin 不在 PATH | 修复 PATH 后 openspec --version 验证 |
| 安装报引擎版本不符 | Node 低于 20.19.0 | 升级 Node 后重装 |
| init 卡在交互选择 | 未显式 --tools | 脚本场景显式 --tools codex |
| 担心覆盖 Spec Kit 文件 | 误以为两工具冲突 | diff 审查：init 只新增 openspec/ 与工具命令目录 |
Monorepo 与 feature 定位
先说清楚这一节解决什么问题。前面所有命令都有一个隐含前提：你在项目根目录执行，仓库里只有一个 .specify/。本书三个案例都是这样，所以这节可以暂时跳过，等遇到下面的情况再回来。
monorepo 打破了这个前提。假设当初把图书系统和博客放进同一个仓库：
1my-workspace/
2├── apps/
3│ ├── library-api/ # 各自跑过 specify init，各有 .specify/
4│ └── blog-api/ # 同上
5└── specs/ # library-api 的 feature 目录也可能在子项目内这时你在仓库根目录敲 specify integration list，工具面对两个 .specify/，不知道该听谁的。要让它干活，得先回答两个问题：操作哪个项目？做哪个 feature？ 两个问题各有各的开关。
定位项目：SPECIFY_INIT_DIR
从 monorepo 根执行命令时，用它指明 .specify/ 在哪个子目录：
1cd my-workspace
2export SPECIFY_INIT_DIR=apps/library-api
3specify integration list # 现在操作的是 library-api 这一个项目不设置时默认用当前目录。单项目仓库用不上它。
定位 feature：SPECIFY_FEATURE_DIRECTORY
一个项目里也可能同时开着多个 feature（specs/001、specs/002 并行开发）。默认的活动 feature 记录在项目内的 .specify/feature.json 里；环境变量是临时覆盖它的方式：
1export SPECIFY_FEATURE_DIRECTORY=specs/001-library-circulation【官方能力】两个变量各管一层：SPECIFY_INIT_DIR 回答"哪个项目"，SPECIFY_FEATURE_DIRECTORY 回答"这个项目里的哪个 feature"。设置了一个不代表设置了另一个。另外和第 1 章说过的一样，活动 feature 不跟随 Git 分支——切了分支不代表换了 feature。
命令报"找不到 feature"或作用到错误项目时的排查，见本章末尾的常见错误表。
常见错误、原因与修正
| 症状 | 原因 | 修正 |
|---|---|---|
specify: command not found | uv tool/pipx bin 不在 PATH | 修复 PATH 后运行 specify version |
| CI 卡住 | 初始化进入交互选择器 | 显式传 --non-interactive --integration codex |
| Agent 中没有命令 | 选错 integration 或工具布局不同 | 查看 specify integration list 和实际 agent 目录 |
plan 找不到 feature | 活动 feature 指针不对 | 检查 .specify/feature.json 或设置 SPECIFY_FEATURE_DIRECTORY |
| Brownfield 初始化后不知改了什么 | 无干净基线 | 回到安全基线，重新初始化并审查 diff |
| 以为 checkout 会切换 feature | 当前版本不以分支为唯一依据 | 更新 feature 指针或环境变量 |
本章完成检查清单
-
specify version显示团队约定版本。 -
specify check与specify integration list已执行。 - 图书系统已初始化，agent 能看到 Spec Kit 命令/skills。
- 博客初始化前有可回滚提交，初始化 diff 已人工审查。
- 已决定是否启用 git 扩展。
- 知道活动 feature 的实际解析方式。
-
openspec --version显示团队约定版本，library-system 的openspec/已初始化且与 Spec Kit 目录共存。