@katatan/agents

@katatan/agents

KATATAN の AI エージェントセットです。
npx @katatan/agents init の 1 コマンドで、AI コーディングエージェントが E2E テストを自動で計画・実装・実行・修復するワークフローをセットアップできます。

概要

KATATAN AI エージェントとは

KATATAN AI エージェントは、Playwright を使った E2E テストを AI に任せるためのエージェントセットです。
あなたが「ログイン機能のテストを作って」と指示するだけで、エージェントがブラウザを操作しながらテストコードを生成・実行・修復まで行います。

内部では 5 つの専門エージェント が連携して動作します:

エージェント	役割
katatan-supervisor	ユーザーと直接対話する入口。指示を解釈し他エージェントを呼び出す
katatan-e2e-planner	ブラウザを探索してUIを調査。KATATAN の Dictionary と TestCase を登録する
katatan-e2e-generator	TestCase をもとに Playwright の TypeScript テストコードを生成する
katatan-e2e-runner	テストを実行し、結果を KATATAN に記録する
katatan-e2e-healer	失敗したテストの原因を分析し、コードを修復して再実行する

MCP（Model Context Protocol）とは

MCP は AI エージェントが外部ツールやサービスに接続するための標準プロトコルです。
このパッケージでは以下の 2 つの MCP サーバーを設定します:

サーバー	役割
katatan-test	KATATAN の TestSpec・TestCase・Dictionary・TestReport を操作する
playwright	ブラウザ操作（ページ遷移・スナップショット取得・クリック など）を行う

対応 AI クライアント

クライアント	設定ファイル
Claude Code	.claude/agents/ + .mcp.json
VS Code（GitHub Copilot）	.vscode/mcp.json
Cursor	.cursor/mcp.json
Kiro（Amazon）	.kiro/settings/mcp.json
Google Antigravity	~/.gemini/antigravity/mcp_config.json（グローバル）+ .agents/skills/

セットアップ手順

1. セットアップコマンドを実行する

テストしたいプロジェクトのルートディレクトリで以下を実行します:

npx @katatan/agents init

Node.js 18 以上が必要です。

2. AI クライアントを選択する

Step 1: AIクライアントを選択してください
  1. Claude Code           .claude/agents/ + .mcp.json
  2. VS Code (GitHub Copilot)  .vscode/mcp.json
  3. Cursor                .cursor/mcp.json
  4. Kiro (Amazon)         .kiro/settings/mcp.json
  5. Google Antigravity    ~/.gemini/antigravity/mcp_config.json + .agents/skills/

クライアントを選択 (複数可・Enterですべて選択) > 1,2

カンマ区切りで複数選択できます。Enter のみでは全クライアントが選択されます。

3. KATATAN アクセストークンを入力する

Step 2: KATATAN アクセストークンを入力してください
  KATATANの設定ページ (https://app.katatan.com/) から取得できます
  トークン > kat_xxxxxxxxxxxxxxxx

アクセストークンは KATATAN 設定ページ から取得できます。

4. 完了

選択したクライアントの設定ファイルが自動生成されます。
Playwright がまだインストールされていない場合は、インストールするか確認が表示されます。

生成されるファイル

Claude Code

.claude/
└── agents/
    ├── katatan-supervisor.md
    ├── katatan-e2e-planner.md
    ├── katatan-e2e-generator.md
    ├── katatan-e2e-runner.md
    └── katatan-e2e-healer.md
.mcp.json

VS Code（GitHub Copilot）

.vscode/
└── mcp.json

Cursor

.cursor/
└── mcp.json

Kiro（Amazon）

.kiro/
└── settings/
    └── mcp.json

Google Antigravity

~/.gemini/antigravity/mcp_config.json  ← グローバル設定（既存設定とマージ）

.agents/
└── skills/
    ├── katatan-supervisor/SKILL.md
    ├── katatan-e2e-planner/SKILL.md
    ├── katatan-e2e-generator/SKILL.md
    ├── katatan-e2e-runner/SKILL.md
    └── katatan-e2e-healer/SKILL.md

使い方

Claude Code

• Claude Code でプロジェクトを開く
• @katatan-supervisor に話しかける

@katatan-supervisor ログイン画面のE2Eテストを作って

VS Code（GitHub Copilot）

• コマンドパレットで「MCP: List Servers」を開き、katatan-test と playwright を有効化する
• Copilot Chat（エージェントモード）で指示する

Cursor

• Cursor を再起動して設定を反映する
• Agent モードで指示する

Kiro（Amazon）

• Kiro を再起動して設定を反映する
• Agent モードで指示する

Google Antigravity

• Antigravity を再起動して設定を反映する
• katatan-supervisor スキルに話しかける

動作フロー

ユーザー
  │ 「ログイン機能のE2Eテストを作って」
  ▼
katatan-supervisor（指示を解釈・サブエージェントを呼び出す）
  │
  ├─▶ katatan-e2e-planner
  │     ブラウザを探索 → Dictionary 登録 → TestCase 登録
  │
  ├─▶ katatan-e2e-generator
  │     TestCase → Playwright TypeScript コード生成 → TestReport 作成
  │
  ├─▶ katatan-e2e-runner
  │     テスト実行 → 結果を KATATAN に記録
  │
  └─▶ katatan-e2e-healer（失敗時のみ）
        失敗原因の分析 → コード修復 → 再実行

必要条件

• Node.js 18 以上
• KATATAN アカウントとアクセストークン
• 対応 AI クライアントのいずれか