Agentic Workflow Guide
Design, review, and improve agent workflows based on proven principles.
When to Use
| Action | Triggers |
|---|---|
| Create | New .agent.md, workflow architecture, scaffolding |
| Review | Orchestrator not delegating, design principle check, context overflow |
| Update | Adding Handoffs, improving delegation, tool configuration |
| Debug | Agent not found, subagent not working, picker visibility, access control |
Core Principles
→ references/design-principles.md
| Tier | Principles |
|---|---|
| Essential | SSOT, SRP, Simplicity First, Fail Fast, Feedback Loop |
| Quality | Transparency, Gate/Checkpoint, DRY, Observability |
| Scale | Human-in-the-Loop, Loose Coupling, Graceful Degradation |
See design-principles.md > Simplicity First for Anthropic's key recommendation.
Workflow Patterns
→ references/workflow-patterns/overview.md
| Pattern | When to Use |
|---|---|
| Prompt Chaining | Sequential tasks with validation |
| Routing | Processing varies by input type |
| Parallelization | Independent tasks run together |
| Orchestrator-Workers | Dynamic task decomposition |
| Evaluator-Optimizer | Repeat until quality criteria met |
Stop Conditions (MANDATORY): Define success/failure criteria and exit conditions for every loop.
Design Workflow
- Requirements - Goal, subtasks, dependencies, quality criteria
- Pattern Selection - [!] Ask user to confirm pattern before proceeding
- Design Diagram - Visualize with Mermaid
- Principle Check - Validate against review checklist
- Implement & Iterate - Build small → verify → improve
When to Escalate
→ references/splitting-criteria.md
| Level | Configuration | Escalation Triggers |
|---|---|---|
| L0 | Single Prompt | Retry 3+, unstable output |
| L1 | Prompt + Instructions | Steps > 5, "missed/overlooked" errors |
| L2 | Single Agent | Multiple responsibilities, context > 70% |
| L3 | Multi-Agent | Independent subtasks needed |
Quick Check: Prompt > 50 lines? Steps > 5? SRP violation? Context > 70%? → Consider splitting.
Review Checklist
→ references/review-checklist.md
- Single responsibility per agent? (SRP)
- Errors detected immediately? (Fail Fast)
- Small iterative steps? (Iterative)
- Results verifiable at each step? (Feedback Loop)
Key References
| Topic | Reference |
|---|---|
| Prompt Template | references/prompt-template.md |
| agent | references/agent-guide.md |
| Agent Template | references/agent-template.md |
| Agent Placement | references/vscode-agent-placement.md |
| Context Management | references/context-engineering.md |
| Handoffs | references/handoffs-guide.md |
| Scaffold Tool | references/scaffold-usage.md |
| Deep Agent | references/deep-agent-patterns.md |
| Agent Evaluation | references/agent-evaluation.md |
agent Quick Fix
Problem: Orchestrator says "I'll delegate" but does work directly.
Solution: Use MUST/MANDATORY language. See agent-guide.md.
## MANDATORY: Sub-agent Delegation
You MUST use agent for each file. Do NOT read files directly.
Tools Reference
→ references/agent-template.md
| Purpose | VS Code Copilot | Claude Code |
|---|---|---|
| Shell | execute/runInTerminal | Bash |
| Read | read/readFile | Read |
| Edit | edit/editFiles | Write |
| Subagent | agent | Task |
| Web fetch | web/fetch | (MCP) |
External References
Official Documentation
- Chat in IDE - GitHub Docs
- Custom Agents - VS Code Docs
- Custom Agents - GitHub Docs
- Custom Agents Configuration - GitHub Docs
Design Principles
- Building Effective Agents - Anthropic
- Effective Context Engineering - Anthropic
- Writing Tools for Agents - Anthropic
- Context windows - Anthropic
Instructions & Context
Community Resources
- agent (旧 runSubagent) 検証記事 - Zenn
- subagent-driven-development - obra/superpowers
- awesome-copilot agents - GitHub
Prompt Engineering
- https://platform.openai.com/docs/guides/prompt-engineering
- https://code.claude.com/docs/en/best-practices
- https://www.promptingguide.ai/
- https://www.ibm.com/think/prompt-engineering
Done Criteria
- Workflow pattern selected and confirmed with user
-
.agent.mdfile created with clear Role/Workflow/Done Criteria - Design principles checklist passed
- Agent registered in AGENTS.md (if applicable)