Defining Agentic Assistant Workflows and Acceptance Criteria

Welcome to the first lesson of your journey into agentic software engineering. Your goal is to move beyond being a user of AI tools and become a senior-level engineer who can architect and build reliable agentic systems. This course is designed to get you there by building a practical project: an agentic engineering assistant.

In this lesson, we'll tackle the very first and most critical step in building any piece of software, especially an AI-powered one: we'll define its purpose. We will specify the primary user journey and the acceptance criteria for our assistant. This foundation is essential for guiding the AI, preventing it from making poor assumptions, and ensuring it builds exactly what you intend. Think of it as creating the blueprint before the first line of code is written.

The Problem with Vague Instructions

You've likely experienced this yourself when using tools like GitHub Copilot or Claude. If you give a vague prompt like "add authentication," the agent has to make numerous guesses: What kind of authentication? JWT? OAuth? What's the token expiry? Where are users stored? This often leads to code that is technically functional but architecturally wrong, insecure, or simply not what you wanted.

As a senior engineer, your role shifts from just writing code to ensuring the right code gets written. With AI agents, this means providing crystal-clear specifications. This practice is often called Spec-Driven Development.

To see why this is so important, let's watch a short segment from the video "How I Code With AI Agents."

The key takeaway is that an AI spec is a contract that guides the agent's behavior, reducing ambiguity and giving you, the engineer, control over the outcome.

Our Project: An Agentic Engineering Assistant

Throughout this course, we will be building an agentic assistant whose job is to help a developer analyze a development task. This process fits into a larger agentic software engineering workflow.

Our focus in this lesson is squarely on that first phase. Before we can have an agent generate requirements, architecture, or code, we must first define for ourselves what we want it to do.

Defining the Primary User Journey

A user journey describes the path a user takes to accomplish a goal. For our project, the user is a software developer, and their goal is to understand the scope and implications of a task before they start coding.

Let's outline the primary user journey:

1. Task Submission: The developer provides the agent with a description of a development task (e.g., the text from a Jira ticket, a GitHub issue, or a simple text prompt).
2. Analysis: The agent processes the task description to identify key components.
3. Report Generation: The agent produces a structured analysis report.
4. Review: The developer reviews the report to quickly understand the task's requirements, scope, and potential challenges.

This approach is declarative. We are describing the desired outcome (a structured analysis report) rather than the imperative steps the agent must take. This gives the agent flexibility in how it achieves the goal, while ensuring the output meets our needs.

The article "How to write a good spec for AI agents" explains this principle well.

We've already answered the first two questions. The developer (user) needs to quickly understand a development task. Now, let's define what success looks like by creating acceptance criteria.

From Journey to Acceptance Criteria

Acceptance Criteria (AC) are the testable conditions that a feature must meet to be accepted by a user, customer, or in our case, the system's designer (you). Good ACs are not vague; they are specific and measurable. They transform a user journey into a set of verifiable rules.

For an AI agent, ACs are not just for testing—they are crucial guardrails that constrain the agent's behavior.

Let's look at a concrete example of how vague goals can be transformed into a structured, agent-ready specification.

Inspired by this structure, let's draft the initial specification for our agentic assistant.

Specification: Task Analysis Agent

• User Story: As a developer, I want to provide a task description to an AI assistant, so that I can receive a structured analysis that helps me understand the implementation requirements and potential risks.

• Context: Developers often receive tasks that are poorly defined or lack technical detail. Manually analyzing each task to determine which files to touch, what tests to write, and what risks to consider is time-consuming. This agent automates that initial analysis.

• Output Specification: When given a task description, the agent must generate a markdown-formatted report containing the following sections:

  1. Task Summary: A one-paragraph summary of the goal.
  2. Affected Files: A list of existing files in the codebase that are likely to require modification.
  3. Implementation Plan: A high-level, step-by-step plan to complete the task.
  4. Tests to Write: A list of suggested unit, integration, or end-to-end tests to verify the feature.
  5. Risks & Ambiguities: A list of potential risks (e.g., "modifying a core authentication file") or questions for clarification (e.g., "The task mentions 'users' but doesn't specify user roles. Are there different permission levels?").

• Acceptance Criteria (Success Criteria):

  1. The generated report must contain all five sections listed in the Output Specification.
  2. The Affected Files list must correctly identify at least 80% of the core files that a senior developer would modify for a given task (this will be tested against a benchmark set of tasks).
  3. The analysis process must not involve writing or committing code to the repository. The agent's role is analysis only.
  4. The entire analysis and report generation must complete in under 30 seconds for a typical task description (< 500 words).

This format provides a clear, unambiguous definition of done. It tells the agent precisely what a successful outcome looks like, including both the structure of the output and measurable quality targets (80% accuracy, <30s latency).

Conclusion

In this lesson, we've laid the critical groundwork for our agentic engineering assistant. We've moved from a vague idea to a concrete specification by defining the primary user journey and a set of clear, testable acceptance criteria. This spec-driven approach is fundamental to building reliable and predictable AI systems, putting you in the driver's seat as the senior engineer.

Key Takeaways:

• Spec-Driven Development: Providing agents with clear, detailed specifications is crucial to prevent them from making incorrect assumptions. An AI spec is an execution document.
• User Journey: Start by defining the user, their goal, and the high-level steps they take.
• Declarative Outcomes: Focus on what you want the agent to produce, not the low-level how.
• Acceptance Criteria: Use specific, measurable, and testable criteria to define success and create guardrails for the agent.

In our next lesson, we will expand on this foundation by defining measurable latency and availability objectives together with cost, privacy, retention, and auditability constraints. These non-functional requirements are essential for turning a prototype into a production-ready system.