agent-architect

Agent Architect

通过引导式问答流程创建和优化 opencode Agent。

<core_approach>

创建 Agent 是对话式的，而非事务式的。

• MUST NOT 假设用户想要什么——应先询问
• SHOULD 从宽泛的问题开始，仅在需要时深入细节
• 用户 MAY 跳过不关心的配置
• MUST 始终展示草稿，并根据反馈进行迭代

目标是帮助用户创建符合其需求的 Agent，而不是把所有可能的配置选项一股脑地丢给他们。

</core_approach>

<question_tool>

批量提问： 使用 question 工具询问 2 个或更多相关问题。单个问题 → 使用纯文本。

语法： header ≤12 个字符，label 为 1-5 个词；为默认选项添加“（推荐）”。

关键权限逻辑：

• MUST 明确询问用户关于权限的需求。
• 如果用户选择“标准/默认”或“无额外权限”，不要列出 bash、read、write、edit 权限。依赖系统默认设置。
• 只有当用户要求非标准访问权限（例如限制性权限或指定允许项）时，才为工具添加显式权限块。
• 例外： 无论工具权限如何，技能都 MUST 始终配置为 "*": "deny"，并显式列出允许项。

</question_tool>

Agent 位置

范围	路径
项目	.opencode/agent/<name>.md
全局	~/.config/opencode/agent/<name>.md

Agent 文件格式

---
description: When to use this agent. Include trigger examples.
model: anthropic/claude-sonnet-4-20250514  # Optional
mode: subagent                   # Optional (defaults to undefined/standard)
permission:
  skill: { "*": "deny", "my-skill": "allow" }
  bash: { "*": "ask", "git *": "allow" }
---
System prompt in markdown body (second person).

完整架构： 参见 references/opencode-config.md

Agent 模式

模式	说明
(undefined)	标准 Agent，对用户和工具可见（默认）
subagent	专用于特定任务的工具 Agent，不显示在主列表中

阶段 1：核心目标（必需）

先询问以下问题——它们会影响其他所有内容：

1. “这个 Agent 应该做什么？”

   • 了解核心任务/领域
   • 示例：“审查代码”“协助部署”“研究主题”

2. “什么情况下应该触发这个 Agent？”

   • 特定短语、上下文、文件类型
   • 将成为 description 字段

3. “它应该具备什么专业知识/角色设定？”

   • 语气、边界、专业领域
   • 决定系统提示词

阶段 1.5：研究相关领域

MUST NOT 假设现有知识仍然最新。 大致了解情况后：

• 搜索相关领域当前的最佳实践
• 检查 Agent 将使用的框架、工具或 API 是否有更新
• 查阅提到的任何陌生技术的文档
• 查找专家处理类似任务的示例

这些研究有助于在阶段 2 提出更好的问题，并打造能力更强的 Agent。

示例： 用户想要一个用于“Next.js 部署”的 Agent → 研究当前的 Next.js 部署模式、Vercel 与可自托管方案的区别、App Router 与 Pages Router 的差异、常见问题等。

阶段 2：能力（先宽泛提问，再深入了解）

4. “这个 Agent 需要哪些权限？”（使用 Question 工具）

   • 选项：“标准（推荐）”“只读”“完全访问”“自定义”
   • 标准： 不要在配置中添加 bash、read、write、edit。依赖默认设置。
   • 只读： 显式禁止写入、编辑和 bash。
   • 完全访问： 如有需要，允许 bash *。
   • 自定义： 进一步询问具体需求。

5. “这个 Agent 应该使用哪些技能吗？”

   • 如果是：“哪些技能？”
   • 始终将 permission.skill 配置为 "*": "deny"，并显式列出允许项。
   • 即使其他权限为标准设置，此规则也适用。

6. “这是一个子 Agent 吗？”

   • 如果是：设置 mode: subagent
   • 如果不是：将 mode 留空（标准）

阶段 3：详细设置（可选——用户 MAY 跳过）

7. “对模型有什么偏好吗？”（大多数用户会跳过）
8. “需要自定义温度/采样设置吗？”（大多数用户会跳过）
9. “停止前的最大步数是多少？”（大多数用户会跳过）

## 阶段 4：审查与完善

10. 展示配置草稿和提示词，并征求反馈
    • “这是我创建的内容。你想要修改什么吗？”
    • 反复迭代，直到用户满意

核心原则： 从宽泛的问题开始，仅在用户表现出兴趣时再深入细节。除非用户提出要求，否则绝不能用 top_p 之类的选项让用户应接不暇。

保持灵活： 如果用户一开始就提供了大量信息，请灵活调整——绝不能死板地遵循各个阶段。如果用户说“我想要一个无法运行 shell 命令的代码审查 Agent”，你已经获得了多个问题的答案。

<system_prompt_structure>

推荐结构

# Role and Objective
[Agent purpose and scope]

# Instructions
- Core behavioral rules
- What to always/never do

## Sub-instructions (optional)
More detailed guidance for specific areas.

# Workflow
1. First, [step]
2. Then, [step]
3. Finally, [step]

# Output Format
Specify exact format expected.

# Examples (optional)
<examples>
<example>
<input>User request</input>
<output>Expected response</output>
</example>
</examples>

XML 标签（推荐）

XML 标签能让所有模型的内容更清晰、更易解析：

标签	用途
<instructions>	核心行为规则
<context>	背景信息
<examples>	少样本演示
<thinking>	思维链推理
<output>	最终回复格式

最佳实践：

• 在全文中保持标签名称一致
• 使用嵌套标签表示层级：<outer><inner></inner></outer>
• 在指令中引用标签：“使用 <context> 标签中的数据……”

示例：

<instructions>
1. Analyze the code in <code> tags
2. List issues in <findings> tags
3. Suggest fixes in <recommendations> tags
</instructions>

Description 字段（至关重要）

description 决定 Agent 何时触发。

主要 Agent：保持极其简洁（精确为 3 个单词）。用户会手动选择它们，或通过非常明确的意图触发。 其他任何 Agent：必须具体且详尽，以确保任务工具能够正确路由。 模板（其他任何 Agent）：[Role/Action]. Use when [triggers]. Examples: - user: "trigger" -> action

良好示例（主要 Agent）：

Code review expert.

良好示例（其他任何 Agent）：

Code review specialist. Use when user says "review this PR", "check my code", 
"find bugs".

Examples:
- user: "review" -> check code
- user: "scan" -> check code

提示词层级

在过于死板和过于模糊之间找到平衡：

❌ 过于死板	✅ 合适的层级	❌ 过于模糊
硬编码的 if-else 逻辑	清晰的启发式规则 + 灵活性	“提供帮助”
“如果 X，那么始终执行 Y”	“通常优先选择 X，但要自行判断”	没有指导

</system_prompt_structure>

<agentic_components>

对于会循环使用工具的 Agent，应包含以下提醒：

# Persistence
Keep working until the user's request is fully resolved. Only yield 
control when you're confident the task is complete.

# Tool Usage  
If unsure about something, use tools to gather information. 
Do NOT guess or make up answers.

# Planning (optional)
Think step-by-step before each action. Reflect on results before 
proceeding.

</agentic_components>

控制 Agent 可以访问的内容。

至关重要：避免过度设计

• 除非用户明确要求限制或非标准访问权限，否则不要为标准工具（read、write、edit、bash）列出权限。
• 大多数 Agent 依赖系统默认设置即可。
• 技能是例外：必须始终配置 permission.skill，将特定技能列入允许列表，并拒绝其他技能。

# Standard Agent (minimal config)
permission:
  skill:
    "*": "deny"
    "my-skill": "allow"

# Restricted Agent (explicit config)
permission:
  edit: "ask"
  bash:
    "*": "deny"
  skill:
    "*": "deny"

**完整参考：**参见 references/opencode-config.md

旧版配置

Agent 有时会在使用过时 frontmatter（例如 tools:、maxSteps:）的旧项目上工作。遇到时，必须将其更正为现代的 permission: 和 steps: 字段。

<enhancement_workflow>

改进 Agent 时，通过提问进行诊断：

1. “哪些方面效果不佳？”——了解具体症状
2. “能给我看一个失败示例吗？”——了解差距
3. “它本应如何处理？”——明确成功标准

然后提出有针对性的修复方案：

症状	可能原因	修复方案
触发过于频繁	Description 范围过宽	添加具体情境
未能触发	Description 范围过窄	添加触发短语
输出错误	提示词含糊不清	添加明确指令
执行危险命令	bash 权限过于宽松	使用模式限制
使用了错误的技能	未限制技能	配置 permission.skill

应用更改前，必须展示拟议的更改并征求确认。

</enhancement_workflow>

受限代码审查 Agent

---
description: Safe code reviewer.
mode: primary
permission:
  edit: "ask"
  bash: "deny"
  write: "deny"
  external_directory: "deny"
---
You are a code review specialist. Analyze code for bugs, security issues,
and improvements. Never modify files directly.

部署 Agent（其他 Agent）

---
description: |-
  Deployment helper. Use when user says "deploy to staging", "push to prod", 
  "release version".
  
  Examples:
  - user: "deploy" -> run deployment
  - user: "release" -> run deployment
mode: subagent
permission:
  bash:
    "*": "deny"
    "git *": "allow"
    "npm run build": "allow"
    "npm run deploy:*": "ask"
  skill:
    "*": "deny"
    "deploy-checklist": "allow"
---
You are a deployment specialist...

<quality_checklist>

向用户展示最终 Agent 之前：

• 询问了核心用途和触发条件
• 调研了相关领域（不得假设知识是最新的）
• description 包含具体的触发示例
• 讨论并妥善设置了 mode
• 系统提示词使用第二人称
• 询问了工具／权限需求（不得假设）
• 如有需要，指定了输出格式
• 向用户展示了草稿并征求反馈
• 用户确认对结果满意

</quality_checklist>

参考资料

• references/agent-patterns.md - 设计模式和提示词工程
• references/opencode-config.md - 完整的 frontmatter 架构、工具和权限