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 时	需求列表 + 进度写入备份文件