TAKT Piece Builder

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

前提 takt バージョン: v0.31.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/facets/{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→write_tests→implement→ai_review→reviewers(arch+qa)→fix→supervise 標準開発

dual.yaml

plan→write_tests→team_leader_implement→ai_review→reviewers(2段階)→fix→supervise フロントエンド＋バックエンド

backend.yaml

plan→write_tests→implement→ai_review→reviewers→fix→supervise バックエンド特化

frontend.yaml

plan→write_tests→implement→ai_review→reviewers→fix→supervise フロントエンド特化

backend-mini.yaml / dual-mini.yaml / frontend-mini.yaml

plan→implement→supervise 最小構成

review.yaml / review-fix.yaml

レビュー→修正ループ コードレビュー

takt-default.yaml

plan→write_tests→team_leader_implement→ai_review→reviewers→fix→supervise TAKT開発用

再利用判断: ビルトインのファセットで足りる場合はカスタムファセットを作らない。

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 provider_options: # v0.30.0〜: allowed_tools はここに配置 claude: allowed_tools: - Read - Glob - Grep - Bash - WebSearch - WebFetch instruction: plan 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

実装系ムーブメントで新規セッション開始

pass_previous_response: false

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

required_permission_mode

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

provider_options.claude.allowed_tools

ムーブメント単位でClaudeの使用ツールを制限（v0.30.0で allowed_tools から移動）

ルール設計

ルール種別 記法 使い分け

テキスト条件 "条件文"

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:

• cycle: [ai_review, ai_fix] threshold: 3 judge: persona: supervisor instruction: loop-monitor-ai-fix # ビルトインファセット参照 rules: - condition: 健全（進捗あり） next: ai_review - condition: 非生産的（改善なし） next: reviewers
• cycle: [reviewers, fix] threshold: 3 judge: persona: supervisor instruction: loop-monitor-reviewers-fix # ビルトインファセット参照 rules: - condition: 健全（指摘数が減少、修正が反映されている） next: reviewers - condition: 非生産的（同じ指摘が繰り返される） next: supervise

Step 6: 検証

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

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

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

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

• initial_movement が movements 配列内に存在

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

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

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

バリデーション

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

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

検証項目:

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

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

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