4941f8eabf
README を約950行から約270行に圧縮し、詳細は個別ドキュメントに分離した。 コンセプトを実態に合わせて再定義（4軸: すぐ始められる・実用的・再現可能・マルチエージェント）し、 基本ユースケースを takt → takt run のフローに修正した。 英語版・日本語版の両方を対応し、日本語版はネイティブ日本語で記述。
273 lines
9.9 KiB
Markdown
273 lines
9.9 KiB
Markdown
# TAKT
|
||
|
||
[English](../README.md)
|
||
|
||
**T**AKT **A**gent **K**oordination **T**opology — 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](./faceted-prompting.ja.md)）。
|
||
|
||
## 必要なもの
|
||
|
||
次のいずれかが必要です。
|
||
|
||
- **プロバイダー CLI**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex](https://github.com/openai/codex)、[OpenCode](https://opencode.ai) のいずれか
|
||
- **API Key 直接利用**: Anthropic / OpenAI / OpenCode の API Key があれば CLI は不要です
|
||
|
||
任意:
|
||
|
||
- [GitHub CLI](https://cli.github.com/) (`gh`) — `takt #N` で GitHub Issue を使う場合に必要です
|
||
|
||
## クイックスタート
|
||
|
||
### インストール
|
||
|
||
```bash
|
||
npm install -g takt
|
||
```
|
||
|
||
### AI と相談して実行する
|
||
|
||
```
|
||
$ takt
|
||
|
||
Select piece:
|
||
> 🎼 default (current)
|
||
📁 🚀 クイックスタート/
|
||
📁 🎨 フロントエンド/
|
||
📁 ⚙️ バックエンド/
|
||
|
||
対話モード - タスク内容を入力してください。
|
||
コマンド: /go（実行）, /cancel（終了）
|
||
|
||
> ユーザー認証を JWT で追加して
|
||
|
||
[AI が要件を整理してくれます]
|
||
|
||
> /go
|
||
|
||
提案されたタスク指示:
|
||
...
|
||
|
||
どうしますか？
|
||
> 実行する
|
||
GitHub Issueを建てる
|
||
タスクにつむ
|
||
会話を続ける
|
||
```
|
||
|
||
TAKT が隔離された worktree を作り、piece を実行（計画 → 実装 → レビュー → 修正ループ）します。終わったら PR を作成するか聞いてきます。
|
||
|
||
### タスクを積んでまとめて実行する
|
||
|
||
```bash
|
||
# 会話でタスクを積みます
|
||
takt
|
||
> auth モジュールをリファクタリングして
|
||
> /go
|
||
# → どうしますか？ → 「タスクにつむ」を選択
|
||
|
||
# GitHub Issue から積むこともできます
|
||
takt add #6
|
||
takt add #12
|
||
|
||
# まとめて実行します
|
||
takt run
|
||
```
|
||
|
||
### 結果を管理する
|
||
|
||
```bash
|
||
# 完了・失敗したタスクブランチの一覧を確認し、マージ、リトライ、削除ができます
|
||
takt list
|
||
```
|
||
|
||
## 仕組み
|
||
|
||
TAKT は音楽のメタファーを使っています。**piece** がワークフロー、**movement** が各ステップにあたります。
|
||
|
||
piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。
|
||
|
||
```yaml
|
||
name: simple
|
||
initial_movement: plan
|
||
|
||
personas:
|
||
planner: ../personas/planner.md
|
||
coder: ../personas/coder.md
|
||
reviewer: ../personas/architecture-reviewer.md
|
||
|
||
movements:
|
||
- name: plan
|
||
persona: planner
|
||
edit: false
|
||
rules:
|
||
- condition: Planning complete
|
||
next: implement
|
||
|
||
- name: implement
|
||
persona: coder
|
||
edit: true
|
||
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](./pieces.md) を参照してください。
|
||
|
||
## おすすめ piece
|
||
|
||
| Piece | 用途 |
|
||
|-------|------|
|
||
| `default-mini` | ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。 |
|
||
| `frontend-mini` | フロントエンド向けの mini 構成です。 |
|
||
| `backend-mini` | バックエンド向けの mini 構成です。 |
|
||
| `expert-mini` | エキスパート向けの mini 構成です。 |
|
||
| `default` | 本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。 |
|
||
全ピース・ペルソナの一覧は [Builtin Catalog](./builtin-catalog.ja.md) を参照してください。
|
||
|
||
## 主要コマンド
|
||
|
||
| コマンド | 説明 |
|
||
|---------|------|
|
||
| `takt` | AI と相談して、タスクを実行または積みます |
|
||
| `takt run` | 積まれたタスクをまとめて実行します |
|
||
| `takt list` | タスクブランチを管理します（マージ、リトライ、追加指示、削除） |
|
||
| `takt #N` | GitHub Issue をタスクとして実行します |
|
||
| `takt switch` | 使う piece を切り替えます |
|
||
| `takt eject` | ビルトインの piece/persona をコピーしてカスタマイズできます |
|
||
|
||
全コマンド・オプションは [CLI Reference](./cli-reference.ja.md) を参照してください。
|
||
|
||
## 設定
|
||
|
||
最小限の `~/.takt/config.yaml` は次の通りです。
|
||
|
||
```yaml
|
||
provider: claude # claude, codex, or opencode
|
||
model: sonnet # プロバイダーにそのまま渡されます
|
||
language: ja # en or ja
|
||
```
|
||
|
||
API Key を直接使う場合は、CLI のインストールは不要です。
|
||
|
||
```bash
|
||
export TAKT_ANTHROPIC_API_KEY=sk-ant-...
|
||
```
|
||
|
||
全設定項目・プロバイダープロファイル・モデル解決の詳細は [Configuration Guide](./configuration.ja.md) を参照してください。
|
||
|
||
## カスタマイズ
|
||
|
||
### カスタム piece
|
||
|
||
```bash
|
||
takt eject default # ビルトインを ~/.takt/pieces/ にコピーして編集できます
|
||
```
|
||
|
||
### カスタム persona
|
||
|
||
`~/.takt/personas/` に Markdown ファイルを置きます。
|
||
|
||
```markdown
|
||
# ~/.takt/personas/my-reviewer.md
|
||
You are a code reviewer specialized in security.
|
||
```
|
||
|
||
piece から `persona: my-reviewer` で参照できます。
|
||
|
||
詳細は [Piece Guide](./pieces.md) と [Agent Guide](./agents.md) を参照してください。
|
||
|
||
## CI/CD
|
||
|
||
GitHub Actions 向けに [takt-action](https://github.com/nrslib/takt-action) を提供しています。
|
||
|
||
```yaml
|
||
- uses: nrslib/takt-action@main
|
||
with:
|
||
anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
|
||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||
```
|
||
|
||
他の CI ではパイプラインモードを使います。
|
||
|
||
```bash
|
||
takt --pipeline --task "バグを修正して" --auto-pr
|
||
```
|
||
|
||
セットアップの詳細は [CI/CD Guide](./ci-cd.ja.md) を参照してください。
|
||
|
||
## プロジェクト構造
|
||
|
||
```
|
||
~/.takt/ # グローバル設定
|
||
├── config.yaml # プロバイダー、モデル、言語など
|
||
├── pieces/ # ユーザー定義の piece
|
||
└── personas/ # ユーザー定義の persona
|
||
|
||
.takt/ # プロジェクトレベル
|
||
├── config.yaml # プロジェクト設定
|
||
├── tasks.yaml # 積まれたタスク
|
||
├── tasks/ # タスクの仕様書
|
||
└── runs/ # 実行レポート、ログ、コンテキスト
|
||
```
|
||
|
||
## API
|
||
|
||
```typescript
|
||
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](./cli-reference.ja.md) | 全コマンド・オプション |
|
||
| [Configuration](./configuration.ja.md) | グローバル設定・プロジェクト設定 |
|
||
| [Piece Guide](./pieces.md) | piece の作成・カスタマイズ |
|
||
| [Agent Guide](./agents.md) | カスタムエージェントの設定 |
|
||
| [Builtin Catalog](./builtin-catalog.ja.md) | ビルトイン piece・persona の一覧 |
|
||
| [Faceted Prompting](./faceted-prompting.ja.md) | プロンプト設計の方法論 |
|
||
| [Task Management](./task-management.ja.md) | タスクの追加・実行・隔離 |
|
||
| [CI/CD Integration](./ci-cd.ja.md) | GitHub Actions・パイプラインモード |
|
||
| [Changelog](../CHANGELOG.md) ([日本語](./CHANGELOG.ja.md)) | バージョン履歴 |
|
||
| [Security Policy](../SECURITY.md) | 脆弱性の報告 |
|
||
|
||
## コントリビュート
|
||
|
||
[CONTRIBUTING.md](../CONTRIBUTING.md) を参照してください。
|
||
|
||
## ライセンス
|
||
|
||
MIT — [LICENSE](../LICENSE) を参照してください。
|