Menu
仕様（Why）と設計（How）を記録し、Living Documentation原則でコードと常に同期させる
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
FleetFlow（KDLベースのコンテナオーケストレーションツール）を効果的に使用するためのガイド
LLMが外部サービスと対話するための適切に設計されたツールを通じて、高品質なMCP (Model Context Protocol) サーバーを作成するためのガイド。Python (FastMCP)、Node/TypeScript (MCP SDK)、Rust (Tokio)で、外部APIやサービスを統合するMCPサーバーを構築する際に使用します。
Rust製非同期Docker APIクライアント「Bollard」の使い方と実装パターン
Based on SOC occupation classification
| name | spec-design-guide |
| description | 仕様（Why）と設計（How）を記録し、Living Documentation原則でコードと常に同期させる |
このスキルは、プロジェクトの仕様・設計ドキュメント作成をガイドし、Living Documentation原則に基づいてドキュメントとコードを同期管理します。
このスキルは以下のように呼ぶことができます：
spec-design-guide → 「仕様設計ガイド」sdg → 「仕様設計ガイド」の略称実装前に仕様と設計を明確にし、実装の助けとなるドキュメントを体系的に管理します。 ドキュメントは「生きた写像」としてコードと常に同期し、技術的負債を防ぎ、生きたメモリーとして機能します。
このスキルは以下の場合に自動的に適用されます：
docs/spec/ ディレクトリ内のファイルを操作する際ユーザーがスキルを明示的に呼び出す方法:
/spec-design-guide または /sdg コマンドWhat & Why - 何を作るか、なぜ作るか
How - どう作るか
Usage - どう使うか
ドキュメントは3つのトップレベルディレクトリに分けて管理します。 すべてフラット構造で、番号付きファイルで管理します：
docs/
├── spec/ # 仕様（What & Why）- フラット、番号付き
│ ├── 01-core-concepts.md # コアコンセプト
│ ├── 02-memory-store.md # メモリストア仕様
│ ├── 03-storage.md # ストレージ仕様
│ ├── 04-embeddings.md # 埋め込み仕様
│ ├── 05-search.md # 検索仕様
│ └── 06-attachments.md # 添付ファイル仕様
├── design/ # 設計（How）- フラット、番号付き
│ ├── 01-system-architecture.md # システムアーキテクチャ
│ ├── 02-data-model.md # データモデル
│ ├── 03-memory-store-api.md # Memory Store API設計
│ ├── 04-storage-integration.md # ストレージ統合（SurrealDB + Qdrant）
│ ├── 05-embedding-integration.md # 埋め込み統合（Plamo）
│ └── 06-search-implementation.md # 検索実装
└── guide/ # ガイド（Usage）- フラット、番号付き
├── 01-getting-started.md # はじめに
├── 02-local-setup.md # ローカル環境セットアップ
└── 03-basic-operations.md # 基本操作
目的: コンセプト、仕様、哲学
ファイル名: docs/spec/{連番}-{機能名}.md（例: docs/spec/01-core-concepts.md）
# {機能名} - 仕様書
## コンセプト
### ビジョン
この機能が目指すもの、解決する問題、提供する価値。
### 哲学・設計原則
- 原則1: なぜこの設計を選んだか
- 原則2: トレードオフと判断基準
- 原則3: ユーザー体験への配慮
### 他との違い
既存のソリューションとの違い、独自性。
### システム概要図
\`\`\`mermaid
flowchart TD
A[入力] --> B[処理]
B --> C[出力]
B --> D{条件分岐}
D -->|Yes| E[処理A]
D -->|No| F[処理B]
\`\`\`
## 仕様
### 機能仕様
#### FS-001: 機能名
**目的**: この機能が何をするか
**入力/出力**:
- 入力: ...
- 出力: ...
**振る舞い**:
1. ステップ1
2. ステップ2
**制約**:
- 制約1
### インターフェース仕様
\`\`\`rust
// ユーザーが使う形式
pub fn example() {
// ...
}
\`\`\`
### 非機能仕様
- **パフォーマンス**: 期待される性能
- **セキュリティ**: セキュリティ考慮事項
- **互換性**: 後方互換性の方針
## 哲学的考察
### なぜこの仕様か
選択の理由、背景にある思想。
### ユーザー体験
ユーザーがどう感じるか、どう使うか。
### 進化の方向性
将来どう発展させるか、拡張の余地。
## 変更履歴
### YYYY-MM-DD: 変更内容
- **理由**: なぜこの変更が必要だったか
- **影響**: どのコンポーネントに影響するか
- **コミット**: コミットハッシュ
目的: モデル、手法、実装
ファイル名: docs/design/{連番}-{設計種類}.md（例: docs/design/01-system-architecture.md）
# {設計種類} - 設計書
## 設計思想: Simplicity（シンプルさ）
シンプルなコードを実現するため、以下の原則に従う。
### 型の分類
基本的に、全ての型は以下に分類される：
- **data**: 値を保持する
- **calculations**（主に同期）: 値を計算する
- **actions**（主に非同期）: 値を操作する
calculations, actionsは関数的に実装されるのが望ましい。
### Straightforward原則
入力から出力までの経路を直線的に、最小限のステップになるように、ロジックを組み立てる。
**これらの原則を守ることで、理解しやすく保守しやすいシンプルなコードが実現される。**
## データモデル
### 構造定義
\`\`\`rust
pub struct Example {
field1: Type1,
field2: Type2,
}
\`\`\`
### モデルの関係性
\`\`\`mermaid
classDiagram
class ModelA {
+field1: Type1
+field2: Type2
+method1()
}
class ModelB {
+field1: Type1
+method1()
}
class ModelC {
+field1: Type1
}
ModelA --> ModelB : uses
ModelA --> ModelC : contains
\`\`\`
## アーキテクチャ
### コンポーネント構成
\`\`\`mermaid
flowchart LR
Input[入力] --> Parser[パーサー]
Parser --> Validator[バリデーター]
Validator --> Processor[プロセッサー]
Processor --> Output[出力]
\`\`\`
### コンポーネント詳細
#### Component A
**責務**: ...
**インターフェース**:
\`\`\`rust
pub trait ComponentA {
fn method(&self) -> Result<T>;
}
\`\`\`
## 実装手法
### アルゴリズム
処理の流れ、アルゴリズムの選択理由。
\`\`\`mermaid
sequenceDiagram
participant User
participant System
participant Database
User->>System: リクエスト
System->>Database: データ取得
Database-->>System: データ
System->>System: 処理
System-->>User: レスポンス
\`\`\`
### エラーハンドリング
\`\`\`rust #[derive(Error, Debug)]
pub enum MyError { #[error("...")]
Variant,
}
\`\`\`
### パフォーマンス最適化
- 最適化ポイント1
- 最適化ポイント2
## テスト戦略
### ユニットテスト
- テスト対象1
- テスト対象2
### 統合テスト
- シナリオ1
- シナリオ2
## 実装チェックリスト
- [ ] データモデル実装
- [ ] コア機能実装
- [ ] エラーハンドリング
- [ ] テスト作成
- [ ] ドキュメント更新
## 変更履歴
### YYYY-MM-DD: 変更内容
- **理由**: なぜこの変更が必要だったか
- **影響**: どのコンポーネントに影響するか
- **コミット**: コミットハッシュ
目的: 実用的な使い方ガイド
ファイル名: docs/guide/{連番}-{トピック名}.md（例: docs/guide/01-getting-started.md）
# {トピック名}
## 概要
このガイドの目的と対象読者。
## 前提条件
- 必要な環境
- 必要な知識
- 必要なツール
## 手順
### ステップ1: ...
詳細な説明とコード例。
```bash
# コマンド例
```
// 実用的なコード例
症状: ... 原因: ... 解決策: ...
Q: ... A: ...
関連するガイドへのリンク。
## 連番の割り当て
| 連番 | 機能 | 状態 |
| ---- | ------------------ | ------ |
| 01 | Core Concepts | 作成済 |
| 02 | Transport Layer | 作成済 |
| 03 | Protocol Layer | 作成済 |
| 04 | Service Integration| 作成済 |
| 05 | Cloud Deployment | 作成済 |
| 06 | Local Storage | 作成済 |
| 07 | HTTP Transport | 作成済 |
## ワークフロー
### 新機能追加時
1. **docs/spec/** に機能仕様を追加
- 次の連番を決定（既存の最大連番 + 1）
- `docs/spec/{連番}-{機能名}.md` を作成（コンセプト・仕様・哲学）
- 例: `docs/spec/07-realtime-sync.md`
2. **docs/design/** に設計を追加
- 設計の種類を決定（architecture, data-model, api, integrationなど）
- 次の連番を決定（既存の最大連番 + 1）
- `docs/design/{連番}-{設計種類}.md` を作成
- 例: `docs/design/07-realtime-architecture.md`
3. **docs/guide/** に使い方を追加（必要に応じて）
- 次の連番を決定（既存の最大連番 + 1）
- `docs/guide/{連番}-{トピック}.md` を作成
- 例: `docs/guide/04-realtime-usage.md`
4. 実装開始
5. 実装完了後、ドキュメント更新
### 既存機能修正時
1. **docs/spec/** で該当機能のファイルを確認（例: `docs/spec/02-memory-store.md`）
2. **docs/design/** で関連する設計ファイルを確認（例: `docs/design/03-memory-store-api.md`）
3. 変更が設計に影響する場合、該当ファイルを更新
4. 実装
5. 必要に応じて **docs/guide/** も更新（例: `docs/guide/03-basic-operations.md`）
### ドキュメント構造の判断基準
**docs/spec/に入れるもの**:
- 機能の「何を」「なぜ」
- ビジネス要件
- ユーザーストーリー
- 連番で優先順位を表現
**docs/design/に入れるもの**:
- 技術的な「どう作るか」
- アーキテクチャ、データモデル、API設計、統合設計
- 連番で重要度を表現
**docs/guide/に入れるもの**:
- 実用的な「どう使うか」
- セットアップ手順、使用例
- 連番で利用順序を表現
### ドキュメント追加の原則
**既存ドキュメントへの追記を優先**:
- 新しい情報を追加する際は、まず既存のドキュメントに含めるのが適切かを検討
- 既存ドキュメントのスコープ内であれば、そちらに追記する
- なるべくドキュメントの種類を増やさない運用を心がける
**新規ドキュメント作成の判断基準**:
- 既存ドキュメントのスコープを超える新しいトピック
- 独立した機能・設計・ガイドとして扱うべき内容
- 既存ドキュメントに追記すると焦点がぼやける場合
**追記時の注意点**:
- セクション構造を維持
- 変更履歴に追記内容を記録
- 関連する他のドキュメントも更新が必要か確認
### ドキュメント構造の定期的な見直し
**見直しのタイミング**:
- 新機能追加時
- 大きな設計変更時
- ドキュメント数が増えてきた時
- ユーザーからドキュメントに関するフィードバックがあった時
**見直しの観点**:
- **整理統合**: 似た内容のドキュメントを統合できないか
- **分割**: 1つのドキュメントが大きくなりすぎていないか
- **連番の再割り当て**: 優先順位・重要度・順序が適切か
- **命名**: ファイル名が内容を適切に表現しているか
- **スコープ**: 各ドキュメントのスコープが明確で重複がないか
**見直しの実施**:
- 構造変更が必要な場合は、ユーザーと相談
- 変更履歴に構造見直しの理由を記録
- 関連する全てのドキュメントを一度に更新
## 実践例
### 機能追加の例
新機能「リアルタイム同期」を追加する場合：
```bash
# 1. 仕様を作成
vim docs/spec/07-realtime-sync.md
# 2. 設計を作成
vim docs/design/07-realtime-architecture.md
# 3. ガイドを作成
vim docs/guide/04-realtime-usage.md
# 4. 実装
# コードを書く...
# 5. コミット
git add docs/spec/07-realtime-sync.md docs/design/07-realtime-architecture.md
git add docs/guide/04-realtime-usage.md packages/creo-memories/src/realtime/
git commit -m "feat: リアルタイム同期機能を追加
## 仕様
- docs/spec/07-realtime-sync.md: リアルタイム同期の仕様
## 設計
- docs/design/07-realtime-architecture.md: リアルタイムアーキテクチャ
## ガイド
- docs/guide/04-realtime-usage.md: 使い方ガイド
## コード
- packages/creo-memories/src/realtime/: リアルタイム機能の実装
## 理由
複数クライアント間でのメモリ同期を実現するため
"
データモデルを変更する場合：
# 1. 該当する仕様を確認
cat docs/spec/01-core-concepts.md
# 2. 設計ドキュメントを更新
vim docs/design/02-data-model.md
# 3. 影響するコードを更新
# コードを変更...
# 4. コミット
git add docs/design/02-data-model.md packages/creo-core/src/types/
git commit -m "refactor: メモリ構造を改善
## 設計変更
- docs/design/02-data-model.md: メタデータ構造を拡張
## コード変更
- packages/creo-core/src/types/memory.ts: Memory型を更新
## 理由
より柔軟なメタデータ管理のため
"
重要: このスキルが有効な場合、コード変更を提案・実装する際は必ず以下を実行してください：
コード設計・実装時は、Simplicity（シンプルさ） を最優先してください。 以下の原則を守ることで、理解しやすく保守しやすいコードを実現します。
全ての型は以下に分類されます：
data: 値を保持する不変データ構造
struct User { id: UserId, name: String }calculations（主に同期）: 値を計算する純粋関数
fn calculate_total(items: &[Item]) -> Moneyactions（主に非同期）: 値を操作する副作用のある関数
async fn save_user(user: &User) -> Result<()>→ これらの原則 = Simplicity（シンプルさ）の実現
docs/spec/{連番}-{機能名}.mdを特定docs/design/配下の関連する設計ファイルを特定して読む（How）
docs/design/01-system-architecture.mddocs/design/02-data-model.mddocs/design/03-memory-store-api.mddocs/design/04-storage-integration.mddocs/design/05-embedding-integration.mddocs/design/06-search-implementation.mddocs/guide/も更新マーメイド図を積極的に活用してください：
flowchart TD
Start[開始] --> Input[入力]
Input --> Process{処理}
Process -->|成功| Success[成功]
Process -->|失敗| Error[エラー]
classDiagram
class Model {
+field: Type
+method()
}
| 図の種類 | 用途 | 使用例 |
|---|---|---|
flowchart | 処理フロー、アーキテクチャ | システム概要、コンポーネント構成 |
sequenceDiagram | 時系列の相互作用 | API呼び出し、メッセージングフロー |
classDiagram | データモデル | 構造体、クラスの関係性 |
stateDiagram | 状態遷移 | ライフサイクル、ステートマシン |
erDiagram | データベース設計 | テーブル関係、エンティティ |
既存ドキュメントへの追記を最優先:
新規ドキュメント作成の判断:
{変更内容の要約}
## 仕様（該当する場合）
- docs/spec/{連番}-{機能名}.md: 更新内容
## 設計（該当する場合）
- docs/design/{連番}-{設計種類}.md: 更新内容
## ガイド（該当する場合）
- docs/guide/{連番}-{トピック}.md: 更新内容
## コード変更
- src/xxx.ts: 変更内容
- packages/yyy/: 変更内容
## 理由
なぜこの変更が必要だったか
## 影響範囲
この変更が影響する範囲
ドキュメントは死んだテキストではなく、生きたコードベースの鏡である
ドキュメントはAIエージェント（Claude）が信頼して活用できる生きたメモリーとして機能する：
AIエージェントの活用シナリオ:
詳細は Living Documentation原則 を参照。
このスキルは、仕様と設計を明確にし、Living Documentation原則に基づいてドキュメントとコードを同期させることで、プロジェクトの品質と保守性を高めます。
キーポイント: