nrslib 9ce4358e9d Release v0.28.0-alpha.1

2026-02-28 22:01:34 +09:00

11 KiB

Raw Blame History

TAKT

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

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

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

なぜ TAKT か

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

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

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

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

必要なもの

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

プロバイダー CLI: Claude Code、Codex、OpenCode、Cursor Agent、GitHub Copilot のいずれか
API Key 直接利用: Anthropic / OpenAI / OpenCode / Cursor の 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 は音楽のメタファーを使っています。TAKT という名前自体が、オーケストラの指揮で拍を刻む「タクト（Takt）」に由来しています。piece がワークフロー、movement が各ステップにあたります。音楽の楽曲（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	用途
`default-mini`	ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。
`default-test-first-mini`	テストファースト開発向けです。テストを先に書き、それを通す実装を行います。
`frontend-mini`	フロントエンド向けの mini 構成です。
`backend-mini`	バックエンド向けの mini 構成です。
`expert-mini`	エキスパート向けの mini 構成です。
`default`	本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。

主要コマンド

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

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

設定

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

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

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

export TAKT_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-...          # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=...           # OpenCode
export TAKT_CURSOR_API_KEY=...             # Cursor Agent（login 済みなら省略可）

全設定項目・プロバイダープロファイル・モデル解決の詳細は 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('movement:complete', (movement, response) => {
  console.log(`${movement.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・パイプラインモード
Provider Sandbox	プロバイダーのサンドボックス設定
Changelog (日本語)	バージョン履歴
Security Policy	脆弱性の報告

コミュニティ

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

コントリビュート

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

ライセンス

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

11 KiB Raw Blame History Unescape Escape