skill-extract

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に適応されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストールされたスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能になっていないプロバイダー、モデル、ホストのサブエージェントを利用できると主張しないでください。 ホストツールの同等機能については、skills/blocks/codex-host-adapter.md を参照してください。

Extract スキル — 実装ガイド

概要

extract スキルは、デザインシステムとプロダクトアーキテクチャの包括的なリバースエンジニアリング機能を提供します。ドキュメント化されていないコードベースを、構造化された実装可能なドキュメントに変換します。

機能

デザインシステムの抽出

• トークンの抽出：コードまたは CSS から色、タイポグラフィ、間隔、シャドウを抽出します
• コンポーネント分析：React／Vue／Svelte 全体の Props、バリアント、使用パターンを分析します
• パターン検出：レイアウトパターン、デザインルール、アクセシビリティガイドラインを検出します
• Storybook の生成：バリアントとコントロールを含むストーリーを自動生成します

プロダクトアーキテクチャの抽出

• サービス検出：マイクロサービスの境界、モジュール、ドメイン境界を検出します
• API マッピング：REST、GraphQL、tRPC、gRPC エンドポイントをカタログ化します
• データモデリング：ORM スキーマを抽出します（Prisma、TypeORM、Sequelize）
• 機能一覧の作成：ルートベースおよびドメインベースで機能を検出します
• C4 図：アーキテクチャを自動で可視化します（Mermaid）

技術的な実装

トークン抽出パイプライン

優先順位（信頼度の高い順）：

1. コードで定義（95%）：theme.ts、tokens.json、Tailwind 設定
2. CSS 変数（90%）：:root 宣言
3. 計算済みスタイル（60%）：DOM 分析
4. 推定（40～60%）：色のクラスタリング、スケールの検出

色のクラスタリングアルゴリズム：

• 知覚的に正確な色差の算出に CIEDE2000 を使用します
• 安定したクラスタリングのために K-means++ で初期化します
• プライマリパレットにはデフォルトで k=8 クラスターを使用します
• 重複検出には ΔE < 2 のしきい値を使用します

コンポーネント分析

検出方法：

• TypeScript／JavaScript の AST 解析
• インターフェースと PropTypes から Props を抽出
• Union 型からバリアントを検出
• コードベース全体で使用状況を追跡

対応フレームワーク：

• React（関数コンポーネント、クラス、フック）
• Vue（SFC、Composition API、Options API）
• Svelte（スクリプト／テンプレートの分離）

アーキテクチャの検出

サービス境界のヒューリスティクス：

• サブディレクトリ内の package.json
• 独立したデプロイ設定
• チームの所有権境界
• 通信パターンの分析

API エンドポイントの検出：

• デコレーターを使用したルーティング（NestJS、routing-controllers）
• Express／Fastify のルート定義
• GraphQL リゾルバークラス
• tRPC ルータープロシージャ
• Protocol Buffer（.proto）ファイル

マルチ AI オーケストレーション

有効にすると、extract 機能は複数の AI プロバイダーを使用して精度を高めます。

プロバイダーの役割：

• Claude：統合、競合の解決、ドキュメント作成
• Codex：コードレベルの分析、型の抽出、アーキテクチャ
• Antigravity：パターン認識、別の解釈、UX に関する洞察

合意メカニズム：

• しきい値：抽出品質のゲートでは、設定された合意しきい値（デフォルトは 67%）が必要です。数値の投票データがない場合、クォーラムリゾルバーは最大 3 つのプロバイダーの見解から最も一致する提案を選び、意見の相違を記録します。
• 意見の相違は 90_evidence/disagreements.md に記録されます
• すべての出力に信頼度スコアが付与されます

出力構造

octopus-extract/
└── project-name/
    └── timestamp/
        ├── README.md                   # Navigation and summary
        ├── metadata.json               # Extraction parameters
        │
        ├── 00_intent/
        │   ├── answers.json            # User intent responses
        │   ├── intent-contract.md      # Human-readable summary
        │   └── detection-report.md     # Stack auto-detection results
        │
        ├── 10_design/
        │   ├── tokens.json             # W3C Design Tokens format
        │   ├── tokens.css              # CSS custom properties
        │   ├── tokens.md               # Human-readable token docs
        │   ├── components.csv          # Component inventory (tabular)
        │   ├── components.json         # Structured component data
        │   ├── patterns.md             # Layout and design patterns
        │   └── storybook/              # Storybook scaffold (optional)
        │       ├── .storybook/
        │       └── stories/
        │
        ├── 20_product/
        │   ├── product-overview.md     # What, who, key journeys
        │   ├── feature-inventory.md    # Features by domain
        │   ├── architecture.md         # C4 text description
        │   ├── architecture.mmd        # Mermaid C4 diagrams
        │   ├── PRD.md                  # AI-agent executable PRD
        │   ├── user-stories.md         # Gherkin-style scenarios
        │   ├── api-contracts.md        # Endpoint specifications
        │   ├── data-model.md           # Entity relationships
        │   └── implementation-plan.md  # Phased milestones
        │
        └── 90_evidence/
            ├── quality-report.md       # Coverage and confidence metrics
            ├── disagreements.md        # Multi-AI conflicts
            ├── extraction-log.md       # Timestamped progress log
            └── references.json         # File paths per claim

品質ゲート

自動検証により、抽出品質を確保します。

1. トークンの網羅性：デザインモードでトークンが 0 件の場合は失敗します
2. コンポーネントの網羅性：検出されたコンポーネントファイルが 50% 未満の場合は警告します
3. アーキテクチャの完全性：プロダクトモードでサービスが検出されない場合は警告します
4. マルチ AI の合意：主要な出力に対する一致率が設定された合意しきい値（デフォルトは 67%）を下回る場合は失敗します

使用パターン

基本的な抽出

/octo:extract ./my-app

デザインのみの抽出

/octo:extract ./my-app --mode design --storybook true

マルチ AI による詳細な分析

/octo:extract ./my-app --depth deep --multi-ai force

URL 抽出

/octo:extract https://example.com --mode design --depth quick

他のスキルとの連携

• /octo:review: 抽出された出力の品質をレビューします
• /octo:deliver: 抽出の完全性を検証します
• /octo:docs: 抽出結果から追加のドキュメントを生成します

エラー処理

一般的なエラーコード:

• ERR-001: 無効な入力（パス/URL が見つかりません）
• ERR-002: ネットワークタイムアウト（URL 抽出）
• ERR-003: 権限が拒否されました
• ERR-004: メモリ不足（--depth quick を使用してください）
• VAL-001: 検証に失敗しました（トークンが検出されませんでした）
• VAL-004: マルチ AI のコンセンサスが低い

パフォーマンス目標

深度	時間目標	カバレッジ目標
Quick	2 分未満	70% カバレッジ、基本分析
Standard	2〜5 分	85% カバレッジ、包括的
Deep	5〜15 分	95% カバレッジ、マルチ AI 検証

調査ソース

このスキルは以下の調査に基づいています:

• Tokens Studio - デザイントークンの自動化
• Superposition - Web サイトからのトークン抽出
• W3C Design Tokens - トークン形式の標準
• C4 Model - アーキテクチャのダイアグラム化
• 現代のリバースエンジニアリング手法（2026）

実装状況

現在のバージョン: 1.0.0（スケルトン）

実装済み:

• ✅ コマンド構造
• ✅ CLI 引数の解析
• ✅ 出力ディレクトリのセットアップ
• ✅ メタデータの生成
• ✅ マルチ AI 検出

進行中:

• 🚧 トークン抽出パイプライン
• 🚧 コンポーネント分析エンジン
• 🚧 アーキテクチャ検出
• 🚧 PRD 生成
• 🚧 品質ゲート

計画中:

• ⏳ Storybook スキャフォールドの生成
• ⏳ C4 ダイアグラムの生成
• ⏳ URL 抽出モード
• ⏳ CSS 推論アルゴリズム

コントリビューション

プロジェクトドキュメントの実装計画を参照してください。

実装フェーズ:

1. 基盤と CLI（第 1 週）
2. 自動検出エンジン（第 2 週）
3. デザイン抽出（第 3〜4 週）
4. プロダクト抽出（第 5〜6 週）
5. マルチ AI オーケストレーション（第 7 週）
6. 品質ゲート（第 8 週）
7. テストとドキュメント（第 10 週）

このスキルは PRD v2.0（AI-Executable）で指定された設計を実装しています