agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
takt/docs/README.ja.md
nrslib a1bfc2ce34 docs: README の YAML 例から不要な personas セクションマップを削除 
ビルトインのファセット解決で自動的に見つかるため明示的なマッピングは不要
2026-02-23 22:06:35 +09:00

10 KiB
Raw Blame History

TAKT

English | 💬 Discord コミュニティ

TAKT Agent Koordination Topology — AI コーディングエージェントにレビューループ・プロンプト管理・ガードレールを与え、「とりあえず動くコード」ではなく「品質の高いコード」を出させるツールです。

AI と会話してやりたいことを決め、タスクとして積み、takt run で実行します。計画・実装・レビュー・修正のループは YAML の piece ファイルで定義されており、エージェント任せにはしません。Claude Code、Codex、OpenCode に対応しています。

TAKT は TAKT 自身で開発しています（ドッグフーディング）。

なぜ TAKT か

すぐ始められる — アーキテクチャ、セキュリティ、AI アンチパターンなどのレビュー観点をビルトインで備えています。インストールしたその日から、一定以上の品質のコードを出せます。

実用的 — 日々の開発で使うためのツールです。AI と相談して要件を固め、タスクを積んで実行します。worktree の自動隔離、PR 作成、失敗時のリトライまで面倒を見てくれます。

再現可能 — 実行パスを YAML で宣言するから、結果のブレを抑えられます。piece は共有できるので、チームの誰かが作ったワークフローを他のメンバーがそのまま使って同じ品質プロセスを回せます。すべてのステップは NDJSON でログに残るため、タスクから PR まで追跡もできます。

マルチエージェント — 異なるペルソナ・権限・レビュー基準を持つ複数のエージェントを協調させます。並列レビュー、失敗時の差し戻し、ルールによる結果の集約に対応しています。プロンプトは persona・policy・knowledge・instruction の独立したファセットとして管理し、ワークフロー間で自由に組み合わせられます（Faceted Prompting）。

必要なもの

次のいずれかが必要です。

  • プロバイダー CLI: Claude Code、Codex、OpenCode のいずれか
  • API Key 直接利用: Anthropic / OpenAI / OpenCode の API Key があれば CLI は不要です

任意:

  • GitHub CLI (gh) — takt #N で GitHub Issue を使う場合に必要です

クイックスタート

インストール

npm install -g takt

AI と相談して実行する

$ takt

Select piece:
  > 🎼 default (current)
    📁 🚀 クイックスタート/
    📁 🎨 フロントエンド/
    📁 ⚙️ バックエンド/

対話モード - タスク内容を入力してください。
コマンド: /go（実行）, /cancel（終了）

> ユーザー認証を JWT で追加して

[AI が要件を整理してくれます]

> /go

提案されたタスク指示:
  ...

どうしますか？
  > 実行する
    GitHub Issueを建てる
    タスクにつむ
    会話を続ける

TAKT が隔離された worktree を作り、piece を実行（計画 → 実装 → レビュー → 修正ループ）します。終わったら PR を作成するか聞いてきます。

タスクを積んでまとめて実行する

# 会話でタスクを積みます
takt
> auth モジュールをリファクタリングして
> /go
# → どうしますか？ → 「タスクにつむ」を選択

# GitHub Issue から積むこともできます
takt add #6
takt add #12

# まとめて実行します
takt run

結果を管理する

# 完了・失敗したタスクブランチの一覧を確認し、マージ、リトライ、削除ができます
takt list

仕組み

TAKT は音楽のメタファーを使っています。piece がワークフロー、movement が各ステップにあたります。

piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。

name: plan-implement-review
initial_movement: plan
max_movements: 10

movements:
  - name: plan
    persona: planner
    edit: false
    rules:
      - condition: Planning complete
        next: implement

  - name: implement
    persona: coder
    edit: true
    required_permission_mode: edit
    rules:
      - condition: Implementation complete
        next: review

  - name: review
    persona: reviewer
    edit: false
    rules:
      - condition: Approved
        next: COMPLETE
      - condition: Needs fix
        next: implement    # <- 修正ループ

ルールが次の movement を決めます。COMPLETE で成功終了、ABORT で失敗終了です。並列 movement やルール条件の詳細は Piece Guide を参照してください。

おすすめ piece

Piece 用途
default-mini ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。
default-test-first-mini テストファースト開発向けです。テストを先に書き、それを通す実装を行います。
frontend-mini フロントエンド向けの mini 構成です。
backend-mini バックエンド向けの mini 構成です。
expert-mini エキスパート向けの mini 構成です。
default 本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。
全ピース・ペルソナの一覧は Builtin Catalog を参照してください。

主要コマンド

コマンド 説明
takt AI と相談して、タスクを実行または積みます
takt run 積まれたタスクをまとめて実行します
takt list タスクブランチを管理します（マージ、リトライ、追加指示、削除）
takt #N GitHub Issue をタスクとして実行します
takt switch 使う piece を切り替えます
takt eject ビルトインの piece/persona をコピーしてカスタマイズできます
takt repertoire add GitHub から repertoire パッケージをインストールします

全コマンド・オプションは CLI Reference を参照してください。

設定

最小限の ~/.takt/config.yaml は次の通りです。

provider: claude    # claude, codex, or opencode
model: sonnet       # プロバイダーにそのまま渡されます
language: ja        # en or ja

API Key を直接使う場合は、CLI のインストールは不要です。

export TAKT_ANTHROPIC_API_KEY=sk-ant-...

全設定項目・プロバイダープロファイル・モデル解決の詳細は Configuration Guide を参照してください。

カスタマイズ

カスタム piece

takt eject default    # ビルトインを ~/.takt/pieces/ にコピーして編集できます

カスタム persona

~/.takt/personas/ に Markdown ファイルを置きます。

# ~/.takt/personas/my-reviewer.md
You are a code reviewer specialized in security.

piece から persona: my-reviewer で参照できます。

詳細は Piece Guide と Agent Guide を参照してください。

CI/CD

GitHub Actions 向けに takt-action を提供しています。

- uses: nrslib/takt-action@main
  with:
    anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}

他の CI ではパイプラインモードを使います。

takt --pipeline --task "バグを修正して" --auto-pr

セットアップの詳細は CI/CD Guide を参照してください。

プロジェクト構造

~/.takt/                    # グローバル設定
├── config.yaml             # プロバイダー、モデル、言語など
├── pieces/                 # ユーザー定義の piece
├── facets/                 # ユーザー定義のファセット（personas, policies, knowledge など）
└── repertoire/               # インストール済み repertoire パッケージ

.takt/                      # プロジェクトレベル
├── config.yaml             # プロジェクト設定
├── facets/                 # プロジェクトのファセット
├── tasks.yaml              # 積まれたタスク
├── tasks/                  # タスクの仕様書
└── runs/                   # 実行レポート、ログ、コンテキスト

API

import { PieceEngine, loadPiece } from 'takt';

const config = loadPiece('default');
if (!config) throw new Error('Piece not found');

const engine = new PieceEngine(config, process.cwd(), 'My task');
engine.on('step:complete', (step, response) => {
  console.log(`${step.name}: ${response.status}`);
});

await engine.run();

ドキュメント

ドキュメント 内容
CLI Reference 全コマンド・オプション
Configuration グローバル設定・プロジェクト設定
Piece Guide piece の作成・カスタマイズ
Agent Guide カスタムエージェントの設定
Builtin Catalog ビルトイン piece・persona の一覧
Faceted Prompting プロンプト設計の方法論
Repertoire Packages パッケージのインストール・共有
Task Management タスクの追加・実行・隔離
CI/CD Integration GitHub Actions・パイプラインモード
Changelog (日本語) バージョン履歴
Security Policy 脆弱性の報告

コミュニティ

質問・議論・最新情報は TAKT Discord へどうぞ。

コントリビュート

CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。