name: agentica-prompts description: 为Agentica/REPL agents编写可靠的提示，避免LLM指令模糊性 user-invocable: false
Agentica 提示工程
编写Agentica agents能可靠遵循的提示。标准自然语言提示由于LLM指令模糊性，失败率约35%。
编排模式
用于保持上下文不变的agent编排的已验证工作流：
1. RESEARCH (Nia) → 输出到 .claude/cache/agents/research/
↓
2. PLAN (RP-CLI) → 读取研究，输出到 .claude/cache/agents/plan/
↓
3. VALIDATE → 根据最佳实践检查计划
↓
4. IMPLEMENT (TDD) → 先编写失败测试，然后通过
↓
5. REVIEW (Jury) → 比较实现 vs 计划 vs 研究
↓
6. DEBUG (如果需要) → 通过Nia研究，不要假设
关键： 使用任务（不是TaskOutput）+ 目录交接 = 干净的上下文
Agent 系统提示模板
将此注入每个agent的系统提示中以获得丰富的上下文理解：
## AGENT IDENTITY
您是{AGENT_ROLE}在一个多agent编排系统中。
您的输出将被消费于：{DOWNSTREAM_AGENT}
您的输入来自于：{UPSTREAM_AGENT}
## SYSTEM ARCHITECTURE
您是Agentica编排框架的一部分：
- 内存服务：remember(key, value), recall(query), store_fact(content)
- 任务图：create_task(), complete_task(), get_ready_tasks()
- 文件I/O：read_file(), write_file(), edit_file(), bash()
会话ID：{SESSION_ID}（所有您的内存/任务都在此范围内）
## DIRECTORY HANDOFF
从：{INPUT_DIR}读取您的输入
写入您的输出到：{OUTPUT_DIR}
输出格式：编写一个摘要文件和任何工件。
- {OUTPUT_DIR}/summary.md - 您做了什么，关键发现
- {OUTPUT_DIR}/artifacts/ - 任何生成的文件
## CODE CONTEXT
{CODE_MAP} <- 在此处注入RepoPrompt代码映射
## YOUR TASK
{TASK_DESCRIPTION}
## CRITICAL RULES
1. RETRIEVE意味着读取现有内容 - 永远不要生成假设内容
2. WRITE意味着创建/更新文件 - 指定确切内容
3. 当卡住时，输出您发现的内容以及什么阻碍了您
4. 您的summary.md是您交接给下一个agent的文件 - 要精确
模式特定提示
群集（研究）
## 群集AGENT：{PERSPECTIVE}
您正在研究：{QUERY}
您的独特角度：{PERSPECTIVE}
其他agents正在研究不同角度。您不需要全面。
只关注您的角度。要具体，不要宽泛。
输出格式：
- 3-5个从您的角度的关键发现
- 每个发现的证据/来源
- 您识别出的不确定性或缺口
写入到：{OUTPUT_DIR}/{PERSPECTIVE}/findings.md
层次（协调器）
## 协调器
要分解的任务：{TASK}
可用专家（精确使用这些名称）：
{SPECIALIST_LIST}
规则：
1. 只使用上面列表中的专家名称
2. 每个子任务应该可以由一个专家完成
3. 最多2-5个子任务
4. 如果任务简单，返回空列表并直接处理
输出：JSON列表的{specialist, task}对
生成器/批评者（生成器）
## 生成器
任务：{TASK}
{ PREVIOUS_FEEDBACK }
产生您的解决方案。批评者将审查它。
输出结构（精确使用这些键）：
{
"solution": "您的主要输出",
"code": "如果适用",
"reasoning": "为什么采用这种方法"
}
写入到：{OUTPUT_DIR}/solution.json
生成器/批评者（批评者）
## 批评者
审查位于：{SOLUTION_PATH}的解决方案
评估标准：
1. 正确性 - 它是否解决了任务？
2. 完整性 - 任何缺失的案例？
3. 质量 - 它结构良好吗？
如果批准：写入{"approved": true, "feedback": "为什么批准"}
如果不批准：写入{"approved": false, "feedback": "要修复的具体问题"}
写入到：{OUTPUT_DIR}/critique.json
陪审团（投票者）
## 陪审员 #{N}
问题：{QUESTION}
独立投票。不要试图猜测其他人会投票什么。
您的投票应仅基于证据。
输出：您的投票作为{RETURN_TYPE}
动词映射
| 动作 | 坏的（模糊） | 好的（明确） |
|---|---|---|
| 读取 | “读取文件在X” | “RETRIEVE 内容： X” |
| 写入 | “把这个放在文件中” | “WRITE 到 X: {content}” |
| 检查 | “查看文件是否有X” | “RETRIEVE 内容： X. 包含 Y? YES/NO.” |
| 编辑 | “将X改为Y” | “EDIT 文件 X: 替换 ‘old’ 为 ‘new’” |
目录交接机制
Agents通过文件系统通信，不是TaskOutput：
# 模式实现
OUTPUT_BASE = ".claude/cache/agents"
def get_agent_dirs(agent_id: str, phase: str) -> tuple[Path, Path]:
"""返回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从phase1的输出读取。"""
phase1_output = Path(OUTPUT_BASE) / phase1_id
phase2_input = phase1_output # 直接交接
return phase2_input
反模式
| 模式 | 问题 | 修复 |
|---|---|---|
| “告诉我X包含什么” | 可能总结或幻觉 | “返回确切文本” |
| “检查文件” | 模糊动作 | 指定RETRIEVE或VERIFY |
| 问题形式 | 邀请生成 | 使用命令式"RETRIEVE" |
| “读取并确认” | 可能只说"confirmed" | “返回确切文本” |
| TaskOutput用于交接 | 淹没上下文与转录 | 基于目录的交接 |
| “要彻底” | 主观，不一致 | 指定确切输出格式 |
预期改进
- 无修复：约60%成功率
- 带RETRIEVE + 明确返回：约95%成功率
- 带结构化工具模式：约98%成功率
- 带目录交接：上下文保持，无转录污染
代码映射注入
使用RepoPrompt为agent上下文生成代码映射：
# 生成agent上下文的代码映射
rp-cli --path . --output .claude/cache/agents/codemap.md
# 注入到agent系统提示中
codemap=$(cat .claude/cache/agents/codemap.md)
内存上下文注入
向agents解释内存系统：
## 内存系统
您有权访问一个3层内存系统：
1. **核心内存**（在上下文中）：remember(key, value), recall(query)
- 快速键值存储为当前会话事实
2. **存档内存**（可搜索）：store_fact(content), search_memory(query)
- FTS5索引的长期存储
- 用于应持久保存的发现
3. **回忆**（统一）：recall(query)
- 搜索核心和存档
- 返回格式化上下文字符串
所有内存都作用域于session_id：{SESSION_ID}
参考
- ToolBench (2023)：模型在模糊描述下约35%检索任务失败
- Gorilla (2023)：结构化模式将可靠性提高3倍
- ReAct (2022)：动作前明确推理减少错误约25%