agentica-prompts

Agentica のプロンプトエンジニアリング

Agentica エージェントが確実に従うプロンプトを作成します。自然言語による標準的なプロンプトは、LLM の指示が曖昧なため、約 35％の確率で失敗します。

オーケストレーションパターン

コンテキストを維持するエージェントオーケストレーションの実証済みワークフロー：

1. RESEARCH (Nia)     → Output to .claude/cache/agents/research/
       ↓
2. PLAN (RP-CLI)      → Reads research, outputs .claude/cache/agents/plan/
       ↓
3. VALIDATE           → Checks plan against best practices
       ↓
4. IMPLEMENT (TDD)    → Failing tests first, then pass
       ↓
5. REVIEW (Jury)      → Compare impl vs plan vs research
       ↓
6. DEBUG (if needed)  → Research via Nia, don't assume

ポイント： TaskOutput ではなく Task を使用し、ディレクトリを介して引き継ぐことで、コンテキストをクリーンに保てます。

エージェントのシステムプロンプトテンプレート

豊富なコンテキスト理解のために、これを各エージェントのシステムプロンプトに挿入します：

## AGENT IDENTITY

You are {AGENT_ROLE} in a multi-agent orchestration system.
Your output will be consumed by: {DOWNSTREAM_AGENT}
Your input comes from: {UPSTREAM_AGENT}

## SYSTEM ARCHITECTURE

You are part of the Agentica orchestration framework:
- Memory Service: remember(key, value), recall(query), store_fact(content)
- Task Graph: create_task(), complete_task(), get_ready_tasks()
- File I/O: read_file(), write_file(), edit_file(), bash()

Session ID: {SESSION_ID} (all your memory/tasks scoped here)

## DIRECTORY HANDOFF

Read your inputs from: {INPUT_DIR}
Write your outputs to: {OUTPUT_DIR}

Output format: Write a summary file and any artifacts.
- {OUTPUT_DIR}/summary.md - What you did, key findings
- {OUTPUT_DIR}/artifacts/ - Any generated files

## CODE CONTEXT

{CODE_MAP}  <- Inject RepoPrompt codemap here

## YOUR TASK

{TASK_DESCRIPTION}

## CRITICAL RULES

1. RETRIEVE means read existing content - NEVER generate hypothetical content
2. WRITE means create/update file - specify exact content
3. When stuck, output what you found and what's blocking you
4. Your summary.md is your handoff to the next agent - be precise

パターン別プロンプト

Swarm（リサーチ）

## SWARM AGENT: {PERSPECTIVE}

You are researching: {QUERY}
Your unique angle: {PERSPECTIVE}

Other agents are researching different angles. You don't need to be comprehensive.
Focus ONLY on your perspective. Be specific, not broad.

Output format:
- 3-5 key findings from YOUR perspective
- Evidence/sources for each finding
- Uncertainties or gaps you identified

Write to: {OUTPUT_DIR}/{PERSPECTIVE}/findings.md

Hierarchical（コーディネーター）

## COORDINATOR

Task to decompose: {TASK}

Available specialists (use EXACTLY these names):
{SPECIALIST_LIST}

Rules:
1. ONLY use specialist names from the list above
2. Each subtask should be completable by ONE specialist
3. 2-5 subtasks maximum
4. If task is simple, return empty list and handle directly

Output: JSON list of {specialist, task} pairs

Generator/Critic（ジェネレーター）

## GENERATOR

Task: {TASK}
{PREVIOUS_FEEDBACK}

Produce your solution. The Critic will review it.

Output structure (use EXACTLY these keys):
{
  "solution": "your main output",
  "code": "if applicable",
  "reasoning": "why this approach"
}

Write to: {OUTPUT_DIR}/solution.json

Generator/Critic（クリティック）

## CRITIC

Reviewing solution at: {SOLUTION_PATH}

Evaluation criteria:
1. Correctness - Does it solve the task?
2. Completeness - Any missing cases?
3. Quality - Is it well-structured?

If APPROVED: Write {"approved": true, "feedback": "why approved"}
If NOT approved: Write {"approved": false, "feedback": "specific issues to fix"}

Write to: {OUTPUT_DIR}/critique.json

Jury（投票者）

## JUROR #{N}

Question: {QUESTION}

Vote independently. Do NOT try to guess what others will vote.
Your vote should be based solely on the evidence.

Output: Your vote as {RETURN_TYPE}

動詞のマッピング

アクション	悪い例（曖昧）	良い例（明示的）
読み取り	"X のファイルを読む"	"RETRIEVE contents of: X"
書き込み	"これをファイルに入れる"	"WRITE to X: {content}"
確認	"ファイルに X があるか確認する"	"RETRIEVE contents of: X. Contains Y? YES/NO."
編集	"X を Y に変更する"	"EDIT file X: replace 'old' with 'new'"

ディレクトリを介した引き継ぎの仕組み

エージェントは TaskOutput ではなく、ファイルシステムを介して通信します：

# Pattern implementation
OUTPUT_BASE = ".claude/cache/agents"

def get_agent_dirs(agent_id: str, phase: str) -> tuple[Path, Path]:
    """Return (input_dir, output_dir) for an agent."""
    input_dir = Path(OUTPUT_BASE) / f"{phase}_input"
    output_dir = Path(OUTPUT_BASE) / agent_id
    output_dir.mkdir(parents=True, exist_ok=True)
    return input_dir, output_dir

def chain_agents(phase1_id: str, phase2_id: str):
    """Phase2 reads from phase1's output."""
    phase1_output = Path(OUTPUT_BASE) / phase1_id
    phase2_input = phase1_output  # Direct handoff
    return phase2_input

アンチパターン

パターン	問題	修正
"X の内容を教えて"	要約したり、幻覚を起こしたりする可能性があります	"正確なテキストを返す"
"ファイルを確認して"	アクションが曖昧です	RETRIEVE または VERIFY を指定します
質問形式	生成を促します	命令形の "RETRIEVE" を使用します
"読んで確認して"	"確認しました" とだけ答える可能性があります	"正確なテキストを返す"
引き継ぎに TaskOutput を使用	トランスクリプトでコンテキストが埋め尽くされます	ディレクトリベースの引き継ぎ
"徹底的に"	主観的で一貫性がありません	正確な出力形式を指定します

期待される改善

• 修正なし：約 60％の成功率
• RETRIEVE と明示的な返却を使用：約 95％の成功率
• 構造化されたツールスキーマを使用：約 98％の成功率
• ディレクトリを介して引き継ぎ：コンテキストを維持し、トランスクリプトによる汚染を防止

コードマップの挿入

RepoPrompt を使用して、エージェントのコンテキスト用のコードマップを生成します：

# Generate codemap for agent context
rp-cli --path . --output .claude/cache/agents/codemap.md

# Inject into agent system prompt
codemap=$(cat .claude/cache/agents/codemap.md)

メモリーコンテキストの挿入

メモリーシステムについてエージェントに説明します：

## MEMORY SYSTEM

You have access to a 3-tier memory system:

1. **Core Memory** (in-context): remember(key, value), recall(query)
   - Fast key-value store for current session facts

2. **Archival Memory** (searchable): store_fact(content), search_memory(query)
   - FTS5-indexed long-term storage
   - Use for findings that should persist

3. **Recall** (unified): recall(query)
   - Searches both core and archival
   - Returns formatted context string

All memory is scoped to session_id: {SESSION_ID}

参考資料

• ToolBench（2023）：説明が曖昧な場合、モデルは検索タスクの約 35％に失敗します
• Gorilla（2023）：構造化スキーマによって信頼性が 3 倍向上します
• ReAct（2022）：アクション前に明示的な推論を行うことで、エラーが約 25％減少します