Working with AI in its default state is a manual loop: you prompt, get a result, tweak it, and repeat. The core problem is that this approach has no memory or system. A lesson learned in one prompt is forgotten by the next.
This inevitably ends in frustrating loops, where the AI goes beyond what is asked and gets stuck solving the wrong problem while we waste time and energy trying to prompt it back on track.
Breaking the Loop: Creating a Repeatable AI Process
We learned that the agent's effectiveness skyrocketed when we stopped treating it like a single-use tool and started building a system around it by:
- Enriching the context with clear documentation.
- Limiting its actions with explicit rules to prevent it from going off-course.
Initially, each developer solved this in their own way, creating custom prompts and conventions. It worked, but it didn't scale. The solution was to systematize this knowledge and turn it into shared workflows and rules using the Windsurf Editor.
The windsurf-devsuite Repo
Our Innovation Hub created a repository that functions as an additional workspace, providing a set of workflows and rules that standardize how we interact with the AI on development projects.
Workflows: The Process Steps
Building a workflow in Windsurf is like creating a smart recipe for your AI assistant. You're giving it the ingredients, the rules, and the step-by-step instructions separately so it can deliver a perfect result every time.
Location: .windsurf/workflows/ These are executed with slash commands and orchestrate the entire flow of a task:
- /0-task → Initializes the task and sets up tracking.
- /1-discovery → Analyzes the current state of the code.
- /2-design → Proposes design options and documents the chosen one.
- /3-implement → Incremental implementation with logs and validations.
- /4-clean → Refactoring and cleanup with approval.
- /5-test → Plans and executes tests.
- /6-document → Audits and generates technical and user documentation.
- /status → Shows progress and next steps.
Using Rules as AI Guardrails for Code Quality
Location: .windsurf/rules/
This is where you enforce quality and consistency. You create "rules" that act as non-negotiable guardrails for the AI's output.
global.md
Guidelines for architecture, TypeScript conventions, use of Tailwind + shadcn/ui, testing, performance, error handling, and the assistant's expected behavior (e.g., do not assume or invent libraries).
devsuite-workspace-paths.md
This file tells the AI "where" to work. It defines that process tracking and documentation are centralized in docs/development/current-task.md within the devsuite. This maintains order and traceability.
You can explore all the DevSuite guidelines and workflows directly on our GitHub repository here.
Benefits of Using Windsurf Workflows
Consistency → The same rules applied across all projects.
Standardization → Clear steps and documented outcomes in each workflow.
Traceability → All decisions recorded in a single location.
Productivity → Less friction; the assistant knows what to do at each stage.
Current Status and Next Steps
Today, we are in the middle of the adoption phase: each team at Kaizen is incorporating the workflow set into their daily routine while we gather feedback to improve it. The goal is for these workflows to evolve with use:
- Adjusting rules that prove to be too restrictive.
- Adding steps where they are needed.
- Refining the generated documentation to make it truly useful.
We want this to become a common and living foundation that empowers every dev, regardless of their seniority, and facilitates collaboration between teams.
In Summary
We went from "fighting with the AI to make it understand what we want" to having a structured and reliable process where the assistant works with focus, within a common framework, and without endless prompt loops.
With Windsurf + devsuite, AI has stopped being an isolated experiment and has become a real pillar of our daily operations.
.png)
