Best Practices for Workflow Template Design

A workflow template is the blueprint that tells an AI agent what to do, how to do it, and what constraints to follow. In FlowKoi, templates consist of a CLAUDE.md file (persistent context and rules), a workflow.md file (the specific task instructions), optional tools, and environment configuration. The quality of your template directly determines the quality of your results.

The Role of Each File

CLAUDE.md is the system-level context. It persists across runs and defines the agent’s “personality” for this workflow: what tools are available, what conventions to follow, what to avoid, and how to handle common situations. Think of it as the employee handbook.

workflow.md is the task-level prompt. It describes what to do in this specific run. For one-off workflows, this is the main instruction set. For scheduled workflows, it should be written to work without modification on every run.

Tools (in the tools/ directory) are scripts and utilities the AI can invoke. These extend the agent’s capabilities beyond what Claude CLI provides out of the box.

Writing Effective CLAUDE.md Files

Keep these principles in mind:

Be specific about output format. Instead of “generate a report,” specify “generate a Markdown file named report.md with an H1 title, a summary section, and a detailed findings section with bullet points.” The more precise your format specification, the more consistent your results.

Define boundaries. Tell the agent what it should not do. “Do not modify any files outside the output/ directory.” “Do not make network requests to domains other than api.example.com.” Constraints are just as important as instructions.

Include examples. If you want output in a specific format, include a short example in the CLAUDE.md file. AI agents follow examples more reliably than abstract descriptions.

Document available tools. List each tool in the tools/ directory with a one-line description of what it does and how to invoke it. The agent will discover tools on its own, but explicit documentation reduces errors.

Writing Effective workflow.md Files

Start with the goal. The first line should clearly state what the workflow is supposed to accomplish. “Generate a weekly summary of all pull requests merged into the main branch.”

Break complex tasks into steps. Numbered steps give the agent a clear execution path. Each step should be a discrete, verifiable action.

Specify data sources. If the workflow needs to read from an API, database, or file, provide the exact endpoint, credentials location (use environment variables), and expected data format.

Define success criteria. What does a successful run look like? “The workflow is complete when output/report.md exists and contains at least one finding.” This helps the agent know when to stop.

Common Mistakes

Over-prompting. Giving the agent a 2,000-word workflow description with dozens of edge cases often produces worse results than a focused 200-word version. Start simple and add detail only where the agent consistently gets things wrong.

Assuming context. The agent starts fresh every run. Do not assume it remembers anything from previous executions. If it needs context from a prior run, store that context in a file and reference it explicitly.

Ignoring environment variables. Hardcoding API keys, URLs, or configuration values in templates makes them fragile and insecure. Use .env files and reference variables by name in your instructions.

Iterating on Templates

The best templates are built iteratively. Run the workflow, review the output, identify where the agent deviated from your expectations, and refine the template. After three or four iterations, most templates stabilize and produce consistently good results.

Treat your templates like code: version them, review changes, and keep them as simple as possible while still achieving the desired outcome.