spec-design-guide
Linear-integrated AI centric workflow management tool
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
# Spec & Design Guide Skill
このスキルは、Unison Flowプロジェクトの仕様・設計ドキュメント作成をガイドします。
## エイリアス
このスキルは以下のように呼ぶことができます：
- `spec-design-guide` → 「仕様設計ガイド」
- `sdg` → 「仕様設計ガイド」の略称
## 目的
実装前に仕様と設計を明確にし、実装の助けとなるドキュメントを体系的に管理します。
## ドキュメントの役割
### SPEC.md - コンセプト、仕様、哲学
**What & Why** - 何を作るか、なぜ作るか
- コンセプト・ビジョン
- 設計哲学・原則
- 機能仕様
- ユーザー体験
### DESIGN.md - モデル、手法、実装
**How** - どう作るか
- データモデル
- アーキテクチャ
- 実装手法
- 技術的詳細
### GUIDE.md - ガイド
**Usage** - どう使うか
- 使い方
- ベストプラクティス
- トラブルシューティング
## ディレクトリ構造
```
spec/
├── 01-core-concept/
│ ├── SPEC.md # コンセプト・仕様・哲学
│ ├── DESIGN.md # モデル・手法・実装
│ └── GUIDE.md # 使い方ガイド（オプション）
├── 02-kdl-parser/
│ ├── SPEC.md
│ └── DESIGN.md
└── ...
```
## SPEC.md のテンプレート
**目的**: コンセプト、仕様、哲学
```markdown
# {機能名} - 仕様書
## コンセプト
### ビジョン
この機能が目指すもの、解決する問題、提供する価値。
### 哲学・設計原則
- 原則1: なぜこの設計を選んだか
- 原則2: トレードオフと判断基準
- 原則3: ユーザー体験への配慮
### 他との違い
既存のソリューションとの違い、独自性。
## 仕様
### 機能仕様
#### FS-001: 機能名
**目的**: この機能が何をするか
**入力/出力**:
- 入力: ...
- 出力: ...
**振る舞い**:
1. ステップ1
2. ステップ2
**制約**:
- 制約1
### インターフェース仕様
\`\`\`kdl
// ユーザーが書く形式
service "example" {
// ...
}
\`\`\`
### 非機能仕様
- **パフォーマンス**: 期待される性能
- **セキュリティ**: セキュリティ考慮事項
- **互換性**: 後方互換性の方針
## 哲学的考察
### なぜこの仕様か
選択の理由、背景にある思想。
### ユーザー体験
ユーザーがどう感じるか、どう使うか。
### 進化の方向性
将来どう発展させるか、拡張の余地。
```
## DESIGN.md のテンプレート
**目的**: モデル、手法、実装
```markdown
# {機能名} - 設計書
## データモデル
### 構造定義
\`\`\`rust
pub struct Example {
field1: Type1,
field2: Type2,
}
\`\`\`
### モデルの関係性
\`\`\`
Model A ---> Model B
|
v
Model C
\`\`\`
## アーキテクチャ
### コンポーネント構成
\`\`\`
Input → Parser → Validator → Processor → Output
\`\`\`
### コンポーネント詳細
#### Component A
**責務**: ...
**インターフェース**:
\`\`\`rust
pub trait ComponentA {
fn method(&self) -> Result<T>;
}
\`\`\`
## 実装手法
### アルゴリズム
処理の流れ、アルゴリズムの選択理由。
### エラーハンドリング
\`\`\`rust #[derive(Error, Debug)]
pub enum MyError { #[error("...")]
Variant,
}
\`\`\`
### パフォーマンス最適化
- 最適化ポイント1
- 最適化ポイント2
## テスト戦略
### ユニットテスト
- テスト対象1
- テスト対象2
### 統合テスト
- シナリオ1
- シナリオ2
## 実装チェックリスト
- [ ] データモデル実装
- [ ] コア機能実装
- [ ] エラーハンドリング
- [ ] テスト作成
```
## GUIDE.md のテンプレート（オプション）
**目的**: 使い方ガイド
```markdown
# {機能名} - ガイド
## クイックスタート
最小限の使用例。
## 基本的な使い方
### ケース1: ...
説明と例。
### ケース2: ...
## ベストプラクティス
- 推奨される使い方
- アンチパターン
## トラブルシューティング
### 問題1: ...
**原因**: ...
**解決策**: ...
```
## 連番の割り当て
| 連番 | 機能 | 状態 |
| ---- | ------------------ | ------ |
| 01 | Core Concept | 作成済 |
| 02 | KDL Parser | 作成済 |
| 03 | Service Management | 未定 |
| 04 | Container Runtime | 未定 |
| 05 | CLI Interface | 未定 |
## ワークフロー
### 新機能追加時
1. `spec/{連番}-{機能名}/` を作成
2. SPEC.md を作成（コンセプト・仕様・哲学）
3. DESIGN.md を作成（モデル・手法・実装）
4. （必要なら）GUIDE.md を作成
5. 実装開始
6. 実装完了後、ドキュメント更新
### 既存機能修正時
1. 該当するspec/ディレクトリを確認
2. SPEC.md/DESIGN.mdを読んで理解
3. 必要に応じてドキュメント更新
4. 実装
## ベストプラクティス
### SPEC.md（コンセプト・仕様・哲学）
- **Why重視**: なぜその選択をしたか
- **ユーザー視点**: 技術詳細より価値を重視
- **哲学を語る**: 設計思想を明確に
### DESIGN.md（モデル・手法・実装）
- **How重視**: どう実装するか
- **実装可能に**: コードに落とし込める粒度
- **技術的詳細**: データ構造、アルゴリズム
### GUIDE.md（使い方）
- **実用的**: すぐ使える例
- **段階的**: 簡単→複雑へ
- **トラブル対応**: よくある問題と解決策