Write-Spec Skill

参照ドキュメント（survey結果、PDF、ソースコード等）をもとに、実装仕様書を生成します。

使用方法

/write-spec <対象システム名> [--refs <参照パス...>] [--scope <スコープ>] [--output <出力パス>] [--template <テンプレート名>]

引数

• 対象システム名（必須）: 仕様書の対象となるシステムやコンポーネントの名前
• --refs: 参照する資料のパス（カンマ区切りで複数指定可）。survey結果、PDF、ソースコード等
• --scope: 仕様書のスコープ（例: telemetry, commands, navigation, full）。省略時: full
• --output: 出力先ファイルパス（省略時: ./docs/<システム名>_spec.md）
• --template: 使用するテンプレート（省略時: fleet-adapter）
  • fleet-adapter: ロボットフリートアダプター向け（テレメトリ・コマンド・ナビゲーション）
  • api: API仕様書向け（エンドポイント・リクエスト/レスポンス）
  • generic: 汎用仕様書

処理手順

Step 1: 入力解析と参照資料の読み込み

$ARGUMENTS を解析し、以下を特定する:

1. 対象システム名: 仕様書のタイトルとスコープを決定
2. 参照パス: 指定された資料を順に読み込む
   • *.md → Readで直接読み込み
   • *.pdf → Readのpagesパラメータで分割読み込み（12ページ単位）
   • ディレクトリ → Glob + Grep で関連ファイルを特定して読み込み
   • URL → WebFetchで取得

引数が空の場合はAskUserQuestionで以下を確認:

• 対象システム名
• 参照資料のパス
• 仕様書のスコープ

Step 2: 既存コードベースの調査

参照パスにソースコードが含まれる場合、以下を自動抽出する:

1. データ型定義: クラス、型エイリアス、Enum定義
2. API定義: エンドポイント、メソッドシグネチャ
3. 設定項目: 環境変数、設定ファイルのキー
4. エラーコード: エラー定義、例外クラス

# 調査例
Grep: pattern="class.*Telemetry|type.*Telemetry|interface.*Telemetry"
Grep: pattern="class.*Command|type.*Command|interface.*Command"
Grep: pattern="enum |Enum|ERROR_CODE|ErrorCode"
Grep: pattern="ENV|config\[|getenv|os\.environ"

Step 3: 情報の構造化

読み込んだ参照資料から以下を構造化する:

1. プロトコル仕様: 通信方式、データフォーマット、メッセージ構造
2. テレメトリ定義: 各テレメトリの型、フィールド、送信頻度、JSON構造
3. コマンド定義: 各コマンドの型、パラメータ、レスポンス、JSON構造
4. 変換ロジック: 外部APIと内部表現の変換マッピング
5. エラーハンドリング: エラーコード、リトライ戦略、フォールバック
6. 設定項目: 必須/任意の設定パラメータ、デフォルト値

Step 4: 仕様書生成

テンプレートに従ってMarkdown仕様書を生成する。

重要な記述ルール:

• JSON例は正確に: 参照資料から取得した実際のフィールド名・型・構造を使用する。推測で書かない
• Enum値は網羅: 全てのEnum値をテーブルで列挙する
• フィールド定義は必須/任意を明記: 各フィールドに Required/Optional を記載する
• 変換ロジックは表形式: 入力→出力の対応を変換テーブルで記述する
• コード参照を含める: 実装時に参照すべきファイル・関数への具体的なパスを記載する

Step 5: 不明点の確認

仕様が曖昧な箇所がある場合、AskUserQuestionで確認する:

• 未定義のフィールドのデフォルト値
• 複数の解釈が可能な仕様
• 参照資料間で矛盾がある箇所

Step 6: ファイル出力

• --output が指定されている場合はそのパスに出力
• 未指定の場合は ./docs/<システム名>_spec.md に出力
• 出力先ディレクトリが存在しない場合は Bash の mkdir -p で作成
• Write ツールでファイルを書き出す

テンプレート: fleet-adapter

# [システム名] 仕様書

| 項目 | 値 |
|------|-----|
| 対象システム | [システム名] |
| バージョン | v0.1.0 (draft) |
| 作成日 | YYYY-MM-DD |
| 参照資料 | [資料1], [資料2], ... |

## 1. 概要

### 1.1 目的
[このシステムの目的と役割]

### 1.2 アーキテクチャ
[システム構成図、通信フロー]

### 1.3 用語定義

| 用語 | 定義 |
|------|------|
| ... | ... |

## 2. 通信プロトコル

### 2.1 通信方式
[WebSocket / Redis Pub/Sub / REST API 等]

### 2.2 共通メッセージ構造
[ヘッダーフォーマット、認証情報、シーケンス番号等]

```json
{
  "header": {
    "seq": 0,
    "timestamp": "2026-01-01T00:00:00.000Z"
  },
  "robotId": "robot-001",
  "data": { ... }
}

2.3 接続パラメータ

3. テレメトリ

[各テレメトリ種別ごとにサブセクションを作成]

3.N [テレメトリ名]

概要: [1行の説明] 送信頻度: [頻度] トピック/チャネル: [通信チャネル名]

フィールド定義

JSON例

{
  ...正確なJSON例（参照資料から取得した実際の構造を使用）
}

変換ロジック

4. コマンド

[各コマンド種別ごとにサブセクションを作成]

4.N [コマンド名]

概要: [1行の説明] トピック/チャネル: [通信チャネル名]

リクエスト

{
  ...リクエストJSON例
}

レスポンス / ACK

{
  ...レスポンスJSON例
}

処理フロー

1. コマンド受信
2. バリデーション
3. ロボットAPI呼び出し
4. 結果変換
5. レスポンス送信

エラーケース

5. ナビゲーション

5.1 座標系

[座標系の定義、変換方法]

5.2 フロア管理

[フロアIDとマップ名のマッピング]

5.3 ウェイポイント

[ウェイポイント定義、名前解決]

6. 施設連携

6.1 エレベーター

[エレベーター連携の仕様]

6.2 自動ドア

[自動ドア連携の仕様]

7. エラーハンドリング

7.1 エラーコード一覧

7.2 リトライ戦略

[リトライ回数、バックオフ、タイムアウト]

7.3 フォールバック

[フォールバック動作の定義]

8. 設定

8.1 環境変数

8.2 設定ファイル

[設定ファイルのフォーマットと項目]

9. コード参照

実装時に参照すべきファイル:

付録

A. Enum定義

[全Enum値のテーブル]

B. 全JSON構造一覧

[全メッセージのJSON構造を1箇所にまとめて掲載]

## テンプレート: api

```markdown
# [システム名] API仕様書

## 1. 概要
## 2. 認証
## 3. エンドポイント一覧
## 4. 各エンドポイント詳細
### 4.N [エンドポイント名]
- Method: GET/POST/PUT/DELETE
- Path: /api/v1/...
- Request Body / Query Parameters
- Response
- Error Codes
## 5. データモデル
## 6. エラーコード一覧
## 7. 設定

テンプレート: generic

# [システム名] 仕様書

## 1. 概要
## 2. アーキテクチャ
## 3. 機能仕様
## 4. データ定義
## 5. インターフェース
## 6. エラーハンドリング
## 7. 設定
## 8. 参照

注意事項

• 推測しない: 参照資料に記載のない仕様は推測で埋めず、TBDまたは要確認と明記する
• JSON例は実データベース: 参照資料のサンプルデータやフィールド名をそのまま使用する
• 整合性チェック: 複数の参照資料間でデータ型やフィールド名に矛盾がないか確認する
• 不明点はAskUserQuestionで確認: 仕様が曖昧な場合は作者に確認する
• 出力は日本語: セクションタイトルは日本語、フィールド名・JSON等の技術用語は原語のまま

実行対象

$ARGUMENTS