Menu
仕様（Why）と設計（How）を記録し、Living Documentation原則でコードと常に同期させる
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| 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原則に基づいてドキュメントとコードを同期させることで、プロジェクトの品質と保守性を高めます。
キーポイント:
FleetFlow（KDLベースのコンテナオーケストレーションツール）を効果的に使用するためのガイド
LLMが外部サービスと対話するための適切に設計されたツールを通じて、高品質なMCP (Model Context Protocol) サーバーを作成するためのガイド。Python (FastMCP)、Node/TypeScript (MCP SDK)、Rust (Tokio)で、外部APIやサービスを統合するMCPサーバーを構築する際に使用します。
Rust製非同期Docker APIクライアント「Bollard」の使い方と実装パターン