grove-spec-writing について
Grove エコシステムの技術仕様書を作成・検証するスキルです。文書構成、視覚要素、文体ルール、チェックリストを定め、内部仕様書や実装計画を作成する開発者を支援します。
主な機能
- 01仕様書の構成と frontmatter
- 02ASCII アートの見出しと図
- 03モックアップと状態図のガイド
- 04文体・トーンの検証チェックリスト
- 05Grove 関連文書の作成ガイド
活用シーン
- 01新しい技術仕様書の作成
- 02仕様書の完全性の確認
- 03既存仕様書の形式統一
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/grove-spec-writingを入力して読み込まれたか確認します。
詳細
Grove の仕様書作成
Grove エコシステムで技術仕様書を作成するための包括的なガイドです。このスキルを使って、絵本のページのような新しい仕様書を作成したり、既存の仕様書を検証して標準化したりできます。
有効にするタイミング
- 新しい技術仕様書を作成するとき
- 既存の仕様書の完全性を確認するとき
- ASCII アートのヘッダーがない仕様書に追加するとき
- テキストの多い仕様書に図、モックアップ、視覚要素を追加するとき
- 仕様書ファイル全体のフロントマターを標準化するとき
- 最終化する前に、仕様書が Grove の標準に準拠しているか検証するとき
絵本のページとしての仕様書
Grove の仕様書は単なる技術文書ではありません。より大きな物語を構成する絵本のページです。どの仕様書も、美しく挿絵が描かれた森のフィールドガイドを開くような感覚にしてください。
基本構成：
- 表紙（フロントマター＋ASCII アート＋タグライン）
- 序章（自然界と Grove における、これが何か）
- 旅路（アーキテクチャ、フロー、実装）
- 詳細（API、スキーマ、セキュリティ）
- この先の道筋（実装チェックリスト）
必須の構成
1. フロントマター（必須）
すべての仕様書には、次の形式のフロントマターを必ず含めてください。
---
aliases: []
date created: [Day], [Month] [Ordinal] [Year]
date modified: [Day], [Month] [Ordinal] [Year]
tags:
- primary-domain
- tech-stack
- category
type: tech-spec
---
日付形式の例：
Monday, December 29th 2025Saturday, January 4th 2026
タイプの選択肢：
tech-spec— 技術仕様書（最も一般的）implementation-plan— ステップごとの実装ガイドindex— インデックス／ナビゲーション文書
2. ASCII アートのヘッダー（必須）
フロントマターの直後に、コンセプトを視覚的に表現した ASCII アートをコードブロックで含めてください。
# [Name] — [Short Description]
ASCII ART HERE
representing the concept
in a visual way
> *Poetic tagline in italics*
良い ASCII アートの条件：
- 自然のメタファー（森、庭など）に関連している
- コンセプトを視覚的に表現している（バックアップなら層、分析なら輪など）
- 罫線文字を使用している：
─│┌┐└┘├┤┬┴┼╭╮╰╯ - 自然を表す絵文字を控えめに使用している：
🌲🌿🍂✨🌸 - 詩的なタグラインまたはモットーを含んでいる
優れた仕様書の例：
Wisp（鬼火の光）：
🌲 🌲 🌲
\ | /
\ | /
✨
╱ ╲
╱ ╲
╱ · ╲
╱ · ╲
╱ · ╲
· · ·
gentle
guiding
light
Patina（層状のバックアップ）：
╭───────────────────╮
╭┤ ┌─────────────┐ ├╮
╭┤│ │ 2026-01-05 │ │├╮
│││ │ ▓▓▓▓▓▓▓▓▓▓ │ │││
│││ │ ▒▒▒▒▒▒▒▒▒▒ │ │││
│││ │ ░░░░░░░░░░ │ │││
│││ │ ·········· │ │││
╰┴┴──└─────────────┘──┴┴╯
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱
──────────────────────────────
~~~~~~~~ oxidation layer ~~~~~~~~
Age as armor. Time as protection.
Heartwood（年輪）：
╭──────────╮
╭──│ ╭──────╮ │──╮
╭─│ │ │ ╭──╮ │ │ │─╮
│ │ │ │ │♥ │ │ │ │ │
╰─│ │ │ ╰──╯ │ │ │─╯
╰──│ ╰──────╯ │──╯
╰──────────╯
every ring: a year, a story, a layer of growth
The center that holds it all.
3. 序章セクション
ASCII アートのヘッダーの後に、次の内容を記載してください。
> *Poetic tagline repeated*
[2-3 sentence description of what this is in the Grove ecosystem]
**Public Name:** [Name]
**Internal Name:** Grove[Name]
**Domain:** `name.grove.place`
**Repository:** [Link if applicable]
**Last Updated:** [Month Year]
[1-2 paragraphs explaining the nature metaphor and how it applies]
---
4. 本文セクション
明確な見出しを使って内容を整理してください。以下を含めます。
- 概要／目標 — このシステムが行うこと
- アーキテクチャ — どのように構築されているか（図を含めます！）
- 技術スタック — 依存関係、フレームワーク
- API／スキーマ — 技術的な詳細
- セキュリティ — 重要な考慮事項
- 実装チェックリスト — 明確な作業項目
必須の視覚要素
フロー図
プロセスを説明する仕様書には、必ず ASCII フロー図を 1 つ以上含めてください。
┌─────────────────────────────────────────────────────────────────────┐
│ Client Sites │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Site A │ │ Site B │ │ Site C │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼───────────────────────┘
│ │ │
│ 1. Request │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Central Service │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ Handler A │ │ Handler B │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
罫線文字のリファレンス：
- 角：
┌ ┐ └ ┘（角型）または╭ ╮ ╰ ╯（丸型） - 線：
─ │ ═ ║ - 接続：
├ ┤ ┬ ┴ ┼ - 矢印：
→ ← ↑ ↓ ▶ ◀ ▲ ▼
UI モックアップ
ユーザーインターフェースを説明する仕様書には、必ず ASCII モックアップを含めてください。
┌─────────────────────────────────────────────────────────────────┐
│ ✧ Panel Title [×] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Label ────────────────────────────────────────────────┐ │
│ │ Content here with proper spacing │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Input field... [↵] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ─────────────────────────────────────────────────────────── │
│ [ Action A ] [ Action B ✦ ] │
│ │
└─────────────────────────────────────────────────────────────────┘
状態図
複数の状態を持つ機能については、状態図を含めてください。
Idle: Analyzing: Success:
. * . . * . * . analyzing . * *
. _ . . \ | / . * /|\ .
/ \ * . -- (o.o) -- thinking * / | \ *
/ ~ ~ \ . . / | \ /__|__\
/ \______ ~~~~~~~~~~~~~~~~~ ~~~~/ \~~~~
~~~~~~~~~~~~~~~~~~~ words flowing... all clear
比較表
選択肢、状態、構成を比較する場合は、表を使ってください。
| Feature | Seedling | Sapling | Oak | Evergreen |
|---------|----------|---------|-----|-----------|
| Posts | 50 | 250 | ∞ | ∞ |
| Storage | 1 GB | 5 GB | 20 GB | 100 GB |
| Themes | 3 | 10 | All | All + custom |
タイムライン／保持期間の図
時間に関する内容には、図を含めてください。
TODAY 12 WEEKS AGO
│ │
▼ ▼
┌─┬─┬─┬─┬─┬─┬─┐ ┌─┐
│█│█│█│█│█│█│█│ ◀── Daily backups (7 days) │░│
└─┴─┴─┴─┴─┴─┴─┘ └─┘
S M T W T F S
検証チェックリスト
仕様書を最終化する前に、次の項目を確認してください。
構成
- 必須フィールドをすべて含むフロントマターがある
-
aliases: []が含まれている（空の場合も含む） - 日付形式が正しい（曜日、月、序数付き日、年）
-
type: tech-specまたは適切なタイプになっている - フロントマターの後に ASCII アートのヘッダーがある
- 詩的なタグラインが斜体で記載されている
- 公開名／内部名が記載されている
- ドメインが指定されている（該当する場合）
視覚的な内容
- ASCII フロー図が 1 つ以上ある（プロセスを扱う場合）
- UI モックアップが含まれている（インターフェースを説明する場合）
- 適切な箇所に比較表がある
- 技術的な詳細を示すコードブロックがある
- 視覚的な区切りのない長文が続いていない
文体（全リストは owl-archive/references/anti-patterns.md を参照してください）
- em ダッシュを使わない（ピリオドまたはカンマを使う）
- 「X ではなく Y」形式やその変形を使わない（「X ではない。Y でもない。ただ Z だ。」「X とは？ Y だ。」など）
- AI っぽい単語を使わない（robust、seamless、leverage、delve、utilize、streamline など）
- 「serves as」「stands as」「marks a」を使わない。簡潔な動詞を使う
- つなぎの言葉で埋めない（Furthermore、Moreover、It's worth noting、Notably）
- 動名詞の断片を並べ立てたり、太字を先頭に置いた箇条書きにしたりしない
- もったいぶった表現を使わない（「Here's the kicker」「Here's the thing」）
- 使い古された比喩を繰り返さない（同じ比喩を各セクションで繰り返さない）
- 短い段落にする
- 詩的な締めくくりは、無理に付けず、ふさわしい場合に使う
完全性
- 概要／目標のセクション
- アーキテクチャ図
- 技術的詳細（API、スキーマ）
- セキュリティ上の考慮事項
- 実装チェックリスト
ASCII アートの作成
手順
- 核となる比喩を特定する — これはどんな自然物を表していますか？
- コンセプトをスケッチする — ひと目で伝わる図はどんなものですか？
- 使う文字を選ぶ — 罫線文字、絵文字、または創作した ASCII
- 層を重ねる — 輪郭から始め、細部を加え、飾りを添える
- タグラインを加える — 本質を捉える詩的な一文
文字パレット
罫線文字（安全で一貫性があります）：
┌─────┬─────┐ ╭─────╮
│ │ │ │ │
├─────┼─────┤ ╰─────╯
│ │ │
└─────┴─────┘
線と矢印：
→ ← ↑ ↓ ↔ ↕
▶ ◀ ▲ ▼
⟿ ⟸ ⟹
自然の絵文字（控えめに使います）：
🌲 🌳 🌿 🍂 🍃 🌸 🌺 🌻 🌷 🌱 🍄
☀️ 🌤️ ⭐ ✨ 💧 🔥
🦋 🐛 🐌
装飾用：
· ∙ • ° ˚ ∘
~ ≈ ∿
═ ║ ╔ ╗ ╚ ╝
░ ▒ ▓ █
ヒント
- ASCII アートは高さ 20 行以内にします
- コードブロック内でアートを中央揃えにします
- 余白を設けます（上下に空行を入れます）
- 等幅フォントで確認します
- モバイルでの表示を考慮します（シンプルなほうが適しています）
例：仕様書の完全なヘッダー
---
aliases: []
date created: Monday, January 6th 2026
date modified: Monday, January 13th 2026
tags:
- support
- user-communication
- cloudflare-workers
type: tech-spec
---
# Porch — Support System
🏠
___│___
│ │
~~~~~~│ PORCH │~~~~~~
╱│_______│╲
╱ ╲
╱ ┌───┐ ╲
╱ │ ☕ │ ╲
╱ └───┘ 👤 ╲
════════════════════════
steps
どうぞお掛けください。一緒に考えましょう。
> *Have a seat on the porch. We'll figure it out together.*
Grove's front porch: a warm, accessible space where users sit down and have a conversation. Not a corporate help desk with ticket numbers. A porch where you chat with the grove keeper about what's going on.
**Public Name:** Porch
**Internal Name:** GrovePorch
**Domain:** `porch.grove.place`
**Status:** Planned (Launch Priority)
A porch is where you sit and talk. You come up the steps, have a seat, and the grove keeper comes out to chat. It's not a ticket counter. It's two people on a porch, figuring things out together.
---
他のスキルとの連携
仕様書を書く前
- walking-through-the-grove — 新機能に名前を付ける場合は、先に命名の手順を完了します
- grove-ui-design — 仕様に UI が含まれる場合は、デザインパターンを把握します
執筆中
- grove-documentation — 全体を通して Grove の文体を適用し、AI っぽい表現を避けます
執筆後
- grove-spec-writing（このスキル）— 検証チェックリストを実行します
- 新鮮な目で見直します。物語の一節のように感じられますか？
代わりに museum-documentation を使う場合
このスキル（grove-spec-writing）は、社内向けの技術仕様書を対象としています。アーキテクチャの決定、システム設計、実装計画など、開発者向けの文書です。
理解を深めたい Wanderers 向けに書く場合は、museum-documentation を使います。
| grove-spec-writing を使う場合 | museum-documentation を使う場合 |
|---|---|
| 技術仕様書 | 興味を持った訪問者向けの「仕組み」解説 |
| アーキテクチャの決定 | コードベースのガイド付きツアー |
| 実装計画 | ナレッジベースの展示 |
| 内部システム文書 | 技術的な内容の物語形式の解説 |
読者が何かを実装する開発者なら、このスキルを使います。 読者が森を探検する Wandererなら、museum-documentation を使います。
クイックリファレンス
| 要素 | 必須 | 場所 |
|---|---|---|
| Frontmatter | はい | ファイルの先頭 |
| ASCII アートのヘッダー | はい | Frontmatter の後 |
| 詩的なタグライン | はい | ASCII アートの後 |
| 公開名／内部名 | はい | 導入部 |
| アーキテクチャ図 | 該当する場合 | 本文 |
| UI モックアップ | UI がある場合 | 本文 |
| 実装チェックリスト | はい | 仕様書の末尾 |
優れた仕様書は、午前 2 時にも読みたくなるものです。美しく仕上げましょう。
コメント
Markdown 対応