gstack の分解: 開発者が学べるスキル

はじめに

概念 と 実践 では、gstack とは何か、およびユーザーの観点からその使用方法を学びました。このメモは別の視点からのものです。スキル開発者として、gstack ウェアハウスをファイルごとに読んだ後、どのようなエンジニアリング設計が学び、学ぶ価値があるかを考えます。

gstack は、23 個のプロンプト ファイルの単なるコレクションではありません。その背後には完全なエンジニアリング システムがあり、テンプレートの生成、自動アップグレード、学習と記憶、段階的なガイダンス、マルチプラットフォームへの適応、階層化されたテストが、スキル プロジェクトを「使える」ものから「使いやすい」ものに変える鍵となります。

1. SKILL.md は手書きではありません - テンプレート生成システム

gstack の最も直観に反する設計: **各 SKILL.md は自動的に生成され、直接編集することはできません。 **

SKILL.md.tmpl (人写)  →  gen-skill-docs  →  SKILL.md (机生)

人間が作成した .tmpl テンプレートには、ワークフロー ロジックとベスト プラクティスに加えて、{{PLACEHOLDER}} プレースホルダーが含まれています。ビルド スクリプトは、ソース コードからコマンド リファレンス、ブラウザ フラグ リスト、プリアンブル スタートアップ コードなどを抽出し、プレースホルダーに埋め込んで最終的な SKILL.md を生成します。

{{PREAMBLE}}           ← 从 resolvers/preamble.ts 生成的启动代码
{{BROWSE_SETUP}}       ← 浏览器初始化指令
{{COMMAND_REFERENCE}}  ← 从 commands.ts 提取的命令文档
{{SNAPSHOT_FLAGS}}     ← 从源代码常量提取的快照选项

**なぜこれを行うのですか? **

• ドキュメントとコードが同期しなくなることはありません。 - コマンド リファレンスはソース コードから生成され、ソース コードが変更されるとドキュメントは自動的に更新されます。
• 23 のスキルが同じプリアンブル (約 220 行) を共有し、すべてのスキルが同時に更新されます
• CI は、再生成の忘れを防ぐために、生成されたファイルの有効期限が切れているかどうかを --dry-run チェックできます

要点: 複数のスキルを維持する場合は、スキル間で共有されるコンテンツをテンプレートに抽出し、ビルド ステップで使用して最終ファイルを生成する必要があります。同じコンテンツの複数のコピーを手動で同期すると、遅かれ早かれ問題が発生します。

2. アップグレード メカニズム - 検出から実行までの完全なリンク

gstack のアップグレード システムは非常に精巧に設計されており、次の 3 つの層に分かれています。

最初の層: バージョン検出

bin/gstack-update-check は、次のことを行うスタンドアロンの bash スクリプトです。

1. ローカルの VERSION ファイルを読み取ります
2. キャッシュ ~/.gstack/last-update-check を確認します (UP_TO_DATE キャッシュは 60 分間、UPGRADE_AVAILABLE キャッシュは 720 分間)
3. キャッシュの有効期限が切れた場合、HTTP リクエストは GitHub の raw.githubusercontent.com/.../VERSION
4. バージョン番号を比較し、UPGRADE_AVAILABLE <旧> <新> を出力します。

第 2 層: プリアンブルの統合

各スキルの SKILL.md スタートアップ コードの最初の行はバージョン検出です:

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true

これは、ユーザーがスキルを呼び出すと更新が自動的に検出されることを意味します。特にアップグレード コマンドを実行する必要はありません。存在感はありませんが、カバレッジは 100% です。

3 番目のレベル: プログレッシブ リマインダー + 自動アップグレード

新しいバージョンを検出した後、すぐにユーザーに迷惑をかけることはありませんが、プログレッシブ バックオフのためにスヌーズ メカニズム (スヌーズ) を使用します。

• 1 回目のリマインダー: 24 時間後にもう一度言及してください
• 2 回目のリマインダー: 48 時間後にもう一度言及してください
• 3回目以降：7日後にもう一度言ってください
• 新しいバージョンのリリースによりスヌーズカウンターがリセットされる

ユーザーは gstack-config set auto_upgrade true 自動アップグレードを有効にし、確認をスキップして直接実行することができます。

アップグレードを実行すると、5 つのインストール タイプ (グローバル git、ローカル git、ベンダーなど) が区別されます。 git インストールは git fetch + reset を使用し、ベンダーのインストールは最初にバックアップしてから置き換え、障害が発生した場合は .bak から復元します。アップグレード後、プロジェクトのローカル ベンダーのコピーも自動的に同期されます。

学ぶ価値のあるポイント:

• 「通話ごとに検出」モードは非常に高いカバレッジを持ち、ユーザーには認識されません。
• 段階的なバックオフにより、頻繁な中断を回避します
• インストール タイプを区別し、画一的な方法ではなく、さまざまなアップグレード戦略を実装します。
• バックアップと復元により、アップグレードの失敗によってスキル全体がハングアップすることがなくなります。

3. 学習システム - 使えば使うほどスキルが賢くなる

gstack は、軽量かつ効果的な クロスセッション メモリ システムを実装しています。

ストレージ

各プロジェクトには独立した学習ログ ~/.gstack/projects/$SLUG/learnings.jsonl が追加で書き込まれます。

{
  "skill": "review",
  "type": "pitfall",
  "key": "n-plus-one",
  "insight": "这个项目的 User model 有 N+1 查询问题，findAll 要加 include",
  "confidence": 8,
  "source": "observed",
  "files": ["src/models/user.ts"],
  "ts": "2026-04-01T14:30:00Z"
}

自動収集

各スキルが完了する前に、「運用上の自己改善」リンクがあり、実行中に予期せぬ失敗、回り道、またはプロジェクトの癖が発見されたかどうかが反映され、それらはすべて learnings.jsonl に自動的に記録されます。ユーザーが手動でトリガーする必要はありません。

自動ロード

新しいセッションが開始されるたびに、プリアンブルは最初の 3 つの高信頼学習エントリをロードしてコンテキストを挿入し、新しいセッションが履歴知識を継承できるようにします。

自信の低下

observed および inferred ソースからのエントリーは 30 日ごとに 1 ポイントずつ減少します。ナレッジ ベースを手動でクリーンアップする必要はありません。古い知識は自然に消え、新しい観察が自然に置き換えられます。

管理インターフェース

/learn            # 显示最近 20 条
/learn search     # 搜索
/learn prune      # 检测过期条目（引用的文件已删除）
/learn export     # 导出为 markdown 可加入 CLAUDE.md

学ぶ価値のあるポイント:

• 追加の書き込み専用設計はシンプルで信頼性が高く、同時実行性も安全です
• 信頼の減衰は、メンテナンスの手間がかからない知識の老化管理であり、手動でのクリーニングよりもはるかに効率的です。
• パスの代わりに git リモート URL を使用してプロジェクトを識別します (gstack-slug 経由)。これは別の場所に複製して再利用できます。
• プロジェクト間のクエリをサポートしますが、デフォルトでは分離されています

4. プリアンブルインジェクション - スキルの「ミドルウェア層」

これは、gstack の最もスマートなアーキテクチャ設計の 1 つです。各 SKILL.md は約 220 行のプリアンブル コードを共有しており、Web フレームワークのミドルウェアのように機能します。

┌─ 更新检测 ──────────────────────────────────┐
│ 会话追踪 (sessions/$PPID)                    │
│ 配置读取 (proactive, skill_prefix, telemetry)│
│ 学习历史加载 (前 3 条高置信度)                │
│ 上下文恢复 (最近的 checkpoint + timeline)     │
│ 路由规则检测                                 │
│ 首次使用引导流程                              │
└──────────────────────────────────────────────┘
         ↓
    Skill 特有逻辑

プリアンブルの bash スクリプトはキーと値のペア (BRANCH: main、PROACTIVE: true) を出力し、テンプレートは自然言語条件を使用して、クロードがそれに応じて動作を調整できるようにします。

If PROACTIVE is false, do not invoke skills automatically.
Instead suggest: "I think /skillname might help here -- want me to run it?"

これは基本的に bash 出力をクロードの「環境変数」として扱います。ランタイム検出には bash を、動作ルーティングには自然言語を使用します。

学ぶ価値のあるポイント: 複数のスキルがある場合は、スキルごとにコピーを作成するのではなく、共有ロジック (構成の読み込み、状態の回復、バージョンの検出) を統合されたプリアンブルに抽出する必要があります。

5. プログレッシブ ブート - Sentinel ファイル モード

gstack の初めてのユーザー エクスペリエンスは細心の注意を払って設計されています。各ブート ステップが touch ファイル (センチネル ファイル) 経由で 1 回だけ実行されるようにします。

~/.gstack/.completeness-intro-seen    ← "Boil the Lake" 理念介绍
~/.gstack/.telemetry-prompted         ← 遥测选择（community/anonymous/off）
~/.gstack/.proactive-prompted         ← 主动触发开关
~/.gstack/.routing-prompted           ← CLAUDE.md 路由规则写入
~/.gstack/.welcome-seen               ← 安装欢迎消息

スキルを開始するたびに、これらのファイルが存在するかどうかを確認します。そうでない場合は、対応するブート ファイルとタッチ ファイルを表示します。すでに表示されたステップは再度表示されません。

学ぶ価値のあるポイント: 構成で "onboarding_step": 3 のステータスを維持する場合と比較して、センチネル ファイルはよりシンプルで信頼性が高くなります。構成ファイルの破損による影響を受けず、各ステップは独立して制御されます。

6. SKILL.md 構造設計 - 3 層アーキテクチャ

各 SKILL.md は標準の 3 層構造に従います。

最初の層: YAML Frontmatter

---
name: qa
preamble-tier: 3
version: 0.15.1.0
description: |
  Systematically QA test a web application...
  Use when asked to "qa", "test this site", "find bugs"...
benefits-from: [office-hours]
allowed-tools:
  - Bash
  - Read
  - Write
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
---

主要なフィールド:

• allowed-tools: ツールレベルの権限ホワイトリスト。各スキルは必要なツールのみを宣言します。
• benefits-from: 事前依存スキルを明示的に宣言します
• hooks: PreToolUse フック。ツールが呼び出される前にインターセプトできます (慎重なインターセプト rm -rf など)。
• description: すべての自然言語トリガーワードが含まれています

レイヤ 2: 共有プリアンブル + 一般規則

プリアンブル起動コード + 音声定義 + コンテキスト回復 + 整合性原則 + 検索優先度 + 完了ステータス プロトコル + アップグレード ルールなど。すべてのスキルは同一であり、テンプレートから生成されます。

3 番目の層: スキル固有のロジック

これは、ワークフロー定義、ロール設定、認知モデルの注入、インタラクション ゲーティングなどの各スキルの「魂」です。

学ぶ価値のあるポイント: 3 層に分離されているため、各スキルは独自のロジックのみに集中でき、共有部分はフレームワークによって一貫性が確保されています。

7. 迅速なエンジニアリングのヒント集

SKILL.md をすべて読んだ後は、学ぶ価値のあるプロンプト デザイン テクニックを以下に示します。

媚び防止ルール

オフィスアワーのスタートアップ モードは、AI の一般的な「そして泥臭い」動作を明示的に禁止します。

Never say:
- "That's an interesting approach" → take a position instead
- "There are many ways to think about this" → pick one
- "You might want to consider..." → say "This is wrong because..."
- "That could work" → say whether it WILL work

禁止用語リスト

「音声」セクションには、明確に禁止されている単語やフレーズが含まれています。

• 禁止されている単語: 掘り下げる、極めて重要、堅牢、包括的、微妙な、重要な、景観...
• 禁止されているフレーズ: 「ここにキッカーがある」、「どんでん返し」、「これを分解してみましょう」...
• 無効な形式: 全角ダッシュ (カンマ/ピリオドに置き換えます)

これらは LLM の一般的な「AI 風味の」単語であり、無効にした後の出力は明らかにより自然になります。

認知モデルインジェクション

各レビュー スキルには、異なる思考フレームワークが注入されます。

• CEO レビュー: 18 の認知モデル (ベゾスの一方通行/双方向ドアの意思決定、マンガーの逆思考、ジョブズの集中力と引き算...)
• 英語レビュー: 15 のエンジニアリング管理パターン (「デフォルトでは退屈」、爆発範囲の直感、コンウェイの法則...)
• デザインレビュー: 12 のデザイン認識パターン (サービスとしての階層、制約の崇拝、「気づきますか?」テスト...)

これらのモードは AI に機械的に動作させるのではなく、思考フレームワークを提供します。これは、賢い新参者に先任者の経験のリストを与えるのと同じです。

仕様規格

Not "you should test this"
    but `bun test test/billing.test.ts`

Not "this might be slow"
    but "this queries N+1, ~200ms per page load with 50 items"

Not "there's an issue in the auth flow"
    but "auth.ts:47, the token check returns undefined"

信頼度の調整

レビュー スキルでは、各発見に信頼スコアが伴う必要があり、信頼性の低い発見は自動的に格下げされるか非表示になります。

インタラクティブ ゲーティング

Ship スキルは、いつ停止してユーザーを待つか、いつ自動的に続行するかを正確に定義します。

Only stop for:
- Tests failing with no obvious fix
- Merge conflicts requiring human judgment
- Unclear which changes to include

Never stop for:
- Normal git operations
- CHANGELOG/VERSION updates
- PR creation

学ぶ価値のあるポイント: 優れたスキルとは、「AI がすべてを行う」のではなく、人間とマシンの境界を正確に定義することです。

8. 状態管理 - ファイルシステムはデータベースです

gstack の永続化はすべて、~/.gstack/ に保存されるファイル システムを通じて行われます。

ほとんどすべての時系列データは、JSONL (行ごとに 1 つの JSON オブジェクト) を使用して追加的に書き込まれます。この選択は賢明です:

• 書き込みの自然な同時実行の安全性を追加しました
• データベースの依存関係は必要ありません
• grep / jq を使用して直接クエリできます
• 最後の行が欠落しているまで破損しています

9. クロススキル統合モード

ファイル転送製品

ファイル システムを介してスキル間で作業成果物を転送します。

/office-hours → design doc → /plan-ceo-review 读取
/plan-ceo-review → ceo-plans/*.md → /autoplan 读取
/review → reviews.jsonl → /ship 读取并展示 Dashboard
/qa → qa-reports/ → /retro 读取

Review Readiness Dashboard

船のスキルは reviews.jsonl と読み取られ、公開前のクロススキル レビュー ステータスを示します。

| Review          | Runs | Last Run    | Status | Required |
| Eng Review      |  1   | 2026-03-16  | CLEAR  | YES      |
| CEO Review      |  0   | —           | —      | no       |
| Design Review   |  0   | —           | —      | no       |

依存関係前の提案

plan-ceo-review が設計ドキュメントがないことを検出すると、最初に /office-hours を実行することを積極的に推奨します。

"No design doc found. /office-hours produces a structured problem statement...
Takes about 10 minutes."
Options: A) Run /office-hours now  B) Skip

シーケンス予測を使用する

Context Recovery は、最近のスキル使用シーケンスを分析し、次のステップを予測します。

If pattern repeats (e.g., review → ship → review),
suggest: "Based on your recent pattern, you probably want /ship."

10. その他の注目デザイン

フックシステム

注意、フリーズ、ガードの 3 つのスキルは PreToolUse フックを使用します。これは、ツールが呼び出される前にインターセプトできる唯一のメカニズムです。

• 注意: Bash をインターセプトし、rm -rf、DROP TABLE、git push --force を確認してください。
• フリーズ: 編集/書き込みをインターセプトし、パスが許可された範囲内にあるかどうかを確認します。
• ガード: 上記 2 つを組み合わせます

マルチプラットフォームへの適応

同じテンプレートのセットは、--host パラメーターを通じてさまざまなプラットフォーム用のスキル ファイルを生成します。

bun run gen:skill-docs --host claude   # Claude Code 格式
bun run gen:skill-docs --host codex    # OpenAI Codex 格式
bun run gen:skill-docs --host kiro     # AWS Kiro 格式
bun run gen:skill-docs --host factory  # Factory Droid 格式

パスとフロントマターは自動的に適応され、スキルのロジックは変更されません。

完了ステータスプロトコル

標準化された完了ステータスは、各スキルの終了時に出力される必要があります。

DONE                — 全部完成，提供证据
DONE_WITH_CONCERNS  — 完成但有顾虑
BLOCKED             — 无法继续
NEEDS_CONTEXT       — 需要更多信息

失敗した 3 つのアップグレード ルール

If you have attempted a task 3 times without success, STOP and escalate.

AI が無限再試行ループに陥るのを防ぎます。

差分ベースのテストの選択

E2E テストの費用はそれぞれ約 4 ドル (クロード エージェントの起動が必要) であるため、gstack は各テストが依存するソース ファイルを touchfiles.ts を通じて宣言し、影響を受けるテストのみ git diff に従って実行します。

// test/helpers/touchfiles.ts
{
  "qa-workflow": ["qa/SKILL.md.tmpl", "browse/src/server.ts"],
  "ship-flow": ["ship/SKILL.md.tmpl", "scripts/resolvers/preamble.ts"]
}

概要: 参考にできる設計原則

gstack のエンジニアリング実践から、スキル開発者にとって最も価値のある次の設計原則を抽出しました。

1. テンプレート生成 > 手動同期: スキル間で共有されるコンテンツは、テンプレートとビルド手順を使用して自動的に生成されます。コピーして貼り付ける必要はありません。
2. パッシブ検出 > アクティブ検出: アップグレード検出はすべてのスキル呼び出しに組み込まれており、ユーザーは気づきませんが、カバー率は 100% です。
3. ログの追加 > 複雑なデータベース: JSONL + ファイル システムは、ほとんどの永続化ニーズをカバーでき、シンプルで信頼性が高くなります。
4. プログレッシブ ブート > 1 つの構成: センチネル ファイルを使用してブート ステップを制御します。各ファイルは 1 回だけ表示されます。
5. 正確なゲート > 全自動: 「停止してユーザーを待つ」と「自動的に続行する」の間の境界を明確に定義します。
6. 信頼性の定量化 > ファジー判定: 各 AI 判定には信頼性スコアが付属しており、信頼性が低い場合は自動的に格下げされます。
7. 時間の減衰 > 手作業によるクリーニング: 学習記録の信頼性は時間の経過とともに減衰し、古い知識は自然に薄れていきます。
8. 禁止語リスト > スタイルガイド: 禁止語を直接リストした方が、「自然な口調でお願いします」よりもはるかに効果的です。

関連書籍:

• gstack の概念 — gstack とは何ですか? gstack によってどのような問題が解決されますか?
• gstack 実践編 — インストールから実行までの完全なワークフロー
• gstack フロントエンド スキル — フロントエンド/UI 設計スキルのパノラマと推奨ワークフロー
• Claude Skills Concept — スキルの基礎となるメカニズムを理解する