agentic-workflow-guide

name	agentic-workflow-guide
description	Create, review, and update Prompt and agents and workflows. Covers 5 workflow patterns, agent delegation, Handoffs, Context Engineering. Use for any .agent.md file work or multi-agent system design. Triggers on 'agent workflow', 'create agent', 'ワークフロー設計'.
license	CC BY-NC-SA 4.0
metadata	{"author":"yamapan (https://github.com/aktsmm)"}

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

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

1. Requirements - Goal, subtasks, dependencies, quality criteria
2. Pattern Selection - [!] Ask user to confirm pattern before proceeding
3. Design Diagram - Visualize with Mermaid
4. Principle Check - Validate against review checklist
5. 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
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	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

• Adding repository custom instructions - GitHub Docs

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.md file created with clear Role/Workflow/Done Criteria
• Design principles checklist passed
• Agent registered in AGENTS.md (if applicable)