---
id: pieces
title: Piece を選ぶ・作る
category: basic
order: 50
keywords: [piece, タスクタイプ, 自動分類, piece-builder, movement]
---

# Piece を選ぶ・作る

Piece は「タスクの種類ごとの実行手順」を定義したものです。エージェントは選ばれた Piece に従って動くため、依頼内容に合った Piece が使われることが品質の鍵になります。

## Piece とは

1 つの Piece は **movement（フェーズ）の並び** で構成されます。各 movement には「使ってよいツール（`allowed_tools`）」「ファイル編集の可否（`edit`）」「次の movement への遷移条件（`rules`）」が定義されています。`allowed_tools` に載っていないツールは、その movement では LLM に一切提示されません。

シンプルな Piece は単一 movement（例: `chat`）、調査系は「分解 → 集約 → 検証」のように複数 movement を持ちます。

## Piece はどう選ばれるか

タスク作成時に「タスクタイプ」を **auto** のままにすると、LLM ベースの分類器が依頼文と全 Piece の説明を見て、最適な Piece を 1 つ自動で選びます。手動で特定の Piece を指定することもできます。

分類器の挙動（`piece-classifier`）:

- **デフォルトは `chat`** — 特化型 Piece に明確に該当しない依頼はすべて `chat` で処理されます
- 特化型 Piece が選ばれるのは、依頼が「スライド作成 → slide」「データ加工 → data-process」「構造化された調査レポート → research」「ブレスト → brainstorming」のように **強く** 該当する場合のみ
- 迷ったときも `chat` が選ばれます
- 各 Piece の `triggers.keywords` は分類の **ヒント** として渡されます（キーワード一致だけで確定はしません）

意図しない Piece が選ばれるときは、依頼文を書き換えて狙いを明確にする（例:「ブレストして」と書く）か、手動でタスクタイプを指定してください。タスク作成の詳細は [タスクを作る](02-tasks.md) を参照。

## ユーザー向け Piece カタログ

| Piece | 何をするか |
|---|---|
| `chat` | 汎用デフォルト。質問・調査・コード生成・文書作成・データ処理など、特化型に該当しない依頼を 1 つの movement で処理する |
| `general` | 汎用タスク実行。ファイル編集・コード生成・翻訳・文書作成など、主目的がファイル生成・編集のタスク。最後のフォールバックとしても機能する |
| `research` | Web 検索やファイル読み込みによる情報収集と、収集情報の分析・構造化レポート作成。比較分析・トレンド調査・文献サーベイ向け |
| `data-process` | CSV / JSON / TSV / SQL など構造化データの加工・集計・変換・フィルタリング |
| `office-process` | Excel / Word / PowerPoint / PDF の読み取り・編集・変換・文書生成。売上集計・議事録作成・PDF 読み取りなど |
| `slide` | pptxgenjs を使い、PowerPoint で再編集可能な .pptx をゼロから生成する。プレゼン・LT・提案資料向け |
| `brainstorming` | 複数の視点から並列にアイデア・選択肢を検討し、推奨方針を導く |
| `sns-research` | X (Twitter) / Reddit / Hacker News などの SNS から意見・評判・議論を収集してレポート化 |
| `ssh-ops` | SSH 経由でリモートホストに単発オペレーションを実行（health check / config push / log fetch） |
| `ssh-console` | 人間と AI が 1 つの PTY セッションを共有する対話的 SSH コンソール。長時間作業や TUI（vim / top / tmux / tail 等）向け |
| `piece-builder` | Piece の設計・作成・編集を行う専用エージェント。「Piece を作って」「ワークフローを自動化したい」に対応 |

`ssh-ops` / `ssh-console` は admin が `config.yaml` で SSH を有効化し、接続登録・grant が済んでいる場合のみ使えます。詳細は [SSH 連携](14-ssh.md) を参照。

> このほか組織が独自に追加した Piece もここに加わります。利用可能なツールの一覧は [ツール一覧](16-tools.md) を参照。

## Default Pieces と Custom Pieces

Pieces ページでは「**Default Pieces**」と「**Custom Pieces**」の 2 つのセクションが表示されます。

**Default Pieces（組み込み）**

- システムに同梱され、git で管理されている Piece です
- **削除は非 admin ユーザーには禁止**されています（削除は admin のみ）
- **編集は admin のみ** 可能です（非 admin ユーザーは読み取り専用）
- 非 admin ユーザーは `⎘` ボタンで **「Custom に複製」** でき、別名の Custom Piece として自分用にカスタマイズできます

**Custom Pieces（ユーザー作成）**

- ユーザーが作成した Piece で、自分のユーザーフォルダ配下に保存されます
- 自分で作った Custom Piece は編集・削除できます
- Custom Piece は **Default Piece と同名にできません**（別名を付けてください）
- タスク実行時、Custom Piece はそのオーナーのユーザーフォルダから読み込まれ、正しく実行されます

## カスタム Piece を作る

### 方法 1: piece-builder に依頼する

タスクを作成し、「○○用の Piece を作って」と書きます。`piece-builder` が選ばれ、要件をヒアリングしながら movement 構成・ツール選定・遷移ルールを設計して Piece を保存します。既存 Piece の改良で済む場合はそれを優先します。

### 方法 2: Pieces ページで手動作成する

TopBar → Pieces → Custom Pieces セクションの `+` から新規作成できます。YAML を直接編集して保存できます。**Default Piece と同名の名前は使えません**（別名を付けてください）。

### 方法 3: Default Piece を複製してカスタマイズする

Default Piece の行にある `⎘` ボタンをクリックすると「複製名」の入力ダイアログが開きます。別名を入力して複製すると、Custom Pieces セクションに追加されます。元の Default Piece はそのまま残ります。複製後の Custom Piece は自分で自由に編集できます。

## Piece を編集するときの勘所

- `description` は分類器が読みます。「○○をする。選ぶべき場合: … / 選ぶべきでない場合: …」の形式が効きます
- `instruction`（指示書）は長く書いて構いません。手順・避けるべきこと・終了方法を明示するとエージェントの動きが安定します
- movement の開始時に、その movement の `allowed_tools` と 1 行サマリが自動で system prompt に注入されます。指示書にツール一覧を重複して書く必要はありません
- 必要なツールは `allowed_tools` に列挙します。MCP ツールをまとめて許可するなら `mcp__*` を追加します
- LLM が `allowed_tools` にないツールを呼ぶとエラーで弾かれます。その場合は Piece を編集してツールを追加してください（[困ったときは](08-troubleshooting.md) 参照）
