gstack 深度分析报告

1项目概述与定位

gstack 是 Y Combinator CEO Garry Tan 构建的一个 AI 工程团队操作系统。它不是简单的 prompt 集合，而是一个完整的、多角色、多引擎的软件开发生命周期自动化框架。

技术栈

• Runtime: Bun (TypeScript)
• AI Engines: Claude Code (主力), OpenAI Codex, Google Gemini CLI
• Browser: Playwright Chromium 持久化守护进程 (~100ms/cmd)
• Telemetry: Supabase Edge Functions
• CI/CD: GitHub Actions + 12-job 并行矩阵

项目规模

2团队组织架构

gstack 的核心设计思想是 Conway's Law 的逆向应用：先设计理想的工程团队结构，再将每个角色实现为 Skill。

角色矩阵

安全守卫 (正交于主流程)

3工作流 Pipeline 设计

编排模式

A. 手动调用 (主模式)

用户显式调用每个 skill。每个 skill 独立运行，但会读取前置 skill 的输出（如果存在）。

B. 自动编排 (/autoplan)

自动运行 CEO Review → Design Review → Eng Review 的完整规划管线。

C. 依赖声明 (benefits-from)

# plan-ceo-review/SKILL.md.tmpl YAML frontmatter
benefits-from: [office-hours]

这是软依赖——不强制，但 skill 会优雅降级（跳过缺失的上游输出）。

D. 决策门 (Decision Gates)

多引擎策略

同一套 .tmpl 源文件，通过构建时代码生成支持 3 个 AI 引擎：

# Claude Code 输出
bun run gen:skill-docs              → SKILL.md (Claude 原生)

# Codex 输出
bun run gen:skill-docs --host codex → .agents/skills/gstack-*/SKILL.md
                                    + agents/openai.yaml

转换规则包括路径替换、Hook 转内联建议文本、YAML 配置适配等。

4Skill 亮点分析

4.1 Plan-CEO-Review: 认知模式驱动

4.2 Review: 结构化审查仪表盘

4.3 QA: 真实浏览器 + 植入 Bug 评估

4.4 CSO (Security Officer): 零噪声安全审计

4.5 Ship: "Do It, Don't Ask"

合并 base → 运行测试 → 检查覆盖率(自动补全) → 版本号 →
CHANGELOG → Review Gate → 原子提交 → Push → 创建 PR(嵌入所有仪表盘)

4.6 Investigate: 受限调试

5模板系统与代码生成

为什么需要模板？

生成管线

.tmpl 文件 + 源代码元数据
    ↓
gen-skill-docs.ts (解析 {{PLACEHOLDER}})
    ↓
resolvers/ (45+ 个解析器)
    ↓
输出: SKILL.md (Claude) + .agents/skills/ (Codex)

关键占位符

Preamble 分层系统

6测试与评估体系

三层测试金字塔

智能测试选择 (Diff-Based)

// touchfiles.ts
E2E_TOUCHFILES = {
  'browse-basic': ['browse/src/**'],
  'qa-b6-static': ['qa/**', 'browse/src/**', 'test/fixtures/qa-eval.html'],
  'journey-*':    ['*/SKILL.md.tmpl', 'scripts/gen-skill-docs.ts'],
}

// 只运行受影响的测试
git diff main...HEAD --name-only → match against touchfiles → run selected tests

植入 Bug 评估 (Outcome Eval)

{
  "total_bugs": 8,
  "minimum_detection": 5,
  "max_false_positives": 2,
  "bugs": [{"id": "b1", "category": "layout", "severity": "high", ...}]
}

评估结果持久化与对比

• 增量保存: 每个测试完成后写入 _partial-e2e.json (原子写入, 可中断恢复)
• 版本化存储: {version}-{branch}-{tier}-{timestamp}.json
• 对比工具: bun run eval:compare 自动比较两次运行，输出自然语言评论
• 实时监控: bun run eval:watch 心跳文件 + 过期告警

CI/CD 集成

GitHub Actions: PR 触发 → 12 并行 job → 聚合结果 → PR Comment 汇总表

7Skill 书写范式总结

从 gstack 27+ skills 中提炼出的可复用范式：

范式 1: YAML Frontmatter 标准结构

---
name: skill-name
preamble-tier: 1-4          # 认知负载等级
version: 1.0.0
description: One-line desc
allowed-tools:               # 工具白名单
  - Bash
  - Read
  - Edit
  - Agent
benefits-from: [office-hours] # 软依赖 (可选)
hooks:                        # 安全守卫 (可选)
  pre-tool-use:
    - type: regex
      pattern: "rm -rf"
      action: block
---

范式 2: 角色 Persona 而非检查清单

// Bad: 检查清单
- [ ] 检查 SQL 注入
- [ ] 检查 XSS
- [ ] 检查权限

// Good: 角色注入
You are the Chief Security Officer. Your job is to find vulnerabilities
that would make the front page of Hacker News. Every finding must include
a concrete exploit scenario. You have 17 false-positive exclusion rules
and an 8/10 confidence threshold. Zero noise.

范式 3: 自包含 Bash 块

Step 3: Check review gate

Read the review dashboard:

```bash
cat ~/.gstack/projects/$SLUG/review-dashboard.json
```

If the review status is CLEAR, proceed to Step 4.
If the review has ASK items, use AskUserQuestion to present each item.

Step 4: Run tests

Re-read the test framework detection from Step 1 output:

```bash
# Self-contained: re-detect, don't rely on bash variables from Step 1
if [ -f package.json ]; then ... fi
```

范式 4: 自然语言决策树

// 不是 if/else 嵌套:
if (testsPass && reviewClear && !hasAskItems) { ... }

// 而是散文式决策:
"If tests pass, proceed to version bump.
 If tests fail, triage:
   - Pre-existing failure (existed before this branch): note in PR, don't block.
   - Regression (introduced by this branch): fix before shipping.
   - Environmental (CI-specific): retry once, then note.
   - Flaky (intermittent): retry once, note if still fails."

范式 5: 完成状态协议

End every skill invocation with one of:
  DONE                 — Skill completed successfully
  DONE_WITH_CONCERNS   — Completed but flagged issues
  BLOCKED              — Cannot proceed, needs user input
  NEEDS_CONTEXT        — Insufficient information to proceed

范式 6: 安全边界 — Hook vs 内联建议

范式 7: 渐进式升级而非全有全无

// 不是: "确保 100% 覆盖率否则失败"
// 而是:
"Step 3: Check test coverage.
 If coverage is below threshold, auto-generate tests for uncovered paths.
 Commit the new tests as a separate atomic commit.
 If auto-generation fails, note the gap in the PR body."

范式 8: 遥测即文化

8Skill 开发策略提炼

以下是从 gstack 实践中沉淀的完整 Skill 开发策略框架：

策略 1: 角色优先，功能其次

策略 2: 模板化一切共享知识

策略 3: 按认知负载分层 (Preamble Tiers)

策略 4: 可恢复的步骤设计

策略 5: 软依赖与优雅降级

策略 6: 用测试衡量 Skill 质量

策略 7: 安全边界的平台适配

策略 8: "Do It, Don't Ask" 原则

策略 9: 评估驱动的迭代

策略 10: 文化注入 (Ethos)

Quick Reference: Skill 开发 Checklist