0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@dev_chickenx(がっちりしたDev)

gstack で学び、Agent Skills を運用する工夫に落とし込む

0
Posted at

gstack で学び、Agent Skills を運用する工夫に落とし込む

1. はじめに

1.1. Skills, Agent Skillsとは何か

Skills（Agent Skills） とは、AIコーディングツールに「専門家としての役割と手順」をMarkdownファイルで定義し、必要なときだけ読み込ませる仕組みです。Claude Code の公式では SKILL.md を使って Claude の能力を拡張するこの仕組みを「Skills」と呼んでいます。

ClaudeだけでなくOpenAI（Codex）やCursorも同様にスキル定義が可能で、特定のAIツールに依存しない考え方として広まりつつあるように見えます。

AIエディタの進化は rules によるルール定義から始まり、徐々にスキル定義ができるように進化してきました。Skillsはその延長線上にある仕組みです。

1.2. ここで学びたいこと

大きく分けて2つあります。

  • Agentの価値を知ること
  • Agentの活用方法を学ぶこと

背景として、ClaudeがAgent Teamを提供したり、AIによるオーケストレーションによる効果が認められるようになりました。「チャットでやり取りしてコードを書く」だけでなく、複数のAgentや複数のモデルを組み合わせて成果物の品質を上げる方向へ進んでいると感じています。

展望として、現在はWebアプリケーションに特化したフレームワークが多いですが、今後は製造業など各業界のフィールドにあわせたカスタマイズが求められる場面も増えそうです。

1.3. gstackの公式情報・セットアップについて

本記事ではセットアップ手順などには触れませんが、リポジトリやQiita記事については紹介いたします。

  • gstack リポジトリ
    • Claude以外でも利用できますので、README.mdをご確認ください。
  • Qiita紹介記事
    • CLAUDE.mdに記載するコマンド一覧は最新のものより古くなっている可能性があります。
    • 公式手順 を確認して記載するのがよさそうです。（公式がmdっぽく書いてくれればいいんですが...）

2. gstack を「Agent運用の工夫」として読む

gstack は、Claude Code（AnthropicのAI CLI）向けに「専門家としての役割と手順」を SKILL.md で配布し、さらに実行を補助する小さなツール群を揃えた仕組みです。

gstack には Web アプリ向けのスキル（例：QAでブラウザ操作をするもの）も含まれますが、本記事ではWebアプリをレビューする技術よりも、そこから読み取れる **「Agentを安定して動かすための工夫」**に焦点を当てます。

具体的には、次の観点に昇華して整理します。

  • 何を SKILL.md に書くと、エージェントがブレにくくなるか
  • 失敗しにくい実行手順（フェーズ設計、再実行、証跡の残し方）をどう作るか
  • セッションをまたいで賢くなる仕組み（学習・記憶、コンテキスト回復）をどう作るか

3. gstack が提供しているもの（ざっくり）

実態はシンプルで、SKILL.md というMarkdownファイルの集合体 + 実行を助けるユーティリティです。

（細部は変わる可能性がありますが）大枠は次のような構成です。

~/.claude/skills/gstack/
├── qa-only/SKILL.md      ← QA担当としての振る舞い
├── investigate/SKILL.md  ← 調査（デバッグ）担当としての振る舞い
├── ship/SKILL.md         ← リリース担当としての振る舞い
└── bin/                  ← 各種CLIユーティリティ

ポイントは、AIに「賢く考えさせる」だけでなく、迷わず実行できるように手順と道具を整えていることです。

4. SKILL.md 設計の型（gstackから抽出）

gstack の各スキルは、だいたい次のような型に落とし込めます。

  1. Preamble（共通初期化）
  2. 事前コンテキスト回収
  3. 必要な知識（学習）の検索
  4. メインのワークフロー（フェーズ分け）
  5. 完了時の記録（ログ・学習・タイムライン）

ここで重要なのは、**「何をするか」だけでなく「何を出力するか」**まで含めて手順化している点です。

人間の作業でも「調査→修正→確認」を頭の中だけで回すとブレます。エージェントはさらにブレやすいので、フェーズ設計（区切り）と成果物設計（証拠）が効きます。

5. Agentを利用するために必要な工夫（運用パターン）

ここからは、gstack を Web 固有の仕組みとしてではなく、Agent運用のパターン集として読み替えます。

5.1. 事前コンテキスト回収を「最初に自動でやる」

エージェントの失敗で多いのは、能力不足よりも前提の取り違えです。

そのため、Preambleや最初のフェーズで、毎回決まった情報を回収するのが効きます。

  • どのブランチ・差分を対象にするか（git status / git diff など）
  • 実行環境の制約（Node/Pythonのバージョン、必要な環境変数など）
  • リポジトリ固有のルール（CLAUDE.md / AGENTS.md / README など）

5.2. フェーズを分けて「やること」を狭める

いきなり「直してください」と投げるより、フェーズを分ける方が成功率が上がります。

例（調査スキルの場合）

  1. 再現：現象を再現し、最小の手順にする
  2. 原因特定：影響範囲を絞り、仮説を立てる
  3. 修正：最小の変更で直す
  4. 検証：テスト・動作確認で裏取りする
  5. 記録：次回同じ落とし穴を踏まない形で残す

5.3. 「証跡」を成果物として残す

人間がレビューできる形で証跡を残すと、エージェントの暴走も抑えられます。

  • 変更点（差分）
  • 実行したコマンドと結果（要点）
  • 判断理由（なぜそうしたか）

5.4. 再実行に強い手順にする

セッションが切れても、途中からやり直せる（同じ手順を踏める）設計が重要です。

  • 出力ディレクトリは作り直せる（冪等）
  • 途中結果があれば再利用する
  • 失敗時のリトライ条件を明確にする

5.5. 「考える」と「実行する」の境界をはっきりさせる

エージェントに任せるときは、思考だけで完結させず、必ず「実行する手順」とセットにします。

  • 実行はコマンドに落とす（テスト、フォーマット、ビルドなど）
  • 失敗したら次に何を確認するか決める（ログ、差分、環境情報）
  • 危険な操作（削除、強制pushなど）は人間の確認ポイントにする

6. 学習と記憶の仕組み（次回をラクにする）

gstack はセッションをまたいで「学習」を蓄積します。

6.1. 学習の記録

スキル完了時、Claude は今回のセッションを振り返って気づきを記録します。

~/.claude/skills/gstack/bin/gstack-learnings-log '{
  "skill": "investigate",
  "type": "operational",
  "key": "poetry2-python-version-check",
  "insight": "Poetry 2.x はコマンド実行前に PATH の Python がプロジェクト制約を満たすか確認する...",
  "confidence": 9,
  "source": "observed",
  "files": ["backend/pyproject.toml"]
}'

type は以下のいずれかです。

type 意味
operational 環境・CLI・ワークフローに関する知見
pattern 再利用できるアプローチ
pitfall やってはいけないこと
architecture 構造的な設計判断
preference ユーザーの明示的な好み

6.2. 学習の活用

次回セッション開始時の Preamble で、プロジェクトに関連する学習を自動検索します。

~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10

「このプロジェクトでは Poetry を使うとき .venv を明示的に作成する必要がある」という知見が記録されていれば、次回の /investigate や /qa-only でその手順を最初から正しく踏めます。

7. タイムラインとコンテキスト回復（中断に強くする）

セッションが途切れても状態を引き継げるように、スキルの開始・終了をタイムラインファイルに記録します。

~/.gstack/projects/<slug>/timeline.jsonl

{"skill":"investigate","event":"started","branch":"feature/add_pytest_for_api","session":"99802-..."}
{"skill":"investigate","event":"completed","outcome":"success","duration_s":"120","session":"99802-..."}
{"skill":"qa-only","event":"started","branch":"feature/add_pytest_for_api","session":"121516-..."}

次回スキルを起動したとき、このタイムラインを読んで「前回は /investigate が成功した」と自動的に把握します。長いプロジェクトで作業を再開したとき、一から状況説明しなくてよいのが助かります。

8. 哲学的な土台 — なぜこう設計されているのか

gstack の振る舞いは3つの原則に従っています。ETHOS.md に明文化されています。

8.1. Boil the Lake（湖を沸かす）

AIを使えばコードを書くコストは限りなく低くなります。だから「90%の実装で妥協」は意味をなしません。完全な実装をするコストが数分で済むなら、常に完全な方を選びます。

「テストは後で書こう」は過去の考え方です。

8.2. Search Before Building（作る前に探す）

知識には3つの層があります。

  • Layer 1（定番） — 標準的なパターン。まず確認する
  • Layer 2（最新トレンド） — ブログや事例。批判的に読む
  • Layer 3（第一原理） — 問題から直接導かれる本質的な観察。最も価値がある

一番価値ある発見は「みんながやっていることとその理由を理解した上で、従来の前提が間違っていることに気づく瞬間」だと思います。

8.3. User Sovereignty（ユーザーの主権）

AIは推薦します。決定はユーザーがします。

ClaudeとCodexが同じ変更を推薦しても、それは強いシグナルであって命令ではありません。ユーザーは常にAIが知らないコンテキスト（ビジネス事情、戦略的タイミング、個人の好み）を持っています。「両方のAIが同意した→正しい」は間違いです。

9. Skillsについての要約

gstack で得た学びを、自分のSkillsをカスタマイズするときに持ち帰るなら、次をチェックすると整理しやすいです。

  • 役割を絞る：まずは「調査」「QA」「出荷」など3つ程度から始めます
  • 共通初期化を作る：毎回集めるべき前提情報をPreambleに寄せます
  • フェーズと成果物を決める：各フェーズで何を出力するか決めます
  • 証跡を残す：人間が判断できる形（差分・ログ・理由）で残します
  • 学習を残す：落とし穴や好みを、次回検索できる形で記録します

10. まとめ

最近のアプローチのほとんどがそうですが、エージェントを「賢い会話相手」ではなく、手順書と道具で動く実行者として設計しています。
（Anthropicから流出したコードを見ても同様に、SKILLSをうまく定義していたそうです。）

WebアプリQAの細部は環境に依存しますが、そこから抽出できる運用の工夫（コンテキスト回収・フェーズ設計・証跡・学習・再開性）は、どの分野のAgent活用でも再利用できるものだと思います。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?