核心用法
backstage 是一个面向 AI 辅助开发的通用项目工作流管理技能,通过强制上下文感知来防止"项目漂移"。它采用双模式设计:
Start 模式(工作开始):触发词包括 "backstage start"、"vamos trabalhar no X"、"whatsup"。自动读取 README 中的 🤖 导航块定位状态文件(ROADMAP、CHANGELOG、HEALTH、POLICY),检查当前 Git 分支,分析变更并分类(patch/minor/major),执行 HEALTH 检查(硬失败策略),自动更新文档(勾选 ROADMAP、追加 CHANGELOG),生成开发者上下文摘要,最后提示提交。
End 模式(工作结束):触发词包括 "backstage end"、"boa noite"、"wrap up"。执行软失败策略的健康检查,列出待修复项,简短胜利总结(最多3项成就),进行身体状态检查(饥饿/口渴/疲劳),最后静默关闭 VS Code。
显著优点
1. 防漂移架构:强制在代码提交前验证文档-现实一致性,解决"地图≠领土"的信任侵蚀问题
2. 代谢成本优化:将原本 3x 成本(原始工作+解释方法论+定义知识去向)压缩为 1x
3. 多中心治理:支持全局规则(backstage/global/)与项目规则(backstage/)的层级覆盖,项目级优先
4. 通用无侵入:不硬编码路径,通过 README 的 🤖 块动态发现,适用于任何项目
5. 状态机清晰:5 种明确结局状态(🛑失败/⚠️不匹配/🧑梳理/✅进行中/🎉完成),推送权限与状态绑定
潜在缺点与局限性
1. 草案状态: SKILL.md 明确标注为 DRAFT,流程图过于复杂(待简化),emoji 注释待补充
2. 脚本未实现:backstage-start.sh 和 backstage-end.sh 仅为规范引用,实际执行依赖外部脚本
3. 边缘情况未覆盖:无 Git、无 README、文件损坏等场景的行为未定义
4. VS Code 强耦合:End 模式的关闭编辑器逻辑使用 macOS 专属 osascript,跨平台支持存疑
5. 学习成本:需要理解"代谢成本"、"多中心治理"等特定术语体系
适合人群
- 使用 AI 辅助编程的独立开发者或小团队
- 需要维护多个项目、频繁上下文切换的"多项目并行"场景
- 重视文档与代码同步、厌恶技术债务累积的纪律型团队
- 已采用或愿意采用"Epic 分支"工作流的 Git 用户
常规风险
- 误关闭风险:End 模式的
[STAY SILENT]要求若被违反,会导致 VS Code "未保存更改"弹窗,可能丢失工作 - 健康检查阻塞:Start 模式的硬失败策略可能在紧急修复时成为阻碍(虽然设计上 Epic 分支为软失败)
- 文档膨胀:自动更新的 ROADMAP/CHANGELOG 若缺乏定期人工整理,可能导致信息过载
- AI 幻觉:依赖 AI 正确解析 🤖 导航块和状态文件格式,格式偏差可能导致流程中断