docs: add research-backed prompt design and developer guides
- Add research-backed-prompt-design.md with Stanford/Anthropic patterns - Add openagent.md documentation with workflow and delegation details - Add developer guides for slash commands and context system - Document position sensitivity, nesting limits, and instruction ratios - Include examples and best practices for prompt optimization
This commit is contained in:
darrenhinde
parent
e06833015f
commit
c0ea1c064c
4 changed files with 823 additions and 0 deletions
125
dev/ai-tools/opencode/how-context-works.md
Normal file
125
dev/ai-tools/opencode/how-context-works.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# OpenCode File Structure & Reference Guide
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
### Global Config (`~/.config/opencode/`)
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.config/opencode/
|
||||||
|
├── opencode.json # Global config
|
||||||
|
├── AGENTS.md # Auto-loaded instructions
|
||||||
|
├── CLAUDE.md # Auto-loaded instructions
|
||||||
|
├── agent/ # Custom agents
|
||||||
|
│ ├── my-agent.md
|
||||||
|
│ └── category/
|
||||||
|
│ └── nested-agent.md
|
||||||
|
├── command/ # Custom commands
|
||||||
|
│ └── my-command.md
|
||||||
|
└── plugin/ # Custom plugins
|
||||||
|
└── my-plugin.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Local Repo (`.opencode/`)
|
||||||
|
|
||||||
|
```
|
||||||
|
your-repo/
|
||||||
|
├── opencode.json # Repo config
|
||||||
|
├── .opencode/
|
||||||
|
│ ├── AGENTS.md # Auto-loaded instructions
|
||||||
|
│ ├── agent/ # Project-specific agents
|
||||||
|
│ │ └── my-agent.md
|
||||||
|
│ ├── command/ # Project-specific commands
|
||||||
|
│ │ └── my-command.md
|
||||||
|
│ └── plugin/ # Project-specific plugins
|
||||||
|
│ └── my-plugin.ts
|
||||||
|
└── src/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Auto-Loaded Files
|
||||||
|
|
||||||
|
**Instruction files** (loaded automatically as system prompts):
|
||||||
|
- `AGENTS.md` - Custom instructions (global or local)
|
||||||
|
- `CLAUDE.md` - Legacy Claude instructions
|
||||||
|
- `CONTEXT.md` - Deprecated, but still works
|
||||||
|
|
||||||
|
**Config files** (merged in order):
|
||||||
|
1. `~/.config/opencode/opencode.json` (global)
|
||||||
|
2. `opencode.json` files from repo root up to current directory
|
||||||
|
3. Files from `.opencode/` folders in hierarchy
|
||||||
|
|
||||||
|
## Supported Subfolders
|
||||||
|
|
||||||
|
| Folder | Files | Purpose |
|
||||||
|
|--------|-------|---------|
|
||||||
|
| `agent/` | `*.md` | Custom agents with system prompts |
|
||||||
|
| `command/` | `*.md` | Custom slash commands |
|
||||||
|
| `plugin/` | `*.ts`, `*.js` | Custom tools and extensions |
|
||||||
|
|
||||||
|
**⚠️ Use singular names only:** `agent/`, NOT `agents/`
|
||||||
|
|
||||||
|
## File References with `@` Symbol
|
||||||
|
|
||||||
|
**In commands and templates:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Relative to repo root
|
||||||
|
@README.md
|
||||||
|
@src/main.ts
|
||||||
|
|
||||||
|
# Home directory
|
||||||
|
@~/my-file.txt
|
||||||
|
|
||||||
|
# Absolute path
|
||||||
|
@/absolute/path/file.txt
|
||||||
|
|
||||||
|
# If file doesn't exist, looks for agent
|
||||||
|
@my-agent
|
||||||
|
```
|
||||||
|
|
||||||
|
**Resolution order:**
|
||||||
|
1. Check if starts with `~/` → resolve to home directory
|
||||||
|
2. Check if absolute path → use as-is
|
||||||
|
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
||||||
|
4. If not found → look for agent with that name
|
||||||
|
|
||||||
|
## Custom Instruction Files
|
||||||
|
|
||||||
|
**For arbitrary paths, use `instructions` field:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"instructions": [
|
||||||
|
"~/opencode/context/my-context.md",
|
||||||
|
"docs/**/*.md",
|
||||||
|
".opencode/context/**/*.md"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Paths can be:**
|
||||||
|
- Absolute: `/path/to/file.md`
|
||||||
|
- Home relative: `~/path/to/file.md`
|
||||||
|
- Repo relative: `docs/instructions.md`
|
||||||
|
- Glob patterns: `**/*.md`
|
||||||
|
|
||||||
|
## Config Merging
|
||||||
|
|
||||||
|
**Configs merge with priority** (later overrides earlier):
|
||||||
|
1. Global config (`~/.config/opencode/`)
|
||||||
|
2. Repo root configs (from root up)
|
||||||
|
3. Custom config directories (`.opencode/` folders)
|
||||||
|
4. Environment variables (`OPENCODE_CONFIG`)
|
||||||
|
|
||||||
|
**Agents, commands, and plugins** from all locations are merged together.
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| What | Where | How |
|
||||||
|
|------|-------|-----|
|
||||||
|
| Global agent | `~/.config/opencode/agent/name.md` | Auto-loaded |
|
||||||
|
| Local agent | `.opencode/agent/name.md` | Auto-loaded |
|
||||||
|
| Global command | `~/.config/opencode/command/name.md` | Auto-loaded |
|
||||||
|
| Local command | `.opencode/command/name.md` | Auto-loaded |
|
||||||
|
| Global instructions | `~/.config/opencode/AGENTS.md` | Auto-loaded |
|
||||||
|
| Local instructions | `.opencode/AGENTS.md` or `AGENTS.md` | Auto-loaded |
|
||||||
|
| Custom files | Anywhere | Use `instructions` config or `@` symbol |
|
||||||
373
dev/ai-tools/opencode/slash-commands-and-subagents.md
Normal file
373
dev/ai-tools/opencode/slash-commands-and-subagents.md
Normal file
|
|
@ -0,0 +1,373 @@
|
||||||
|
# Clear Guidelines: Main Agent → Slash Command → Subagent
|
||||||
|
|
||||||
|
## The Complete Pattern
|
||||||
|
|
||||||
|
### Step 1: Create Your Command (Template Only)
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# .opencode/command/security/scan.md
|
||||||
|
---
|
||||||
|
description: "Security vulnerability scan"
|
||||||
|
# NO agent field - let caller decide
|
||||||
|
---
|
||||||
|
|
||||||
|
Perform security scan on: $ARGUMENTS
|
||||||
|
|
||||||
|
@$1
|
||||||
|
@AGENTS.md
|
||||||
|
@.cursorrules
|
||||||
|
|
||||||
|
Check for:
|
||||||
|
- SQL injection
|
||||||
|
- XSS vulnerabilities
|
||||||
|
- Authentication issues
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Create Your Subagent
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# .opencode/agent/security/scanner.md
|
||||||
|
---
|
||||||
|
mode: "subagent"
|
||||||
|
description: "Security vulnerability detection specialist"
|
||||||
|
tools:
|
||||||
|
read: true
|
||||||
|
grep: true
|
||||||
|
---
|
||||||
|
|
||||||
|
You are a security expert. Scan code for vulnerabilities.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Document in AGENTS.md (CRITICAL)
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
## Slash Commands for Subagents
|
||||||
|
|
||||||
|
When you need specialized workflows, use the Task tool with slash commands:
|
||||||
|
|
||||||
|
### Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="[subagent-name]",
|
||||||
|
prompt="/command-name arguments"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available Commands
|
||||||
|
|
||||||
|
**Security:**
|
||||||
|
- `/security/scan [file]`
|
||||||
|
- Use: `Task(subagent_type="security/scanner", prompt="/security/scan auth.ts")`
|
||||||
|
- Performs comprehensive security analysis
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- `/test/generate [file]`
|
||||||
|
- Use: `Task(subagent_type="testing/generator", prompt="/test/generate service.ts")`
|
||||||
|
- Generates unit tests with project patterns
|
||||||
|
|
||||||
|
**Refactoring:**
|
||||||
|
- `/refactor/modernize [file] [context]`
|
||||||
|
- Use: `Task(subagent_type="refactor/modernizer", prompt="/refactor/modernize old.js 'use async/await'")`
|
||||||
|
- Updates legacy code to modern standards
|
||||||
|
|
||||||
|
### When to Use
|
||||||
|
|
||||||
|
- User asks for security audit → Use `/security/scan`
|
||||||
|
- After writing code → Use `/test/generate`
|
||||||
|
- Legacy code mentioned → Use `/refactor/modernize`
|
||||||
|
```
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
```
|
||||||
|
User: "Check auth.ts for security issues"
|
||||||
|
↓
|
||||||
|
Main Agent reads AGENTS.md
|
||||||
|
↓
|
||||||
|
Sees: /security/scan pattern
|
||||||
|
↓
|
||||||
|
Main Agent calls:
|
||||||
|
Task(
|
||||||
|
subagent_type="security/scanner",
|
||||||
|
prompt="/security/scan auth.ts"
|
||||||
|
)
|
||||||
|
↓
|
||||||
|
System processes /security/scan command:
|
||||||
|
- Loads template from command/security/scan.md
|
||||||
|
- Replaces $ARGUMENTS with "auth.ts"
|
||||||
|
- Attaches @auth.ts file
|
||||||
|
- Attaches @AGENTS.md, @.cursorrules
|
||||||
|
↓
|
||||||
|
Subagent "security/scanner" receives:
|
||||||
|
- Full template text
|
||||||
|
- All attached files as context
|
||||||
|
↓
|
||||||
|
Subagent executes → Returns result → Main agent responds to user
|
||||||
|
```
|
||||||
|
|
||||||
|
## Complete Working Example
|
||||||
|
|
||||||
|
### Files Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.opencode/
|
||||||
|
├── agent/
|
||||||
|
│ ├── security/
|
||||||
|
│ │ └── scanner.md
|
||||||
|
│ ├── testing/
|
||||||
|
│ │ └── generator.md
|
||||||
|
│ └── refactor/
|
||||||
|
│ └── modernizer.md
|
||||||
|
├── command/
|
||||||
|
│ ├── security/
|
||||||
|
│ │ └── scan.md
|
||||||
|
│ ├── test/
|
||||||
|
│ │ └── generate.md
|
||||||
|
│ └── refactor/
|
||||||
|
│ └── modernize.md
|
||||||
|
└── AGENTS.md ← Documents the patterns
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1. Command Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# .opencode/command/test/generate.md
|
||||||
|
---
|
||||||
|
description: "Generate comprehensive unit tests"
|
||||||
|
---
|
||||||
|
|
||||||
|
Generate unit tests for: $ARGUMENTS
|
||||||
|
|
||||||
|
Target file:
|
||||||
|
@$1
|
||||||
|
|
||||||
|
Existing test patterns:
|
||||||
|
!`find $(dirname $1) -name "*.test.*" | head -3`
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- Test all public methods
|
||||||
|
- Include edge cases
|
||||||
|
- Mock external dependencies
|
||||||
|
- Follow project conventions from @AGENTS.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Subagent
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# .opencode/agent/testing/generator.md
|
||||||
|
---
|
||||||
|
mode: "subagent"
|
||||||
|
description: "Use AFTER writing new code to generate comprehensive tests"
|
||||||
|
tools:
|
||||||
|
read: true
|
||||||
|
write: true
|
||||||
|
grep: true
|
||||||
|
---
|
||||||
|
|
||||||
|
You generate unit tests by:
|
||||||
|
1. Analyzing the implementation
|
||||||
|
2. Studying existing test patterns
|
||||||
|
3. Creating thorough test coverage
|
||||||
|
4. Following project conventions
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. AGENTS.md Documentation
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
## Build/Test Commands
|
||||||
|
- Run tests: `npm test`
|
||||||
|
- Single test: `npm test -- path/to/test.ts`
|
||||||
|
|
||||||
|
## Code Standards
|
||||||
|
- TypeScript strict mode
|
||||||
|
- camelCase for functions
|
||||||
|
- PascalCase for classes
|
||||||
|
|
||||||
|
## Slash Commands with Subagents
|
||||||
|
|
||||||
|
Use Task tool to invoke specialized workflows:
|
||||||
|
|
||||||
|
### Testing Workflow
|
||||||
|
|
||||||
|
After writing new code, generate tests:
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="testing/generator",
|
||||||
|
prompt="/test/generate src/services/payment.ts"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Security Workflow
|
||||||
|
|
||||||
|
Before deploying authentication code:
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="security/scanner",
|
||||||
|
prompt="/security/scan src/auth/*.ts"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Refactoring Workflow
|
||||||
|
|
||||||
|
When updating legacy code:
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="refactor/modernizer",
|
||||||
|
prompt="/refactor/modernize src/legacy/util.js 'convert to TypeScript with async/await'"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern Summary
|
||||||
|
|
||||||
|
1. Identify the workflow need
|
||||||
|
2. Use Task tool with appropriate subagent_type
|
||||||
|
3. Pass slash command as the prompt
|
||||||
|
4. Command loads template + context
|
||||||
|
5. Subagent executes with full context
|
||||||
|
```
|
||||||
|
|
||||||
|
## Real Conversation Example
|
||||||
|
|
||||||
|
```
|
||||||
|
User: "I just wrote a new payment service. Can you add tests?"
|
||||||
|
|
||||||
|
Main Agent (reads AGENTS.md, sees testing workflow):
|
||||||
|
"I'll generate comprehensive tests for the payment service."
|
||||||
|
|
||||||
|
[Calls Task tool:]
|
||||||
|
Task(
|
||||||
|
description="Generate payment service tests",
|
||||||
|
subagent_type="testing/generator",
|
||||||
|
prompt="/test/generate src/services/payment.ts"
|
||||||
|
)
|
||||||
|
|
||||||
|
Command System:
|
||||||
|
- Loads .opencode/command/test/generate.md
|
||||||
|
- Replaces $1 with "src/services/payment.ts"
|
||||||
|
- Attaches payment.ts file
|
||||||
|
- Finds existing test files in same directory
|
||||||
|
- Attaches AGENTS.md for conventions
|
||||||
|
|
||||||
|
Subagent (testing/generator):
|
||||||
|
- Receives full context
|
||||||
|
- Analyzes payment.ts implementation
|
||||||
|
- Studies existing test patterns
|
||||||
|
- Generates comprehensive tests
|
||||||
|
- Returns result
|
||||||
|
|
||||||
|
Main Agent:
|
||||||
|
"✅ Generated comprehensive tests in src/services/payment.test.ts
|
||||||
|
- Tests all public methods
|
||||||
|
- Includes edge cases for failed payments
|
||||||
|
- Mocks payment gateway
|
||||||
|
- Follows project test conventions"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Template for Your AGENTS.md
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
## Project Commands
|
||||||
|
[Your build/test commands]
|
||||||
|
|
||||||
|
## Code Standards
|
||||||
|
[Your standards]
|
||||||
|
|
||||||
|
## Automated Workflows
|
||||||
|
|
||||||
|
I have specialized workflows accessible via slash commands.
|
||||||
|
Use the Task tool to invoke them with appropriate subagents.
|
||||||
|
|
||||||
|
### Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="[subagent-name]",
|
||||||
|
prompt="/[command-name] [arguments]"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Security Analysis
|
||||||
|
|
||||||
|
**When:** Before deploying auth/payment code
|
||||||
|
**Command:** `/security/scan [file]`
|
||||||
|
**Subagent:** `security/scanner`
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="security/scanner",
|
||||||
|
prompt="/security/scan src/auth/jwt.ts"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Generation
|
||||||
|
|
||||||
|
**When:** After writing new code
|
||||||
|
**Command:** `/test/generate [file]`
|
||||||
|
**Subagent:** `testing/generator`
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="testing/generator",
|
||||||
|
prompt="/test/generate src/services/payment.ts"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Code Modernization
|
||||||
|
|
||||||
|
**When:** Refactoring legacy code
|
||||||
|
**Command:** `/refactor/modernize [file] [instructions]`
|
||||||
|
**Subagent:** `refactor/modernizer`
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Task(
|
||||||
|
subagent_type="refactor/modernizer",
|
||||||
|
prompt="/refactor/modernize src/old-api.js 'convert to TypeScript with async/await'"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Reference
|
||||||
|
|
||||||
|
| Task | Command | Subagent |
|
||||||
|
|------|---------|----------|
|
||||||
|
| Security scan | `/security/scan` | `security/scanner` |
|
||||||
|
| Generate tests | `/test/generate` | `testing/generator` |
|
||||||
|
| Modernize code | `/refactor/modernize` | `refactor/modernizer` |
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Commands are templates that attach context files automatically
|
||||||
|
- Subagents receive full context and execute specialized workflows
|
||||||
|
- Always specify subagent_type when using Task tool with slash commands
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Points
|
||||||
|
|
||||||
|
1. **Commands are templates** - They don't execute anything, they just format context
|
||||||
|
2. **Subagents do the work** - They receive the processed template + attached files
|
||||||
|
3. **AGENTS.md is the bridge** - It tells main agent HOW to connect commands to subagents
|
||||||
|
4. **Pattern is always:** `Task(subagent_type="X", prompt="/command args")`
|
||||||
|
5. **Main agent decides** which subagent to use based on your documentation
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
- ✅ Create command templates (no agent field)
|
||||||
|
- ✅ Create specialized subagents (mode: "subagent")
|
||||||
|
- ✅ Document pattern in AGENTS.md with examples
|
||||||
|
- ✅ Include "When to use" triggers
|
||||||
|
- ✅ Show exact Task tool syntax
|
||||||
|
- ✅ Test with: "Can you [task description]"
|
||||||
|
|
||||||
|
That's it! Main agent reads AGENTS.md, sees the patterns, and knows how to invoke slash commands through subagents.
|
||||||
|
|
@ -1139,4 +1139,26 @@ OpenAgent is configured in `.opencode/agent/openagent.md`. You can customize:
|
||||||
- Test failure protocol
|
- Test failure protocol
|
||||||
- And more!
|
- And more!
|
||||||
|
|
||||||
|
### Recent Optimizations (Nov 2025)
|
||||||
|
|
||||||
|
OpenAgent has been optimized based on research-backed prompt engineering patterns:
|
||||||
|
|
||||||
|
✅ **Critical rules positioned early** - Safety rules now appear in the first 15% of the prompt (10.7% position)
|
||||||
|
✅ **Minimal nesting complexity** - Flattened XML structure to only 2 levels for maximum clarity
|
||||||
|
✅ **Modular design** - Session management and context discovery extracted to reference files
|
||||||
|
✅ **Explicit prioritization** - 3-tier priority system for conflict resolution
|
||||||
|
✅ **Single source of truth** - Critical rules defined once and referenced throughout
|
||||||
|
|
||||||
|
**Effectiveness improvements are model- and task-specific.** These patterns are validated by Stanford/Anthropic research but actual performance gains vary based on your specific use case.
|
||||||
|
|
||||||
|
### Required Context Files
|
||||||
|
|
||||||
|
OpenAgent requires these context files to function properly:
|
||||||
|
- `.opencode/context/core/session-management.md` - Session lifecycle and cleanup policies
|
||||||
|
- `.opencode/context/core/context-discovery.md` - Dynamic context loading and discovery
|
||||||
|
- `.opencode/context/core/context-management.md` - Overall context management strategy
|
||||||
|
- `.opencode/context/core/essential-patterns.md` - Core coding patterns and best practices
|
||||||
|
|
||||||
|
These files are automatically loaded when OpenAgent starts.
|
||||||
|
|
||||||
Happy building! 🚀
|
Happy building! 🚀
|
||||||
|
|
|
||||||
303
docs/agents/research-backed-prompt-design.md
Normal file
303
docs/agents/research-backed-prompt-design.md
Normal file
|
|
@ -0,0 +1,303 @@
|
||||||
|
# Updated Agent Prompt Design Flow: Empirically Validated Framework
|
||||||
|
|
||||||
|
**Key Takeaway:**
|
||||||
|
The overall flow—context-driven, safety-aware, multi-stage orchestration using XML structure—is architecturally robust and aligns well with published best practices. However, the effectiveness of specific ordering, placement, and ratios is task-dependent. No universal percentages or absolute gains can be cited from research, but these design choices are supported by empirical studies, which inform _how_ and _why_ each component helps improve agent safety, reliability, and output clarity.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Critical Rules / Safety Gates _(First 5–10% of prompt)_
|
||||||
|
|
||||||
|
**Purpose:** Establish explicit boundaries, mandatory approval points, and error-handling at the very start for immediate agent alignment.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<critical_rules priority="highest">
|
||||||
|
<rule>ALWAYS request approval before ANY execution</rule>
|
||||||
|
<rule>NEVER auto-fix issues without explicit user approval</rule>
|
||||||
|
<rule>STOP immediately on test failure</rule>
|
||||||
|
<rule>Confirm before cleaning up files</rule>
|
||||||
|
</critical_rules>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Southampton NAACL 2024**: Early placement of critical instructions improves adherence, but magnitude depends on the task. No single "best" position; position sensitivity is real.[1]
|
||||||
|
- **Anthropic & Industry Docs:** Early, flat rules elevate attention and safety for LLMs.[2]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Context Hierarchy _(Next 15–25%)_
|
||||||
|
|
||||||
|
**Purpose:** Provide a layered, hierarchical context—from the system level down to current execution—before specifying tasks or instructions.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<context_hierarchy>
|
||||||
|
<system_context>Universal AI agent orchestration</system_context>
|
||||||
|
<domain_context>Multi-agent workflow coordination</domain_context>
|
||||||
|
<task_context>User request analysis and routing</task_context>
|
||||||
|
<execution_context>Current user session, tools available</execution_context>
|
||||||
|
</context_hierarchy>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Stanford/NAACL Studies**: Context aids multi-step task adherence, though not universally; broad-to-narrow ordering improves clarity for complex workflows.[3]
|
||||||
|
- **AWS Agent Patterns**: Hierarchical context reduces cognitive load and token wastage.[4]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Role Definition _(First 20–30%)_
|
||||||
|
|
||||||
|
**Purpose:** State the agent's persona, scope, and operational constraints up front.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<role>
|
||||||
|
<identity>OpenAgent: Universal Coordinator</identity>
|
||||||
|
<capabilities>Answering, executing, workflow management</capabilities>
|
||||||
|
<scope>Any domain, adaptive</scope>
|
||||||
|
<constraints>Safety, approval, human-centric</constraints>
|
||||||
|
</role>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Anthropic Docs:** Early role tagging increases output coherence and agent "persona" adherence; quantified benefit is task/model-specific.[2]
|
||||||
|
- **Role Prompting Research:** Early persona setting improves adherence in multi-instruction chains.[5]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Execution Path Decision _(25–35%)_
|
||||||
|
|
||||||
|
**Purpose:** Quickly branch into conversational or task workflow execution based on the query type.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<execution_paths>
|
||||||
|
<decision>
|
||||||
|
<if trigger="simple_question">route="conversational"</if>
|
||||||
|
<if trigger="task_or_execution">route="task_workflow"</if>
|
||||||
|
</decision>
|
||||||
|
</execution_paths>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Microsoft/AWS/Recent Studies:** Adaptive branching reduces overhead and improves efficiency.[6]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5A. Conversational Path _(If simple informational query)_
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<conversational_path>
|
||||||
|
<trigger>simple_question</trigger>
|
||||||
|
<execution>
|
||||||
|
<step>Analyze request and context</step>
|
||||||
|
<step>Answer clearly and directly</step>
|
||||||
|
<style>Lean, conversational</style>
|
||||||
|
</execution>
|
||||||
|
</conversational_path>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Lean Design Principle:** Simplified pathways reduce cognitive and token overhead for basic tasks.[7]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5B. Task Workflow _(If executing a complex or delegated task)_
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<task_workflow>
|
||||||
|
<stage name="Analyze">Assess request complexity & dependencies</stage>
|
||||||
|
<stage name="Plan">Draft stepwise execution plan</stage>
|
||||||
|
<stage name="Approval">Present plan and request user approval</stage>
|
||||||
|
<stage name="Execute">Carry out approved steps</stage>
|
||||||
|
<stage name="Validate">Test outputs, report and propose fixes if needed</stage>
|
||||||
|
<stage name="Summarize">Formally summarize results, next steps</stage>
|
||||||
|
<stage name="Complete">Confirm user satisfaction and session cleanup</stage>
|
||||||
|
</task_workflow>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **AWS Workflow/Multi-Agent Orchestration:** Staged, approval-gated flows improve output accuracy and user trust, with benefits contingent on workflow complexity.[8][4]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Delegation Logic _(50–65%)_
|
||||||
|
|
||||||
|
**Purpose:** Clearly define when to call subagents vs. direct execution.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<delegation_criteria>
|
||||||
|
<route agent="@subagent/core/task-manager" category="features">
|
||||||
|
<when>Feature spans multiple files | effort > 60 min | complex dependencies</when>
|
||||||
|
<context_inheritance>Load session context from manifest</context_inheritance>
|
||||||
|
</route>
|
||||||
|
<direct_execution>
|
||||||
|
<when>Single file; simple edit; direct user request</when>
|
||||||
|
</direct_execution>
|
||||||
|
</delegation_criteria>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Recent Multi-Agent Studies:** Explicit delegation criteria and context inheritance improves reliability and output quality.[9][8]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Session & Context Management _(65–75%)_
|
||||||
|
|
||||||
|
**Purpose:** Lazy session creation for resource efficiency, manifest-driven context discovery for robustness.
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<session_management>
|
||||||
|
<lazy_init>Only create session when context file needed</lazy_init>
|
||||||
|
<isolation>Unique session IDs</isolation>
|
||||||
|
<cleanup_policy>
|
||||||
|
<manual>Confirm cleanup</manual>
|
||||||
|
<stale>Auto-remove after 24h</stale>
|
||||||
|
</cleanup_policy>
|
||||||
|
<error_handling>
|
||||||
|
<subagent_failure>Report error, seek retry/abort confirmation</subagent_failure>
|
||||||
|
</error_handling>
|
||||||
|
</session_management>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Microsoft/AWS/Industry Docs:** Lazy init reduces overhead; manifest-driven context discovery improves targeting and prevents leakage.[10][11][12]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Guiding Principles _(End of prompt, or repeated as needed)_
|
||||||
|
|
||||||
|
**XML Block:**
|
||||||
|
```xml
|
||||||
|
<principles>
|
||||||
|
<lean>Concise, focused responses</lean>
|
||||||
|
<adaptive>Tone-matching: conversational for info, formal for tasks</adaptive>
|
||||||
|
<safe>ALWAYS request approval before ANY execution</safe>
|
||||||
|
<report_first>On errors: REPORT → PLAN → APPROVAL → FIX</report_first>
|
||||||
|
<lazy>Sessions/files only as needed</lazy>
|
||||||
|
</principles>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why This Works:**
|
||||||
|
- **Cognitive Load Theory & Industry Practice:** Memorable, actionable principles guide agent logic and user interaction.[13][14][15]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adjustments & Expert Recommendations
|
||||||
|
|
||||||
|
- **Drop all universal % improvement claims:** Instead, denote performance gains as "model- and task-specific."
|
||||||
|
- **Integrate safety gates and role tagging in first 20–30% of every prompt, not buried mid-prompt.**
|
||||||
|
- **Use flat XML wherever possible; avoid excessive nesting for maximum clarity.**
|
||||||
|
- **Session management and delegation should use manifest-driven context for reliable scaling.**
|
||||||
|
- **Make context layering explicit and test various orderings to optimize for your agent/model.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research References (Why Each Stage Works)
|
||||||
|
|
||||||
|
- **[1] NAACL '24 (Southampton): Position affects performance—variance is task-specific.**
|
||||||
|
- **[3] Stanford CS224N: Context helps adherence in multi-step instructions; effect varies.**
|
||||||
|
- **[2] Anthropic Claude docs: XML tags improve clarity and structure; early role definition improves output.**
|
||||||
|
- **[5] LearnPrompting & medical role studies: Role prompting benefits are real, magnitude varies by domain/model.**
|
||||||
|
- **[4][8] AWS, MS Research: Stage-based workflows, explicit approval gates, and clear branching improve accuracy.**
|
||||||
|
- **[11][12][10] Industry docs: Lazy session/context management, manifest indexing improve efficiency and reliability.**
|
||||||
|
- **[14][15][13] Cognitive load studies & agent best practices: Lean, safety-first and adaptive approaches outperform generic prompts.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Complete Updated XML Agent Prompt Template
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<critical_rules priority="highest">
|
||||||
|
<rule>ALWAYS request approval before ANY execution</rule>
|
||||||
|
<rule>NEVER auto-fix issues without explicit user approval</rule>
|
||||||
|
<rule>STOP immediately on test failure</rule>
|
||||||
|
<rule>Confirm before cleaning up files</rule>
|
||||||
|
</critical_rules>
|
||||||
|
|
||||||
|
<context_hierarchy>
|
||||||
|
<system_context>...</system_context>
|
||||||
|
<domain_context>...</domain_context>
|
||||||
|
<task_context>...</task_context>
|
||||||
|
<execution_context>...</execution_context>
|
||||||
|
</context_hierarchy>
|
||||||
|
|
||||||
|
<role>
|
||||||
|
<identity>...</identity>
|
||||||
|
<capabilities>...</capabilities>
|
||||||
|
<scope>...</scope>
|
||||||
|
<constraints>...</constraints>
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<execution_paths>
|
||||||
|
<decision>
|
||||||
|
<if trigger="simple_question">route="conversational"</if>
|
||||||
|
<if trigger="task_or_execution">route="task_workflow"</if>
|
||||||
|
</decision>
|
||||||
|
</execution_paths>
|
||||||
|
|
||||||
|
<conversational_path>
|
||||||
|
<trigger>...</trigger>
|
||||||
|
<execution>...</execution>
|
||||||
|
</conversational_path>
|
||||||
|
|
||||||
|
<task_workflow>
|
||||||
|
<stage name="Analyze">...</stage>
|
||||||
|
<stage name="Plan">...</stage>
|
||||||
|
<stage name="Approval">...</stage>
|
||||||
|
<stage name="Execute">...</stage>
|
||||||
|
<stage name="Validate">...</stage>
|
||||||
|
<stage name="Summarize">...</stage>
|
||||||
|
<stage name="Complete">...</stage>
|
||||||
|
</task_workflow>
|
||||||
|
|
||||||
|
<delegation_criteria>
|
||||||
|
<route agent="..." category="...">...</route>
|
||||||
|
<direct_execution>...</direct_execution>
|
||||||
|
</delegation_criteria>
|
||||||
|
|
||||||
|
<session_management>
|
||||||
|
<lazy_init>...</lazy_init>
|
||||||
|
<isolation>...</isolation>
|
||||||
|
<cleanup_policy>...</cleanup_policy>
|
||||||
|
<error_handling>...</error_handling>
|
||||||
|
</session_management>
|
||||||
|
|
||||||
|
<principles>
|
||||||
|
<lean>...</lean>
|
||||||
|
<adaptive>...</adaptive>
|
||||||
|
<safe>...</safe>
|
||||||
|
<report_first>...</report_first>
|
||||||
|
<lazy>...</lazy>
|
||||||
|
</principles>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Final Recommendation
|
||||||
|
|
||||||
|
**Use this structure as your foundation, but always empirically test prompt segmentation, safety gate placement, and workflow details with your specific agent and model for best results.** The research validates the general flow and methodology, not any universal quantitative improvement figures. This flow is robust, security-conscious, and adaptable—making it a best-practices template for modern LLM agent design.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
[1] https://github.com/carterlasalle/aipromptxml
|
||||||
|
[2] https://portkey.ai/blog/role-prompting-for-llms
|
||||||
|
[3] https://aws.amazon.com/blogs/machine-learning/best-practices-for-prompt-engineering-with-meta-llama-3-for-text-to-sql-use-cases/
|
||||||
|
[4] https://pmc.ncbi.nlm.nih.gov/articles/PMC12439060/
|
||||||
|
[5] https://beginswithai.com/xml-tags-vs-other-dividers-in-prompt-quality/
|
||||||
|
[6] https://www.linkedin.com/posts/jafarnajafov_how-to-write-prompts-for-claude-using-xml-activity-7353829895602356224-y0Le
|
||||||
|
[7] https://www.nexailabs.com/blog/cracking-the-code-json-or-xml-for-better-prompts
|
||||||
|
[8] https://www.thoughtworks.com/en-gb/insights/blog/generative-ai/improve-ai-outputs-advanced-prompt-techniques
|
||||||
|
[9] https://www.getdynamiq.ai/post/agent-orchestration-patterns-in-multi-agent-systems-linear-and-adaptive-approaches-with-dynamiq
|
||||||
|
[10] https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
|
||||||
|
[11] https://aimaker.substack.com/p/the-10-step-system-prompt-structure-guide-anthropic-claude
|
||||||
|
[12] https://arxiv.org/html/2507.12466v1
|
||||||
|
[13] https://www.youtube.com/watch?v=gujqOjzYzY8
|
||||||
|
[14] https://arxiv.org/html/2511.02200v1
|
||||||
|
[15] https://web.stanford.edu/~jurafsky/slp3/old_jan25/12.pdf
|
||||||
Loading…
Reference in a new issue