已经实现、验证且仍然有效的能力说明。新项目在第一个 Change 归档时才会出现。
AGENT SKILL · 从这里开始安装、接入、发出第一条任务，
安装、接入、发出第一条任务，
三步开始使用 SpecTrail。
SpecTrail Skill 安装在你的项目里，由 Codex 或 Claude Code 在对话中使用。它让 Agent 先和你对齐目标与验收条件，再规划、实现、验证，并把这些记录提交到仓库。只用 Skill 就能完整工作，不需要先部署工作台或启用原型。
第 1 步 · 在终端中
在项目根目录安装 Skill。
准备：Git、Node.js 24 或更新版本、Codex 或 Claude Code，以及要使用 SpecTrail 的 Git 仓库。
打开终端，进入目标仓库的根目录，选择你使用的 Agent，复制命令执行：
Codex · 项目内安装
npx skills add iTgo-lyq/spec-trail --skill spec-trail --agent codex --copy -y在目标 Git 仓库的根目录执行
Claude Code · 项目内安装
npx skills add iTgo-lyq/spec-trail --skill spec-trail --agent universal claude-code --copy -y在目标 Git 仓库的根目录执行
这条命令一次装好 SpecTrail 共享 Skill 与 Claude Code 入口，安装后照常在 Claude Code 中使用。
这条命令一次装好 SpecTrail 共享 Skill 与 Claude Code 入口，安装后照常在 Claude Code 中使用。
接下来会发生什么：安装器把 Skill 文件复制到项目中，供所选 Agent 使用。
你需要做：用 git status 确认项目中新增了 Skill 文件，把它们随项目提交，协作者就能使用同一套规则。然后在这个项目里打开 Codex 或 Claude Code，进入第 2 步。
第 2 步 · 在 Agent 对话中
让 Agent 把项目接入工作流。
在这个项目的 Agent 对话里发送：
使用 spec-trail 为当前项目接入工作流，检查默认分支和现有提交校验。
这段提示词在 Codex 和 Claude Code 中都可以直接发送，开头的 spec-trail 用来指定 Skill。在 Claude Code 中也可以输入 /spec-trail 后接任务，例如 /spec-trail 为当前项目接入工作流，见 Claude Code Skills 文档。
接下来会发生什么：Agent 确认项目的默认分支（通常是 main，改动都在单独分支上进行），把 SpecTrail 的记录校验接入项目的提交检查并实际运行一次，然后提交这些接入改动。
你需要做：回答 Agent 关于分支和提交检查的问题；项目还没有提交检查时，和它商定接入方式。查看并确认它提交的接入改动。每个项目只需接入一次，协作者新克隆仓库后按项目约定在本机启用提交检查。
第 3 步 · 在 Agent 对话中
说出一项具体改动，和你的验收期待。
接入完成后，在同一个项目里描述你想完成的改动。目标越具体、验收期待越明确，Agent 需要追问的就越少。例如：
使用 spec-trail 实现订单 CSV 导出：支持当前筛选结果，导出字段与列表一致。先整理需求和验收条件，再推进实现。
接下来会发生什么：Agent 先查看代码和已有记录，说明它理解的目标、估计的改动规模和大致方案。你确认后，它把这项改动建成一个 Change：在单独的 change/<id> 分支上写下需求和验收条件，再逐个任务实现、运行验证，把代码、进度和验证结果一起提交推送。中等及以上的改动，动手前还会请你确认需求、技术方案和计划。
你需要做：确认方向和规模，在 Agent 请求确认时阅读对应文档，并告诉它项目的测试、部署和合入约定。小改动由 Agent 对照验收条件自验收并在记录中注明，其他规模需要你实际验收。归档后由你决定直接合入 main、发起 PR 还是暂不处理。各规模的确认点见进阶：流程与规模。
记录保存在哪里
三类记录，分别回答三个问题。
进行中的改动：目标、方案、任务、进度和验证证据。
完成的 Change 整体移到这里，保留验收依据和原型引用，只读保存。
docs/project/ ├── workflow.json ├── specs/<capability>/spec.md ├── changes/<change-id>/ │ ├── change.json │ ├── requirement.md │ └── 按改动规模补充的方案、计划与证据 └── archive/YYYY-MM-DD-<change-id>/
change.json 记录进度状态，由 Agent 用 Skill 自带的命令更新；Markdown 记录正文和证据；Git 保存历史。只有提交并推送的记录，协作者和工作台才能看到。
进阶 · 流程与规模
改动越大，确认点越多。
你不需要自己判断规模。Agent 会根据改动范围给出建议规模和依据，由你确认；之后有新证据时可以调整。
| 规模 | 大致适用 | 你参与的确认 |
|---|---|---|
| Small | 局部改动，多个模块共同依赖的接口和数据结构不变，通常一个任务 | 确认方向；Agent 自验收后归档（你也可以要求人工验收） |
| Medium | 实质改变共同依赖的接口或数据结构，或实现范围较大、涉及多个模块 | 确认需求，再一起确认技术方案和计划；默认有独立评审，最后实际验收 |
| Large | 实现规模更大，或有多项需分阶段集成的交付 | 分别确认需求、技术方案和计划；独立评审（或由你亲自评审）后实际验收 |
| XLarge | 需要拆成可独立推进和验收的子 Change | 确认整体方案与拆分；每个子 Change 按自身规模推进 |
以下情况不需要建立 Change：问答、讨论、只读调查或评审，以及不改变产品行为的拼写、注释、格式修正。具体判断标准见 主 Skill 文档。
更新与扩展
更新 Skill，按需添加其他模块。
在项目根目录运行以下命令，更新项目内安装的 Skill：
更新项目内 Skill
npx skills update spec-trail -p -y更新会改动项目内的 Skill 文件，用 git diff 查看差异后随项目提交。
想在浏览器里查看记录，了解 OpenFolio 工作台；改动涉及界面设计时，启用 原型管理。两者都基于同一份仓库记录，不改变只用 Skill 的工作方式。