takt-facet-builder

TAKT Facet Builder

TAKTの5種類のファセットファイルを個別に作成・編集する。

前提 takt バージョン: v0.47.0

参照資料

ファセット作成時は references/takt/builtins/ja/ の資料を参照する。

資料	パス	用途
スタイルガイド総合	references/takt/builtins/ja/STYLE_GUIDE.md	各ファセットの位置づけ
ペルソナガイド	references/takt/builtins/ja/PERSONA_STYLE_GUIDE.md	ペルソナ記述規約
ポリシーガイド	references/takt/builtins/ja/POLICY_STYLE_GUIDE.md	ポリシー記述規約
インストラクションガイド	references/takt/builtins/ja/INSTRUCTION_STYLE_GUIDE.md	インストラクション記述規約
出力契約ガイド	references/takt/builtins/ja/OUTPUT_CONTRACT_STYLE_GUIDE.md	出力契約記述規約
Faceted Prompting	references/takt/docs/faceted-prompting.ja.md	5ファセット設計の理論
ビルトインファセット	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	既存ファセット例

注意: references/takt/builtins/{ja,en}/templates/ は v0.43.0 でも実在する。雛形として参照してよいが、実際の命名・責務分割・文体はビルトインファセットを source of truth として合わせる。

重要: ファセット作成前に該当するスタイルガイドを必ず読む。

ワークフロー

Step 1: ファセット種別の判定

ユーザーの要件から、作成すべきファセット種別を判定する。

この内容は…
├── 特定エージェントのidentity・専門知識 → Persona
├── 複数エージェントが共有する行動規範 → Policy
├── ステップ固有の実行手順 → Instruction
├── 判断の前提となる参照情報 → Knowledge
└── エージェント出力の構造定義 → Output Contract

ファセット	配置先	対象	キー判断
Persona	system prompt	1エージェント	「この知識はこのエージェント固有か？」
Policy	user message内	複数エージェント	「複数エージェントが同じルールに従うか？」
Instruction	Phase 1 message	1ステップ	「この手順はこのステップ固有か？」
Knowledge	user message内	1+エージェント	「判断の前提となる参照情報か？」
Output Contract	Phase 2 message	1レポート	「後続が{report:filename}で参照するか？」

Step 2: 检查内置项

检查同类内置 Facet，并判断是否可以复用。

Facet	内置示例
Persona	coder, planner, architect-planner, architecture-reviewer, qa-reviewer, supervisor, security-reviewer, frontend-reviewer, cqrs-es-reviewer, pure-reviewer, testing-reviewer, terraform-reviewer, terraform-coder, dual-supervisor, research-analyzer, research-digger, research-planner, research-supervisor, conductor, pr-commenter, test-planner, ai-antipattern-reviewer, coding-reviewer, findings-manager, melchior, balthasar, casper
Policy	coding, review, testing, qa, ai-antipattern, design-fidelity, design-planning, task-decomposition, screen-api, existing-system-respect, research, terraform
Instruction	plan, plan-investigate, plan-test, implement, implement-after-tests, implement-test, implement-terraform, write-tests-first, team-leader-implement, dual-team-leader-implement, plan-maintenance, write-tests-maintenance, implement-maintenance, fix-maintenance, supervise-maintenance, review-coding, review-arch, review-qa, review-security, review-frontend, review-cqrs-es, review-pure, review-test, review-terraform, supervise, fix, fix-supervisor, arbitrate, architect, ai-antipattern-review, ai-antipattern-fix, loop-monitor-ai-antipattern-fix, loop-monitor-reviewers-fix, findings-manager, research-plan, research-dig, research-analyze, research-supervise, gather-review, architecture-audit-plan, architecture-audit-review, architecture-audit-supervise, architecture-audit-team-leader, audit-security-plan, audit-security-review, audit-security-supervise, audit-security-team-leader, e2e-audit-plan, e2e-audit-review, e2e-audit-supervise, e2e-audit-team-leader, e2e-coverage-implement, e2e-coverage-plan, e2e-coverage-supervise, unit-audit-plan, unit-audit-review, unit-audit-supervise, unit-audit-team-leader
Knowledge	architecture, backend, cqrs-es, frontend, security, task-decomposition, takt, terraform-aws, e2e-testing, react, unit-testing, existing-system, research, research-comparative
Output Contract	plan, architecture-design, architecture-review, ai-antipattern-review, qa-review, security-review, frontend-review, cqrs-es-review, pure-review, testing-review, terraform-review, coding-review, findings-manager, ai-antipattern-review-finding-contract, architecture-review-finding-contract, coding-review-finding-contract, cqrs-es-review-finding-contract, frontend-review-finding-contract, pure-review-finding-contract, qa-review-finding-contract, security-review-finding-contract, terraform-review-finding-contract, testing-review-finding-contract, summary, validation, coder-scope, coder-decisions, maintenance-scope, review-gather, research-report, test-plan, test-report, plan-frontend, architecture-audit-plan, architecture-audit, audit-security, e2e-audit-plan, e2e-audit, e2e-coverage-plan, unit-audit-plan, unit-audit, supervisor-validation

v0.46.0 的变更：删除 requirements-reviewer Persona、review-requirements instruction 和 requirements-review output contract。改为使用 pure-reviewer（review-pure instruction + pure-review output contract）。pure-reviewer 不局限于特定专业领域，是一名只判断“现在是否可以合并”的通用审查者。

v0.47.0 的变更：新增支持 Finding Contract 的 Facet。

• Persona：findings-manager（负责核对和判定 Finding Contract 的专用 Persona）
• Instruction：findings-manager（面向 findings-manager Persona 的指令）
• Output Contract：findings-manager（findings-manager 输出结构）、*-finding-contract 系列（ai-antipattern-review-finding-contract, architecture-review-finding-contract, coding-review-finding-contract, cqrs-es-review-finding-contract, frontend-review-finding-contract, pure-review-finding-contract, qa-review-finding-contract, security-review-finding-contract, terraform-review-finding-contract, testing-review-finding-contract）。对于附带 Finding Contract 的审查，使用 *-finding-contract 系列替代常规 output contract。

复用判断：如果内置项足以满足需求，则不要创建自定义 Facet。

Step 3: 选择并创建模板

Persona

参考：references/takt/builtins/ja/facets/personas/ 中的现有 Facet

模板	用途	示例
simple.md	无领域知识	coder, planner
expert.md	有领域知识	architecture-reviewer
character.md	独特的人格与语气	melchior, balthasar, casper

# {エージェント名}

{1-2文のロール定義。「あなたは〜です。」で始める}

## 役割の境界

**やること:**
- ...

**やらないこと:**
- ...（担当エージェント名を明記）

## 行動姿勢

- ...（3-8項目）

## ドメイン知識（expertのみ）

### {観点}
...

建议长度：simple 30-50 行（上限 100 行），expert 50-300 行（上限 550 行）

禁止事项：

• 照搬策略的详细规则（代码示例、表格）（一行的行为准则可以）
• 工作流专属概念（步骤名称、报告文件名）
• 工具专属路径（如 .takt/runs/）
• 执行步骤

Policy

参考：references/takt/builtins/ja/facets/policies/ 中的现有 Facet

# {ポリシー名}

{1文の目的説明}

## 原則

| 原則 | 基準 |
|------|------|
| ... | ... |

## {ルールカテゴリ1}

{テーブル、コード例、箇条書きを自由に組み合わせ}

建议长度：60-250 行（上限 300 行）

禁止事项：

• 特定 Agent 专属知识
• 工作流专属概念、工具专属路径
• 执行步骤

Instruction

参考：references/takt/builtins/ja/facets/instructions/ 中的现有 Facet

{目的宣言。1-2行、命令形}

**注意:** {条件付き注意事項（該当する場合）}

**やること:**
1. {手順1}
2. {手順2}
3. {手順3}

**必須出力（見出しを含める）**
## {出力セクション1}
- {内容}
## {出力セクション2}
- {内容}

建议长度：审查 sub-step 5-12 行，计划与修正 10-20 行，实现与验证 30-50 行

禁止事项：

• Persona 的内容（专业知识、行为态度）
• Policy 的内容（共享编码原则）
• 手动编写自动注入的变量（{task}, {previous_response}）
• 直接引用其他步骤名称

模板变量（可用）：

• {iteration}, {max_steps}, {step_iteration}
• {report_dir}, {report:filename}, {cycle_count}

Knowledge

参考：references/takt/builtins/ja/facets/knowledge/ 中的现有 Facet

# {ドメイン名}知識

## {トピック1}

{概要。1-2文}

| 基準 | 判定 |
|------|------|
| ... | ... |

### {サブトピック}

{コード例で具体的に}

## {トピック2}

| パターン | 例 | 問題 |
|---------|-----|------|
| ... | `{コード}` | ... |

検証アプローチ:
1. {手順}

特点：描述性（“现状如何”），为 Policy 提供“WHY”。

Output Contract

参考：references/takt/builtins/ja/facets/output-contracts/ 中的现有 Facet

```markdown
# {レポートタイトル}

## 結果: APPROVE / REJECT

## サマリー
{1-2文で結果を要約}

## 詳細
| 観点 | 結果 | 備考 |
|------|------|------|
```

**認知負荷軽減ルール:**
- APPROVE → サマリーのみ（5行以内）
- REJECT → 問題点を表形式で（30行以内）

建议长度：10-25 行（上限 30 行，不包括减轻认知负担的规则）

状态模式：APPROVE / REJECT（二值）、APPROVE / IMPROVE / REJECT（三值）、完了（固定值）

审查输出契约的结构（v0.30.0 起）：

• 为每条指摘添加 family_tag 列（用于对指摘进行分类）
• 章节结构：new（新增）→ persists（持续存在）→ resolved（已解决）→ reopened（重新开启）

禁止事项：

• 执行步骤（属于 Instruction 的职责）
• 详细判断标准（属于 Persona / Instruction 的职责）

Step 4: 应用通用规则

确认所有 Facet 通用的规则。

规则	内容
标题深度	最多到 ###。不能使用 #### 或更深层级
代码示例	成对提供正确示例/错误示例。使用 // REJECT // OK 注释
文体	Persona、Policy、Knowledge：常体。Instruction：敬体（命令语气）
文件命名	{name}.md，以连字符分隔，使用英文小写
位置	~/.takt/{facet-type}/ 或项目专属位置

Step 5: 验证

检查创建的 Facet 的质量。

所有 Facet 通用：

• 是否没有 #### 或更深层级的嵌套
• 是否遵循文件命名规范
• 是否未超过长度上限

Persona：

• 角色定义是否为 1-2 句
• “负责做什么”“不负责做什么”中是否包含负责的 Agent 名称
• 是否没有混入 Policy 的详细规则
• 是否没有工作流专属概念

Policy：

• 目的说明是否为 1 句
• 是否包含原则表格
• 是否适用于多个 Agent

Instruction：

• 开头是否使用命令形式
• 是否没有手动编写自动注入的变量
• 是否没有混入 Persona / Policy 的内容

Knowledge：

• 是否采用描述性（陈述性）文体
• 是否通过表格和代码示例提供具体内容

Output Contract：

• 是否用 ```markdown 代码块包围
• 审查类内容是否包含状态和减轻认知负担的规则
• 文件名中是否没有编号前缀

验证

创建或编辑的文件可以通过 validate-takt-files.sh 进行机械验证：

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

验证项目：

• 工作流 YAML：必填字段（name/initial_step/steps）、initial_step 的 step 引用、Facet 文件引用是否存在
• Facet .md：空文件检查、persona/policy/knowledge 必须包含 # 标题、instruction/output-contract 必须包含内容

可以使用选项 --workflows / --facets 筛选目标。