# Takt Builder

> TAKTのワークフローYAMLとファセット（ペルソナ・ポリシー・ナレッジ・インストラクション・出力契約）を作成・更新する。スタイルガイドに準拠したファセット分離とYAMLスキーマに準拠したワークフロー設計を行う。トリガー：「ワークフローを作りたい」「ピースを作りたい」「ファセットを追加」「TAKTのペルソナを作成」「ポリシーを更新」「ナレッジを追加」「出力契約を作成」「ワークフローYAMLを設計」「ピースYAMLを設計」といったTAKTファセット・ワークフロー関連リクエストで起動。

- Skill: `nrslib/takt-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nrslib/takt-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nrslib/takt-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nrslib (https://skillmd.com/u/nrslib)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nrslib/takt-builder

---


# TAKT Builder

TAKT のワークフローYAMLとファセットをスタイルガイドに準拠して作成・更新する。

使い方:
- `/takt-builder 調査用の deep-research ワークフローを作りたい` — 新規ワークフロー作成
- `/takt-builder default ワークフローにセキュリティレビューを追加` — 既存ワークフロー更新
- `/takt-builder research 用の policy を作りたい` — ファセット作成

## 重要

**手順を飛ばさない。** 事前準備（リファレンスの読み込み）から結果報告まで、ステップバイステップで実行する。「既に知っている」「前に読んだ」という判断でステップを省略しない。

**ファセットはプロジェクト非依存で書く。** `npm run build` や `pytest` のようなプロジェクト固有のコマンド、特定のフレームワーク名、具体的なファイルパスをファセットに直接書かない。「ビルド（型チェック）を実行」「テストを実行」のように抽象的に記述する。具体的なコード例を含めるのは、ナレッジやポリシーで良い例/悪い例のパターンを示す場合に限る。

**このスキルには具体的なルールや例を書かない。**

すべてのスタイルルールは同梱の `references/` 配下のスタイルガイドに記載されており、それらが Single Source of Truth である。

**同期について:** このスキルのスタイルガイド・テンプレート・YAMLスキーマは TAKT 本体の `builtins/` から移植したもの。TAKT 本体を更新した場合は、対応するファイルをこのスキルにも反映する。

## 目次

1. [引数](#引数)
2. [事前準備: リファレンスの読み込み](#事前準備-リファレンスの読み込み)
3. [手順 1. 意図の分析](#1-意図の分析)
4. [手順 2A. ワークフロー設計 / 2B. 分離判断](#2a-ワークフロー設計ワークフロー作成時)
5. [手順 3. ファセット作成](#3-ファセット作成)
6. [手順 4. ワークフローYAML作成/更新](#4-ワークフローyaml作成更新)
7. [手順 5. セルフチェック](#5-セルフチェック)
8. [手順 6. ビルドとテスト](#6-ビルドとテストの確認)
9. [手順 7. 結果の報告](#7-結果の報告)

## 引数

$ARGUMENTS にユーザーの意図が入る。省略時は AskUserQuestion で確認する。

意図の種類:
- 新しいワークフローの作成（例: `deep-research ワークフローを作りたい`）
- 既存ワークフローの更新（例: `default ワークフローにセキュリティレビューを追加`）
- 既存ワークフローへのファセット追加（例: `research ワークフローに knowledge を追加`）
- 既存ファセットの更新（例: `research-planner ペルソナを更新`）
- 新しいファセットの作成（例: `research 用の policy を作りたい`）

---

## 事前準備: リファレンスの読み込み

このスキルの `references/` と `templates/` にリファレンスが同梱されている。
スキルのベースディレクトリ（スキル読み込み時に表示される `Base directory`）をルートとして、**Read tool で読み込む**。

### 必須（毎回）

| ファイル | 目的 |
|---------|------|
| `references/STYLE_GUIDE.md` | 全体アーキテクチャと分離判断フロー |

### ワークフロー作成時は追加で読み込む

| ファイル | 目的 |
|---------|------|
| `references/yaml-schema.md` | ワークフローYAMLの構造定義とフィールド説明 |
| 同種の既存ワークフローYAML | 参考パターンの把握 |

### ファセット作成時は対象に応じて読み込む

| 対象ファセット | スタイルガイド | テンプレート |
|-------------|--------------|------------|
| ペルソナ | `references/PERSONA_STYLE_GUIDE.md` | `templates/personas/{simple,expert,character}.md` |
| ポリシー | `references/POLICY_STYLE_GUIDE.md` | `templates/policies/policy.md` |
| ナレッジ | `references/KNOWLEDGE_STYLE_GUIDE.md` | `templates/knowledge/knowledge.md` |
| インストラクション | `references/INSTRUCTION_STYLE_GUIDE.md` | `templates/instructions/{plan,implement,review,...}.md` |
| 出力契約 | `references/OUTPUT_CONTRACT_STYLE_GUIDE.md` | `templates/output-contracts/{plan,review,...}.md` |

### ファセット・ワークフローの出力先

作成したファセットやワークフローYAMLの配置先は、cwd が TAKT プロジェクトかどうかで決まる。

| 配置先 | 条件 | 用途 |
|--------|------|------|
| `builtins/{lang}/` | cwd に `builtins/ja/STYLE_GUIDE.md` が存在する | TAKT プロジェクト本体の builtin 更新 |
| `.takt/` | 上記以外（ユーザー選択） | プロジェクト固有のファセット・ワークフロー |
| `~/.takt/` | 上記以外（ユーザー選択） | eject 済み環境、個人のカスタムファセット |

**出力先の決定手順:**
1. cwd で `builtins/ja/STYLE_GUIDE.md` を Glob → 見つかれば TAKT プロジェクト内（`builtins/{lang}/` に出力）
2. 見つからなければ AskUserQuestion で「プロジェクトローカル（`.takt/`）に置くか、ユーザーグローバル（`~/.takt/`）に置くか」を確認

---

## 手順

### 1. 意図の分析

$ARGUMENTS を分析し、以下を判断する。

| 判断項目 | 選択肢 |
|---------|--------|
| 作業スコープ | **ワークフロー作成** / ワークフロー更新 / ファセット作成・更新 |
| 必要なファセット | ペルソナ / ポリシー / ナレッジ / インストラクション / 出力契約 |
| 言語 | ja（マスター） + en（翻訳） |

**ワークフロー作成の場合** → ステップ 2A（ワークフロー設計）へ
**ファセット作成・更新の場合** → ステップ 2B（分離判断）へ

### 2A. ワークフロー設計（ワークフロー作成時）

`references/yaml-schema.md` を読み込み、ワークフローの構造を設計する。

**設計の手順:**

1. **フロー設計**: ステップの遷移フロー（状態遷移図）を決める
   - どのステップが必要か（plan → implement → review → ...）
   - 各ステップ間の遷移条件（rules）
   - ループの有無（review → fix → review のサイクル等）
   - max_steps の見積もり

2. **ファセット割り当て**: 各ステップに必要なファセットを決める
   - persona: どのエージェントが担当するか
   - policy: どの共有ルールを適用するか
   - knowledge: どのドメイン知識が必要か
   - instruction: どんな手順で実行するか
   - output_contracts: どんなレポートを出力するか

3. **既存ファセットの確認**: 再利用可能な既存ファセットを探す
   - 出力先ディレクトリの既存ファセットを Glob で確認
   - 既存のものは再利用、不足分のみ新規作成

4. **参考ワークフローの確認**: 同種の既存ワークフローYAMLがあれば Read で読み込み参考にする

**設計をユーザーに提示して確認を取ってから**、ステップ 3 以降でファセット作成 → ワークフローYAML作成に進む。

### 2B. 分離判断（ファセット作成・更新時）

内容をファセットに分離する。STYLE_GUIDE.md の分離判断フローに従う。

```
この内容は…
├── 特定のエージェントだけが必要 → ペルソナ
├── 「〜すべき」行動規範（複数エージェント共有） → ポリシー
├── 「〜はこう動く」ドメイン知識 → ナレッジ
├── ステップ固有の手順 → インストラクション
└── エージェント出力の構造定義 → 出力契約
```

**判断に迷ったら AskUserQuestion で確認する。**

判断ポイント:

| 迷いやすいケース | 判断基準 |
|---------------|---------|
| ペルソナ vs ナレッジ | そのエージェントだけが使う → ペルソナ、複数エージェントが参照 → ナレッジ |
| ポリシー vs ナレッジ | 「〜すべき/禁止」ルール → ポリシー、「〜はこう動く」知識 → ナレッジ |
| ペルソナの行動姿勢 vs ポリシー | 1行の指針 → ペルソナ行動姿勢、詳細ルール(テーブル/コード例) → ポリシー |
| インストラクション vs ペルソナ | 「今このステップでやること」→ インストラクション、「常に持つ知識」→ ペルソナ |

### 3. ファセット作成

**まず出力先を確定する。** 「事前準備」セクションの「ファセット・ワークフローの出力先」に従い、出力先ディレクトリを決定してから作成に入る。

対象ファセットごとにスタイルガイドとテンプレートを読み込み、準拠したファイルを作成する。

**作成順序: 日本語（マスター）→ 英語（翻訳）**

各ファセットの作成ルール:

**ペルソナ:**
- テンプレートを選択（simple / expert / character）
- ロール定義 1-2文、「あなたは〜です。」
- 役割の境界（やること/やらないこと + 担当エージェント名）
- 行動姿勢（3-8項目、1行の指針）
- ドメイン知識（エージェント固有のみ）
- 見出し最大 `###`、文体は常体

**ポリシー:**
- 目的説明 1文
- 原則テーブル（5-10行）
- ルールカテゴリ（`##` で直接分ける）
- 「基準 → 判定」テーブル
- 見出し最大 `###`、文体は常体

**ナレッジ:**
- **プロジェクト固有の手順をそのまま書かない。** 汎用的なパターン/原則として記述する（KNOWLEDGE_STYLE_GUIDE.md「抽象度の原則」参照）
- トピック概要（各 `##` の冒頭1-2文）
- 評価基準テーブル
- コード例（良い例/悪い例ペア）
- 見出し最大 `###`、文体は常体

**インストラクション:**
- 目的宣言（1-2行、命令形「〜してください。」）
- やること（番号付きリスト or 箇条書き）
- `{task}`, `{previous_response}`, `{user_inputs}` は書かない（自動注入）
- 文体は丁寧語

**出力契約:**
- ```markdown コードブロックで構造定義
- プレースホルダー `{簡潔な説明}` 形式

### 4. ワークフローYAML作成/更新

`references/yaml-schema.md` に準拠してワークフローYAMLを作成する。

**セクションマップは基本不要。** TAKT は 3層解決（project `.takt/` → user `~/.takt/` → builtin `builtins/{lang}/`）でファセットを自動検索する。ステップ内でファセット名（キー名）を指定すれば、標準パス（`facets/personas/{name}.md` 等）に配置されたファセットは自動解決される。

セクションマップが必要なのは次の場合のみ:
- ファセット名とファイル名が異なる場合
- 標準パス外にファセットを配置する場合
- repertoire パッケージのファセットを参照する場合

```yaml
# セクションマップなし（推奨）— ファセット名で自動解決
name: workflow-name
max_steps: 10
initial_step: plan

steps:
  - name: plan
    persona: planner
    policy: coding
    instruction: plan
    edit: false
    output_contracts:
      report:
        - name: 01-plan.md
          format: plan
    rules:
      - condition: 要件が明確で実装可能
        next: implement
      - condition: 要件が不明確
        next: ABORT
```

```yaml
# セクションマップあり — 名前とファイルが異なる場合のみ
personas:
  arch-reviewer: ../facets/personas/architecture-reviewer.md
```

**instruction はファイル参照を使う。** `instruction` フィールドはセクションマップ → パス → 3層ファセット検索の順で解決される。インストラクションファセットとして作成し、キー名で参照する。

### 5. セルフチェック

各ファセットのスタイルガイドのチェックリストで検証する。

**共通チェック:**
- [ ] `####` 以下のネストがないか
- [ ] ワークフロー固有の概念（ステップ名、レポートファイル名）がペルソナ/ポリシー/ナレッジに混入していないか
- [ ] ツール固有のパス（`.takt/runs/` 等）がペルソナ/ポリシー/ナレッジに混入していないか

**ペルソナチェック:**
- [ ] ロール定義が1-2文か
- [ ] 「やらないこと」に担当エージェント名があるか
- [ ] ポリシーの詳細ルール（コード例・テーブル）を転記していないか
- [ ] ファイルサイズ（ドメイン知識なし: 30-100行、あり: 50-550行）

**ポリシーチェック:**
- [ ] 目的説明が1文か
- [ ] 原則テーブルがあるか
- [ ] 複数エージェントに適用可能な内容か
- [ ] ファイルサイズ（60-300行）

**ナレッジチェック:**
- [ ] パターン/原則として抽象的に記述されているか
- [ ] 各トピックに評価基準テーブルがあるか
- [ ] 横断的な行動規範が混入していないか（→ ポリシー）
- [ ] ファイルサイズ（横断: 100-300行、設計: 200-600行、技術: 500-800行）

**インストラクションチェック:**
- [ ] 冒頭1-2行で目的が命令形で書かれているか
- [ ] 自動注入される変数を手動で書いていないか
- [ ] ファイルサイズ（レビュー: 5-20行、計画: 10-30行、実装: 30-60行）

**ワークフローYAMLチェック:**
- [ ] `name`, `max_steps`, `initial_step`, `steps` が定義されているか
- [ ] セクションマップを使っている場合、パスがワークフローYAMLからの正しい相対パスか（標準パスなら不要）
- [ ] 各ステップに `edit` と `rules` が定義されているか
- [ ] `COMPLETE` への遷移パスが存在するか
- [ ] parallel ステップの親 rules に `all()` / `any()` が使われているか

**不合格の場合:** 該当ファセットのステップ 3 に戻って修正し、再度セルフチェックする。ワークフローYAMLの問題はステップ 4 に戻る。

### 6. ビルドとテストの確認

TAKT プロジェクト内で作業している場合は、ファイル作成後に以下を実行する。

```bash
npm run build && npm run test
```

TAKT プロジェクト外の場合はスキップする。

### 7. 結果の報告

作成・更新したファイルの一覧と構成のサマリーを表示する。

```
作成物:
| 種別 | ファイル（ja） | ファイル（en） |
|------|--------------|--------------|
| Workflow | workflows/xxx.yaml | workflows/xxx.yaml |
| Persona | facets/personas/xxx.md | facets/personas/xxx.md |
| Policy | facets/policies/xxx.md | facets/policies/xxx.md |
| ... | ... | ... |

ワークフロー:
plan → implement → reviewers → [fix ↔ reviewers] → supervise → COMPLETE
```