# Zy Track

> 轻量级需求追踪，目标锚定，跨会话连续性

- Skill: `ian-zy1/zy-track` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ian-zy1/zy-track`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ian-zy1/zy-track/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ian-zy1 (https://skillmd.com/u/ian-zy1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ian-zy1/zy-track

---


# zy-track

> 轻量级需求追踪，目标锚定，跨会话连续性

## When to Use

- 用户说 `/zy-track`、`继续`、`/zy-track new/edit/status/resume/done/update`
- 用户开始一个新的多会话开发任务时，主动建议使用
- 用户说"我要做XX"且这个任务明显跨会话时

## 触发词

| 命令 | 功能 |
|------|------|
| `/zy-track init` | 初始化项目 |
| `/zy-track new 需求描述` | 新建需求（自动 init） |
| `/zy-track edit NNN` | 编辑需求（范围、标准、任务） |
| `/zy-track status` | 增强概览（含过期检测） |
| `/zy-track resume [NNN]` | 恢复需求（目标锚定 + 范围确认） |
| `/zy-track done 001` | 归档 |
| `/zy-track update` | 进度更新 |
| `继续` | 等同 `/zy-track resume` |

## 目录结构

```
.project/
├── CONTEXT.md                    # 项目技术上下文
├── pitfalls.md                   # 实战踩坑记录
├── requirements/{NNN}-{slug}.md  # 活跃需求
└── archive/                      # 归档需求（含完整历史）
```

## Quick Reference

| 模板 | 文件 |
|------|------|
| 需求模板 | @templates/requirement.md |
| 项目上下文模板 | @templates/CONTEXT.md |
| 踩坑模板 | @templates/pitfalls.md |

## 核心原则

- **默认跳过**：不自动触发，只在用户请求时执行
- **零仪式**：最小化交互，不问多余问题
- **目标锚定**：每次 resume 重新读取目标和范围外，确认后才开始
- **人工驱动**：所有关键决策由用户确认

## 流程

### init — 初始化项目

1. 检查 `.project/` 是否存在
2. 创建目录：`mkdir -p .project/requirements .project/archive`
3. 检测项目类型（三层策略）：
   - Layer 1: 扫描代码库配置文件（package.json, go.mod, pom.xml...）
   - Layer 2: 交叉参考 README（标注置信度）
   - Layer 3: 询问用户填补缺口
4. 生成 CONTEXT.md 和空 pitfalls.md（使用上方模板）
5. 用户确认

### new — 新建需求

1. 自动 init（如果 `.project/` 不存在）
2. 计算序号（跨 requirements/ 和 archive/）
3. 自动生成 slug（如 "实现微信支付" → wechat-pay）
4. 确认文件名：`{NNN}-{slug}.md`
5. 填充模板（使用上方需求模板）
6. 需求类型检测：
   - 字段透传类（"展示XX"、"显示XX字段"、"透传XX"）→ 自动用 explore agent 追踪完整映射链路（SQL → DTO/Entity → 转换层 → VO），填入"技术链路"段落
   - 其他类型 → 跳过
7. 展示创建的文件
8. **联动建议**：如果需求较复杂或涉及架构决策，主动建议 `"需求文档已创建。可以用 /zy-xr {file} 做交叉评审验证完整性。"` 小需求不推

**粒度规则**：一个需求应在 1-5 个会话内完成。太小用 todo，太大则拆分。

### resume — 恢复需求（核心锚定机制）

1. 读取需求文件
2. **检测未处理的交叉评审**：检查同目录下是否存在 `{NNN}-{slug}.xr.md`，且需求进度记录中没有对应的"修订状态: 已采纳"。如果有：
   - 显示评审摘要（从进度记录中的 xr 条目提取）
   - 提醒：`"⚠️ 此需求有未采纳的交叉评审结果，建议先查看 .xr.md"`
3. 检测未记录的 git 提交
4. 展示：目标 + 范围外 + 未完成标准 + 上次进度 + 未完成任务
5. 确认本次会话范围
6. 开始工作——目标和范围外作为护栏

### edit — 编辑需求

1. 读取需求文件
2. 确认修改内容
3. 展示 当前值 → 新值
4. 在关键决策表追加变更记录
5. 自动追加进度记录（含变更说明、原因、影响）
6. 更新需求字段

### status — 状态概览

1. 列出 requirements/ 文件
2. 每个需求：目标 + 完成标准进度 + 上次更新时间
3. CONTEXT.md 过期检测（检查引用的配置文件是否存在）
4. 增强摘要：
   - 进度条：████████░░░░░░
   - 状态标记：⚠️ 超过7天 / 🆕 新建 / 🔄 当天更新

### update — 进度更新

1. 追加进度记录（永不覆盖）
2. 更新任务分解复选框
3. 偏差检查：是否偏离目标？是否越界？
4. 询问是否记录新 pitfall
5. **联动建议**：`"本次进展已记录。要 /zy-bak 备份当前会话吗？"`

### done — 归档

1. 验证所有完成标准已勾选
2. 添加归档总结：目标达成、遗留项、经验沉淀
3. 同步经验到 pitfalls.md
4. 移动到 archive/
5. **联动建议**：`"需求 {NNN} 已归档。建议 /zy-bak 备份——归档是天然的最佳备份时机。"`

## Common Traps

1. **不要把 todo 和需求混淆** — todo 是会话内任务，需求是跨会话目标。一个需求太大就拆分，太小就用 todo
2. **不要在归档前跳过完成标准验证** — 所有复选框必须勾选才能归档
3. **不要让需求膨胀到 5 个会话以上** — 太大则拆分为多个需求
4. **进度记录永远追加，不要覆盖** — 即使记录有误也是历史，纠正在新行追加

## 约束

- 不自动触发
- 不覆盖进度记录——始终追加
- 不单独追踪任务——反映到任务分解
- 不在单个文件中混用语言
- 不归档时不写归档总结
- 不编辑需求字段时不记录关键决策

## Related Skills

- **zy-session**：update/done 后建议备份；归档是天然的最佳备份时机
- **zy-xr**：new 后建议对需求文档做交叉评审；resume 时检测未采纳的评审结果

## 联动协议

本 skill 与其他 zy-skills 通过以下数据契约联动：

| 联动 | 方向 | 触发时机 | 数据契约 |
|------|------|---------|---------|
| 新需求建议评审 | track → xr | `new` 完成后 | 需求文件路径传递给 `/zy-xr` |
| 评审结果写入进度 | xr → track | xr 检测到 `.project/requirements/` 路径时 | 评审摘要追加到 `## 进度记录`，完整评审写入 `.xr.md` |
| resume 检测未处理评审 | track → xr | `resume` 读取需求时 | 检查 `.xr.md` 是否存在且无"已采纳"记录 |
| 进展后建议备份 | track → session | `update` / `done` 完成后 | 建议文字，用户确认后执行 |
| 备份含需求快照 | session → track | `/zy-bak` 时 | 需求列表 + 进度写入备份文件 |