教程概述
系列索引: gstack 教程系列
发布后，完成闭环：/document-release 更新文档，/retro 反思什么有效，/learn 捕获模式供下次使用。
你将学到
- ✅
/document-release文档同步 - ✅ 过时文档检测
- ✅
/retro每周工程回顾 - ✅ 个人分解和趋势
- ✅
/learn记忆管理 - ✅ 发布后工作流
为什么需要发布后文档？
文档漂移问题
flowchart LR
A[代码变更] --> B[文档未更新]
B --> C[新开发者困惑]
C --> D[错误假设]
D --> E[Bug]
style B fill:#ffcccc
style E fill:#ffcccc
/document-release 解决方案
flowchart TD
A[/document-release] --> B[扫描变更文件]
B --> C[查找相关文档]
C --> D[检测漂移]
D --> E[更新文档]
E --> F[提交变更]
style A fill:#e1f5ff
style F fill:#e8f5e9
/document-release — 同步文档与代码
更新什么
| 文件 | 何时更新 |
|---|---|
| README.md | 新功能、设置变更、新命令 |
| ARCHITECTURE.md | 结构变更、新模块 |
| CONTRIBUTING.md | 新工作流、前置条件变更 |
| CLAUDE.md | AI 上下文变更、新模式 |
| API.md | 新端点、参数变更 |
| CHANGELOG.md | 每次发布 |
使用
/document-release
输出：
正在扫描文档漂移...
┌─────────────────────────────────────────────────────────────┐
│ 文档发布 │
├─────────────────────────────────────────────────────────────┤
│ 变更文件: 12 │
│ 相关文档: 4 │
│ │
│ 📄 README.md │
│ ─────────────────────────────────────────────────────────────│
│ 部分: Getting Started │
│ 问题: 引用旧包名 │
│ │
│ 旧: npm install mypkg-v1 │
│ 新: npm install mypkg-v2 │
│ │
│ 🔧 已更新 │
│ │
│ 📄 ARCHITECTURE.md │
│ ─────────────────────────────────────────────────────────────│
│ 部分: 模块概述 │
│ 问题: 缺失新 auth 模块 │
│ │
│ 已添加： │
│ - src/auth/ - 认证系统（新） │
│ - login.ts - 登录流程 │
│ - session.ts - 会话管理 │
│ │
│ 🔧 已更新 │
│ │
│ 📄 CHANGELOG.md │
│ ─────────────────────────────────────────────────────────────│
│ 已添加条目： │
│ │
│ ## 2026-04-07 - v2.1.0 │
│ │
│ ### 添加 │
│ - 带 OAuth2 支持的认证系统 │
│ - 安全 cookie 的会话管理 │
│ │
│ ### 变更 │
│ - 包从 v1 更新到 v2 │
│ │
│ 🔧 已更新 │
│ │
│ 📄 CLAUDE.md │
│ ─────────────────────────────────────────────────────────────│
│ 问题: 缺失 auth 模式 │
│ │
│ 已添加： │
│ - Auth 流程: 使用 /login 端点，不是 /auth │
│ - Sessions: API 调用前始终检查 │
│ - 测试: 用 mockSession() 在测试中模拟会话 │
│ │
│ 🔧 已更新 │
└─────────────────────────────────────────────────────────────┘
文档已更新: 4 个文件
提交: docs: update documentation for v2.1.0
过时文档检测
检测文档何时与代码不匹配：
| 检查 | 检测 |
|---|---|
| 过时命令 | 命令引用已删除的代码 |
| 缺失模块 | 新目录未记录 |
| 错误文件路径 | 重命名的文件仍被引用 |
| 已废弃 API | 仍记录为当前 |
| 错误示例 | 示例代码与实际不符 |
扫描什么
project/
├── README.md ✅ 始终扫描
├── ARCHITECTURE.md ✅ 始终扫描
├── CONTRIBUTING.md ✅ 始终扫描
├── CLAUDE.md ✅ 始终扫描
├── docs/
│ ├── API.md ✅ 如果存在
│ ├── SETUP.md ✅ 如果存在
│ └── DEPLOY.md ✅ 如果存在
└── CHANGELOG.md ✅ 始终更新
/retro — 工程回顾
分析什么
- 上次回顾以来的提交
- 合并的 PR
- 添加/删除的测试
- 修复的 bug
- 性能变化
使用
/retro
输出：
正在运行工程回顾...
┌─────────────────────────────────────────────────────────────┐
│ 每周回顾 │
│ 期间: 2026-03-31 至 2026-04-07 │
├─────────────────────────────────────────────────────────────┤
│ 📊 概要 │
│ ─────────────────────────────────────────────────────────────│
│ 提交: 47 │
│ 合并 PR: 12 │
│ 添加测试: 34 │
│ 修复 Bug: 8 │
│ 覆盖率: 78% → 82% (+4%) │
│ │
│ 📊 个人分解 │
│ ─────────────────────────────────────────────────────────────│
│ @alice │
│ 提交: 18 │
│ PR: 5 │
│ 测试: 15 │
│ 发布连续天数: 12 天 │
│ 重点: 认证系统 │
│ │
│ @bob │
│ 提交: 15 │
│ PR: 4 │
│ 测试: 12 │
│ 发布连续天数: 8 天 │
│ 重点: API 优化 │
│ │
│ @charlie │
│ 提交: 14 │
│ PR: 3 │
│ 测试: 7 │
│ 发布连续天数: 5 天 │
│ 重点: Bug 修复和 QA │
│ │
│ 📊 测试健康趋势 │
│ ─────────────────────────────────────────────────────────────│
│ 覆盖率趋势: ↑ +4% │
│ 不稳定测试: 2（从 5 减少） │
│ 测试运行时间: 45s（从 52s 减少） │
│ │
│ 📊 做得好的 │
│ ─────────────────────────────────────────────────────────────│
│ ✅ 认证系统按时发布 │
│ ✅ 覆盖率提升 4% │
│ ✅ 零生产事故 │
│ ✅ PR 审查时间: 平均 4 小时 │
│ │
│ 📊 需改进 │
│ ─────────────────────────────────────────────────────────────│
│ ⚠️ 仍有 2 个不稳定测试 │
│ ⚠️ API 响应时间在仪表板上 +5% │
│ ⚠️ 错误路径缺失测试 │
│ │
│ 📊 行动项 │
│ ─────────────────────────────────────────────────────────────│
│ 1. 修复不稳定测试 (auth.test.ts, api.test.ts) │
│ 2. 分析仪表板 API 性能 │
│ 3. 添加错误路径测试（目标: 85% 覆盖） │
└─────────────────────────────────────────────────────────────┘
回顾已保存: .gstack/retros/2026-04-07.md
全局回顾
跨所有项目运行：
/retro global
输出：
正在跨所有项目运行全局回顾...
┌─────────────────────────────────────────────────────────────┐
│ 全局回顾 │
│ 项目: 4 | 期间: 最近 7 天 │
├─────────────────────────────────────────────────────────────┤
│ 📊 跨项目统计 │
│ ─────────────────────────────────────────────────────────────│
│ 总提交: 142 │
│ 总 PR: 38 │
│ 总添加测试: 89 │
│ 覆盖率 >80% 的项目: 3/4 │
│ │
│ 📊 按项目 │
│ ─────────────────────────────────────────────────────────────│
│ myapp: 47 提交, 82% 覆盖 │
│ api-server: 52 提交, 85% 覆盖 │
│ dashboard: 28 提交, 75% 覆盖 ⚠️ │
│ mobile-app: 15 提交, 88% 覆盖 │
│ │
│ 📊 AI 工具使用 │
│ ─────────────────────────────────────────────────────────────│
│ Claude Code 会话: 156 │
│ Codex 调用: 42 │
│ /review 运行: 28 │
│ /qa 运行: 15 │
│ │
│ ⚠️ 需要关注 │
│ ─────────────────────────────────────────────────────────────│
│ dashboard: 覆盖率低于 80% │
│ 运行: cd dashboard && /ship │
└─────────────────────────────────────────────────────────────┘
/learn — 记忆管理
存储什么
| 类别 | 示例 |
|---|---|
| 模式 | “API 验证始终使用 zod” |
| 陷阱 | “不要使用没有 deps 数组的 useEffect” |
| 偏好 | “使用 Tailwind 而非 CSS modules” |
| 约定 | “API 路由放在 src/api/” |
| 注意事项 | “环境变量需要 NEXT_PUBLIC_ 前缀” |
使用
添加学习
/learn pattern: "处理前始终用 zod 验证 API 输入"
查询学习
/learn ask "我们的验证模式是什么？"
输出：
正在查询已学知识...
┌─────────────────────────────────────────────────────────────┐
│ 已学知识 │
├─────────────────────────────────────────────────────────────┤
│ 模式: API 验证 │
│ ─────────────────────────────────────────────────────────────│
│ "处理前始终用 zod 验证 API 输入" │
│ │
│ 相关： │
│ - 陷阱: "永远不要信任未验证的 request.body" │
│ - 约定: "验证模式放在 src/schemas/" │
│ - 模式: "用 .parse() 抛出异常，.safeParse() 检查" │
│ │
│ 添加于: 2026-03-15 │
│ 使用次数: 12 │
└─────────────────────────────────────────────────────────────┘
列出所有学习
/learn list
输出：
列出所有已学知识...
┌─────────────────────────────────────────────────────────────┐
│ 已学知识（15 条） │
├─────────────────────────────────────────────────────────────┤
│ 模式 (6) │
│ ─────────────────────────────────────────────────────────────│
│ 1. 用 zod 进行 API 验证 │
│ 2. 用 Result 类型处理错误 │
│ 3. 用 React Query 获取数据 │
│ 4. 用 Tailwind 样式 │
│ 5. TypeScript 严格模式 │
│ 6. 每个修复一个原子提交 │
│ │
│ 陷阱 (5) │
│ ─────────────────────────────────────────────────────────────│
│ 1. useEffect 没有 deps 数组 │
│ 2. 在客户端代码存储密钥 │
│ 3. React 中直接操作 DOM │
│ 4. 未验证的环境变量 │
│ 5. 异步函数中的同步操作 │
│ │
│ 约定 (4) │
│ ─────────────────────────────────────────────────────────────│
│ 1. API 路由: src/api/ │
│ 2. 组件: src/components/ │
│ 3. 测试: tests/ 镜像结构 │
│ 4. PR 标题: 类型: 描述 │
└─────────────────────────────────────────────────────────────┘
/learn 何时自动触发
- 修复重复 bug 后 → 添加陷阱
- 建立模式后 → 添加模式
- PR 审查反馈后 → 添加约定
/retro行动项后 → 添加待办
发布后工作流
完整序列
flowchart TD
A[/land-and-deploy] --> B[/canary]
B --> C[/benchmark]
C --> D[/document-release]
D --> E[/retro]
E --> F[/learn]
F --> G[完成]
style A fill:#e8f5e9
style D fill:#fff3e0
style G fill:#e1f5ff
命令
# 1. 文档发布内容
/document-release
# 2. 运行回顾
/retro
# 3. 捕获本周的学习
/learn list # 查看当前知识
# 4. 添加发现的任何新模式
/learn pattern: "发布期间发现的新模式"
# 5. 准备下一个 sprint
示例：发布后工作流
场景
刚发布带认证系统的 v2.1.0。
命令
# 步骤 1: 更新文档
/document-release
# 步骤 2: 运行回顾
/retro
# 步骤 3: 捕获学习
/learn pattern: "Auth: 用 httpOnly cookies 存储会话 token"
/learn pitfall: "不要在 localStorage 存储会话（XSS 风险）"
# 步骤 4: 检查全局健康
/retro global
回顾输出
回顾行动项：
1. 修复不稳定的 auth 测试
2. 添加仪表板性能分析
3. 覆盖率提升到 85%
下次发布前运行：
- /qa --focus auth
- /benchmark --compare
技能快速参考
| 命令 | 用途 | 输出 |
|---|---|---|
/document-release |
同步文档与代码 | 更新文档，提交 |
/retro |
每周回顾 | 统计、分解、行动 |
/retro global |
所有项目回顾 | 跨项目健康 |
/learn add <类型> <内容> |
添加知识 | 存入记忆 |
/learn ask <问题> |
查询知识 | 相关学习 |
/learn list |
显示所有 | 分类列表 |
总结
gstack 中的发布后技能提供：
- 文档同步 — 保持文档匹配代码
- 过时检测 — 找到过时引用
- 回顾 — 带数据的每周反思
- 个人统计 — 跟踪贡献
- 记忆管理 — 捕获模式供未来使用
关键要点
- ✅ 每次部署后运行
/document-release - ✅ 每周运行
/retro（建议周五） - ✅ 发现模式时添加学习
- ✅ 用
/retro global查看多项目视图
系列导航：
- ← 上一篇: 教程 10：发布工程
- → 下一篇: 教程 12：并行 Sprint
- 返回: 系列索引