/agentic-workflow-guide

Design Principles

A collection of principles for designing agent workflows.

Table of Contents

• Tier 1: Core Principles - SSOT, SRP, Simplicity First, Fail Fast, Iterative, Feedback Loop
• Tier 2: Quality Principles - Transparency, Gate/Checkpoint, DRY, ISP, Idempotency, Observability, Reasoning
• IR Architecture - Two-stage pattern (reference)
• Tier 3: Scale Principles - Human-in-the-Loop, KISS, Loose Coupling, Graceful Degradation
• ACI Design - Tool design guidelines
• File Organization - Instructions organization, naming conventions

Tier 1: Core Principles (Essential)

1. SSOT (Single Source of Truth)

Manage information in one place

Multi-Agent Propagation Rule:

In Orchestrator-Workers patterns, writing a rule only in the central document (e.g., AGENTS.md) is not enough. Worker agents may not read or follow central rules unless they are explicitly referenced or duplicated in each .agent.md.

Lesson: When adding shared rules to a central SSOT, always propagate to worker definitions simultaneously. Update checklist: central doc + each .agent.md + scripts + instructions.

2. SRP (Single Responsibility Principle)

1 Agent = 1 Responsibility

3. Simplicity First

Start with the simplest solution

Anthropic's Recommendation:

"Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short."

4. Fail Fast

Detect and fix errors early

Contract Binding Liveness:

Paths, schema fields, CLI flags, IDs, and state keys referenced by policies, orchestrators, validators, and tests are executable contracts. A rename or deletion is incomplete until every live binding is updated.

• Before deleting or renaming an artifact, search policy/config, runtime code, tests, and generated-current-state definitions for references.
• Add a deterministic liveness check at the workflow entry or CI boundary; tests alone are insufficient if operators may not run them before production.
• Compare canonical path spelling against the source of truth. Git path case remains significant even on case-insensitive filesystems and can turn history/readback into a silent not found.
• Structural faults such as unmapped inputs, missing artifacts, and case mismatches must fail before freshness or scheduling filters. Ordinary pending work must remain allowed.

5. Iterative Refinement

Build small, improve repeatedly

Related Pattern: Evaluator-Optimizer

6. Feedback Loop

Verify results at each step → adjust

Anthropic's Recommendation:

"During execution, it's crucial for the agents to gain 'ground truth' from the environment at each step to assess its progress."

Tier 2: Quality Principles (Recommended)

7. Transparency

Show plans and progress explicitly

Anthropic's Recommendation:

"Prioritize transparency by explicitly showing the agent's planning steps."

8. Gate/Checkpoint

Validation gates at each step

9. DRY (Don't Repeat Yourself)

Eliminate duplication, promote reuse

10. ISP (Interface Segregation Principle)

Minimal context only

11. Idempotency

Safe to retry

Queue Hygiene for Issue/PR Automation:

For workflows that create or resume work through Issues, labels, and PRs, retry safety depends on treating those queue artifacts as workflow state.

• Before creating new work, check whether an equivalent Issue or PR is already open.
• If a blocker label such as needs-human-review can become stale, only auto-clear it under explicit safe conditions, for example when no open PR remains and the rerun was manual or triggered by a fresh failure.
• If the latest evaluation says there is no actionable work, auto-close stale request Issues so the queue does not look blocked forever.

12. Observability

Record decisions and make progress visible

Idle State Visibility:

If 0 new items is a valid and healthy result, surface that state separately from latest published artifact date. Otherwise, users may misread a normal no-op run as a stale deployment or failed automation.

Elapsed Time Tracking:

For multi-step workflows, record start/end timestamps to measure performance:

// manifest/status.json
{
  "startedAt": "2026-05-08T04:37:00+09:00",
  "completedAt": "2026-05-08T04:50:00+09:00",
  "elapsedMinutes": 13.0
}

This enables:

• Performance regression detection across runs
• User-facing elapsed time reports
• Bottleneck identification (which step takes longest)

Decision Log Example:

| Time  | Decision                      | Rationale                  |
| ----- | ----------------------------- | -------------------------- |
| 10:00 | Delegate to @impl for task-01 | Code change required       |
| 10:05 | Skip task-02                  | File already up-to-date    |
| 10:10 | Escalate to human             | Requires production access |

13. Reasoning Before Conclusions

Show your thinking, then provide the answer

Why This Matters:

LLMs perform better when they can "think out loud" before committing to an answer. This principle improves accuracy and makes agent decisions auditable.

Prompt Design:

✅ Encourage reasoning:

Before selecting a workflow pattern:

1. Analyze the task characteristics
2. List applicable patterns with pros/cons
3. Recommend the best fit based on your analysis

❌ Discourage reasoning:

Select the best workflow pattern for this task.

Implementation Techniques:

Example Output:

## Analysis

- Task requires processing 10 files
- Files are independent
- No interdependencies detected

## Options Considered

1. Prompt Chaining: ❌ Sequential would be slow
2. Parallelization: ✅ Files are independent
3. Orchestrator-Workers: ⚠️ Overkill for fixed task count

## Decision

Use Parallelization pattern (Pattern 3)

## Implementation Plan

[Detailed steps...]

Benefits:

References:

• Chain-of-Thought Prompting - Google Research
• vscode-ai-toolkit Prompt Generation Best Practices

Intermediate Representation (IR) Architecture

→ workflow-patterns/ir-architecture.md (SSOT)

For complex workflows, use a two-stage architecture with an intermediate representation. Core principle: Same IR → Same Output. No creativity in transformation phase.

Tier 3: Scale Principles (Advanced)

14. Human-in-the-Loop

Human confirmation at critical points

15. KISS (Keep It Simple, Stupid)

Keep it simple

16. Loose Coupling

Loose coupling between agents

17. Graceful Degradation

Continue operation despite partial failures

ACI Design (Agent-Computer Interface)

Anthropic's Recommendation:

"Think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI)."

Core Principles

Tool Design Guidelines

1. Clear Description - Clarify tool purpose and usage
2. Edge Cases - Document boundary conditions
3. Input Format - Specify expected input format
4. Error Handling - Define behavior on failure
5. Testing - Actually use it and iterate
6. Example Usage - Include usage examples in description
7. Poka-yoke - Design to prevent mistakes (e.g., use absolute paths)
8. Display Surface Fit - Match output structure to where users will read it, such as cards/fields for chat embeds instead of dense text

Format Selection

Choose formats that minimize cognitive load for LLMs:

Anthropic's Tool Format Recommendations

"Give the model enough tokens to 'think' before it writes itself into a corner. Keep the format close to what the model has seen naturally occurring in text on the internet."

Do:

• Use formats the model has seen in training (Markdown, code, XML)
• Allow space for reasoning before final output
• Use descriptive parameter names

Don't:

• Require accurate counting (e.g., line numbers in diffs)
• Force heavy escaping (e.g., code inside JSON strings)
• Create ambiguous decision points between similar tools

Tool Set Design

Testing Checklist

- [ ] Can a junior developer understand how to use this tool from its description?
- [ ] Does running multiple test inputs produce expected outputs?
- [ ] Are error messages actionable?
- [ ] Is the output format consistent and parseable?
- [ ] Has the output been checked in the final reading surface or a faithful dry-run payload?
- [ ] Does the tool handle edge cases gracefully?

File Organization Principles

Instructions Organization

Group related instructions by domain/genre

Why This Matters:

• Easier navigation for both humans and agents
• Related instructions stay together
• Reduces cognitive load when searching
• Enables folder-level .gitignore or permissions

Recommended Structure:

.github/instructions/
├── azure/
│   ├── bicep-style.instructions.md
│   ├── naming-conventions.instructions.md
│   └── resource-tagging.instructions.md
├── git/
│   ├── commit-message.instructions.md
│   ├── branch-naming.instructions.md
│   └── pr-contribution.instructions.md
├── code/
│   ├── python-style.instructions.md
│   ├── typescript-style.instructions.md
│   └── testing-guidelines.instructions.md
├── skills/
│   └── skill-creator.instructions.md
└── global.instructions.md  # Cross-cutting rules

Benefits:

Naming Conventions

Use consistent, descriptive file names

File Naming Rules

Suffix Conventions

Folder Naming Rules

Agent/Prompt File Naming

For .agent.md and .prompt.md files, use action-oriented names:

✅ Good:
- code-reviewer.agent.md
- pr-summarizer.agent.md
- test-generator.prompt.md
- refactor-suggestions.prompt.md

❌ Bad:
- agent1.agent.md
- my-agent.agent.md
- prompt.prompt.md
- test.prompt.md

Versioning in Names (When Needed)

If maintaining multiple versions:

feature-flags-v1.instructions.md
feature-flags-v2.instructions.md

Or use folders:

feature-flags/
├── v1/
│   └── implementation.instructions.md
└── v2/
    └── implementation.instructions.md

References

• Building Effective Agents - Anthropic
• Writing tools for AI agents - Anthropic
• SOLID Principles
• 12-Factor App

SSOT Implementation Patterns

SSOT Reference Pattern

When referencing shared definitions across multiple files, use this standard format:

Format:

> **SSOT**: See [file](path) section "Section Name" for details

The referenced heading MUST exist in the target file, and the target MUST hold the definition itself. A pointer to a section that only forwards elsewhere leaves the rule undefined while every checker still reports the link as valid.

Anti-pattern (Before):

• Same logic duplicated in 3+ files (e.g., holiday check, validation rules)
• Requires updating all files when logic changes
• Inconsistencies emerge over time

Best Practice (After):

• Define authoritative rule in one file (e.g., instructions.md)
• Other files reference SSOT with link only
• Changes propagate automatically

Example:

### Step 0-2: Holiday Check

> **SSOT**: See [copilot-instructions.md](../copilot-instructions.md) section "Holiday Rules"

1. Check holiday calendar
2. If holiday: skip and notify

View vs Master Separation

For task/project management workflows, separate display views from data masters:

⚠️ Anti-pattern: Putting task tables in both View and Master creates dual maintenance burden.

Correct Structure:

DASHBOARD.md (View)
├── Today's Focus: TOP 3 actions (links only)
├── This Week: Schedule view
└── Recent Completions: Last 5 items

Tasks/active.md (Master - SSOT)
├── Full task details
├── All metadata
└── History

Activity Log Collection Strategy

When collecting activity logs from integrated tools (M365, Slack, etc.), use multiple query types for comprehensive coverage:

⚠️ Single query anti-pattern: Using only one query type causes detection gaps.

Example queries:

1. What did I post in channels today? → Own contributions
2. What messages mentioned me today? → Inbound requests
3. What files did I share today? → Artifacts created