TAKT Piece Creator

TAKTピース（ワークフローYAML）とその関連ファセットファイルを作成する。

前提 takt バージョン: v0.30.0

参照資料

taktのコードベースとドキュメントは references/takt/ にある。必要に応じて以下を参照する。

資料 パス 用途

YAMLスキーマ references/takt/builtins/skill/references/yaml-schema.md

ピースYAMLの構造定義

エンジン仕様 references/takt/builtins/skill/references/engine.md

プロンプト構築・ルール評価の詳細

Faceted Prompting references/takt/docs/faceted-prompting.ja.md

5ファセット設計の理論

ビルトインピース references/takt/builtins/ja/pieces/

実例（default.yaml, dual.yaml等）

スタイルガイド references/takt/builtins/ja/STYLE_GUIDE.md

ファセット記述規約

ペルソナガイド references/takt/builtins/ja/PERSONA_STYLE_GUIDE.md

ペルソナ記述規約

ビルトインファセット references/takt/builtins/ja/{personas,policies,instructions,knowledge,output-contracts}/

既存ファセット例

重要: ピース作成前に references/takt/builtins/ja/pieces/default.yaml を読み、プロジェクトのパターンを把握する。

ワークフロー

Step 1: 要件ヒアリング

以下を確認する（不明な点はユーザーに質問）:

• 目的: このピースで何を達成するか

• ムーブメント構成: どんなステップが必要か（plan→implement→review→supervise等）

• レビュー体制: 並列レビューの有無、レビュアーの種類

• ループ制御: 修正ループの有無と閾値

• 出力先: ピースとファセットの配置場所（デフォルト: ~/.takt/pieces/ ）

Step 2: ビルトイン参照

ビルトインピース（references/takt/builtins/ja/pieces/ ）から類似パターンを探す。

ビルトイン 構成 用途

default.yaml

plan→implement→ai_review→reviewers(arch+qa)→supervise 標準開発（バックエンド）

dual.yaml

plan→implement→ai_review→reviewers(arch+frontend+security+qa)→supervise フルスタック（FE+BE）

dual-mini.yaml

plan→implement→supervise フルスタック最小構成

backend.yaml

plan→implement→ai_review→reviewers(arch+qa)→supervise バックエンド特化

frontend.yaml

plan→implement→ai_review→reviewers(frontend+qa)→supervise フロントエンド特化

review.yaml

レビュー専用 コードレビューのみ

review-fix.yaml

review→fix ループ レビュー＋自動修正

research.yaml

調査→レポート リサーチ・分析

注意: v0.28.1 で expert → dual にリネーム、default-mini は廃止。*-cqrs , *-mini , *-review , *-review-fix 等のバリエーションが多数追加されている。全一覧は references/takt/builtins/ja/pieces/ を参照。

ビルトイン再利用の判断

カスタムファセットを作る前に、まずビルトインで代替できないか確認する。ビルトインは takt 本体でテスト済みであり、一貫性と保守性の面で有利。

役割 ビルトイン名 カスタムが必要なケース

計画 planner

プロジェクト固有の計画手法がある場合のみ

実装 coder

特殊な技術スタック向け制約がある場合のみ

レビュー architecture-reviewer , frontend-reviewer , security-reviewer , qa-reviewer

独自のレビュー観点が必要な場合のみ

監督 supervisor

—

修正 (coder流用) 修正固有の制約がある場合のみ

判断基準: 「このファセットはビルトインと何が違うか？」を一文で説明できなければ、ビルトインを使う。

Step 3: ピースYAML作成

以下の構造でYAMLを作成する。

name: piece-name description: ピースの説明 max_movements: 30 initial_movement: plan

セクションマップ（カスタムファセットがある場合のみ）

personas: custom-role: ../personas/custom-role.md policies: custom-policy: ../policies/custom-policy.md instructions: custom-step: ../instructions/custom-step.md knowledge: domain: ../knowledge/domain.md report_formats: custom-report: ../output-contracts/custom-report.md

movements:

• name: plan edit: false persona: planner # ビルトイン参照（bare name） knowledge: architecture instruction: plan provider_options: # v0.30.0: ツール制限はプロバイダ別に指定 claude: allowed_tools: - Read - Glob - Grep - Bash - WebSearch - WebFetch output_contracts: report: - name: 00-plan.md format: plan rules:

  • condition: 要件が明確で実装可能 next: implement
  • condition: 要件が不明確、情報不足 next: ABORT

• name: implement edit: true persona: coder policy: [coding, testing] session: refresh instruction: implement rules:

  • condition: 実装完了 next: review

Parallel Movement 例

• name: reviewers parallel:
  • name: arch-review edit: false persona: architecture-reviewer policy: review instruction: review-arch output_contracts: report: - name: 05-architect-review.md format: architecture-review rules:
    • condition: approved
    • condition: needs_fix
  • name: qa-review edit: false persona: qa-reviewer policy: [review, qa] instruction: review-qa rules:
    • condition: approved
    • condition: needs_fix rules:
  • condition: all("approved") next: supervise
  • condition: any("needs_fix") next: fix

注意: サブステップの rules は結果分類用。next は無視され、親の rules が遷移先を決定する。

設計判断ガイド

判断ポイント 基準

edit: true/false

コード変更するムーブメントのみtrue

session: refresh

implement と fix に設定する。長いコンテキストの蓄積を防ぎ、レポート経由で必要情報を引き継ぐ

pass_previous_response: false

レビュー結果を直接読ませたくない場合

required_permission_mode

edit権限が必要な場合に edit を指定

quality_gates

ムーブメント単位の完了基準（AI指示）。例: ["All tests pass", "No lint errors"]

provider_options

プロバイダ固有設定。allowed_tools は provider_options.claude.allowed_tools に配置する（v0.30.0〜）

CI実行責任の配置 ビルドを伴うCIは edit: true の fix /implement ムーブメントで実行しレポートに記録する。supervise 等の edit: false ムーブメントはレポート証跡の確認のみ行い、CI自身は実行しない

supervise の失敗遷移 修正で解決できる問題なら fix へ遷移させる。plan は根本的な設計変更が必要な場合のみ。supervise → plan の安易な遷移はループの原因になる

edit:false ムーブメントの安全ルール

edit: false のムーブメント（plan, review, supervise等）は読み取り専用サンドボックスで動作する。これはtaktエンジンが強制する制約であり、以下を必ず守る:

• allowed_tools に Bash を含めない — Bash があるとエージェントがビルドコマンド（cargo check , npm test 等）を試みて必ず失敗する。読み取り専用で必要なのは Read , Glob , Grep 等のみ

• インストラクションに「やらないこと」を明記 — 「コンパイル・ビルド・テスト実行は行わない」と明示する

• CI/ビルド結果が必要なら — edit: true の前段ムーブメント（implement/fix）でビルドを実行し、レポートに記録する。edit:false ムーブメントはそのレポートを読んで判断する

❌ 間違い: review に Bash を含めている

• name: review edit: false provider_options: claude: allowed_tools: - Read - Glob - Grep - Bash # ← 読み取り専用で Bash は使えない！

✅ 正解: review は読み取り専用ツールのみ

• name: review edit: false provider_options: claude: allowed_tools: - Read - Glob - Grep - WebSearch

ルール設計

ルール種別 記法 使い分け

テキスト条件 "条件文"

Phase 3タグ判定（推奨）

AI判定 ai("条件")

タグ判定が不適な場合

全一致 all("条件")

parallelの親のみ

いずれか any("条件")

parallelの親のみ

特殊遷移先: COMPLETE （成功終了）、ABORT （失敗終了）

Step 4: ファセットファイル作成

カスタムファセットが必要な場合、以下の規約で作成する。

ディレクトリ構造

~/.takt/ ├── pieces/ │ └── my-piece.yaml ├── personas/ │ └── custom-role.md ├── policies/ │ └── custom-policy.md ├── instructions/ │ └── custom-step.md ├── knowledge/ │ └── domain.md └── output-contracts/ └── custom-report.md

ファセット作成規約

Persona: system promptに配置。identity + 専門性 + 境界。

{ロール名}

{1-2文のロール定義}

役割の境界

やること:

• ...

やらないこと:

• ...（担当エージェント名を明記）

行動姿勢

• ...

Policy: 複数ムーブメントで共有する行動規範。

{ポリシー名}

原則

禁止事項

• ...

Instruction: ムーブメント固有の手順。命令形で記述。{task} , {previous_response} は自動注入されるため不要。

Knowledge: 判断の前提となる参照情報。記述的（「こうなっている」）。

Output Contract: レポートの構造定義。

# {レポートタイトル}

## 結果: APPROVE / REJECT

## サマリー
{1-2文で要約}

## 詳細
| 観点 | 結果 | 備考 |
|------|------|------|

詳細なスタイル規約は references/takt/builtins/ja/STYLE_GUIDE.md を参照。

Step 5: Loop Monitor（任意）

修正ループが想定される場合に設定する。

loop_monitors:

AI修正ループ監視

• cycle: [ai_review, ai_fix] threshold: 5 judge: persona: supervisor instruction_template: loop-monitor-ai-fix # v0.30.0: ビルトインテンプレート参照 rules: - condition: 健全（進捗あり） next: ai_review - condition: 非生産的（改善なし） next: ABORT

レビュアー修正ループ監視

• cycle: [reviewers, fix] threshold: 3 judge: persona: supervisor instruction_template: loop-monitor-reviewers-fix # v0.30.0: 新規ビルトインテンプレート rules: - condition: 健全（指摘数が減少、修正が反映されている） next: reviewers - condition: 非生産的（同じ指摘が繰り返される） next: ABORT

注意（v0.30.0）: instruction_template にはビルトインファセット名を指定することを推奨する。これにより一貫性と保守性が向上する。インラインテキストも引き続き使用可能だが、ビルトインに同等のテンプレートがある場合は参照名を優先する。カスタムテンプレートが必要な場合は、instructions セクションマップにカスタムファセットを登録し、そのキー名を指定する。

Loop Monitor 安全ルール

• loop_monitors[*].cycle の「健全（進捗あり）」遷移先は、必ず cycle の先頭ノードにする

• 例: cycle: [reviewers, fix] の場合、健全時 next: reviewers

• judge.instruction_template で参照する {report:...} は、対象 cycle 内 movement が生成するレポートのみ許可

• cycle 外 movement（例: verify ）専用レポートは参照しない

• 上記2点を満たさない場合は、ループ継続判定が壊れるため修正してから保存する

Step 6: 検証

作成したファイルの整合性を確認する:

• セクションマップのキーとムーブメント内の参照が一致

• セクションマップのパスが実際のファイル位置と一致（ピースYAMLからの相対パス）

• ビルトイン参照（bare name）とカスタム参照（セクションマップキー）が混在していないか

• initial_movement が movements 配列内に存在

• 全ムーブメントの rules.next が有効な遷移先（他のムーブメント名 or COMPLETE/ABORT）

• parallel ムーブメントの親ルールが all() / any() を使用

• parallel サブステップのルールに next がない（親が制御）

• loop monitor の健全時 next が cycle 先頭ノードと一致

• loop monitor の instruction_template が cycle 外レポートを参照していない

• edit: false ムーブメントの allowed_tools に Bash が含まれていない

• implement / fix ムーブメントに session: refresh が設定されている

• ビルトインで代替可能なカスタムファセットが不必要に作成されていない

バリデーション

作成・編集したファイルは validate-takt-files.sh で機械的に検証できる:

bash .agents/skills/takt-piece/scripts/validate-takt-files.sh

検証項目:

• ピース YAML: 必須フィールド（name /initial_movement /movements ）、initial_movement の movement 参照、ファセットファイル参照の実在

• loop_monitors: 健全時 next が cycle 先頭ノード、instruction_template のレポート参照が cycle 内 movement 生成物に限定されていること

• ファセット .md: 空チェック、persona/policy/knowledge は # 見出し 必須、instruction/output-contract は内容存在

オプション --pieces / --facets で対象を絞り込み可能。