核心用法
Backstage 是一个AI辅助开发的通用项目状态管理系统，通过强制性的工作流程确保文档与现实始终保持一致。
触发命令：
- 启动模式：
backstage start、whatsup、vamos trabalhar no X—— 加载项目上下文、执行健康检查、分析变更 - 结束模式：
backstage end、boa noite、wrap up—— 同步文档、提交变更、生成胜利总结
核心流程：
1. 读取 README 中的 🤖 导航块（单一事实来源）
2. 定位所有状态文件（ROADMAP、CHANGELOG、checks/）
3. 检查 Git 分支与变更分析
4. 双重治理检查：
5. 多中心治理：全局 + 本地规则共存，本地优先
6. 自动文档同步（标记完成项、版本升级、生成 Mermaid 图表）
7. 五种状态判定：🛑 失败 / ⚠️ 不匹配 / 🧑 规划 / ✅ 进行中 / 🎉 完成
- 解释性检查（.md）：AI 读取并理解工作流规则
- 确定性检查（.sh）：Bash 执行验证脚本
显著优点
- 抗漂移设计： 强制每次会话前验证文档与现实的一致性，从根本上解决"代码与文档脱节"的慢性病
- 代谢成本优化： 通过"教一次，AI 内化"模式，将人类委托成本从 3 倍（工作+方法论+存储位置）降至 1 倍
- 多中心治理： 全局规则与项目特定规则灵活共存，既保证一致性又保留本地适应性
- 零配置迁移： 不硬编码任何路径，通过读取 README 自动发现项目结构，可在任意项目中使用
- 双模执行： 解释性规则（AI 灵活理解）与确定性脚本（严格验证）互补，兼顾智能与可靠
潜在缺点与局限性
- 脚本依赖未就绪： 当前 SKILL.md 为文档规范，底层
backstage-start.sh/backstage-end.sh等执行脚本仍处开发中 - Bash 环境依赖： 需要 awk、sed、git 等 Unix 工具链，Windows 环境需 WSL 或兼容层
- 学习曲线陡峭： 多中心治理、五种状态判定、Mermaid 图表生成等概念需要用户理解设计哲学
- 静默关闭风险： VS Code 自动关闭后必须保持沉默，否则触发"未保存更改"提示，这对 AI 代理是严格的约束
- Markdown 解析敏感： 依赖特定标记（
> 🤖、checkbox 语法），文件格式错误会导致流程中断
适合人群
- AI 原生开发者： 习惯与 AI 结对编程、愿意投入前期配置换取长期效率的开发者
- 多项目维护者： 需要统一的工作流来管理多个并行项目的技术负责人
- 文档驱动型团队： 认同"文档即代码"、追求架构优先而非补丁式开发的组织
- 个人知识工作者： 希望建立可复用的项目治理框架，减少上下文切换认知负担的自由开发者
常规风险
| 风险类型 | 描述 | 缓解措施 |
|---------|------|---------|
| **执行失败** | Shell 脚本返回非零退出码阻断流程 | Start 模式硬失败必须修复；End 模式软失败仅警告 |
| **规则冲突** | 全局与本地 checks/ 定义矛盾 | 本地优先合并策略，但需人工审查复杂冲突 |
| **Git 状态污染** | 自动提交意外包含未审查变更 | 始终经过 "Can Push?" 状态检查， grooming 模式跳过提交 |
| **AI 理解偏差** | 解释性 .md 规则被 AI 误读 | 规则文件需清晰无歧义，关键检查应配套 .sh 脚本 |
| **沉默协议违规** | End 流程后 AI 额外输出导致 VS Code 弹窗 | 严格实现 `[STAY SILENT]` 终止条件 |