AGENT SKILL · 必需
SpecTrail Skill
帮你做：在 Agent 对话里，让 Agent 先对齐目标和验收条件，再规划、实现、验证，并把每一步的记录提交到仓库。
什么时候用：从第一项改动开始。这是唯一必需的部分。
安装并发出第一条任务在 Codex / Claude Code 中使用 · 记录写进你的仓库
Codex / Claude Code 的工作流 Skill先对齐目标，
先对齐目标，
再让 Agent 动手，
记录都留在 Git 里。
SpecTrail 是给 Codex、Claude Code 用户的工作流 Skill，装在你的项目仓库里。你说出想做的改动，Agent 先和你确认目标与验收条件，再规划、实现、验证；需求、方案、任务和验收记录都提交到仓库，之后随时可以回看。
只装 Skill 就能完整使用记录保存在你的 Git 仓库工作台和原型按需添加
示例 · 订单导出
订单导出 Skill · 仓库中的记录
docs/project/
specs/当前能力说明
changes/export-orders/这次改动
requirement.md目标与验收条件
technical.md方案与取舍
plan.md任务安排
change.json进度状态
archive/已完成的改动
执行中
stage: execution代码、进度和验证结果一起提交OpenFolio 工作台 · 只读
Specs
Changes
原型
订单导出
只读展示已推送的任务进度和验证记录。
需求与方案完成
导出数据完成
浏览器验证进行中
export-orders同一项改动的任务、验证与原型集中查看订单页面 原型 · 固定版本
订单列表导出 CSV
| 订单 | 金额 | 状态 |
|---|---|---|
| #DEMO-001 | ¥ 280.00 | 已完成 |
| #DEMO-002 | ¥ 148.00 | 待发货 |
| #DEMO-003 | ¥ 620.00 | 已完成 |
示例数据桌面 / iPad / 手机
固定版本 → 本次改动三个模块，按需选用
先用 Skill，
需要时再加另外两个。
只安装 Skill 就能完整推进和记录改动。工作台和原型管理是附加选择，用不用都不影响 Skill 的工作方式。
WORKBENCH · 可选
OpenFolio 工作台
帮你做：在浏览器里查看已推送的记录：项目现在有哪些能力、每项改动进行到哪一步、验证了什么，以及关联的原型。只读，不改仓库。
什么时候用：想让不打开代码的协作者也能看进度，或集中回看历史改动时。需要团队已部署的 OpenFolio 实例。
了解如何获得入口单独部署的网页服务 · 用你自己的 GitHub token 只读访问
PROTOTYPES · 可选
原型管理
帮你做：改动涉及界面时，让 Agent 用示例数据做出可点击的原型，并为每项改动保存对应版本，讨论和验收都对着同一个版本。
什么时候用：需要讨论页面或组件设计时再启用。它随 Skill 一起安装，无需另外下载。
打开示例，了解如何启用Skill 的可选部分 · 发布到 OpenFolio、自建静态托管或 Git
三个模块，共用同一份记录：你的 Git 仓库。
Skill 写入记录，工作台只读展示，原型版本跟随对应的改动保存。
Specs 当前能力Changes 改动Archive 归档Prototypes 原型一项改动会经历什么
从一句目标，到可回看的交付。
在 SpecTrail 里，一次有目标、范围和验收条件的改动叫作一个 Change；已经实现并验证过的当前能力说明叫作 Specs。
改动大小不同，流程有何不同
- 01
对齐目标
你描述想做的改动。Agent 先查看代码和已有记录，整理目标、范围和验收条件，估计改动大小，请你确认方向。
- 02
方案与任务
小改动直接写明方案要点和任务；较大的改动先写技术方案和计划，由你确认后再动手。
- 03
实现并验证
Agent 逐个任务实现并运行验证，把代码、进度和验证结果一起提交推送。
- 04
验收与归档
小改动由 Agent 对照验收条件自查；较大的改动等你验收。之后更新 Specs，把这次 Change 归档保存。
第一步：安装
在你的项目里，
安装 SpecTrail。
打开终端，进入要使用 SpecTrail 的 Git 仓库根目录，按你使用的 Agent 复制命令执行。需要 Git 和 Node.js 24 或更新版本。
安装后回到 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 就能完整使用；工作台和原型管理可以以后再加。
开始前常见问题
先装 Skill，
其余按需添加。
只安装 Skill 可以使用吗？
可以。Skill 不依赖工作台或原型管理。所有记录都是仓库里的 Markdown 和 JSON 文件，在编辑器或 GitHub 上就能直接阅读。
支持哪些 Agent？
本站提供 Codex 和 Claude Code 的安装命令；也可以为其他支持 Agent Skills、能运行命令并操作 Git 的客户端安装。Skill 指令目前使用中文，适用于单个 Git 仓库及同仓库的分支和 worktree。
小改动也要写很多文档吗？
不会。问答、讨论、只读调查，以及不改变行为的拼写、注释、格式修正，都不需要建立 Change。小改动只写一份需求（含方案要点和任务）；改动越大，才需要技术方案、计划和评审记录。
Agent 会自己提交、合入代码吗？
Agent 会在这项改动自己的分支上提交并推送进度。合入 main、创建 PR 或发布都按你的授权进行：归档后，Agent 会问你直接合入、发起 PR，还是暂不处理。
Agent 会替我验收吗？
只有小改动默认由 Agent 对照验收条件自验收，并在记录中注明是自验收；你也可以要求人工验收。中等及以上的改动必须等你实际验收，测试通过不等于验收。
工作台会修改我的仓库吗？
不会。OpenFolio 只读取已经提交推送的记录。需求、任务和进度由 Agent 在仓库中维护，推送后刷新工作台即可看到。
原型会用到真实数据吗？可以公开分享吗？
原型使用示例数据演示页面和组件交互，不连接真实业务服务。发布后的原型地址通常可以公开访问，因此只放适合公开的演示内容；工程记录则按各自的仓库权限读取。
从一项具体的改动开始。
安装 Skill，在 Agent 里说出你想完成的改动和验收期待。