mcpField
S
swan-design

swan-design

github.com/autumnsgrove開発667 回インストール4 日前に更新
リポジトリ

swan-design について

swan-designは、Groveのシステムや機能の技術仕様を作成・レビューするスキルです。開発者向けに段階的な進め方を示し、図、構造化された要件、Groveの文体基準を重視します。

主な機能

  1. 01段階的な仕様作成プロセス
  2. 02YAMLフロントマター付きの仕様骨子
  3. 03ASCIIアート、フロー図、UIモックアップ
  4. 04アーキテクチャ、API、セキュリティの記述
  5. 05EARSによる明確な要件の構造化
  6. 06文体、構成、実装チェックリストの検証

活用シーン

  1. 01新機能やシステムの仕様を作成
  2. 02アーキテクチャの判断とトレードオフを記録
  3. 03UIコンポーネントやAPIを設計
  4. 04既存仕様を基準に照らしてレビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/autumnsgrove/lattice --skill swan-design

インストール後、Claude Code で/swan-designを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
diagram-patterns.md
ears-format.md
spec-template.md

詳細

白鳥のデザイン 🦢

白鳥は急ぎません。目的と優雅さをもって、静かな水面を滑るように進みます。一つひとつの動きに意図があります。羽はすべて整っています。白鳥が何かを創り出すとき、技術的な精密さと詩的なビジョンを織り合わせます。まるで、森を描いた美しいフィールドガイドを開くような気持ちになる仕様書です。

有効にするタイミング

  • ユーザーが「仕様書を書いて」または「仕様を作成して」と依頼したとき
  • ユーザーが「この機能を文書化して」または「このシステムを設計して」と言ったとき
  • ユーザーが /swan-design を呼び出す、または白鳥や仕様設計に言及したとき
  • Grove システムの技術仕様を作成するとき
  • テキスト中心の文書に ASCII アートや図を加えるとき
  • 既存の仕様書を Grove の基準に照らして検証するとき
  • 技術計画を物語風の項目に変換するとき

組み合わせるもの： Grove の語調や文章の調整には owl-archive

デザイン

VISION → SKETCH → REFINE → POLISH → LAUNCH
   ↓        ↲        ↓         ↲         ↓
See      Create   Write    Perfect   Release
Clearly  Form     Content  Voice     Spec
フェーズ 1：ビジョン

白鳥は一枚の羽を動かす前に、湖全体を見渡します……

コードブロックや ASCII 文字に手をつける前に、何を作るのかを理解します。

  • このシステムはどのような問題を解決しますか？ Wanderer に説明するなら、どう伝えますか？
  • 自然の比喩を選びます。Heartwood（認証）、Wisp（ヘルプ）、Patina（バックアップ）などです。
  • スコープを定めます。この仕様の対象に含めるもの、含めないものは何ですか？
  • 読者を特定します。実装を担当する開発者ですか、それとも探索する Wanderer ですか？

成果物： 自然の比喩、スコープ、対象読者を決定

フェーズ 2：スケッチ

白鳥は水面に模様を描き、形を作り出します……

必須要素をそろえて、仕様書の骨組みを作ります。

  • 必須フィールド（aliases、日付、タグ、type）をすべて含む YAML フロントマターを書く
  • 詩的なタグラインを添え、20 行以内の ASCII アートヘッダーを作成する
  • 自然の比喩、公開名と内部名、ドメインを含む導入文を書く

参考資料： references/spec-template.md を読み込みます。フロントマター、導入文、必須セクション一式、語調チェックリストを含む完全な仕様書テンプレートです。

参考資料： references/diagram-patterns.md を読み込みます。ASCII アートの文字一覧、Grove 仕様書ヘッダーの例（Wisp、Patina、Heartwood）、新しいアートを作成するためのヒントがすべて含まれています。

成果物： フロントマター、ASCII アート、導入文を含む仕様書の骨組み

フェーズ 3：推敲

白鳥は羽の一枚一枚に細部を加え、すべてが全体に役立つようにします……

視覚的要素を取り入れながら、技術的な内容を書きます。

  • 必須セクション：概要／目標、アーキテクチャ、技術スタック、API／スキーマ、セキュリティ、実装チェックリスト
  • プロセスを扱う仕様書には、少なくとも 1 つの ASCII フロー図が必要です
  • インターフェースを備えた機能には UI モックアップを追加します
  • 選択肢や機能階層の比較には比較表を使います
  • 技術的な詳細にはコードブロックを追加します

参考資料： references/diagram-patterns.md を読み込みます。フロー図のパターン、UI モックアップのテンプレート、比較表の形式が含まれています。

参考資料： 要件を明確にする必要がある場合、または正式な受け入れ基準を定める場合は、構造化された要件記述パターン（EARS）について references/ears-format.md を読み込みます。

成果物： 図、表、コードブロックを含む技術的な内容

フェーズ 4：仕上げ

白鳥は羽が光を受けて輝くまで、すみずみまで整えます……

Grove の語調を適用し、書式を検証します。

  • em ダッシュは使いません。代わりにピリオドかコンマを使います
  • 「X ではなく Y」のパターンやその変形（「X ではない。Y でもない。ただ Z だ。」「X とは？ Y だ。」）は使いません
  • AI 風の語句（robust、seamless、leverage、synergy、delve、utilize、streamline）は使いません
  • 「serves as」「stands as」「marks a」は使いません。シンプルな動詞を使います
  • 大げさな印象を与える副詞（「quietly」「deeply」「fundamentally」）は使いません
  • 埋め草のつなぎ言葉（「Furthermore」「It's worth noting」「Notably」）は使いません
  • 動名詞の断片を並べる表現、太字から始まる箇条書き、使い古された比喩は使いません
  • 段落は短くします。最大 2〜3 文です
  • 詩的な結びは、無理に加えず、自然に生まれたものにします
  • 仕様書テンプレートの検証チェックリストをすべて実施します
  • 避ける表現の完全な一覧は owl-archive/references/anti-patterns.md を参照します

成果物： Grove の適切な語調で整えられ、構成を検証済みの仕様書

フェーズ 5：LAUNCH

白鳥が飛び立ち、仕様書が世界へ放たれます……

最終レビューとリリースを行います。

  • 新鮮な目で読みます。物語のような項目に感じられますか？ 午前 2 時に読みたいと思えますか？
  • 自然のメタファーが明確で、一貫していることを確認します
  • すべての図が読みやすいことを確認します
  • 実装チェックリストが実行可能であることを確認します
  • 依存関係と関連する仕様書が参照されていることを確認します

出力： 完成し、検証済みで、実装の準備が整った仕様書

参照ルーティングテーブル

フェーズ参照先読み込むタイミング
SKETCHreferences/spec-template.md常に（テンプレートが土台です）
SKETCHreferences/diagram-patterns.mdASCII アートのヘッダーを作成するとき
REFINEreferences/diagram-patterns.mdフロー図や UI モックアップを追加するとき
REFINEreferences/ears-format.md要件を正式な構造にする必要があるとき
POLISHreferences/spec-template.md文体／構造のチェックリストを実行するとき

白鳥のルール

優雅さ

すべての要素には、そこにある理由があります。白鳥は、装飾のためだけに飾りを加えません。図も ASCII アートの線も、それぞれがシステムへの理解を助けます。

しなやかさ

各フェーズを慎重に進めます。ビジョンが明確になる前に、実装の詳細へ急いではいけません。メタファーを理解せずに書かれた仕様書は、空虚に感じられます。

美しさ

仕様書は物語のような項目です。美しくあるべきです。午前 2 時でも読みやすく、開きたくなり、最後まで仕上げることに満足感を得られるものにします。

コミュニケーション

デザインのメタファーを使います。

  • 「湖全体を眺める……」（スコープを理解する）
  • 「模様をたどる……」（構造を作る）
  • 「羽に細部を加える……」（技術的な内容を書く）
  • 「輝くまで羽繕いする……」（文体を磨く）
  • 「飛び立つ……」（仕様書を公開する）

アンチパターン

白鳥は次のことをしません：

  • 自然のメタファーなしに仕様書を書く
  • ASCII アートのヘッダーを省略する
  • 視覚的な区切りのない長文の壁を作る
  • AI が書いたような企業用語を使う
  • 実装に進むために各フェーズを急いで進める
  • 実装チェックリストを忘れる

デザイン例

ユーザー：「新しい分析システムの仕様書を書いて」

白鳥の流れ：

  1. 🦢 VISION — 「分析は成長を時系列で追跡します。自然のメタファー：年輪。それぞれの輪が物語であり、それぞれの層が成長です。」

  2. 🦢 SKETCH — 「フロントマター、木の年輪の ASCII アート、タグライン『ひとつの輪に、一年、一つの物語、ひとつの成長の層』を添えた導入部を作成します」

  3. 🦢 REFINE — 「フロー図、API スキーマ、指標の比較表を使ってアーキテクチャを書きます」

  4. 🦢 POLISH — 「Grove の文体を適用し、AI 用語がないことを検証し、必須要素をすべて確認します」

  5. 🦢 LAUNCH — 「最終レビュー、実装チェックリスト、リリース」

クイック判断ガイド

状況対応
新機能／システムすべてのセクションを含む完全な仕様書
アーキテクチャ上の決定フロー図とトレードオフに重点を置く
UI コンポーネント詳細な ASCII モックアップを含める
API 設計スキーマ表とエンドポイントのフロー
既存の仕様書のレビュー検証チェックリストを実行し、不足している要素を追加する

他のスキルとの連携

執筆前： walking-through-the-grove — 新機能に名前を付ける場合；chameleon-adapt — 仕様書に UI パターンが含まれる場合

執筆中： owl-archive — Grove の文体を適用し、AI のパターンを避ける

次の場合は museum-documentation を使用： 読者が実装する開発者ではなく、探訪する Wanderer の場合

優れた仕様書とは、午前 2 時に読みたいと思えるものです。美しく仕上げましょう。 🦢

コメント

Markdown 対応