agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

README刷新: agent→persona, セクションマップ導入, 制御・管理セクション追加

Browse Source 
- ピース例・カスタムピース例にセクションマップ（personas/policies/knowledge）を追加
- agent: → persona: に全面置換、ディレクトリ構造も agents/ → personas/ に更新
- dist/resources/ → builtins/ に修正
- 「TAKTが制御・管理するもの」セクションを追加（制御: ルーティング・権限・記録、管理: ペルソナ・ポリシー・ナレッジ）
- ドキュメントファイル名を prompt-composition → faceted-prompting にリネーム
- Faceted Prompting ドキュメントの Policy 配置とエンジン説明を修正
- クローン作成時の進捗ログを追加
This commit is contained in:
nrslib 2026-02-07 21:58:42 +09:00
parent e506c4035f
commit 9e50e9df4b
6 changed files with 163 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@ -4,7 +4,7 @@
**T**ask **A**gent **K**oordination **T**ool - Define how AI agents coordinate, where humans intervene, and what gets recorded — in YAML **T**ask **A**gent **K**oordination **T**ool - Define how AI agents coordinate, where humans intervene, and what gets recorded — in YAML
TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what's allowed, what happens on failure — is declared in a piece file, not left to the agent. TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what they see, what's allowed, what happens on failure — is declared in a piece file, not left to the agent.
TAKT is built with TAKT itself (dogfooding). TAKT is built with TAKT itself (dogfooding).
@ -24,6 +24,21 @@ You can read every term as standard workflow language (piece = workflow, movemen
- Multi-agent coordination needs structure — pieces define who does what, in what order, with what permissions - Multi-agent coordination needs structure — pieces define who does what, in what order, with what permissions
- CI/CD integration needs guardrails — pipeline mode runs agents non-interactively with full audit logs - CI/CD integration needs guardrails — pipeline mode runs agents non-interactively with full audit logs
## What TAKT Controls and Manages
TAKT **controls** agent execution and **manages** prompt components.
| | Concern | Description |
|---|---------|-------------|
| Control | **Routing** | State transition rules (who runs when) |
| Control | **Tools & Permissions** | Readonly, edit, full access (what's allowed) |
| Control | **Recording** | Session logs, reports (what gets captured) |
| Manage | **Personas** | Agent roles and expertise (who they act as) |
| Manage | **Policies** | Coding standards, quality criteria, prohibitions (what to uphold) |
| Manage | **Knowledge** | Domain knowledge, architecture info (what to reference) |
Personas, policies, and knowledge are managed as independent files and freely combined across workflows ([Faceted Prompting](./docs/faceted-prompting.md)). Change a policy in one file and every workflow using it gets the update.
## What TAKT is NOT ## What TAKT is NOT
- **Not an autonomous engineer** — TAKT coordinates agents but doesn't decide what to build. You provide the task, TAKT governs the execution. - **Not an autonomous engineer** — TAKT coordinates agents but doesn't decide what to build. You provide the task, TAKT governs the execution.
@ -235,7 +250,7 @@ In pipeline mode, PRs are not created unless `--auto-pr` is specified.
# Interactively switch pieces # Interactively switch pieces
takt switch takt switch
# Copy builtin pieces/agents to project .takt/ for customization # Copy builtin pieces/personas to project .takt/ for customization
takt eject takt eject
# Copy to ~/.takt/ (global) instead # Copy to ~/.takt/ (global) instead
@ -244,7 +259,7 @@ takt eject --global
# Clear agent conversation sessions # Clear agent conversation sessions
takt clear takt clear
# Deploy builtin pieces/agents as Claude Code Skill # Deploy builtin pieces/personas as Claude Code Skill
takt export-cc takt export-cc
# Preview assembled prompts for each movement and phase # Preview assembled prompts for each movement and phase
@ -296,9 +311,21 @@ name: default
max_iterations: 10 max_iterations: 10
initial_movement: plan initial_movement: plan
# Section maps — key: file path (relative to this YAML)
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
reviewer: ../personas/architecture-reviewer.md
policies:
coding: ../policies/coding.md
knowledge:
architecture: ../knowledge/architecture.md
movements: movements:
- name: plan - name: plan
agent: ../agents/default/planner.md persona: planner
model: opus model: opus
edit: false edit: false
rules: rules:
@ -308,7 +335,9 @@ movements:
Analyze the request and create an implementation plan. Analyze the request and create an implementation plan.
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
policy: coding
knowledge: architecture
edit: true edit: true
permission_mode: edit permission_mode: edit
rules: rules:
@ -320,7 +349,8 @@ movements:
Implement based on the plan. Implement based on the plan.
- name: review - name: review
agent: ../agents/default/architecture-reviewer.md persona: reviewer
knowledge: architecture
edit: false edit: false
rules: rules:
- condition: Approved - condition: Approved
@ -331,13 +361,13 @@ movements:
Review the implementation from architecture and code quality perspectives. Review the implementation from architecture and code quality perspectives.
``` ```
### Agentless Movements ### Persona-less Movements
The `agent` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require agent behavior customization. The `persona` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require persona customization.
```yaml ```yaml
- name: summarize - name: summarize
# No agent specified — uses instruction_template only # No persona specified — uses instruction_template only
edit: false edit: false
rules: rules:
- condition: Summary complete - condition: Summary complete
@ -346,11 +376,11 @@ The `agent` field is optional. When omitted, the movement executes using only th
Read the report and provide a concise summary. Read the report and provide a concise summary.
``` ```
You can also write an inline system prompt as the `agent` value (if the specified file doesn't exist): You can also write an inline system prompt as the `persona` value (if the specified file doesn't exist):
```yaml ```yaml
- name: review - name: review
agent: "You are a code reviewer. Focus on readability and maintainability." persona: "You are a code reviewer. Focus on readability and maintainability."
edit: false edit: false
instruction_template: | instruction_template: |
Review code quality. Review code quality.
@ -364,14 +394,14 @@ Execute sub-movements in parallel within a movement and evaluate with aggregate
- name: reviewers - name: reviewers
parallel: parallel:
- name: arch-review - name: arch-review
agent: ../agents/default/architecture-reviewer.md persona: reviewer
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction_template: |
Review architecture and code quality. Review architecture and code quality.
- name: security-review - name: security-review
agent: ../agents/default/security-reviewer.md persona: security-reviewer
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
@ -417,10 +447,10 @@ TAKT includes multiple builtin pieces:
Use `takt switch` to switch pieces. Use `takt switch` to switch pieces.
## Builtin Agents ## Builtin Personas
| Agent | Description | | Persona | Description |
|-------|-------------| |---------|-------------|
| **planner** | Task analysis, spec investigation, implementation planning | | **planner** | Task analysis, spec investigation, implementation planning |
| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans | | **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans |
| **coder** | Feature implementation, bug fixing | | **coder** | Feature implementation, bug fixing |
@ -431,12 +461,12 @@ Use `takt switch` to switch pieces.
| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags | | **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags |
| **supervisor** | Final validation, approval | | **supervisor** | Final validation, approval |
## Custom Agents ## Custom Personas
Create agent prompts in Markdown files: Create persona prompts in Markdown files:
```markdown ```markdown
# ~/.takt/agents/my-agents/reviewer.md # ~/.takt/personas/my-reviewer.md
You are a code reviewer specialized in security. You are a code reviewer specialized in security.
@ -465,8 +495,8 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
├── config.yaml # Global config (provider, model, piece, etc.) ├── config.yaml # Global config (provider, model, piece, etc.)
├── pieces/ # User piece definitions (override builtins) ├── pieces/ # User piece definitions (override builtins)
│ └── custom.yaml │ └── custom.yaml
└── agents/ # User agent prompt files (.md) └── personas/ # User persona prompt files (.md)
└── my-agent.md └── my-persona.md
.takt/ # Project-level configuration .takt/ # Project-level configuration
├── config.yaml # Project config (current piece, etc.) ├── config.yaml # Project config (current piece, etc.)
@ -480,7 +510,7 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
└── {sessionId}.jsonl # NDJSON session log per piece execution └── {sessionId}.jsonl # NDJSON session log per piece execution
``` ```
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority. Builtin resources are embedded in the npm package (`builtins/`). User files in `~/.takt/` take priority.
### Global Configuration ### Global Configuration
@ -615,9 +645,13 @@ description: Custom piece
max_iterations: 5 max_iterations: 5
initial_movement: analyze initial_movement: analyze
personas:
analyzer: ~/.takt/personas/analyzer.md
coder: ../personas/coder.md
movements: movements:
- name: analyze - name: analyze
agent: ~/.takt/agents/my-agents/analyzer.md persona: analyzer
edit: false edit: false
rules: rules:
- condition: Analysis complete - condition: Analysis complete
@ -626,7 +660,7 @@ movements:
Thoroughly analyze this request. Thoroughly analyze this request.
- name: implement - name: implement
agent: ~/.takt/agents/default/coder.md persona: coder
edit: true edit: true
permission_mode: edit permission_mode: edit
pass_previous_response: true pass_previous_response: true
@ -639,19 +673,15 @@ movements:
> **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template. > **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template.
### Specifying Agents by Path ### Specifying Personas by Path
In piece definitions, specify agents using file paths: Map keys to file paths in section maps, then reference keys from movements:
```yaml ```yaml
# Relative path from piece file # Section maps (relative to piece file)
agent: ../agents/default/coder.md personas:
coder: ../personas/coder.md
# Home directory reviewer: ~/.takt/personas/my-reviewer.md
agent: ~/.takt/agents/default/coder.md
# Absolute path
agent: /path/to/custom/agent.md
``` ```
### Piece Variables ### Piece Variables
@ -673,11 +703,11 @@ Variables available in `instruction_template`:
Elements needed for each piece movement: Elements needed for each piece movement:
**1. Agent** - Markdown file containing system prompt: **1. Persona** - Referenced by section map key (used as system prompt):
```yaml ```yaml
agent: ../agents/default/coder.md # Path to agent prompt file persona: coder # Key from personas section map
agent_name: coder # Display name (optional) persona_name: coder # Display name (optional)
``` ```
**2. Rules** - Define routing from movement to next movement. The instruction builder auto-injects status output rules, so agents know which tags to output: **2. Rules** - Define routing from movement to next movement. The instruction builder auto-injects status output rules, so agents know which tags to output:
@ -787,7 +817,7 @@ export TAKT_OPENAI_API_KEY=sk-...
## Documentation ## Documentation
- [Faceted Prompting](./docs/prompt-composition.md) - Separation of Concerns for AI prompts (Persona, Stance, Instruction, Knowledge, Report Format) - [Faceted Prompting](./docs/faceted-prompting.md) - Separation of Concerns for AI prompts (Persona, Policy, Instruction, Knowledge, Output Contract)
- [Piece Guide](./docs/pieces.md) - Creating and customizing pieces - [Piece Guide](./docs/pieces.md) - Creating and customizing pieces
- [Agent Guide](./docs/agents.md) - Configuring custom agents - [Agent Guide](./docs/agents.md) - Configuring custom agents
- [Changelog](../CHANGELOG.md) - Version history - [Changelog](../CHANGELOG.md) - Version history

102
docs/README.ja.md
View File

@ -2,7 +2,7 @@
**T**ask **A**gent **K**oordination **T**ool - AIエージェントの協調手順・人の介入ポイント・記録をYAMLで定義する **T**ask **A**gent **K**oordination **T**ool - AIエージェントの協調手順・人の介入ポイント・記録をYAMLで定義する
TAKTは複数のAIエージェント（Claude Code、Codex）をYAMLで定義されたワークフローに従って実行します。各ステップで誰が実行し、何を許可し、失敗時にどうするかはピースファイルに宣言され、エージェント任せにしません。 TAKTは複数のAIエージェント（Claude Code、Codex）をYAMLで定義されたワークフローに従って実行します。各ステップで誰が実行し、何を見て、何を許可し、失敗時にどうするかはピースファイルに宣言され、エージェント任せにしません。
TAKTはTAKT自身で開発されています（ドッグフーディング）。 TAKTはTAKT自身で開発されています（ドッグフーディング）。
@ -20,6 +20,21 @@ TAKTはオーケストラをイメージした音楽メタファで用語を統
- マルチエージェントの協調には構造が必要 — ピースが誰が何をどの順序でどの権限で行うかを定義する - マルチエージェントの協調には構造が必要 — ピースが誰が何をどの順序でどの権限で行うかを定義する
- CI/CD連携にはガードレールが必要 — パイプラインモードが非対話でエージェントを実行し、完全な監査ログを残す - CI/CD連携にはガードレールが必要 — パイプラインモードが非対話でエージェントを実行し、完全な監査ログを残す
## TAKTが制御・管理するもの
TAKTはエージェントの実行を**制御**し、プロンプトの構成要素を**管理**します。
| | 対象 | 説明 |
|---|------|------|
| 制御 | **ルーティング** | 状態遷移ルール（誰がいつ動くか） |
| 制御 | **ツール・権限** | 読み取り専用・編集可・フルアクセス（何を許可するか） |
| 制御 | **記録** | セッションログ・レポート（何を残すか） |
| 管理 | **ペルソナ** | エージェントの役割・専門性（誰として振る舞うか） |
| 管理 | **ポリシー** | コーディング規約・品質基準・禁止事項（何を守るか） |
| 管理 | **ナレッジ** | ドメイン知識・アーキテクチャ情報（何を参照するか） |
ペルソナ・ポリシー・ナレッジは独立したファイルとして管理され、ワークフロー間で自由に組み合わせられます（[Faceted Prompting](./faceted-prompting.ja.md)）。ポリシーを1ファイル変更すれば、それを使うすべてのワークフローに反映されます。
## TAKTとは何でないか ## TAKTとは何でないか
- **自律型AIエンジニアではない** — TAKTはエージェントを協調させるが、何を作るかは決めない。タスクを与えるのはあなたで、TAKTは実行を統制する。 - **自律型AIエンジニアではない** — TAKTはエージェントを協調させるが、何を作るかは決めない。タスクを与えるのはあなたで、TAKTは実行を統制する。
@ -292,9 +307,21 @@ name: default
max_iterations: 10 max_iterations: 10
initial_movement: plan initial_movement: plan
# セクションマップ — キー: ファイルパス（このYAMLからの相対パス）
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
reviewer: ../personas/architecture-reviewer.md
policies:
coding: ../policies/coding.md
knowledge:
architecture: ../knowledge/architecture.md
movements: movements:
- name: plan - name: plan
agent: ../agents/default/planner.md persona: planner
model: opus model: opus
edit: false edit: false
rules: rules:
@ -304,7 +331,9 @@ movements:
リクエストを分析し、実装計画を作成してください。 リクエストを分析し、実装計画を作成してください。
- name: implement - name: implement
agent: ../agents/default/coder.md persona: coder
policy: coding
knowledge: architecture
edit: true edit: true
permission_mode: edit permission_mode: edit
rules: rules:
@ -316,7 +345,8 @@ movements:
計画に基づいて実装してください。 計画に基づいて実装してください。
- name: review - name: review
agent: ../agents/default/architecture-reviewer.md persona: reviewer
knowledge: architecture
edit: false edit: false
rules: rules:
- condition: 承認 - condition: 承認
@ -327,13 +357,13 @@ movements:
アーキテクチャとコード品質の観点で実装をレビューしてください。 アーキテクチャとコード品質の観点で実装をレビューしてください。
``` ```
### エージェントレスムーブメント ### ペルソナレスムーブメント
`agent` フィールドは省略可能です。省略した場合、ムーブメントはシステムプロンプトなしで `instruction_template` のみを使って実行されます。これはエージェントの動作カスタマイズが不要なシンプルなタスクに便利です。 `persona` フィールドは省略可能です。省略した場合、ムーブメントはシステムプロンプトなしで `instruction_template` のみを使って実行されます。これはペルソナのカスタマイズが不要なシンプルなタスクに便利です。
```yaml ```yaml
- name: summarize - name: summarize
# agent未指定 — instruction_templateのみを使用 # persona未指定 — instruction_templateのみを使用
edit: false edit: false
rules: rules:
- condition: 要約完了 - condition: 要約完了
@ -342,11 +372,11 @@ movements:
レポートを読んで簡潔な要約を提供してください。 レポートを読んで簡潔な要約を提供してください。
``` ```
また、`agent` の値としてインラインシステムプロンプトを記述することもできます（指定されたファイルが存在しない場合）: また、`persona` の値としてインラインシステムプロンプトを記述することもできます（指定されたファイルが存在しない場合）:
```yaml ```yaml
- name: review - name: review
agent: "あなたはコードレビュアーです。可読性と保守性に焦点を当ててください。" persona: "あなたはコードレビュアーです。可読性と保守性に焦点を当ててください。"
edit: false edit: false
instruction_template: | instruction_template: |
コード品質をレビューしてください。 コード品質をレビューしてください。
@ -360,14 +390,14 @@ movements:
- name: reviewers - name: reviewers
parallel: parallel:
- name: arch-review - name: arch-review
agent: ../agents/default/architecture-reviewer.md persona: reviewer
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
instruction_template: | instruction_template: |
アーキテクチャとコード品質をレビューしてください。 アーキテクチャとコード品質をレビューしてください。
- name: security-review - name: security-review
agent: ../agents/default/security-reviewer.md persona: security-reviewer
rules: rules:
- condition: approved - condition: approved
- condition: needs_fix - condition: needs_fix
@ -413,10 +443,10 @@ TAKTには複数のビルトインピースが同梱されています:
`takt switch` でピースを切り替えられます。 `takt switch` でピースを切り替えられます。
## ビルトインエージェント ## ビルトインペルソナ
| エージェント | 説明 | | ペルソナ | 説明 |
|------------|------| |---------|------|
| **planner** | タスク分析、仕様調査、実装計画 | | **planner** | タスク分析、仕様調査、実装計画 |
| **architect-planner** | タスク分析と設計計画: コード調査、不明点の解決、実装計画の作成 | | **architect-planner** | タスク分析と設計計画: コード調査、不明点の解決、実装計画の作成 |
| **coder** | 機能の実装、バグ修正 | | **coder** | 機能の実装、バグ修正 |
@ -427,12 +457,12 @@ TAKTには複数のビルトインピースが同梱されています:
| **conductor** | Phase 3 判定専用: レポートやレスポンスを読み取り、ステータスタグを出力 | | **conductor** | Phase 3 判定専用: レポートやレスポンスを読み取り、ステータスタグを出力 |
| **supervisor** | 最終検証、バリデーション、承認 | | **supervisor** | 最終検証、バリデーション、承認 |
## カスタムエージェント ## カスタムペルソナ
Markdown ファイルでエージェントプロンプトを作成: Markdown ファイルでペルソナプロンプトを作成:
```markdown ```markdown
# ~/.takt/agents/my-agents/reviewer.md # ~/.takt/personas/my-reviewer.md
あなたはセキュリティに特化したコードレビュアーです。 あなたはセキュリティに特化したコードレビュアーです。
@ -461,8 +491,8 @@ Claude Code はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`def
├── config.yaml # グローバル設定（プロバイダー、モデル、ピース等） ├── config.yaml # グローバル設定（プロバイダー、モデル、ピース等）
├── pieces/ # ユーザーピース定義（ビルトインを上書き） ├── pieces/ # ユーザーピース定義（ビルトインを上書き）
│ └── custom.yaml │ └── custom.yaml
└── agents/ # ユーザーエージェントプロンプトファイル（.md） └── personas/ # ユーザーペルソナプロンプトファイル（.md）
└── my-agent.md └── my-persona.md
.takt/ # プロジェクトレベルの設定 .takt/ # プロジェクトレベルの設定
├── config.yaml # プロジェクト設定（現在のピース等） ├── config.yaml # プロジェクト設定（現在のピース等）
@ -476,7 +506,7 @@ Claude Code はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`def
└── {sessionId}.jsonl # ピース実行ごとの NDJSON セッションログ └── {sessionId}.jsonl # ピース実行ごとの NDJSON セッションログ
``` ```
ビルトインリソースはnpmパッケージ（`dist/resources/`）に埋め込まれています。`~/.takt/` のユーザーファイルが優先されます。 ビルトインリソースはnpmパッケージ（`builtins/`）に埋め込まれています。`~/.takt/` のユーザーファイルが優先されます。
### グローバル設定 ### グローバル設定
@ -611,9 +641,13 @@ description: カスタムピース
max_iterations: 5 max_iterations: 5
initial_movement: analyze initial_movement: analyze
personas:
analyzer: ~/.takt/personas/analyzer.md
coder: ../personas/coder.md
movements: movements:
- name: analyze - name: analyze
agent: ~/.takt/agents/my-agents/analyzer.md persona: analyzer
edit: false edit: false
rules: rules:
- condition: 分析完了 - condition: 分析完了
@ -622,7 +656,7 @@ movements:
このリクエストを徹底的に分析してください。 このリクエストを徹底的に分析してください。
- name: implement - name: implement
agent: ~/.takt/agents/default/coder.md persona: coder
edit: true edit: true
permission_mode: edit permission_mode: edit
pass_previous_response: true pass_previous_response: true
@ -635,19 +669,15 @@ movements:
> **Note**: `{task}`、`{previous_response}`、`{user_inputs}` は自動的にインストラクションに注入されます。テンプレート内での位置を制御したい場合のみ、明示的なプレースホルダーが必要です。 > **Note**: `{task}`、`{previous_response}`、`{user_inputs}` は自動的にインストラクションに注入されます。テンプレート内での位置を制御したい場合のみ、明示的なプレースホルダーが必要です。
### エージェントをパスで指定する ### ペルソナをパスで指定する
ピース定義ではファイルパスを使ってエージェントを指定します: セクションマップでキーとファイルパスを対応付け、ムーブメントからキーで参照します:
```yaml ```yaml
# ピースファイルからの相対パス # セクションマップ（ピースファイルからの相対パス）
agent: ../agents/default/coder.md personas:
coder: ../personas/coder.md
# ホームディレクトリ reviewer: ~/.takt/personas/my-reviewer.md
agent: ~/.takt/agents/default/coder.md
# 絶対パス
agent: /path/to/custom/agent.md
``` ```
### ピース変数 ### ピース変数
@ -669,11 +699,11 @@ agent: /path/to/custom/agent.md
各ピースのムーブメントに必要な要素: 各ピースのムーブメントに必要な要素:
**1. エージェント** - システムプロンプトを含むMarkdownファイル: **1. ペルソナ** - セクションマップのキーで参照（system promptとして使用）:
```yaml ```yaml
agent: ../agents/default/coder.md # エージェントプロンプトファイルのパス persona: coder # personas セクションマップのキー
agent_name: coder # 表示名（オプション） persona_name: coder # 表示名（オプション）
``` ```
**2. ルール** - ムーブメントから次のムーブメントへのルーティングを定義。インストラクションビルダーがステータス出力ルールを自動注入するため、エージェントはどのタグを出力すべきか把握できます: **2. ルール** - ムーブメントから次のムーブメントへのルーティングを定義。インストラクションビルダーがステータス出力ルールを自動注入するため、エージェントはどのタグを出力すべきか把握できます:
@ -783,7 +813,7 @@ export TAKT_OPENAI_API_KEY=sk-...
## ドキュメント ## ドキュメント
- [Faceted Prompting](./prompt-composition.ja.md) - AIプロンプトへの関心の分離（Persona, Policy, Instruction, Knowledge, Output Contract） - [Faceted Prompting](./faceted-prompting.ja.md) - AIプロンプトへの関心の分離（Persona, Policy, Instruction, Knowledge, Output Contract）
- [Piece Guide](./pieces.md) - ピースの作成とカスタマイズ - [Piece Guide](./pieces.md) - ピースの作成とカスタマイズ
- [Agent Guide](./agents.md) - カスタムエージェントの設定 - [Agent Guide](./agents.md) - カスタムエージェントの設定
- [Changelog](../CHANGELOG.md) - バージョン履歴 - [Changelog](../CHANGELOG.md) - バージョン履歴

2
docs/prompt-composition.ja.md → docs/faceted-prompting.ja.md
View File

@ -408,7 +408,7 @@ movements:
**エンジンにとって:** **エンジンにとって:**
- プロンプト組み立ては決定的 — 同じワークフロー定義とファイルからは同じプロンプトが構築される - プロンプト組み立ては決定的 — 同じワークフロー定義とファイルからは同じプロンプトが構築される
- ポリシーの配置を最適化できる（例: 「Lost in the Middle」効果に対抗するためプロンプトの先頭と末尾に配置） - ポリシーの配置を最適化できる（例: recency効果を活用して末尾に配置し、制約遵守を強化）
- 各関心を他の部分に影響を与えずにステップごとに注入・省略・上書きできる - 各関心を他の部分に影響を与えずにステップごとに注入・省略・上書きできる
## まとめ ## まとめ

50
docs/prompt-composition.md → docs/faceted-prompting.md
View File

@ -49,15 +49,17 @@ System Prompt:
User Message: User Message:
┌──────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────┐
│ Policy — rules, prohibitions, quality standards │
│ Knowledge — reference materials for judgment │ │ Knowledge — reference materials for judgment │
│ Instruction — step-specific procedures │ │ Instruction — step-specific procedures │
│ Output Contract — output structure definition │ │ Output Contract — output structure definition │
│ Policy — rules, prohibitions, quality standards │
└──────────────────────────────────────────────────┘ └──────────────────────────────────────────────────┘
``` ```
Persona is the agent's **identity** — it doesn't change across tasks. Placing it in the system prompt shapes all LLM responses. The remaining four change per step and are composed into the user message. Persona is the agent's **identity** — it doesn't change across tasks. Placing it in the system prompt shapes all LLM responses. The remaining four change per step and are composed into the user message.
Placing Policy at the end of the user message is a deliberate design choice. LLMs are strongly influenced by what they read last (recency effect). Constraints such as prohibitions and REJECT criteria are more likely to be followed when placed immediately before output generation. The flow of Knowledge → Instruction → Policy also follows a natural cognitive order: "understand the context → understand the task → confirm the constraints."
Below are typical file examples for each facet. Below are typical file examples for each facet.
#### Persona — `personas/architecture-reviewer.md` #### Persona — `personas/architecture-reviewer.md`
@ -213,31 +215,9 @@ You evaluate code structure, design, and maintainability.
**User Message:** **User Message:**
```markdown ```markdown
## Policy
# Coding Policy
## Principles
| Principle | Standard |
|-----------|----------|
| DRY | 3+ duplications → REJECT |
| Fail Fast | Reject invalid state early |
| Least Privilege | Minimal scope necessary |
## Prohibitions
- **Unused code** — no "just in case" methods, no future-use fields
- **Direct object mutation** — create new objects with spread operators
- **Fallback abuse** — don't hide uncertainty with `?? 'default'`
---
## Knowledge ## Knowledge
# Architecture Knowledge ### Layer Structure
## Layer Structure
Dependency direction: upper layers → lower layers (reverse prohibited) Dependency direction: upper layers → lower layers (reverse prohibited)
@ -247,7 +227,7 @@ Dependency direction: upper layers → lower layers (reverse prohibited)
| Service | Business logic | Repository | | Service | Business logic | Repository |
| Repository | Data access | None | | Repository | Data access | None |
## File Organization ### File Organization
| Criteria | Judgment | | Criteria | Judgment |
|----------|----------| |----------|----------|
@ -302,6 +282,24 @@ Output your report in the following format.
|---|----------|-------|-----| |---|----------|-------|-----|
| 1 | `src/file.ts:42` | Issue description | How to fix | | 1 | `src/file.ts:42` | Issue description | How to fix |
\``` \```
---
## Policy
### Principles
| Principle | Standard |
|-----------|----------|
| DRY | 3+ duplications → REJECT |
| Fail Fast | Reject invalid state early |
| Least Privilege | Minimal scope necessary |
### Prohibitions
- **Unused code** — no "just in case" methods, no future-use fields
- **Direct object mutation** — create new objects with spread operators
- **Fallback abuse** — don't hide uncertainty with `?? 'default'`
``` ```
Independent files are assembled into a single prompt at runtime. Change a file's content and the prompt changes; point to different files and the combination changes. Independent files are assembled into a single prompt at runtime. Change a file's content and the prompt changes; point to different files and the combination changes.
@ -410,7 +408,7 @@ The key distinction: existing approaches either decompose *tasks* (what to do) o
**For the engine:** **For the engine:**
- Prompt assembly is deterministic — given the same workflow definition and files, the same prompt is built - Prompt assembly is deterministic — given the same workflow definition and files, the same prompt is built
- Policy placement can be optimized (e.g., placed at top and bottom to counter the "Lost in the Middle" effect) - Policy placement can be optimized (e.g., placed at the end to leverage recency effect for better constraint adherence)
- Concerns can be injected, omitted, or overridden per step without touching other parts - Concerns can be injected, omitted, or overridden per step without touching other parts
## Summary ## Summary

1
src/features/tasks/execute/selectAndExecute.ts
View File

@ -114,6 +114,7 @@ export async function confirmAndCreateWorktree(
info('Generating branch name...'); info('Generating branch name...');
const taskSlug = await summarizeTaskName(task, { cwd }); const taskSlug = await summarizeTaskName(task, { cwd });
info('Creating clone...');
const result = createSharedClone(cwd, { const result = createSharedClone(cwd, {
worktree: true, worktree: true,
taskSlug, taskSlug,

1
src/features/tasks/execute/taskExecution.ts
View File

@ -240,6 +240,7 @@ export async function resolveTaskExecution(
info('Generating branch name...'); info('Generating branch name...');
const taskSlug = await summarizeTaskName(task.content, { cwd: defaultCwd }); const taskSlug = await summarizeTaskName(task.content, { cwd: defaultCwd });
info('Creating clone...');
const result = createSharedClone(defaultCwd, { const result = createSharedClone(defaultCwd, {
worktree: data.worktree, worktree: data.worktree,
branch: data.branch, branch: data.branch,