agentic-workflow-guide

# Agentic Workflow Guide

Design, review, and improve agent workflows based on proven principles.

この SKILL の基本姿勢は、**agent を増やすことではなく、必要最小の primitive で解くこと**。
context が膨らんだときも、まずは split / compact / reference 化を考え、いきなり multi-agent にしない。

## Primitive First

Do not start with multi-agent by default.

- Single focused slash task -> **Prompt**
- Always-on or file-scoped guidance -> **Instruction**
- Reusable workflow with bundled assets -> **Skill**
- Persona, tool restrictions, delegation, or handoffs -> **Agent**
- Deterministic enforcement -> **Hook**

If the ask does not require an **Agent**, stop and use the simpler primitive.

Selection details: [references/customization-decision.md](references/customization-decision.md)

## When to Use

| Action     | Triggers                                                                      |
| ---------- | ----------------------------------------------------------------------------- |
| **Create** | New `.agent.md`, `.instructions.md`, `.prompt.md`, `AGENTS.md`, or workflow architecture |
| **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      |
| **Decide** | Determining whether multi-agent is justified or a simpler primitive is enough |

## Core Principles

- **Simplicity First**: より単純な primitive で解けるなら agent 化しない
- **SSOT / SRP**: 情報源と責務の分割を守る
- **Fail Fast**: エラーは早く止める
- **Feedback Loop**: 各段で検証できるようにする
- **Context Discipline**: context が膨らんだら compact / split / retrieve を検討する

Principle details: [references/design-principles.md](references/design-principles.md)

## Pattern Selection

- **Prompt Chaining**: 順序のある段階処理
- **Routing**: 入力タイプで分岐する処理
- **Parallelization**: 独立タスクを並列で進める処理
- **Orchestrator-Workers**: 動的に subtasks を分解する処理
- **Evaluator-Optimizer**: 品質基準を満たすまで反復する処理

Every loop needs explicit stop conditions.

Pattern details: [references/workflow-patterns/overview.md](references/workflow-patterns/overview.md)

## Design Workflow

1. **Extract from conversation**
   Repeated behavior, tool preferences, workflow shape, and obvious specialization を先に拾う。
2. **Choose primitive + scope**
   Prompt / instruction / skill / agent / hook と workspace / profile を決める。
3. **Clarify only the gaps**
   挙動を変える曖昧さだけ聞く。
4. **Check escalation**
   agent や multi-agent が本当に必要か確認する。
5. **Choose pattern**
   complexity が上がるなら pattern を明示して設計する。
6. **Review before expanding**
   split / compact / reference 化で済まないかを見る。
7. **Implement and iterate**
   最初から完成形を狙わず、弱い箇所を見つけて詰める。

## Rule Placement

- 汎用的な workflow 設計原則は、この SKILL と `references/` を SSOT にする。
- repo local の `.instructions.md` には workspace 固有の差分だけを残す。差分が無い generic instruction は merge back して削除候補にする。
- IR は原則 in-memory で扱う。validator、script、deterministic handoff が必要な場合だけ中間 file を materialize し、不要になったら片付ける。

## Escalation Rules

- **L0**: Single Prompt
- **L1**: Prompt + Instructions
- **L2**: Single Agent
- **L3**: Multi-Agent

Prefer the lowest level that solves the problem cleanly.

Quick signals:

- Prompt > 50 lines
- Steps > 5
- "missed" / "overlooked" errorsが続く
- Multiple responsibilities in one agent
- Context > 70%

Threshold details: [references/splitting-criteria.md](references/splitting-criteria.md)

## Entry Boundary Smells

### Instruction Elevation Smell

always-loaded entry において、強い命令語が直下の catalog、reference list、workflow map、rule inventory を会話の優先レイヤーへ昇格させる状態。

### Always-Loaded Entry Budget

always-loaded entry は会話境界と最小 guardrail のみを持つ。catalog、詳細手順、広い参照一覧は docs、README、task-specific assets へ退避する。

### Runtime Boundary Rule

Review assets improve design quality and detect structural problems. Default conversational behavior is controlled by always-loaded entries.

### Casual Input Safety Check

Lightweight inputs such as greetings, short Q&A, and numeric-only replies should not be force-routed into task intake unless the task context is explicit.

## Review Gates

- [ ] Primitive choice is simpler than agent if possible
- [ ] Placement is appropriate and always-loaded entry files stay thin
- [ ] New additions are proposed only after delete / merge / split / move options are checked
- [ ] Repo-local design instructions keep workspace-specific delta only; generic guidance lives in this skill or its references
- [ ] Frontmatter review validates file-type-specific supported and unsupported properties, not just missing fields
- [ ] Prompt-level `tools:` is present only when a slash prompt intentionally narrows capabilities; otherwise prompts inherit the selected agent tools
- [ ] `copilot-instructions.md` and `AGENTS.md` keep distinct always-on roles and do not duplicate intake / routing / catalog content
- [ ] always-loaded entries do not combine strong directive wording with catalogs or reference inventories
- [ ] findings distinguish runtime-affected entry issues from review-only asset issues
- [ ] Single responsibility per agent is preserved
- [ ] Errors can be detected and stopped early
- [ ] Results are verifiable at each step
- [ ] lightweight conversational inputs are not unnecessarily forced into task intake
- [ ] Context can be compacted or split before adding more orchestration
- [ ] catalogs and workflow maps are separated from always-loaded entry files
- [ ] Deterministic parts are offloaded to scripts / IR / hooks (not LLM loops)
- [ ] File-based IR is introduced only when deterministic handoff requires it, and cleanup is defined

Full checklist: [references/review-checklist.md](references/review-checklist.md)

## Reference Map

| Topic                  | Reference                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Primitive decision     | [references/customization-decision.md](references/customization-decision.md)                                                               |
| Design principles      | [references/design-principles.md](references/design-principles.md)                                                                         |
| Workflow patterns      | [references/workflow-patterns/overview.md](references/workflow-patterns/overview.md)                                                       |
| Splitting criteria     | [references/splitting-criteria.md](references/splitting-criteria.md)                                                                       |
| Review checklist       | [references/review-checklist.md](references/review-checklist.md)                                                                           |
| Prompt template        | [references/prompt-template.md](references/prompt-template.md)                                                                             |
| Context management     | [references/context-engineering.md](references/context-engineering.md)                                                                     |
| Agent guide / template | [references/agent-guide.md](references/agent-guide.md), [references/agent-template.md](references/agent-template.md)                       |
| Handoffs / placement   | [references/handoffs-guide.md](references/handoffs-guide.md), [references/vscode-agent-placement.md](references/vscode-agent-placement.md) |
| Hooks                  | [references/hooks-guide.md](references/hooks-guide.md)                                                                                     |
| Evaluation             | [references/agent-evaluation.md](references/agent-evaluation.md)                                                                           |
| External links         | [references/external-resources.md](references/external-resources.md)                                                                       |

## External References

Keep a small curated set here for first-hop reading. The longer link list stays in [references/external-resources.md](references/external-resources.md).

- GitHub Docs: [Chat in IDE](https://docs.github.com/en/copilot/how-tos/chat-with-copilot/chat-in-ide)
- VS Code Docs: [Custom Agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
- GitHub Docs: [Create custom agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
- Anthropic: [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
- Anthropic: [Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
- Anthropic: [Writing Tools for Agents](https://www.anthropic.com/engineering/writing-tools-for-agents)

## agent Quick Fix

**Problem:** Orchestrator says "I'll delegate" but does work directly.

**Solution:** Use MUST/MANDATORY language. See [agent-guide.md](references/agent-guide.md).

```yaml
## MANDATORY: Sub-agent Delegation
You MUST use agent for each file. Do NOT read files directly.
```

## Tools Reference

→ **[references/agent-template.md](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)       |

## Done Criteria

- [ ] Primitive and scope selected intentionally
- [ ] Workflow pattern selected and confirmed with user
- [ ] New or updated assets have clear Role/Workflow/Done Criteria where applicable
- [ ] Design principles checklist passed
- [ ] Recommendations are classified as delete / merge / split / move / add / keep where applicable
- [ ] Always-on instruction boundaries and DRY / SSOT risks are explicitly reviewed when `copilot-instructions.md` or `AGENTS.md` are in scope
- [ ] New agent / workflow assets are registered in the appropriate catalog or docs when needed
- [ ] `AGENTS.md` is updated only when shared guardrails or entry behavior need to change
- [ ] Long-running or ad-hoc terminals/tasks started during the workflow are closed, or remaining terminals are explicitly reported with a reason