spikes

---

これは何ですか？

Spikes は、AI 支援開発向けのフィードバックツールです。レビュアーはスクリーンショットを使ったり、「あそこのボタン」と説明したり、コンテキストを失ったりすることなく、Web ページ上で対象を絞ったフィードバックを直接残せます。

任意の要素をクリックして、評価し、コメントできます。Spikes は正確な CSS セレクター、バウンディングボックス、ページのコンテキストを取得します。AI エージェントは、すぐに対応できる構造化 JSON を受け取ります。

アカウントは不要です。ビルド手順も不要です。file://、localhost など、どこでも動作します。

---

クイックスタート

1. CLI をインストールする

curl -fsSL https://spikes.sh/install.sh | sh
# Or: cargo install spikes

2. プロジェクトを初期化する

spikes init                     # Defaults to hosted spikes.sh
# spikes init --self-host       # Opt out — scaffold a self-hosted config instead

spikes init は、デフォルトで https://spikes.sh を指す [remote] セクションを含む .spikes/config.toml を作成します。ホスト型のデフォルト設定をスキップするには、--self-host を渡すか、プロンプトで s と回答します。

3. ウィジェットを HTML に追加する

spikes inject ./mockups/        # Injects widget script tag (uses configured endpoint)
spikes serve                    # http://localhost:3847

4. フィードバックを収集して活用する

spikes list                     # See all feedback
spikes list --json              # Feed to your agent
spikes list --rating no         # Find problems
spikes hotspots                 # Elements with most feedback
spikes resolve <id>             # Mark items done

---

CLI コマンド

コマンド	説明
spikes init	設定ファイルを含む .spikes/ ディレクトリを作成します（デフォルトはホスト型。利用しない場合は --self-host）
spikes list	フィードバックを一覧表示します（--json、--page、--reviewer、--rating、--unresolved）
spikes show <id>	個別のスパイクの詳細を表示します
spikes export	JSON／CSV／JSONL／Cursor／Claude のコンテキストにエクスポートします
spikes hotspots	フィードバックが最も多い要素を表示します
spikes reviewers	すべてのレビュアーを一覧表示します
spikes inject <dir>	HTML ファイルへのウィジェットの追加／削除を行います（--endpoint <url> で設定済みのエンドポイントを上書きできます）
spikes serve	ローカル開発サーバーを起動します（--port、--marked、--cors-allow-origin）
spikes mcp serve	AI エージェント連携用の MCP サーバーを起動します
spikes pull/push/sync	リモートエンドポイントと同期します
spikes share <dir>	spikes.sh にアップロードしてすぐに共有します
spikes login/logout/whoami	認証を管理します
spikes upgrade/billing	Stripe 経由で Pro プランに登録します
spikes deploy cloudflare	セルフホスト可能な Worker と D1 のひな形を作成します

すべてのコマンドで、スクリプトから利用するための --json を指定できます。CLI リファレンス全文をご覧ください。

ホスト型プロジェクトのスパイクを表示する：

ホスト型ダッシュボード https://spikes.sh/dashboard では、所有するすべてのプロジェクトを一覧表示し、個々のスパイクを確認できます（ページ、評価、解決済みで絞り込み、resolved をインラインで切り替えられます）。ブラウザーから直接サインインできます。Sign in をクリックし、確認ページを開いて、メールで届いたマジックリンクから承認します。CLI は不要です。

ベアラートークン（spikes login で取得する $SPIKES_TOKEN）を使って、JSON API に直接アクセスすることもできます。

# GET /me/projects
# List all projects you own (with spike_count + last_activity)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  https://spikes.sh/me/projects

# GET /me/projects/:key/spikes
# List spikes for one of your projects (paginated, filterable: page, per_page,
# filter_page, filter_rating, filter_resolved)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  "https://spikes.sh/me/projects/my-project/spikes?page=1&per_page=50"

# PATCH /me/projects/:key/spikes/:id
# Toggle the `resolved` flag on one spike
curl -X PATCH -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}' \
  https://spikes.sh/me/projects/my-project/spikes/<spike_id>

# POST /projects
# Create a new project (user bearer only)
curl -X POST -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "my-project", "allowed_origins": ["https://example.com"]}' \
  https://spikes.sh/projects

# Single-line variant (copy-paste friendly)
curl -H "Authorization: Bearer $SPIKES_TOKEN" https://spikes.sh/me/projects

すべての /me/* エンドポイントはユーザー単位でスコープされており、自分が所有するプロジェクトとスパイクだけを参照できます。別のテナントへのリクエストは 404 PROJECT_NOT_FOUND を返します（列挙による特定を防止）。

セキュリティに関する注意： API キー（sk_spikes_*）と管理者用の SPIKES_TOKEN は、/me/* エンドポイントおよび POST /projects では受け付けられません。これらには spikes login で取得したユーザーベアラートークンが必要です。POST /spikes の収集エンドポイントでは、プロジェクトごとのオリジン許可リストとレート制限が適用されます。拒否されたウィジェットリクエストは、ウィジェットボタン上に小さな赤い #spikes-error-dot インジケーター（404／403／429）として表示されます。

---

AI エージェントとの連携

Spikes はエージェントに標準対応しています。AI コーディングアシスタントは、ワークフローを離れることなくフィードバックを読み取り、書き込み、管理できます。

npx spikes-mcp            # Zero-install MCP server — just works
# or: spikes mcp serve    # If you have the CLI installed

MCP サーバー — 16 個のツール

spikes mcp serve を実行すると、16 個のツールを公開する Model Context Protocol サーバーが起動します。

ツール	目的
get_spikes	フィルター（ページ、評価、未解決、url_prefix、since）を指定してフィードバックを一覧表示
get_element_feedback	特定の CSS セレクターに対するフィードバックを取得
get_hotspots	フィードバックが最も多い要素を検索
submit_spike	プログラムからフィードバックを作成
resolve_spike	フィードバックを対応済みとしてマーク
delete_spike	スパイクを削除
create_share	ファイルをアップロードして共有可能な URL を取得
list_shares	有効な共有を確認
get_usage	使用状況、上限、支出を確認
reply_to_spike	ページ上でレビュアーに回答（任意でステータスとバージョンも指定可能）（ホスト型）
set_spike_status	スパイクを未対応、対応済み、または対応しないとしてマーク（ホスト型）
list_versions / add_version	レビュー対象のバージョンを登録し、バージョンごとの件数を確認（ホスト型）
list_questions / ask_question / get_question_answers	レビュアーに質問し、回答を読む（ホスト型）

stdio および HTTP トランスポート、ローカル および リモートのデータモードに対応しています。

spikes mcp serve                              # stdio, local JSONL
spikes mcp serve --remote                     # stdio, hosted API
spikes mcp serve --transport http --port 3848 # HTTP for sandboxed agents

API キー

エージェントにはそれぞれ独自の ID が割り当てられます。メールアドレスも、マジックリンクも、人手による手順も不要です。

spikes auth create-key --name "my-agent"   # → sk_spikes_...
spikes auth list-keys                       # See all keys
spikes auth revoke-key <key_id>            # Revoke

キーは読み取り、書き込み、フルのスコープと、任意の予算上限に対応しています。

エージェント向けの従量課金

エージェント規模の使用に適した従量課金制です。シート単位ではなく、スパイクごとに支払います。

spikes usage    # See current spend and limits

予算上限に達すると、予算の適用により 429 BUDGET_EXCEEDED が返されます。エージェントは上限を超える前に確認できます。

コンテキストのエクスポート

エージェントが利用しやすい形式に最適化された、構造化 Markdown をエクスポートします。

spikes export --format cursor-context > cursor-feedback.md
spikes export --format claude-context > claude-feedback.md

検出

• llms.txt — 9 個すべての MCP ツール、パラメーター、エージェント向けクイックスタート
• agents.md — エージェント向けの機械可読なランディングページ
• Smithery — MCP サーバーレジストリに掲載
• spikes mcp install — Claude Desktop / Cursor 用の設定を生成

詳細はこちら：llms.txt · agents.md

---

GitHub Action

フィードバックの品質に基づいて CI を制御します。未解決の否定的なフィードバックが設定したしきい値を超えると、spikes-action はビルドを失敗させます。

name: CI
on: [push, pull_request]

jobs:
  feedback-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bierlingm/spikes/[email protected]
        with:
          threshold: 0           # Fail if any blocking spikes
          ignore-paths: ""     # Optional: pages to ignore
          require-resolution: false

詳しいドキュメントについては、action/README.md をご覧ください。

---

ウィジェットの属性

簡単なセットアップ — プロジェクトキーを追加するだけで、フィードバックを収集できます。

<script src="https://spikes.sh/spikes.js" data-project="my-app"></script>

data-project を設定すると、フィードバックは自動的に https://spikes.sh/spikes に同期されます。セルフホストする場合を除き、エンドポイントの設定は不要です。

完全な設定 — 使用できるすべての属性：

<script src="https://spikes.sh/spikes.js"
  data-project="my-app"
  data-position="bottom-right"
  data-color="#e74c3c"
  data-theme="dark"
  data-reviewer="Pat"
  data-collect-email="true"
  data-admin="true">
</script>

セルフホスト — 独自のバックエンドを指定します。

<script src="/spikes.js"
  data-project="my-app"
  data-endpoint="https://my-worker.workers.dev/spikes">
</script>

属性	説明	デフォルト
data-project	プロジェクトキーでフィードバックをグループ化	location.hostname
data-position	ボタンの角：bottom-right、bottom-left、top-right、top-left	bottom-right
data-color	アクセントカラー（任意の CSS カラー）	#e74c3c
data-theme	モーダルのテーマ：dark または light	dark
data-reviewer	レビュアー名を事前設定	（ユーザーに入力を求める）
data-endpoint	複数レビュアー間の同期に使用するバックエンド URL。任意 — data-project が設定されている場合、デフォルトは https://spikes.sh/spikes です。	https://spikes.sh/spikes（data-project 設定時）、/spikes（ローカル開発時）
data-collect-email	プロンプトにメールアドレス欄を表示	false
data-admin	レビューモードの機能を有効化	false
data-offset-x/y	端からのボタンのオフセット	—

詳しいドキュメントについては、ウィジェット属性リファレンスをご覧ください。

アーキテクチャ

Spikes は、連携しても単独でも動作する 3 つのコンポーネントで構成されています。

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CLI       │────▶│   Widget    │◄────│   Worker    │
│  (Rust)     │     │  (Vanilla   │     │ (Cloudflare │
│             │     │    JS)      │     │  + D1)      │
└─────────────┘     └─────────────┘     └─────────────┘
     │                                            │
     │          spikes.sh (hosted)                │
     └────────────────────────────────────────────┘

CLI — ローカル開発、スパイク管理、デプロイ向けの Rust バイナリです。スパイクは ~/.local/share/spikes/ に保存されます。

ウィジェット — gzip 圧縮時に 14KB のバニラ JS です。要素セレクター、バウンディングボックス、評価、コメントを取得します。localStorage を使ってオフラインで動作します。

Worker — 複数レビュアー間の同期、共有、ホスト型デプロイに対応するオプションの Cloudflare Worker + D1 バックエンドです。spikes-hosted/ にあります。

---

開発

CLI

cd cli
cargo build --release
cargo test              # 160+ tests
cargo run -- --help

ウィジェット

cd widget
# Edit src/spikes.js
# Test by running: spikes serve from the project root

ウィジェットのリグレッションテスト

サイレントデータ損失のバグを検出する CI スイートです（例：許可されていないオリジンで読み込まれたウィジェットが、エラーを表示せずに同期に失敗するケース）。

cd tests/widget
npm install
npx playwright install chromium    # one-time
npm test                           # 23 tests: marker checks + happy/reverse/boundary specs (<60s)

ローカルの agent-ci にも組み込まれています。

npx agent-ci run --workflow workflows-local/widget.yml

Worker

Worker バックエンドは非公開の spikes-hosted リポジトリにあります。テストするには：

cd ../spikes-hosted/worker
npm test              # Worker test suite (vitest)
npx wrangler dev

---

セルフホスティング

独自のバックエンドが必要ですか？コマンド 1 つでセットアップできます。

spikes deploy cloudflare    # Creates spikes-worker/ directory
cd spikes-worker && npx wrangler deploy

D1 データベース、認証、Stripe の請求連携を含む詳細なセットアップについては、セルフホスティングガイドをご覧ください。

Share と Deploy Cloudflare：どちらを選ぶべきですか？

セットアップなしですぐに共有したい場合は、spikes share を使ってください。ファイルが spikes.sh にアップロードされ、当社のインフラから配信されます。手早いレビューやクライアントからのフィードバックを得たい場合、またはバックエンドを管理したくない場合に最適です。

データの分離（フィードバックが自身の Cloudflare アカウント内に保持されます）、カスタムドメインが必要な場合、またはインフラを完全に管理したい場合は、spikes deploy cloudflare を使ってください。セルフホスティングには Cloudflare アカウントと、初回のデプロイ設定が必要です。

---

変更点（最近の大規模改修）

• セキュリティ：PBKDF2 によるパスワードハッシュ化、パストラバーサルの修正、XSS 対策
• 認証：マジックリンク認証（忘れる心配のあるパスワードは不要）
• 請求：Pro ティアに対応した Stripe 連携
• テスト：CLI テストスイート（Rust）+ Worker テストスイート（../spikes-hosted/worker 内）
• アーキテクチャ：関心事を明確に分離したモジュール式 Worker
• CI/CD：テストとデプロイのパイプラインを自動化

---

詳細ドキュメント

• CLI リファレンス — コマンドの完全なドキュメント
• ウィジェットの属性 — すべての設定オプション
• セルフホスティングガイド — 独自のバックエンドをデプロイ
• API リファレンス — REST API のドキュメント
• ロールバックガイド — 緊急時の手順

---

Spikes を選ぶ理由

手間いらず	script タグ 1 つだけで、登録もビルド手順も不要
どこでも動作	file://、localhost、あらゆるドメインに対応
高精度	正確な CSS セレクターを使った要素単位のフィードバック
エージェント向け	あらゆる場面で JSON を使用し、パイプやクエリ可能な CLI に対応
独自のインフラ	セルフホスト型かホスト型かを選択可能
軽量	ウィジェットは gzip 圧縮時に 14KB
プライベート	トラッキングなし。データは自分のものです

---

料金

	無料	Pro
価格	ずっと $0	お支払いいただける金額
共有数	5	無制限
共有あたりのスパイク数	1,000	無制限
ウィジェット + CLI	フル機能	フル機能
セルフホスティング	はい	はい
パスワード保護	—	はい
Webhook	—	はい
バッジの削除	—	はい

---