核心定位
Backstage Skill 是一套反漂移（Anti-Drift）的项目治理协议，专为 AI 辅助开发设计。它通过强制性的「四文件体系」（ROADMAP.md、POLICY.md、HEALTH.md、CHANGELOG.md）确保代码与文档始终同步，解决「人类教一遍，AI 重复问」的代谢成本问题。
核心用法
触发方式：
- Start 模式：
backstage start、vamos trabalhar no X、whatsup— 工作前自动加载上下文 - End 模式：
backstage end、boa noite、wrap up— 工作后自动归档与身体检查
执行流程：
1. 读取 README 的 🤖 导航块，定位所有状态文件
2. 检查 Git 分支与变更，分析 patch/minor/major 影响
3. 关键步骤： checks.sh 统一执行 POLICY + HEALTH 规则
4. 自动同步文档（更新 ROADMAP 勾选框、CHANGELOG 版本、Mermaid 图表）
5. 生成 5 状态报告（🛑 Failed / ⚠️ Mismatch / 🧑 Grooming / ✅ Progress / 🎉 Complete）
- 可执行规则（代码块、文件结构）→ Shell 直接执行
- 解释性规则（质量标准、上下文判断）→ AI 解读并行动
显著优点
- 代谢成本优化： 将「教 AI 做事」的三倍工作量（执行+方法论+存储位置）压缩为一次投资
- 多中心治理： 支持全局规则 + 项目规则叠加，项目规则冲突时优先
- 零硬编码： 通过 README 导航块自发现，可移植到任何项目
- 自动图表生成： 解析 ROADMAP 自动生成 Mermaid 流程图并同步到所有文件
- 身体检查机制： 结束会话时提醒饥饿/口渴/疲劳，关注开发者身心健康
潜在局限
- Bash 依赖： 需要 Unix-like 环境（bash、awk、sed、git），Windows 需 WSL
- 规则冲突风险： 解释性规则由 AI 解读，不同模型理解可能存在偏差
- 静默关闭陷阱：
close VS Code后必须保持完全静默，否则触发未保存提示 - 模板缺失： 新项目需手动创建四文件，暂无自动模板生成
- 版本 0.3.5： 仍处于生产早期，文档标注「需要细化」
适合人群
- 多项目并行开发者： 需要快速切换上下文而不丢失状态
- AI 结对编程用户： 厌倦了每会话重复解释项目结构
- 文档驱动开发者： 认同「代码即文档」但希望自动化同步
- 团队技术负责人： 需要可复用的项目治理模板
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| **规则覆盖错误** | 项目 POLICY 与全局 POLICY 冲突时，意外采用全局规则 | 明确标注 `project wins on conflict` 逻辑 |
| **HEALTH 检查误报** | 解释性规则被 Shell 误判为可执行 | `checks.sh` 已实现自动分离逻辑 |
| **Git 状态污染** | 自动提交意外包含未审查代码 | 需用户显式确认 push 步骤 |
| **VS Code 未保存阻塞** | 关闭命令后任何输出触发弹窗 | 严格遵循 `[STAY SILENT]` 协议 |
| **模型幻觉图表** | AI 生成错误 Mermaid 语法 | 依赖 `parse-roadmap.sh` 结构化提取 |
技术架构亮点
该 Skill 实现了罕见的「人机混编」执行模型：Markdown 文件作为人类可读提示 + AI 可解析规则，Shell 脚本作为确定性执行器，两者通过明确的 🤖 标记和 checks.sh 桥接，形成可审计的治理闭环。