agentica-prompts

Agentica 提示词工程

编写能让 Agentica Agent 可靠遵循的提示词。由于大模型的指令存在歧义，标准自然语言提示词约有 35% 的失败率。

编排模式

经验证的工作流，可在 Agent 编排过程中保留上下文：

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

要点： 使用 Task（而非 TaskOutput）并通过目录交接，实现干净的上下文

Agent 系统提示词模板

将此模板注入每个 Agent 的系统提示词，以便其充分理解上下文：

## 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 以下内容：X”
写入	“把这个放进文件里”	“WRITE 到 X：{content}”
检查	“看看文件是否包含 X”	“RETRIEVE 以下内容：X。是否包含 Y？YES/NO。”
编辑	“将 X 改为 Y”	“EDIT 文件 X：将 ‘old’ 替换为 ‘new’”

目录交接机制

Agent 通过文件系统通信，而不是使用 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 为 Agent 生成代码映射，以提供上下文：

# 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)

注入记忆上下文

向 Agent 说明记忆系统：

## 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%