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. 意図の分析
4. 手順 2A. ワークフロー設計 / 2B. 分離判断
5. 手順 3. ファセット作成
6. 手順 4. ワークフローYAML作成/更新
7. 手順 5. セルフチェック
8. 手順 6. ビルドとテスト
9. 手順 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} は書かない（自動注入）
• 文体は丁寧語

出力契約:

• プレースホルダー {簡潔な説明} 形式

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

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

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

セクションマップが必要なのは次の場合のみ:

• ファセット名とファイル名が異なる場合
• 標準パス外にファセットを配置する場合
• repertoire パッケージのファセットを参照する場合

# セクションマップなし（推奨）— ファセット名で自動解決
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

# セクションマップあり — 名前とファイルが異なる場合のみ
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 プロジェクト内で作業している場合は、ファイル作成後に以下を実行する。

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