G Skills
一套围绕 OpenSpec 的规格驱动开发 skills:把需求讨论、方案生成、设计评审、逐票实现、代码评审、测试验证和归档合并串成可恢复的开发流程。
项目面向使用 Claude Code、Codex 等支持本地 skills 的开发者。本仓库既包含给 AI 阅读的 SKILL.md,也包含负责文件操作、状态判定和格式校验的 Python / Shell 脚本,以及共享规则、模板和测试。
当前执行方式是单人、单会话、串行推进。 需求生成、不同视角的评审和实现都由当前主会话执行;不派发子代理,不做跨模型调用,不配置模型档位或 effort 调度。阶段交界可以清理上下文,但这不等于获得了独立审查者。
日常使用最常见的四个入口是:
/g-init 给目标项目接入工作流
/g-spec 把一次需求做成经过讨论的变更规格
/g-review spec 评审设计,交给用户明确批准
/g-done <change> 按盘面继续实现、评审、验证、归档和合并
g-done 会使用 g-implement 和 g-review code,通常不需要用户逐个手动调用。
目录
- 这套项目解决什么问题
- 第一次使用:从安装到完成一个变更
- 先理解几个概念
- 安装位置、依赖和运行方式
- 所有 skill 的职责与选择
- 主流程如何工作
- 项目级规划与环境 skills
- issues、ADR 与复盘
- 项目会生成哪些文件
- gate 状态机与内容指纹
- 测试配置、证据和 PASS 的边界
- Git、提交和合并行为
- 中断以后怎样恢复
- 脚本诊断与高级用法
- 升级和规则维护
- 常见问题
- 开发本项目与验证改动
- 能力边界与文档导航
1. 这套项目解决什么问题
AI 辅助开发的困难经常发生在步骤之间:需求只存在于对话中,设计没有明确批准,任务勾完却没有真实验收,评审后的修复没有重新测试,或者会话中断后不知道从哪里继续。
gear 把这些衔接点变成文件和判据:
| 常见问题 | 本项目的处理方式 |
|---|---|
| 讨论很长,换会话就丢决策 | decision-memo.md 持续记录承重约束、拍板决策与证据 |
| 一上来生成一堆文档,关键前提没想清 | g-spec 先澄清和拷问,再生成正式产物 |
| 设计评审通过与用户同意混在一起 | 设计报告交人批准,明确批准后才写设计门锚 |
| 实现拆成横向大任务,很晚才能验证 | tickets.md 采用可独立验证的纵向切片,并写出依赖 |
| AI 只凭复选框认为做完了 | gate 以已提交的 checkpoint 完成标签识别进度 |
| 代码改了,旧评审还被认为有效 | 评审、验证报告绑定代码内容指纹,变化后重跑 |
| 报告提交顺手夹带未验证代码 | 代码报告限定提交路径,PASS 写入核对检查前的提交基准 |
| 测试没配,直接被当作不需要测试 | 返回待发现的测试层,要求查项目实际命令或说明未覆盖依据 |
| 历史问题反复建号,来源被覆盖 | issues 保留原始来源,评审台账区分 new 与 reuse |
| 归档只是搬目录,主规格没同步 | 收尾调用 OpenSpec archive,并核验 delta 同步结果 |
| 中断后靠聊天记忆重做 | g-done 重新运行只读 gate,从当前文件和 Git 记录续跑 |
这些机制能提高执行的可追溯性,但不会自动证明需求理解正确、测试充分或评审判断无误。脚本负责可确定的部分,语义判断仍由执行者完成,关键设计由用户拍板。
2. 第一次使用:从安装到完成一个变更
2.1 安装本机工具链
在终端运行:
cd /path/to/gearbox
bash setup.sh
安装脚本会检查依赖并输出 installed、unchanged、skipped 等清单。出现 ready 不代表所有依赖与安装项都成功;需要看清缺失提示和 skipped 的原因。
这里的路径替换成你的实际 checkout。若以后发布自己的远程仓库,可将它 clone 到标准运行位置 ~/.skills/g-skills;本文不假设一个尚未提供的 G Skills 仓库 URL。已有 checkout 按升级说明更新。
2.2 在目标项目中初始化
切到你实际开发的项目,而不是本工具仓:
cd /path/to/your-project
git status --short
openspec --version
如果尚未初始化 OpenSpec,先在该项目运行:
openspec init
然后在 AI 会话里调用:
/g-init
初始化后,需要让执行者根据真实项目补充 openspec/config.yaml 的技术栈、边界与约定。已有配置时保留项目内容,合并通用 context 和 rules;不要用模板整份覆盖原配置。
2.3 给出一项真实需求
例如,在 AI 会话中说:
使用 g-spec,为现有订单列表增加按订单状态筛选的能力。
保持现有分页和权限行为,先核对项目代码与测试约定,再讨论边界。
支持斜杠入口的宿主也可以写:
/g-spec
为现有订单列表增加按订单状态筛选的能力。
AI 会先确认目标、调查现状、验证关键前提,再创建 change 和生成文档。假设本次 change 名为 filter-orders-by-status,后续目录就是:
openspec/changes/filter-orders-by-status/
这里的名称只是示例。实际运行时使用本次生成的准确名称,不要照抄不存在的 change。
2.4 设计评审与明确批准
生成完成后,按出口指引清理上下文,再运行设计审:
/clear
/g-review spec
请评审 filter-orders-by-status。
/clear 是会话操作,不是 shell 命令。宿主没有对应入口时,可以开启新会话并指向同一项目、同一 change;新的会话需要重新读取产物。
阅读 spec-review-report.md,确认范围、关键决策、代价与尚未解决的问题。批准时给出明确指示,例如:
批准 filter-orders-by-status 的当前设计,按报告中的方案执行。
执行者随后写入设计门锚。报告写着“通过”、文件已经生成、用户没有反对,都不能代替明确批准。
2.5 交给 done 连续推进
设计门落盘后,可以再次清理上下文,再调用:
/clear
/g-done filter-orders-by-status
正常情况下,它会连续推进:
出票 → 逐票实现和自审 → 聚合测试 → 最终代码审 → verify
→ hand-off → ADR 同步 → archive → 同步核验 → commit → ff-only merge
它会自动创建流程提交,不会自动 push。遇到真实阻塞会停止并报告原因,不会为了到达完成状态而改写失败结论。
2.6 只归档,暂时不合并
在调用里明确表达:
/g-done filter-orders-by-status
完成验证和归档,先不要合并。
流程使用 .skip-merge 标记保存这个意图。归档与有效验证结论满足条件后,可以正常结束;完成摘要会注明尚未合并。
之后改变主意,可以重新调用:
/g-done filter-orders-by-status
现在把这个已归档的变更合回记录的起始分支。
执行者会读取归档中的分支约定,在未请求合并(merge_target=null)时先确认具体目标;有目标时在归档位置删除并单独提交 .skip-merge,重新运行 gate 后继续合并。仅在工作树删掉标记还不足以恢复流程,因为 gate 读取的是已提交状态。
2.7 什么时候算完成
完成后查看:
- 归档目录中的
verify-report.md:需求逐条核验、证据、缺口与结论。 hand-off.md:详细变更说明,包含完成能力、关键文件、修改前后行为、实现取舍、提交/证据、测试结果、覆盖边界,以及未完成事项与后续建议。openspec/specs/:本次行为变化同步后的正式规格。- Git 记录:流程提交,以及合并结果或明确的 skip-merge 状态。
SHIPPED 在本项目中表示开发流程的归档/合并终态,不表示应用已经部署上线。
3. 先理解几个概念
3.1 三种位置不要混用
| 位置 | 放什么 | 常见例子 |
|---|---|---|
| 工具链 checkout | 本仓源码、skills、模板、测试、安装器 | ~/.skills/g-skills/ |
| 全局安装位置 | 宿主发现的 skills、共享规则入口、辅助脚本 | ~/.agents/skills/、~/.claude/skills/、~/.g/ |
| 消费项目 | 你真正开发的软件、项目配置、变更与报告 | /path/to/your-project/openspec/ |
脚本位于工具链或已安装的 skill 目录中;脚本的 --root 通常指向消费项目根目录。把两者弄反,会让脚本检查或修改错误的仓库。
3.2 术语速查
| 术语 | 在本项目中的含义 |
|---|---|
| skill | 给 AI 的任务入口,核心是 SKILL.md,按需使用 scripts / references / assets |
| change | 一次可交付的变更,活动材料在 openspec/changes/<change>/ |
| 四件套 | proposal.md、specs/、design.md、tasks.md;specs/ 可以包含多份文件 |
| delta spec | 当前 change 对行为规格的新增、修改、移除或重命名 |
| 主 spec | openspec/specs/ 中当前有效的行为契约 |
| decision memo | 拷问后留下的约束、决策、证据和被否方案,承担跨会话传递职责 |
| ticket | 实现管线中的独立验证单元,记录在 tickets.md,不是 issues 台账里的 B/T 项 |
| checkpoint | 用固定 Conventional Commits 格式记录一个流程节点的提交 |
| gate | ship_gate.py 读取文件和 Git 状态后给出的下一步判定 |
| anchor / 锚 | 报告头部 ship-gate 中的结论与内容指纹 |
| canonical 规则 | 全局共享、运行时实际读取的规则源,不是消费仓的人读手册副本 |
| lens / 镜 | 一次检查的视角,例如范围、工程可行性、领域、对抗、接地 |
| hand-off | 交接记录,说明剩余事项、覆盖边界和必要的后续动作 |
| SAD | 项目级系统架构文档,位于 openspec/architecture/sad.md |
| ADR | 有背景、备选、取舍和后果的架构决策记录,位于 openspec/adr/ |
3.3 三层职责
flowchart TD
U[用户目标与明确批准] --> S[SKILL.md:步骤、判断、产物与停点]
S --> R[共享规则:触发目录、清单、模板]
S --> T[脚本:确定性读写与校验]
R --> A[项目产物:规格、票、报告、证据]
T --> A
A --> G[ship_gate:只读判定下一步]
G --> S
- 用户决定目标、偏好与关键方案批准。
- AI调查、讨论、写文档、实现、读码、评审和执行验证。
- 脚本处理可确定的结构与操作,例如编号、依赖、指纹、索引、状态与原子写入。
没有一个脚本能代替另外两层完成所有工作。格式 lint 通过不等于内容正确;gate 可推进不等于所有语义风险都已消除。
4. 安装位置、依赖和运行方式
4.1 依赖分层
以下版本信息来自仓库中的安装检查与 CI 配置,用于说明本项目的要求与复现环境。
| 依赖 | 用途 | 要求或本仓验证方式 |
|---|---|---|
| Git | 分支、内容树、checkpoint、恢复与合并 | 必需,需能正常访问消费项目的 Git 记录 |
| Bash | 安装器与辅助脚本 | macOS / Linux 使用 Bash;Windows 使用 Git Bash |
| Python 3 | 本地 helpers、recorder、lint | 安装器探测下限为 3.7;本仓 CI 的 Python 档为 3.9 / 3.12 / 3.14 |
| mikefarah/yq | 通用 YAML 与 frontmatter 的读取和校验 | 至少 4.16.0;本仓 CI 固定 4.53.6 |
| OpenSpec CLI | 创建 change、读取上下文与 instructions、validate、archive | 主流程必需;本仓 CLI 契约测试固定 1.14.3 |
| Node.js / npm | 运行 OpenSpec CLI,开发时安装 DOM 测试依赖 | 复现 CLI 测试可使用 CI 的 Node 22;CLI 1.14.3 的 Node 下限为 20.19.0 |
| pytest | 开发本工具仓、运行回归测试 | pytest>=8;使用 skills 本身不要求安装 pytest |
| Chromium / Playwright | 本工具仓的评审页浏览器回归 | 仅相关开发测试需要,不是日常工作流的运行依赖 |
多数 Python helper 使用标准库。通用 YAML 场景依赖外部 yq;issues 的单文件台账使用自己的有界字段格式,不需要额外安装 PyYAML。
注意区分同名 yq。 这里需要 mikefarah/yq,不是 Python 包 kislyuk/yq。可先检查:
git --version
python3 --version
yq --version
openspec --version
复现本仓固定 CLI 版本的安装命令:
npm install -g @fission-ai/openspec@1.14.3
安装器会提供各平台的缺依赖指引,不会自动把所有系统依赖装齐。消费项目需要的数据库、容器、硬件 SDK、测试服务等由项目自身决定。
4.2 setup.sh 安装到哪里
| 落点 | 用途 | 更新方式 |
|---|---|---|
~/.claude/skills/<skill>/ |
Claude 一侧的 skill 发现目录 | Unix 为源码绝对路径软链,Windows 为受管理复制 |
~/.agents/skills/<skill>/ |
共享 Agent Skills 目录,供支持它的宿主发现 | 同上 |
~/.g/workflow |
Unix 上共享规则目录的软链 | 指向当前工具链 checkout 的权威规则源 |
~/.g/workflow-path |
Windows 上共享规则源的路径指针 | 由 resolver 读取 |
~/.g/hack/ |
checkpoint、规则解析、页面生成等辅助工具 | 复制安装,修改源文件后必须重跑 setup |
~/.claude/agents/ |
兼容安装器保留的三个历史角色定义 | 由安装器维护自属定义;当前主流程不派发这些角色 |
安装器通过根目录下的 SKILL.md 识别 skill,docs/、hack/ 等不会被误装成 skill。已有的非本工具同名实体目录会被跳过并报告,不会无条件覆盖。
新共享位置安装成功后,安装器会清理旧 ~/.codex/skills/ 中可确认属于本工具的对应安装项,保留其它 skills。
不要在安装后删除或随意移动工具链 checkout。 Unix skill 软链与全局规则源需要它持续存在。
4.3 项目初始化与全局安装的区别
bash setup.sh 让本机找到 skills 和共享工具;/g-init 让一个目标项目接上工作流。二者不能互相替代。
g-init 的确定性入口是:
# 在消费项目根目录执行;安装路径按实际宿主选择
python3 "$HOME/.agents/skills/g-init/scripts/init.py" init --root .
初始化主要处理:
openspec/changes/、openspec/specs/等核心目录。- 人读手册
openspec/workflow/WORKFLOW-GUIDE.md。 - CLI 版本门允许时,铺设
openspec/schemas/g-spec-driven/。 - 新建配置或窄改配置的
schema键,并提示人工/AI 合并项目内容。 - 注入
CLAUDE.md、AGENTS.md、openspec/INDEX.md的托管区块。 - 合并托管的运行时忽略项,检查旧规则残留。
- 幂等安装 Claude 全局 hooks,并清理可识别的退役 hook / 部署文件。
其中 hook 包括分支守卫,以及兼容保留的 g-* 子代理权限请求守卫;后者存在不表示当前流程会启动子代理。这些是 Claude hook 机制,不应声称在所有宿主上都有相同的工具拦截效果。
托管标记之外的项目内容会保留。想修改托管内容,应修改工具源中的 snippets,再更新项目,不要直接改标记内部。
4.4 project-local schema 与版本门
g-init 检查 OpenSpec CLI 版本:
- CLI 可解析且至少 1.7.0:允许铺设 project-local 的
g-spec-drivenschema。 - CLI 不可用、版本不可解析或过低:不铺该 schema,按脚本的降级路径保持内置
spec-driven。 - 切换项目前,先为符合迁移条件的在途 change 补写其原 schema 标记,避免全局配置切换改变在途解释。
这个 schema 描述四件套的结构与依赖,也为不改变行为的变更提供 skip_specs 语义。schema 中历史名为 delegation 的提示块现在负责引导回 /g-spec 入口,不提供多代理调度。
context 和 rules 是给执行者的生成指导。不要把它们当作 OpenSpec validate 已经执行过的硬校验。
4.5 在不同宿主里如何调用
本 README 使用 /g-xxx 展示会话入口。实际触发形式取决于宿主,可以通过斜杠菜单、宿主提供的 skill 选择方式,或明确要求“使用 g-xxx”来调用。
如果宿主没有显示 skill:先确认安装目录与文件,再检查宿主的发现方式或重新打开会话。不要把缺少某种调用接口描述为“模型拒绝调用”。
文中的 python3 ...、bash ...、git ... 是终端命令;/g-xxx、/clear 是对话操作。Windows 默认终端为 PowerShell 时,工作流里的 Bash 命令需经 Git Bash 执行;python3 不可用时选择实际可用的 Python 3 解释器。
5. 所有 skill 的职责与选择
仓库目前有 12 个 skill 目录。g-review 的两种评审模式、g-implement 的两种实现模式共用各自的入口,不是额外安装项。
| Skill | 什么时候使用 | 主要输入 | 主要产物 / 行为 |
|---|---|---|---|
| g-init | 首次给项目接入工作流,或刷新项目托管材料 | 目标项目、已有配置 | 目录、配置、schema、手册、入口托管区块 |
| g-upgrade | 升级本机 gear 工具链 | 标准运行 checkout | pull --ff-only → setup → 展示版本 |
| g-spec | 开始一次明确交付边界的变更 | 需求、现状、项目约束 | 四件套、decision-memo.md |
| g-review | 设计审或实现后的代码审 | spec / code 模式与 change |
评审报告、发现处置、对应 gate 锚 |
| g-implement | 设计已批准后出票、逐票实现 | mode=plan / mode=exec |
tickets.md、实现报告、代码与完成标签 |
| g-done | 从当前盘面推进到开发流程完成 | change、可选合并意图 | 驱动实现、评审、verify、交接、归档与合并 |
| g-architecture | 项目级子系统边界、contract、骨架设计 | 系统目标、外部系统、硬约束 | SAD、架构日志、骨架切片建议 |
| g-roadmap | 工作超过一个 change,需分阶段规划 | 目标、约束、已有架构 | design / roadmap / task-log,可选 memo |
| g-devenv | 梳理测试策略、开发环境与测试执行路径 | 真实代码、现有工具、可选 SAD | 环境文档、测试策略、泳道状态、脚手架 |
| g-issues | 记录缺陷、优化、技术债,跟踪处理状态 | 描述、模块、来源与证据 | B/T 单文件台账与生成索引 |
| g-adr | 新建决策、变更后同步决策、存量体检 | 决策背景、代码、change | ADR 文件、格式检查、偏离项记录 |
| g-retro | 查看阶段耗时与已有历史评审数据 | Git 历史、变更报告 | 再生 openspec/retro/report.md |
5.1 根据当前问题选入口
只是接入流程 → g-init
不知道系统该怎么划分 → g-architecture
目标很大,要分阶段交付 → g-roadmap
不知道项目怎么测、环境怎么准备 → g-devenv
开始一个具体变更 → g-spec
设计已生成,需要检查 → g-review spec
设计已批准,要实施并收尾 → g-done <change>
发现 bug / 改进但本轮不做 → g-issues
需要留下长期决策 → g-adr new
需要核查已有 ADR → g-adr audit
想看流程历史耗时 → g-retro
工具链要更新 → g-upgrade
architecture、roadmap、devenv 是按需使用的项目级工具,不是每个 change 都必须重复执行的前置仪式。成熟项目已有可靠资产时,应先读取并复用。
5.2 一个新项目的常见组合
g-init
→ g-architecture:系统边界和骨架建议
→ g-roadmap:拆阶段(确实需要多个 change 时)
→ g-devenv:准备测试策略和运行路径
→ g-spec:一个具体 change
→ g-review spec:设计审与明确批准
→ g-done:实现到归档合并
这里表达的是职责衔接。架构和测试策略可能需要随真实骨架的建立逐步完善,不能在没有实现和执行证据时声称已经验证。
6. 主流程如何工作
6.1 全流程图
flowchart TD
A[需求与项目现状] --> B[g-spec:澄清]
B --> C[拷问关键前提,增量保存 memo]
C --> D[生成 proposal / specs / design / tasks]
D --> E[g-review spec:串行多视角检查]
E --> F{用户明确批准当前设计}
F -->|修订意见| C
F -->|批准并写设计锚| G[g-done:读取 gate]
G --> H[g-implement plan:出票并提交]
H --> I[g-implement exec:按依赖逐票实现]
I --> J[收尾票:聚合测试与基准证据]
J --> K[g-review code:最终代码审]
K --> L{仍有 P0/P1}
L -->|有| M[修复后重审,仍不能解决则阻塞]
M --> K
L -->|无| N[verify:逐需求核验与必要重跑]
N --> O{验证结论}
O -->|FAIL / 环境故障| P[报告缺口并停止]
O -->|PASS| Q[hand-off 与 ADR 同步]
Q --> R[OpenSpec archive 与 delta 核验]
R --> S[归档提交]
S --> T{是否明确跳过合并}
T -->|是| U[SHIPPED:归档完成、尚未合并]
T -->|有合并目标| V[ff-only merge 到记录的目标分支]
T -->|原地开发,无合并目标| X[SHIPPED:归档后留在工作分支]
V --> W[SHIPPED:归档并合并]
图中的实线表示正常职责顺序。实际运行中,done 每步前后都重新调用 gate;新产物、代码变化或恢复运行可能让它回到需要补做的步骤。
6.2 阶段一:g-spec 把讨论转成可实施材料
A. 澄清
执行者先检查 OpenSpec CLI、项目上下文、当前分支与在途 change,再调查现有实现。
这一阶段要得到可描述的目标态,确认会影响哪些模块,以及真正需要用户决策的偏好或约束。仓内能查到的事实应自行调查,不能把检索工作交回用户。
目标清楚时,澄清可以很短;这不等于后面的拷问可以跳过。
B. 拷问
拷问的对象是“这个方案依赖的前提是否站得住”。例如:
- 当前调用方真的允许改变这个字段吗?
- 所谓兼容要求有没有真实使用方?
- 某个约束是业务必需,还是原实现留下的惯性?
- 不采用推荐方案会付出什么代价?
- 一个决定改变后,哪些下游决定需要重新评估?
开始这个阶段时会先检查工作树,按 FF-0 规则准备分支,再通过 OpenSpec CLI 创建 change,并立即保存最小草稿 decision-memo.md。约束确认一条,就保存一条,避免长讨论只活在聊天里。
memo 的主要内容包括承重约束、拍板决策、证据、必要的候选与被否理由。讨论尚未收敛时只增量保存,不把每轮讨论都做成 checkpoint。
停止条件是“人机共识达成,且承重约束逐条有证据”,不是“已经问过固定数量的问题”。
C. 生成与终审
执行者按实际 schema 的依赖生成四件套,读取项目 context / rules,并按命中的触发项补充内容:
| 产物 | 主要回答 |
|---|---|
proposal.md |
为什么做、改什么、成功标准、范围与非目标 |
specs/<capability>/spec.md |
外部可观察行为、输入输出、错误条件、验收场景 |
design.md |
如何实现、组件与接口、失败模式、取舍与约束 |
tasks.md |
要完成哪些工作,分别对应哪些需求 |
decision-memo.md |
这些方案与约束为什么成立,用户拍了什么板 |
生成完后,主会话读回整个 change,核对 memo 与产物、design 与 specs、规则必填项和引用事实,再做 CLI 完成度与严格验证检查,最后提交阶段 checkpoint。
纯文档、工具调整或重构,如果确实不改变规格级行为,可以按 schema 使用 skip_specs: true。这不是为了避开测试,也不能用来掩盖真实行为变化。不要为了凑一个 delta 而编造需求。
6.3 阶段二:g-review spec 检查设计
设计审顺序覆盖:
- 广审 strategy:目标、范围、假设、决策与整体完整性。
- 广审 plan-eng:可行性、错误处理、约束、追踪性、图表与组件。
- 领域检查:根据技术栈和本次触发项选择相关清单。
- 对抗检查:构造具体失败条件,尝试证伪方案。
- 接地检查:打开真实代码,核验函数、字段、API、依赖等现状断言。
这些视角由主会话逐一完成。每次开始前重读对应清单和材料,分别记录发现;它们共享一个上下文,不声称具有独立第二意见。
报告固定写入 spec-review-report.md。需要拍板的选择进入决策登记区,包含推荐、依据、系统/用户/开发循环三方面后果及备选。
设计审结束后要把报告交人。明确批准之前不能写 design_approved: true,也不能进入自动实施。
主变更链的固定人工批准点是设计门。 需求讨论本身仍可能需要用户回答,architecture、roadmap、devenv 等项目级流程也各自有人参与的决策与确认;“一次设计门”不表示所有 skills 全程都不再提问。
6.4 阶段三入口:g-done 负责推进,不凭记忆排步骤
调用方式:
/g-done filter-orders-by-status
done 不把对话里的“刚才应该做完了”当状态,而是运行 ship_gate.py,读取 verdict 和下一步建议。它会把兼容保留的旧 next 名映射到当前 g-review spec/code 入口。
通常只要设计已批准,用户就可以让 done 接管后续流程。单独调用 implement / review code 更适合定向检查或诊断;正常路径应让 done 维护前后门禁。
同一个 verdict 连续重跑两次仍没有新产物时,done 会熔断并报告,避免无限空转。
6.5 g-implement:出票与执行分开
mode=plan:把规格拆成票
计划读取 design、tasks 和 specs,默认切成 3–6 张纵向功能票,加 1 张收尾票。纵向切片要求一张票能穿过必要的存储/接口/消费端或测试路径,产生可验证行为。
tickets.md 中每张票有:
- 固定标题
### Task N: ...。 Blocked-by:必须先完成的票号,或者none。R-ID:对应的需求标识。- 可执行、可观察的验收条件。
收尾票必须唯一,R-ID: all,并明确依赖全部功能票。出票后运行预算检查并提交;tickets.md 的首次提交是后续完成标签窗口的起点。
tasks.md 是变更级工作清单;tickets.md 是实施时的依赖与验收计划。两者职责不同,不能用一个文件替换另一个。
mode=exec:按依赖串行选票
helper 根据 Blocked-by 和 gate 的 done_tasks 计算当前可执行票,主会话取其中最小票号,逐张完成:
读取本票与全局约束
→ 实现
→ Spec 轴自审:是否满足需求与验收
→ Standards 轴自审:是否符合代码规则
→ 运行验收并保存证据
→ 勾选并提交本票完成 checkpoint
完成标签形式为:
checkpoint(filter-orders-by-status:task1-status-query): 完成状态查询切片
task<N>- 后必须有 slug。勾选票、写了实现报告或者源码已经存在,都不能单独替代已提交的完成标签。
首次提交后,不应重排、删除或复用已有 Task 编号;需要调整计划时保留身份和历史,按约定追加。
收尾票:聚合验证
功能票完成后,先确认源码已提交,再运行 suite-scope 求出本次应覆盖的测试域和层。把原始 JSON 保存进收尾报告头部,执行对应测试并记录证据。
即使命中域没有自动测试层,原始 JSON 的完整 head 仍要保留。它是后续 verify 比较“收尾验证以后发生了什么变化”的基准,不依赖报告中是否存在通过行。
6.6 g-review code:检查整个实现
最终代码审不只重复每票自审,它要检查跨票与全 change 的行为:
| 视角 | 重点 |
|---|---|
| scope 审计 | 有无多做、少做、偏离已批准目标,需求是否全部实现 |
| 领域检查 | 通用代码清单与命中领域的规则 |
| 对抗检查 | 边界、错误路径、并发,以及“测试绿但语义错”的情形 |
| 历史检查 | 对照已有 open/closed issues,复用同一问题的 ID |
实现自审和最终代码审共用同一严重度口径:
| 级别 | 判据 | 默认处置 |
|---|---|---|
| P0 | 数据损坏、越权、核心能力不可用等严重错误 | 必须修复,否则阻塞 |
| P1 | 已批准验收不满足、确定的正确性错误或重要功能回归 | 必须修复,否则阻塞 |
| P2 | 不影响本轮验收的维护性、体验细节、后续改进 | 可带理由延期,需真实 issue |
自动修复最多两轮,仍有 P0/P1 就写 blocked。不能因为修起来麻烦就改标 P2,也不能用“已经记了 issue”替代修复。
修复提交以后,从干净源码捕获检查基准,完成最终审查和相关测试。只提交报告,再用带基准校验的写锚脚本记录结论。
6.7 verify:按需求确认实际交付
verify 要求执行者不信任复选框和既有报告措辞,重新核对 tasks / specs 与真实实现。
主要步骤:
- 确认源码已提交,在检查开始前捕获完整提交 SHA。
- 逐条需求读码、查测试与证据,给出有依据的结论。
- 读取收尾票报告中的原始
suite-scopeJSON.head 和测试证据。 - 比较收尾基准到当前代码,覆盖代码审修复带来的必要重跑。
- 在
verify-report.md中记录需求、证据、未覆盖与缺口。 - 限定路径提交报告,写入经过基准核对的 PASS / FAIL 与内容锚,再提交锚。
没有证据的“应该完成”不能写成已通过。零用例的成功退出不能算有效通过;环境故障不能算产品通过。
6.8 hand-off、archive 与最终完成
verify PASS 后:
- hand-off:写已完成、未完成/延期、下一阶段建议;查询本次新增未闭合 issues,必要时生成 roadmap 回填草稿。
- 来源 issue 回写:proposal 明确关联来源 issue,且对应验收全部满足时,按池写
FIXED/DONE,附证据。 - ADR sync:按本次路径变化与显式引用召回候选,主会话串行核对。失败或缺工具记录原因,不阻塞合并。
- archive:通过 OpenSpec CLI 归档并同步主 specs,不手工
mv冒充归档。 - delta 核验:检查归档变更与主 specs 的同步,失败先补齐,不能直接进入归档提交。
- commit / merge:保存归档结果;默认留在工作分支结束;只有明确指定目标时做 ff-only merge,也可按显式
.skip-merge暂停合并。
CLI 同步失败存在 skill 内定义的 fallback:仍经 CLI 处理归档,再依真实代码补同步主 specs,并验证相关 spec 与 delta。fallback 不是忽略同步失败。
7. 项目级规划与环境 skills
7.1 g-architecture:先把系统边界想清楚
适用于新系统设计,或成熟项目需要重新核对系统分解、外部依赖、子系统 contract 和骨架路径。
会话示例:
使用 g-architecture,为这个项目梳理系统架构。
先读取现有 ADR、设计文档和代码,再确认定位、外部系统与硬约束。
它直接维护项目级单例:
openspec/architecture/sad.md
openspec/architecture/sad-log.md
不为“写架构文档”本身包一层 change。流程是:
- 采集定位、外部系统、硬约束三类事实;已有资料先蒸馏,交用户确认。
- 按分解规则形成子系统候选,检查实体服务化、纯技术分层、God-hub 等问题。
- 把真实方案分歧与代价交人选择,不凑明显劣化的对照方案。
- 写 SAD,执行场景 × 子系统 × contract 的内联走查;风险高时增加检查视角。
- 用户复核事实、处置假设与走查洞,再迁移到
skeleton-ready并 lint。 - 给出骨架 change 建议,交回用户决定是否触发
g-spec。
skeleton-ready 表示材料足以进入骨架实施,不表示系统已经实现或 contract 已实测。
已有 SAD 时区分 continue 与 replan:前者增量续写,后者有原因地重规划。不能静默覆盖既有文档。当前模型是单系统单例,不能据此承诺已支持一仓多系统的独立 SAD 布局。
结构检查输出中的 SEMANTICS-UNCHECKED 是刻意保留的边界提示:结构合格不能替代内容走查与用户判断。
7.2 g-roadmap:把大目标拆成多个可交付 change
适用于跨多个阶段的项目、迁移或重构。它只做规划,不直接实施。
会话示例:
使用 g-roadmap,把现有订单服务迁移计划拆成分阶段交付。
每个子任务控制在一个 change 的粒度,近期详细、远期保留边界和依赖。
产物直接写入:
openspec/roadmaps/<name>/
├── design.md
├── roadmap.md
├── task-log.md
└── memo.md # 按讨论需要保留
design.md保存长期目标态与总体方案。roadmap.md保存阶段、依赖、目标和验收边界,近期细化、远期允许保留雾区。task-log.md保存推进与 review 处置历史。memo.md承接讨论期约束与决策,不应让正式设计只靠历史纪要解释。
三个正式文件作为一个整体做 strategy / plan-eng 内联检查,并核对跨文件一致性。检查没有完成时不能声称规划已过审。
已有同名包时区分:
| 模式 | 行为 |
|---|---|
| create | 新建规划包 |
| continue | 增量更新,保留既有任务日志与 review 处置 |
| replan | 先记录原因,再改写受影响规划,保留历史日志 |
roadmap 的阶段实施仍然回到主流程:为一个阶段触发 g-spec,然后设计审与 done。收尾可能提供 roadmap 回填草稿,草稿不等于已经回填并批准长期规划。
roadmap 保留静态评审页 review/roadmap-review.html。页面是阅读和反馈界面,Markdown 包仍是正文依据。
7.3 g-devenv:把“怎么测”与“证明了什么”说清楚
适用于新建测试环境,也适用于把散落在 CI、脚本、文档中的现有测试约定归位。
会话示例:
使用 g-devenv,整理本项目的单元、集成和端到端测试策略。
先查已有命令和 CI,说明各层能证明什么、看不见什么,并核验可执行的泳道。
主要文件位于 openspec/architecture/:
| 文件 | 职责 |
|---|---|
.devenv.json |
结构化的三层框架、执行泳道与证据状态 |
testing-strategy.md |
从 JSON 机械渲染的测试策略,不手工维护第二份 |
environments.md |
开发与发布环境文档,由执行者编写和维护 |
devenv-log.md |
决策、验证与人门记录 |
devenv-review.md |
本轮汇总,供人复核 |
review/devenv-review.html |
可读的静态评审页 |
“泳道”是一条具体的验证路径,比如真实数据库集成测试、浏览器端到端测试、硬件人工验证。
每层除工具、规范、命令和依赖,还必须说明信心与盲区。例如“codec 单测使用内存 buffer,没有覆盖真实 socket 分片”,比“单元测试不保证集成正确”更有用。
常见泳道状态:
| 状态 | 含义 |
|---|---|
| planned | 已规划,尚未落地 |
| scaffolded | 脚手架已落地,但尚未获得通过证据,可能有 blocked_by |
| verified | 已实际验证,有执行或人工确认的证据 |
缺系统依赖导致命令跑不起来,应记录 scaffolded + blocked_by;不能改成“人工执行”来掩盖环境未满足。确实需要人工判读或真机的路径,才按 skill 的人工确认流程处理。
这个 skill 的边界比普通实现任务更窄:首跑前展示命令与 smoke / harness 的 diff;默认不替用户装系统依赖;一次验证失败就保存原因和修复指引,不在这条泳道上无限重试调试。待定、未验证和有后果说明的不适用,都是合法产物。
它也会根据已经查证的命令,建议补充 openspec/config.yaml 的 test-suites。已有配置保留;没有真实构建隔离时不发明测试分域。
8. issues、ADR 与复盘
8.1 g-issues:记录问题,不把记录当实现
两个池共用一个入口:
| 池 | 用途 | ID 前缀 | 状态 |
|---|---|---|---|
| bug | 偏离预期的可观察故障、错误或退化 | B | OPEN / PROPOSED / FIXED / WONTFIX |
| todo | 行为没坏,但可改进的质量、体验、性能或基础设施事项 | T | OPEN / PROPOSED / DONE / WONTDO |
“性能违反原有 SLA”属于 bug;“已经达标但还可以更快”通常属于 todo。存在真实故障与否,比措辞里有没有“优化”更重要。
文件模型:
openspec/issues/
├── open/
│ ├── B1.md
│ └── T1.md
├── closed/
│ └── B2.md
├── INDEX.md # 自动生成的活跃索引
└── CLOSED.md # 自动生成的闭合索引
每条 issue 的 YAML frontmatter 是机器字段的权威源,Markdown body 可补现象、根因、复现和方案。索引由脚本重建,不能手改。
自然语言使用:
使用 g-issues,记录一个 bug:空状态筛选会触发 500。
模块是 orders/filter,来源是 filter-orders-by-status。
也可以直接调用 recorder。以下命令在消费项目根执行:
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . add --pool bug --json '{"module":"orders/filter","summary":"空状态筛选触发 500","priority":"P1","source_change":"filter-orders-by-status"}'
扫描与回写示例:
# 活跃项;--all 才包含 closed/
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . scan --json
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . scan --all --json
# ID 与证据仅为示例,替换成实际 recorder 返回值和真实修复依据
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . set-status --id B1 --to FIXED --evidence 'filter-orders-by-status 已验证并归档'
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . set-status --id T1 --to WONTDO --reason '需求取消,继续实现没有收益'
# 同一已关闭问题重新出现,保留 ID 与原始来源
python3 "$HOME/.agents/skills/g-issues/scripts/issues_v2.py" --root . reopen --id B1 --reason '同一失败路径在新版本复现'
重要行为:
FIXED/DONE必须带证据,WONTFIX/WONTDO必须带理由。- 终态文件迁到
closed/,受控反向操作使用reopen,不能用set-status绕过。 add、set-status、reopen默认会暂存其改动,并自动重建索引;不希望触及暂存区时使用它们支持的--no-stage。source_change表示最初发现来源,复用与重开不改成当前 change;关闭归属由resolved_by记录。- 当前没有跨 bug/todo 池的通用 move/reclassify 命令。落池前应核对,不要假设可无损自动换前缀。
issues skill 的一般记录策略与具体流程要一起看:并非所有讨论意见都应进池;但代码审明确决定延期的 P2,必须按其 defer 契约保留真实记录,不能只写一句“后面再说”。
8.2 评审 defer 台账:new 与 reuse
代码审报告采用四列:
| id | 摘要 | 去向 | 来源 |
|---|---|---|---|
| T12 | 不影响当前验收的后续整理 | defer | new |
| B7 | 已有问题的关联记录 | defer | reuse |
示例编号必须替换成真实文件中的 ID。
| 来源 | gate 校验 |
|---|---|
| new | 对应 open 池文件存在,且 source_change 为当前 change |
| reuse | open/closed 中能找到唯一文件,真实 id / pool 与引用一致;允许历史或空来源 |
旧三列表没有来源列时按 new 解释,保留原有严格校验。有来源列却留空、写其它单词、票不存在或存在多个匹配文件,都会被拒绝。
如果同一 closed 问题确实重新发生,先 reopen 再记录关联。reuse 允许核验历史关闭记录,不等于可以把仍待处理的复现问题留在关闭状态。
8.3 g-adr:保留长期决策与取舍
三个模式:
/g-adr new
/g-adr audit
sync 通常由 done 在 verify 之后、archive 之前调用,不是日常手动入口。
| 模式 | 行为 |
|---|---|
| new | 脚本分配编号、建文件;执行者补背景、决策、备选与后果,再 lint |
| sync | 按本 change 的路径和显式引用召回候选,串行核对本次变化;非阻塞收尾 |
| audit | 分批检查全部 ADR 的格式与代码事实,把需决策的偏离记录到 issues |
新建 ADR 不会自动把任意设计偏好升级成长期约束。应确认该决定确实有后续影响、非显然或容易被质疑,并保留真实取舍。
ADR 的 lint 负责结构与格式,不证明文字与代码一致。sync / audit 的读码判断也由主会话执行,不派发子代理。
8.4 g-retro:查看历史,不自动调整流程
会话入口:
/g-retro
或运行:
python3 "$HOME/.agents/skills/g-retro/scripts/retro_report.py" --root "$(git rev-parse --show-toplevel)"
它从 Git checkpoint、活动/归档 change 的报告和已有历史数据再生:
openspec/retro/report.md
“只读复盘”表示不改变实现、规格、issue 状态或流程决策;再生报告文件本身会写盘。
当前简化流程不再生成 token 快照和 lens 度量锚。旧数据仍兼容读取,缺数据应理解为“未覆盖”,不能当成零成本、零发现或完整统计。
阶段墙钟来自提交时间差,包含等待、讨论和其它间隔,不是模型纯计算时间,也不能直接作为精确费用核算。
9. 项目会生成哪些文件
以下是使用相应能力之后的汇总视图,并不表示 init 一次会创建全部目录:
your-project/
├── AGENTS.md # 托管入口 + 项目自定义内容
├── CLAUDE.md # 托管入口 + 项目自定义内容
└── openspec/
├── config.yaml # 项目上下文、规则、测试命令
├── INDEX.md # 工作流与项目资产导航
├── CONTEXT.md # 按需维护的项目术语与上下文
├── workflow/
│ └── WORKFLOW-GUIDE.md # 给人的手册副本
├── schemas/
│ └── g-spec-driven/ # CLI 版本门允许时铺设
├── specs/
│ └── <capability>/spec.md # 当前正式规格
├── changes/
│ ├── <change>/
│ │ ├── .g-branch.json # 起始分支、工作分支、固定基准与合并目标
│ │ ├── .openspec.yaml
│ │ ├── decision-memo.md
│ │ ├── proposal.md
│ │ ├── specs/<capability>/spec.md
│ │ ├── design.md
│ │ ├── tasks.md
│ │ ├── spec-review-report.md
│ │ ├── tickets.md
│ │ ├── impl-reports/
│ │ │ ├── planning-decisions.md
│ │ │ └── task<N>-<slug>.md
│ │ ├── code-review-report.md
│ │ ├── verify-report.md
│ │ ├── hand-off.md
│ │ └── .skip-merge # 仅明确跳过合并时存在
│ └── archive/
│ └── <date>-<change>/ # 归档后的变更材料
├── architecture/
│ ├── sad.md
│ ├── sad-log.md
│ ├── .devenv.json
│ ├── environments.md
│ ├── testing-strategy.md
│ ├── devenv-log.md
│ ├── devenv-review.md
│ └── review/devenv-review.html
├── roadmaps/
│ └── <name>/
│ ├── design.md
│ ├── roadmap.md
│ ├── task-log.md
│ ├── memo.md
│ └── review/roadmap-review.html
├── issues/
│ ├── open/<ID>.md
│ ├── closed/<ID>.md
│ ├── INDEX.md
│ └── CLOSED.md
├── adr/<number>-<slug>.md
└── retro/report.md
9.1 文件名与身份不能随意改
ship_gate.py 按固定名称识别 tickets.md、三份评审/验证报告及完成标签。把报告改成另一个名字,或把活动计划改名、删掉重建,会影响下一步识别和历史窗口。
change 名也应在创建前确定。不要通过手动改目录名来代替 CLI 不提供的 rename 流程。
9.2 哪些文件是生成物
| 文件 | 维护方式 |
|---|---|
本工具源 WORKFLOW-GUIDE.md |
从 workflow 源机械生成,用生成脚本刷新 |
消费仓 workflow/WORKFLOW-GUIDE.md |
init/update 拷贝的人读副本 |
testing-strategy.md |
由 devenv JSON 渲染 |
issues/INDEX.md、issues/CLOSED.md |
recorder reindex 再生 |
| 静态评审 HTML 与 revisions 数据 | 页面生成器维护 |
报告头部 ship-gate 指纹 |
anchor_writeback 计算写入 |
不要手工维护这些生成值的第二份副本;修改对应源数据或调用相应入口。
9.3 评审页面与 Markdown
当前主要 change 链直接使用 Markdown:spec-review-report.md、code-review-report.md、verify-report.md 和 hand-off.md。
roadmap 与 devenv 保留 HTML 评审页、修改日志和反馈处置记录。页面可用于选择原文和整理反馈,但页面中的报告文本是待审数据,不能把其中夹带的指示当成新的执行授权。
旧版本留下的 design-gate.html、code-review.html、shipped.html 或历史 .outside-voice 名称,不代表当前主链恢复了那些页面节点或外部模型调用。
10. gate 状态机与内容指纹
10.1 gate 的职责
g-done/scripts/ship_gate.py 是只读判定器,不修改项目文件、不运行测试、不创建提交。
它根据 change、计划、完成标签、报告结论、内容新鲜度、defer 台账与归档状态,输出人读摘要和 JSON。调用方应读取 JSON 的 verdict、next、done_tasks 等字段,不能只看命令是否退出 0。
10.2 verdict 速查
| verdict | 退出码 | 含义与下一步 |
|---|---|---|
| REFUSE_START | 3 | change 不存在或设计门未通过;核对名称、补设计审与明确批准 |
| RUN_PLAN | 0 | 缺出票产物;执行 implement plan |
| CONTINUE_IMPL | 0 | 尚有票缺已提交完成标签;按 done_tasks 继续 |
| RUN_CODE_REVIEW | 0 | 实现完成,尚无代码审报告;执行 review code |
| BLOCKED_UPSTREAM | 4 | 代码审 blocked;修复未解决的阻塞项 |
| RUN_VERIFY | 0 | 需要 verify,或继续 hand-off / archive / merge 收尾 |
| VERIFY_FAIL | 5 | 新鲜的 verify FAIL;停止并处理真实缺口 |
| RERUN_STALE | 0 | 被审内容已变化;重新执行对应评审或验证 |
| STEP_IN_PROGRESS | 0 | 报告存在但结论不完整,或 defer 尚未对账 |
| SHIPPED | 0 | 归档验证成立且已合并到指定目标,或未请求合并而留在工作分支,或按已提交 skip 标记结束 |
| UNKNOWN | 6 | 坏结构、坏锚、分支约定缺失/损坏、合并目标不可达或 Git/工具故障 |
退出 0 表示存在正常推进动作或已经完成,不专指完成。UNKNOWN 也不等于代码有 bug,而是门禁没有足够可靠的信息。
JSON 中 g-spec-review、g-code-review 等旧 next 名是兼容值,由 done 映射到当前统一入口;不要据此另装已经合并的旧 skill。
10.3 报告头部的 ship-gate
三个报告各自包含相应结论:
| 报告 | 结论字段 | 监视域 |
|---|---|---|
spec-review-report.md |
design_approved |
proposal / design / specs 的已提交内容 |
code-review-report.md |
code_review |
排除 openspec 记账域后的已提交代码内容 |
verify-report.md |
verify |
同上 |
另外保存:
reviewed_sha:监视域 manifest 的 SHA-256,64 位十六进制。reviewed_manifest:同一份 manifest 的编码,用于互证与定位差异。
reviewed_sha 不是 Git commit SHA。 它与检查前捕获的 Git 提交基准是两种不同用途的值,不应混写。
报告正文先完成,结论与指纹由 anchor_writeback.py 同批写入头部 frontmatter。不要复制一个旧锚,也不要自己填看起来合法的十六进制串。
10.4 为什么写报告通常不使代码锚失鲜
代码域排除了 openspec/ 记账内容。因此只修改本次报告或归档材料,代码内容指纹可以不变;修改源码、源码目录内容或相关代码域文件,就会使指纹变化。
这使流程可以“提交报告 → 写锚 → 提交锚”,而不会因为报告本身推进 HEAD 就立刻失鲜。
设计域不同:它监视本次 change 的 proposal / design / specs,并在进入实现的窗口检查。它没有声称在后续所有阶段都持续检查设计变化。
10.5 PASS 写入的基准保护
代码审与 verify 在检查前捕获完整提交 OID,随后写代码域 PASS 必须传 --expected-ref。
写入时会拒绝:
- 未提供基准。
- 使用
HEAD、分支名等可变引用,或不完整的 OID。 - 基准提交不存在。
- 当前代码内容与已检查基准不同。
- 源码有未提交变更,或者尝试用
--allow-dirty写代码 PASS。
报告专用 checkpoint 只提交列出的 openspec/ 路径,并拒绝 openspec/ 外的未提交改动,避免把测试之后的源码顺手提交进“已验证版本”。
这能防止基准漂移,不能证明传入的基准真的接受过测试。检查必须真实发生,不能在写锚时才临时取最新 HEAD 冒充检查前记录。
11. 测试配置、证据和 PASS 的边界
11.1 在哪里声明测试命令
消费项目使用 openspec/config.yaml 的 test-suites。命令必须来自真实项目,不能为了把表填满而发明。
以下 YAML 是形状示例,命令路径需要替换成项目中已经存在且可执行的入口。
形状一:每层一个命令。 quick 和 full 都使用同一命令:
test-suites:
unit: "python3 -m pytest tests/unit"
integration: "python3 -m pytest tests/integration"
e2e: "npm run test:e2e"
形状二:有真实快慢分档时分别配置。 缺一档时使用另一档,不必造一个假的 quick:
test-suites:
unit:
quick: "python3 -m pytest tests/unit -m 'not slow'"
full: "python3 -m pytest tests/unit"
integration:
full: "make integration"
e2e:
full: "npm run test:e2e"
如果项目没有 slow marker 或对应 Make target,就不能原样采用这些示例。
形状三:项目已有真实构建隔离时按域配置。
test-suites:
domains:
docs:
paths: ["docs/", "README.md"]
layers: {}
tools:
paths: ["tools/"]
layers:
tools: "python3 -m pytest tests/tools"
project:
default: true
paths: []
layers:
unit: "python3 -m pytest tests/unit"
integration: "make integration"
e2e: "npm run test:e2e"
分域规则要点:
domains存在时,不再同时放顶层 unit / integration / e2e 旧键。- 恰好一个域标
default: true,接住未匹配路径。 docs/这种带尾斜杠的路径按目录前缀匹配;README.md按精确路径匹配。- 更具体、更长的匹配优先。
- 一次变更可能命中多个域,应按 helper 输出执行,不自行只挑最便宜的层。
- 域可以使用自己的层名;
layers: {}只有在明确配置且确实无自动层时才表示该域没有自动测试。 - 分域应反映独立 module、build tag 或实际依赖隔离,不是为了少跑测试而随意画分区。
完整配置母本见 config.template.yaml。
11.2 suite-scope 输出怎么读
g-implement/scripts/impl_route.py suite-scope 只求范围,不运行测试。输出包含:
| 字段 | 用途 |
|---|---|
| base / head | 本轮比较基准与当前提交身份 |
| domains_configured | 是否启用了显式分域配置 |
| hit_domains | 命中的域 |
| layers | 本轮按配置应执行的命令与档位 |
| unconfigured_layers | 未配置、需要继续查明的基础测试层 |
| skipped_layers | 本次范围中未触发的层信息 |
| mapping | 变更路径与归域信息 |
正常流程必须传 --change <name>,未显式传 --base 时读取该 change 的固定 base_sha。verify 重跑可以显式传收尾 JSON.head;仅不带 change 的独立兼容调用才按仓库默认分支求 merge-base。显式给 --head 时比较提交范围;不传 head 的默认路径还会考虑工作树及未跟踪文件,因此收尾前必须确认源码状态。
这个 helper 读取指定版本的配置来判域,不应拿当前工作树中的另一份配置偷偷解释旧提交范围。
11.3 配置缺失、无命中测试、零用例是三回事
| 情况 | 正确处理 |
|---|---|
| 没有配某个基础测试层 | 查 CI、README、testing-strategy 与现有脚本,发现命令后真跑;确实没有则写查证依据 |
显式命中一个 layers: {} 的域 |
记录该域无自动测试层,保留分域与验收依据 |
| 某层运行成功但发现 0 个用例 | 不能当成通过证据,应检查命令和测试发现范围 |
| 命令返回成功,但用例数未知 | 如实写未知,不能编数字;结合实际输出与验收要求判断覆盖 |
| 测试启动失败、依赖未就绪 | 报环境阻塞,不能冒充功能通过 |
| 没有源码变化,且无待发现测试层 | 可说明没有触发重跑,保留先前证据及比较依据 |
11.4 测试证据格式
实现报告每层一行:
层 | 命令原文 | 退出码 | 用例数 | SHA
命令要能复现,用例数来自真实输出。通过行的 SHA 必须能解析到实际测试的代码版本。
收尾票额外保留原始 suite-scope JSON,所有通过行指向同一 head。后续 verify 从这个 head 比较代码审修复,不从“第一条通过行”推导基准,所以没有自动层也不会失去版本身份。
测试中途修改源码或测试配置后,应重新捕获基准并按规则重跑;不能沿用旧证据为新版本背书。
11.5 失败如何分诊
- 本轮引入的失败:修复、重跑,不能用 issue 登记代替。
- 已有红测:需要确认基线同样失败,记录层、用例标识和 issue;verify 按收尾报告里的明确记录匹配,不能把所有红测一概归为历史问题。
- 复跑即绿的 flaky:注明复跑与波动,不伪装成首次全绿。
- 环境故障:报告 problem / cause / fix 并阻塞相应阶段。
- 未覆盖项:解释缺失的依据与后果;“没跑”就是没跑。
是否满足用户需求还需逐条读码和核验,测试层数多不自动等于需求验收充分。
12. Git、提交和合并行为
12.1 起始分支、固定基准与合并目标
spec 创建 change 前遵循 FF-0:
| 当前分支 | 默认动作 |
|---|---|
| main / master / 默认分支 | 创建 feat/<change> |
已在本 change 的 feat/<change> |
继续使用 |
| 在其它 feature 分支 | 确认从当前新建、回明确分支新建,还是原地开发;记录对应交付意图 |
现有默认命名是 feat/<change>;用户或消费仓有明确规则时,应遵循实际约定。
每个 change 保存自己的起点,不再默认合回仓库默认分支。
| 你在分支 a 上选择什么 | 工作分支 | 默认交付结果 |
|---|---|---|
| 从 a 新建功能分支 | 例如 feat/my-change | 提交、验证、归档,留在新功能分支,不自动合并 |
| 直接在 a 上做 | a | 提交、验证、归档,留在 a,不额外合并 |
| 明确指定合到 release | 当前记录的工作分支 | 按指定目标合到 release;不能快进则停止 |
分支切换前捕获起始分支与完整提交 SHA;CLI 创建 change 后由 branch_context.py init 保存 openspec/changes/<change>/.g-branch.json:
{
"source_branch": "a",
"work_branch": "feat/my-change",
"base_sha": "<切分支前的完整真实提交OID>",
"merge_target": null
}
这里的 OID 是形状说明,必须由真实 Git 记录取得。新建功能分支和原地开发默认 merge_target 均为 JSON null;原地开发时 work_branch 为 a。该文件随 checkpoint 提交并随 change 归档保留,不能随恢复运行重新捕获。
代码审、收尾测试范围与 ADR 召回使用固定 base_sha;即使原地分支 a 已经推进,仍能检查本次全部差异。最终合并只读取 merge_target。修改目标不改变起始基准。
只有你明确指定合并目标时才由 branch_context.py set-target 改目标,并提交这项改动。说“现在合并”沿用已有目标;原来是 null 时要先明确目标,不自动选 master/main。目标不存在就停止,不回退默认分支。
仓库默认分支解析仍保留作诊断、旧已合并归档识别和未指定 change 的独立工具兼容用途,不再决定正常 change 的交付去向。远程引用不自动 fetch。旧变更缺约定时,done 与按 change 的测试工具要求核对历史并补录,禁止拿当前 HEAD 或默认分支猜起点;gate 可诊断旧活动变更进度,但不自动合并缺约定的旧归档。
12.2 checkpoint 会提交什么
普通模式:
checkpoint-commit.sh <step> [描述]
它仍然使用 git add -A。因此阶段起手和 checkpoint 前必须检查工作树,避免混入用户已有文件、其它任务或测试生成物。
代码审和 verify 报告必须使用限定路径的模式:
checkpoint-commit.sh <step> <描述> -- openspec/<文件> ...
该模式:
- 只接受
openspec/内的限定路径,拒绝路径中的./..组件。 - 拒绝
openspec/外已暂存、未暂存或未跟踪的改动。 - 只提交指定路径,保留无关文档的暂存状态。
- 配合
--expected-ref防止未验证源码被写入 PASS。
这些行为不意味着所有流程提交都自动隔离了无关文件。普通 checkpoint 和最终归档提交仍需遵守干净起手与范围检查。
12.3 合并方式与边界
有合并目标时,收尾使用 git merge --ff-only,不自动 rebase、不强行解决非快进问题、不自动 push。
如果记录的合并目标已经有了与工作分支分叉的提交,ff-only 会失败。此时应报告分叉与可选处理,让有权限的人决定如何更新分支;不能为了完成流程擅自 reset 或强推。
源码有未提交变化、未跟踪文件可能被切分支影响,或归档同步未完成时,都需要先处理对应状态。
12.4 skip merge 是持久意图
.skip-merge 随 change 进入归档。gate 只采信已提交的标记,并要求归档有有效 verify PASS;一个空目录加标记不能绕过验证。
无新意图时重复调用 done 会保持跳过合并的状态。只有用户明确要求现在合并,流程才在归档位置撤销标记、单独提交,再续跑 gate 与 merge。
13. 中断以后怎样恢复
13.1 主变更链:先确认项目和 change
新会话可以这样说:
继续使用 g-done 处理 filter-orders-by-status。
请重新读取 gate 与盘面产物,不依据上次聊天里“已经完成”的说法跳步。
执行者应先确认仓根、分支、工作树和 change,再运行 gate。
13.2 常见断点
| 中断位置 | 恢复方式 |
|---|---|
| spec 讨论中,memo 尚为草稿 | 重入 g-spec,读已存 memo,确认继续原 change |
| 部分四件套已经写出 | 读 OpenSpec status 与已有产物,补缺失部分,不盲目全量重生成 |
| 四件套已经完整 | 转设计审,不把 complete 当作可以任意重写的草稿 |
| 设计报告有了但尚未批准 | 等待明确批准或按意见修订,不自动写批准锚 |
| plan 已写但没提交 | 提交合法出票产物,建立完成标签窗口 |
| 代码写了一半 | 读取本票代码与报告,补未完成实现和验收 |
| 票已勾满但没完成标签 | 不直接跳票,续做自审/验收,通过后再提交完成标签 |
| 代码审后改了源码 | 接受 RERUN_STALE,重审/重验变更后的版本 |
| verify 报告写到一半 | 补真实证据和结论,不能仅补一个 PASS 字段 |
| 已归档但未合并 | 读取已提交的分支约定;有目标则继续合并,null 则留在工作分支完成,不重新创建同名活动 change |
| 已 skip merge,现明确要合并 | 撤销归档标记的提交完成后,重新运行 gate |
13.3 项目级材料各自恢复
- architecture:读
sad-log.md的步骤与候选快照,区分 continue / replan。 - roadmap:起手探测 DRAFT memo,继续已有包或明确新开;保留 task-log 历史。
- devenv:读取 JSON 与泳道 evidence,补条件后使用 continue,不把已有脚手架误标 verified。
- issues:以单文件为准;索引不一致先 reindex,终态迁移中断按 recorder 的受控路径重跑。
恢复依赖正确的文件和 Git 历史。手动重排 Task、删除计划重建、改 change 名、复制旧锚,都会破坏这种可恢复性。
14. 脚本诊断与高级用法
日常使用优先触发 skill。下面主要用于检查状态、排查阻塞,或在工具仓开发时验证接口。
14.1 在同一个 Bash 终端定位安装根
以下变量只服务于本组示例;AI 的不同工具调用未必共享 shell 状态,不能假定一次赋值会跨调用保留。
G_SKILLS_ROOT=""
for candidate in "$HOME/.agents/skills" "$HOME/.claude/skills"; do
if [ -f "$candidate/g-done/scripts/ship_gate.py" ]; then
G_SKILLS_ROOT="$candidate"
break
fi
done
if [ -z "$G_SKILLS_ROOT" ]; then
echo "找不到 gear 安装;先在工具链 checkout 跑 bash setup.sh" >&2
else
printf 'skills: %s\n' "$G_SKILLS_ROOT"
fi
确认输出有效后,在消费项目根目录继续下面的命令。这里统一使用共享安装路径,实际 skill 也有其宿主路径探测逻辑。
14.2 检查项目配置与规则源
python3 "$G_SKILLS_ROOT/g-init/scripts/init.py" config-lint --root .
bash "$HOME/.g/hack/resolve-workflow.sh" --root "$(git rev-parse --show-toplevel)" --explain
规则 resolver 成功时 stdout 是规则根;失败会给出显式告警。它不会因为消费仓残留一套本地规则,就静默把旧副本当作当前权威源。
14.3 只读查看 gate 与本次分支约定
将 change 替换成真实名称:
python3 "$G_SKILLS_ROOT/g-done/scripts/ship_gate.py" --root . --change filter-orders-by-status
python3 "$G_SKILLS_ROOT/g-done/scripts/branch_context.py" show --root . --change filter-orders-by-status
branch_context.py show 输出四项约定与 context_path。ship_gate.py --default-branch 仍可单独诊断仓库默认分支,但它不是本 change 的合并去向。
14.4 检查票依赖、预算与测试范围
python3 "$G_SKILLS_ROOT/g-implement/scripts/impl_route.py" plan-budget --plan openspec/changes/filter-orders-by-status/tickets.md
# done 列表只是参数形状;实际必须取 gate 的 done_tasks
python3 "$G_SKILLS_ROOT/g-implement/scripts/impl_route.py" frontier --plan openspec/changes/filter-orders-by-status/tickets.md --done none
python3 "$G_SKILLS_ROOT/g-implement/scripts/impl_route.py" suite-scope --root . --change filter-orders-by-status
比较收尾基准到当前提交时,使用实际保存的完整基准 SHA:
python3 <skills-root>/g-implement/scripts/impl_route.py suite-scope --root . --change <change> --base <收尾JSON.head> --head HEAD
尖括号是说明占位符,不能原样交给 shell。
14.5 检查归档同步与 ADR
python3 <skills-root>/g-done/scripts/delta_sync_check.py --archive-dir openspec/changes/archive/<实际日期>-<change>
python3 <skills-root>/g-adr/scripts/adr.py lint --root .
前者退出 1 表示同步有缺口,2 表示调用/读取错误;后者退出 1 表示 lint 红项,2 表示用法或 IO 错误。不要把它们的退出码与 gate 的退出码表混用。
14.6 查看写锚和其它命令的帮助
python3 "$G_SKILLS_ROOT/g-done/scripts/anchor_writeback.py" --help
python3 "$G_SKILLS_ROOT/g-issues/scripts/issues_v2.py" --help
python3 "$G_SKILLS_ROOT/g-adr/scripts/adr.py" --help
python3 "$G_SKILLS_ROOT/g-devenv/scripts/devenv_scaffold.py" --help
写锚是有副作用的操作,应由完成实际评审/验证的流程调用。不要通过手工补字段来“修复” REFUSE_START、UNKNOWN 或 STEP_IN_PROGRESS。
15. 升级和规则维护
15.1 升级本机工具链
标准运行位置下可以调用:
/g-upgrade
该 skill 针对 ~/.skills/g-skills 的公开运行 checkout,依序进行:
git -C "$HOME/.skills/g-skills" pull --ff-only
bash "$HOME/.skills/g-skills/setup.sh"
git -C "$HOME/.skills/g-skills" describe --tags --always --dirty
它不负责把任意开发 fork 合并成公开仓,也不应覆盖开发 checkout 的本地修改。使用其它路径时,在实际工具链 checkout 中自行完成 ff-only pull 与 setup。
本仓版本由 Git 自报,不维护需要人工同步的 VERSION 文件。
从原 sdflow 安装迁移
当前命令统一为 /g-init、/g-spec、/g-review、/g-done 等 g-* 入口;全局工具根为 ~/.g/,环境变量使用 G_HOME、G_REQUIRE_DOM 等 G 前缀。
- 在这份修改版 checkout 运行
bash setup.sh,不要运行原上游安装器代替。 - 安装器确认新入口已安装后,才清理能够确认自属的旧
sdflow-*skill 链接或带旧安装标记的复制件;第三方目录不会直接删除。新入口被占用时保留对应旧入口并报告。 - 在消费项目运行
/g-init update,刷新手册、托管入口和 schema。项目自己的配置与业务文件保留。 - 已有
.sdflow-branch.json仍兼容读取,不改写其起点、目标或历史;新写入使用.g-branch.json。 - 在途变更锁定的旧 schema ID 保留;update 为其提供使用新命令提示的兼容 schema。历史 checkpoint 的阶段名也保留读取兼容。
旧全局 ~/.sdflow/ 目录不做整目录删除,避免误删仍使用原工具的其它项目。旧名称只出现在迁移、历史兼容和来源声明中,不作为新流程的调用入口。
15.2 为什么 pull 之后还要 setup
| 改动 | Unix 上是否会通过软链立即可见 | 是否仍应重跑 setup |
|---|---|---|
| 已链接的 SKILL.md / scripts / references | 通常会 | 升级仍统一重跑,检查分发完整性 |
| 新增或删除 skill | 不会自动建/清安装项 | 是 |
~/.g/hack/ 的源脚本或页面资产 |
不会,安装的是复制件 | 是 |
| Windows 的 skill 复制件 | 不会 | 是 |
| 共享规则源 | 当前链接/指针仍正确时可见 | 升级统一重跑,避免半更新 |
只 pull 不 setup 会造成 skill 指令与全局辅助脚本版本不一致。
15.3 更新消费项目材料
在目标项目调用:
/g-init update
或:
python3 "$HOME/.agents/skills/g-init/scripts/init.py" update --root /path/to/your-project
update 刷新手册、托管入口、版本门允许的 project-local schema、忽略项与 hook / 残留检查。项目 config 的自定义内容保留,但脚本可能按 schema 版本门窄改顶层 schema 键;不能笼统理解为配置逐字节不变。
update 不自动把模板中的全部 context / rules 覆盖进已有配置。需要变更通用规则时,应读模板和现有项目配置做有意识的合并。
共享规则与 tools 运行时来自全局 canonical,所以一次 setup 后同机消费项目会读取当前共享版本;人读手册和项目 schema 是项目内材料,需要时再 update。
15.4 规则的权威源在哪里
本工具仓 g-init/assets/workflow/
→ setup 建立全局链接/指针
→ ~/.g/hack/resolve-workflow.sh 解析
→ skill 读取共享规则和 tools
消费仓 openspec/workflow/ 正常只保留 WORKFLOW-GUIDE.md。不要为了局部修改就复制整套规则进去;resolver 不把这种副本当作当前规则源。
维护规则时改工具源,必要时生成手册,再跑检查与 setup。项目特有的事实、测试命令和约束放在项目配置及文档中。
15.5 回退原则
需要回到已知良好的工具版本时,先确认运行 checkout 没有要保留的本地改动,再切到对应已知提交并重跑 setup。不要只切 Git 版本却继续使用旧 hack 复制件。
不要在长期开发中的 fork 上直接照搬回退操作;应先评估已有修改和分支状态。
16. 常见问题
| 现象 | 原因与处理 |
|---|---|
| 安装提示 ready,但 AI 找不到 skill | 检查 skipped、目标目录与 SKILL.md;确认宿主支持该发现目录,必要时重新打开会话 |
| 找得到 skill,但 checkpoint / resolver 不存在 | 全局 hack 分发不完整或只做了 pull;在实际运行 checkout 重跑 setup |
| openspec command not found | 主流程必需的 CLI 缺失;先装 CLI、检查 PATH 与 Node,再运行 spec |
| yq 已装但仍报错 | 确认是 mikefarah/yq 且版本满足要求,排除同名 Python 包或 PATH 顺序冲突 |
| init 只铺了一份手册,是否漏文件 | 正常;规则和 tools 全局共享,消费仓不复制全套 |
| update 后项目 context 没变 | 正常;不会自动用模板覆盖项目配置,需要审阅合并 |
| 在途 change 重入时询问继续还是新开 | 两种意图产物不同,需要确认;不要让 AI 静默重建已有 change |
| 设计报告写通过,done 仍 REFUSE_START | 检查是否有用户明确批准、设计锚是否由脚本写入及是否新鲜 |
| 全部复选框已勾,仍 CONTINUE_IMPL | gate 要求完成 checkpoint;读取现有实现,补真实自审与验收后再提交标签 |
| UNKNOWN 提示计划/收尾票有问题 | 核对固定标题、唯一 R-ID: all、完整依赖、计划提交窗口,不手改 gate 绕过 |
| 报告存在,但 STEP_IN_PROGRESS | 缺结论/内容锚、frontmatter 不完整,或 defer 票号未对账;按 reason 补实际步骤 |
| RERUN_STALE | 被审内容变了;重跑对应步骤,不复制旧指纹到新报告 |
| PASS 写锚要求 expected-ref | 新保护要求检查前捕获完整提交 OID;缺基准应重新检查,不能临时取 HEAD 糊过去 |
| 报告 checkpoint 拒绝源码脏改动 | 先处理源码并按实际变更重新验证;不要改用普通 add-A 模式把它夹进去 |
| pytest 退出 0,但没收集到用例 | 零用例不能作通过证据;检查发现路径、过滤器与测试命令 |
| suite-scope layers 为空 | 同时查看 domains_configured、unconfigured_layers 和 mapping,区分未配置与显式无层 |
| 复用历史票被 gate 拦住 | 四列表明确写 reuse,确认唯一文件的 id/pool;不要篡改 source_change 假装新票 |
| issue 状态成功但索引更新失败 | 单文件写入可能已经生效;按 recorder 提示重跑 reindex,避免重复 add |
| 已归档,done 仍 RUN_VERIFY | 可能尚未并入该 change 的 merge_target;读取 reason,继续收尾,不把 verdict 名字理解为必须重测 |
| skip merge 后重复调用直接完成 | 默认保留持久意图;如现在确实要合并,在调用中明确说明 |
| ff-only 失败 | 分支已经分叉或基准状态不满足;报告后按仓库策略处理,不强推或强行 reset |
| 找不到 roadmap / devenv 评审页 | 检查 render-review-page.py 与 review-page 资产是否已 setup;Markdown 仍保留,报告页面缺口 |
| 架构 lint 绿,但仍要求人确认 | lint 只检查结构,事实真实性、假设与决策仍需要人判断 |
| devenv 有 planned/scaffolded 是否失败 | 是真实未验证状态,可合法交付;按 blocked_by 补条件后 continue |
| retro 没有 token / lens 数字 | 当前流程不再采集这些锚;显示未覆盖,不通过补零或估算制造完整度 |
遇到其它故障,保留 problem / cause / fix、实际退出码、命令原文与相关路径,比一句“流程卡住了”更容易恢复。
17. 开发本项目与验证改动
17.1 仓库结构
g-skills/
├── setup.sh # 本机安装、更新与自属旧项清理
├── g-*/
│ ├── SKILL.md # skill 入口与执行契约
│ ├── scripts/ # 按需存在的确定性 helpers
│ ├── references/ # 按需加载的模板、格式与判据
│ ├── assets/ # 需要分发的规则、schema、页面资产等
│ └── tests/ # 适用 skill 的回归测试
├── hack/
│ ├── sync_principles.py # 共享通则与广审定义同步/检查
│ ├── gen_workflow_guide.py # 人读手册生成/检查
│ └── tests/ # 安装、跨文件与分发契约测试
├── test_support/ # 跨平台测试支持
├── docs/ # 流程说明与可视化地图
└── .github/workflows/ # Linux / macOS 与 Windows 检查配置
不是每个 skill 都有 scripts 或 tests;例如部分入口主要是 Markdown 编排。retro 的脚本测试位于 g-retro/scripts/tests/。
17.2 改动应该落在哪里
| 要改什么 | 优先修改 |
|---|---|
| 某 skill 的触发、步骤、停点或产物契约 | 对应 SKILL.md,必要时同步调用方 |
| 确定性的解析、状态判定与写入 | 对应 scripts / assets/hack 中的实现及行为测试 |
| 共享开发原则 | g-init/assets/hack/skill-principles.md,通过同步工具投放 |
| 全局评审方法和触发规则 | g-init/assets/workflow/ 中对应单一源 |
| 初始化注入的入口文字 | g-init/assets/snippets/ |
| project-local schema | g-init/assets/schemas/g-spec-driven/ |
| 人读完整手册 | 修改 workflow 源,再生成 WORKFLOW-GUIDE,不手改生成物 |
| skill 的安装路径或升级行为 | setup.sh 与相关安装测试 |
| 本 README 的说明 | 直接修改 README;命令与实现不一致时核对源,不拿文档强迫代码迁就 |
变更一个字段、状态、checkpoint slug 或目录名时,要搜索它的所有消费点。gate、报告 producer、复盘分类、安装复制件和测试之间可能共享这些契约。
17.3 快速检查
在工具仓根目录执行:
git diff --check
python3 hack/sync_principles.py --check
python3 hack/gen_workflow_guide.py --check
bash -n setup.sh
bash -n g-init/assets/hack/checkpoint-commit.sh
修改 workflow 源后生成手册:
python3 hack/gen_workflow_guide.py --write
python3 hack/gen_workflow_guide.py --check
共享原则需要同步时,先查看对应脚本 --help,按其支持的写入模式更新,再执行 --check。不要直接在多个 SKILL.md 的托管区块里做互相不同的改动。
17.4 Python 回归
确保所选解释器里已安装 pytest:
python3 -m pip install 'pytest>=8'
python3 -m pytest -q -rs -W error
定向验证示例:
python3 -m pytest -q -rs g-done/tests
python3 -m pytest -q -rs g-issues/tests
python3 -m pytest -q -rs g-init/tests/test_checkpoint_commit.py
python3 -m pytest -q -rs g-retro/scripts/tests
这些定向命令按子目录分别运行即可。测试使用临时仓库与临时 HOME 验证安装,不应通过手工改真实用户目录制造测试前置。
-rs 会打印跳过原因,-W error 将警告作为错误。公开发布快照缺少开发期 openspec/ 台账、CLAUDE/AGENTS 载体或当前机器不具备 Windows 真机条件时,部分测试会按条件跳过;跳过项没有获得通过证据。
17.5 评审页浏览器回归
首次准备开发依赖:
cd g-init/tests/dom
npm ci
npx playwright install chromium
cd ../../..
Linux CI 如缺浏览器系统依赖,按本仓 workflow 使用 npx playwright install --with-deps chromium。
执行:
node --test g-init/tests/review_page_pure.test.js
G_REQUIRE_DOM=1 python3 -m pytest -q -rs g-init/tests/test_review_page_dom.py
G_REQUIRE_DOM=1 会让缺 DOM 依赖成为失败,防止“浏览器测试没有跑,却因为 skip 让门禁显绿”。准备好全部依赖后,也可以带这个变量运行全仓 pytest。
页面回归使用真实生成的 HTML 与 Chromium;Playwright 仅用于本工具仓开发测试,不会变成消费项目必须安装的运行组件。
详情见 DOM 测试说明。
17.6 CI 与验证范围
CI 配置包含 Linux / macOS 的机械检查及 Windows 相关 smoke。主机械 workflow 的 push / PR 自动触发受 G_MECHANICAL_GATES 仓库变量控制,手动触发可独立运行;文件存在不表示每次提交都已经跑过。
本地一次全绿不代表所有 OS、Python 和真硬件路径都已验证。报告结果时要区分本次实际执行、条件跳过、尚未覆盖与历史兼容数据。
18. 能力边界与文档导航
18.1 当前简化版明确保留什么
- 单会话串行执行,按需读取材料与规则。
- 规格、决策纪要和实现票之间的追踪关系。
- 主变更链的设计人工批准。
- 实现自审、最终代码审与 verify 的分工。
- checkpoint 完成标签、内容新鲜度、代码 PASS 的检查基准保护。
- 真实测试证据、缺口说明、issues / ADR / hand-off。
- OpenSpec archive、delta 核验、可选 ff-only merge 与断点恢复。
18.2 没有承诺的能力
| 边界 | 读者应该怎样理解 |
|---|---|
| 内联检查共享上下文 | 多视角能降低遗漏,不保证消除作者偏置;没有自动跨模型第二意见 |
| gate 不执行语义审查或测试 | 它验证结构、身份与内容关系,不能证明报告真实或需求充分 |
| gate 以已提交内容为核心盘面 | 脏源码需由写锚和提交/合并前检查处理,不能把旧结论扩展到未提交工作树 |
| 代码域排除 openspec | 记账变化不会自动触发代码失鲜;规则、规格与测试配置的语义影响仍需执行者核验 |
| 设计新鲜度有窗口 | 主要保护进入实现的阶段,不承诺进入代码审后持续阻断每次设计文字变化 |
| 归档终态不重新验证源码 | verify 后的正常收尾不应再改源码;异常手改不能靠旧归档 PASS 自证 |
| 分支约定不负责更新远程 | origin 引用可能过时,目标解析成功不等于远程最新;明确变更目标不自动 rebase |
| project-local schema 不是自动跟随上游的分支管理器 | 没有 fork 漂移机械检测或自动 rebase,需要维护者核对升级 |
| issues 不是实施管线 | 登记问题不等于修复,真实实现仍走 change 与验证 |
| retro 的历史数据覆盖有限 | 缺锚不补零,不把提交间隔解释成精确算力成本 |
| 保留历史文件、角色和字段 | 用于安装与读取兼容,不表示当前流程重新启用旧调度架构 |
| SHIPPED 不是生产部署 | 本仓不自动完成你的应用发布、线上验证或远程 push |
18.3 继续阅读
| 文档 / 入口 | 适合查什么 |
|---|---|
| WORKFLOW-GUIDE.md | 人读的端到端流程手册,来自规则源生成 |
| workflow-map.md | 状态、skill、脚本与产物的简明映射 |
| workflow-map.html | 浏览器阅读的流程地图 |
| workflow-flowchart.html | 流程可视化 |
| workflow.md | 当前共享流程骨架 |
| trigger-catalog.md | 按技术栈和行为触发哪些规则、图表与必填项 |
| 设计清单 | base 与领域设计审规则 |
| 代码清单 | base 与领域代码审规则 |
| 代码放行口径 | P0/P1/P2 处置、实现与最终审查共同规则 |
| 配置模板 | context、rules、test-suites 与 operations 形状 |
| issues 约定 | 字段、状态、索引与 recorder 行为 |
| ADR 格式 | 长期决策记录的格式与状态更新约定 |
| DOM 测试 | 评审页依赖、运行方式与覆盖范围 |
本 README 负责解释如何理解与使用这套系统;具体执行契约以相应 SKILL.md、共享单一源和脚本行为为准。遇到不一致时应核对并修正文档,不能凭历史示例绕过当前检查。
项目介绍网站
网站源码在 site/,包含项目首页和由本 README 同源生成的完整手册。构建命令为 node site/build.mjs;本地预览与 Cloudflare Pages 部署说明见网站目录文档。
许可
Apache-2.0,见 LICENSE。