仕様(Why)と設計(How)を記録し、Living Documentation原則でコードと常に同期させる
This skill inherits all available tools. When active, it can use any tool Claude has access to.
このスキルは、プロジェクトの仕様・設計ドキュメント作成をガイドし、Living Documentation原則に基づいてドキュメントとコードを同期管理します。
このスキルは以下のように呼ぶことができます:
spec-design-guide → 「仕様設計ガイド」sdg → 「仕様設計ガイド」の略称実装前に仕様と設計を明確にし、実装の助けとなるドキュメントを体系的に管理します。 ドキュメントは「生きた写像」としてコードと常に同期し、技術的負債を防ぎ、生きたメモリーとして機能します。
重要: すべてのドキュメントはCreo Memoriesに保存されます。
sdg(domain:019b1c05-b0d6-7eb8-95a6-1aa0c5601338)spec, design, guideドキュメントの操作にはCreo Memories MCPツールを使用します:
// ドキュメントを保存
remember_context({
content: "# Core Concepts - 仕様書\n...",
category: "spec",
tags: ["core-concepts", "architecture"],
metadata: {
title: "Core Concepts - 仕様書",
docType: "spec"
}
})
// ドキュメントを検索
recall_relevant({
sessionId: "...",
query: "認証システム設計",
threshold: 0.7
})
// カテゴリで一覧
search_memories({
category: "spec",
limit: 20
})
このスキルは以下の場合に自動的に適用されます:
ユーザーがスキルを明示的に呼び出す方法:
/spec-design-guide または /sdg コマンドWhat & Why - 何を作るか、なぜ作るか
How - どう作るか
Usage - どう使うか
目的: コンセプト、仕様、哲学
カテゴリ: spec
タグ: 機能名(例: core-concepts, storage, mcp)
# {機能名} - 仕様書
## コンセプト
### ビジョン
この機能が目指すもの、解決する問題、提供する価値。
### 哲学・設計原則
- 原則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
### インターフェース仕様
\`\`\`typescript
// ユーザーが使う形式
function example() {
// ...
}
\`\`\`
### 非機能仕様
- **パフォーマンス**: 期待される性能
- **セキュリティ**: セキュリティ考慮事項
- **互換性**: 後方互換性の方針
## 哲学的考察
### なぜこの仕様か
選択の理由、背景にある思想。
### ユーザー体験
ユーザーがどう感じるか、どう使うか。
### 進化の方向性
将来どう発展させるか、拡張の余地。
## 変更履歴
### YYYY-MM-DD: 変更内容
- **理由**: なぜこの変更が必要だったか
- **影響**: どのコンポーネントに影響するか
- **コミット**: コミットハッシュ
目的: モデル、手法、実装
カテゴリ: design
タグ: 設計種類(例: architecture, data-model, api)
# {設計種類} - 設計書
## 設計思想: Simplicity(シンプルさ)
シンプルなコードを実現するため、以下の原則に従う。
### 型の分類
基本的に、全ての型は以下に分類される:
- **data**: 値を保持する
- **calculations**(主に同期): 値を計算する
- **actions**(主に非同期): 値を操作する
calculations, actionsは関数的に実装されるのが望ましい。
### Straightforward原則
入力から出力までの経路を直線的に、最小限のステップになるように、ロジックを組み立てる。
**これらの原則を守ることで、理解しやすく保守しやすいシンプルなコードが実現される。**
## データモデル
### 構造定義
\`\`\`typescript
interface 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
**責務**: ...
**インターフェース**:
\`\`\`typescript
interface ComponentA {
method(): Promise<T>
}
\`\`\`
## 実装手法
### アルゴリズム
処理の流れ、アルゴリズムの選択理由。
\`\`\`mermaid
sequenceDiagram
participant User
participant System
participant Database
User->>System: リクエスト
System->>Database: データ取得
Database-->>System: データ
System->>System: 処理
System-->>User: レスポンス
\`\`\`
### エラーハンドリング
\`\`\`typescript
class MyError extends Error {
constructor(message: string) {
super(message)
}
}
\`\`\`
### パフォーマンス最適化
- 最適化ポイント1
- 最適化ポイント2
## テスト戦略
### ユニットテスト
- テスト対象1
- テスト対象2
### 統合テスト
- シナリオ1
- シナリオ2
## 実装チェックリスト
- [ ] データモデル実装
- [ ] コア機能実装
- [ ] エラーハンドリング
- [ ] テスト作成
- [ ] ドキュメント更新
## 変更履歴
### YYYY-MM-DD: 変更内容
- **理由**: なぜこの変更が必要だったか
- **影響**: どのコンポーネントに影響するか
- **コミット**: コミットハッシュ
目的: 実用的な使い方ガイド
カテゴリ: guide
タグ: トピック名(例: getting-started, deployment, troubleshooting)
# {トピック名}
## 概要
このガイドの目的と対象読者。
## 前提条件
- 必要な環境
- 必要な知識
- 必要なツール
## 手順
### ステップ1: ...
詳細な説明とコード例。
```bash
# コマンド例
```
// 実用的なコード例
症状: ... 原因: ... 解決策: ...
Q: ... A: ...
関連するガイドへのリンク。
## ワークフロー
### 新機能追加時
1. **spec** にドキュメントを保存
```typescript
remember_context({
content: "# 新機能 - 仕様書\n...",
category: "spec",
tags: ["new-feature", "v2"]
})
design に設計を保存
remember_context({
content: "# 新機能 - 設計書\n...",
category: "design",
tags: ["new-feature", "architecture"]
})
guide に使い方を追加(必要に応じて)
実装開始
実装完了後、ドキュメント更新
関連する仕様を検索
recall_relevant({
sessionId: "...",
query: "該当機能の仕様"
})
設計ドキュメントを検索・確認
変更が設計に影響する場合、ドキュメントを更新
実装
// セマンティック検索(意味で検索)
recall_relevant({
sessionId: "...",
query: "認証システムの設計",
threshold: 0.7
})
// カテゴリ検索
search_memories({
category: "spec",
limit: 20
})
// タグ検索
search_memories({
tags: ["authentication"],
limit: 10
})
重要: このスキルが有効な場合、コード変更を提案・実装する際は必ず以下を実行してください:
コード設計・実装時は、Simplicity(シンプルさ) を最優先してください。 以下の原則を守ることで、理解しやすく保守しやすいコードを実現します。
全ての型は以下に分類されます:
data: 値を保持する不変データ構造
interface User { id: UserId; name: string }calculations(主に同期): 値を計算する純粋関数
function calculateTotal(items: Item[]): Moneyactions(主に非同期): 値を操作する副作用のある関数
async function saveUser(user: User): Promise<void>→ これらの原則 = Simplicity(シンプルさ)の実現
マーメイド図を積極的に活用してください:
ドキュメントは死んだテキストではなく、生きたコードベースの鏡である
ドキュメントはAIエージェント(Claude)が信頼して活用できる生きたメモリーとして機能する:
このスキルは、仕様と設計を明確にし、Living Documentation原則に基づいてドキュメントとコードを同期させることで、プロジェクトの品質と保守性を高めます。
キーポイント: