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 (Local harness only; prompt files are deprecated for Agent Host sessions, so prefer a Skill for new slash workflows)
• Always-on or file-scoped guidance -> Instruction
• Reusable workflow with bundled assets -> Skill
• Persona, tool restrictions, delegation, or handoffs -> Agent
• Deterministic enforcement -> Hook (Preview; events and config differ by harness)

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

Selection details: 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

Pattern Selection

Name the pattern explicitly when complexity rises, using the selector in references/workflow-patterns/overview.md. Every loop needs explicit stop conditions.

Design Workflow

1. Extract repeated behavior, tool preferences, and workflow shape from the conversation.
2. Choose primitive + scope (workspace / profile); ask only about ambiguities that change behavior.
3. Escalate only when split / compact / reference-ization cannot solve it, then pick a pattern.
4. Implement the smallest version and tighten the weakest parts.

Rule Placement

• 汎用的な workflow 設計原則は、この SKILL と references/ を SSOT にする。
• repo local の .instructions.md には workspace 固有の差分だけを残す。差分が無い generic instruction は merge back して削除候補にする。
• IR は原則 in-memory で扱う。validator、script、deterministic handoff が必要な場合だけ中間 file を materialize し、不要になったら片付ける。
• scheduler / service / config など決定論的な state mutation は、AI/UI loop ではなく direct script / API で現状確認 -> 最小変更 -> live read-back まで行う。LLM は scope と整合対象の判断に限定する。
• For model allocation reviews, use scheduled runtime bindings.

Escalation Rules

Prefer the lowest level (L0 prompt → L1 + instructions → L2 single agent → L3 multi-agent) that solves the problem cleanly. Quick signals to split:

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

Threshold details: references/splitting-criteria.md

レビューゲート

• プリミティブの選択が、可能であればエージェントよりシンプルである
• 配置が適切で、常時読み込まれるエントリファイルが薄いままである（エントリ境界のにおい: review-checklist.md）
• 新規追加は、削除 / 統合 / 分割 / 移動の選択肢を確認した後にのみ提案されている
• エージェントごとに単一責任が保たれている
• エラーを早期に検出して停止できる
• バリデータに注入されたフィクスチャだけでなく、実際の生産者から消費者へのデータフローを検証する。空の結果と意味のある状態遷移を網羅する。変化しない入力を繰り返すことは冪等性を証明するが、ライフサイクル全体を証明するものではない。
• 決定論的な部分はスクリプト / IR / フックにオフロードされ、状態変化は権威あるライブ状態を読み返すことで確認されている（LLM/UI のループではない）

完全なチェックリスト: references/review-checklist.md

リファレンスマップ

主要なリファレンス: プリミティブの決定、設計原則、ワークフローパターン、分割基準、レビューチェックリスト、コンテキスト管理。

スケジュールされたワークフローには、スケジュール実行時バインディングを使用してください。委譲されたエビデンスと追記専用の現在状態抽出については、オーケストレーター・ワーカーと IR アーキテクチャを参照してください。

オーケストレーターが委譲を約束しながら直接作業している場合は、委譲要件を明示的かつ検証可能にしてください（agent-guide.md）。ツールマッピングとエージェントスキャフォールド: agent-template.md。

完了基準

• プリミティブとスコープが意図的に選択されている
• ワークフローパターンが選択され、ユーザーと確認されている
• 新規または更新されたアセットに、該当する場合は明確なロール/ワークフロー/完了基準がある
• レビューゲートを通過している
• 推奨事項が、該当する場合は削除 / 統合 / 分割 / 移動 / 追加 / 維持に分類されている
• copilot-instructions.md または AGENTS.md がスコープに含まれる場合、常時有効な指示の境界と DRY / SSOT のリスクが明示的にレビューされている
• 必要に応じて、新しいエージェント / ワークフローのアセットが適切なカタログまたはドキュメントに登録されている
• AGENTS.md は、共有ガードレールまたはエントリの動作を変更する必要がある場合にのみ更新されている
• ワークフロー中に起動された長時間実行またはアドホックなターミナル/タスクが閉じられているか、残っているターミナルが理由とともに明示的に報告されている
• 設定の保存、コードのテスト、ライブ読み取りの検証、アクションの承認、定期サイクルの完了を区別する。完了または無人での準備完了を主張する前に権威ある状態を検証する。保留中のセーフガードと未観測のサイクルは、そのブロッカーと次回確認条件を保持したままとする。